OpenMPI 0.1.1

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

- File List
- Globals

Data Structures | Macros | Typedefs | Variables
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] | 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.

Note
  The parameter in/out parameters are relative to the user's callback function.

Parameters

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

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] | priority | Selection priority for the given component

Return values

  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.

Note
  The parameter in/out parameters are relative to the user's callback function.

Parameters

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

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

Parameters

  [in] | cbfunc | User callback

Return values

  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.

Note
  Whether or not the finalize function returns successfully, the module should not be used once this function is called.

Return values

  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

Parameters

  [in] | state | Fault tolerance state update

Return values

  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.

Note
  The function may return a contact info string which contains multiple addresses.

Return values

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

Parameters

  [in] | contact_info | The contact info string for the remote process
  [in] | tv | Timeout after which the ping should be failed

Return values

  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.

Parameters

  [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

Return values

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

Parameters

  [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

Return values

  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.

Parameters

  [in] | peer | Peer process or ORTE_NAME_WILDCARD, exactly as passed to the non-blocking receive call
  [in] | tag | Posted receive tag

Return values

  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.

Parameters

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

Return values

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

Parameters

  [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

Return values

  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.

Parameters

  [in] | peer | Name of receiving process
  [in] | buffer | send buffer
  [in] | tag | User defined tag for matching send/recv
  [in] | flags | Currently unused.

Return values

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

Parameters

  [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

Return values

  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.

Parameters

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

Return values

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

Parameters

  [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

Return values

  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.

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_info | The contact information string of a peer

Return values

  ORTE_SUCCESS | The contact information was successfully updated
  ORTE_ERROR | An unspecified error occurred during the update