OpenMPI 0.1.1

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

- File List
- Globals

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 */
mca_base_component_2_0_0_t
Common type for all MCA components.
Definition: mca.h:250
ompi_modex_recv_key_value
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
ompi_proc_t
Remote Open MPI process structure.
Definition: proc.h:56
ompi_modex_recv
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
mca.h
Top-level interface for all MCA components.
ompi_modex_send
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_modex_send_string
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_modex_recv_string
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
dss_types.h
Buffer management types.
ompi_modex_send_key_value
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