root/opal/util/info.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


DEFINITIONS

This source file includes following definitions.
  1. opal_info_get_nkeys

   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   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-2012 Cisco Systems, Inc.  All rights reserved.
  14  * Copyright (c) 2009      Sun Microsystems, Inc.  All rights reserved.
  15  * Copyright (c) 2012-2017 Los Alamos National Security, LLC. All rights
  16  *                         reserved.
  17  * Copyright (c) 2017-2018 IBM Corporation. All rights reserved.
  18  * $COPYRIGHT$
  19  *
  20  * Additional copyrights may follow
  21  *
  22  * $HEADER$
  23  */
  24 
  25 #ifndef OPAL_INFO_H
  26 #define OPAL_INFO_H
  27 
  28 #include <string.h>
  29 
  30 #include "opal/class/opal_list.h"
  31 #include "opal/class/opal_pointer_array.h"
  32 #include "opal/threads/mutex.h"
  33 #include "opal/mca/base/mca_base_var_enum.h"
  34 
  35 /**
  36  * \internal
  37  * opal_info_t structure. MPI_Info is a pointer to this structure
  38  */
  39 
  40 struct opal_info_t {
  41   opal_list_t   super;
  42   opal_mutex_t  *i_lock;
  43 };
  44 
  45 /**
  46  * \internal
  47  * Convenience typedef
  48  */
  49 typedef struct opal_info_t opal_info_t;
  50 
  51 
  52 /**
  53  * Table for Fortran <-> C translation table
  54  */
  55 extern opal_pointer_array_t ompi_info_f_to_c_table;
  56 
  57 
  58 /**
  59  * \internal
  60  *
  61  * opal_info_entry_t object. Each item in opal_info_list is of this
  62  * type. It contains (key,value) pairs
  63  */
  64 struct opal_info_entry_t {
  65     opal_list_item_t super; /**< required for opal_list_t type */
  66     char *ie_value; /**< value part of the (key, value) pair.
  67                   * Maximum length is MPI_MAX_INFO_VAL */
  68     char ie_key[OPAL_MAX_INFO_KEY + 1]; /**< "key" part of the (key, value)
  69                                      * pair */
  70 };
  71 /**
  72  * \internal
  73  * Convenience typedef
  74  */
  75 typedef struct opal_info_entry_t opal_info_entry_t;
  76 
  77 BEGIN_C_DECLS
  78 
  79 /**
  80  * \internal
  81  * Some declarations needed to use OBJ_NEW and OBJ_DESTRUCT macros
  82  */
  83 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_info_t);
  84 
  85 /**
  86  * \internal
  87  * Some declarations needed to use OBJ_NEW and OBJ_DESTRUCT macros
  88  */
  89 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_info_entry_t);
  90 
  91 
  92 int opal_mpiinfo_init(void*);
  93 
  94 /**
  95  *   opal_info_dup - Duplicate an 'MPI_Info' object
  96  *
  97  *   @param info source info object (handle)
  98  *   @param newinfo pointer to the new info object (handle)
  99  *
 100  *   @retval OPAL_SUCCESS upon success
 101  *   @retval OPAL_ERR_OUT_OF_RESOURCE if out of memory
 102  *
 103  *   Not only will the (key, value) pairs be duplicated, the order
 104  *   of keys will be the same in 'newinfo' as it is in 'info'.  When
 105  *   an info object is no longer being used, it should be freed with
 106  *   'MPI_Info_free'.
 107  */
 108 int opal_info_dup (opal_info_t *info, opal_info_t **newinfo);
 109 
 110 // Comments might still say __IN_<key>, but the code should be using the
 111 // below macro instead.
 112 #define OPAL_INFO_SAVE_PREFIX "_OMPI_IN_"
 113 
 114 /**
 115  *   opal_info_dup_mpistandard - Duplicate an 'MPI_Info' object
 116  *
 117  *   @param info source info object (handle)
 118  *   @param newinfo pointer to the new info object (handle)
 119  *
 120  *   @retval OPAL_SUCCESS upon success
 121  *   @retval OPAL_ERR_OUT_OF_RESOURCE if out of memory
 122  *
 123  *   The user sets an info object with key/value pairs and once processed,
 124  *   we keep key/val pairs that might have been modified vs what the user
 125  *   provided, and some user inputs might have been ignored too.  The original
 126  *   user inpust are kept as __IN_<key>/<val>.
 127  *
 128  *   This routine then outputs key/value pairs as:
 129  *
 130  *   if <key> and __IN_<key> both exist:
 131  *       This means the user set a k/v pair and it was used.
 132  *       output: <key> / value(__IN_<key>), the original user input
 133  *   if <key> exists but __IN_<key> doesn't:
 134  *       This is a system-provided setting.
 135  *       output: <key>/value(<key>)
 136  *   if __IN_<key> exists but <key> doesn't:
 137  *       The user provided a setting that was rejected (ignored) by the system
 138  *       output: nothing for this key
 139  */
 140 int opal_info_dup_mpistandard (opal_info_t *info, opal_info_t **newinfo);
 141 
 142 /**
 143  * Set a new key,value pair on info.
 144  *
 145  * @param info pointer to opal_info_t object
 146  * @param key pointer to the new key object
 147  * @param value pointer to the new value object
 148  *
 149  * @retval OPAL_SUCCESS upon success
 150  * @retval OPAL_ERR_OUT_OF_RESOURCE if out of memory
 151  */
 152 OPAL_DECLSPEC int opal_info_set (opal_info_t *info, const char *key, const char *value);
 153 
 154 /**
 155  * Set a new key,value pair from a variable enumerator.
 156  *
 157  * @param info pointer to opal_info_t object
 158  * @param key pointer to the new key object
 159  * @param value integer value of the info key (must be valid in var_enum)
 160  * @param var_enum variable enumerator
 161  *
 162  * @retval OPAL_SUCCESS upon success
 163  * @retval OPAL_ERR_OUT_OF_RESOURCE if out of memory
 164  * @retval OPAL_ERR_VALUE_OUT_OF_BOUNDS if the value is not valid in the enumerator
 165  */
 166 OPAL_DECLSPEC int opal_info_set_value_enum (opal_info_t *info, const char *key, int value,
 167                                             mca_base_var_enum_t *var_enum);
 168 
 169 /**
 170  * opal_info_free - Free an 'MPI_Info' object.
 171  *
 172  *   @param info pointer to info (opal_info_t *) object to be freed (handle)
 173  *
 174  *   @retval OPAL_SUCCESS
 175  *   @retval OPAL_ERR_BAD_PARAM
 176  *
 177  *   Upon successful completion, 'info' will be set to
 178  *   'MPI_INFO_NULL'.  Free the info handle and all of its keys and
 179  *   values.
 180  */
 181 int opal_info_free (opal_info_t **info);
 182 
 183   /**
 184    *   Get a (key, value) pair from an 'MPI_Info' object and assign it
 185    *   into a boolen output.
 186    *
 187    *   @param info Pointer to opal_info_t object
 188    *   @param key null-terminated character string of the index key
 189    *   @param value Boolean output value
 190    *   @param flag true (1) if 'key' defined on 'info', false (0) if not
 191    *               (logical)
 192    *
 193    *   @retval OPAL_SUCCESS
 194    *
 195    *   If found, the string value will be cast to the boolen output in
 196    *   the following manner:
 197    *
 198    *   - If the string value is digits, the return value is "(bool)
 199    *     atoi(value)"
 200    *   - If the string value is (case-insensitive) "yes" or "true", the
 201    *     result is true
 202    *   - If the string value is (case-insensitive) "no" or "false", the
 203    *     result is false
 204    *   - All other values are false
 205    */
 206 OPAL_DECLSPEC int opal_info_get_bool (opal_info_t *info, char *key, bool *value,
 207                                       int *flag);
 208 
 209 /**
 210  *   Get a (key, value) pair from an 'MPI_Info' object and assign it
 211  *   into an integer output based on the enumerator value.
 212  *
 213  *   @param info Pointer to opal_info_t object
 214  *   @param key null-terminated character string of the index key
 215  *   @param value integer output value
 216  *   @param default_value value to use if the string does not conform to the
 217  *          values accepted by the enumerator
 218  *   @param var_enum variable enumerator for the value
 219  *   @param flag true (1) if 'key' defined on 'info', false (0) if not
 220  *               (logical)
 221  *
 222  *   @retval OPAL_SUCCESS
 223  */
 224 
 225 OPAL_DECLSPEC int opal_info_get_value_enum (opal_info_t *info, const char *key,
 226                                             int *value, int default_value,
 227                                             mca_base_var_enum_t *var_enum, int *flag);
 228 
 229 /**
 230  *   Get a (key, value) pair from an 'MPI_Info' object
 231  *
 232  *   @param info Pointer to opal_info_t object
 233  *   @param key null-terminated character string of the index key
 234  *   @param valuelen maximum length of 'value' (integer)
 235  *   @param value null-terminated character string of the value
 236  *   @param flag true (1) if 'key' defined on 'info', false (0) if not
 237  *               (logical)
 238  *
 239  *   @retval OPAL_SUCCESS
 240  *
 241  *   In C and C++, 'valuelen' should be one less than the allocated
 242  *   space to allow for for the null terminator.
 243  */
 244 OPAL_DECLSPEC int opal_info_get (opal_info_t *info, const char *key, int valuelen,
 245                                  char *value, int *flag);
 246 
 247 /**
 248  * Delete a (key,value) pair from "info"
 249  *
 250  * @param info opal_info_t pointer on which we need to operate
 251  * @param key The key portion of the (key,value) pair that
 252  *            needs to be deleted
 253  *
 254  * @retval OPAL_SUCCESS
 255  * @retval OPAL_ERR_NOT_FOUND
 256  */
 257 int opal_info_delete(opal_info_t *info, const char *key);
 258 
 259 /**
 260  *   @param info - opal_info_t pointer object (handle)
 261  *   @param key - null-terminated character string of the index key
 262  *   @param valuelen - length of the value associated with 'key' (integer)
 263  *   @param flag - true (1) if 'key' defined on 'info', false (0) if not
 264  *   (logical)
 265  *
 266  *   @retval OPAL_SUCCESS
 267  *   @retval OPAL_ERR_BAD_PARAM
 268  *   @retval MPI_ERR_INFO_KEY
 269  *
 270  *   The length returned in C and C++ does not include the end-of-string
 271  *   character.  If the 'key' is not found on 'info', 'valuelen' is left
 272  *   alone.
 273  */
 274 OPAL_DECLSPEC int opal_info_get_valuelen (opal_info_t *info, const char *key, int *valuelen,
 275                                           int *flag);
 276 
 277 /**
 278  *   opal_info_get_nthkey - Get a key indexed by integer from an 'MPI_Info' o
 279  *
 280  *   @param info Pointer to opal_info_t object
 281  *   @param n index of key to retrieve (integer)
 282  *   @param key character string of at least 'MPI_MAX_INFO_KEY' characters
 283  *
 284  *   @retval OPAL_SUCCESS
 285  *   @retval OPAL_ERR_BAD_PARAM
 286  */
 287 int opal_info_get_nthkey (opal_info_t *info, int n, char *key);
 288 
 289 /**
 290  * Convert value string to boolean
 291  *
 292  * Convert value string \c value into a boolean, using the
 293  * interpretation rules specified in MPI-2 Section 4.10.  The
 294  * strings "true", "false", and integer numbers can be converted
 295  * into booleans.  All others will return \c OMPI_ERR_BAD_PARAM
 296  *
 297  * @param value Value string for info key to interpret
 298  * @param interp returned interpretation of the value key
 299  *
 300  * @retval OPAL_SUCCESS string was successfully interpreted
 301  * @retval OPAL_ERR_BAD_PARAM string was not able to be interpreted
 302  */
 303 OPAL_DECLSPEC int opal_info_value_to_bool(char *value, bool *interp);
 304 
 305 /**
 306  * Convert value string to integer
 307  *
 308  * Convert value string \c value into a integer, using the
 309  * interpretation rules specified in MPI-2 Section 4.10.
 310  * All others will return \c OPAL_ERR_BAD_PARAM
 311  *
 312  * @param value Value string for info key to interpret
 313  * @param interp returned interpretation of the value key
 314  *
 315  * @retval OPAL_SUCCESS string was successfully interpreted
 316  * @retval OPAL_ERR_BAD_PARAM string was not able to be interpreted
 317  */
 318 int opal_info_value_to_int(char *value, int *interp);
 319 
 320 END_C_DECLS
 321 
 322 /**
 323  * Get the number of keys defined on on an MPI_Info object
 324  * @param info Pointer to opal_info_t object.
 325  * @param nkeys Pointer to nkeys, which needs to be filled up.
 326  *
 327  * @retval The number of keys defined on info
 328  */
 329 static inline int
 330 opal_info_get_nkeys(opal_info_t *info, int *nkeys)
 331 {
 332     *nkeys = (int) opal_list_get_size(&(info->super));
 333     return OPAL_SUCCESS;
 334 }
 335 
 336 bool opal_str_to_bool(char*);
 337 
 338 #endif /* OPAL_INFO_H */

/* [<][>][^][v][top][bottom][index][help] */