OpenMPI  0.1.1
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. */
71  /** The parameter is of type string. */
73 
74  /** Maximum parameter type. */
77 
78 
79 /**
80  * Source of an MCA parameter's value
81  */
82 typedef enum {
83  /** The default value */
85  /** The value came from the environment (or command line!) */
87  /** The value came from a file */
89  /** The value came a "set" API call */
91 
92  /** Maximum source type */
95 
96 
97 /**
98  * Struct for holding name/type info. Used in mca_base_param_dump(),
99  * below.
100  */
102  /** So that we can be in a list */
104 
105  /** Index of this parameter */
107  /** Enum indicating the back-end type of the parameter */
109 
110  /** String name of the type of this component */
112  /** String name of the component of the parameter */
114  /** String name of the parameter of the parameter */
116  /** Full, assembled parameter name */
118 
119  /** Is this parameter deprecated? */
121 
122  /** Array of pointers of synonyms of this parameter */
124  /** Length of mbpp_synonyms array */
126  /** Back pointer to another mca_base_param_info_t that *this*
127  param is a synonym of (or NULL) */
129 
130  /** Is this parameter internal? */
132  /** Is this parameter changable? */
134  /** Help message associated with this parameter */
136 };
137 /**
138  * Convenience typedef
139  */
141 
142 /*
143  * Global functions for MCA
144  */
145 
146 BEGIN_C_DECLS
147 
148  /**
149  * Make a real object for the info
150  */
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 */
Struct for holding name/type info.
Definition: mca_base_param.h:101
int mbpp_synonyms_len
Length of mbpp_synonyms array.
Definition: mca_base_param.h:125
Common type for all MCA components.
Definition: mca.h:250
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
The value came a "set" API call.
Definition: mca_base_param.h:90
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
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
OPAL_DECLSPEC int mca_base_param_recache_files(bool rel_path_search)
Recache the MCA param files.
Definition: mca_base_param.c:179
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
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
int mbpp_index
Index of this parameter.
Definition: mca_base_param.h:106
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
OPAL_DECLSPEC char * mca_base_param_environ_variable(const char *type, const char *comp, const char *param)
Definition: mca_base_param.c:619
The opal_list_t interface is used to provide a generic doubly-linked list container for Open MPI...
BEGIN_C_DECLS OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_param_info_t)
Make a real object for the info.
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
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
Top-level interface for all MCA components.
Definition: opal_list.h:98
char * mbpp_component_name
String name of the component of the parameter.
Definition: mca_base_param.h:113
bool mbpp_deprecated
Is this parameter deprecated?
Definition: mca_base_param.h:120
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
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
The default value.
Definition: mca_base_param.h:84
OPAL_DECLSPEC int mca_base_param_deregister(int index)
Deregister a MCA parameter.
Definition: mca_base_param.c:515
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
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
The parameter is of type string.
Definition: mca_base_param.h:72
The value came from the environment (or command line!)
Definition: mca_base_param.h:86
OPAL_DECLSPEC int mca_base_param_init(void)
Initialize the MCA parameter system.
Definition: mca_base_param.c:156
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
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
char * mbpp_full_name
Full, assembled parameter name.
Definition: mca_base_param.h:117
struct mca_base_param_info_t ** mbpp_synonyms
Array of pointers of synonyms of this parameter.
Definition: mca_base_param.h:123
OPAL_DECLSPEC int mca_base_param_lookup_int(int index, int *value)
Look up an integer MCA parameter.
Definition: mca_base_param.c:487
bool mbpp_internal
Is this parameter internal?
Definition: mca_base_param.h:131
char * mbpp_help_msg
Help message associated with this parameter.
Definition: mca_base_param.h:135
char * mbpp_type_name
String name of the type of this component.
Definition: mca_base_param.h:111
mca_base_param_source_t
Source of an MCA parameter's value.
Definition: mca_base_param.h:82
Definition: opal_list.h:147
mca_base_param_type_t mbpp_type
Enum indicating the back-end type of the parameter.
Definition: mca_base_param.h:108
The value came from a file.
Definition: mca_base_param.h:88
OPAL_DECLSPEC int mca_base_param_lookup_string(int index, char **value)
Look up a string MCA parameter.
Definition: mca_base_param.c:531
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
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
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
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
opal_list_item_t super
So that we can be in a list.
Definition: mca_base_param.h:103
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
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
Maximum source type.
Definition: mca_base_param.h:93
mca_base_param_type_t
The types of MCA parameters.
Definition: mca_base_param.h:68
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
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
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
The parameter is of type integer.
Definition: mca_base_param.h:70
char * mbpp_param_name
String name of the parameter of the parameter.
Definition: mca_base_param.h:115
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
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
Maximum parameter type.
Definition: mca_base_param.h:75
bool mbpp_read_only
Is this parameter changable?
Definition: mca_base_param.h:133