OpenMPI  0.1.1
ompi_module_exchange.h File Reference

Open MPI module-related data transfer mechanism. More...

#include "ompi_config.h"
#include "opal/dss/dss_types.h"
#include "opal/mca/mca.h"

Go to the source code of this file.

Functions

BEGIN_C_DECLS OMPI_DECLSPEC int ompi_modex_send (mca_base_component_t *source_component, const void *buffer, size_t size)
 Send a module-specific buffer to all other corresponding MCA modules in peer processes. More...
 
OMPI_DECLSPEC int ompi_modex_send_string (const char *key, const void *buffer, size_t size)
 Send a buffer to all other corresponding peer process. More...
 
OMPI_DECLSPEC int ompi_modex_send_key_value (const char *key, const void *value, opal_data_type_t dtype)
 Send a value to all other corresponding peer process. More...
 
OMPI_DECLSPEC int ompi_modex_recv (mca_base_component_t *dest_component, struct ompi_proc_t *source_proc, void **buffer, size_t *size)
 Receive a module-specific buffer from a corresponding MCA module in a specific peer process. More...
 
OMPI_DECLSPEC int ompi_modex_recv_string (const char *key, struct ompi_proc_t *source_proc, void **buffer, size_t *size)
 Receive a buffer from a given peer. More...
 
OMPI_DECLSPEC int ompi_modex_recv_key_value (const char *key, struct ompi_proc_t *source_proc, void *value, opal_data_type_t dtype)
 Recv a value from a given peer. More...
 

Detailed Description

Open MPI module-related data transfer mechanism.

A system for publishing module-related data for global initialization. Known simply as the "modex", this interface provides a system for sharing data, particularly data related to modules and their availability on the system.

The modex system is tightly integrated into the general run-time initialization system and takes advantage of global update periods to minimize the amount of network traffic. All updates are also stored in the general purpose registry, and can be read at any time during the life of the process. Care should be taken to not call the blocking receive during the first stage of global initialization, as data will not be available the process will likely hang.

Note
For the purpose of this interface, two components are "corresponding" if:
  • they share the same major and minor MCA version number
  • they have the same type name string
  • they share the same major and minor type version number
  • they have the same component name string
  • they share the same major and minor component version number

Function Documentation

OMPI_DECLSPEC int ompi_modex_recv ( mca_base_component_t dest_component,
struct ompi_proc_t source_proc,
void **  buffer,
size_t *  size 
)

Receive a module-specific buffer from a corresponding MCA module in a specific peer process.

This is the corresponding "get" call to ompi_modex_send(). After selection, modules can call this function to receive the buffer sent by their corresponding module on the process source_proc.

If a buffer from a corresponding module is found, buffer will be filled with a pointer to a copy of the buffer that was sent by the peer process. It is the caller's responsibility to free this buffer. The size will be filled in with the total size of the buffer.

Note
If the modex system has received information from a given process, but has not yet received information for the given component, ompi_modex_recv() will return no data. This can not happen to a process that has gone through the normal startup proceedure, but if you believe this can happen with your component, you should use ompi_modex_recv_nb() to receive updates when the information becomes available.
Parameters
[in]dest_componentA pointer to this module's component struct
[in]source_procPeer process to receive from
[out]bufferA pointer to a (void*) that will be filled with a pointer to the received buffer
[out]sizePointer to a size_t that will be filled with the number of bytes in the buffer
Return values
OMPI_SUCCESSIf a corresponding module buffer is found and successfully returned to the caller.
OMPI_ERR_NOT_IMPLEMENTEDModex support is not available in this build of Open MPI (systems like the Cray XT)
OMPI_ERR_OUT_OF_RESOURCENo memory could be allocated for the buffer.

References ompi_proc_t::proc_name.

OMPI_DECLSPEC int ompi_modex_recv_key_value ( const char *  key,
struct ompi_proc_t source_proc,
void *  value,
opal_data_type_t  dtype 
)

Recv a value from a given peer.

Similar to ompi_modex_recv(), but uses a char* key instead of a component name for indexing, and performs all required conditioning to deal with heterogeneity.

Parameters
[in]keyA unique key for data storage / lookup
[in]source_procPeer process to receive from
[in]valueA pointer to the address where the data value will be stored
[in]dtypeData type of the value
Return values
OMPI_SUCCESSIf a corresponding module value is found and successfully returned to the caller.
OMPI_ERR_NOT_IMPLEMENTEDModex support is not available in this build of Open MPI (systems like the Cray XT)

References OBJ_CONSTRUCT, OBJ_DESTRUCT, and ompi_proc_t::proc_name.

Referenced by ompi_proc_complete_init().

OMPI_DECLSPEC int ompi_modex_recv_string ( const char *  key,
struct ompi_proc_t source_proc,
void **  buffer,
size_t *  size 
)

Receive a buffer from a given peer.

Similar to ompi_modex_recv(), but uses a char* key instead of a component name for indexing. All other semantics apply.

Note
If the modex system has received information from a given process, but has not yet received information for the given component, ompi_modex_recv_string() will return no data. This can not happen to a process that has gone through the normal startup proceedure, but if you believe this can happen with your component, you should use ompi_modex_recv_string_nb() to receive updates when the information becomes available.
Parameters
[in]keyA unique key for data storage / lookup
[in]source_procPeer process to receive from
[out]bufferA pointer to a (void*) that will be filled with a pointer to the received buffer
[out]sizePointer to a size_t that will be filled with the number of bytes in the buffer
Return values
OMPI_SUCCESSIf a corresponding module buffer is found and successfully returned to the caller.
OMPI_ERR_NOT_IMPLEMENTEDModex support is not available in this build of Open MPI (systems like the Cray XT)
OMPI_ERR_OUT_OF_RESOURCENo memory could be allocated for the buffer.

References ompi_proc_t::proc_name.

BEGIN_C_DECLS OMPI_DECLSPEC int ompi_modex_send ( mca_base_component_t source_component,
const void *  buffer,
size_t  size 
)

Send a module-specific buffer to all other corresponding MCA modules in peer processes.

This function takes a contiguous buffer of network-ordered data and makes it available to all other MCA processes during the selection process. Modules sent by one source_component can only be received by a corresponding module with the same component name.

This function is indended to be used during MCA module initialization before selection (the selection process is defined differently for each component type). Each module will provide a buffer containing meta information and/or parameters that it wants to share with its corresponding modules in peer processes. This information typically contains location / contact information for establishing communication between processes (in a manner that is specific to that module). For example, a TCP-based module could provide its IP address and TCP port where it is waiting on listen(). The peer process receiving this buffer can therefore open a socket to the indicated IP address and TCP port.

During the selection process, the MCA framework will effectively perform an "allgather" operation of all modex buffers; every buffer will be available to every peer process (see ompi_modex_recv()).

The buffer is copied during the send call and may be modified or free()'ed immediately after the return from this function call.

Note
Buffer contents is transparent to the MCA framework – it must already either be in network order or be in some format that peer processes will be able to read it, regardless of pointer sizes or endian bias.
Parameters
[in]source_componentA pointer to this module's component structure
[in]bufferA pointer to the beginning of the buffer to send
[in]sizeNumber of bytes in the buffer
Return values
OMPI_SUCCESSOn success
OMPI_ERRORAn unspecified error occurred

Referenced by mca_btl_elan_component_init(), and mca_btl_mx_component_init().

OMPI_DECLSPEC int ompi_modex_send_key_value ( const char *  key,
const void *  value,
opal_data_type_t  dtype 
)

Send a value to all other corresponding peer process.

Similar to ompi_modex_send(), but uses a char* key instead of a component name for indexing, and performs all required conditioning to deal with heterogeneity.

Parameters
[in]keyA unique key for data storage / lookup
[in]valueA pointer to data value
[in]dtypeData type of the value
Return values
OMPI_SUCCESSOn success
OMPI_ERRORAn unspecified error occurred

References OBJ_CONSTRUCT, and OBJ_DESTRUCT.

Referenced by ompi_proc_init().

OMPI_DECLSPEC int ompi_modex_send_string ( const char *  key,
const void *  buffer,
size_t  size 
)

Send a buffer to all other corresponding peer process.

Similar to ompi_modex_send(), but uses a char* key instead of a component name for indexing. All other semantics apply.

Note
Buffer contents is transparent to the modex – it must already either be in network order or be in some format that peer processes will be able to read it, regardless of pointer sizes or endian bias.
Parameters
[in]keyA unique key for data storage / lookup
[in]bufferA pointer to the beginning of the buffer to send
[in]sizeNumber of bytes in the buffer
Return values
OMPI_SUCCESSOn success
OMPI_ERRORAn unspecified error occurred

Referenced by ompi_mpi_init().