Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
prevent warining for undocumented (because internal) enum members when
[simgrid.git] / include / xbt / config.h
1 /* config - Dictionary where the type of each cell is provided.            */
2
3 /* This is useful to build named structs, like option or property sets.     */
4
5 /* Copyright (c) 2004-2007, 2009-2014. The SimGrid Team.
6  * All rights reserved.                                                     */
7
8 /* This program is free software; you can redistribute it and/or modify it
9  * under the terms of the license (GNU LGPL) which comes with this package. */
10
11 #ifndef _XBT_CONFIG_H_
12 #define _XBT_CONFIG_H_
13
14 #include <stdarg.h>
15 #include "xbt/dynar.h"
16
17 SG_BEGIN_DECL()
18
19 /** @addtogroup XBT_config
20  *  @brief Changing the configuration of SimGrid components (grounding feature)
21  *
22  *  All modules of the SimGrid toolkit can be configured with this API.
23  *  User modules and libraries can also use these facilities to handle
24  *  their own configuration.
25  *
26  *  A configuration set contain several \e variables which have a unique name
27  *  in the set and can take a given type of value. For example, it may
28  *  contain a \a size variable, accepting \e int values.
29  *
30  *  It is impossible to set a value to a variable which has not been registered before.
31  *  Usually, the module registers all the options it accepts in the configuration set,
32  *  during its initialization and user code then set and unset values.
33  *
34  *  The easiest way to register a variable is to use the xbt_str_register_str function,
35  *  which accepts a string representation of the config element descriptor. The syntax
36  *  is the following: \verbatim <name>:<min nb>_to_<max nb>_<type>\endverbatim
37  *
38  *  For example, <tt>size:1_to_1_int</tt> describes a variable called \e size which
39  *  must take exactly one value, and the value being an integer. Set the maximum to 0 to
40  *  disable the upper bound on data count.
41  *
42  *  Another example could be <tt>outputfiles:0_to_10_string</tt> which describes a variable
43  *  called \e outputfiles and which can take between 0 and 10 strings as value.
44  *
45  *  To some extend, configuration sets can be seen as typed hash structures.
46  *
47  *
48  *  \section XBT_cfg_ex Example of use
49  *
50  *  \dontinclude config.c
51  *
52  *  First, let's create a configuration set with some registered variables.
53  *  This must be done by the configurable library before the user interactions.
54  *
55  *  \skip make_set
56  *  \until end_of_make_set
57  *
58  *  Now, set and get a single value
59  *  \skip get_single_value
60  *  \skip int
61  *  \until cfg_free
62  *
63  *  And now, set and get a multiple value
64  *  \skip get_multiple_value
65  *  \skip dyn
66  *  \until cfg_free
67  *
68  *  All those functions throws mismatch_error if asked to deal with an
69  *  unregistered variable.
70  *  \skip myset
71  *  \until cfg_free
72  *
73  */
74 /** @defgroup XBT_cfg_use User interface: changing values
75  *  @ingroup XBT_config
76  *
77  * This is the only interface you should use unless you want to let your
78  * own code become configurable with this.
79  *
80  * If the variable accept at most one value, those functions replace the
81  * current value with the provided one. If max>1, the provided value is
82  * appended to the list.
83  *
84  * string values are strdup'ed before use, so you can (and should) free
85  * your copy
86  *
87  * @{
88  */
89 /** @brief Configuration set's data type is opaque. */
90 typedef void* xbt_cfg_t;
91
92 XBT_PUBLIC(void) xbt_cfg_set(xbt_cfg_t cfg, const char *name, ...);
93 XBT_PUBLIC(void) xbt_cfg_set_vargs(xbt_cfg_t cfg, const char *name,
94                                    va_list pa);
95 XBT_PUBLIC(void) xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options);
96
97
98 /*
99   Set the value of the cell \a name in \a cfg with the provided value.
100  */
101 XBT_PUBLIC(void) xbt_cfg_set_int(xbt_cfg_t cfg, const char *name, int val);
102 XBT_PUBLIC(void) xbt_cfg_set_double(xbt_cfg_t cfg, const char *name,
103                                     double val);
104 XBT_PUBLIC(void) xbt_cfg_set_string(xbt_cfg_t cfg, const char *name,
105                                     const char *val);
106 XBT_PUBLIC(void) xbt_cfg_set_boolean(xbt_cfg_t cfg, const char *name, const char *val);
107 XBT_PUBLIC(void) xbt_cfg_set_peer(xbt_cfg_t cfg, const char *name,
108                                   const char *peer, int port);
109 XBT_PUBLIC(void*) xbt_cfg_set_as_string(xbt_cfg_t cfg, const char *name, const char *val);
110
111 /*
112   Set the default value of the cell \a name in \a cfg with the provided value.
113   If it was already set to something (possibly from the command line), do nothing.
114  */
115 XBT_PUBLIC(void) xbt_cfg_setdefault_int(xbt_cfg_t cfg, const char *name,
116                                         int val);
117 XBT_PUBLIC(void) xbt_cfg_setdefault_double(xbt_cfg_t cfg, const char *name,
118                                            double val);
119 XBT_PUBLIC(void) xbt_cfg_setdefault_string(xbt_cfg_t cfg, const char *name,
120                                            const char *val);
121 XBT_PUBLIC(void) xbt_cfg_setdefault_boolean(xbt_cfg_t cfg, const char *name,
122                                         const char *val);
123 XBT_PUBLIC(void) xbt_cfg_setdefault_peer(xbt_cfg_t cfg, const char *name,
124                                          const char *host, int port);
125
126
127 /*
128  Remove the provided value from the cell @name in @cfg.
129  */
130 XBT_PUBLIC(void) xbt_cfg_rm_int(xbt_cfg_t cfg, const char *name, int val);
131 XBT_PUBLIC(void) xbt_cfg_rm_double(xbt_cfg_t cfg, const char *name,
132                                    double val);
133 XBT_PUBLIC(void) xbt_cfg_rm_string(xbt_cfg_t cfg, const char *name,
134                                    const char *val);
135 XBT_PUBLIC(void) xbt_cfg_rm_boolean(xbt_cfg_t cfg, const char *name, int val);
136 XBT_PUBLIC(void) xbt_cfg_rm_peer(xbt_cfg_t cfg, const char *name,
137                                  const char *peer, int port);
138
139 /*
140  Remove the value at position \e pos from the config \e cfg
141  */
142 XBT_PUBLIC(void) xbt_cfg_rm_at(xbt_cfg_t cfg, const char *name, int pos);
143
144 /* rm every values */
145 XBT_PUBLIC(void) xbt_cfg_empty(xbt_cfg_t cfg, const char *name);
146
147 /* Return if configuration is set by default*/
148 XBT_PUBLIC(int) xbt_cfg_is_default_value(xbt_cfg_t cfg, const char *name);
149
150 /* @} */
151
152 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
153  *  @ingroup XBT_config
154  *
155  *  @{
156  */
157
158   /** @brief possible content of each configuration cell */
159 typedef enum {
160   xbt_cfgelm_int = 0,
161                        /**< int */
162   xbt_cfgelm_double,
163                        /**< double */
164   xbt_cfgelm_string,
165                        /**< char* */
166   xbt_cfgelm_boolean,  /**< int */
167   xbt_cfgelm_peer,     /**< both a char* (representing the peername) and an integer (representing the port) */
168
169   //! @cond
170   xbt_cfgelm_any,               /* not shown to users to prevent errors */
171   xbt_cfgelm_type_count
172   //! @endcond
173 } e_xbt_cfgelm_type_t;
174
175 /** Boolean possible values **/
176
177 struct xbt_boolean_couple {
178   const char *true_val;
179   const char *false_val;
180 };
181
182
183
184
185 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
186 typedef void (*xbt_cfg_cb_t) (const char *, int);
187
188 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
189 XBT_PUBLIC(void) xbt_cfg_cpy(xbt_cfg_t tocopy,  /* OUT */
190                              xbt_cfg_t * whereto);
191 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
192 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent,
193                               xbt_cfg_t cfg);
194
195  /** @} */
196
197 /** @defgroup XBT_cfg_register  Registering stuff
198  *  @ingroup XBT_config
199  *
200  *  This how to add new variables to an existing configuration set. Use it to make your code
201  *  configurable.
202  *
203  *  @{
204  */
205 XBT_PUBLIC(void) xbt_cfg_register(xbt_cfg_t * cfg,
206                                   const char *name,
207                                   const char *description,
208                                   e_xbt_cfgelm_type_t type,
209                                   int min, int max,
210                                   xbt_cfg_cb_t cb_set, xbt_cfg_cb_t cb_rm);
211 XBT_PUBLIC(void) xbt_cfg_unregister(xbt_cfg_t cfg, const char *name);
212 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
213 XBT_PUBLIC(void) xbt_cfg_help(xbt_cfg_t cfg);
214 XBT_PUBLIC(void) xbt_cfg_check(xbt_cfg_t cfg);
215 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg,
216                                                  const char *name);
217 /*  @} */
218 /** @defgroup XBT_cfg_get Getting the stored values
219  *  @ingroup XBT_config
220  *
221  * This is how to retrieve the values stored in the configuration set. This is only
222  * intended to configurable code, naturally.
223  *
224  * Note that those function return a pointer to the values actually stored
225  * in the set. Do not modify them unless you really know what you're doing.
226  * Likewise, do not free the strings after use, they are not copy of the data,
227  * but the data themselves.
228  *
229  *  @{
230  */
231
232 XBT_PUBLIC(int) xbt_cfg_get_int(xbt_cfg_t cfg, const char *name);
233 XBT_PUBLIC(double) xbt_cfg_get_double(xbt_cfg_t cfg, const char *name);
234 XBT_PUBLIC(char *) xbt_cfg_get_string(xbt_cfg_t cfg, const char *name);
235 XBT_PUBLIC(int) xbt_cfg_get_boolean(xbt_cfg_t cfg, const char *name);
236 XBT_PUBLIC(void) xbt_cfg_get_peer(xbt_cfg_t cfg, const char *name,
237                                   char **peer, int *port);
238 XBT_PUBLIC(xbt_dynar_t) xbt_cfg_get_dynar(xbt_cfg_t cfg, const char *name);
239
240 XBT_PUBLIC(int) xbt_cfg_get_int_at(xbt_cfg_t cfg, const char *name,
241                                    int pos);
242 XBT_PUBLIC(double) xbt_cfg_get_double_at(xbt_cfg_t cfg, const char *name,
243                                          int pos);
244 XBT_PUBLIC(char *) xbt_cfg_get_string_at(xbt_cfg_t cfg, const char *name,
245                                          int pos);
246 XBT_PUBLIC(int) xbt_cfg_get_boolean_at(xbt_cfg_t cfg, const char *name,
247                                    int pos);
248 XBT_PUBLIC(void) xbt_cfg_get_peer_at(xbt_cfg_t cfg, const char *name,
249                                      int pos, char **peer, int *port);
250
251 /** @} */
252
253 SG_END_DECL()
254 #endif                          /* _XBT_CONFIG_H_ */