mca/base/pmix_base.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-2007 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) 2009      Cisco Systems, Inc.  All rights reserved.
0014  * Copyright (c) 2013-2015 Los Alamos National Security, LLC. All rights
0015  *                         reserved.
0016  * Copyright (c) 2015      Research Organization for Information Science
0017  *                         and Technology (RIST). All rights reserved.
0018  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0019  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0020  * $COPYRIGHT$
0021  *
0022  * Additional copyrights may follow
0023  *
0024  * $HEADER$
0025  */
0026
0027 #ifndef PMIX_MCA_BASE_H
0028 #define PMIX_MCA_BASE_H
0029
0030 #include "src/include/pmix_config.h"
0031
0032 #include "src/class/pmix_list.h"
0033 #include "src/class/pmix_object.h"
0034
0035 /*
0036  * These units are large enough to warrant their own .h files
0037  */
0038 #include "src/mca/base/pmix_mca_base_framework.h"
0039 #include "src/mca/base/pmix_mca_base_var.h"
0040 #include "src/mca/mca.h"
0041 #include "src/util/pmix_cmd_line.h"
0042 #include "src/util/pmix_output.h"
0043
0044 BEGIN_C_DECLS
0045
0046 /*
0047  * Structure for making plain lists of components
0048  */
0049 struct pmix_mca_base_component_list_item_t {
0050     pmix_list_item_t super;
0051     const pmix_mca_base_component_t *cli_component;
0052 };
0053 typedef struct pmix_mca_base_component_list_item_t pmix_mca_base_component_list_item_t;
0054 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_list_item_t);
0055
0056 /*
0057  * Structure for making priority lists of components
0058  */
0059 struct pmix_mca_base_component_priority_list_item_t {
0060     pmix_mca_base_component_list_item_t super;
0061     int cpli_priority;
0062 };
0063 typedef struct pmix_mca_base_component_priority_list_item_t
0064     pmix_mca_base_component_priority_list_item_t;
0065
0066 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_priority_list_item_t);
0067
0068 /*
0069  * Public variables
0070  */
0071 PMIX_EXPORT extern char *pmix_mca_base_component_path;
0072 PMIX_EXPORT extern char *pmix_mca_base_component_show_load_errors;
0073 PMIX_EXPORT extern bool pmix_mca_base_component_abort_on_load_error;
0074 PMIX_EXPORT extern bool pmix_mca_base_component_track_load_errors;
0075 PMIX_EXPORT extern bool pmix_mca_base_component_disable_dlopen;
0076 PMIX_EXPORT extern char *pmix_mca_base_system_default_path;
0077 PMIX_EXPORT extern char *pmix_mca_base_user_default_path;
0078
0079 /*
0080  * Standard verbosity levels
0081  */
0082 enum {
0083     /** total silence */
0084     PMIX_MCA_BASE_VERBOSE_NONE = -1,
0085     /** only errors are printed */
0086     PMIX_MCA_BASE_VERBOSE_ERROR = 0,
0087     /** emit messages about component selection, open, and unloading */
0088     PMIX_MCA_BASE_VERBOSE_COMPONENT = 10,
0089     /** also emit warnings */
0090     PMIX_MCA_BASE_VERBOSE_WARN = 20,
0091     /** also emit general, user-relevant information, such as rationale as to why certain choices
0092      * or code paths were taken, information gleaned from probing the local system, etc. */
0093     PMIX_MCA_BASE_VERBOSE_INFO = 40,
0094     /** also emit relevant tracing information (e.g., which functions were invoked /
0095      * call stack entry/exit info) */
0096     PMIX_MCA_BASE_VERBOSE_TRACE = 60,
0097     /** also emit PMIX-developer-level (i.e,. highly detailed) information */
0098     PMIX_MCA_BASE_VERBOSE_DEBUG = 80,
0099     /** also output anything else that might be useful */
0100     PMIX_MCA_BASE_VERBOSE_MAX = 100,
0101 };
0102
0103 /*
0104  * Public functions
0105  */
0106
0107 /**
0108  * First function called in the MCA.
0109  *
0110  * @return PMIX_SUCCESS Upon success
0111  * @return PMIX_ERROR Upon failure
0112  *
0113  * This function starts up the entire MCA.  It initializes a bunch
0114  * of built-in MCA parameters, and initialized the MCA component
0115  * repository.
0116  *
0117  * It must be the first MCA function invoked.  It is normally
0118  * invoked during the initialization stage and specifically
0119  * invoked in the special case of the *_info command.
0120  */
0121 PMIX_EXPORT int pmix_mca_base_open(const char *add_path);
0122
0123 /**
0124  * Last function called in the MCA
0125  *
0126  * @return PMIX_SUCCESS Upon success
0127  * @return PMIX_ERROR Upon failure
0128  *
0129  * This function closes down the entire MCA.  It clears all MCA
0130  * parameters and closes down the MCA component repository.
0131  *
0132  * It must be the last MCA function invoked.  It is normally invoked
0133  * during the finalize stage.
0134  */
0135 PMIX_EXPORT int pmix_mca_base_close(void);
0136
0137 /**
0138  * A generic select function
0139  *
0140  */
0141 PMIX_EXPORT int pmix_mca_base_select(const char *type_name, int output_id,
0142                                      pmix_list_t *components_available,
0143                                      pmix_mca_base_module_t **best_module,
0144                                      pmix_mca_base_component_t **best_component, int *priority_out);
0145
0146 /**
0147  * A function for component query functions to discover if they have
0148  * been explicitly required to or requested to be selected.
0149  *
0150  * exclusive: If the specified component is the only component that is
0151  *            available for selection.
0152  *
0153  */
0154 PMIX_EXPORT int pmix_mca_base_is_component_required(pmix_list_t *components_available,
0155                                                     pmix_mca_base_component_t *component,
0156                                                     bool exclusive, bool *is_required);
0157
0158 /* pmix_mca_base_component_compare.c */
0159
0160 PMIX_EXPORT int
0161 pmix_mca_base_component_compare_priority(pmix_mca_base_component_priority_list_item_t *a,
0162                                          pmix_mca_base_component_priority_list_item_t *b);
0163 PMIX_EXPORT int pmix_mca_base_component_compare(const pmix_mca_base_component_t *a,
0164                                                 const pmix_mca_base_component_t *b);
0165 PMIX_EXPORT int pmix_mca_base_component_compatible(const pmix_mca_base_component_t *a,
0166                                                    const pmix_mca_base_component_t *b);
0167 PMIX_EXPORT char *pmix_mca_base_component_to_string(const pmix_mca_base_component_t *a);
0168
0169 /* pmix_mca_base_component_find.c */
0170
0171 PMIX_EXPORT int pmix_mca_base_component_find(const char *directory,
0172                                              pmix_mca_base_framework_t *framework,
0173                                              bool ignore_requested, bool open_dso_components);
0174
0175 /**
0176  * Parse the requested component string and return an pmix_argv of the requested
0177  * (or not requested) components.
0178  */
0179 PMIX_EXPORT int pmix_mca_base_component_parse_requested(const char *requested, bool *include_mode,
0180                                                         char ***requested_component_names);
0181
0182 /**
0183  * Filter a list of components based on a comma-delimted list of names
0184  *
0185  * @param[in] framework
0186  *
0187  * @returns PMIX_SUCCESS On success
0188  * @returns PMIX_ERR_NOT_FOUND If some component in {filter_names} is not found in
0189  * {components}. Does not apply to negated filters.
0190  * @returns pmix error code On other error.
0191  *
0192  * This function closes and releases any components that do not match the filter_name and
0193  * filter flags.
0194  */
0195 PMIX_EXPORT int pmix_mca_base_components_filter(pmix_mca_base_framework_t *framework);
0196
0197 /* Safely release some memory allocated by pmix_mca_base_component_find()
0198    (i.e., is safe to call even if you never called
0199    pmix_mca_base_component_find()). */
0200 PMIX_EXPORT int pmix_mca_base_component_find_finalize(void);
0201
0202 /* pmix_mca_base_components_register.c */
0203 PMIX_EXPORT int
0204 pmix_mca_base_framework_components_register(struct pmix_mca_base_framework_t *framework,
0205                                             pmix_mca_base_register_flag_t flags);
0206
0207 /* pmix_mca_base_components_open.c */
0208 PMIX_EXPORT int pmix_mca_base_show_load_errors_init(void);
0209 PMIX_EXPORT int pmix_mca_base_show_load_errors_finalize(void);
0210 PMIX_EXPORT bool pmix_mca_base_show_load_errors(const char *framework_name,
0211                                                 const char *component_name);
0212 PMIX_EXPORT int pmix_mca_base_framework_components_open(struct pmix_mca_base_framework_t *framework,
0213                                                         pmix_mca_base_open_flag_t flags);
0214
0215 PMIX_EXPORT int pmix_mca_base_components_open(const char *type_name, int output_id,
0216                                               const pmix_mca_base_component_t **static_components,
0217                                               pmix_list_t *components_available,
0218                                               bool open_dso_components);
0219
0220 /* pmix_mca_base_components_close.c */
0221 /**
0222  * Close and release a component.
0223  *
0224  * @param[in] component Component to close
0225  * @param[in] output_id Output id for debugging output
0226  *
0227  * After calling this function the component may no longer be used.
0228  */
0229 PMIX_EXPORT void pmix_mca_base_component_close(const pmix_mca_base_component_t *component,
0230                                                int output_id);
0231
0232 /**
0233  * Release a component without closing it.
0234  * @param[in] component Component to close
0235  * @param[in] output_id Output id for debugging output
0236  *
0237  * After calling this function the component may no longer be used.
0238  */
0239 PMIX_EXPORT void pmix_mca_base_component_unload(const pmix_mca_base_component_t *component,
0240                                                 int output_id);
0241
0242 PMIX_EXPORT int pmix_mca_base_components_close(int output_id, pmix_list_t *components_available,
0243                                                const pmix_mca_base_component_t *skip);
0244
0245 PMIX_EXPORT int
0246 pmix_mca_base_framework_components_close(struct pmix_mca_base_framework_t *framework,
0247                                          const pmix_mca_base_component_t *skip);
0248
0249 END_C_DECLS
0250
0251 #endif /* MCA_BASE_H */