mca_base_param.h

MPI stands for the Message Passing Interface. Written by the MPI Forum (a large committee comprising

     * @param internal [in] Indicates whether the parameter is internal
     * (i.e., not to be shown to users) or not (bool).
     * @param read_only [in] Indicates whether the parameter value can
     * ever change (bool).
     * @param default_value [in] The value that is used for this
     * parameter if the user does not supply one.
     * @param current_value [out] After registering the parameter, look
     * up its current value and return it unless current_value is
     * NULL.
     *
     * @retval OPAL_ERROR Upon failure to register the parameter.
     * @retval 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_int() except
     * that you are registering a string parameter with an associated
     * string default value (which is \em not allowed to be NULL).
     * See mca_base_param_reg_int() for all other details.
     */
    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 that is not associated with a
     * component.
     *
     * @param 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 param_name [in] The name of the parameter being
     * registered (string).
     * @param help_msg [in] A string describing the use and valid
     * values of the parameter (string).
     * @param internal [in] Indicates whether the parameter is internal
     * (i.e., not to be shown to users) or not (bool).
     * @param read_only [in] Indicates whether the parameter value can
     * ever change (bool).
     * @param default_value [in] The value that is used for this
     * parameter if the user does not supply one.
     * @param current_value [out] After registering the parameter, look
     * up its current value and return it unless current_value is
     * NULL.
     *
     * @retval OPAL_ERROR Upon failure to register the parameter.
     * @retval 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 componet 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).
     */
    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);

    /**
     * Associate a communicator/datatype/window keyval with an MCA
     * parameter.
     *
     * @param index The index of the parameter to use.
     * @param keyval The keyval to associate it with.
     *
     * @returns OPAL_SUCCESS Upon success.
     * @returns OPAL_ERROR If the index value is invalid.
     *
     * For an index value that was previously returned by
     * mca_base_param_register_int() or
     * mca_base_param_register_string(), the corresponding MCA parameter
     * can be associated with a communicator, datatype, or window
     * attribute keyval.  
     *
     * After using this function, you can use any of the four lookup
     * functions (mca_base_param_lookup_int(),
     * mca_base_param_lookup_string(), mca_base_param_kv_lookup_int(),
     * and mca_base_param_kv_lookup_string()), but only the "kv"
     * versions will cross reference and attempt to find parameter
     * values on attributes.
     */
    OPAL_DECLSPEC int mca_base_param_kv_associate(int index, int keyval);

    /**
     * Look up an integer MCA parameter.
     *
     * @param index Index previous returned from
     * mca_base_param_register_int().
     * @param value Pointer to int where the parameter value will be
     * stored.
     *
     * @return OPAL_ERROR Upon failure.  The contents of value are
     * undefined.
     * @return 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().
     */
    OPAL_DECLSPEC int mca_base_param_lookup_int(int index, int *value);
    
    /**
     * Look up an integer MCA parameter, to include looking in
     * attributes.
     *
     * @param index Index previous returned from
     * mca_base_param_register_int().
     * @param attrs Object containing attributes to be searched.
     * @param value Pointer to int where the parameter value will
     * be stored.
     *
     * @return OPAL_ERROR Upon failure.  The contents of value are
     * undefined.
     * @return OPAL_SUCCESS Upon success.  value will be filled with the
     * parameter's current value.
     *
     * This function is identical to mca_base_param_lookup_int() except
     * that it looks in attributes \em first to find the parameter
     * value.  The function mca_base_param_kv_associate() must have been
     * called first to associate a keyval with the index.
     */
    OPAL_DECLSPEC int mca_base_param_kv_lookup_int(int index,
                                                   struct opal_hash_table_t *attrs, 
                                                   int *value);
    
    /**
     * Look up a string MCA parameter.
     *
     * @param index Index previous returned from
     * mca_base_param_register_string().
     * @param value Pointer to (char *) where the parameter value will be
     * stored.
     *
     * @return OPAL_ERROR Upon failure.  The contents of value are
     * undefined.
     * @return 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 returns in the \em 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().
     */
    OPAL_DECLSPEC int mca_base_param_lookup_string(int index, char **value);

    /**
     * Look up a string MCA parameter, to include looking in attributes.
     *
     * @param index [in] Index previous returned from
     * mca_base_param_register_string().
     * @param attrs [in] Object containing attributes to be searched.
     * @param value [out] Pointer to (char *) where the parameter value
     * will be stored.
     *
     * @return OPAL_ERROR Upon failure.  The contents of value are
     * undefined.
     * @return OPAL_SUCCESS Upon success.  value will be filled with the
     * parameter's current value.
     *
     * This function is identical to mca_base_param_lookup_string()
     * except that it looks in attributes \em first to find the
     * parameter value.  The function mca_base_param_kv_associate() must
     * have been called first to associate a keyval with the index.
     */
    OPAL_DECLSPEC int mca_base_param_kv_lookup_string(int index, 
                                                      struct opal_hash_table_t *attrs, 
                                                      char **value);

    /**
     * Sets an "override" value for an integer MCA parameter.
     *
     * @param index [in] Index of MCA parameter to set
     * @param value [in] The integer value to set
     *
     * @retval OPAL_ERROR If the parameter was not found.
     * @retval OPAL_SUCCESS Upon success.
     *
     * This function sets an integer value on the MCA parmeter
     * 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.
     */
    OPAL_DECLSPEC int mca_base_param_set_int(int index, int value);

    /**
     * Sets an "override" value for an string MCA parameter.
     *
     * @param index [in] Index of MCA parameter to set
     * @param value [in] The string value to set
     *
     * @retval OPAL_ERROR If the parameter was not found.
     * @retval OPAL_SUCCESS Upon success.
     *
     * This function sets a string value on the MCA parmeter
     * 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).
     */
    OPAL_DECLSPEC int mca_base_param_set_string(int index, char *value);

    /**
     * Unset a parameter that was previously set by
     * mca_base_param_set_int() or mca_base_param_set_string().
     *
     * @param index [in] Index of MCA parameter to set
     *
     * @retval OPAL_ERROR If the parameter was not found.
     * @retval OPAL_SUCCESS Upon success.
     *
     * Resets previous value that was set (if any) on the given MCA