root/opal/mca/pmix/pmix4x/pmix/src/mca/base/base.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   2 /*
   3  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
   4  *                         University Research and Technology
   5  *                         Corporation.  All rights reserved.
   6  * Copyright (c) 2004-2007 The University of Tennessee and The University
   7  *                         of Tennessee Research Foundation.  All rights
   8  *                         reserved.
   9  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
  10  *                         University of Stuttgart.  All rights reserved.
  11  * Copyright (c) 2004-2005 The Regents of the University of California.
  12  *                         All rights reserved.
  13  * Copyright (c) 2009      Cisco Systems, Inc.  All rights reserved.
  14  * Copyright (c) 2013-2015 Los Alamos National Security, LLC. All rights
  15  *                         reserved.
  16  * Copyright (c) 2015      Research Organization for Information Science
  17  *                         and Technology (RIST). All rights reserved.
  18  * Copyright (c) 2016-2017 Intel, Inc. All rights reserved.
  19  * $COPYRIGHT$
  20  *
  21  * Additional copyrights may follow
  22  *
  23  * $HEADER$
  24  */
  25 
  26 #ifndef PMIX_MCA_BASE_H
  27 #define PMIX_MCA_BASE_H
  28 
  29 #include <src/include/pmix_config.h>
  30 
  31 #include "src/class/pmix_object.h"
  32 #include "src/class/pmix_list.h"
  33 
  34 /*
  35  * These units are large enough to warrant their own .h files
  36  */
  37 #include "src/mca/mca.h"
  38 #include "src/mca/base/pmix_mca_base_var.h"
  39 #include "src/mca/base/pmix_mca_base_framework.h"
  40 #include "src/util/cmd_line.h"
  41 #include "src/util/output.h"
  42 
  43 BEGIN_C_DECLS
  44 
  45 /*
  46  * Structure for making plain lists of components
  47  */
  48 struct pmix_mca_base_component_list_item_t {
  49     pmix_list_item_t super;
  50     const pmix_mca_base_component_t *cli_component;
  51 };
  52 typedef struct pmix_mca_base_component_list_item_t pmix_mca_base_component_list_item_t;
  53 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_list_item_t);
  54 
  55 /*
  56  * Structure for making priority lists of components
  57  */
  58 struct pmix_mca_base_component_priority_list_item_t {
  59     pmix_mca_base_component_list_item_t super;
  60     int cpli_priority;
  61 };
  62 typedef struct pmix_mca_base_component_priority_list_item_t
  63     pmix_mca_base_component_priority_list_item_t;
  64 
  65 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_priority_list_item_t);
  66 
  67 /*
  68  * Public variables
  69  */
  70 PMIX_EXPORT extern char *pmix_mca_base_component_path;
  71 PMIX_EXPORT extern bool pmix_mca_base_component_show_load_errors;
  72 PMIX_EXPORT extern bool pmix_mca_base_component_track_load_errors;
  73 PMIX_EXPORT extern bool pmix_mca_base_component_disable_dlopen;
  74 PMIX_EXPORT extern char *pmix_mca_base_system_default_path;
  75 PMIX_EXPORT extern char *pmix_mca_base_user_default_path;
  76 
  77 /*
  78  * Standard verbosity levels
  79  */
  80 enum {
  81     /** total silence */
  82     PMIX_MCA_BASE_VERBOSE_NONE  = -1,
  83     /** only errors are printed */
  84     PMIX_MCA_BASE_VERBOSE_ERROR = 0,
  85     /** emit messages about component selection, open, and unloading */
  86     PMIX_MCA_BASE_VERBOSE_COMPONENT = 10,
  87     /** also emit warnings */
  88     PMIX_MCA_BASE_VERBOSE_WARN  = 20,
  89     /** also emit general, user-relevant information, such as rationale as to why certain choices
  90      * or code paths were taken, information gleaned from probing the local system, etc. */
  91     PMIX_MCA_BASE_VERBOSE_INFO  = 40,
  92     /** also emit relevant tracing information (e.g., which functions were invoked /
  93      * call stack entry/exit info) */
  94     PMIX_MCA_BASE_VERBOSE_TRACE = 60,
  95     /** also emit PMIX-developer-level (i.e,. highly detailed) information */
  96     PMIX_MCA_BASE_VERBOSE_DEBUG = 80,
  97     /** also output anything else that might be useful */
  98     PMIX_MCA_BASE_VERBOSE_MAX   = 100,
  99 };
 100 
 101 /*
 102  * Public functions
 103  */
 104 
 105 /**
 106  * First function called in the MCA.
 107  *
 108  * @return PMIX_SUCCESS Upon success
 109  * @return PMIX_ERROR Upon failure
 110  *
 111  * This function starts up the entire MCA.  It initializes a bunch
 112  * of built-in MCA parameters, and initialized the MCA component
 113  * repository.
 114  *
 115  * It must be the first MCA function invoked.  It is normally
 116  * invoked during the initialization stage and specifically
 117  * invoked in the special case of the *_info command.
 118  */
 119 PMIX_EXPORT int pmix_mca_base_open(void);
 120 
 121 /**
 122  * Last function called in the MCA
 123  *
 124  * @return PMIX_SUCCESS Upon success
 125  * @return PMIX_ERROR Upon failure
 126  *
 127  * This function closes down the entire MCA.  It clears all MCA
 128  * parameters and closes down the MCA component respository.
 129  *
 130  * It must be the last MCA function invoked.  It is normally invoked
 131  * during the finalize stage.
 132  */
 133 PMIX_EXPORT int pmix_mca_base_close(void);
 134 
 135 /**
 136  * A generic select function
 137  *
 138  */
 139 PMIX_EXPORT int pmix_mca_base_select(const char *type_name, int output_id,
 140                                      pmix_list_t *components_available,
 141                                      pmix_mca_base_module_t **best_module,
 142                                      pmix_mca_base_component_t **best_component,
 143                                      int *priority_out);
 144 
 145 /**
 146  * A function for component query functions to discover if they have
 147  * been explicitly required to or requested to be selected.
 148  *
 149  * exclusive: If the specified component is the only component that is
 150  *            available for selection.
 151  *
 152  */
 153 PMIX_EXPORT int pmix_mca_base_is_component_required(pmix_list_t *components_available,
 154                                                     pmix_mca_base_component_t *component,
 155                                                     bool exclusive,
 156                                                     bool *is_required);
 157 
 158 /* mca_base_cmd_line.c */
 159 
 160 PMIX_EXPORT int pmix_mca_base_cmd_line_setup(pmix_cmd_line_t *cmd);
 161 PMIX_EXPORT int pmix_mca_base_cmd_line_process_args(pmix_cmd_line_t *cmd,
 162                                                  char ***app_env,
 163                                                  char ***global_env);
 164 PMIX_EXPORT void pmix_mca_base_cmd_line_wrap_args(char **args);
 165 
 166 /* pmix_mca_base_component_compare.c */
 167 
 168 PMIX_EXPORT int pmix_mca_base_component_compare_priority(pmix_mca_base_component_priority_list_item_t *a,
 169                                                          pmix_mca_base_component_priority_list_item_t *b);
 170 PMIX_EXPORT int pmix_mca_base_component_compare(const pmix_mca_base_component_t *a,
 171                                                 const pmix_mca_base_component_t *b);
 172 PMIX_EXPORT int pmix_mca_base_component_compatible(const pmix_mca_base_component_t *a,
 173                                                    const pmix_mca_base_component_t *b);
 174 PMIX_EXPORT char * pmix_mca_base_component_to_string(const pmix_mca_base_component_t *a);
 175 
 176 /* pmix_mca_base_component_find.c */
 177 
 178 PMIX_EXPORT int pmix_mca_base_component_find (const char *directory, pmix_mca_base_framework_t *framework,
 179                                               bool ignore_requested, bool open_dso_components);
 180 
 181 /**
 182  * Parse the requested component string and return an pmix_argv of the requested
 183  * (or not requested) components.
 184  */
 185 PMIX_EXPORT int pmix_mca_base_component_parse_requested (const char *requested, bool *include_mode,
 186                                                          char ***requested_component_names);
 187 
 188 /**
 189  * Filter a list of components based on a comma-delimted list of names and/or
 190  * a set of meta-data flags.
 191  *
 192  * @param[in,out] components List of components to filter
 193  * @param[in] output_id Output id to write to for error/warning/debug messages
 194  * @param[in] filter_names Comma delimited list of components to use. Negate with ^.
 195  * May be NULL.
 196  * @param[in] filter_flags Metadata flags components are required to have set (CR ready)
 197  *
 198  * @returns PMIX_SUCCESS On success
 199  * @returns PMIX_ERR_NOT_FOUND If some component in {filter_names} is not found in
 200  * {components}. Does not apply to negated filters.
 201  * @returns pmix error code On other error.
 202  *
 203  * This function closes and releases any components that do not match the filter_name and
 204  * filter flags.
 205  */
 206 PMIX_EXPORT int pmix_mca_base_components_filter (pmix_mca_base_framework_t *framework, uint32_t filter_flags);
 207 
 208 
 209 
 210 /* Safely release some memory allocated by pmix_mca_base_component_find()
 211    (i.e., is safe to call even if you never called
 212    pmix_mca_base_component_find()). */
 213 PMIX_EXPORT int pmix_mca_base_component_find_finalize(void);
 214 
 215 /* pmix_mca_base_components_register.c */
 216 PMIX_EXPORT int pmix_mca_base_framework_components_register (struct pmix_mca_base_framework_t *framework,
 217                                                              pmix_mca_base_register_flag_t flags);
 218 
 219 /* pmix_mca_base_components_open.c */
 220 PMIX_EXPORT int pmix_mca_base_framework_components_open (struct pmix_mca_base_framework_t *framework,
 221                                                          pmix_mca_base_open_flag_t flags);
 222 
 223 PMIX_EXPORT int pmix_mca_base_components_open(const char *type_name, int output_id,
 224                                               const pmix_mca_base_component_t **static_components,
 225                                               pmix_list_t *components_available,
 226                                               bool open_dso_components);
 227 
 228 /* pmix_mca_base_components_close.c */
 229 /**
 230  * Close and release a component.
 231  *
 232  * @param[in] component Component to close
 233  * @param[in] output_id Output id for debugging output
 234  *
 235  * After calling this function the component may no longer be used.
 236  */
 237 PMIX_EXPORT void pmix_mca_base_component_close (const pmix_mca_base_component_t *component, int output_id);
 238 
 239 /**
 240  * Release a component without closing it.
 241  * @param[in] component Component to close
 242  * @param[in] output_id Output id for debugging output
 243  *
 244  * After calling this function the component may no longer be used.
 245  */
 246 PMIX_EXPORT void pmix_mca_base_component_unload (const pmix_mca_base_component_t *component, int output_id);
 247 
 248 PMIX_EXPORT int pmix_mca_base_components_close(int output_id, pmix_list_t *components_available,
 249                                                const pmix_mca_base_component_t *skip);
 250 
 251 PMIX_EXPORT int pmix_mca_base_framework_components_close (struct pmix_mca_base_framework_t *framework,
 252                                                           const pmix_mca_base_component_t *skip);
 253 
 254 END_C_DECLS
 255 
 256 #endif /* MCA_BASE_H */

/* [<][>][^][v][top][bottom][index][help] */