OpenMPI  0.1.1
ompi_module_exchange.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * Copyright (c) 2006-2007 Los Alamos National Security, LLC. All rights
13  * reserved.
14  * Copyright (c) 2008 Cisco Systems, Inc. All rights reserved.
15  * $COPYRIGHT$
16  *
17  * Additional copyrights may follow
18  *
19  * $HEADER$
20  */
21 
22 /** @file
23  * Open MPI module-related data transfer mechanism
24  *
25  * A system for publishing module-related data for global
26  * initialization. Known simply as the "modex", this interface
27  * provides a system for sharing data, particularly data related to
28  * modules and their availability on the system.
29  *
30  * The modex system is tightly integrated into the general run-time
31  * initialization system and takes advantage of global update periods
32  * to minimize the amount of network traffic. All updates are also
33  * stored in the general purpose registry, and can be read at any time
34  * during the life of the process. Care should be taken to not call
35  * the blocking receive during the first stage of global
36  * initialization, as data will not be available the process will
37  * likely hang.
38  *
39  * @note For the purpose of this interface, two components are
40  * "corresponding" if:
41  * - they share the same major and minor MCA version number
42  * - they have the same type name string
43  * - they share the same major and minor type version number
44  * - they have the same component name string
45  * - they share the same major and minor component version number
46  */
47 
48 #ifndef MCA_OMPI_MODULE_EXCHANGE_H
49 #define MCA_OMPI_MODULE_EXCHANGE_H
50 
51 #include "ompi_config.h"
52 
53 #ifdef HAVE_SYS_TYPES_H
54 #include <sys/types.h>
55 #endif
56 
57 #include "opal/dss/dss_types.h"
58 #include "opal/mca/mca.h"
59 
60 
61 struct ompi_proc_t;
62 
63 BEGIN_C_DECLS
64 
65 /**
66  * Send a module-specific buffer to all other corresponding MCA
67  * modules in peer processes
68  *
69  * This function takes a contiguous buffer of network-ordered data
70  * and makes it available to all other MCA processes during the
71  * selection process. Modules sent by one source_component can only
72  * be received by a corresponding module with the same
73  * component name.
74  *
75  * This function is indended to be used during MCA module
76  * initialization \em before \em selection (the selection process is
77  * defined differently for each component type). Each module will
78  * provide a buffer containing meta information and/or parameters
79  * that it wants to share with its corresponding modules in peer
80  * processes. This information typically contains location /
81  * contact information for establishing communication between
82  * processes (in a manner that is specific to that module). For
83  * example, a TCP-based module could provide its IP address and TCP
84  * port where it is waiting on listen(). The peer process receiving
85  * this buffer can therefore open a socket to the indicated IP
86  * address and TCP port.
87  *
88  * During the selection process, the MCA framework will effectively
89  * perform an "allgather" operation of all modex buffers; every
90  * buffer will be available to every peer process (see
91  * ompi_modex_recv()).
92  *
93  * The buffer is copied during the send call and may be modified or
94  * free()'ed immediately after the return from this function call.
95  *
96  * @note Buffer contents is transparent to the MCA framework -- it \em
97  * must already either be in network order or be in some format that
98  * peer processes will be able to read it, regardless of pointer sizes
99  * or endian bias.
100  *
101  * @param[in] source_component A pointer to this module's component
102  * structure
103  * @param[in] buffer A pointer to the beginning of the buffer to send
104  * @param[in] size Number of bytes in the buffer
105  *
106  * @retval OMPI_SUCCESS On success
107  * @retval OMPI_ERROR An unspecified error occurred
108  */
109 OMPI_DECLSPEC int ompi_modex_send(mca_base_component_t *source_component,
110  const void *buffer, size_t size);
111 
112 
113 /**
114  * Send a buffer to all other corresponding peer process
115  *
116  * Similar to ompi_modex_send(), but uses a char* key instead of a
117  * component name for indexing. All other semantics apply.
118  *
119  * @note Buffer contents is transparent to the modex -- it \em must
120  * already either be in network order or be in some format that peer
121  * processes will be able to read it, regardless of pointer sizes or
122  * endian bias.
123  *
124  * @param[in] key A unique key for data storage / lookup
125  * @param[in] buffer A pointer to the beginning of the buffer to send
126  * @param[in] size Number of bytes in the buffer
127  *
128  * @retval OMPI_SUCCESS On success
129  * @retval OMPI_ERROR An unspecified error occurred
130  */
131 OMPI_DECLSPEC int ompi_modex_send_string(const char* key,
132  const void *buffer, size_t size);
133 
134 /**
135  * Send a value to all other corresponding peer process
136  *
137  * Similar to ompi_modex_send(), but uses a char* key instead of a
138  * component name for indexing, and performs all required conditioning
139  * to deal with heterogeneity.
140  *
141  * @param[in] key A unique key for data storage / lookup
142  * @param[in] value A pointer to data value
143  * @param[in] dtype Data type of the value
144  *
145  * @retval OMPI_SUCCESS On success
146  * @retval OMPI_ERROR An unspecified error occurred
147  */
148 OMPI_DECLSPEC int ompi_modex_send_key_value(const char* key,
149  const void *value,
150  opal_data_type_t dtype);
151 
152 
153 /**
154  * Receive a module-specific buffer from a corresponding MCA module
155  * in a specific peer process
156  *
157  * This is the corresponding "get" call to ompi_modex_send().
158  * After selection, modules can call this function to receive the
159  * buffer sent by their corresponding module on the process
160  * source_proc.
161  *
162  * If a buffer from a corresponding module is found, buffer will be
163  * filled with a pointer to a copy of the buffer that was sent by
164  * the peer process. It is the caller's responsibility to free this
165  * buffer. The size will be filled in with the total size of the
166  * buffer.
167  *
168  * @note If the modex system has received information from a given
169  * process, but has not yet received information for the given
170  * component, ompi_modex_recv() will return no data. This
171  * can not happen to a process that has gone through the normal
172  * startup proceedure, but if you believe this can happen with your
173  * component, you should use ompi_modex_recv_nb() to receive updates
174  * when the information becomes available.
175  *
176  * @param[in] dest_component A pointer to this module's component struct
177  * @param[in] source_proc Peer process to receive from
178  * @param[out] buffer A pointer to a (void*) that will be filled
179  * with a pointer to the received buffer
180  * @param[out] size Pointer to a size_t that will be filled with
181  * the number of bytes in the buffer
182  *
183  * @retval OMPI_SUCCESS If a corresponding module buffer is found and
184  * successfully returned to the caller.
185  * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in
186  * this build of Open MPI (systems like the Cray XT)
187  * @retval OMPI_ERR_OUT_OF_RESOURCE No memory could be allocated for the
188  * buffer.
189  */
190 OMPI_DECLSPEC int ompi_modex_recv(mca_base_component_t *dest_component,
191  struct ompi_proc_t *source_proc,
192  void **buffer, size_t *size);
193 
194 
195 /**
196  * Receive a buffer from a given peer
197  *
198  * Similar to ompi_modex_recv(), but uses a char* key instead of a
199  * component name for indexing. All other semantics apply.
200  *
201  * @note If the modex system has received information from a given
202  * process, but has not yet received information for the given
203  * component, ompi_modex_recv_string() will return no data. This can
204  * not happen to a process that has gone through the normal startup
205  * proceedure, but if you believe this can happen with your component,
206  * you should use ompi_modex_recv_string_nb() to receive updates when
207  * the information becomes available.
208  *
209  * @param[in] key A unique key for data storage / lookup
210  * @param[in] source_proc Peer process to receive from
211  * @param[out] buffer A pointer to a (void*) that will be filled
212  * with a pointer to the received buffer
213  * @param[out] size Pointer to a size_t that will be filled with
214  * the number of bytes in the buffer
215  *
216  * @retval OMPI_SUCCESS If a corresponding module buffer is found and
217  * successfully returned to the caller.
218  * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in
219  * this build of Open MPI (systems like the Cray XT)
220  * @retval OMPI_ERR_OUT_OF_RESOURCE No memory could be allocated for the
221  * buffer.
222  */
223 OMPI_DECLSPEC int ompi_modex_recv_string(const char* key,
224  struct ompi_proc_t *source_proc,
225  void **buffer, size_t *size);
226 
227 /**
228  * Recv a value from a given peer
229  *
230  * Similar to ompi_modex_recv(), but uses a char* key instead of a
231  * component name for indexing, and performs all required conditioning
232  * to deal with heterogeneity.
233  *
234  * @param[in] key A unique key for data storage / lookup
235  * @param[in] source_proc Peer process to receive from
236  * @param[in] value A pointer to the address where the data
237  * value will be stored
238  * @param[in] dtype Data type of the value
239  *
240  * @retval OMPI_SUCCESS If a corresponding module value is found and
241  * successfully returned to the caller.
242  * @retval OMPI_ERR_NOT_IMPLEMENTED Modex support is not available in
243  * this build of Open MPI (systems like the Cray XT)
244  */
245 OMPI_DECLSPEC int ompi_modex_recv_key_value(const char* key,
246  struct ompi_proc_t *source_proc,
247  void *value,
248  opal_data_type_t dtype);
249 
250 
251 END_C_DECLS
252 
253 #endif /* MCA_OMPI_MODULE_EXCHANGE_H */
Common type for all MCA components.
Definition: mca.h:250
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.
Definition: ompi_module_exchange.c:113
Remote Open MPI process structure.
Definition: proc.h:56
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...
Definition: ompi_module_exchange.c:55
Top-level interface for all MCA components.
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.
Definition: ompi_module_exchange.c:38
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.
Definition: ompi_module_exchange.c:73
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.
Definition: ompi_module_exchange.c:81
Buffer management types.
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.
Definition: ompi_module_exchange.c:89