src/mca/mca.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2005 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2008-2012 Cisco Systems, Inc.  All rights reserved.
0014  * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
0015  *                         reserved.
0016  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0017  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0018  * $COPYRIGHT$
0019  *
0020  * Additional copyrights may follow
0021  *
0022  * $HEADER$
0023  */
0024 /**
0025  * @file
0026  *
0027  * Top-level interface for all pmix MCA components.
0028  */
0029
0030 #ifndef PMIX_MCA_H
0031 #define PMIX_MCA_H
0032
0033 #include "src/include/pmix_config.h"
0034
0035 /**
0036  * Common type for all MCA modules.
0037  *
0038  * An instance of this type is always the first element in MCA
0039  * modules, allowing the module to be associated with a
0040  * particular version of a specific framework, and to publish its own
0041  * name and version.
0042  */
0043 struct pmix_mca_base_module_2_0_0_t {
0044     int dummy_value;
0045 };
0046 /** Unversioned convenience typedef; use this name in
0047     frameworks/components to stay forward source-compatible */
0048 typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_t;
0049 /** Versioned convenience typedef */
0050 typedef struct pmix_mca_base_module_2_0_0_t pmix_mca_base_module_2_0_0_t;
0051
0052 /**
0053  * MCA component open function.
0054  *
0055  * @retval PMIX_SUCCESS This component can be used in the process.
0056  *
0057  * @retval PMIX_ERR_NOT_AVAILABLE Silently ignore this component for
0058  * the duration of the process (it may even be unloaded from the
0059  * process).
0060  *
0061  * @retval anything_else The MCA base will print an error message
0062  * ignore this component for the duration of the process (it may even
0063  * be unloaded from the process).
0064  *
0065  * All MCA components can have an "open" function that is invoked once
0066  * per process, when the component is located and loaded.
0067  *
0068  * This function should avoid registering MCA parameters (use the
0069  * component "register" function for that; i.e.,
0070  * mca_base_register_component_params_2_0_0_fn_t for that).  Legacy
0071  * components still register MCA params in their component "open"
0072  * function, but their authors should update them to use the component
0073  * "register" function.
0074  *
0075  * This function can also be used to allocate any resources necessary
0076  * for the component (e.g., heap memory).
0077  *
0078  * This function should return PMIX_SUCCESS if it wishes to remain
0079  * loaded in the process.  Any other return value will cause the MCA
0080  * base to unload the component.  Although most components do not use
0081  * this mechanism to force themselves to be unloaded (because if they
0082  * are immediately unloaded, ompi_info will not display them), the
0083  * mechanism is available should the need arise.
0084  *
0085  * If the component a) has no MCA parameters to register, b) no
0086  * resources to allocate, and c) can always be used in a process
0087  * (albeit perhaps not selected), it may provide NULL for this
0088  * function.  In this cause, the MCA will act as if it called the open
0089  * function and it returned PMIX_SUCCESS.
0090  */
0091 typedef int (*pmix_mca_base_open_component_1_0_0_fn_t)(void);
0092
0093 /**
0094  * MCA component close function.
0095  *
0096  * @retval PMIX_SUCCESS The component successfully shut down.
0097  *
0098  * @retval any_other_value Some error occurred, but is likely to be
0099  * ignored.
0100  *
0101  * This function is invoked on a component after all of its modules
0102  * have been finalized (according to the rules of its framework) and
0103  * the component will never be used in the process again; the
0104  * component may be unloaded from the process memory after the close
0105  * function has been invoked.
0106  *
0107  * This function is typically used to release any resources still in
0108  * use by the component.
0109  *
0110  * If the component has no resources to free, it may provide NULL for
0111  * this function.  In this case, the MCA will act as if it called the
0112  * close function and it returned PMIX_SUCCESS.
0113  */
0114 typedef int (*pmix_mca_base_close_component_1_0_0_fn_t)(void);
0115
0116 /**
0117  * MCA component query function.
0118  *
0119  * @retval PMIX_SUCCESS The component successfully queried.
0120  *
0121  * @retval any_other_value Some error occurred, but is likely to be
0122  * ignored.
0123  *
0124  * @param module The module to be used if this component is selected.
0125  *
0126  * @param priority The priority of this component.
0127  *
0128  * This function is used by the mca_base_select function to find the
0129  * highest priority component to select. Frameworks are free to
0130  * implement their own query function, but must also implement their
0131  * own select function as a result.
0132  */
0133 typedef int (*pmix_mca_base_query_component_2_0_0_fn_t)(pmix_mca_base_module_2_0_0_t **module,
0134                                                         int *priority);
0135
0136 /**
0137  * MCA component parameter registration function.
0138  *
0139  * @retval PMIX_SUCCESS This component successfully registered its
0140  * parameters and can be used in this process.
0141  * @retval PMIX_ERR_BAD_PARAM Indicates that the register function
0142  * failed because an MCA parameter got an invalid/incorrect value.
0143  *
0144  * @retval anything_else The MCA will ignore this component for the
0145  * duration of the process.
0146  *
0147  * If a component has a non-NULL parameter registration function, it
0148  * will be invoked to register all MCA parameters associated with the
0149  * component.  This function is invoked *before* the component "open"
0150  * function is invoked.
0151  *
0152  * The registration function should not allocate any resources that
0153  * need to be freed (aside from registering MCA parameters).
0154  * Specifically, strings that are passed to the MCA parameter
0155  * registration functions are all internally copied; there's no need
0156  * for the caller to keep them after registering a parameter.  Hence,
0157  * it is possible that the registration function will be the *only*
0158  * function invoked on a component; component authors should take care
0159  * that no resources are leaked in this case.
0160  *
0161  * This function should return PMIX_SUCCESS if it wishes to remain
0162  * loaded in the process.  Any other return value will cause the MCA
0163  * base to unload the component.  Although most components do not use
0164  * this mechanism to force themselves to be unloaded (because if they
0165  * are immediately unloaded, ompi_info will not display them), the
0166  * mechanism is available should the need arise.
0167  *
0168  * Note that if the function returns PMIX_ERR_BAD_PARAM, it is
0169  * possible (likely?) that the component didn't register all of its
0170  * parameters.  When this happens, ompi_info (and friends) will stop
0171  * execution and print out all existing registered parameters from the
0172  * entire framework (since ompi_info doesn't track individual
0173  * component register failures).  This allows a user to know exactly
0174  * what value is incorrect, and from where it was set (e.g., via an
0175  * MCA params file).
0176  *
0177  * If the component a) has no MCA parameters to register, b) no
0178  * resources to allocate, and c) can always be used in a process
0179  * (albeit perhaps not selected), it may provide NULL for this
0180  * function.  In this cause, the MCA will act as if it called the
0181  * registration function and it returned PMIX_SUCCESS.
0182  */
0183 typedef int (*pmix_mca_base_register_component_params_2_0_0_fn_t)(void);
0184
0185 /**
0186  * Maximum length of MCA project string names.
0187  */
0188 #define PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN 15
0189 /**
0190  * Maximum length of MCA framework string names.
0191  */
0192 #define PMIX_MCA_BASE_MAX_TYPE_NAME_LEN 31
0193 /**
0194  * Maximum length of MCA component string names.
0195  */
0196 #define PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN 63
0197
0198 /**
0199  * Common type for all MCA components.
0200  *
0201  * An instance of this type is always the first element in MCA
0202  * components, allowing the component to be associated with a
0203  * particular version of a specific framework, and to publish its own
0204  * name and version.
0205  */
0206 struct pmix_mca_base_component_2_1_0_t {
0207
0208     int pmix_mca_major_version;
0209     /**< Major number of the MCA. */
0210     int pmix_mca_minor_version;
0211     /**< Minor number of the MCA. */
0212     int pmix_mca_release_version;
0213     /**< Release number of the MCA. */
0214
0215     char pmix_mca_project_name[PMIX_MCA_BASE_MAX_PROJECT_NAME_LEN + 1];
0216     /**< String name of the project that this component belongs to. */
0217     int pmix_mca_project_major_version;
0218     /**< Major version number of the project that this component
0219        belongs to. */
0220     int pmix_mca_project_minor_version;
0221     /**< Minor version number of the project that this component
0222        belongs to. */
0223     int pmix_mca_project_release_version;
0224     /**< Release version number of the project that this component
0225        belongs to. */
0226
0227     char pmix_mca_type_name[PMIX_MCA_BASE_MAX_TYPE_NAME_LEN + 1];
0228     /**< String name of the framework that this component belongs to. */
0229     int pmix_mca_type_major_version;
0230     /**< Major version number of the framework that this component
0231        belongs to. */
0232     int pmix_mca_type_minor_version;
0233     /**< Minor version number of the framework that this component
0234        belongs to. */
0235     int pmix_mca_type_release_version;
0236     /**< Release version number of the framework that this component
0237        belongs to. */
0238
0239     char pmix_mca_component_name[PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN + 1];
0240     /**< This comopnent's string name. */
0241     int pmix_mca_component_major_version;
0242     /**< This component's major version number. */
0243     int pmix_mca_component_minor_version;
0244     /**< This component's minor version number. */
0245     int pmix_mca_component_release_version;
0246     /**< This component's release version number. */
0247
0248     pmix_mca_base_open_component_1_0_0_fn_t pmix_mca_open_component;
0249     /**< Method for opening this component. */
0250     pmix_mca_base_close_component_1_0_0_fn_t pmix_mca_close_component;
0251     /**< Method for closing this component. */
0252     pmix_mca_base_query_component_2_0_0_fn_t pmix_mca_query_component;
0253     /**< Method for querying this component. */
0254     pmix_mca_base_register_component_params_2_0_0_fn_t pmix_mca_register_component_params;
0255     /**< Method for registering the component's MCA parameters */
0256
0257     /** Extra space to allow for expansion in the future without
0258         breaking older components. */
0259     char reserved[32];
0260 };
0261 #define PMIX_BASE_COMPONENT_STATIC_INIT         \
0262 {                                               \
0263     .pmix_mca_major_version = 0,                \
0264     .pmix_mca_minor_version = 0,                \
0265     .pmix_mca_release_version = 0,              \
0266     .pmix_mca_project_name = {0},               \
0267     .pmix_mca_type_major_version = 0,           \
0268     .pmix_mca_type_minor_version = 0,           \
0269     .pmix_mca_type_release_version = 0,         \
0270     .pmix_mca_component_name = {0},             \
0271     .pmix_mca_component_major_version = 0,      \
0272     .pmix_mca_component_minor_version = 0,      \
0273     .pmix_mca_component_release_version = 0,    \
0274     .pmix_mca_open_component = NULL,            \
0275     .pmix_mca_close_component = NULL,           \
0276     .pmix_mca_query_component = NULL,           \
0277     .pmix_mca_register_component_params = NULL, \
0278     .reserved = {0}                             \
0279 }
0280 /** Unversioned convenience typedef; use this name in
0281     frameworks/components to stay forward source-compatible */
0282 typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_t;
0283 /** Versioned convenience typedef */
0284 typedef struct pmix_mca_base_component_2_1_0_t pmix_mca_base_component_2_1_0_t;
0285
0286 /**
0287  * Macro for framework author convenience.
0288  *
0289  * This macro is used by frameworks defining their component types,
0290  * indicating that they subscribe to the MCA version 2.0.0.  See
0291  * component header files (e.g., coll.h) for examples of its usage.
0292  */
0293 #define PMIX_MCA_BASE_VERSION_MAJOR   2
0294 #define PMIX_MCA_BASE_VERSION_MINOR   1
0295 #define PMIX_MCA_BASE_VERSION_RELEASE 0
0296
0297 #define PMIX_MCA_BASE_MAKE_VERSION(level, MAJOR, MINOR, RELEASE)                          \
0298     .pmix_mca_##level##_major_version = MAJOR, .pmix_mca_##level##_minor_version = MINOR, \
0299     .pmix_mca_##level##_release_version = RELEASE
0300
0301 #define PMIX_MCA_BASE_VERSION_2_1_0(PROJECT, project_major, project_minor, project_release, TYPE, \
0302                                     type_major, type_minor, type_release)                         \
0303     .pmix_mca_major_version = PMIX_MCA_BASE_VERSION_MAJOR,                                        \
0304     .pmix_mca_minor_version = PMIX_MCA_BASE_VERSION_MINOR,                                        \
0305     .pmix_mca_release_version = PMIX_MCA_BASE_VERSION_RELEASE, .pmix_mca_project_name = PROJECT,  \
0306     PMIX_MCA_BASE_MAKE_VERSION(project, project_major, project_minor, project_release),           \
0307     .pmix_mca_type_name = TYPE,                                                                   \
0308     PMIX_MCA_BASE_MAKE_VERSION(type, type_major, type_minor, type_release)
0309
0310 #define PMIX_MCA_BASE_VERSION_1_0_0(type, type_major, type_minor, type_release) \
0311     PMIX_MCA_BASE_VERSION_2_1_0("pmix", PMIX_MAJOR_VERSION, PMIX_MINOR_VERSION, \
0312                                 PMIX_RELEASE_VERSION, type, type_major, type_minor, type_release)
0313
0314 #endif /* PMIX_MCA_H */