1 /* config - Dictionary where the type of each cell is provided. */
3 /* This is useful to build named structs, like option or property sets. */
5 /* Copyright (c) 2004, 2005, 2006, 2007, 2009, 2010. The SimGrid Team.
6 * All rights reserved. */
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. */
11 #ifndef _XBT_CONFIG_H_
12 #define _XBT_CONFIG_H_
15 #include "xbt/dynar.h"
19 /** @addtogroup XBT_config
20 * @brief Changing the configuration of SimGrid components (grounding feature)
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.
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.
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.
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
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.
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.
45 * To some extend, configuration sets can be seen as typed hash structures.
47 * \todo This great mechanism is not used in SimGrid yet...
50 * \section XBT_cfg_ex Example of use
52 * \dontinclude config.c
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.
58 * \until end_of_make_set
60 * Now, set and get a single value
61 * \skip get_single_value
65 * And now, set and get a multiple value
66 * \skip get_multiple_value
70 * All those functions throws mismatch_error if asked to deal with an
71 * unregistered variable.
76 /** @defgroup XBT_cfg_use User interface: changing values
79 * This is the only interface you should use unless you want to let your
80 * own code become configurable with this.
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.
86 * string values are strdup'ed before use, so you can (and should) free
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;
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,
97 XBT_PUBLIC(void) xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options);
101 Set the value of the cell \a name in \a cfg with the provided value.
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,
106 XBT_PUBLIC(void) xbt_cfg_set_string(xbt_cfg_t cfg, const char *name,
108 XBT_PUBLIC(void) xbt_cfg_set_peer(xbt_cfg_t cfg, const char *name,
109 const char *peer, int port);
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.
115 XBT_PUBLIC(void) xbt_cfg_setdefault_int(xbt_cfg_t cfg, const char *name, int val);
116 XBT_PUBLIC(void) xbt_cfg_setdefault_double(xbt_cfg_t cfg, const char *name, double val);
117 XBT_PUBLIC(void) xbt_cfg_setdefault_string(xbt_cfg_t cfg, const char *name, const char* val);
118 XBT_PUBLIC(void) xbt_cfg_setdefault_peer(xbt_cfg_t cfg, const char *name, const char* host, int port);
122 Remove the provided value from the cell @name in @cfg.
124 XBT_PUBLIC(void) xbt_cfg_rm_int(xbt_cfg_t cfg, const char *name, int val);
125 XBT_PUBLIC(void) xbt_cfg_rm_double(xbt_cfg_t cfg, const char *name,
127 XBT_PUBLIC(void) xbt_cfg_rm_string(xbt_cfg_t cfg, const char *name,
129 XBT_PUBLIC(void) xbt_cfg_rm_peer(xbt_cfg_t cfg, const char *name,
130 const char *peer, int port);
133 Remove the value at position \e pos from the config \e cfg
135 XBT_PUBLIC(void) xbt_cfg_rm_at(xbt_cfg_t cfg, const char *name, int pos);
137 /* rm every values */
138 XBT_PUBLIC(void) xbt_cfg_empty(xbt_cfg_t cfg, const char *name);
142 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
143 * @ingroup XBT_config
148 /** @brief possible content of each configuration cell */
156 xbt_cfgelm_peer,/**< both a char* (representing the peername) and an integer (representing the port) */
158 xbt_cfgelm_any, /* not shown to users to prevent errors */
159 xbt_cfgelm_type_count
160 } e_xbt_cfgelm_type_t;
162 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
163 typedef void (*xbt_cfg_cb_t) (const char *, int);
165 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
166 XBT_PUBLIC(void) xbt_cfg_cpy(xbt_cfg_t tocopy, /* OUT */ xbt_cfg_t * whereto);
167 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
168 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent,
173 /** @defgroup XBT_cfg_register Registering stuff
174 * @ingroup XBT_config
176 * This how to add new variables to an existing configuration set. Use it to make your code
181 XBT_PUBLIC(void) xbt_cfg_register(xbt_cfg_t * cfg,
182 const char *name, const char *description,
183 e_xbt_cfgelm_type_t type,
184 void *default_value, int min, int max,
185 xbt_cfg_cb_t cb_set, xbt_cfg_cb_t cb_rm);
186 XBT_PUBLIC(void) xbt_cfg_unregister(xbt_cfg_t cfg, const char *name);
187 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
188 XBT_PUBLIC(void) xbt_cfg_help(xbt_cfg_t cfg);
189 XBT_PUBLIC(void) xbt_cfg_check(xbt_cfg_t cfg);
190 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg,
193 /** @defgroup XBT_cfg_get Getting the stored values
194 * @ingroup XBT_config
196 * This is how to retrieve the values stored in the configuration set. This is only
197 * intended to configurable code, naturally.
199 * Note that those function return a pointer to the values actually stored
200 * in the set. Do not modify them unless you really know what you're doing.
201 * Likewise, do not free the strings after use, they are not copy of the data,
202 * but the data themselves.
207 XBT_PUBLIC(int) xbt_cfg_get_int(xbt_cfg_t cfg, const char *name);
208 XBT_PUBLIC(double) xbt_cfg_get_double(xbt_cfg_t cfg, const char *name);
209 XBT_PUBLIC(char *) xbt_cfg_get_string(xbt_cfg_t cfg, const char *name);
210 XBT_PUBLIC(void) xbt_cfg_get_peer(xbt_cfg_t cfg, const char *name,
211 char **peer, int *port);
212 XBT_PUBLIC(xbt_dynar_t) xbt_cfg_get_dynar(xbt_cfg_t cfg, const char *name);
214 XBT_PUBLIC(int) xbt_cfg_get_int_at(xbt_cfg_t cfg, const char *name, int pos);
215 XBT_PUBLIC(double) xbt_cfg_get_double_at(xbt_cfg_t cfg, const char *name,
217 XBT_PUBLIC(char *) xbt_cfg_get_string_at(xbt_cfg_t cfg, const char *name,
219 XBT_PUBLIC(void) xbt_cfg_get_peer_at(xbt_cfg_t cfg, const char *name, int pos,
220 char **peer, int *port);
225 #endif /* _XBT_CONFIG_H_ */