Open MPI logo

Open MPI Development Mailing List Archives

  |   Home   |   Support   |   FAQ   |   all Development mailing list

From: Jeffrey Squyres (jsquyres_at_[hidden])
Date: 2005-08-03 09:22:27

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