mca/base/pmix_mca_base_framework.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2012-2015 Los Alamos National Security, LLC. All rights
0004  *                         reserved.
0005  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0006  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0007  * $COPYRIGHT$
0008  *
0009  * Additional copyrights may follow
0010  *
0011  * $HEADER$
0012  */
0013
0014 #if !defined(PMIX_MCA_BASE_FRAMEWORK_H)
0015 #    define PMIX_MCA_BASE_FRAMEWORK_H
0016 #    include "src/include/pmix_config.h"
0017
0018 #    include "src/class/pmix_list.h"
0019 #    include "src/mca/mca.h"
0020
0021 /*
0022  * Register and open flags
0023  */
0024 enum pmix_mca_base_register_flag_t {
0025     PMIX_MCA_BASE_REGISTER_DEFAULT = 0,
0026     /** Register all components (ignore selection MCA variables) */
0027     PMIX_MCA_BASE_REGISTER_ALL = 1,
0028     /** Do not register DSO components */
0029     PMIX_MCA_BASE_REGISTER_STATIC_ONLY = 2
0030 };
0031
0032 typedef enum pmix_mca_base_register_flag_t pmix_mca_base_register_flag_t;
0033
0034 enum pmix_mca_base_open_flag_t {
0035     PMIX_MCA_BASE_OPEN_DEFAULT = 0,
0036     /** Find components in pmix_mca_base_components_find. Used by
0037      pmix_mca_base_framework_open() when NOREGISTER is specified
0038      by the framework */
0039     PMIX_MCA_BASE_OPEN_FIND_COMPONENTS = 1,
0040     /** Do not open DSO components */
0041     PMIX_MCA_BASE_OPEN_STATIC_ONLY = 2,
0042 };
0043
0044 typedef enum pmix_mca_base_open_flag_t pmix_mca_base_open_flag_t;
0045
0046 /**
0047  * Register the MCA framework parameters
0048  *
0049  * @param[in] flags Registration flags (see mca/base/pmix_base.h)
0050  *
0051  * @retval PMIX_SUCCESS on success
0052  * @retval pmix error code on failure
0053  *
0054  * This function registers all framework MCA parameters. This
0055  * function should not call pmix_mca_base_framework_components_register().
0056  *
0057  * Frameworks are NOT required to provide this function. It
0058  * may be NULL.
0059  */
0060 typedef int (*pmix_mca_base_framework_register_params_fn_t)(pmix_mca_base_register_flag_t flags);
0061
0062 /**
0063  * Initialize the MCA framework
0064  *
0065  * @retval PMIX_SUCCESS Upon success
0066  * @retval PMIX_ERROR Upon failure
0067  *
0068  * This must be the first function invoked in the MCA framework.
0069  * It initializes the MCA framework, finds and opens components,
0070  * populates the components list, etc.
0071  *
0072  * This function is invoked during pmix_init() and during the
0073  * initialization of the special case of the ompi_info command.
0074  *
0075  * This function fills in the components framework value, which
0076  * is a list of all components that were successfully opened.
0077  * This variable should \em only be used by other framework base
0078  * functions or by ompi_info -- it is not considered a public
0079  * interface member -- and is only mentioned here for completeness.
0080  *
0081  * Any resources allocated by this function must be freed
0082  * in the framework close function.
0083  *
0084  * Frameworks are NOT required to provide this function. It may
0085  * be NULL. If a framework does not provide an open function the
0086  * default behavior of pmix_mca_base_framework_open() is to call
0087  * pmix_mca_base_framework_components_open(). If a framework provides
0088  * an open function it will need to call pmix_mca_base_framework_components_open()
0089  * if it needs to open any components.
0090  */
0091 typedef int (*pmix_mca_base_framework_open_fn_t)(pmix_mca_base_open_flag_t flags);
0092
0093 /**
0094  * Shut down the MCA framework.
0095  *
0096  * @retval PMIX_SUCCESS Always
0097  *
0098  * This function should shut downs everything in the MCA
0099  * framework, and is called during pmix_finalize() and the
0100  * special case of the ompi_info command.
0101  *
0102  * It must be the last function invoked on the MCA framework.
0103  *
0104  * Frameworks are NOT required to provide this function. It may
0105  * be NULL. If a framework does not provide a close function the
0106  * default behavior of pmix_mca_base_framework_close() is to call
0107  * pmix_mca_base_framework_components_close(). If a framework provide
0108  * a close function it will need to call pmix_mca_base_framework_components_close()
0109  * if any components were opened.
0110  */
0111 typedef int (*pmix_mca_base_framework_close_fn_t)(void);
0112
0113 typedef enum {
0114     PMIX_MCA_BASE_FRAMEWORK_FLAG_DEFAULT = 0,
0115     /** Don't register any variables for this framework */
0116     PMIX_MCA_BASE_FRAMEWORK_FLAG_NOREGISTER = 1,
0117     /** Internal. Don't set outside pmix_mca_base_framework.h */
0118     PMIX_MCA_BASE_FRAMEWORK_FLAG_REGISTERED = 2,
0119     /** Framework does not have any DSO components */
0120     PMIX_MCA_BASE_FRAMEWORK_FLAG_NO_DSO = 4,
0121     /** Internal. Don't set outside pmix_mca_base_framework.h */
0122     PMIX_MCA_BASE_FRAMEWORK_FLAG_OPEN = 8,
0123     /**
0124      * The upper 16 bits are reserved for project specific flags.
0125      */
0126 } pmix_mca_base_framework_flags_t;
0127
0128 typedef struct pmix_mca_base_framework_t {
0129     /** Project name for this component (ex "pmix") */
0130     char *framework_project;
0131     /** Framework name */
0132     char *framework_name;
0133     /** Description of this framework or NULL */
0134     const char *framework_description;
0135     /** Framework register function or NULL if the framework
0136         and all its components have nothing to register */
0137     pmix_mca_base_framework_register_params_fn_t framework_register;
0138     /** Framework open function or NULL */
0139     pmix_mca_base_framework_open_fn_t framework_open;
0140     /** Framework close function or NULL */
0141     pmix_mca_base_framework_close_fn_t framework_close;
0142     /** Framework flags (future use) set to 0 */
0143     pmix_mca_base_framework_flags_t framework_flags;
0144     /** Framework open count */
0145     int framework_refcnt;
0146     /** List of static components */
0147     const pmix_mca_base_component_t **framework_static_components;
0148     /** Component selection. This will be registered with the MCA
0149         variable system and should be either NULL (all components) or
0150         a heap allocated, comma-delimited list of components. */
0151     char *framework_selection;
0152     /** Verbosity level (0-100) */
0153     int framework_verbose;
0154     /** Pmix output for this framework (or -1) */
0155     int framework_output;
0156     /** List of selected components (filled in by pmix_mca_base_framework_register()
0157         or pmix_mca_base_framework_open() */
0158     pmix_list_t framework_components;
0159     /** List of components that failed to load */
0160     pmix_list_t framework_failed_components;
0161 } pmix_mca_base_framework_t;
0162
0163 /**
0164  * Register a framework with MCA.
0165  *
0166  * @param[in] framework framework to register
0167  *
0168  * @retval PMIX_SUCCESS Upon success
0169  * @retval PMIX_ERROR Upon failure
0170  *
0171  * Call a framework's register function.
0172  */
0173 PMIX_EXPORT int pmix_mca_base_framework_register(pmix_mca_base_framework_t *framework,
0174                                                  pmix_mca_base_register_flag_t flags);
0175
0176 /**
0177  * Open a framework
0178  *
0179  * @param[in] framework framework to open
0180  *
0181  * @retval PMIX_SUCCESS Upon success
0182  * @retval PMIX_ERROR Upon failure
0183  *
0184  * Call a framework's open function.
0185  */
0186 PMIX_EXPORT int pmix_mca_base_framework_open(pmix_mca_base_framework_t *framework,
0187                                              pmix_mca_base_open_flag_t flags);
0188
0189 /**
0190  * Close a framework
0191  *
0192  * @param[in] framework framework to close
0193  *
0194  * @retval PMIX_SUCCESS Upon success
0195  * @retval PMIX_ERROR Upon failure
0196  *
0197  * Call a framework's close function.
0198  */
0199 PMIX_EXPORT int pmix_mca_base_framework_close(pmix_mca_base_framework_t *framework);
0200
0201 /**
0202  * Check if a framework is already registered
0203  *
0204  * @param[in] framework framework to query
0205  *
0206  * @retval true if the framework's mca variables are registered
0207  * @retval false if not
0208  */
0209 PMIX_EXPORT bool pmix_mca_base_framework_is_registered(struct pmix_mca_base_framework_t *framework);
0210
0211 /**
0212  * Check if a framework is already open
0213  *
0214  * @param[in] framework framework to query
0215  *
0216  * @retval true if the framework is open
0217  * @retval false if not
0218  */
0219 PMIX_EXPORT bool pmix_mca_base_framework_is_open(struct pmix_mca_base_framework_t *framework);
0220
0221 /**
0222  * Macro to declare an MCA framework
0223  *
0224  * Example:
0225  *  PMIX_MCA_BASE_FRAMEWORK_DECLARE(pmix, foo, NULL, pmix_foo_open, pmix_foo_close,
0226  * MCA_BASE_FRAMEWORK_FLAG_LAZY)
0227  */
0228 #    define PMIX_MCA_BASE_FRAMEWORK_DECLARE(project, name, description, registerfn, openfn, \
0229                                             closefn, static_components, flags)              \
0230         pmix_mca_base_framework_t project##_##name##_base_framework                         \
0231             = {.framework_project = #project,                                               \
0232                .framework_name = #name,                                                     \
0233                .framework_description = description,                                        \
0234                .framework_register = registerfn,                                            \
0235                .framework_open = openfn,                                                    \
0236                .framework_close = closefn,                                                  \
0237                .framework_flags = flags,                                                    \
0238                .framework_refcnt = 0,                                                       \
0239                .framework_static_components = static_components,                            \
0240                .framework_selection = NULL,                                                 \
0241                .framework_verbose = 0,                                                      \
0242                .framework_output = -1}
0243
0244 #endif /* PMIX_MCA_BASE_FRAMEWORK_H */