OpenMPI  0.1.1
rml.h File Reference

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.
 

Detailed Description

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).

Macro Definition Documentation

#define ORTE_RML_BASE_VERSION_2_0_0
Value:
MCA_BASE_VERSION_2_0_0, \
"rml", 2, 0, 0

Macro for use in components that are of type rml.

Typedef Documentation

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.

Note
The parameter in/out parameters are relative to the user's callback function.
Parameters
[in]statusCompletion status - equivalent to the return value from blocking send/recv
[in]peerName of peer process
[in]bufferMessage buffer
[in]tagUser defined tag for matching send/recv
[in]cbdataUser 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.

Note
The parameter in/out parameters are relative to the user's callback function.
Parameters
[in]statusCompletion status - equivalent to the return value from blocking send/recv
[in]peerOpaque name of peer process
[in]msgArray of iovecs describing user buffers and lengths
[in]countNumber of elements in iovec array
[in]tagUser defined tag for matching send/recv
[in]cbdataUser 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.

Returns
Exactly one module created by the call to the component's initialization function should be returned. The module structure should be fully populated, and the priority should be set to a reasonable value.
Parameters
[out]prioritySelection priority for the given component
Return values
NULLAn error occurred and initialization did not occur
non-NULLThe 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.

Note
The parameter in/out parameters are relative to the user's callback function.
Parameters
[in]peerName of peer process
[in]exceptionDescription 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.

Note
While the ping interface may be used between the call to the component's initialization function and this call, care must be taken when doing so. The remote process must have already called enable_comm() or the remote process will not reply to the ping. As the ping interface is generally used by MPI processes to find a daemon to contact, this should not be a major limitation.
Return values
ORTE_SUCCESSCommunications successfully enabled
ORTE_ERRORAn 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.

Parameters
[in]cbfuncUser callback
Return values
ORTE_SUCCESSThe operation completed successfully
ORTE_ERRORAn 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.

Note
Whether or not the finalize function returns successfully, the module should not be used once this function is called.
Return values
ORTE_SUCCESSSuccess
ORTE_ERRORAn unspecified error occurred
typedef int(* orte_rml_module_ft_event_fn_t)(int state)

Handle fault tolerance updates.

Handle fault tolerance updates

Parameters
[in]stateFault tolerance state update
Return values
ORTE_SUCCESSThe operation completed successfully
ORTE_ERRORAn 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.

Note
The function may return a contact info string which contains multiple addresses.
Return values
non-NULLThe contact information for this process
NULLAn 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().

Parameters
[in]contact_infoThe contact info string for the remote process
[in]tvTimeout after which the ping should be failed
Return values
ORTE_SUCESSThe process is available and will allow connections from the local process
ORTE_ERRORAn 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.

Parameters
[in]peerPeer process or ORTE_NAME_WILDCARD for wildcard receive
[out]bufferA dss buffer to update with the received data
[in]tagUser defined tag for matching send/recv
[in]flagsFlags modifying receive behavior
Return values
>0Number of bytes successfully received (may be smaller than the posted buffer size
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERRORAn 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.

Parameters
[in]peerPeer process or ORTE_NAME_WILDCARD for wildcard receive
[in]tagUser defined tag for matching send/recv
[in]flagsMay 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]cbfuncCallback function on message comlpetion
[in]cbdataUser data to provide during completion callback
Return values
ORTE_SUCCESSThe message was successfully started
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Parameters
[in]peerPeer process or ORTE_NAME_WILDCARD, exactly as passed to the non-blocking receive call
[in]tagPosted receive tag
Return values
ORTE_SUCCESSThe receive was successfully cancelled
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_NOT_FOUNDA matching receive was not found
ORTE_ERRORAn 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.

Parameters
[in]peerPeer process or ORTE_NAME_WILDCARD for wildcard receive
[out]msgiovec array of receive buffer space
[in]countNumber of iovec entries in the array
[in]tagUser defined tag for matching send/recv
[in]flagsMay be ORTE_RML_PEEK to return up to the number of bytes provided in the iovec array without removing the message from the queue.
Return values
>0Number of bytes successfully received (may be smaller than the posted buffer size
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERRORAn 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.

Parameters
[in]peerPeer process or ORTE_NAME_WILDCARD for wildcard receive
[out]msgiovec array of receive buffer space
[in]countNumber of iovec entries in the array
[in]tagUser defined tag for matching send/recv
[in]flagsMay 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]cbfuncCallback function on message comlpetion
[in]cbdataUser data to provide during completion callback
Return values
ORTE_SUCCESSThe message was successfully started
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Parameters
[in]peerName of receiving process
[in]buffersend buffer
[in]tagUser defined tag for matching send/recv
[in]flagsCurrently unused.
Return values
>0Number of bytes successfully sent (will be length of buffer)
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Parameters
[in]peerName of receiving process
[in]bufferBuffer array describing send buffer
[in]tagUser defined tag for matching send/recv
[in]flagsCurrently unused
[in]cbfuncCallback function on message comlpetion
[in]cbdataUser data to provide during completion callback
Return values
ORTE_SUCCESSThe message was successfully started
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Parameters
[in]peerName of receiving process
[in]msgiovec array describing send buffer
[in]countLength of iovec array
[in]tagUser defined tag for matching send/recv
[in]flagsCurrently unused.
Return values
>0Number of bytes successfully sent (will be length of all iovecs)
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Parameters
[in]peerName of receiving process
[in]msgiovec array describing send buffer
[in]countLength of iovec array
[in]tagUser defined tag for matching send/recv
[in]flagsCurrently unused
[in]cbfuncCallback function on message comlpetion
[in]cbdataUser data to provide during completion callback
Return values
ORTE_SUCCESSThe message was successfully started
ORTE_ERR_BAD_PARAMOne of the parameters was invalid
ORTE_ERR_ADDRESSEE_UNKNOWNContact information for the receiving process is not available
ORTE_ERRORAn 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.

Note
The user may not always explicitly call this function directly, but may instead cause it to be called through one of the contact setup functions available in orte/mca/rml/base/rml_contact.h.
Parameters
[in]contact_infoThe contact information string of a peer
Return values
ORTE_SUCCESSThe contact information was successfully updated
ORTE_ERRORAn unspecified error occurred during the update