mca_base_param.h

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

/*
 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
 *                         University Research and Technology
 *                         Corporation.  All rights reserved.
 * Copyright (c) 2004-2006 The University of Tennessee and The University
 *                         of Tennessee Research Foundation.  All rights
 *                         reserved.
 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, 
 *                         University of Stuttgart.  All rights reserved.
 * Copyright (c) 2004-2005 The Regents of the University of California.
 *                         All rights reserved.
 * $COPYRIGHT$
 * 
 * Additional copyrights may follow
 * 
 * $HEADER$
 */

/** @file 
 * 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
 * -# Register a parameter, get an index back
 * -# Optionally associate that index with an attribute keyval
 * - Using MCA parameters
 * -# Lookup a "normal" parameter value on a specific index, or
 * -# 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 \em 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.
 * - If the parameter has an MPI attribute keyval associated with it,
 *   see if there is a value assigned that can be used.
 * - 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.
 */

#ifndef OMPI_MCA_BASE_PARAM_H
#define OMPI_MCA_BASE_PARAM_H

#include "opal_config.h"

#include "opal/class/opal_value_array.h"
#include "opal/class/opal_list.h"
#include "opal/class/opal_hash_table.h"
#include "opal/mca/mca.h"


/**
 * The types of MCA parameters.
 */
typedef enum {
    /** The parameter is of type integer. */
    MCA_BASE_PARAM_TYPE_INT,
    /** The parameter is of type string. */
    MCA_BASE_PARAM_TYPE_STRING,
    
    /** Maximum parameter type. */
    MCA_BASE_PARAM_TYPE_MAX
} mca_base_param_type_t;


/**
 * Struct for holding name/type info.  Used in mca_base_param_dump(),
 * below.
 */
struct mca_base_param_info_t {
    /** So that we can be in a list */
    opal_list_item_t super;

    /** Index of this parameter */
    int mbpp_index;
    /** Enum indicating the back-end type of the parameter */
    mca_base_param_type_t mbpp_type;

    /** String name of the type of this component */
    char *mbpp_type_name;
    /** String name of the component of the parameter */
    char *mbpp_component_name;
    /** String name of the parameter of the parameter */
    char *mbpp_param_name;
    /** Full, assembled parameter name */
    char *mbpp_full_name;

    /** Is this value changable? */
    bool mbpp_read_only;
    /** Help message associated with this parameter */
    char *mbpp_help_msg;
};
/**
 * Convenience typedef
 */
typedef struct mca_base_param_info_t mca_base_param_info_t;

/*
 * Global functions for MCA
 */

#if defined(c_plusplus) || defined(__cplusplus)
extern "C" {
#endif
    /**
     * Make a real object for the info
     */
    OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_param_info_t);

    /**
     * Initialize the MCA parameter system.
     *
     * @retval OPAL_SUCCESS
     *
     * This function initalizes the MCA parameter system.  It is
     * invoked internally (by mca_base_open()) and is only documented
     * here for completeness.
     */
    OPAL_DECLSPEC int mca_base_param_init(void);

    /**
     * Register an integer MCA parameter.
     *
     * @param component [in] Pointer to the componet for which the
     * parameter is being registered (string), or NULL.
     * @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_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 now 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}.
     */
    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 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.
     *
     * 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 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_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 a string MCA parameter.
     *
     * @param component [in] Pointer to the componet for which the
     * parameter is being registered (string), or NULL.
     * @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).