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