OpenMPI 0.1.1

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

- File List
- Globals

mca_base_param.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2006 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * Copyright (c) 2008-2011 Cisco Systems, Inc. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 */
19
20 /** @file
21 * This file presents the MCA parameter interface.
22 *
23 * Note that there are two scopes for MCA parameters: "normal" and
24 * attributes. Specifically, all MCA parameters are "normal" -- some
25 * are special and may also be found on attributes on communicators,
26 * datatypes, or windows.
27 *
28 * In general, these functions are intended to be used as follows:
29 *
30 * - Creating MCA parameters
31 * -# Register a parameter, get an index back
32 * - Using MCA parameters
33 * -# Lookup a "normal" parameter value on a specific index, or
34 * -# Lookup an attribute parameter on a specific index and
35 * communicator / datatype / window.
36 *
37 * MCA parameters can be defined in multiple different places. As
38 * such, parameters are \em resolved to find their value. The order
39 * of resolution is as follows:
40 *
41 * - An "override" location that is only available to be set via the
42 * mca_base_param API.
43 * - Look for an environment variable corresponding to the MCA
44 * parameter.
45 * - See if a file contains the MCA parameter (MCA parameter files are
46 * read only once -- when the first time any mca_param_t function is
47 * invoked).
48 * - If nothing else was found, use the parameter's default value.
49 *
50 * Note that there is a second header file (mca_base_param_internal.h)
51 * that contains several internal type delcarations for the parameter
52 * system. The internal file is only used within the parameter system
53 * itself; it should not be required by any other Open MPI entities.
54 */
55
56 #ifndef OPAL_MCA_BASE_PARAM_H
57 #define OPAL_MCA_BASE_PARAM_H
58
59 #include "opal_config.h"
60
61 #include "opal/class/opal_list.h"
62 #include "opal/mca/mca.h"
63
64
65 /**
66 * The types of MCA parameters.
67 */
68 typedef enum {
69 /** The parameter is of type integer. */
70 MCA_BASE_PARAM_TYPE_INT,
71 /** The parameter is of type string. */
72 MCA_BASE_PARAM_TYPE_STRING,
73
74 /** Maximum parameter type. */
75 MCA_BASE_PARAM_TYPE_MAX
76 } mca_base_param_type_t;
77
78
79 /**
80 * Source of an MCA parameter's value
81 */
82 typedef enum {
83 /** The default value */
84 MCA_BASE_PARAM_SOURCE_DEFAULT,
85 /** The value came from the environment (or command line!) */
86 MCA_BASE_PARAM_SOURCE_ENV,
87 /** The value came from a file */
88 MCA_BASE_PARAM_SOURCE_FILE,
89 /** The value came a "set" API call */
90 MCA_BASE_PARAM_SOURCE_OVERRIDE,
91
92 /** Maximum source type */
93 MCA_BASE_PARAM_SOURCE_MAX
94 } mca_base_param_source_t;
95
96
97 /**
98 * Struct for holding name/type info. Used in mca_base_param_dump(),
99 * below.
100 */
101 struct mca_base_param_info_t {
102 /** So that we can be in a list */
103 opal_list_item_t super;
104
105 /** Index of this parameter */
106 int mbpp_index;
107 /** Enum indicating the back-end type of the parameter */
108 mca_base_param_type_t mbpp_type;
109
110 /** String name of the type of this component */
111 char *mbpp_type_name;
112 /** String name of the component of the parameter */
113 char *mbpp_component_name;
114 /** String name of the parameter of the parameter */
115 char *mbpp_param_name;
116 /** Full, assembled parameter name */
117 char *mbpp_full_name;
118
119 /** Is this parameter deprecated? */
120 bool mbpp_deprecated;
121
122 /** Array of pointers of synonyms of this parameter */
123 struct mca_base_param_info_t **mbpp_synonyms;
124 /** Length of mbpp_synonyms array */
125 int mbpp_synonyms_len;
126 /** Back pointer to another mca_base_param_info_t that *this*
127 param is a synonym of (or NULL) */
128 struct mca_base_param_info_t *mbpp_synonym_parent;
129
130 /** Is this parameter internal? */
131 bool mbpp_internal;
132 /** Is this parameter changable? */
133 bool mbpp_read_only;
134 /** Help message associated with this parameter */
135 char *mbpp_help_msg;
136 };
137 /**
138 * Convenience typedef
139 */
140 typedef struct mca_base_param_info_t mca_base_param_info_t;
141
142 /*
143 * Global functions for MCA
144 */
145
146 BEGIN_C_DECLS
147
148 /**
149 * Make a real object for the info
150 */
151 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_param_info_t);
152
153 /**
154 * Initialize the MCA parameter system.
155 *
156 * @retval OPAL_SUCCESS
157 *
158 * This function initalizes the MCA parameter system. It is
159 * invoked internally (by mca_base_open()) and is only documented
160 * here for completeness.
161 */
162 OPAL_DECLSPEC int mca_base_param_init(void);
163
164 /**
165 * Recache the MCA param files
166 *
167 * @param rel_path_search If a relative path is found, search the path even
168 * if the relative path in pointing to the current working directory.
169 * @retval OPAL_SUCCESS
170 *
171 */
172 OPAL_DECLSPEC int mca_base_param_recache_files(bool rel_path_search);
173
174 /**
175 * Register an integer MCA parameter.
176 *
177 * @param component [in] Pointer to the component for which the
178 * parameter is being registered.
179 * @param param_name [in] The name of the parameter being
180 * registered (string).
181 * @param help_msg [in] A string describing the use and valid
182 * values of the parameter (string).
183 * @param internal [in] Indicates whether the parameter is internal
184 * (i.e., not to be shown to users) or not (bool).
185 * @param read_only [in] Indicates whether the parameter value can
186 * ever change (bool).
187 * @param default_value [in] The value that is used for this
188 * parameter if the user does not supply one.
189 * @param current_value [out] After registering the parameter, look
190 * up its current value and return it unless current_value is
191 * NULL.
192 *
193 * @retval OPAL_ERROR Upon failure to register the parameter.
194 * @retval index Index value that can be used with
195 * mca_base_param_lookup_int() to retrieve the value of the parameter.
196 *
197 * This function registers an integer MCA parameter and associates it
198 * with a specific component.
199 *
200 * If the {component} pointer is not NULL, the type name and
201 * component name are automatically prefixed to the parameter
202 * name. Otherwise, the {param_name} is used as the full
203 * parameter name.
204 *
205 * The {help_msg} is a string of arbitrary length (verbose is
206 * good!) for explaining what the parameter is for and what its
207 * valid values are. This message is used in help messages, such
208 * as the output from the ompi_info executable.
209 *
210 * If {internal} is set to true, this parameter is not shown by
211 * default in the output of ompi_info. That is, this parameter is
212 * considered internal to the Open MPI implementation and is not
213 * supposed to be viewed / changed by the user.
214 *
215 * If {read_only} is true, then the registered {default_value}
216 * will be the only value ever returned when this parameter is
217 * looked up. That is, command line, environment, and file
218 * overrides will be ignored. This is useful, for example, for
219 * reporting information to the user (e.g., the version of the GM
220 * library that was linked against).
221 *
222 * If the {current_value} is not NULL, when the registration is
223 * complete, the parameter system will look up the current value
224 * of the parameter and return it in {current_value}.
225 */
226 OPAL_DECLSPEC int mca_base_param_reg_int(const mca_base_component_t *component,
227 const char *param_name,
228 const char *help_msg,
229 bool internal,
230 bool read_only,
231 int default_value,
232 int *current_value);
233
234 /**
235 * Register an integer MCA parameter that is not associated with a
236 * component.
237 *
238 * @param type [in] Although this parameter is not associated with
239 * a component, it still must have a string type name that will
240 * act as a prefix (string).
241 * @param param_name [in] The name of the parameter being
242 * registered (string).
243 * @param help_msg [in] A string describing the use and valid
244 * values of the parameter (string).
245 * @param internal [in] Indicates whether the parameter is internal
246 * (i.e., not to be shown to users) or not (bool).
247 * @param read_only [in] Indicates whether the parameter value can
248 * ever change (bool).
249 * @param default_value [in] The value that is used for this
250 * parameter if the user does not supply one.
251 * @param current_value [out] After registering the parameter, look
252 * up its current value and return it unless current_value is
253 * NULL.
254 *
255 * @retval OPAL_ERROR Upon failure to register the parameter.
256 * @retval index Index value that can be used with
257 * mca_base_param_lookup_string() to retrieve the value of the
258 * parameter.
259 *
260 * This function is identical to mca_base_param_reg_int() except
261 * that it registers parameters that are not associated with
262 * components. For example, it can be used to register parameters
263 * associated with a framework base or an overall layer (e.g., the
264 * MPI layer, or the MCA base system framework itself). Typical
265 * "type" strings are:
266 *
267 * "mca": for the MCA base framework itself
268 * framework name: for any given framework
269 * "mpi": for parameters that apply to the overall MPI layer
270 * "orte": for parameters that apply to the overall ORTE layer
271 * "btl": for parameters to the OMPI BTL framework
272 * ...etc.
273 *
274 * Note that the type should always be a framework or a level name
275 * (e.g., "btl" or "mpi") -- it should not include the component
276 * name, even if the component is the base of a framework. Hence,
277 * "btl_base" is not a valid type name. Specifically, registering
278 * a parameter with an unrecognized type is not an error, but
279 * ompi_info has a hard-coded list of frameworks and levels;
280 * parameters that have recongized types, although they can be
281 * used by the user, will not be displayed by ompi_info.
282 *
283 * Note that if you use mca_base_param_find() to lookup the index
284 * of the registered parameter, the "component" argument should be
285 * NULL (because it is not specified in this registration
286 * function, and is therefore registered with a NULL value).
287 */
288 OPAL_DECLSPEC int mca_base_param_reg_int_name(const char *type,
289 const char *param_name,
290 const char *help_msg,
291 bool internal,
292 bool read_only,
293 int default_value,
294 int *current_value);
295
296 /**
297 * Register a string MCA parameter.
298 *
299 * @param component [in] Pointer to the component for which the
300 * parameter is being registered.
301 * @param param_name [in] The name of the parameter being
302 * registered (string).
303 * @param help_msg [in] A string describing the use and valid
304 * values of the parameter (string).
305 * @param internal [in] Indicates whether the parameter is internal
306 * (i.e., not to be shown to users) or not (bool).
307 * @param read_only [in] Indicates whether the parameter value can
308 * ever change (bool).
309 * @param default_value [in] The value that is used for this
310 * parameter if the user does not supply one.
311 * @param current_value [out] After registering the parameter, look
312 * up its current value and return it unless current_value is
313 * NULL.
314 *
315 * @retval OPAL_ERROR Upon failure to register the parameter.
316 * @retval index Index value that can be used with
317 * mca_base_param_lookup_string() to retrieve the value of the
318 * parameter.
319 *
320 * Note that if a string value is read in from a file then it will
321 * never be NULL. It will always have a value, even if that value is
322 * the empty string.
323 *
324 * NOTE: Strings returned in the \em current_value parameter should later
325 * be free()'ed.
326 *
327 * This function is identical to mca_base_param_reg_int() except
328 * that you are registering a string parameter with an associated
329 * string default value (which is \em not allowed to be NULL).
330 * See mca_base_param_reg_int() for all other details.
331 */
332 OPAL_DECLSPEC int mca_base_param_reg_string(const mca_base_component_t *component,
333 const char *param_name,
334 const char *help_msg,
335 bool internal,
336 bool read_only,
337 const char *default_value,
338 char **current_value);
339
340
341 /**
342 * Register a string MCA parameter that is not associated with a
343 * component.
344 *
345 * @param type [in] Although this parameter is not associated with
346 * a component, it still must have a string type name that will
347 * act as a prefix (string).
348 * @param param_name [in] The name of the parameter being
349 * registered (string).
350 * @param help_msg [in] A string describing the use and valid
351 * values of the parameter (string).
352 * @param internal [in] Indicates whether the parameter is internal
353 * (i.e., not to be shown to users) or not (bool).
354 * @param read_only [in] Indicates whether the parameter value can
355 * ever change (bool).
356 * @param default_value [in] The value that is used for this
357 * parameter if the user does not supply one.
358 * @param current_value [out] After registering the parameter, look
359 * up its current value and return it unless current_value is
360 * NULL.
361 *
362 * @retval OPAL_ERROR Upon failure to register the parameter.
363 * @retval index Index value that can be used with
364 * mca_base_param_lookup_string() to retrieve the value of the
365 * parameter.
366 *
367 * Note that if a string value is read in from a file then it will
368 * never be NULL. It will always have a value, even if that value is
369 * the empty string.
370 *
371 * This function is identical to mca_base_param_reg_string()
372 * except that it registers parameters that are not associated
373 * with components. For example, it can be used to register
374 * parameters associated with a framework base or an overall layer
375 * (e.g., the MPI layer, or the MCA base system framework itself).
376 * Typical "type" strings are:
377 *
378 * "mca": for the MCA base framework itself
379 * framework name: for any given framework
380 * "mpi": for parameters that apply to the overall MPI layer
381 * "orte": for parameters that apply to the overall ORTE layer
382 * "btl": for parameters to the OMPI BTL framework
383 * ...etc.
384 *
385 * Note that the type should always be a framework or a level name
386 * (e.g., "btl" or "mpi") -- it should not include the component
387 * name, even if the component is the base of a framework. Hence,
388 * "btl_base" is not a valid type name. Specifically, registering
389 * a parameter with an unrecognized type is not an error, but
390 * ompi_info has a hard-coded list of frameworks and levels;
391 * parameters that have recongized types, although they can be
392 * used by the user, will not be displayed by ompi_info.
393 *
394 * Note that if you use mca_base_param_find() to lookup the index
395 * of the registered parameter, the "component" argument should be
396 * NULL (because it is not specified in this registration
397 * function, and is therefore registered with a NULL value).
398 */
399 OPAL_DECLSPEC int mca_base_param_reg_string_name(const char *type,
400 const char *param_name,
401 const char *help_msg,
402 bool internal,
403 bool read_only,
404 const char *default_value,
405 char **current_value);
406
407 /**
408 * Register a synonym name for an MCA parameter.
409 *
410 * @param original_index [in] The index of the original parameter to
411 * create a synonym for.
412 * @param syn_component [in] Pointer to the component for which the
413 * synonym is being registered.
414 * @param syn_param_name [in] Parameter name of the synonym to be
415 * created (string)
416 * @param deprecated If true, a warning will be shown if this
417 * synonym is used to set the parameter's value (unless the
418 * warnings are silenced)
419 *
420 * @returns OPAL_SUCCESS Upon success.
421 * @returns OPAL_ERR_BAD_PARAM If the index value is invalid.
422 * @returns OPAL_ERROR Otherwise
423 *
424 * Upon success, this function creates a synonym MCA parameter
425 * that will be treated almost exactly like the original. The
426 * type (int or string) is irrelevant; this function simply
427 * creates a new name that by which the same parameter value is
428 * accessible.
429 *
430 * Note that the original parameter name has precendence over all
431 * synonyms. For example, consider the case if parameter is
432 * originally registered under the name "A" and is later
433 * registered with synonyms "B" and "C". If the user sets values
434 * for both MCA parameter names "A" and "B", the value associated
435 * with the "A" name will be used and the value associated with
436 * the "B" will be ignored (and will not even be visible by the
437 * mca_base_param_*() API). If the user sets values for both MCA
438 * parameter names "B" and "C" (and does *not* set a value for
439 * "A"), it is undefined as to which value will be used.
440 */
441 OPAL_DECLSPEC int mca_base_param_reg_syn(int orignal_index,
442 const mca_base_component_t *syn_component,
443 const char *syn_param_name,
444 bool deprecated);
445
446 /**
447 * Register an MCA parameter synonym that is not associated with a
448 * component.
449 *
450 * @param original_index [in] The index of the original parameter to
451 * create a synonym for.
452 * @param type [in] Although this synonym is not associated with
453 * a component, it still must have a string type name that will
454 * act as a prefix (string).
455 * @param syn_param_name [in] Parameter name of the synonym to be
456 * created (string)
457 * @param deprecated If true, a warning will be shown if this
458 * synonym is used to set the parameter's value (unless the
459 * warnings are silenced)
460 *
461 * Essentially the same as mca_base_param_reg_syn(), but using a
462 * type name instead of a component.
463 *
464 * See mca_base_param_reg_int_name() for guidence on type string
465 * values.
466 */
467 OPAL_DECLSPEC int mca_base_param_reg_syn_name(int orignal_index,
468 const char *syn_type,
469 const char *syn_param_name,
470 bool deprecated);
471
472 /**
473 * Deregister a MCA parameter
474 *
475 * @param index Index returned from mca_base_param_register_init()
476 *
477 */
478 OPAL_DECLSPEC int mca_base_param_deregister(int index);
479
480 /**
481 * Look up an integer MCA parameter.
482 *
483 * @param index Index previous returned from
484 * mca_base_param_register_int().
485 * @param value Pointer to int where the parameter value will be
486 * stored.
487 *
488 * @return OPAL_ERROR Upon failure. The contents of value are
489 * undefined.
490 * @return OPAL_SUCCESS Upon success. value will be filled with the
491 * parameter's current value.
492 *
493 * The value of a specific MCA parameter can be looked up using the
494 * return value from mca_base_param_register_int().
495 */
496 OPAL_DECLSPEC int mca_base_param_lookup_int(int index, int *value);
497
498 /**
499 * Look up a string MCA parameter.
500 *
501 * @param index Index previous returned from
502 * mca_base_param_register_string().
503 * @param value Pointer to (char *) where the parameter value will be
504 * stored.
505 *
506 * @return OPAL_ERROR Upon failure. The contents of value are
507 * undefined.
508 * @return OPAL_SUCCESS Upon success. value will be filled with the
509 * parameter's current value.
510 *
511 * Note that if a string value is read in from a file then it will
512 * never be NULL. It will always have a value, even if that value is
513 * the empty string.
514 *
515 * Strings returned in the \em value parameter should later be
516 * free()'ed.
517 *
518 * The value of a specific MCA parameter can be looked up using the
519 * return value from mca_base_param_register_string().
520 */
521 OPAL_DECLSPEC int mca_base_param_lookup_string(int index, char **value);
522
523 /**
524 * Lookup the source of an MCA parameter's value
525 *
526 * @param index [in] Index of MCA parameter to set
527 * @param source [out] Enum value indicating source
528 * @param source_file [out] If value came from source, name of the
529 * file that set it. The caller should not modify or free this
530 * string. It is permissable to specify source_file==NULL if the
531 * caller does not care to know the filename.
532 *
533 * @retval OPAL_ERROR If the parameter was not found.
534 * @retval OPAL_SUCCESS Upon success.
535 *
536 * This function looks up to see where the value of an MCA
537 * parameter came from.
538 */
539 OPAL_DECLSPEC int mca_base_param_lookup_source(int index,
540 mca_base_param_source_t *source,
541 char **source_file);
542
543 /**
544 * Sets an "override" value for an integer MCA parameter.
545 *
546 * @param index [in] Index of MCA parameter to set
547 * @param value [in] The integer value to set
548 *
549 * @retval OPAL_ERROR If the parameter was not found.
550 * @retval OPAL_SUCCESS Upon success.
551 *
552 * This function sets an integer value on the MCA parameter
553 * indicated by the index value index. This value will be used in
554 * lieu of any other value from any other MCA source (environment
555 * variable, file, etc.) until the value is unset with
556 * mca_base_param_unset().
557 *
558 * This function may be invoked multiple times; each time, the
559 * last "set" value is replaced with the newest value.
560 */
561 OPAL_DECLSPEC int mca_base_param_set_int(int index, int value);
562
563 /**
564 * Sets an "override" value for an string MCA parameter.
565 *
566 * @param index [in] Index of MCA parameter to set
567 * @param value [in] The string value to set
568 *
569 * @retval OPAL_ERROR If the parameter was not found.
570 * @retval OPAL_SUCCESS Upon success.
571 *
572 * This function sets a string value on the MCA parameter
573 * indicated by the index value index. This value will be used in
574 * lieu of any other value from any other MCA source (environment
575 * variable, file, etc.) until the value is unset with
576 * mca_base_param_unset().
577 *
578 * The string is copied by value; the string "value" parameter
579 * does not become "owned" by the parameter subsystem.
580 *
581 * This function may be invoked multiple times; each time, the
582 * last "set" value is replaced with the newest value (the old
583 * value is discarded).
584 */
585 OPAL_DECLSPEC int mca_base_param_set_string(int index, char *value);
586
587 /**
588 * Unset a parameter that was previously set by
589 * mca_base_param_set_int() or mca_base_param_set_string().
590 *
591 * @param index [in] Index of MCA parameter to set
592 *
593 * @retval OPAL_ERROR If the parameter was not found.
594 * @retval OPAL_SUCCESS Upon success.
595 *
596 * Resets previous value that was set (if any) on the given MCA
597 * parameter.
598 */
599 OPAL_DECLSPEC int mca_base_param_unset(int index);
600
601 /**
602 * Get the string name corresponding to the MCA parameter
603 * value in the environment.
604 *
605 * @param param_name Name of the type containing the parameter.
606 *
607 * @retval string A string suitable for setenv() or appending to
608 * an environ-style string array.
609 * @retval NULL Upon failure.
610 *
611 * The string that is returned is owned by the caller; if
612 * appropriate, it must be eventually freed by the caller.
613 */
614 OPAL_DECLSPEC char *mca_base_param_env_var(const char *param_name);
615
616 /**
617 * Find the index for an MCA parameter based on its names.
618 *
619 * @param type Name of the type containing the parameter.
620 * @param component Name of the component containing the parameter.
621 * @param param Name of the parameter.
622 *
623 * @retval OPAL_ERROR If the parameter was not found.
624 * @retval index If the parameter was found.
625 *
626 * It is not always convenient to widely propagate a parameter's index
627 * value, or it may be necessary to look up the parameter from a
628 * different component -- where it is not possible to have the return
629 * value from mca_base_param_register_int() or
630 * mca_base_param_register_string(). This function can be used to
631 * look up the index of any registered parameter. The returned index
632 * can be used with mca_base_param_lookup_int() and
633 * mca_base_param_lookup_string().
634 */
635 OPAL_DECLSPEC int mca_base_param_find(const char *type,
636 const char *component,
637 const char *param);
638
639 /**
640 * Find an MCA parameter in an env array based on its names.
641 *
642 * @param component [in] Pointer to the component for which the
643 * parameter was registered.
644 * @param param_name [in] The name of the parameter being
645 * registered (string).
646 * @param env [in] NULL-terminated list of strings (e.g., from an environment).
647 * @param current_value [out] Return the current value (if found).
648 *
649 * @retval OPAL_ERROR If the parameter was not found.
650 *
651 * Look for a specific MCA parameter in an environment and return its value
652 */
653 OPAL_DECLSPEC int mca_base_param_find_int(const mca_base_component_t *component,
654 const char *param_name,
655 char **env,
656 int *current_value);
657
658 /**
659 * Find an MCA parameter (in an env array) that is not associated with a
660 * component.
661 *
662 * @param type [in] Although this parameter is not associated with
663 * a component, it still must have a string type name that will
664 * act as a prefix (string).
665 * @param param_name [in] The name of the parameter being
666 * registered (string).
667 * @param env [in] NULL-terminated list of strings (e.g., from an environment).
668 * @param current_value [out] Return the current value (if found).
669 *
670 * @retval OPAL_ERROR If the parameter was not found.
671 *
672 * Look for a specific MCA parameter in an environment and return its value
673 */
674 OPAL_DECLSPEC int mca_base_param_find_int_name(const char *type,
675 const char *param_name,
676 char **env,
677 int *current_value);
678 /**
679 * Find a string MCA parameter in an env array based on its names.
680 *
681 * @param component [in] Pointer to the component for which the
682 * parameter was registered.
683 * @param param_name [in] The name of the parameter being
684 * registered (string).
685 * @param env [in] NULL-terminated list of strings (e.g., from an environment).
686 * @param current_value [out] Return the current value (if found).
687 *
688 * @retval OPAL_ERROR If the parameter was not found.
689 *
690 * Look for a specific MCA parameter in an environment and return its value
691 */
692 OPAL_DECLSPEC int mca_base_param_find_string(const mca_base_component_t *component,
693 const char *param_name,
694 char **env,
695 char **current_value);
696
697 /**
698 * Find a string MCA parameter (in an env array) that is not associated with a
699 * component.
700 *
701 * @param type [in] Although this parameter is not associated with
702 * a component, it still must have a string type name that will
703 * act as a prefix (string).
704 * @param param_name [in] The name of the parameter being
705 * registered (string).
706 * @param env [in] NULL-terminated list of strings (e.g., from an environment).
707 * @param current_value [out] Return the current value (if found).
708 *
709 * @retval OPAL_ERROR If the parameter was not found.
710 *
711 * Look for a specific MCA parameter in an environment and return its value
712 */
713 OPAL_DECLSPEC int mca_base_param_find_string_name(const char *type,
714 const char *param_name,
715 char **env,
716 char **current_value);
717
718 /**
719 * Check that two MCA parameters were not both set to non-default
720 * values.
721 *
722 * @param type_a [in] Framework name of parameter A (string).
723 * @param component_a [in] Component name of parameter A (string).
724 * @param param_a [in] Parameter name of parameter A (string.
725 * @param type_b [in] Framework name of parameter A (string).
726 * @param component_b [in] Component name of parameter A (string).
727 * @param param_b [in] Parameter name of parameter A (string.
728 *
729 * This function is useful for checking that the user did not set both
730 * of 2 mutually-exclusive MCA parameters.
731 *
732 * This function will print an opal_show_help() message and return
733 * OPAL_ERR_BAD_PARAM if it finds that the two parameters both have
734 * value sources that are not MCA_BASE_PARAM_SOURCE_DEFAULT. This
735 * means that both parameters have been set by the user (i.e., they're
736 * not default values).
737 *
738 * Note that opal_show_help() allows itself to be hooked, so if this
739 * happens after the aggregated orte_show_help() system is
740 * initialized, the messages will be aggregated (w00t).
741 *
742 * @returns OPAL_ERR_BAD_PARAM if the two parameters have sources that
743 * are not MCA_BASE_PARAM_SOURCE_DEFAULT.
744 * @returns OPAL_SUCCESS otherwise.
745 */
746 OPAL_DECLSPEC int mca_base_param_check_exclusive_string(const char *type_a,
747 const char *component_a,
748 const char *param_a,
749 const char *type_b,
750 const char *component_b,
751 const char *param_b);
752
753 /**
754 * Set the "internal" flag on an MCA parameter to true or false.
755 *
756 * @param index [in] Index previous returned from
757 * mca_base_param_register_string() or mca_base_param_register_int().
758 * @param internal [in] Boolean indicating whether the MCA
759 * parameter is internal (private) or public.
760 *
761 * @returns OPAL_SUCCESS If it can find the parameter to reset
762 * @returns OPAL_ERROR Otherwise
763 *
764 * "Internal" MCA parameters are ones that are not intentended to
765 * be seen or modified by users or user applications. These
766 * include values that are set at run time, such as TCP ports, IP
767 * addresses, etc. By setting the "internal" flag, internal MCA
768 * parameters are not displayed during the output of ompi_info and
769 * MPI_INIT (at least, they're not displayed by default), thus
770 * keeping them away from prying user eyes.
771 */
772 OPAL_DECLSPEC int mca_base_param_set_internal(int index, bool internal);
773
774 /**
775 * Obtain a list of all the MCA parameters currently defined as
776 * well as their types.
777 *
778 * @param info [out] An opal_list_t of mca_base_param_info_t
779 * instances.
780 * @param internal [in] Whether to include the internal parameters
781 * or not.
782 *
783 * @retval OPAL_SUCCESS Upon success.
784 * @retval OPAL_ERROR Upon failure.
785 *
786 * This function is used to obtain a list of all the currently
787 * registered MCA parameters along with their associated types
788 * (currently: string or integer). The results from this function
789 * can be used to repeatedly invoke mca_base_param_lookup_int()
790 * and/or mca_base_param_lookup_string() to obtain a comprehensive
791 * list of all MCA parameters and their current values.
792 *
793 * Releasing the list, and all the items in the list, is a
794 * relatively complicated process. Use the companion function
795 * mca_base_param_dump_release() when finished with the returned
796 * info list to release all associated memory.
797 */
798 OPAL_DECLSPEC int mca_base_param_dump(opal_list_t **info, bool internal);
799
800 /**
801 * Obtain a list of all the MCA parameters currently defined as
802 * well as their types.
803 *
804 * @param env [out] A pointer to an argv-style array of key=value
805 * strings, suitable for use in an environment
806 * @param num_env [out] A pointer to an int, containing the length
807 * of the env array (not including the final NULL entry).
808 * @param internal [in] Whether to include the internal parameters
809 * or not.
810 *
811 * @retval OPAL_SUCCESS Upon success.
812 * @retval OPAL_ERROR Upon failure.
813 *
814 * This function is similar to mca_base_param_dump() except that
815 * its output is in terms of an argv-style array of key=value
816 * strings, suitable for using in an environment.
817 */
818 OPAL_DECLSPEC int mca_base_param_build_env(char ***env, int *num_env,
819 bool internal);
820
821 /**
822 * Release the memory associated with the info list returned from
823 * mca_base_param_dump().
824 *
825 * @param info [in/out] An opal_list_t previously returned from
826 * mca_base_param_dump().
827 *
828 * @retval OPAL_SUCCESS Upon success.
829 * @retval OPAL_ERROR Upon failure.
830 *
831 * This function is intended to be used to free the info list
832 * returned from mca_base_param_dump(). There are a bunch of
833 * strings and other associated memory in the list making it
834 * cumbersome for the caller to free it all properly. Hence, once
835 * the caller is finished with the info list, invoke this
836 * function and all memory associated with the list will be freed.
837 */
838 OPAL_DECLSPEC int mca_base_param_dump_release(opal_list_t *info);
839
840 /**
841 * Shut down the MCA parameter system (normally only invoked by the
842 * MCA framework itself).
843 *
844 * @returns OPAL_SUCCESS This function never fails.
845 *
846 * This function shuts down the MCA parameter repository and frees all
847 * associated memory. No other mca_base_param*() functions can be
848 * invoked after this function.
849 *
850 * This function is normally only invoked by the MCA framework itself
851 * when the process is shutting down (e.g., during MPI_FINALIZE). It
852 * is only documented here for completeness.
853 */
854 OPAL_DECLSPEC int mca_base_param_finalize(void);
855
856 /***************************************************************
857 * Deprecated interface
858 ***************************************************************/
859
860 /**
861 * \deprecated
862 *
863 * Register an integer MCA parameter (deprecated).
864 *
865 * @param type_name [in] The MCA type (string).
866 * @param component_name [in] The name of the component (string).
867 * @param param_name [in] The name of the parameter being registered
868 * (string).
869 * @param mca_param_name [in] Optional parameter to override the
870 * user-visible name of this parameter (string).
871 * @param default_value [in] The value that is used for this
872 * parameter if the user does not supply one.
873 *
874 * @retval OPAL_ERROR Upon failure to register the parameter.
875 * @retval index Index value that can be used with
876 * mca_base_param_lookup_int() to retrieve the value of the parameter.
877 *
878 * This function is deprecated. Use mca_base_param_reg_int() instead.
879 *
880 * This function registers an integer MCA parameter and associates it
881 * with a specific component.
882 *
883 * The default resulting MCA parameter name is
884 * {type_name}[_{component_name}][_{param_name}].
885 *
886 * {component_name} is only included if it is non-NULL. All
887 * components an should include their name; component frameworks
888 * should pass "base". It is only permissible for the MCA base
889 * itself to pass NULL for the component_name.
890 *
891 * Likewise, {param_name} is also only included if it is non-NULL.
892 * Components and frameworks can pass NULL for this parameter if
893 * they wish.
894 *
895 * In most cases, mca_param_name should be NULL, in which case the
896 * user-visible name of this parameter will be the default form (as
897 * described above). Only in rare cases is it necessary (or
898 * advisable) to override the default name -- its use is strongly
899 * discouraged.
900 *
901 * It is permissable to register a (type_name, component_name,
902 * param_name) triple more than once; the same index value will be
903 * returned, but the default value will be changed to reflect the
904 * last registration.
905 */
906 OPAL_DECLSPEC int mca_base_param_register_int(const char *type_name,
907 const char *component_name,
908 const char *param_name,
909 const char *mca_param_name,
910 int default_value) /* __opal_attribute_deprecated__ */;
911
912 /**
913 * \deprecated
914 *
915 * Register a string MCA parameter (deprecated).
916 *
917 * @param type_name [in] The MCA type (string).
918 * @param component_name [in] The name of the component (string).
919 * @param param_name [in] The name of the parameter being registered
920 * (string).
921 * @param mca_param_name [in] Optional parameter to override the
922 * user-visible name of this parameter (string).
923 * @param default_value [in] The value that is used for this
924 * parameter if the user does not supply one.
925 *
926 * @retval OPAL_ERROR Upon failure to register the parameter.
927 * @retval index Index value that can be used with
928 * mca_base_param_lookup_string() to retrieve the value of the
929 * parameter.
930 *
931 * This function is deprecated. Use mca_base_param_reg_string()
932 * instead.
933 *
934 * Note that if a string value is read in from a file then it will
935 * never be NULL. It will always have a value, even if that value is
936 * the empty string.
937 *
938 * This function is identical to mca_base_param_register_int()
939 * except that you are registering a string parameter with an
940 * associated string default value (which is \em not allowed to be NULL).
941 * See mca_base_param_register_int() for all other details.
942 */
943 OPAL_DECLSPEC int mca_base_param_register_string(const char *type_name,
944 const char *component_name,
945 const char *param_name,
946 const char *mca_param_name,
947 const char *default_value) /* __opal_attribute_deprecated__ */;
948
949 /**
950 * \deprecated
951 *
952 * Get the string name corresponding to the MCA parameter
953 * value in the environment (deprecated).
954 *
955 * @param type Name of the type containing the parameter.
956 * @param comp Name of the component containing the parameter.
957 * @param param Name of the parameter.
958 *
959 * @retval string A string suitable for setenv() or appending to
960 * an environ-style string array.
961 * @retval NULL Upon failure.
962 *
963 * This function is deprecated. Use mca_base_param_env_var()
964 * instead.
965 *
966 * The string that is returned is owned by the caller; if
967 * appropriate, it must be eventually freed by the caller.
968 */
969 OPAL_DECLSPEC char *mca_base_param_environ_variable(const char *type,
970 const char *comp,
971 const char *param) /* __opal_attribute_deprecated__ */;
972
973 END_C_DECLS
974
975 #endif /* OPAL_MCA_BASE_PARAM_H */
mca_base_param_info_t
Struct for holding name/type info.
Definition: mca_base_param.h:101
mca_base_param_info_t::mbpp_synonyms_len
int mbpp_synonyms_len
Length of mbpp_synonyms array.
Definition: mca_base_param.h:125
mca_base_component_2_0_0_t
Common type for all MCA components.
Definition: mca.h:250
mca_base_param_reg_syn
OPAL_DECLSPEC int mca_base_param_reg_syn(int orignal_index, const mca_base_component_t *syn_component, const char *syn_param_name, bool deprecated)
Register a synonym name for an MCA parameter.
Definition: mca_base_param.c:463
MCA_BASE_PARAM_SOURCE_OVERRIDE
The value came a "set" API call.
Definition: mca_base_param.h:90
mca_base_param_reg_string_name
OPAL_DECLSPEC int mca_base_param_reg_string_name(const char *type, const char *param_name, const char *help_msg, bool internal, bool read_only, const char *default_value, char **current_value)
Register a string MCA parameter that is not associated with a component.
Definition: mca_base_param.c:386
mca_base_param_unset
OPAL_DECLSPEC int mca_base_param_unset(int index)
Unset a parameter that was previously set by mca_base_param_set_int() or mca_base_param_set_string()...
Definition: mca_base_param.c:573
mca_base_param_recache_files
OPAL_DECLSPEC int mca_base_param_recache_files(bool rel_path_search)
Recache the MCA param files.
Definition: mca_base_param.c:179
mca_base_param_build_env
OPAL_DECLSPEC int mca_base_param_build_env(char ***env, int *num_env, bool internal)
Obtain a list of all the MCA parameters currently defined as well as their types. ...
Definition: mca_base_param.c:836
mca_base_param_register_int
OPAL_DECLSPEC int mca_base_param_register_int(const char *type_name, const char *component_name, const char *param_name, const char *mca_param_name, int default_value)
Definition: mca_base_param.c:418
mca_base_param_info_t::mbpp_index
int mbpp_index
Index of this parameter.
Definition: mca_base_param.h:106
mca_base_param_reg_string
OPAL_DECLSPEC int mca_base_param_reg_string(const mca_base_component_t *component, const char *param_name, const char *help_msg, bool internal, bool read_only, const char *default_value, char **current_value)
Register a string MCA parameter.
Definition: mca_base_param.c:352
mca_base_param_environ_variable
OPAL_DECLSPEC char * mca_base_param_environ_variable(const char *type, const char *comp, const char *param)
Definition: mca_base_param.c:619
opal_list.h
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
OBJ_CLASS_DECLARATION
BEGIN_C_DECLS OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_param_info_t)
Make a real object for the info.
mca_base_param_register_string
OPAL_DECLSPEC int mca_base_param_register_string(const char *type_name, const char *component_name, const char *param_name, const char *mca_param_name, const char *default_value)
Definition: mca_base_param.c:439
mca_base_param_lookup_source
OPAL_DECLSPEC int mca_base_param_lookup_source(int index, mca_base_param_source_t *source, char **source_file)
Lookup the source of an MCA parameter's value.
Definition: mca_base_param.c:560
mca.h
Top-level interface for all MCA components.
opal_list_item_t
Definition: opal_list.h:98
mca_base_param_info_t::mbpp_component_name
char * mbpp_component_name
String name of the component of the parameter.
Definition: mca_base_param.h:113
mca_base_param_info_t::mbpp_deprecated
bool mbpp_deprecated
Is this parameter deprecated?
Definition: mca_base_param.h:120
mca_base_param_check_exclusive_string
OPAL_DECLSPEC int mca_base_param_check_exclusive_string(const char *type_a, const char *component_a, const char *param_a, const char *type_b, const char *component_b, const char *param_b)
Check that two MCA parameters were not both set to non-default values.
Definition: mca_base_param.c:2297
mca_base_param_dump_release
OPAL_DECLSPEC int mca_base_param_dump_release(opal_list_t *info)
Release the memory associated with the info list returned from mca_base_param_dump().
Definition: mca_base_param.c:903
MCA_BASE_PARAM_SOURCE_DEFAULT
The default value.
Definition: mca_base_param.h:84
mca_base_param_deregister
OPAL_DECLSPEC int mca_base_param_deregister(int index)
Deregister a MCA parameter.
Definition: mca_base_param.c:515
mca_base_param_reg_int_name
OPAL_DECLSPEC int mca_base_param_reg_int_name(const char *type, const char *param_name, const char *help_msg, bool internal, bool read_only, int default_value, int *current_value)
Register an integer MCA parameter that is not associated with a component.
Definition: mca_base_param.c:326
mca_base_param_find
OPAL_DECLSPEC int mca_base_param_find(const char *type, const char *component, const char *param)
Find the index for an MCA parameter based on its names.
Definition: mca_base_param.c:670
MCA_BASE_PARAM_TYPE_STRING
The parameter is of type string.
Definition: mca_base_param.h:72
MCA_BASE_PARAM_SOURCE_ENV
The value came from the environment (or command line!)
Definition: mca_base_param.h:86
mca_base_param_init
OPAL_DECLSPEC int mca_base_param_init(void)
Initialize the MCA parameter system.
Definition: mca_base_param.c:156
mca_base_param_info_t::mbpp_synonym_parent
struct mca_base_param_info_t * mbpp_synonym_parent
Back pointer to another mca_base_param_info_t that this param is a synonym of (or NULL) ...
Definition: mca_base_param.h:128
mca_base_param_finalize
OPAL_DECLSPEC int mca_base_param_finalize(void)
Shut down the MCA parameter system (normally only invoked by the MCA framework itself).
Definition: mca_base_param.c:921
mca_base_param_info_t::mbpp_full_name
char * mbpp_full_name
Full, assembled parameter name.
Definition: mca_base_param.h:117
mca_base_param_info_t::mbpp_synonyms
struct mca_base_param_info_t ** mbpp_synonyms
Array of pointers of synonyms of this parameter.
Definition: mca_base_param.h:123
mca_base_param_lookup_int
OPAL_DECLSPEC int mca_base_param_lookup_int(int index, int *value)
Look up an integer MCA parameter.
Definition: mca_base_param.c:487
mca_base_param_info_t::mbpp_internal
bool mbpp_internal
Is this parameter internal?
Definition: mca_base_param.h:131
mca_base_param_info_t::mbpp_help_msg
char * mbpp_help_msg
Help message associated with this parameter.
Definition: mca_base_param.h:135
mca_base_param_info_t::mbpp_type_name
char * mbpp_type_name
String name of the type of this component.
Definition: mca_base_param.h:111
mca_base_param_source_t
mca_base_param_source_t
Source of an MCA parameter's value.
Definition: mca_base_param.h:82
opal_list_t
Definition: opal_list.h:147
mca_base_param_info_t::mbpp_type
mca_base_param_type_t mbpp_type
Enum indicating the back-end type of the parameter.
Definition: mca_base_param.h:108
MCA_BASE_PARAM_SOURCE_FILE
The value came from a file.
Definition: mca_base_param.h:88
mca_base_param_lookup_string
OPAL_DECLSPEC int mca_base_param_lookup_string(int index, char **value)
Look up a string MCA parameter.
Definition: mca_base_param.c:531
mca_base_param_set_int
OPAL_DECLSPEC int mca_base_param_set_int(int index, int value)
Sets an "override" value for an integer MCA parameter.
Definition: mca_base_param.c:502
mca_base_param_dump
OPAL_DECLSPEC int mca_base_param_dump(opal_list_t **info, bool internal)
Obtain a list of all the MCA parameters currently defined as well as their types. ...
Definition: mca_base_param.c:739
mca_base_param_find_int
OPAL_DECLSPEC int mca_base_param_find_int(const mca_base_component_t *component, const char *param_name, char **env, int *current_value)
Find an MCA parameter in an env array based on its names.
Definition: mca_base_param.c:2154
mca_base_param_find_string_name
OPAL_DECLSPEC int mca_base_param_find_string_name(const char *type, const char *param_name, char **env, char **current_value)
Find a string MCA parameter (in an env array) that is not associated with a component.
Definition: mca_base_param.c:2240
mca_base_param_info_t::super
opal_list_item_t super
So that we can be in a list.
Definition: mca_base_param.h:103
mca_base_param_reg_syn_name
OPAL_DECLSPEC int mca_base_param_reg_syn_name(int orignal_index, const char *syn_type, const char *syn_param_name, bool deprecated)
Register an MCA parameter synonym that is not associated with a component.
Definition: mca_base_param.c:476
mca_base_param_set_string
OPAL_DECLSPEC int mca_base_param_set_string(int index, char *value)
Sets an "override" value for an string MCA parameter.
Definition: mca_base_param.c:546
MCA_BASE_PARAM_SOURCE_MAX
Maximum source type.
Definition: mca_base_param.h:93
mca_base_param_type_t
mca_base_param_type_t
The types of MCA parameters.
Definition: mca_base_param.h:68
mca_base_param_reg_int
OPAL_DECLSPEC int mca_base_param_reg_int(const mca_base_component_t *component, const char *param_name, const char *help_msg, bool internal, bool read_only, int default_value, int *current_value)
Register an integer MCA parameter.
Definition: mca_base_param.c:297
mca_base_param_set_internal
OPAL_DECLSPEC int mca_base_param_set_internal(int index, bool internal)
Set the "internal" flag on an MCA parameter to true or false.
Definition: mca_base_param.c:707
mca_base_param_find_int_name
OPAL_DECLSPEC int mca_base_param_find_int_name(const char *type, const char *param_name, char **env, int *current_value)
Find an MCA parameter (in an env array) that is not associated with a component.
Definition: mca_base_param.c:2183
MCA_BASE_PARAM_TYPE_INT
The parameter is of type integer.
Definition: mca_base_param.h:70
mca_base_param_info_t::mbpp_param_name
char * mbpp_param_name
String name of the parameter of the parameter.
Definition: mca_base_param.h:115
mca_base_param_find_string
OPAL_DECLSPEC int mca_base_param_find_string(const mca_base_component_t *component, const char *param_name, char **env, char **current_value)
Find a string MCA parameter in an env array based on its names.
Definition: mca_base_param.c:2211
mca_base_param_env_var
OPAL_DECLSPEC char * mca_base_param_env_var(const char *param_name)
Get the string name corresponding to the MCA parameter value in the environment.
Definition: mca_base_param.c:607
MCA_BASE_PARAM_TYPE_MAX
Maximum parameter type.
Definition: mca_base_param.h:75
mca_base_param_info_t::mbpp_read_only
bool mbpp_read_only
Is this parameter changable?
Definition: mca_base_param.h:133