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