OpenMPI  0.1.1
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
commCommunicator
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
procsArray of new processes
nprocsSize 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
commCommunicator
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
procsArray of processes
nprocsSize 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
enableEnable/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
statusCheckpoint 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
countNumber of requests
requestArray of persistent requests
Returns
OMPI_SUCCESS or failure status.