1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2006 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) 2008-2011 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2012-2016 Los Alamos National Security, LLC. All rights
15 * reserved.
16 * Copyright (c) 2017 Research Organization for Information Science
17 * and Technology (RIST). All rights reserved.
18 * $COPYRIGHT$
19 *
20 * Additional copyrights may follow
21 *
22 * $HEADER$
23 */
24
25 #if !defined(MCA_BASE_VAR_ENUM_H)
26 #define MCA_BASE_VAR_ENUM_H
27
28 #include "opal_config.h"
29
30 #include "opal/class/opal_object.h"
31 #include "opal/constants.h"
32
33 typedef struct mca_base_var_enum_t mca_base_var_enum_t;
34
35 /**
36 * Get the number of values in the enumerator
37 *
38 * @param[in] self the enumerator
39 * @param[out] count the number of values in the enumerator
40 */
41 typedef int (*mca_base_var_enum_get_count_fn_t)(mca_base_var_enum_t *self, int *count);
42
43 /**
44 * Get the value and its string representation for an index 0..get_count()
45 *
46 * @param[in] self the enumerator
47 * @param[in] index the index to get the value of
48 * @param[out] value integer value
49 * @param[out] string_value string value
50 */
51 typedef int (*mca_base_var_enum_get_value_fn_t)(mca_base_var_enum_t *self, int index,
52 int *value, const char **string_value);
53
54 /**
55 * Look up the integer value of a string
56 *
57 * @param[in] self the enumerator
58 * @param[in] string_value string to lookup
59 * @param[out] value integer value for the string
60 *
61 * @retval OPAL_SUCCESS if found
62 * @retval OPAL_ERR_VALUE_OUT_OF_BOUNDS if not
63 */
64 typedef int (*mca_base_var_enum_vfs_fn_t)(mca_base_var_enum_t *self, const char *string_value,
65 int *value);
66
67 /**
68 * Dump a textual representation of all the values in an enumerator
69 *
70 * @param[in] self the enumerator
71 * @param[out] out the string representation
72 *
73 * @retval OPAL_SUCCESS on success
74 * @retval opal error on error
75 */
76 typedef int (*mca_base_var_enum_dump_fn_t)(mca_base_var_enum_t *self, char **out);
77
78 /**
79 * Get the string representation for an enumerator value
80 *
81 * @param[in] self the enumerator
82 * @param[in] value integer value
83 * @param[out] string_value string value for value
84 *
85 * @retval OPAL_SUCCESS on success
86 * @retval OPAL_ERR_VALUE_OUT_OF_BOUNDS if not found
87 *
88 * @long This function returns the string value for a given interger value in the
89 * {string_value} parameter. The {string_value} parameter may be NULL in which case
90 * no string is returned. If a string is returned in {string_value} the caller
91 * must free the string with free().
92 */
93 typedef int (*mca_base_var_enum_sfv_fn_t)(mca_base_var_enum_t *self, const int value,
94 char **string_value);
95
96 /**
97 * The default enumerator class takes in a list of integer-string pairs. If a
98 * string is read from an environment variable or a file value the matching
99 * integer value is used for the MCA variable.
100 */
101 struct mca_base_var_enum_value_t {
102 int value;
103 const char *string;
104 };
105
106 typedef struct mca_base_var_enum_value_t mca_base_var_enum_value_t;
107
108 /**
109 * enumerator base class
110 */
111 struct mca_base_var_enum_t {
112 opal_object_t super;
113
114 /** Is the enumerator statically allocated */
115 bool enum_is_static;
116
117 /** Name of this enumerator. This value is duplicated from the argument provided to
118 mca_base_var_enum_create() */
119 char *enum_name;
120
121 /** Get the number of values this enumerator represents. Subclasses should override
122 the default function. */
123 mca_base_var_enum_get_count_fn_t get_count;
124 /** Get the value and string representation for a particular index. Subclasses should
125 override the default function */
126 mca_base_var_enum_get_value_fn_t get_value;
127 /** Given a string return corresponding integer value. If the string does not match a
128 valid value return OPAL_ERR_VALUE_OUT_OF_BOUNDS */
129 mca_base_var_enum_vfs_fn_t value_from_string;
130 /** Given an integer return the corresponding string value. If the integer does not
131 match a valid value return OPAL_ERR_VALUE_OUT_OF_BOUNDS */
132 mca_base_var_enum_sfv_fn_t string_from_value;
133 /** Dump a textual representation of the enumerator. The caller is responsible for
134 freeing the string */
135 mca_base_var_enum_dump_fn_t dump;
136
137 int enum_value_count;
138 /** Copy of the enumerators values (used by the default functions). This array and
139 and the strings it contains are freed by the destructor if not NULL. */
140 mca_base_var_enum_value_t *enum_values;
141 };
142
143
144 /**
145 * The default flag enumerator class takes in a list of integer-string pairs. If a
146 * string is read from an environment variable or a file value the matching
147 * flag value is used for the MCA variable. The conflicting_flag is used to
148 * indicate any flags that should conflict.
149 */
150 struct mca_base_var_enum_value_flag_t {
151 /** flag value (must be power-of-two) */
152 int flag;
153 /** corresponding string name */
154 const char *string;
155 /** conflicting flag(s) if any */
156 int conflicting_flag;
157 };
158
159 typedef struct mca_base_var_enum_value_flag_t mca_base_var_enum_value_flag_t;
160
161 /**
162 * flag enumerator base class
163 */
164 struct mca_base_var_enum_flag_t {
165 /** use the existing enumerator interface */
166 mca_base_var_enum_t super;
167 /** flag value(s) */
168 mca_base_var_enum_value_flag_t *enum_flags;
169 };
170
171 typedef struct mca_base_var_enum_flag_t mca_base_var_enum_flag_t;
172
173 /**
174 * Object declaration for mca_base_var_enum_t
175 */
176 OPAL_DECLSPEC OBJ_CLASS_DECLARATION(mca_base_var_enum_t);
177
178 /**
179 * Create a new default enumerator
180 *
181 * @param[in] name Name for this enumerator
182 * @param[in] values List of values terminated with a NULL .string
183 * member.
184 * @param[out] enumerator Newly created enumerator.
185 *
186 * @retval OPAL_SUCCESS On success
187 * @retval opal error code On error
188 *
189 * This function creates a value enumerator for integer variables. The
190 * OUT enumerator value will be a newly OBJ_NEW'ed object that should
191 * be released by the caller via OBJ_RELEASE.
192 *
193 * Note that the output enumerator can be OBJ_RELEASE'd after it has
194 * been used in a cvar or pvar registration, because the variable
195 * registration functions will OBJ_RETAIN the enumberator.
196 *
197 * Note that all the strings in the values[] array are strdup'ed into
198 * internal storage, meaning that the caller can free all of the
199 * strings passed in values[] after mca_base_var_enum_create()
200 * returns.
201 */
202 OPAL_DECLSPEC int mca_base_var_enum_create (const char *name, const mca_base_var_enum_value_t values[],
203 mca_base_var_enum_t **enumerator);
204
205 /**
206 * Create a new default flag enumerator
207 *
208 * @param[in] name Name for this enumerator
209 * @param[in] flags List of flags terminated with a NULL .string
210 * member.
211 * @param[out] enumerator Newly created enumerator.
212 *
213 * @retval OPAL_SUCCESS On success
214 * @retval opal error code On error
215 *
216 * This function creates a flag enumerator for integer variables. The
217 * OUT enumerator value will be a newly OBJ_NEW'ed object that should
218 * be released by the caller via OBJ_RELEASE.
219 *
220 * Note that the output enumerator can be OBJ_RELEASE'd after it has
221 * been used in a cvar or pvar registration, because the variable
222 * registration functions will OBJ_RETAIN the enumberator.
223 *
224 * Note that all the strings in the values[] array are strdup'ed into
225 * internal storage, meaning that the caller can free all of the
226 * strings passed in values[] after mca_base_var_enum_create()
227 * returns.
228 */
229 OPAL_DECLSPEC int mca_base_var_enum_create_flag (const char *name, const mca_base_var_enum_value_flag_t flags[],
230 mca_base_var_enum_flag_t **enumerator);
231
232 OPAL_DECLSPEC int mca_base_var_enum_register(const char *project_name, const char *framework_name,
233 const char *component_name, const char *enum_name,
234 void *storage);
235 /* standard enumerators. it is invalid to call OBJ_RELEASE on any of these enumerators */
236 /**
237 * Boolean enumerator
238 *
239 * This enumerator maps:
240 * positive integer, true, yes, enabled, t -> 1
241 * 0, false, no, disabled, f -> 0
242 */
243 extern mca_base_var_enum_t mca_base_var_enum_bool;
244
245 /**
246 * Extended boolean enumerator
247 *
248 * This enumerator maps:
249 * positive integer, true, yes, enabled, t -> 1
250 * 0, false, no, disabled, f -> 0
251 * auto -> -1
252 */
253 extern mca_base_var_enum_t mca_base_var_enum_auto_bool;
254
255 /**
256 * Verbosity level enumerator
257 */
258 extern mca_base_var_enum_t mca_base_var_enum_verbose;
259
260 #endif /* !defined(MCA_BASE_VAR_ENUM_H) */