1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2012-2015 Los Alamos National Security, LLC. All rights
4 * reserved.
5 * Copyright (c) 2016-2017 Intel, Inc. All rights reserved.
6 * $COPYRIGHT$
7 *
8 * Additional copyrights may follow
9 *
10 * $HEADER$
11 */
12
13 #if !defined(PMIX_MCA_BASE_FRAMEWORK_H)
14 #define PMIX_MCA_BASE_FRAMEWORK_H
15 #include <src/include/pmix_config.h>
16
17 #include "src/mca/mca.h"
18 #include "src/class/pmix_list.h"
19
20 /*
21 * Register and open flags
22 */
23 enum pmix_mca_base_register_flag_t {
24 PMIX_MCA_BASE_REGISTER_DEFAULT = 0,
25 /** Register all components (ignore selection MCA variables) */
26 PMIX_MCA_BASE_REGISTER_ALL = 1,
27 /** Do not register DSO components */
28 PMIX_MCA_BASE_REGISTER_STATIC_ONLY = 2
29 };
30
31 typedef enum pmix_mca_base_register_flag_t pmix_mca_base_register_flag_t;
32
33 enum pmix_mca_base_open_flag_t {
34 PMIX_MCA_BASE_OPEN_DEFAULT = 0,
35 /** Find components in pmix_mca_base_components_find. Used by
36 pmix_mca_base_framework_open() when NOREGISTER is specified
37 by the framework */
38 PMIX_MCA_BASE_OPEN_FIND_COMPONENTS = 1,
39 /** Do not open DSO components */
40 PMIX_MCA_BASE_OPEN_STATIC_ONLY = 2,
41 };
42
43 typedef enum pmix_mca_base_open_flag_t pmix_mca_base_open_flag_t;
44
45
46 /**
47 * Register the MCA framework parameters
48 *
49 * @param[in] flags Registration flags (see mca/base/base.h)
50 *
51 * @retval PMIX_SUCCESS on success
52 * @retval pmix error code on failure
53 *
54 * This function registers all framework MCA parameters. This
55 * function should not call pmix_mca_base_framework_components_register().
56 *
57 * Frameworks are NOT required to provide this function. It
58 * may be NULL.
59 */
60 typedef int (*pmix_mca_base_framework_register_params_fn_t) (pmix_mca_base_register_flag_t flags);
61
62 /**
63 * Initialize the MCA framework
64 *
65 * @retval PMIX_SUCCESS Upon success
66 * @retval PMIX_ERROR Upon failure
67 *
68 * This must be the first function invoked in the MCA framework.
69 * It initializes the MCA framework, finds and opens components,
70 * populates the components list, etc.
71 *
72 * This function is invoked during pmix_init() and during the
73 * initialization of the special case of the ompi_info command.
74 *
75 * This function fills in the components framework value, which
76 * is a list of all components that were successfully opened.
77 * This variable should \em only be used by other framework base
78 * functions or by ompi_info -- it is not considered a public
79 * interface member -- and is only mentioned here for completeness.
80 *
81 * Any resources allocated by this function must be freed
82 * in the framework close function.
83 *
84 * Frameworks are NOT required to provide this function. It may
85 * be NULL. If a framework does not provide an open function the
86 * default behavior of pmix_mca_base_framework_open() is to call
87 * pmix_mca_base_framework_components_open(). If a framework provides
88 * an open function it will need to call pmix_mca_base_framework_components_open()
89 * if it needs to open any components.
90 */
91 typedef int (*pmix_mca_base_framework_open_fn_t) (pmix_mca_base_open_flag_t flags);
92
93 /**
94 * Shut down the MCA framework.
95 *
96 * @retval PMIX_SUCCESS Always
97 *
98 * This function should shut downs everything in the MCA
99 * framework, and is called during pmix_finalize() and the
100 * special case of the ompi_info command.
101 *
102 * It must be the last function invoked on the MCA framework.
103 *
104 * Frameworks are NOT required to provide this function. It may
105 * be NULL. If a framework does not provide a close function the
106 * default behavior of pmix_mca_base_framework_close() is to call
107 * pmix_mca_base_framework_components_close(). If a framework provide
108 * a close function it will need to call pmix_mca_base_framework_components_close()
109 * if any components were opened.
110 */
111 typedef int (*pmix_mca_base_framework_close_fn_t) (void);
112
113 typedef enum {
114 PMIX_MCA_BASE_FRAMEWORK_FLAG_DEFAULT = 0,
115 /** Don't register any variables for this framework */
116 PMIX_MCA_BASE_FRAMEWORK_FLAG_NOREGISTER = 1,
117 /** Internal. Don't set outside pmix_mca_base_framework.h */
118 PMIX_MCA_BASE_FRAMEWORK_FLAG_REGISTERED = 2,
119 /** Framework does not have any DSO components */
120 PMIX_MCA_BASE_FRAMEWORK_FLAG_NO_DSO = 4,
121 /** Internal. Don't set outside pmix_mca_base_framework.h */
122 PMIX_MCA_BASE_FRAMEWORK_FLAG_OPEN = 8,
123 /**
124 * The upper 16 bits are reserved for project specific flags.
125 */
126 } pmix_mca_base_framework_flags_t;
127
128 typedef struct pmix_mca_base_framework_t {
129 /** Project name for this component (ex "pmix") */
130 char *framework_project;
131 /** Framework name */
132 char *framework_name;
133 /** Description of this framework or NULL */
134 const char *framework_description;
135 /** Framework register function or NULL if the framework
136 and all its components have nothing to register */
137 pmix_mca_base_framework_register_params_fn_t framework_register;
138 /** Framework open function or NULL */
139 pmix_mca_base_framework_open_fn_t framework_open;
140 /** Framework close function or NULL */
141 pmix_mca_base_framework_close_fn_t framework_close;
142 /** Framework flags (future use) set to 0 */
143 pmix_mca_base_framework_flags_t framework_flags;
144 /** Framework open count */
145 int framework_refcnt;
146 /** List of static components */
147 const pmix_mca_base_component_t **framework_static_components;
148 /** Component selection. This will be registered with the MCA
149 variable system and should be either NULL (all components) or
150 a heap allocated, comma-delimited list of components. */
151 char *framework_selection;
152 /** Verbosity level (0-100) */
153 int framework_verbose;
154 /** Pmix output for this framework (or -1) */
155 int framework_output;
156 /** List of selected components (filled in by pmix_mca_base_framework_register()
157 or pmix_mca_base_framework_open() */
158 pmix_list_t framework_components;
159 /** List of components that failed to load */
160 pmix_list_t framework_failed_components;
161 } pmix_mca_base_framework_t;
162
163
164 /**
165 * Register a framework with MCA.
166 *
167 * @param[in] framework framework to register
168 *
169 * @retval PMIX_SUCCESS Upon success
170 * @retval PMIX_ERROR Upon failure
171 *
172 * Call a framework's register function.
173 */
174 PMIX_EXPORT int pmix_mca_base_framework_register (pmix_mca_base_framework_t *framework,
175 pmix_mca_base_register_flag_t flags);
176
177 /**
178 * Open a framework
179 *
180 * @param[in] framework framework to open
181 *
182 * @retval PMIX_SUCCESS Upon success
183 * @retval PMIX_ERROR Upon failure
184 *
185 * Call a framework's open function.
186 */
187 PMIX_EXPORT int pmix_mca_base_framework_open (pmix_mca_base_framework_t *framework,
188 pmix_mca_base_open_flag_t flags);
189
190 /**
191 * Close a framework
192 *
193 * @param[in] framework framework to close
194 *
195 * @retval PMIX_SUCCESS Upon success
196 * @retval PMIX_ERROR Upon failure
197 *
198 * Call a framework's close function.
199 */
200 PMIX_EXPORT int pmix_mca_base_framework_close (pmix_mca_base_framework_t *framework);
201
202
203 /**
204 * Check if a framework is already registered
205 *
206 * @param[in] framework framework to query
207 *
208 * @retval true if the framework's mca variables are registered
209 * @retval false if not
210 */
211 PMIX_EXPORT bool pmix_mca_base_framework_is_registered (struct pmix_mca_base_framework_t *framework);
212
213
214 /**
215 * Check if a framework is already open
216 *
217 * @param[in] framework framework to query
218 *
219 * @retval true if the framework is open
220 * @retval false if not
221 */
222 PMIX_EXPORT bool pmix_mca_base_framework_is_open (struct pmix_mca_base_framework_t *framework);
223
224
225 /**
226 * Macro to declare an MCA framework
227 *
228 * Example:
229 * PMIX_MCA_BASE_FRAMEWORK_DECLARE(pmix, foo, NULL, pmix_foo_open, pmix_foo_close, MCA_BASE_FRAMEWORK_FLAG_LAZY)
230 */
231 #define PMIX_MCA_BASE_FRAMEWORK_DECLARE(project, name, description, registerfn, openfn, closefn, static_components, flags) \
232 pmix_mca_base_framework_t project##_##name##_base_framework = { \
233 .framework_project = #project, \
234 .framework_name = #name, \
235 .framework_description = description, \
236 .framework_register = registerfn, \
237 .framework_open = openfn, \
238 .framework_close = closefn, \
239 .framework_flags = flags, \
240 .framework_refcnt = 0, \
241 .framework_static_components = static_components, \
242 .framework_selection = NULL, \
243 .framework_verbose = 0, \
244 .framework_output = -1}
245
246 #endif /* PMIX_MCA_BASE_FRAMEWORK_H */