Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Test if the configuration into tag_config is already set by command line.
[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, 2005, 2006, 2007, 2009, 2010. 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  *  \todo This great mechanism is not used in SimGrid yet...
48  *
49  *
50  *  \section XBT_cfg_ex Example of use
51  *
52  *  \dontinclude config.c
53  *
54  *  First, let's create a configuration set with some registered variables.
55  *  This must be done by the configurable library before the user interactions.
56  *
57  *  \skip make_set
58  *  \until end_of_make_set
59  *
60  *  Now, set and get a single value
61  *  \skip get_single_value
62  *  \skip int
63  *  \until cfg_free
64  *
65  *  And now, set and get a multiple value
66  *  \skip get_multiple_value
67  *  \skip dyn
68  *  \until cfg_free
69  *
70  *  All those functions throws mismatch_error if asked to deal with an
71  *  unregistered variable.
72  *  \skip myset
73  *  \until cfg_free
74  *
75  */
76 /** @defgroup XBT_cfg_use User interface: changing values
77  *  @ingroup XBT_config
78  *
79  * This is the only interface you should use unless you want to let your
80  * own code become configurable with this.
81  *
82  * If the variable accept at most one value, those functions replace the
83  * current value with the provided one. If max>1, the provided value is
84  * appended to the list.
85  *
86  * string values are strdup'ed before use, so you can (and should) free
87  * your copy
88  *
89  * @{
90  */
91   /** @brief Configuration set are only special dynars. But don't rely on it, it may change. */
92 typedef xbt_dynar_t xbt_cfg_t;
93
94 XBT_PUBLIC(void) xbt_cfg_set(xbt_cfg_t cfg, const char *name, ...);
95 XBT_PUBLIC(void) xbt_cfg_set_vargs(xbt_cfg_t cfg, const char *name,
96                                    va_list pa);
97 XBT_PUBLIC(void) xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options);
98
99
100 /*
101   Set the value of the cell \a name in \a cfg with the provided value.
102  */
103 XBT_PUBLIC(void) xbt_cfg_set_int(xbt_cfg_t cfg, const char *name, int val);
104 XBT_PUBLIC(void) xbt_cfg_set_double(xbt_cfg_t cfg, const char *name,
105                                     double val);
106 XBT_PUBLIC(void) xbt_cfg_set_string(xbt_cfg_t cfg, const char *name,
107                                     const char *val);
108 XBT_PUBLIC(void) xbt_cfg_set_peer(xbt_cfg_t cfg, const char *name,
109                                   const char *peer, int port);
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_peer(xbt_cfg_t cfg, const char *name,
122                                          const char *host, int port);
123
124
125 /*
126  Remove the provided value from the cell @name in @cfg.
127  */
128 XBT_PUBLIC(void) xbt_cfg_rm_int(xbt_cfg_t cfg, const char *name, int val);
129 XBT_PUBLIC(void) xbt_cfg_rm_double(xbt_cfg_t cfg, const char *name,
130                                    double val);
131 XBT_PUBLIC(void) xbt_cfg_rm_string(xbt_cfg_t cfg, const char *name,
132                                    const char *val);
133 XBT_PUBLIC(void) xbt_cfg_rm_peer(xbt_cfg_t cfg, const char *name,
134                                  const char *peer, int port);
135
136 /*
137  Remove the value at position \e pos from the config \e cfg
138  */
139 XBT_PUBLIC(void) xbt_cfg_rm_at(xbt_cfg_t cfg, const char *name, int pos);
140
141 /* rm every values */
142 XBT_PUBLIC(void) xbt_cfg_empty(xbt_cfg_t cfg, const char *name);
143
144 /* @} */
145
146 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
147  *  @ingroup XBT_config
148  *
149  *  @{
150  */
151
152   /** @brief possible content of each configuration cell */
153 typedef enum {
154   xbt_cfgelm_int = 0,
155                        /**< int */
156   xbt_cfgelm_double,
157                        /**< double */
158   xbt_cfgelm_string,
159                        /**< char* */
160   xbt_cfgelm_peer,     /**< both a char* (representing the peername) and an integer (representing the port) */
161
162   xbt_cfgelm_any,               /* not shown to users to prevent errors */
163   xbt_cfgelm_type_count
164 } e_xbt_cfgelm_type_t;
165
166 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
167 typedef void (*xbt_cfg_cb_t) (const char *, int);
168
169 /* xbt_cfgelm_t: the typedef corresponding to a config variable.
170
171    Both data and DTD are mixed, but fixing it now would prevent me to ever
172    defend my thesis. */
173
174 typedef struct {
175   /* Description */
176   char *desc;
177
178   /* Allowed type of the variable */
179   e_xbt_cfgelm_type_t type;
180   int min, max;
181   int isdefault:1;
182
183   /* Callbacks */
184   xbt_cfg_cb_t cb_set;
185   xbt_cfg_cb_t cb_rm;
186
187   /* actual content
188      (cannot be an union because type peer uses both str and i) */
189   xbt_dynar_t content;
190 } s_xbt_cfgelm_t, *xbt_cfgelm_t;
191
192 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
193 XBT_PUBLIC(void) xbt_cfg_cpy(xbt_cfg_t tocopy,  /* OUT */
194                              xbt_cfg_t * whereto);
195 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
196 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent,
197                               xbt_cfg_t cfg);
198
199 /* Retrieve the variable we'll modify */
200 XBT_PUBLIC(xbt_cfgelm_t) xbt_cfgelm_get(xbt_cfg_t cfg, const char *name,
201                                    e_xbt_cfgelm_type_t type);
202  /** @} */
203
204 /** @defgroup XBT_cfg_register  Registering stuff
205  *  @ingroup XBT_config
206  *
207  *  This how to add new variables to an existing configuration set. Use it to make your code
208  *  configurable.
209  *
210  *  @{
211  */
212 XBT_PUBLIC(void) xbt_cfg_register(xbt_cfg_t * cfg,
213                                   const char *name,
214                                   const char *description,
215                                   e_xbt_cfgelm_type_t type,
216                                   void *default_value, int min, int max,
217                                   xbt_cfg_cb_t cb_set, xbt_cfg_cb_t cb_rm);
218 XBT_PUBLIC(void) xbt_cfg_unregister(xbt_cfg_t cfg, const char *name);
219 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
220 XBT_PUBLIC(void) xbt_cfg_help(xbt_cfg_t cfg);
221 XBT_PUBLIC(void) xbt_cfg_check(xbt_cfg_t cfg);
222 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg,
223                                                  const char *name);
224 /*  @} */
225 /** @defgroup XBT_cfg_get Getting the stored values
226  *  @ingroup XBT_config
227  *
228  * This is how to retrieve the values stored in the configuration set. This is only
229  * intended to configurable code, naturally.
230  *
231  * Note that those function return a pointer to the values actually stored
232  * in the set. Do not modify them unless you really know what you're doing.
233  * Likewise, do not free the strings after use, they are not copy of the data,
234  * but the data themselves.
235  *
236  *  @{
237  */
238
239 XBT_PUBLIC(int) xbt_cfg_get_int(xbt_cfg_t cfg, const char *name);
240 XBT_PUBLIC(double) xbt_cfg_get_double(xbt_cfg_t cfg, const char *name);
241 XBT_PUBLIC(char *) xbt_cfg_get_string(xbt_cfg_t cfg, const char *name);
242 XBT_PUBLIC(void) xbt_cfg_get_peer(xbt_cfg_t cfg, const char *name,
243                                   char **peer, int *port);
244 XBT_PUBLIC(xbt_dynar_t) xbt_cfg_get_dynar(xbt_cfg_t cfg, const char *name);
245
246 XBT_PUBLIC(int) xbt_cfg_get_int_at(xbt_cfg_t cfg, const char *name,
247                                    int pos);
248 XBT_PUBLIC(double) xbt_cfg_get_double_at(xbt_cfg_t cfg, const char *name,
249                                          int pos);
250 XBT_PUBLIC(char *) xbt_cfg_get_string_at(xbt_cfg_t cfg, const char *name,
251                                          int pos);
252 XBT_PUBLIC(void) xbt_cfg_get_peer_at(xbt_cfg_t cfg, const char *name,
253                                      int pos, char **peer, int *port);
254
255 /** @} */
256
257 SG_END_DECL()
258 #endif                          /* _XBT_CONFIG_H_ */