OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

Data Structures | Macros | Typedefs | Enumerations | Variables
pml.h File Reference

P2P Management Layer (PML) More...

`#include "ompi_config.h"`
`#include "opal/mca/mca.h"`
`#include "mpi.h"`

Go to the source code of this file.

## Data Structures
struct | mca_pml_base_component_2_0_0_t
| PML component version and interface functions. More...
struct | mca_pml_base_module_1_0_0_t
| PML instance. More...

## Macros
#define | OMPI_ANY_TAG MPI_ANY_TAG
#define | OMPI_ANY_SOURCE MPI_ANY_SOURCE
#define | OMPI_PROC_NULL MPI_PROC_NULL
#define | MCA_PML_BASE_VERSION_2_0_0
#define | MCA_PML_CALL(a) mca_pml.pml_ ## a

## Typedefs
typedef struct mca_pml_base_module_1_0_0_t *(* | mca_pml_base_component_init_fn_t )(int *priority, bool enable_progress_threads, bool enable_mpi_threads)
| MCA->PML Called by MCA framework to initialize the component. More...
typedef int(* | mca_pml_base_component_finalize_fn_t )(void)
typedef struct mca_pml_base_component_2_0_0_t | mca_pml_base_component_2_0_0_t
typedef mca_pml_base_component_2_0_0_t | mca_pml_base_component_t
typedef int(* | mca_pml_base_module_add_procs_fn_t )(struct ompi_proc_t **procs, size_t nprocs)
| MCA management functions. More...
typedef int(* | mca_pml_base_module_del_procs_fn_t )(struct ompi_proc_t **procs, size_t nprocs)
| Downcall from MPI/RTE layer when processes are terminated. More...
typedef int(* | mca_pml_base_module_enable_fn_t )(bool enable)
| Downcall from MCA layer to enable the PML/BTLs. More...
typedef int(* | mca_pml_base_module_progress_fn_t )(void)
| For non-threaded case, provides MCA the opportunity to progress outstanding requests on all btls. More...
typedef int(* | mca_pml_base_module_add_comm_fn_t )(struct ompi_communicator_t *comm)
| MPI Interface Functions. More...
typedef int(* | mca_pml_base_module_del_comm_fn_t )(struct ompi_communicator_t *comm)
| Downcall from MPI layer when a communicator is destroyed. More...
typedef int(* | mca_pml_base_module_irecv_init_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, struct ompi_request_t **request)
| Initialize a persistent receive request. More...
typedef int(* | mca_pml_base_module_irecv_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, struct ompi_request_t **request)
| Post a receive request. More...
typedef int(* | mca_pml_base_module_imrecv_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, struct ompi_message_t **message, struct ompi_request_t **request)
typedef int(* | mca_pml_base_module_recv_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, ompi_status_public_t *status)
| Post a receive and wait for completion. More...
typedef int(* | mca_pml_base_module_mrecv_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, struct ompi_message_t **message, ompi_status_public_t *status)
typedef int(* | mca_pml_base_module_isend_init_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm, struct ompi_request_t **request)
| Initialize a persistent send request. More...
typedef int(* | mca_pml_base_module_isend_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm, struct ompi_request_t **request)
| Post a send request. More...
typedef int(* | mca_pml_base_module_send_fn_t )(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm)
| Post a send request and wait for completion. More...
typedef int(* | mca_pml_base_module_start_fn_t )(size_t count, struct ompi_request_t **requests)
| Initiate one or more persistent requests. More...
typedef int(* | mca_pml_base_module_iprobe_fn_t )(int src, int tag, struct ompi_communicator_t *comm, int *matched, ompi_status_public_t *status)
| Probe to poll for pending recv. More...
typedef int(* | mca_pml_base_module_improbe_fn_t )(int src, int tag, struct ompi_communicator_t *comm, int *matched, struct ompi_message_t **message, ompi_status_public_t *status)
typedef int(* | mca_pml_base_module_probe_fn_t )(int src, int tag, struct ompi_communicator_t *comm, ompi_status_public_t *status)
| Blocking probe to wait for pending recv. More...
typedef int(* | mca_pml_base_module_mprobe_fn_t )(int src, int tag, struct ompi_communicator_t *comm, struct ompi_message_t **message, ompi_status_public_t *status)
typedef int(* | mca_pml_base_module_cancel_fn_t )(struct ompi_request_t *request)
| Cancel pending operation. More...
typedef int(* | mca_pml_base_module_cancelled_fn_t )(struct ompi_request_t *request, int *flag)
| Has a request been cancelled? More...
typedef int(* | mca_pml_base_module_free_fn_t )(struct ompi_request_t **request)
| Release resources held by a persistent mode request. More...
typedef int(* | mca_pml_base_module_null_fn_t )(struct ompi_request_t **request)
| A special NULL request handle. More...
typedef int(* | mca_pml_base_module_dump_fn_t )(struct ompi_communicator_t *comm, int verbose)
| Diagnostics function. More...
typedef int(* | mca_pml_base_module_ft_event_fn_t )(int status)
| Fault Tolerance Awareness function. More...
typedef struct mca_pml_base_module_1_0_0_t | mca_pml_base_module_1_0_0_t
typedef mca_pml_base_module_1_0_0_t | mca_pml_base_module_t

## Enumerations
enum | mca_pml_base_send_mode_t { MCA_PML_BASE_SEND_SYNCHRONOUS, MCA_PML_BASE_SEND_COMPLETE, MCA_PML_BASE_SEND_BUFFERED, MCA_PML_BASE_SEND_READY, MCA_PML_BASE_SEND_STANDARD, MCA_PML_BASE_SEND_SIZE }

## Variables
BEGIN_C_DECLS typedef uint64_t | mca_pml_sequence_t
OMPI_DECLSPEC mca_pml_base_module_t | mca_pml

## Detailed Description

P2P Management Layer (PML)

An MCA component type that provides the P2P interface functionality required by the MPI layer. The PML is a relatively thin layer that primarily provides for the fragmentation and scheduling of messages over multiple transports (instances of the Byte Transfer Layer (BTL) MCA component type) as depicted below:

## | MPI |

## | PML |

## | BTL (TCP) | BTL (SM) | BTL (...) |

A single PML component is selected by the MCA framework during library initialization. Initially, all available PMLs are loaded (potentially as shared libraries) and their component open and init functions called. The MCA framework selects the component returning the highest priority and closes/unloads any other PML components that may have been opened.

After all of the MCA components are initialized, the MPI/RTE will make downcalls into the PML to provide the initial list of processes (ompi_proc_t instances), and notification of changes (add/delete).

The PML module must select the set of BTL components that are to be used to reach a given destination. These should be cached on a PML specific data structure that is hung off the ompi_proc_t.

The PML should then apply a scheduling algorithm (round-robin, weighted distribution, etc), to schedule the delivery of messages over the available BTLs.

## Macro Definition Documentation

#define MCA_PML_BASE_VERSION_2_0_0

Value:
MCA_BASE_VERSION_2_0_0, \
"pml", 2, 0, 0

## Typedef Documentation

typedef struct mca_pml_base_module_1_0_0_t*(* mca_pml_base_component_init_fn_t)(int *priority, bool enable_progress_threads, bool enable_mpi_threads)

MCA->PML Called by MCA framework to initialize the component.

Parameters

  priority | (OUT) Relative priority or ranking used by MCA to selected a component.
  enable_progress_threads | (IN) Whether this component is allowed to run a hidden/progress thread or not.
  enable_mpi_threads | (IN) Whether support for multiple MPI threads is enabled or not (i.e., MPI_THREAD_MULTIPLE), which indicates whether multiple threads may invoke this component simultaneously or not.

typedef int(* mca_pml_base_module_add_comm_fn_t)(struct ompi_communicator_t *comm)

MPI Interface Functions.

Downcall from MPI layer when a new communicator is created.

Parameters

  comm | Communicator

Returns
  OMPI_SUCCESS or failure status.

Provides the PML the opportunity to initialize/cache a data structure on the communicator.

typedef int(* mca_pml_base_module_add_procs_fn_t)(struct ompi_proc_t **procs, size_t nprocs)

MCA management functions.

Downcall from MPI/RTE layer when new processes are created.

Parameters

  procs | Array of new processes
  nprocs | Size of process array

Returns
  OMPI_SUCCESS or failure status.

Provides a notification to the PML that new processes have been created, and provides the PML the opportunity to cache data (e.g. list of BTLs to use) on the ompi_proc_t data structure.

typedef int(* mca_pml_base_module_cancel_fn_t)(struct ompi_request_t *request)

Cancel pending operation.

Parameters

  request | (IN) Request

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_cancelled_fn_t)(struct ompi_request_t *request, int *flag)

Has a request been cancelled?

Parameters

  request | (IN) Request

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_del_comm_fn_t)(struct ompi_communicator_t *comm)

Downcall from MPI layer when a communicator is destroyed.

Parameters

  comm | Communicator

Returns
  OMPI_SUCCESS or failure status.

Provides the PML the opportunity to cleanup any datastructures associated with the communicator.

typedef int(* mca_pml_base_module_del_procs_fn_t)(struct ompi_proc_t **procs, size_t nprocs)

Downcall from MPI/RTE layer when processes are terminated.

Parameters

  procs | Array of processes
  nprocs | Size of process array

Returns
  OMPI_SUCCESS or failure status.

Provides a notification to the PML that processes have gone away, and provides the PML the opportunity to cleanup any data cached on the ompi_proc_t data structure.

typedef int(* mca_pml_base_module_dump_fn_t)(struct ompi_communicator_t *comm, int verbose)

Diagnostics function.

Parameters

  request | (IN) Communicator
  verbose | (IN) Verbosity level (passed to BTL)

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_enable_fn_t)(bool enable)

Downcall from MCA layer to enable the PML/BTLs.

Parameters

  enable | Enable/Disable PML forwarding

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_free_fn_t)(struct ompi_request_t **request)

Release resources held by a persistent mode request.

Parameters

  request | (IN) Request

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_ft_event_fn_t)(int status)

Fault Tolerance Awareness function.

Parameters

  status | Checkpoint status

Returns
  OMPI_SUCCESS or failure status

typedef int(* mca_pml_base_module_iprobe_fn_t)(int src, int tag, struct ompi_communicator_t *comm, int *matched, ompi_status_public_t *status)

Probe to poll for pending recv.

Parameters

  src | (IN) Source rank w/in communicator.
  tag | (IN) User defined tag.
  comm | (IN) Communicator.
  matched | (OUT) Flag indicating if matching recv exists.
  status | (OUT) Completion statuses.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_irecv_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, struct ompi_request_t **request)

Post a receive request.

Parameters

  buf | (IN) User buffer.
  count | (IN) Number of elements of the specified datatype.
  datatype | (IN) User defined datatype.
  src | (IN) Source rank w/in communicator.
  tag | (IN) User defined tag.
  comm | (IN) Communicator.
  request | (OUT) Request handle.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_irecv_init_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, struct ompi_request_t **request)

Initialize a persistent receive request.

Parameters

  buf | (IN) User buffer.
  count | (IN) Number of elements of the specified datatype.
  datatype | (IN) User defined datatype.
  src | (IN) Source rank w/in communicator.
  tag | (IN) User defined tag.
  comm | (IN) Communicator.
  request | (OUT) Request handle.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_isend_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm, struct ompi_request_t **request)

Post a send request.

Parameters

  buf | (IN) User buffer.
  count | (IN) Number of elements of the specified datatype.
  datatype | (IN) User defined datatype.
  dst | (IN) Peer rank w/in communicator.
  tag | (IN) User defined tag.
  mode | (IN) Send mode (STANDARD,BUFFERED,SYNCHRONOUS,READY)
  comm | (IN) Communicator.
  request | (OUT) Request handle.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_isend_init_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm, struct ompi_request_t **request)

Initialize a persistent send request.

Parameters

  buf | (IN) User buffer.
  count | (IN) Number of elements of the specified datatype.
  datatype | (IN) User defined datatype.
  dst | (IN) Peer rank w/in communicator.
  tag | (IN) User defined tag.
  mode | (IN) Send mode (STANDARD,BUFFERED,SYNCHRONOUS,READY)
  comm | (IN) Communicator.
  request | (OUT) Request handle.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_null_fn_t)(struct ompi_request_t **request)

A special NULL request handle.

Parameters

  request | (OUT) Request

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_probe_fn_t)(int src, int tag, struct ompi_communicator_t *comm, ompi_status_public_t *status)

Blocking probe to wait for pending recv.

Parameters

  src | (IN) Source rank w/in communicator.
  tag | (IN) User defined tag.
  comm | (IN) Communicator.
  status | (OUT) Completion statuses.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_progress_fn_t)(void)

For non-threaded case, provides MCA the opportunity to progress outstanding requests on all btls.

- Returns
    Count of "completions", a metric of how many items where completed in the call to progress.

typedef int(* mca_pml_base_module_recv_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int src, int tag, struct ompi_communicator_t *comm, ompi_status_public_t *status)

Post a receive and wait for completion.

Parameters

  buf | (IN) User buffer
  count | (IN) Number of elements of the specified datatype
  datatype | (IN) User defined datatype
  src | (IN) Source rank w/in communicator
  tag | (IN) User defined tag
  comm | (IN) Communicator
  status | (OUT) Completion status

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_send_fn_t)(void *buf, size_t count, struct ompi_datatype_t *datatype, int dst, int tag, mca_pml_base_send_mode_t mode, struct ompi_communicator_t *comm)

Post a send request and wait for completion.

Parameters

  buf | (IN) User buffer.
  count | (IN) Number of elements of the specified datatype.
  datatype | (IN) User defined datatype.
  dst | (IN) Peer rank w/in communicator.
  tag | (IN) User defined tag.
  mode | (IN) Send mode (STANDARD,BUFFERED,SYNCHRONOUS,READY)
  comm | (IN) Communicator.

Returns
  OMPI_SUCCESS or failure status.

typedef int(* mca_pml_base_module_start_fn_t)(size_t count, struct ompi_request_t **requests)

Initiate one or more persistent requests.

Parameters

  count | Number of requests
  request | Array of persistent requests

Returns
  OMPI_SUCCESS or failure status.