OpenMPI  0.1.1
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"
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 {
40  /**< generic list pointer which is the container for (key,value)
41  pairs */
43  /**< fortran handle for info. This is needed for translation from
44  fortran to C and vice versa */
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 
64  struct ompi_info_t info;
65  char padding[PREDEFINED_INFO_PAD - sizeof(ompi_info_t)];
66 };
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  */
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  */
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  */
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 */
opal_list_item_t super
required for opal_list_t type
Definition: info.h:77
dynamic pointer array
Definition: opal_pointer_array.h:45
bool i_freed
Whether this info has been freed or not.
Definition: info.h:47
static size_t opal_list_get_size(opal_list_t *list)
Return the number of items in a list.
Definition: opal_list.h:299
Definition: mutex_unix.h:53
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
See opal_bitmap.h for an explanation of why there is a split between OPAL and ORTE for this generic c...
char ie_key[MPI_MAX_INFO_KEY+1]
"key" part of the (key, value) pair
Definition: info.h:80
int i_f_to_c_index
fortran handle for info.
Definition: info.h:42
Definition: opal_list.h:98
Definition: info.h:38
opal_mutex_t * i_lock
Mutex for thread safety.
Definition: info.h:45
Definition: info.h:76
opal_list_t super
generic list pointer which is the container for (key,value) pairs
Definition: info.h:39
char * ie_value
value part of the (key, value) pair.
Definition: info.h:78
Definition: opal_list.h:147
Mutual exclusion functions.
Definition: info.h:63
#define OBJ_CLASS_DECLARATION(NAME)
Declaration for class descriptor.
Definition: opal_object.h:236