The new MCA param API has been committed. I request that you start
converting over your components to use this API as soon as convenient
-- for one thing, the [new] ability to pass in a help string describing
the parameter is a major benefit to users (and forgetful developers ;-)
).
There are 2 main functions (one for int, one for string -- they're both
similar, so I'll just show the int function):
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);
Everything is documented in opal/mca/base/mca_base_param.h (doxygen),
but here's the quick version:
- This function is slightly different in name from the old functions
("reg" vs. "register"); the old functions still exist so that we don't
break the code base. However, I'd like to remove the old ones someday
in the not-distant future (and therefore get rid of the
similar-but-different function names).
- You pass in a pointer to the component and the param name. The
framework and component name are derived from the component pointer.
- It is strongly advised to supply a help string that describes what
the parameter is, how it is used, and what its legal values are (don't
worry about word wrapping -- just one long string is fine). This
string will be displayed in ompi_info output.
- You can set the param to be "internal", meaning that it won't be
displayed in ompi_info (by default), and also set it to be "read_only",
meaning that it's considered to be information only and cannot be
changed at run time (e.g., a string indicating what version of GM the
GM BTL component was linked against).
- Finally, if you supply a non-NULL pointer for current_value, it will
lookup the current value and return it to you. This prevents you from
needing to do a two step register-then-lookup, as we have done in many
of the components.
The string version is essentially the same -- just s/int/string/ in the
function name and change the "int" params to "char *".
There's also 2 functions for non-component-related parameters (e.g.,
MPI-layer parameters; they take char*'s for the type name instead of a
pointer to the component) -- mca_base_param_reg_{int|string}_name().
See mca_base_param.h for details.
--
{+} Jeff Squyres
{+} The Open MPI Project
{+} http://www.open-mpi.org/
