openpmix-src 0.1.0-rc.1

/* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
/*
 * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
 *                         University Research and Technology
 *                         Corporation.  All rights reserved.
 * Copyright (c) 2004-2005 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 (c) 2008-2012 Cisco Systems, Inc.  All rights reserved.
 * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
 *                         reserved.
 * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
 * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
 * $COPYRIGHT$
 *
 * Additional copyrights may follow
 *
 * $HEADER$
 */
/**
 * @file
 *
 * Top-level interface for all pmix MCA components.
 */

#ifndef PMIX_MCA_H
#define PMIX_MCA_H

#include "src/include/pmix_config.h"

/**
 * Common type for all MCA modules.
 *
 * An instance of this type is always the first element in MCA
 * modules, allowing the module to be associated with a
 * particular version of a specific framework, and to publish its own
 * name and version.
 */
struct pmix_mca_base_module_2_0_0_t {
    int dummy_value;
};
/** Unversioned convenience typedef; use this name in
    frameworks/components to stay forward source-compatible */
typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_t;
/** Versioned convenience typedef */
typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_2_0_0_t;

/**
 * MCA component open function.
 *
 * @retval PMIX_SUCCESS This component can be used in the process.
 *
 * @retval PMIX_ERR_NOT_AVAILABLE Silently ignore this component for
 * the duration of the process (it may even be unloaded from the
 * process).
 *
 * @retval anything_else The MCA base will print an error message
 * ignore this component for the duration of the process (it may even
 * be unloaded from the process).
 *
 * All MCA components can have an "open" function that is invoked once
 * per process, when the component is located and loaded.
 *
 * This function should avoid registering MCA parameters (use the
 * component "register" function for that; i.e.,
 * mca_base_register_component_params_2_0_0_fn_t for that).  Legacy
 * components still register MCA params in their component "open"
 * function, but their authors should update them to use the component
 * "register" function.
 *
 * This function can also be used to allocate any resources necessary
 * for the component (e.g., heap memory).
 *
 * This function should return PMIX_SUCCESS if it wishes to remain
 * loaded in the process.  Any other return value will cause the MCA
 * base to unload the component.  Although most components do not use
 * this mechanism to force themselves to be unloaded (because if they
 * are immediately unloaded, ompi_info will not display them), the
 * mechanism is available should the need arise.
 *
 * If the component a) has no MCA parameters to register, b) no
 * resources to allocate, and c) can always be used in a process
 * (albeit perhaps not selected), it may provide NULL for this
 * function.  In this cause, the MCA will act as if it called the open
 * function and it returned PMIX_SUCCESS.
 */
typedef int (*pmix_mca_base_open_component_1_0_0_fn_t)(void);

/**
 * MCA component close function.
 *
 * @retval PMIX_SUCCESS The component successfully shut down.
 *
 * @retval any_other_value Some error occurred, but is likely to be
 * ignored.
 *
 * This function is invoked on a component after all of its modules
 * have been finalized (according to the rules of its framework) and
 * the component will never be used in the process again; the
 * component may be unloaded from the process memory after the close
 * function has been invoked.
 *
 * This function is typically used to release any resources still in
 * use by the component.
 *
 * If the component has no resources to free, it may provide NULL for
 * this function.  In this case, the MCA will act as if it called the
 * close function and it returned PMIX_SUCCESS.
 */
typedef int (*pmix_mca_base_close_component_1_0_0_fn_t)(void);

/**
 * MCA component query function.
 *
 * @retval PMIX_SUCCESS The component successfully queried.
 *
 * @retval any_other_value Some error occurred, but is likely to be
 * ignored.
 *
 * @param module The module to be used if this component is selected.
 *
 * @param priority The priority of this component.
 *
 * This function is used by the mca_base_select function to find the
 * highest priority component to select. Frameworks are free to
 * implement their own query function, but must also implement their
 * own select function as a result.
 */
typedef int (*pmix_mca_base_query_component_2_0_0_fn_t)(pmix_mca_base_module_2_0_0_t **module,
                                                        int *priority);

/**
 * MCA component parameter registration function.
 *
 * @retval PMIX_SUCCESS This component successfully registered its
 * parameters and can be used in this process.
 * @retval PMIX_ERR_BAD_PARAM Indicates that the register function
 * failed because an MCA parameter got an invalid/incorrect value.
 *
 * @retval anything_else The MCA will ignore this component for the
 * duration of the process.
 *
 * If a component has a non-NULL parameter registration function, it
 * will be invoked to register all MCA parameters associated with the
 * component.  This function is invoked *before* the component "open"
 * function is invoked.
 *
 * The registration function should not allocate any resources that
 * need to be freed (aside from registering MCA parameters).
 * Specifically, strings that are passed to the MCA parameter
 * registration functions are all internally copied; there's no need
 * for the caller to keep them after registering a parameter.  Hence,
 * it is possible that the registration function will be the *only*
 * function invoked on a component; component authors should take care
 * that no resources are leaked in this case.
 *
 * This function should return PMIX_SUCCESS if it wishes to remain
 * loaded in the process.  Any other return value will cause the MCA
 * base to unload the component.  Although most components do not use
 * this mechanism to force themselves to be unloaded (because if they
 * are immediately unloaded, ompi_info will not display them), the
 * mechanism is available should the need arise.
 *
 * Note that if the function returns PMIX_ERR_BAD_PARAM, it is
 * possible (likely?) that the component didn't register all of its
 * parameters.  When this happens, ompi_info (and friends) will stop
 * execution and print out all existing registered parameters from the
 * entire framework (since ompi_info doesn't track individual
 * component register failures).  This allows a user to know exactly
 * what value is incorrect, and from where it was set (e.g., via an
 * MCA params file).
 *
 * If the component a) has no MCA parameters to register, b) no
 * resources to allocate, and c) can always be used in a process
 * (albeit perhaps not selected), it may provide NULL for this
 * function.  In this cause, the MCA will act as if it called the
 * registration function and it returned PMIX_SUCCESS.
 */
typedef int (*pmix_mca_base_register_component_params_2_0_0_fn_t)(void);

/**
 * Maximum length of MCA project string names.
 */
#define PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN 15
/**
 * Maximum length of MCA framework string names.
 */
#define PMIX_MCA_BASE_MAX_TYPE_NAME_LEN 31
/**
 * Maximum length of MCA component string names.
 */
#define PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN 63

/**
 * Common type for all MCA components.
 *
 * An instance of this type is always the first element in MCA
 * components, allowing the component to be associated with a
 * particular version of a specific framework, and to publish its own
 * name and version.
 */
struct pmix_mca_base_component_2_1_0_t {

    int pmix_mca_major_version;
    /**< Major number of the MCA. */
    int pmix_mca_minor_version;
    /**< Minor number of the MCA. */
    int pmix_mca_release_version;
    /**< Release number of the MCA. */

    char pmix_mca_project_name[PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN + 1];
    /**< String name of the project that this component belongs to. */
    int pmix_mca_project_major_version;
    /**< Major version number of the project that this component
       belongs to. */
    int pmix_mca_project_minor_version;
    /**< Minor version number of the project that this component
       belongs to. */
    int pmix_mca_project_release_version;
    /**< Release version number of the project that this component
       belongs to. */

    char pmix_mca_type_name[PMIX_MCA_BASE_MAX_TYPE_NAME_LEN + 1];
    /**< String name of the framework that this component belongs to. */
    int pmix_mca_type_major_version;
    /**< Major version number of the framework that this component
       belongs to. */
    int pmix_mca_type_minor_version;
    /**< Minor version number of the framework that this component
       belongs to. */
    int pmix_mca_type_release_version;
    /**< Release version number of the framework that this component
       belongs to. */

    char pmix_mca_component_name[PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN + 1];
    /**< This comopnent's string name. */
    int pmix_mca_component_major_version;
    /**< This component's major version number. */
    int pmix_mca_component_minor_version;
    /**< This component's minor version number. */
    int pmix_mca_component_release_version;
    /**< This component's release version number. */

    pmix_mca_base_open_component_1_0_0_fn_t pmix_mca_open_component;
    /**< Method for opening this component. */
    pmix_mca_base_close_component_1_0_0_fn_t pmix_mca_close_component;
    /**< Method for closing this component. */
    pmix_mca_base_query_component_2_0_0_fn_t pmix_mca_query_component;
    /**< Method for querying this component. */
    pmix_mca_base_register_component_params_2_0_0_fn_t pmix_mca_register_component_params;
    /**< Method for registering the component's MCA parameters */

    /** Extra space to allow for expansion in the future without
        breaking older components. */
    char reserved[32];
};
#define PMIX_BASE_COMPONENT_STATIC_INIT         \
{                                               \
    .pmix_mca_major_version = 0,                \
    .pmix_mca_minor_version = 0,                \
    .pmix_mca_release_version = 0,              \
    .pmix_mca_project_name = {0},               \
    .pmix_mca_type_major_version = 0,           \
    .pmix_mca_type_minor_version = 0,           \
    .pmix_mca_type_release_version = 0,         \
    .pmix_mca_component_name = {0},             \
    .pmix_mca_component_major_version = 0,      \
    .pmix_mca_component_minor_version = 0,      \
    .pmix_mca_component_release_version = 0,    \
    .pmix_mca_open_component = NULL,            \
    .pmix_mca_close_component = NULL,           \
    .pmix_mca_query_component = NULL,           \
    .pmix_mca_register_component_params = NULL, \
    .reserved = {0}                             \
}
/** Unversioned convenience typedef; use this name in
    frameworks/components to stay forward source-compatible */
typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_t;
/** Versioned convenience typedef */
typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_2_1_0_t;

/**
 * Macro for framework author convenience.
 *
 * This macro is used by frameworks defining their component types,
 * indicating that they subscribe to the MCA version 2.0.0.  See
 * component header files (e.g., coll.h) for examples of its usage.
 */
#define PMIX_MCA_BASE_VERSION_MAJOR   2
#define PMIX_MCA_BASE_VERSION_MINOR   1
#define PMIX_MCA_BASE_VERSION_RELEASE 0

#define PMIX_MCA_BASE_MAKE_VERSION(level, MAJOR, MINOR, RELEASE)                          \
    .pmix_mca_##level##_major_version = MAJOR, .pmix_mca_##level##_minor_version = MINOR, \
    .pmix_mca_##level##_release_version = RELEASE

#define PMIX_MCA_BASE_VERSION_2_1_0(PROJECT, project_major, project_minor, project_release, TYPE, \
                                    type_major, type_minor, type_release)                         \
    .pmix_mca_major_version = PMIX_MCA_BASE_VERSION_MAJOR,                                        \
    .pmix_mca_minor_version = PMIX_MCA_BASE_VERSION_MINOR,                                        \
    .pmix_mca_release_version = PMIX_MCA_BASE_VERSION_RELEASE, .pmix_mca_project_name = PROJECT,  \
    PMIX_MCA_BASE_MAKE_VERSION(project, project_major, project_minor, project_release),           \
    .pmix_mca_type_name = TYPE,                                                                   \
    PMIX_MCA_BASE_MAKE_VERSION(type, type_major, type_minor, type_release)

#define PMIX_MCA_BASE_VERSION_1_0_0(type, type_major, type_minor, type_release) \
    PMIX_MCA_BASE_VERSION_2_1_0("pmix", PMIX_MAJOR_VERSION, PMIX_MINOR_VERSION, \
                                PMIX_RELEASE_VERSION, type, type_major, type_minor, type_release)

#endif /* PMIX_MCA_H */