OpenMPI 0.1.1

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

- File List
- Globals

info.h
1 /* -*- Mode: C; c-basic-offset:4 ; -*- */
2 /*
3 * Copyright (c) 2004-2010 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2007 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2007 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
15 * $COPYRIGHT$
16 *
17 * Additional copyrights may follow
18 *
19 * $HEADER$
20 */
21
22 #ifndef OMPI_INFO_H
23 #define OMPI_INFO_H
24
25 #include "ompi_config.h"
26 #include <string.h>
27
28 #include "mpi.h"
29 #include "opal/class/opal_list.h"
30 #include "opal/class/opal_pointer_array.h"
31 #include "opal/threads/mutex.h"
32
33
34 /**
35 * \internal
36 * ompi_info_t structure. MPI_Info is a pointer to this structure
37 */
38 struct ompi_info_t {
39 opal_list_t super;
40 /**< generic list pointer which is the container for (key,value)
41 pairs */
42 int i_f_to_c_index;
43 /**< fortran handle for info. This is needed for translation from
44 fortran to C and vice versa */
45 opal_mutex_t *i_lock;
46 /**< Mutex for thread safety */
47 bool i_freed;
48 /**< Whether this info has been freed or not */
49 };
50 /**
51 * \internal
52 * Convenience typedef
53 */
54 typedef struct ompi_info_t ompi_info_t;
55
56 /**
57 * Padded struct to maintain back compatibiltiy.
58 * See ompi/communicator/communicator.h comments with struct ompi_communicator_t
59 * for full explanation why we chose the following padding construct for predefines.
60 */
61 #define PREDEFINED_INFO_PAD (sizeof(void*) * 32)
62
63 struct ompi_predefined_info_t {
64 struct ompi_info_t info;
65 char padding[PREDEFINED_INFO_PAD - sizeof(ompi_info_t)];
66 };
67 typedef struct ompi_predefined_info_t ompi_predefined_info_t;
68
69
70 /**
71 * \internal
72 *
73 * ompi_info_entry_t object. Each item in ompi_info_list is of this
74 * type. It contains (key,value) pairs
75 */
76 struct ompi_info_entry_t {
77 opal_list_item_t super; /**< required for opal_list_t type */
78 char *ie_value; /**< value part of the (key, value) pair.
79 * Maximum length is MPI_MAX_INFO_VAL */
80 char ie_key[MPI_MAX_INFO_KEY + 1]; /**< "key" part of the (key, value)
81 * pair */
82 };
83 /**
84 * \internal
85 * Convenience typedef
86 */
87 typedef struct ompi_info_entry_t ompi_info_entry_t;
88
89 BEGIN_C_DECLS
90
91 /**
92 * Table for Fortran <-> C translation table
93 */
94 extern opal_pointer_array_t ompi_info_f_to_c_table;
95
96 /**
97 * Global instance for MPI_INFO_NULL
98 */
99 OMPI_DECLSPEC extern ompi_predefined_info_t ompi_mpi_info_null;
100
101 /**
102 * \internal
103 * Some declarations needed to use OBJ_NEW and OBJ_DESTRUCT macros
104 */
105 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(ompi_info_t);
106
107 /**
108 * \internal
109 * Some declarations needed to use OBJ_NEW and OBJ_DESTRUCT macros
110 */
111 OMPI_DECLSPEC OBJ_CLASS_DECLARATION(ompi_info_entry_t);
112
113 /**
114 * This function is invoked during ompi_mpi_init() and sets up
115 * MPI_Info handling.
116 */
117 int ompi_info_init(void);
118
119 /**
120 * This functions is called during ompi_mpi_finalize() and shuts
121 * down MPI_Info handling.
122 */
123 int ompi_info_finalize(void);
124
125 /**
126 * ompi_info_dup - Duplicate an 'MPI_Info' object
127 *
128 * @param info source info object (handle)
129 * @param newinfo pointer to the new info object (handle)
130 *
131 * @retval MPI_SUCCESS upon success
132 * @retval MPI_ERR_NO_MEM if out of memory
133 *
134 * Not only will the (key, value) pairs be duplicated, the order
135 * of keys will be the same in 'newinfo' as it is in 'info'. When
136 * an info object is no longer being used, it should be freed with
137 * 'MPI_Info_free'.
138 */
139 int ompi_info_dup (ompi_info_t *info, ompi_info_t **newinfo);
140
141 /*
142 * Set a new key,value pair on info.
143 *
144 * @param info pointer to ompi_info_t object
145 * @param key pointer to the new key object
146 * @param value pointer to the new value object
147 *
148 * @retval MPI_SUCCESS upon success
149 * @retval MPI_ERR_NO_MEM if out of memory
150 */
151 OMPI_DECLSPEC int ompi_info_set (ompi_info_t *info, char *key, char *value);
152
153 /**
154 * ompi_info_free - Free an 'MPI_Info' object.
155 *
156 * @param info pointer to info (ompi_info_t *) object to be freed (handle)
157 *
158 * @retval MPI_SUCCESS
159 * @retval MPI_ERR_ARG
160 *
161 * Upon successful completion, 'info' will be set to
162 * 'MPI_INFO_NULL'. Free the info handle and all of its keys and
163 * values.
164 */
165 int ompi_info_free (ompi_info_t **info);
166
167 /**
168 * Get a (key, value) pair from an 'MPI_Info' object and assign it
169 * into a boolen output.
170 *
171 * @param info Pointer to ompi_info_t object
172 * @param key null-terminated character string of the index key
173 * @param value Boolean output value
174 * @param flag true (1) if 'key' defined on 'info', false (0) if not
175 * (logical)
176 *
177 * @retval MPI_SUCCESS
178 *
179 * If found, the string value will be cast to the boolen output in
180 * the following manner:
181 *
182 * - If the string value is digits, the return value is "(bool)
183 * atoi(value)"
184 * - If the string value is (case-insensitive) "yes" or "true", the
185 * result is true
186 * - If the string value is (case-insensitive) "no" or "false", the
187 * result is false
188 * - All other values are false
189 */
190 OMPI_DECLSPEC int ompi_info_get_bool (ompi_info_t *info, char *key, bool *value,
191 int *flag);
192
193 /**
194 * Get a (key, value) pair from an 'MPI_Info' object
195 *
196 * @param info Pointer to ompi_info_t object
197 * @param key null-terminated character string of the index key
198 * @param valuelen maximum length of 'value' (integer)
199 * @param value null-terminated character string of the value
200 * @param flag true (1) if 'key' defined on 'info', false (0) if not
201 * (logical)
202 *
203 * @retval MPI_SUCCESS
204 *
205 * In C and C++, 'valuelen' should be one less than the allocated
206 * space to allow for for the null terminator.
207 */
208 OMPI_DECLSPEC int ompi_info_get (ompi_info_t *info, char *key, int valuelen,
209 char *value, int *flag);
210
211 /**
212 * Delete a (key,value) pair from "info"
213 *
214 * @param info ompi_info_t pointer on which we need to operate
215 * @param key The key portion of the (key,value) pair that
216 * needs to be deleted
217 *
218 * @retval MPI_SUCCESS
219 * @retval MPI_ERR_NOKEY
220 */
221 int ompi_info_delete (ompi_info_t *info, char *key);
222
223 /**
224 * @param info - ompi_info_t pointer object (handle)
225 * @param key - null-terminated character string of the index key
226 * @param valuelen - length of the value associated with 'key' (integer)
227 * @param flag - true (1) if 'key' defined on 'info', false (0) if not
228 * (logical)
229 *
230 * @retval MPI_SUCCESS
231 * @retval MPI_ERR_ARG
232 * @retval MPI_ERR_INFO_KEY
233 *
234 * The length returned in C and C++ does not include the end-of-string
235 * character. If the 'key' is not found on 'info', 'valuelen' is left
236 * alone.
237 */
238 OMPI_DECLSPEC int ompi_info_get_valuelen (ompi_info_t *info, char *key, int *valuelen,
239 int *flag);
240
241 /**
242 * ompi_info_get_nthkey - Get a key indexed by integer from an 'MPI_Info' o
243 *
244 * @param info Pointer to ompi_info_t object
245 * @param n index of key to retrieve (integer)
246 * @param key character string of at least 'MPI_MAX_INFO_KEY' characters
247 *
248 * @retval MPI_SUCCESS
249 * @retval MPI_ERR_ARG
250 */
251 int ompi_info_get_nthkey (ompi_info_t *info, int n, char *key);
252
253 /**
254 * Convert value string to boolean
255 *
256 * Convert value string \c value into a boolean, using the
257 * interpretation rules specified in MPI-2 Section 4.10. The
258 * strings "true", "false", and integer numbers can be converted
259 * into booleans. All others will return \c OMPI_ERR_BAD_PARAM
260 *
261 * @param value Value string for info key to interpret
262 * @param interp returned interpretation of the value key
263 *
264 * @retval OMPI_SUCCESS string was successfully interpreted
265 * @retval OMPI_ERR_BAD_PARAM string was not able to be interpreted
266 */
267 OMPI_DECLSPEC int ompi_info_value_to_bool(char *value, bool *interp);
268
269 /**
270 * Convert value string to integer
271 *
272 * Convert value string \c value into a integer, using the
273 * interpretation rules specified in MPI-2 Section 4.10.
274 * All others will return \c OMPI_ERR_BAD_PARAM
275 *
276 * @param value Value string for info key to interpret
277 * @param interp returned interpretation of the value key
278 *
279 * @retval OMPI_SUCCESS string was successfully interpreted
280 * @retval OMPI_ERR_BAD_PARAM string was not able to be interpreted
281 */
282 int ompi_info_value_to_int(char *value, int *interp);
283
284 END_C_DECLS
285
286 /**
287 * Return whether this info has been freed already or not.
288 *
289 * @param info Pointer to ompi_info_t object.
290 *
291 * @retval true If the info has already been freed
292 * @retval false If the info has not yet been freed
293 *
294 * If the info has been freed, return true. This will likely only
295 * happen in a reliable manner if ompi_debug_handle_never_free is
296 * true, in which case an extra OBJ_RETAIN is set on the object during
297 * OBJ_NEW, meaning that the user will never be able to actually free
298 * the underlying object. It's a good way to find out if a process is
299 * unintentionally using a freed handle.
300 */
301 static inline bool ompi_info_is_freed(ompi_info_t *info)
302 {
303 return info->i_freed;
304 }
305
306
307 /**
308 * Get the number of keys defined on on an MPI_Info object
309 * @param info Pointer to ompi_info_t object.
310 * @param nkeys Pointer to nkeys, which needs to be filled up.
311 *
312 * @retval The number of keys defined on info
313 */
314 static inline int
315 ompi_info_get_nkeys(ompi_info_t *info, int *nkeys)
316 {
317 *nkeys = (int) opal_list_get_size(&(info->super));
318 return MPI_SUCCESS;
319 }
320
321 #endif /* OMPI_INFO_H */
ompi_info_entry_t::super
opal_list_item_t super
required for opal_list_t type
Definition: info.h:77
opal_pointer_array_t
dynamic pointer array
Definition: opal_pointer_array.h:45
ompi_info_t::i_freed
bool i_freed
Whether this info has been freed or not.
Definition: info.h:47
opal_list_get_size
static size_t opal_list_get_size(opal_list_t *list)
Return the number of items in a list.
Definition: opal_list.h:299
opal_mutex_t
Definition: mutex_unix.h:53
opal_list.h
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
opal_pointer_array.h
See opal_bitmap.h for an explanation of why there is a split between OPAL and ORTE for this generic c...
ompi_info_entry_t::ie_key
char ie_key[MPI_MAX_INFO_KEY+1]
"key" part of the (key, value) pair
Definition: info.h:80
ompi_info_t::i_f_to_c_index
int i_f_to_c_index
fortran handle for info.
Definition: info.h:42
opal_list_item_t
Definition: opal_list.h:98
ompi_info_t
Definition: info.h:38
ompi_info_t::i_lock
opal_mutex_t * i_lock
Mutex for thread safety.
Definition: info.h:45
ompi_info_entry_t
Definition: info.h:76
ompi_info_t::super
opal_list_t super
generic list pointer which is the container for (key,value) pairs
Definition: info.h:39
ompi_info_entry_t::ie_value
char * ie_value
value part of the (key, value) pair.
Definition: info.h:78
opal_list_t
Definition: opal_list.h:147
mutex.h
Mutual exclusion functions.
ompi_predefined_info_t
Definition: info.h:63
OBJ_CLASS_DECLARATION
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236