1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2006 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) 2008-2011 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2012-2018 Los Alamos National Security, LLC. All rights
15 * reserved.
16 * Copyright (c) 2016 Intel, Inc. All rights reserved.
17 * Copyright (c) 2017 IBM Corporation. All rights reserved.
18 * Copyright (c) 2018 Triad National Security, LLC. All rights
19 * reserved.
20 * $COPYRIGHT$
21 *
22 * Additional copyrights may follow
23 *
24 * $HEADER$
25 */
26
27 /** @file
28 * This file presents the MCA variable interface.
29 *
30 * Note that there are two scopes for MCA variables: "normal" and
31 * attributes. Specifically, all MCA variables are "normal" -- some
32 * are special and may also be found on attributes on communicators,
33 * datatypes, or windows.
34 *
35 * In general, these functions are intended to be used as follows:
36 *
37 * - Creating MCA variables
38 * -# Register a variable, get an index back
39 * - Using MCA variables
40 * -# Lookup a "normal" variable value on a specific index, or
41 * -# Lookup an attribute variable on a specific index and
42 * communicator / datatype / window.
43 *
44 * MCA variables can be defined in multiple different places. As
45 * such, variables are \em resolved to find their value. The order
46 * of resolution is as follows:
47 *
48 * - An "override" location that is only available to be set via the
49 * mca_base_param API.
50 * - Look for an environment variable corresponding to the MCA
51 * variable.
52 * - See if a file contains the MCA variable (MCA variable files are
53 * read only once -- when the first time any mca_param_t function is
54 * invoked).
55 * - If nothing else was found, use the variable's default value.
56 *
57 * Note that there is a second header file (mca_base_vari.h)
58 * that contains several internal type delcarations for the variable
59 * system. The internal file is only used within the variable system
60 * itself; it should not be required by any other Open MPI entities.
61 */
62
63 #ifndef OPAL_MCA_BASE_VAR_H
64 #define OPAL_MCA_BASE_VAR_H
65
66 #include "opal_config.h"
67
68 #include "opal/class/opal_list.h"
69 #include "opal/class/opal_value_array.h"
70 #include "opal/mca/base/mca_base_var_enum.h"
71 #include "opal/mca/base/mca_base_var_group.h"
72 #include "opal/mca/base/mca_base_framework.h"
73 #include "opal/mca/mca.h"
74
75 /**
76 * The types of MCA variables.
77 */
78 typedef enum {
79 /** The variable is of type int. */
80 MCA_BASE_VAR_TYPE_INT,
81 /** The variable is of type unsigned int */
82 MCA_BASE_VAR_TYPE_UNSIGNED_INT,
83 /** The variable is of type unsigned long */
84 MCA_BASE_VAR_TYPE_UNSIGNED_LONG,
85 /** The variable is of type unsigned long long */
86 MCA_BASE_VAR_TYPE_UNSIGNED_LONG_LONG,
87 /** The variable is of type size_t */
88 MCA_BASE_VAR_TYPE_SIZE_T,
89 /** The variable is of type string. */
90 MCA_BASE_VAR_TYPE_STRING,
91 /** The variable is of type string and contains version. */
92 MCA_BASE_VAR_TYPE_VERSION_STRING,
93 /** The variable is of type bool */
94 MCA_BASE_VAR_TYPE_BOOL,
95 /** The variable is of type double */
96 MCA_BASE_VAR_TYPE_DOUBLE,
97 /** The variable is of type long int */
98 MCA_BASE_VAR_TYPE_LONG,
99 /** The variable is of type int32_t */
100 MCA_BASE_VAR_TYPE_INT32_T,
101 /** The variable is of type uint32_t */
102 MCA_BASE_VAR_TYPE_UINT32_T,
103 /** The variable is of type int64_t */
104 MCA_BASE_VAR_TYPE_INT64_T,
105 /** The variable is of type uint64_t */
106 MCA_BASE_VAR_TYPE_UINT64_T,
107
108 /** Maximum variable type. */
109 MCA_BASE_VAR_TYPE_MAX
110 } mca_base_var_type_t;
111
112 extern const char *ompi_var_type_names[];
113
114 /**
115 * Source of an MCA variable's value
116 */
117 typedef enum {
118 /** The default value */
119 MCA_BASE_VAR_SOURCE_DEFAULT,
120 /** The value came from the command line */
121 MCA_BASE_VAR_SOURCE_COMMAND_LINE,
122 /** The value came from the environment */
123 MCA_BASE_VAR_SOURCE_ENV,
124 /** The value came from a file */
125 MCA_BASE_VAR_SOURCE_FILE,
126 /** The value came a "set" API call */
127 MCA_BASE_VAR_SOURCE_SET,
128 /** The value came from the override file */
129 MCA_BASE_VAR_SOURCE_OVERRIDE,
130
131 /** Maximum source type */
132 MCA_BASE_VAR_SOURCE_MAX
133 } mca_base_var_source_t;
134
135 /**
136 * MCA variable scopes
137 *
138 * Equivalent to MPI_T scopes with the same base name (e.g.,
139 * MCA_BASE_VAR_SCOPE_CONSTANT corresponts to MPI_T_SCOPE_CONSTANT).
140 */
141 typedef enum {
142 /** The value of this variable will not change after it is
143 registered. This flag is incompatible with
144 MCA_BASE_VAR_FLAG_SETTABLE, and also implies
145 MCA_BASE_VAR_SCOPE_READONLY. */
146 MCA_BASE_VAR_SCOPE_CONSTANT,
147 /** Setting the READONLY flag means that the mca_base_var_set()
148 function cannot be used to set the value of this variable
149 (e.g., the MPI_T_cvar_write() MPI_T function). */
150 MCA_BASE_VAR_SCOPE_READONLY,
151 /** The value of this variable may be changed locally. */
152 MCA_BASE_VAR_SCOPE_LOCAL,
153 /** The value of this variable must be set to a consistent value
154 within a group */
155 MCA_BASE_VAR_SCOPE_GROUP,
156 /** The value of this variable must be set to the same value
157 within a group */
158 MCA_BASE_VAR_SCOPE_GROUP_EQ,
159 /** The value of this variable must be set to a consistent value
160 for all processes */
161 MCA_BASE_VAR_SCOPE_ALL,
162 /** The value of this variable must be set to the same value
163 for all processes */
164 MCA_BASE_VAR_SCOPE_ALL_EQ,
165 MCA_BASE_VAR_SCOPE_MAX
166 } mca_base_var_scope_t;
167
168 typedef enum {
169 OPAL_INFO_LVL_1,
170 OPAL_INFO_LVL_2,
171 OPAL_INFO_LVL_3,
172 OPAL_INFO_LVL_4,
173 OPAL_INFO_LVL_5,
174 OPAL_INFO_LVL_6,
175 OPAL_INFO_LVL_7,
176 OPAL_INFO_LVL_8,
177 OPAL_INFO_LVL_9,
178 OPAL_INFO_LVL_MAX
179 } mca_base_var_info_lvl_t;
180
181 typedef enum {
182 MCA_BASE_VAR_SYN_FLAG_DEPRECATED = 0x0001,
183 MCA_BASE_VAR_SYN_FLAG_INTERNAL = 0x0002
184 } mca_base_var_syn_flag_t;
185
186 typedef enum {
187 /** Variable is internal (hidden from *_info/MPIT) */
188 MCA_BASE_VAR_FLAG_INTERNAL = 0x0001,
189 /** Variable will always be the default value. Implies
190 !MCA_BASE_VAR_FLAG_SETTABLE */
191 MCA_BASE_VAR_FLAG_DEFAULT_ONLY = 0x0002,
192 /** Variable can be set with mca_base_var_set() */
193 MCA_BASE_VAR_FLAG_SETTABLE = 0x0004,
194 /** Variable is deprecated */
195 MCA_BASE_VAR_FLAG_DEPRECATED = 0x0008,
196 /** Variable has been overridden */
197 MCA_BASE_VAR_FLAG_OVERRIDE = 0x0010,
198 /** Variable may not be set from a file */
199 MCA_BASE_VAR_FLAG_ENVIRONMENT_ONLY = 0x0020,
200 /** Variable should be deregistered when the group is deregistered
201 (DWG = "deregister with group"). This flag is set
202 automatically when you register a variable with
203 mca_base_component_var_register(), but can also be set
204 manually when you register a variable with
205 mca_base_var_register(). Analogous to the
206 MCA_BASE_PVAR_FLAG_IWG. */
207 MCA_BASE_VAR_FLAG_DWG = 0x0040,
208 /** Variable has a default value of "unset". Meaning to only
209 * be set when the user explicitly asks for it */
210 MCA_BASE_VAR_FLAG_DEF_UNSET = 0x0080,
211 } mca_base_var_flag_t;
212
213
214 /**
215 * Types for MCA parameters.
216 */
217 typedef union {
218 /** integer value */
219 int intval;
220 /** int32_t value */
221 int32_t int32tval;
222 /** long value */
223 long longval;
224 /** int64_t value */
225 int64_t int64tval;
226 /** unsigned int value */
227 unsigned int uintval;
228 /** uint32_t value */
229 uint32_t uint32tval;
230 /** string value */
231 char *stringval;
232 /** boolean value */
233 bool boolval;
234 /** unsigned long value */
235 unsigned long ulval;
236 /** uint64_t value */
237 uint64_t uint64tval;
238 /** unsigned long long value */
239 unsigned long long ullval;
240 /** size_t value */
241 size_t sizetval;
242 /** double value */
243 double lfval;
244 } mca_base_var_storage_t;
245
246
247 /**
248 * Entry for holding information about an MCA variable.
249 */
250 struct mca_base_var_t {
251 /** Allow this to be an OPAL OBJ */
252 opal_object_t super;
253
254 /** Variable index. This will remain constant until mca_base_var_finalize()
255 is called. */
256 int mbv_index;
257 /** Group index. This will remain constant until mca_base_var_finalize()
258 is called. This variable will be deregistered if the associated group
259 is deregistered with mca_base_var_group_deregister() */
260 int mbv_group_index;
261
262 /** Info level of this variable */
263 mca_base_var_info_lvl_t mbv_info_lvl;
264
265 /** Enum indicating the type of the variable (integer, string, boolean) */
266 mca_base_var_type_t mbv_type;
267
268 /** String of the variable name */
269 char *mbv_variable_name;
270 /** Full variable name, in case it is not <framework>_<component>_<param> */
271 char *mbv_full_name;
272 /** Long variable name <project>_<framework>_<component>_<name> */
273 char *mbv_long_name;
274
275 /** List of synonym names for this variable. This *must* be a
276 pointer (vs. a plain opal_list_t) because we copy this whole
277 struct into a new var for permanent storage
278 (opal_vale_array_append_item()), and the internal pointers in
279 the opal_list_t will be invalid when that happens. Hence, we
280 simply keep a pointer to an external opal_list_t. Synonyms
281 are uncommon enough that this is not a big performance hit. */
282 opal_value_array_t mbv_synonyms;
283
284 /** Variable flags */
285 mca_base_var_flag_t mbv_flags;
286
287 /** Variable scope */
288 mca_base_var_scope_t mbv_scope;
289
290 /** Source of the current value */
291 mca_base_var_source_t mbv_source;
292
293 /** Synonym for */
294 int mbv_synonym_for;
295
296 /** Variable description */
297 char *mbv_description;
298
299 /** File the value came from */
300 char *mbv_source_file;
301
302 /** Value enumerator (only valid for integer variables) */
303 mca_base_var_enum_t *mbv_enumerator;
304
305 /** Bind value for this variable (0 - none) */
306 int mbv_bind;
307
308 /** Storage for this variable */
309 mca_base_var_storage_t *mbv_storage;
310
311 /** File value structure */
312 void *mbv_file_value;
313 };
314 /**
315 * Convenience typedef.
316 */
317 typedef struct mca_base_var_t mca_base_var_t;
318
319 /*
320 * Global functions for MCA
321 */
322
323 BEGIN_C_DECLS
324
325 /**
326 * Object declarayion for mca_base_var_t
327 */
328 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_var_t);
329
330 /**
331 * Initialize the MCA variable system.
332 *
333 * @retval OPAL_SUCCESS
334 *
335 * This function initalizes the MCA variable system. It is
336 * invoked internally (by mca_base_open()) and is only documented
337 * here for completeness.
338 */
339 OPAL_DECLSPEC int mca_base_var_init(void);
340
341 /**
342 * Register an MCA variable
343 *
344 * @param[in] project_name The name of the project associated with
345 * this variable
346 * @param[in] framework_name The name of the framework associated with
347 * this variable
348 * @param[in] component_name The name of the component associated with
349 * this variable
350 * @param[in] variable_name The name of this variable
351 * @param[in] description A string describing the use and valid
352 * values of the variable (string).
353 * @param[in] type The type of this variable (string, int, bool).
354 * @param[in] enumerator Enumerator describing valid values.
355 * @param[in] bind Hint for MPIT to specify type of binding (0 = none)
356 * @param[in] flags Flags for this variable.
357 * @param[in] info_lvl Info level of this variable
358 * @param[in] scope Indicates the scope of this variable
359 * @param[in,out] storage Pointer to the value's location.
360 *
361 * @retval index Index value representing this variable.
362 * @retval OPAL_ERR_OUT_OF_RESOURCE Upon failure to allocate memory.
363 * @retval OPAL_ERROR Upon failure to register the variable.
364 *
365 * This function registers an MCA variable and associates it
366 * with a specific group.
367 *
368 * {description} is a string of arbitrary length (verbose is good!)
369 * for explaining what the variable is for and what its valid values
370 * are. This message is used in help messages, such as the output
371 * from the ompi_info executable. The {description} string is copied
372 * internally; the caller can free {description} upon successful
373 * return.
374 *
375 * {enumerator} is either NULL or a handle that was created via
376 * mca_base_var_enum_create(), and describes the valid values of an
377 * integer variable (i.e., one with type MCA_BASE_VAR_TYPE_INT). When
378 * a non-NULL {enumerator} is used, the value set for this variable by
379 * the user will be compared against the values in the enumerator.
380 * The MCA variable system will allow the parameter to be set to
381 * either one of the enumerator values (0, 1, 2, etc) or a string
382 * representing one of those values. {enumerator} is retained until
383 * either the variable is deregistered using
384 * mca_base_var_deregister(), mca_base_var_group_deregister(), or
385 * mca_base_var_finalize(). {enumerator} should be NULL for
386 * parameters that do not support enumerated values.
387 *
388 * {flags} indicate attributes of this variable (internal, settable,
389 * default only, etc.), as listed below.
390 *
391 * If MCA_BASE_VAR_FLAG_SETTABLE is set in {flags}, this variable may
392 * be set using mca_base_var_set_value() (i.e., the MPI_T interface).
393 *
394 * If MCA_BASE_VAR_FLAG_INTERNAL is set in {flags}, this variable
395 * is not shown by default in the output of ompi_info. That is,
396 * this variable is considered internal to the Open MPI implementation
397 * and is not supposed to be viewed / changed by the user.
398 *
399 * If MCA_BASE_VAR_FLAG_DEFAULT_ONLY is set in {flags}, then the value
400 * provided in storage will not be modified by the MCA variable system
401 * (i.e., users cannot set the value of this variable via CLI
402 * parameter, environment variable, file, etc.). It is up to the
403 * caller to specify (using the scope) if this value may change
404 * (MCA_BASE_VAR_SCOPE_READONLY) or remain constant
405 * (MCA_BASE_VAR_SCOPE_CONSTANT). MCA_BASE_VAR_FLAG_DEFAULT_ONLY must
406 * not be specified with MCA_BASE_VAR_FLAG_SETTABLE.
407 *
408 * Set MCA_BASE_VAR_FLAG_DEPRECATED in {flags} to indicate that
409 * this variable name is deprecated. The user will get a warning
410 * if they set this variable.
411 *
412 * {scope} is for informational purposes to indicate how this variable
413 * can be set, or if it is considered constant or readonly (which, by
414 * MPI_T's definitions, are different things). See the comments in
415 * the description of mca_base_var_scope_t for information about the
416 * different scope meanings.
417 *
418 * {storage} points to a (char *), (int), or (bool) where the value of
419 * this variable is stored ({type} indicates the type of this
420 * pointer). The location pointed to by {storage} must exist until
421 * the variable is deregistered. Note that the initial value in
422 * {storage} may be overwritten if the MCA_BASE_VAR_FLAG_DEFAULT_ONLY
423 * flag is not set (e.g., if the user sets this variable via CLI
424 * option, environment variable, or file value). If input value of
425 * {storage} points to a (char *), the pointed-to string will be
426 * duplicated and maintained internally by the MCA variable system;
427 * the caller may free the original string after this function returns
428 * successfully.
429 */
430 OPAL_DECLSPEC int mca_base_var_register (const char *project_name, const char *framework_name,
431 const char *component_name, const char *variable_name,
432 const char *description, mca_base_var_type_t type,
433 mca_base_var_enum_t *enumerator, int bind, mca_base_var_flag_t flags,
434 mca_base_var_info_lvl_t info_lvl,
435 mca_base_var_scope_t scope, void *storage);
436
437 /**
438 * Convenience function for registering a variable associated with a
439 * component.
440 *
441 * While quite similar to mca_base_var_register(), there is one key
442 * difference: vars registered this this function will automatically
443 * be unregistered / made unavailable when that component is closed by
444 * its framework.
445 */
446 OPAL_DECLSPEC int mca_base_component_var_register (const mca_base_component_t *component,
447 const char *variable_name, const char *description,
448 mca_base_var_type_t type, mca_base_var_enum_t *enumerator,
449 int bind, mca_base_var_flag_t flags,
450 mca_base_var_info_lvl_t info_lvl,
451 mca_base_var_scope_t scope, void *storage);
452
453 /**
454 * Convenience function for registering a variable associated with a framework. This
455 * function is equivalent to mca_base_var_register with component_name = "base" and
456 * with the MCA_BASE_VAR_FLAG_DWG set. See mca_base_var_register().
457 */
458 OPAL_DECLSPEC int mca_base_framework_var_register (const mca_base_framework_t *framework,
459 const char *variable_name,
460 const char *help_msg, mca_base_var_type_t type,
461 mca_base_var_enum_t *enumerator, int bind,
462 mca_base_var_flag_t flags,
463 mca_base_var_info_lvl_t info_level,
464 mca_base_var_scope_t scope, void *storage);
465
466 /**
467 * Register a synonym name for an MCA variable.
468 *
469 * @param[in] synonym_for The index of the original variable. This index
470 * must not refer to a synonym.
471 * @param[in] project_name The project this synonym belongs to. Should
472 * not be NULL (except for legacy reasons).
473 * @param[in] framework_name The framework this synonym belongs to.
474 * @param[in] component_name The component this synonym belongs to.
475 * @param[in] synonym_name The synonym name.
476 * @param[in] flags Flags for this synonym.
477 *
478 * @returns index Variable index for new synonym on success.
479 * @returns OPAL_ERR_BAD_VAR If synonym_for does not reference a valid
480 * variable.
481 * @returns OPAL_ERR_OUT_OF_RESOURCE If memory could not be allocated.
482 * @returns OPAL_ERROR For all other errors.
483 *
484 * Upon success, this function creates a synonym MCA variable
485 * that will be treated almost exactly like the original. The
486 * type (int or string) is irrelevant; this function simply
487 * creates a new name that by which the same variable value is
488 * accessible.
489 *
490 * Note that the original variable name has precendence over all
491 * synonyms. For example, consider the case if variable is
492 * originally registered under the name "A" and is later
493 * registered with synonyms "B" and "C". If the user sets values
494 * for both MCA variable names "A" and "B", the value associated
495 * with the "A" name will be used and the value associated with
496 * the "B" will be ignored (and will not even be visible by the
497 * mca_base_var_*() API). If the user sets values for both MCA
498 * variable names "B" and "C" (and does *not* set a value for
499 * "A"), it is undefined as to which value will be used.
500 */
501 OPAL_DECLSPEC int mca_base_var_register_synonym (int synonym_for, const char *project_name,
502 const char *framework_name,
503 const char *component_name,
504 const char *synonym_name,
505 mca_base_var_syn_flag_t flags);
506
507 /**
508 * Deregister a MCA variable or synonym
509 *
510 * @param vari Index returned from mca_base_var_register() or
511 * mca_base_var_register_synonym().
512 *
513 * Deregistering a variable does not free the variable or any memory assoicated
514 * with it. All memory will be freed and the variable index released when
515 * mca_base_var_finalize() is called.
516 *
517 * If an enumerator is associated with this variable it will be dereferenced.
518 */
519 OPAL_DECLSPEC int mca_base_var_deregister(int vari);
520
521
522 /**
523 * Get the current value of an MCA variable.
524 *
525 * @param[in] vari Index of variable
526 * @param[in,out] value Pointer to copy the value to. Can be NULL.
527 * @param[out] source Source of current value. Can be NULL.
528 * @param[out] source_file Source file for the current value if
529 * it was set from a file.
530 *
531 * @return OPAL_ERROR Upon failure. The contents of value are
532 * undefined.
533 * @return OPAL_SUCCESS Upon success. value (if not NULL) will be filled
534 * with the variable's current value. value_size will contain the size
535 * copied. source (if not NULL) will contain the source of the variable.
536 *
537 * Note: The value can be changed by the registering code without using
538 * the mca_base_var_* interface so the source may be incorrect.
539 */
540 OPAL_DECLSPEC int mca_base_var_get_value (int vari, const void *value,
541 mca_base_var_source_t *source,
542 const char **source_file);
543
544 /**
545 * Sets an "override" value for an integer MCA variable.
546 *
547 * @param[in] vari Index of MCA variable to set
548 * @param[in] value Pointer to the value to set. Should point to
549 * a char * for string variables or a int * for integer variables.
550 * @param[in] size Size of value.
551 * @param[in] source Source of this value.
552 * @param[in] source_file Source file if source is MCA_BASE_VAR_SOURCE_FILE.
553 *
554 * @retval OPAL_SUCCESS Upon success.
555 * @retval OPAL_ERR_PERM If the variable is not settable.
556 * @retval OPAL_ERR_BAD_PARAM If the variable does not exist or has
557 * been deregistered.
558 * @retval OPAL_ERROR On other error.
559 *
560 * This function sets the value of an MCA variable. This value will
561 * overwrite the current value of the variable (or if index represents
562 * a synonym the variable the synonym represents) if the value is
563 * settable.
564 */
565 OPAL_DECLSPEC int mca_base_var_set_value (int vari, const void *value, size_t size,
566 mca_base_var_source_t source,
567 const char *source_file);
568
569 /**
570 * Get the string name corresponding to the MCA variable
571 * value in the environment.
572 *
573 * @param param_name Name of the type containing the variable.
574 *
575 * @retval string A string suitable for setenv() or appending to
576 * an environ-style string array.
577 * @retval NULL Upon failure.
578 *
579 * The string that is returned is owned by the caller; if
580 * appropriate, it must be eventually freed by the caller.
581 */
582 OPAL_DECLSPEC int mca_base_var_env_name(const char *param_name,
583 char **env_name);
584
585 /**
586 * Find the index for an MCA variable based on its names.
587 *
588 * @param project_name Name of the project
589 * @param type_name Name of the type containing the variable.
590 * @param component_name Name of the component containing the variable.
591 * @param param_name Name of the variable.
592 *
593 * @retval OPAL_ERROR If the variable was not found.
594 * @retval vari If the variable was found.
595 *
596 * It is not always convenient to widely propagate a variable's index
597 * value, or it may be necessary to look up the variable from a
598 * different component. This function can be used to look up the index
599 * of any registered variable. The returned index can be used with
600 * mca_base_var_get() and mca_base_var_get_value().
601 */
602 OPAL_DECLSPEC int mca_base_var_find (const char *project_name,
603 const char *type_name,
604 const char *component_name,
605 const char *param_name);
606
607 /**
608 * Find the index for a variable based on its full name
609 *
610 * @param full_name [in] Full name of the variable
611 * @param vari [out] Index of the variable
612 *
613 * See mca_base_var_find().
614 */
615 OPAL_DECLSPEC int mca_base_var_find_by_name (const char *full_name, int *vari);
616
617 /**
618 * Check that two MCA variables were not both set to non-default
619 * values.
620 *
621 * @param type_a [in] Framework name of variable A (string).
622 * @param component_a [in] Component name of variable A (string).
623 * @param param_a [in] Variable name of variable A (string.
624 * @param type_b [in] Framework name of variable A (string).
625 * @param component_b [in] Component name of variable A (string).
626 * @param param_b [in] Variable name of variable A (string.
627 *
628 * This function is useful for checking that the user did not set both
629 * of 2 mutually-exclusive MCA variables.
630 *
631 * This function will print an opal_show_help() message and return
632 * OPAL_ERR_BAD_VAR if it finds that the two variables both have
633 * value sources that are not MCA_BASE_VAR_SOURCE_DEFAULT. This
634 * means that both variables have been set by the user (i.e., they're
635 * not default values).
636 *
637 * Note that opal_show_help() allows itself to be hooked, so if this
638 * happens after the aggregated opal_show_help() system is
639 * initialized, the messages will be aggregated (w00t).
640 *
641 * @returns OPAL_ERR_BAD_VAR if the two variables have sources that
642 * are not MCA_BASE_VAR_SOURCE_DEFAULT.
643 * @returns OPAL_SUCCESS otherwise.
644 */
645 OPAL_DECLSPEC int mca_base_var_check_exclusive (const char *project,
646 const char *type_a,
647 const char *component_a,
648 const char *param_a,
649 const char *type_b,
650 const char *component_b,
651 const char *param_b);
652
653 /**
654 * Set or unset a flag on a variable.
655 *
656 * @param[in] vari Index of variable
657 * @param[in] flag Flag(s) to set or unset.
658 * @param[in] set Boolean indicating whether to set flag(s).
659 *
660 * @returns OPAL_SUCCESS If the flags are set successfully.
661 * @returns OPAL_ERR_BAD_PARAM If the variable is not registered.
662 * @returns OPAL_ERROR Otherwise
663 */
664 OPAL_DECLSPEC int mca_base_var_set_flag(int vari, mca_base_var_flag_t flag,
665 bool set);
666
667 /**
668 * Obtain basic info on a single variable (name, help message, etc)
669 *
670 * @param[in] vari Valid variable index.
671 * @param[out] var Storage for the variable pointer.
672 *
673 * @retval OPAL_SUCCESS Upon success.
674 * @retval opal error code Upon failure.
675 *
676 * The returned pointer belongs to the MCA variable system. Do not
677 * modify/free/retain the pointer.
678 */
679 OPAL_DECLSPEC int mca_base_var_get (int vari, const mca_base_var_t **var);
680
681 /**
682 * Obtain the number of variables that have been registered.
683 *
684 * @retval count on success
685 * @return opal error code on error
686 *
687 * Note: This function does not return the number of valid MCA variables as
688 * mca_base_var_deregister() has no impact on the variable count. The count
689 * returned is equal to the number of calls to mca_base_var_register with
690 * unique names. ie. two calls with the same name will not affect the count.
691 */
692 OPAL_DECLSPEC int mca_base_var_get_count (void);
693
694 /**
695 * Obtain a list of enironment variables describing the all
696 * valid (non-default) MCA variables and their sources.
697 *
698 * @param[out] env A pointer to an argv-style array of key=value
699 * strings, suitable for use in an environment
700 * @param[out] num_env A pointer to an int, containing the length
701 * of the env array (not including the final NULL entry).
702 * @param[in] internal Whether to include internal variables.
703 *
704 * @retval OPAL_SUCCESS Upon success.
705 * @retval OPAL_ERROR Upon failure.
706 *
707 * This function is similar to mca_base_var_dump() except that
708 * its output is in terms of an argv-style array of key=value
709 * strings, suitable for using in an environment.
710 */
711 OPAL_DECLSPEC int mca_base_var_build_env(char ***env, int *num_env,
712 bool internal);
713
714 typedef enum {
715 /* Dump human-readable strings */
716 MCA_BASE_VAR_DUMP_READABLE = 0,
717 /* Dump easily parsable strings */
718 MCA_BASE_VAR_DUMP_PARSABLE = 1,
719 /* Dump simple name=value string */
720 MCA_BASE_VAR_DUMP_SIMPLE = 2
721 } mca_base_var_dump_type_t;
722
723 /**
724 * Dump strings describing the MCA variable at an index.
725 *
726 * @param[in] vari Variable index
727 * @param[out] out Array of strings describing this variable
728 * @param[in] output_type Type of output desired
729 *
730 * This function returns an array of strings describing the variable. All strings
731 * and the array must be freed by the caller.
732 */
733 OPAL_DECLSPEC int mca_base_var_dump(int vari, char ***out, mca_base_var_dump_type_t output_type);
734
735 #define MCA_COMPILETIME_VER "print_compiletime_version"
736 #define MCA_RUNTIME_VER "print_runtime_version"
737
738 /*
739 * Parse a provided list of envars and add their local value, or
740 * their assigned value, to the provided argv
741 */
742 OPAL_DECLSPEC int mca_base_var_process_env_list(char *list, char ***argv);
743 OPAL_DECLSPEC int mca_base_var_process_env_list_from_file(char ***argv);
744
745 /*
746 * Initialize any file-based params
747 */
748 OPAL_DECLSPEC int mca_base_var_cache_files(bool rel_path_search);
749
750
751 extern char *mca_base_env_list;
752 #define MCA_BASE_ENV_LIST_SEP_DEFAULT ";"
753 extern char *mca_base_env_list_sep;
754 extern char *mca_base_env_list_internal;
755
756 END_C_DECLS
757
758 #endif /* OPAL_MCA_BASE_VAR_H */