OpenMPI 0.1.1

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

- File List
- Globals

Data Structures | Typedefs | Enumerations | Functions
mca_base_param.h File Reference

This file presents the MCA parameter interface. More...

`#include "opal_config.h"`
`#include "opal/class/opal_list.h"`
`#include "opal/mca/mca.h"`

Go to the source code of this file.

## Data Structures
struct | mca_base_param_info_t
| Struct for holding name/type info. More...

## Typedefs
typedef struct mca_base_param_info_t | mca_base_param_info_t
| Convenience typedef.

## Enumerations
enum | mca_base_param_type_t { MCA_BASE_PARAM_TYPE_INT, MCA_BASE_PARAM_TYPE_STRING, MCA_BASE_PARAM_TYPE_MAX }
| The types of MCA parameters. More...
enum | mca_base_param_source_t { MCA_BASE_PARAM_SOURCE_DEFAULT, MCA_BASE_PARAM_SOURCE_ENV, MCA_BASE_PARAM_SOURCE_FILE, MCA_BASE_PARAM_SOURCE_OVERRIDE, MCA_BASE_PARAM_SOURCE_MAX }
| Source of an MCA parameter's value. More...

## Functions
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_init (void)
| Initialize the MCA parameter system. More...
OPAL_DECLSPEC int | mca_base_param_recache_files (bool rel_path_search)
| Recache the MCA param files. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
OPAL_DECLSPEC int | mca_base_param_deregister (int index)
| Deregister a MCA parameter. More...
OPAL_DECLSPEC int | mca_base_param_lookup_int (int index, int *value)
| Look up an integer MCA parameter. More...
OPAL_DECLSPEC int | mca_base_param_lookup_string (int index, char **value)
| Look up a string MCA parameter. More...
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. More...
OPAL_DECLSPEC int | mca_base_param_set_int (int index, int value)
| Sets an "override" value for an integer MCA parameter. More...
OPAL_DECLSPEC int | mca_base_param_set_string (int index, char *value)
| Sets an "override" value for an string MCA parameter. More...
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(). More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
OPAL_DECLSPEC int | mca_base_param_set_internal (int index, bool internal)
| Set the "internal" flag on an MCA parameter to true or false. More...
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. More...
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. More...
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(). More...
OPAL_DECLSPEC int | mca_base_param_finalize (void)
| Shut down the MCA parameter system (normally only invoked by the MCA framework itself). More...
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)
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)
OPAL_DECLSPEC char * | mca_base_param_environ_variable (const char *type, const char *comp, const char *param)

## Detailed Description

This file presents the MCA parameter interface.

Note that there are two scopes for MCA parameters: "normal" and attributes. Specifically, all MCA parameters are "normal" – some are special and may also be found on attributes on communicators, datatypes, or windows.

In general, these functions are intended to be used as follows:

- Creating MCA parameters

1. Register a parameter, get an index back

- Using MCA parameters

1. Lookup a "normal" parameter value on a specific index, or
2. Lookup an attribute parameter on a specific index and communicator / datatype / window.

MCA parameters can be defined in multiple different places. As such, parameters are resolved to find their value. The order of resolution is as follows:

- An "override" location that is only available to be set via the mca_base_param API.
- Look for an environment variable corresponding to the MCA parameter.
- See if a file contains the MCA parameter (MCA parameter files are read only once – when the first time any mca_param_t function is invoked).
- If nothing else was found, use the parameter's default value.

Note that there is a second header file (mca_base_param_internal.h) that contains several internal type delcarations for the parameter system. The internal file is only used within the parameter system itself; it should not be required by any other Open MPI entities.

## Enumeration Type Documentation

enum mca_base_param_source_t

Source of an MCA parameter's value.

Enumerator
MCA_BASE_PARAM_SOURCE_DEFAULT | The default value.
MCA_BASE_PARAM_SOURCE_ENV | The value came from the environment (or command line!)
MCA_BASE_PARAM_SOURCE_FILE | The value came from a file.
MCA_BASE_PARAM_SOURCE_OVERRIDE | The value came a "set" API call.
MCA_BASE_PARAM_SOURCE_MAX | Maximum source type.

enum mca_base_param_type_t

The types of MCA parameters.

Enumerator
MCA_BASE_PARAM_TYPE_INT | The parameter is of type integer.
MCA_BASE_PARAM_TYPE_STRING | The parameter is of type string.
MCA_BASE_PARAM_TYPE_MAX | Maximum parameter type.

## Function Documentation

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.

Parameters

  env | [out] A pointer to an argv-style array of key=value strings, suitable for use in an environment
  num_env | [out] A pointer to an int, containing the length of the env array (not including the final NULL entry).
  internal | [in] Whether to include the internal parameters or not.

Return values

  OPAL_SUCCESS | Upon success.
  OPAL_ERROR | Upon failure.

This function is similar to mca_base_param_dump() except that its output is in terms of an argv-style array of key=value strings, suitable for using in an environment.

References mca_base_param_storage_t::intval, MCA_BASE_PARAM_TYPE_INT, MCA_BASE_PARAM_TYPE_STRING, opal_argv_append(), opal_argv_free(), and mca_base_param_storage_t::stringval.

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.

Parameters

  type_a | [in] Framework name of parameter A (string).
  component_a | [in] Component name of parameter A (string).
  param_a | [in] Parameter name of parameter A (string.
  type_b | [in] Framework name of parameter A (string).
  component_b | [in] Component name of parameter A (string).
  param_b | [in] Parameter name of parameter A (string.

This function is useful for checking that the user did not set both of 2 mutually-exclusive MCA parameters.

This function will print an opal_show_help() message and return OPAL_ERR_BAD_PARAM if it finds that the two parameters both have value sources that are not MCA_BASE_PARAM_SOURCE_DEFAULT. This means that both parameters have been set by the user (i.e., they're not default values).

Note that opal_show_help() allows itself to be hooked, so if this happens after the aggregated orte_show_help() system is initialized, the messages will be aggregated (w00t).

Returns
  OPAL_ERR_BAD_PARAM if the two parameters have sources that are not MCA_BASE_PARAM_SOURCE_DEFAULT.
  OPAL_SUCCESS otherwise.

References mca_base_param_find(), mca_base_param_lookup_source(), and MCA_BASE_PARAM_SOURCE_DEFAULT.

OPAL_DECLSPEC int mca_base_param_deregister | ( | int | index | ) |

Deregister a MCA parameter.

Parameters

  index | Index returned from mca_base_param_register_init()

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.

Parameters

  info | [out] An opal_list_t of mca_base_param_info_t instances.
  internal | [in] Whether to include the internal parameters or not.

Return values

  OPAL_SUCCESS | Upon success.
  OPAL_ERROR | Upon failure.

This function is used to obtain a list of all the currently registered MCA parameters along with their associated types (currently: string or integer). The results from this function can be used to repeatedly invoke mca_base_param_lookup_int() and/or mca_base_param_lookup_string() to obtain a comprehensive list of all MCA parameters and their current values.

Releasing the list, and all the items in the list, is a relatively complicated process. Use the companion function mca_base_param_dump_release() when finished with the returned info list to release all associated memory.

References mca_base_param_t::mbp_component_name, mca_base_param_t::mbp_deprecated, mca_base_param_t::mbp_full_name, mca_base_param_t::mbp_help_msg, mca_base_param_t::mbp_internal, mca_base_param_t::mbp_param_name, mca_base_param_t::mbp_read_only, mca_base_param_t::mbp_type, mca_base_param_t::mbp_type_name, mca_base_param_info_t::mbpp_component_name, mca_base_param_info_t::mbpp_deprecated, mca_base_param_info_t::mbpp_full_name, mca_base_param_info_t::mbpp_help_msg, mca_base_param_info_t::mbpp_index, mca_base_param_info_t::mbpp_internal, mca_base_param_info_t::mbpp_param_name, mca_base_param_info_t::mbpp_read_only, mca_base_param_info_t::mbpp_synonym_parent, mca_base_param_info_t::mbpp_synonyms, mca_base_param_info_t::mbpp_synonyms_len, mca_base_param_info_t::mbpp_type, mca_base_param_info_t::mbpp_type_name, opal_list_append, opal_list_get_end(), opal_list_get_first(), opal_list_get_next, opal_list_get_size(), and opal_list_is_empty().

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().

Parameters

  info | [in/out] An opal_list_t previously returned from mca_base_param_dump().

Return values

  OPAL_SUCCESS | Upon success.
  OPAL_ERROR | Upon failure.

This function is intended to be used to free the info list returned from mca_base_param_dump(). There are a bunch of strings and other associated memory in the list making it cumbersome for the caller to free it all properly. Hence, once the caller is finished with the info list, invoke this function and all memory associated with the list will be freed.

References OBJ_RELEASE, and opal_list_remove_first().

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.

Parameters

  param_name | Name of the type containing the parameter.

Return values

  string | A string suitable for setenv() or appending to an environ-style string array.
  NULL | Upon failure.

The string that is returned is owned by the caller; if appropriate, it must be eventually freed by the caller.

Referenced by parse_args().

OPAL_DECLSPEC char* mca_base_param_environ_variable | ( | const char * | type,
|  | const char * | comp,
|  | const char * | param
| ) |  |

Deprecated:

Get the string name corresponding to the MCA parameter value in the environment (deprecated).

Parameters

  type | Name of the type containing the parameter.
  comp | Name of the component containing the parameter.
  param | Name of the parameter.

Return values

  string | A string suitable for setenv() or appending to an environ-style string array.
  NULL | Upon failure.

This function is deprecated. Use mca_base_param_env_var() instead.

The string that is returned is owned by the caller; if appropriate, it must be eventually freed by the caller.

References mca_base_param_find().

Referenced by orte_plm_submit_launch().

OPAL_DECLSPEC int mca_base_param_finalize | ( | void |  | ) |

Shut down the MCA parameter system (normally only invoked by the MCA framework itself).

Returns
  OPAL_SUCCESS This function never fails.

This function shuts down the MCA parameter repository and frees all associated memory. No other mca_base_param*() functions can be invoked after this function.

This function is normally only invoked by the MCA framework itself when the process is shutting down (e.g., during MPI_FINALIZE). It is only documented here for completeness.

References OBJ_DESTRUCT, OBJ_RELEASE, and opal_list_remove_first().

Referenced by opal_finalize_util().

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.

Parameters

  type | Name of the type containing the parameter.
  component | Name of the component containing the parameter.
  param | Name of the parameter.

Return values

  OPAL_ERROR | If the parameter was not found.
  index | If the parameter was found.

It is not always convenient to widely propagate a parameter's index value, or it may be necessary to look up the parameter from a different component – where it is not possible to have the return value from mca_base_param_register_int() or mca_base_param_register_string(). This function can be used to look up the index of any registered parameter. The returned index can be used with mca_base_param_lookup_int() and mca_base_param_lookup_string().

Referenced by mca_base_param_check_exclusive_string(), mca_base_param_environ_variable(), mca_btl_ud_component_init(), mca_io_base_open(), ompi_init_preconnect_mpi(), ompi_mpi_init(), opal_carto_auto_detect_component_query(), opal_maffinity_first_use_component_query(), opal_memchecker_valgrind_component_query(), opal_progress_init(), and orte_plm_base_orted_append_basic_args().

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.

Parameters

  component | [in] Pointer to the component for which the parameter was registered.
  param_name | [in] The name of the parameter being registered (string).
  env | [in] NULL-terminated list of strings (e.g., from an environment).
  current_value | [out] Return the current value (if found).

Return values

  OPAL_ERROR | If the parameter was not found.

Look for a specific MCA parameter in an environment and return its value

References mca_base_component_2_0_0_t::mca_component_name, and mca_base_component_2_0_0_t::mca_type_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.

Parameters

  type | [in] Although this parameter is not associated with a component, it still must have a string type name that will act as a prefix (string).
  param_name | [in] The name of the parameter being registered (string).
  env | [in] NULL-terminated list of strings (e.g., from an environment).
  current_value | [out] Return the current value (if found).

Return values

  OPAL_ERROR | If the parameter was not found.

Look for a specific MCA parameter in an environment and return its value

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.

Parameters

  component | [in] Pointer to the component for which the parameter was registered.
  param_name | [in] The name of the parameter being registered (string).
  env | [in] NULL-terminated list of strings (e.g., from an environment).
  current_value | [out] Return the current value (if found).

Return values

  OPAL_ERROR | If the parameter was not found.

Look for a specific MCA parameter in an environment and return its value

References mca_base_component_2_0_0_t::mca_component_name, and mca_base_component_2_0_0_t::mca_type_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.

Parameters

  type | [in] Although this parameter is not associated with a component, it still must have a string type name that will act as a prefix (string).
  param_name | [in] The name of the parameter being registered (string).
  env | [in] NULL-terminated list of strings (e.g., from an environment).
  current_value | [out] Return the current value (if found).

Return values

  OPAL_ERROR | If the parameter was not found.

Look for a specific MCA parameter in an environment and return its value

OPAL_DECLSPEC int mca_base_param_init | ( | void |  | ) |

Initialize the MCA parameter system.

Return values

  OPAL_SUCCESS | This function initalizes the MCA parameter system. It is invoked internally (by mca_base_open()) and is only documented here for completeness.

References mca_base_param_recache_files(), and OBJ_CONSTRUCT.

Referenced by opal_init_util().

OPAL_DECLSPEC int mca_base_param_lookup_int | ( | int | index,
|  | int * | value
| ) |  |

Look up an integer MCA parameter.

Parameters

  index | Index previous returned from mca_base_param_register_int().
  value | Pointer to int where the parameter value will be stored.

Returns
  OPAL_ERROR Upon failure. The contents of value are undefined.
  OPAL_SUCCESS Upon success. value will be filled with the parameter's current value.

The value of a specific MCA parameter can be looked up using the return value from mca_base_param_register_int().

References mca_base_param_storage_t::intval.

Referenced by ompi_init_preconnect_mpi(), ompi_mpi_init(), opal_carto_auto_detect_component_query(), opal_dss_open(), opal_maffinity_first_use_component_query(), opal_memchecker_valgrind_component_query(), opal_progress_init(), and orte_rmaps_base_open().

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.

Parameters

  index | [in] Index of MCA parameter to set
  source | [out] Enum value indicating source
  source_file | [out] If value came from source, name of the file that set it. The caller should not modify or free this string. It is permissable to specify source_file==NULL if the caller does not care to know the filename.

Return values

  OPAL_ERROR | If the parameter was not found.
  OPAL_SUCCESS | Upon success.

This function looks up to see where the value of an MCA parameter came from.

Referenced by mca_base_param_check_exclusive_string().

OPAL_DECLSPEC int mca_base_param_lookup_string | ( | int | index,
|  | char ** | value
| ) |  |

Look up a string MCA parameter.

Parameters

  index | Index previous returned from mca_base_param_register_string().
  value | Pointer to (char *) where the parameter value will be stored.

Returns
  OPAL_ERROR Upon failure. The contents of value are undefined.
  OPAL_SUCCESS Upon success. value will be filled with the parameter's current value.

Note that if a string value is read in from a file then it will never be NULL. It will always have a value, even if that value is the empty string.

Strings returned in the value parameter should later be free()'ed.

The value of a specific MCA parameter can be looked up using the return value from mca_base_param_register_string().

References mca_base_param_storage_t::stringval.

Referenced by mca_btl_base_open(), mca_btl_ud_component_init(), mca_io_base_delete(), mca_io_base_file_select(), and orte_plm_base_orted_append_basic_args().

OPAL_DECLSPEC int mca_base_param_recache_files | ( | bool | rel_path_search | ) |

Recache the MCA param files.

Parameters

  rel_path_search | If a relative path is found, search the path even if the relative path in pointing to the current working directory.

Return values

  OPAL_SUCCESS |

References mca_base_param_reg_string_name(), and opal_output().

Referenced by mca_base_param_init().

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.

Parameters

  component | [in] Pointer to the component for which the parameter is being registered.
  param_name | [in] The name of the parameter being registered (string).
  help_msg | [in] A string describing the use and valid values of the parameter (string).
  internal | [in] Indicates whether the parameter is internal (i.e., not to be shown to users) or not (bool).
  read_only | [in] Indicates whether the parameter value can ever change (bool).
  default_value | [in] The value that is used for this parameter if the user does not supply one.
  current_value | [out] After registering the parameter, look up its current value and return it unless current_value is NULL.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_int() to retrieve the value of the parameter.

This function registers an integer MCA parameter and associates it with a specific component.

If the {component} pointer is not NULL, the type name and component name are automatically prefixed to the parameter name. Otherwise, the {param_name} is used as the full parameter name.

The {help_msg} is a string of arbitrary length (verbose is good!) for explaining what the parameter is for and what its valid values are. This message is used in help messages, such as the output from the ompi_info executable.

If {internal} is set to true, this parameter is not shown by default in the output of ompi_info. That is, this parameter is considered internal to the Open MPI implementation and is not supposed to be viewed / changed by the user.

If {read_only} is true, then the registered {default_value} will be the only value ever returned when this parameter is looked up. That is, command line, environment, and file overrides will be ignored. This is useful, for example, for reporting information to the user (e.g., the version of the GM library that was linked against).

If the {current_value} is not NULL, when the registration is complete, the parameter system will look up the current value of the parameter and return it in {current_value}.

References mca_base_param_storage_t::intval, MCA_BASE_PARAM_TYPE_INT, mca_base_component_2_0_0_t::mca_component_name, and mca_base_component_2_0_0_t::mca_type_name.

Referenced by mca_btl_elan_component_open(), mca_btl_self_component_open(), and orte_ras_gridengine_open().

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.

Parameters

  type | [in] Although this parameter is not associated with a component, it still must have a string type name that will act as a prefix (string).
  param_name | [in] The name of the parameter being registered (string).
  help_msg | [in] A string describing the use and valid values of the parameter (string).
  internal | [in] Indicates whether the parameter is internal (i.e., not to be shown to users) or not (bool).
  read_only | [in] Indicates whether the parameter value can ever change (bool).
  default_value | [in] The value that is used for this parameter if the user does not supply one.
  current_value | [out] After registering the parameter, look up its current value and return it unless current_value is NULL.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_string() to retrieve the value of the parameter.

This function is identical to mca_base_param_reg_int() except that it registers parameters that are not associated with components. For example, it can be used to register parameters associated with a framework base or an overall layer (e.g., the MPI layer, or the MCA base system framework itself). Typical "type" strings are:

"mca": for the MCA base framework itself framework name: for any given framework "mpi": for parameters that apply to the overall MPI layer "orte": for parameters that apply to the overall ORTE layer "btl": for parameters to the OMPI BTL framework ...etc.

Note that the type should always be a framework or a level name (e.g., "btl" or "mpi") – it should not include the component name, even if the component is the base of a framework. Hence, "btl_base" is not a valid type name. Specifically, registering a parameter with an unrecognized type is not an error, but ompi_info has a hard-coded list of frameworks and levels; parameters that have recongized types, although they can be used by the user, will not be displayed by ompi_info.

Note that if you use mca_base_param_find() to lookup the index of the registered parameter, the "component" argument should be NULL (because it is not specified in this registration function, and is therefore registered with a NULL value).

References mca_base_param_storage_t::intval, and MCA_BASE_PARAM_TYPE_INT.

Referenced by mca_btl_base_open(), mca_io_base_open(), ompi_mpi_finalize(), ompi_mpi_init(), ompi_op_base_open(), opal_cr_init(), opal_register_params(), orte_ess_base_open(), orte_odls_base_open(), orte_plm_base_open(), orte_ras_base_open(), orte_register_params(), and orte_rmaps_base_open().

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.

Parameters

  component | [in] Pointer to the component for which the parameter is being registered.
  param_name | [in] The name of the parameter being registered (string).
  help_msg | [in] A string describing the use and valid values of the parameter (string).
  internal | [in] Indicates whether the parameter is internal (i.e., not to be shown to users) or not (bool).
  read_only | [in] Indicates whether the parameter value can ever change (bool).
  default_value | [in] The value that is used for this parameter if the user does not supply one.
  current_value | [out] After registering the parameter, look up its current value and return it unless current_value is NULL.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_string() to retrieve the value of the parameter.

Note that if a string value is read in from a file then it will never be NULL. It will always have a value, even if that value is the empty string.

NOTE: Strings returned in the current_value parameter should later be free()'ed.

This function is identical to mca_base_param_reg_int() except that you are registering a string parameter with an associated string default value (which is not allowed to be NULL). See mca_base_param_reg_int() for all other details.

References MCA_BASE_PARAM_TYPE_STRING, mca_base_component_2_0_0_t::mca_component_name, mca_base_component_2_0_0_t::mca_type_name, and mca_base_param_storage_t::stringval.

Referenced by mca_btl_elan_component_open().

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.

Parameters

  type | [in] Although this parameter is not associated with a component, it still must have a string type name that will act as a prefix (string).
  param_name | [in] The name of the parameter being registered (string).
  help_msg | [in] A string describing the use and valid values of the parameter (string).
  internal | [in] Indicates whether the parameter is internal (i.e., not to be shown to users) or not (bool).
  read_only | [in] Indicates whether the parameter value can ever change (bool).
  default_value | [in] The value that is used for this parameter if the user does not supply one.
  current_value | [out] After registering the parameter, look up its current value and return it unless current_value is NULL.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_string() to retrieve the value of the parameter.

Note that if a string value is read in from a file then it will never be NULL. It will always have a value, even if that value is the empty string.

This function is identical to mca_base_param_reg_string() except that it registers parameters that are not associated with components. For example, it can be used to register parameters associated with a framework base or an overall layer (e.g., the MPI layer, or the MCA base system framework itself). Typical "type" strings are:

"mca": for the MCA base framework itself framework name: for any given framework "mpi": for parameters that apply to the overall MPI layer "orte": for parameters that apply to the overall ORTE layer "btl": for parameters to the OMPI BTL framework ...etc.

Note that the type should always be a framework or a level name (e.g., "btl" or "mpi") – it should not include the component name, even if the component is the base of a framework. Hence, "btl_base" is not a valid type name. Specifically, registering a parameter with an unrecognized type is not an error, but ompi_info has a hard-coded list of frameworks and levels; parameters that have recongized types, although they can be used by the user, will not be displayed by ompi_info.

Note that if you use mca_base_param_find() to lookup the index of the registered parameter, the "component" argument should be NULL (because it is not specified in this registration function, and is therefore registered with a NULL value).

References MCA_BASE_PARAM_TYPE_STRING, and mca_base_param_storage_t::stringval.

Referenced by mca_base_param_recache_files(), ompi_mpi_init(), ompi_wait_for_debugger(), opal_cr_init(), opal_register_params(), orte_ess_base_orted_setup(), orte_notifier_base_open(), orte_register_params(), orte_rmaps_base_open(), orte_rml_base_open(), and orte_rml_base_select().

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.

Parameters

  original_index | [in] The index of the original parameter to create a synonym for.
  syn_component | [in] Pointer to the component for which the synonym is being registered.
  syn_param_name | [in] Parameter name of the synonym to be created (string)
  deprecated | If true, a warning will be shown if this synonym is used to set the parameter's value (unless the warnings are silenced)

Returns
  OPAL_SUCCESS Upon success.
  OPAL_ERR_BAD_PARAM If the index value is invalid.
  OPAL_ERROR Otherwise

Upon success, this function creates a synonym MCA parameter that will be treated almost exactly like the original. The type (int or string) is irrelevant; this function simply creates a new name that by which the same parameter value is accessible.

Note that the original parameter name has precendence over all synonyms. For example, consider the case if parameter is originally registered under the name "A" and is later registered with synonyms "B" and "C". If the user sets values for both MCA parameter names "A" and "B", the value associated with the "A" name will be used and the value associated with the "B" will be ignored (and will not even be visible by the mca_base_param_*() API). If the user sets values for both MCA parameter names "B" and "C" (and does not set a value for "A"), it is undefined as to which value will be used.

References mca_base_component_2_0_0_t::mca_component_name, and mca_base_component_2_0_0_t::mca_type_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.

Parameters

  original_index | [in] The index of the original parameter to create a synonym for.
  type | [in] Although this synonym is not associated with a component, it still must have a string type name that will act as a prefix (string).
  syn_param_name | [in] Parameter name of the synonym to be created (string)
  deprecated | If true, a warning will be shown if this synonym is used to set the parameter's value (unless the warnings are silenced)

Essentially the same as mca_base_param_reg_syn(), but using a type name instead of a component.

See mca_base_param_reg_int_name() for guidence on type string values.

Referenced by orte_rmaps_base_open().

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
| ) |  |

Deprecated:

Register an integer MCA parameter (deprecated).

Parameters

  type_name | [in] The MCA type (string).
  component_name | [in] The name of the component (string).
  param_name | [in] The name of the parameter being registered (string).
  mca_param_name | [in] Optional parameter to override the user-visible name of this parameter (string).
  default_value | [in] The value that is used for this parameter if the user does not supply one.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_int() to retrieve the value of the parameter.

This function is deprecated. Use mca_base_param_reg_int() instead.

This function registers an integer MCA parameter and associates it with a specific component.

The default resulting MCA parameter name is {type_name}[_{component_name}][_{param_name}].

{component_name} is only included if it is non-NULL. All components an should include their name; component frameworks should pass "base". It is only permissible for the MCA base itself to pass NULL for the component_name.

Likewise, {param_name} is also only included if it is non-NULL. Components and frameworks can pass NULL for this parameter if they wish.

In most cases, mca_param_name should be NULL, in which case the user-visible name of this parameter will be the default form (as described above). Only in rare cases is it necessary (or advisable) to override the default name – its use is strongly discouraged.

It is permissable to register a (type_name, component_name, param_name) triple more than once; the same index value will be returned, but the default value will be changed to reflect the last registration.

References mca_base_param_storage_t::intval, and MCA_BASE_PARAM_TYPE_INT.

Referenced by opal_dss_open().

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
| ) |  |

Deprecated:

Register a string MCA parameter (deprecated).

Parameters

  type_name | [in] The MCA type (string).
  component_name | [in] The name of the component (string).
  param_name | [in] The name of the parameter being registered (string).
  mca_param_name | [in] Optional parameter to override the user-visible name of this parameter (string).
  default_value | [in] The value that is used for this parameter if the user does not supply one.

Return values

  OPAL_ERROR | Upon failure to register the parameter.
  index | Index value that can be used with mca_base_param_lookup_string() to retrieve the value of the parameter.

This function is deprecated. Use mca_base_param_reg_string() instead.

Note that if a string value is read in from a file then it will never be NULL. It will always have a value, even if that value is the empty string.

This function is identical to mca_base_param_register_int() except that you are registering a string parameter with an associated string default value (which is not allowed to be NULL). See mca_base_param_register_int() for all other details.

References MCA_BASE_PARAM_TYPE_STRING, and mca_base_param_storage_t::stringval.

Referenced by mca_btl_base_open().

OPAL_DECLSPEC int mca_base_param_set_int | ( | int | index,
|  | int | value
| ) |  |

Sets an "override" value for an integer MCA parameter.

Parameters

  index | [in] Index of MCA parameter to set
  value | [in] The integer value to set

Return values

  OPAL_ERROR | If the parameter was not found.
  OPAL_SUCCESS | Upon success.

This function sets an integer value on the MCA parameter indicated by the index value index. This value will be used in lieu of any other value from any other MCA source (environment variable, file, etc.) until the value is unset with mca_base_param_unset().

This function may be invoked multiple times; each time, the last "set" value is replaced with the newest value.

References mca_base_param_storage_t::intval, MCA_BASE_PARAM_TYPE_INT, and mca_base_param_unset().

OPAL_DECLSPEC int mca_base_param_set_internal | ( | int | index,
|  | bool | internal
| ) |  |

Set the "internal" flag on an MCA parameter to true or false.

Parameters

  index | [in] Index previous returned from mca_base_param_register_string() or mca_base_param_register_int().
  internal | [in] Boolean indicating whether the MCA parameter is internal (private) or public.

Returns
  OPAL_SUCCESS If it can find the parameter to reset
  OPAL_ERROR Otherwise

"Internal" MCA parameters are ones that are not intentended to be seen or modified by users or user applications. These include values that are set at run time, such as TCP ports, IP addresses, etc. By setting the "internal" flag, internal MCA parameters are not displayed during the output of ompi_info and MPI_INIT (at least, they're not displayed by default), thus keeping them away from prying user eyes.

References mca_base_param_t::mbp_internal.

OPAL_DECLSPEC int mca_base_param_set_string | ( | int | index,
|  | char * | value
| ) |  |

Sets an "override" value for an string MCA parameter.

Parameters

  index | [in] Index of MCA parameter to set
  value | [in] The string value to set

Return values

  OPAL_ERROR | If the parameter was not found.
  OPAL_SUCCESS | Upon success.

This function sets a string value on the MCA parameter indicated by the index value index. This value will be used in lieu of any other value from any other MCA source (environment variable, file, etc.) until the value is unset with mca_base_param_unset().

The string is copied by value; the string "value" parameter does not become "owned" by the parameter subsystem.

This function may be invoked multiple times; each time, the last "set" value is replaced with the newest value (the old value is discarded).

References MCA_BASE_PARAM_TYPE_STRING, mca_base_param_unset(), and mca_base_param_storage_t::stringval.

Referenced by ompi_mpi_init().

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().

Parameters

  index | [in] Index of MCA parameter to set

Return values

  OPAL_ERROR | If the parameter was not found.
  OPAL_SUCCESS | Upon success.

Resets previous value that was set (if any) on the given MCA parameter.

References mca_base_param_t::mbp_override_value, mca_base_param_t::mbp_override_value_set, MCA_BASE_PARAM_TYPE_STRING, and mca_base_param_storage_t::stringval.

Referenced by mca_base_param_set_int(), and mca_base_param_set_string().