/* * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana * University Research and Technology * Corporation. All rights reserved. * Copyright (c) 2004-2005 The University of Tennessee and The University * of Tennessee Research Foundation. All rights * reserved. * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, * University of Stuttgart. All rights reserved. * Copyright (c) 2004-2005 The Regents of the University of California. * All rights reserved. * Copyright (c) 2006-2012 Los Alamos National Security, LLC. All rights * reserved. * Copyright (c) 2008 Cisco Systems, Inc. All rights reserved. * $COPYRIGHT$ * * Additional copyrights may follow * * $HEADER$ */ /** @file * 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 */ #ifndef MCA_OMPI_MODULE_EXCHANGE_H #define MCA_OMPI_MODULE_EXCHANGE_H #include "ompi_config.h" #ifdef HAVE_SYS_TYPES_H #include #endif #include "opal/dss/dss_types.h" #include "opal/mca/mca.h" #include "ompi/proc/proc.h" BEGIN_C_DECLS /** * 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 \em before \em 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 \em * 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. * * @param[in] source_component A pointer to this module's component * structure * @param[in] buffer A pointer to the beginning of the buffer to send * @param[in] size Number of bytes in the buffer * * @retval OMPI_SUCCESS On success * @retval OMPI_ERROR An unspecified error occurred */ OMPI_DECLSPEC int ompi_modex_send(const mca_base_component_t *source_component, 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 \em 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. * * @param[in] key A unique key for data storage / lookup * @param[in] buffer A pointer to the beginning of the buffer to send * @param[in] size Number of bytes in the buffer * * @retval OMPI_SUCCESS On success * @retval OMPI_ERROR An unspecified error occurred */ OMPI_DECLSPEC int ompi_modex_send_string(const char* key, const void *buffer, size_t size); /** * 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. * * @param[in] key A unique key for data storage / lookup * @param[in] value A pointer to data value * @param[in] dtype Data type of the value * * @retval OMPI_SUCCESS On success * @retval OMPI_ERROR An unspecified error occurred */ OMPI_DECLSPEC int ompi_modex_send_key_value(const char* key, const void *value, opal_data_type_t dtype); /** * 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. * * @param[in] dest_component A pointer to this module's component struct * @param[in] source_proc Peer process to receive from * @param[out] buffer A pointer to a (void*) that will be filled * with a pointer to the received buffer * @param[out] size Pointer to a size_t that will be filled with * the number of bytes in the buffer * * @retval OMPI_SUCCESS If a corresponding module buffer is found and * successfully returned to the caller. * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in * this build of Open MPI (systems like the Cray XT) * @retval OMPI_ERR_OUT_OF_RESOURCE No memory could be allocated for the * buffer. */ OMPI_DECLSPEC int ompi_modex_recv(const mca_base_component_t *dest_component, const ompi_proc_t *source_proc, void **buffer, size_t *size); OMPI_DECLSPEC int ompi_modex_recv_pointer(const mca_base_component_t *component, const ompi_proc_t *proc, void **buffer, opal_data_type_t type); /** * 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. * * @param[in] key A unique key for data storage / lookup * @param[in] source_proc Peer process to receive from * @param[out] buffer A pointer to a (void*) that will be filled * with a pointer to the received buffer * @param[out] size Pointer to a size_t that will be filled with * the number of bytes in the buffer * * @retval OMPI_SUCCESS If a corresponding module buffer is found and * successfully returned to the caller. * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in * this build of Open MPI (systems like the Cray XT) * @retval OMPI_ERR_OUT_OF_RESOURCE No memory could be allocated for the * buffer. */ OMPI_DECLSPEC int ompi_modex_recv_string(const char* key, const ompi_proc_t *source_proc, void **buffer, size_t *size); OMPI_DECLSPEC int ompi_modex_recv_string_pointer(const char* key, const ompi_proc_t *source_proc, void **buffer, opal_data_type_t type); /** * 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. * * @param[in] key A unique key for data storage / lookup * @param[in] source_proc Peer process to receive from * @param[in] value A pointer to the address where the data * value will be stored * @param[in] dtype Data type of the value * * @retval OMPI_SUCCESS If a corresponding module value is found and * successfully returned to the caller. * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in * this build of Open MPI (systems like the Cray XT) */ OMPI_DECLSPEC int ompi_modex_recv_key_value(const char* key, const ompi_proc_t *source_proc, void **value, opal_data_type_t dtype); END_C_DECLS #endif /* MCA_OMPI_MODULE_EXCHANGE_H */