OpenMPI
0.1.1
|
Runtime Messaging Layer (RML) Communication Interface. More...
#include "orte_config.h"
#include "orte/types.h"
#include "opal/mca/mca.h"
#include "opal/mca/crs/crs.h"
#include "opal/mca/crs/base/base.h"
#include "orte/mca/rml/rml_types.h"
Go to the source code of this file.
Data Structures | |
struct | orte_rml_component_2_0_0_t |
RML component interface. More... | |
struct | orte_rml_module_t |
RML module interface. More... | |
Macros | |
#define | ORTE_RML_BASE_VERSION_2_0_0 |
Macro for use in components that are of type rml. More... | |
Typedefs | |
typedef struct orte_rml_module_t *(* | orte_rml_component_init_fn_t )(int *priority) |
RML component initialization. More... | |
typedef struct orte_rml_component_2_0_0_t | orte_rml_component_t |
Convienence typedef. | |
typedef void(* | orte_rml_callback_fn_t )(int status, struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, void *cbdata) |
Funtion prototype for callback from non-blocking iovec send and receive. More... | |
typedef void(* | orte_rml_buffer_callback_fn_t )(int status, struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, void *cbdata) |
Funtion prototype for callback from non-blocking buffer send and receive. More... | |
typedef void(* | orte_rml_exception_callback_t )(const orte_process_name_t *peer, orte_rml_exception_t exception) |
Function prototype for exception callback. More... | |
typedef int(* | orte_rml_module_enable_comm_fn_t )(void) |
Enable communication using the RML module. More... | |
typedef int(* | orte_rml_module_finalize_fn_t )(void) |
Finalize the RML module. More... | |
typedef char *(* | orte_rml_module_get_contact_info_fn_t )(void) |
Get a "contact info" string for the local process. More... | |
typedef int(* | orte_rml_module_set_contact_info_fn_t )(const char *contact_info) |
Update the RML with a remote process's contact info. More... | |
typedef int(* | orte_rml_module_ping_fn_t )(const char *contact_info, const struct timeval *tv) |
"Ping" another process to determine availability More... | |
typedef int(* | orte_rml_module_send_fn_t )(struct orte_process_name_t *peer, struct iovec *msg, int count, int tag, int flags) |
Send an iovec blocking message. More... | |
typedef int(* | orte_rml_module_send_buffer_fn_t )(struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, int flags) |
Send a buffer blocking message. More... | |
typedef int(* | orte_rml_module_send_nb_fn_t )(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags, orte_rml_callback_fn_t cbfunc, void *cbdata) |
Send an iovec non-blocking message. More... | |
typedef int(* | orte_rml_module_send_buffer_nb_fn_t )(struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, int flags, orte_rml_buffer_callback_fn_t cbfunc, void *cbdata) |
Send an buffer non-blocking message. More... | |
typedef int(* | orte_rml_module_recv_fn_t )(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags) |
Receive an iovec blocking message. More... | |
typedef int(* | orte_rml_module_recv_buffer_fn_t )(struct orte_process_name_t *peer, struct opal_buffer_t *buf, orte_rml_tag_t tag, int flags) |
Receive a buffer blocking message. More... | |
typedef int(* | orte_rml_module_recv_nb_fn_t )(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags, orte_rml_callback_fn_t cbfunc, void *cbdata) |
Receive an iovec non-blocking message. More... | |
typedef int(* | orte_rml_module_recv_buffer_nb_fn_t )(struct orte_process_name_t *peer, orte_rml_tag_t tag, int flags, orte_rml_buffer_callback_fn_t cbfunc, void *cbdata) |
Receive a buffer non-blocking message. More... | |
typedef int(* | orte_rml_module_recv_cancel_fn_t )(orte_process_name_t *peer, orte_rml_tag_t tag) |
Cancel a posted non-blocking receive. More... | |
typedef int(* | orte_rml_module_exception_fn_t )(orte_rml_exception_callback_t cbfunc) |
Register or deregister an exception callback function. More... | |
typedef int(* | orte_rml_module_ft_event_fn_t )(int state) |
Handle fault tolerance updates. More... | |
typedef int(* | orte_rml_module_purge_fn_t )(struct orte_process_name_t *peer) |
Purge the RML/OOB of contact info and pending messages to/from a specified process. More... | |
typedef struct orte_rml_module_t | orte_rml_module_t |
Convienence typedef. | |
Variables | |
ORTE_DECLSPEC orte_rml_module_t | orte_rml |
Interface for RML communication. | |
Runtime Messaging Layer (RML) Communication Interface.
The Runtime Messaging Layer (RML) provices basic point-to-point communication between ORTE processes. The system is available for most architectures, with some exceptions (the Cray XT3/XT4, for example).
#define ORTE_RML_BASE_VERSION_2_0_0 |
Macro for use in components that are of type rml.
typedef void(* orte_rml_buffer_callback_fn_t)(int status, struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, void *cbdata) |
Funtion prototype for callback from non-blocking buffer send and receive.
Funtion prototype for callback from non-blocking buffer send and receive. The buffer may not be the same pointer passed to either send_buffer_nb and recv_buffer_nb. The peer memory location may not be the same, and is owned by the RML, not the calling process.
[in] | status | Completion status - equivalent to the return value from blocking send/recv |
[in] | peer | Name of peer process |
[in] | buffer | Message buffer |
[in] | tag | User defined tag for matching send/recv |
[in] | cbdata | User data passed to send_nb() or recv_nb() |
typedef void(* orte_rml_callback_fn_t)(int status, struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, void *cbdata) |
Funtion prototype for callback from non-blocking iovec send and receive.
Funtion prototype for callback from non-blocking iovec send and receive. The iovec pointer will be the same pointer passed to either send_nb and recv_nb. The peer memory location may not be the same, and is owned by the RML, not the calling process.
[in] | status | Completion status - equivalent to the return value from blocking send/recv |
[in] | peer | Opaque name of peer process |
[in] | msg | Array of iovecs describing user buffers and lengths |
[in] | count | Number of elements in iovec array |
[in] | tag | User defined tag for matching send/recv |
[in] | cbdata | User data passed to send_nb() or recv_nb() |
typedef struct orte_rml_module_t*(* orte_rml_component_init_fn_t)(int *priority) |
RML component initialization.
Create an instance (module) of the given RML component. Upon returning, the module data structure should be fully populated and all functions should be usable. Non-blocking receive calls may be posted upon return from this function, although communication need not be enabled until enable_comm() call is called on the module.
[out] | priority | Selection priority for the given component |
NULL | An error occurred and initialization did not occur |
non-NULL | The module was successfully initialized |
typedef void(* orte_rml_exception_callback_t)(const orte_process_name_t *peer, orte_rml_exception_t exception) |
Function prototype for exception callback.
Function prototype for callback triggered when a communication error is detected.
[in] | peer | Name of peer process |
[in] | exception | Description of the error causing the exception |
typedef int(* orte_rml_module_enable_comm_fn_t)(void) |
Enable communication using the RML module.
Enable communication using the RML module. Before this call, only the non-blocking receive and ping interfaces may be used. After this call returns, the module must be fully functional, capable of sending and receiving data. This function will be called after the process has been assigned a proces identifier.
ORTE_SUCCESS | Communications successfully enabled |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_exception_fn_t)(orte_rml_exception_callback_t cbfunc) |
Register or deregister an exception callback function.
Register or deregister a callback when an asynchronous communication exception occurs.
[in] | cbfunc | User callback |
ORTE_SUCCESS | The operation completed successfully |
ORTE_ERROR | An unspecifed error occurred |
typedef int(* orte_rml_module_finalize_fn_t)(void) |
Finalize the RML module.
Finalize the RML module, ending all communication and cleaning up all resources associated with the module. After the finalize function is called, all interface functions (and the module structure itself) are not available for use.
ORTE_SUCCESS | Success |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_ft_event_fn_t)(int state) |
Handle fault tolerance updates.
Handle fault tolerance updates
[in] | state | Fault tolerance state update |
ORTE_SUCCESS | The operation completed successfully |
ORTE_ERROR | An unspecifed error occurred |
typedef char*(* orte_rml_module_get_contact_info_fn_t)(void) |
Get a "contact info" string for the local process.
Get a "contact info" string that can be used by other processes to share the contact information for the given process. The "contact info" string includes the process identifier for the given process and uses only basic ascii characters. It should be quoted when evaluated by a shell, although no special escaping is necessary.
non-NULL | The contact information for this process |
NULL | An error occurred when trying to get the current process contact info |
typedef int(* orte_rml_module_ping_fn_t)(const char *contact_info, const struct timeval *tv) |
"Ping" another process to determine availability
Ping another process to determine if it is available. This function only verifies that the process is alive and will allow a connection to the local process. It does not qualify as establishing communication with the remote process, as required by the note for set_contact_info().
[in] | contact_info | The contact info string for the remote process |
[in] | tv | Timeout after which the ping should be failed |
ORTE_SUCESS | The process is available and will allow connections from the local process |
ORTE_ERROR | An unspecified error occurred during the update |
typedef int(* orte_rml_module_purge_fn_t)(struct orte_process_name_t *peer) |
Purge the RML/OOB of contact info and pending messages to/from a specified process.
Used when a process aborts and is to be restarted
typedef int(* orte_rml_module_recv_buffer_fn_t)(struct orte_process_name_t *peer, struct opal_buffer_t *buf, orte_rml_tag_t tag, int flags) |
Receive a buffer blocking message.
Receive a message into a user-provided buffer. The call will not return until the buffer has been received. The remote process does not need to be connected to the current process to post the receive, so it is possible to post a receive with no sending process (ie, it will never complete). The buffer must not be currently in use with any other RML communication function during a receive call.
[in] | peer | Peer process or ORTE_NAME_WILDCARD for wildcard receive |
[out] | buffer | A dss buffer to update with the received data |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | Flags modifying receive behavior |
>0 | Number of bytes successfully received (may be smaller than the posted buffer size |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_recv_buffer_nb_fn_t)(struct orte_process_name_t *peer, orte_rml_tag_t tag, int flags, orte_rml_buffer_callback_fn_t cbfunc, void *cbdata) |
Receive a buffer non-blocking message.
Receive a message into a user-provided buffer. The call will not return until the buffer has been received. The remote process does not need to be connected to the current process to post the receive, so it is possible to post a receive with no sending process (ie, it will never complete). The buffer must not be currently in use with any other RML communication function during a receive call.
[in] | peer | Peer process or ORTE_NAME_WILDCARD for wildcard receive |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | May be ORTE_RML_PEEK to return up to the number of bytes provided in the iovec array without removing the message from the queue. |
[in] | cbfunc | Callback function on message comlpetion |
[in] | cbdata | User data to provide during completion callback |
ORTE_SUCCESS | The message was successfully started |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_recv_cancel_fn_t)(orte_process_name_t *peer, orte_rml_tag_t tag) |
Cancel a posted non-blocking receive.
Attempt to cancel a posten non-blocking receive.
[in] | peer | Peer process or ORTE_NAME_WILDCARD, exactly as passed to the non-blocking receive call |
[in] | tag | Posted receive tag |
ORTE_SUCCESS | The receive was successfully cancelled |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_NOT_FOUND | A matching receive was not found |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_recv_fn_t)(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags) |
Receive an iovec blocking message.
Receive a message into a user-provided iovec. The call will not return until the buffer has been received. The remote process does not need to be connected to the current process to post the receive, so it is possible to post a receive with no sending process (ie, it will never complete). The buffer must not be currently in use with any other RML communication function during a receive call.
[in] | peer | Peer process or ORTE_NAME_WILDCARD for wildcard receive |
[out] | msg | iovec array of receive buffer space |
[in] | count | Number of iovec entries in the array |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | May be ORTE_RML_PEEK to return up to the number of bytes provided in the iovec array without removing the message from the queue. |
>0 | Number of bytes successfully received (may be smaller than the posted buffer size |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_recv_nb_fn_t)(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags, orte_rml_callback_fn_t cbfunc, void *cbdata) |
Receive an iovec non-blocking message.
Receive a message into a user-provided iovec. The call will not return until the buffer has been received. The remote process does not need to be connected to the current process to post the receive, so it is possible to post a receive with no sending process (ie, it will never complete). The buffer must not be currently in use with any other RML communication function during a receive call.
[in] | peer | Peer process or ORTE_NAME_WILDCARD for wildcard receive |
[out] | msg | iovec array of receive buffer space |
[in] | count | Number of iovec entries in the array |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | May be ORTE_RML_PEEK to return up to the number of bytes provided in the iovec array without removing the message from the queue. |
[in] | cbfunc | Callback function on message comlpetion |
[in] | cbdata | User data to provide during completion callback |
ORTE_SUCCESS | The message was successfully started |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_send_buffer_fn_t)(struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, int flags) |
Send a buffer blocking message.
Send a buffer blocking message to the specified peer. The call will return when the buffer may be modified. The return of a call to send() does not give any indication of remote completion.
[in] | peer | Name of receiving process |
[in] | buffer | send buffer |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | Currently unused. |
>0 | Number of bytes successfully sent (will be length of buffer) |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_send_buffer_nb_fn_t)(struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, int flags, orte_rml_buffer_callback_fn_t cbfunc, void *cbdata) |
Send an buffer non-blocking message.
Send an buffer blocking message to the specified peer. The call will return immediately, although the buffer may not be modified until the completion callback is triggered. The buffer may be passed to another call to send_nb before the completion callback is triggered. The callback being triggered does not give any indication of remote completion.
[in] | peer | Name of receiving process |
[in] | buffer | Buffer array describing send buffer |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | Currently unused |
[in] | cbfunc | Callback function on message comlpetion |
[in] | cbdata | User data to provide during completion callback |
ORTE_SUCCESS | The message was successfully started |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_send_fn_t)(struct orte_process_name_t *peer, struct iovec *msg, int count, int tag, int flags) |
Send an iovec blocking message.
Send an iovec blocking message to the specified peer. The call will return when the buffer may be modified. The return of a call to send() does not give any indication of remote completion.
[in] | peer | Name of receiving process |
[in] | msg | iovec array describing send buffer |
[in] | count | Length of iovec array |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | Currently unused. |
>0 | Number of bytes successfully sent (will be length of all iovecs) |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_send_nb_fn_t)(struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, int flags, orte_rml_callback_fn_t cbfunc, void *cbdata) |
Send an iovec non-blocking message.
Send an iovec blocking message to the specified peer. The call will return immediately, although the iovec may not be modified until the completion callback is triggered. The iovec may be passed to another call to send_nb before the completion callback is triggered. The callback being triggered does not give any indication of remote completion.
[in] | peer | Name of receiving process |
[in] | msg | iovec array describing send buffer |
[in] | count | Length of iovec array |
[in] | tag | User defined tag for matching send/recv |
[in] | flags | Currently unused |
[in] | cbfunc | Callback function on message comlpetion |
[in] | cbdata | User data to provide during completion callback |
ORTE_SUCCESS | The message was successfully started |
ORTE_ERR_BAD_PARAM | One of the parameters was invalid |
ORTE_ERR_ADDRESSEE_UNKNOWN | Contact information for the receiving process is not available |
ORTE_ERROR | An unspecified error occurred |
typedef int(* orte_rml_module_set_contact_info_fn_t)(const char *contact_info) |
Update the RML with a remote process's contact info.
Update the RML with a remote process's contact information, as returned from the get_contact_info() function on the remote process. Before a send can be initiated to a remote process, either this function must be called for that process or that process must have already established a connection to the local process.
[in] | contact_info | The contact information string of a peer |
ORTE_SUCCESS | The contact information was successfully updated |
ORTE_ERROR | An unspecified error occurred during the update |