Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Sonar: dont't duplicate declarations.
[simgrid.git] / include / xbt / config.h
1 /* config - Dictionary where the type of each cell is provided.             */
2 /* This is useful to build named structs, like option or property sets.     */
3
4 /* Copyright (c) 2004-2018. The SimGrid Team. All rights reserved.          */
5
6 /* This program is free software; you can redistribute it and/or modify it
7  * under the terms of the license (GNU LGPL) which comes with this package. */
8
9 #ifndef XBT_CONFIG_H
10 #define XBT_CONFIG_H
11
12 #include <stdarg.h>
13 #include <xbt/base.h>
14
15 /** @addtogroup XBT_config
16  *  @brief Changing the configuration of SimGrid components (grounding feature)
17  *
18  *  All modules of the SimGrid toolkit can be configured with this API.
19  *  User modules and libraries can also use these facilities to handle their own configuration.
20  *
21  *  A configuration set contain several \e variables which have a unique name in the set and can take a given type of
22  *  value. For example, it may contain a \a size variable, accepting \e int values.
23  *
24  *  It is impossible to set a value to a variable which has not been registered before.
25  *  Usually, the module registers all the options it accepts in the configuration set, during its initialization and
26  *  user code then set and unset values.
27  *
28  *  The easiest way to register a variable is to use the xbt_str_register_str function, which accepts a string
29  *  representation of the config element descriptor. The syntax is the following:
30  *  \verbatim <name>:<min nb>_to_<max nb>_<type>\endverbatim
31  *
32  *  For example, <tt>size:1_to_1_int</tt> describes a variable called \e size which must take exactly one value, and
33  *  the value being an integer. Set the maximum to 0 to disable the upper bound on data count.
34  *
35  *  Another example could be <tt>outputfiles:0_to_10_string</tt> which describes a variable called \e outputfiles and
36  *  which can take between 0 and 10 strings as value.
37  *
38  *  To some extend, configuration sets can be seen as typed hash structures.
39  *
40  *  \section XBT_cfg_ex Example of use
41  *
42  *  TBD
43  */
44 /** @defgroup XBT_cfg_use User interface: changing values
45  *  @ingroup XBT_config
46  *
47  * This is the only interface you should use unless you want to let your own code become configurable with this.
48  *
49  * If the variable accept at most one value, those functions replace the current value with the provided one. If max>1,
50  * the provided value is appended to the list.
51  *
52  * string values are strdup'ed before use, so you can (and should) free your copy
53  *
54  * @{
55  */
56 /** @brief Configuration set's data type is opaque. */
57 #ifdef __cplusplus
58 #include <xbt/config.hpp>
59 typedef simgrid::config::Config* xbt_cfg_t;
60 #else
61 typedef void* xbt_cfg_t;
62 #endif
63
64 SG_BEGIN_DECL()
65
66 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_parse") XBT_PUBLIC
67     void xbt_cfg_set_parse(const char* options);
68
69 /* Set the value of the cell \a name in \a cfg with the provided value.*/
70 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value<int>") XBT_PUBLIC
71     void xbt_cfg_set_int(const char* name, int val);
72 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value<double>") XBT_PUBLIC
73     void xbt_cfg_set_double(const char* name, double val);
74 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value<bool>") XBT_PUBLIC
75     void xbt_cfg_set_boolean(const char* name, const char* val);
76 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_value<std::string>") XBT_PUBLIC
77     void xbt_cfg_set_string(const char* name, const char* val);
78 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_as_string") XBT_PUBLIC
79     void xbt_cfg_set_as_string(const char* name, const char* val);
80
81 /*
82   Set the default value of the cell \a name in \a cfg with the provided value.
83   If it was already set to something (possibly from the command line), do nothing.
84  */
85 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_default<int>") XBT_PUBLIC
86     void xbt_cfg_setdefault_int(const char* name, int val);
87 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_default<double>") XBT_PUBLIC
88     void xbt_cfg_setdefault_double(const char* name, double val);
89 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_default<bool>") XBT_PUBLIC
90     void xbt_cfg_setdefault_boolean(const char* name, const char* val);
91 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::set_default<std::string>") XBT_PUBLIC
92     void xbt_cfg_setdefault_string(const char* name, const char* val);
93
94 /** @brief Return if configuration is set by default*/
95 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::is_default") XBT_PUBLIC
96     int xbt_cfg_is_default_value(const char* name);
97
98 /* @} */
99
100 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
101  *  @ingroup XBT_config
102  *
103  *  @{
104  */
105
106 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
107 typedef void (*xbt_cfg_cb_t)(const char* name);
108
109 XBT_ATTRIB_DEPRECATED_v323("Please don't use it") XBT_PUBLIC xbt_cfg_t xbt_cfg_new();
110 XBT_ATTRIB_DEPRECATED_v323("Please don't use it") XBT_PUBLIC void xbt_cfg_free(xbt_cfg_t* cfg);
111 XBT_ATTRIB_DEPRECATED_v323("Please don't use it") XBT_PUBLIC
112     void xbt_cfg_dump(const char* name, const char* indent, xbt_cfg_t cfg);
113
114 /** @} */
115
116 /** @defgroup XBT_cfg_register  Registering stuff
117  *  @ingroup XBT_config
118  *
119  *  This how to add new variables to an existing configuration set. Use it to make your code configurable.
120  *
121  *  @{
122  */
123 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::declare_flag<double>") XBT_PUBLIC
124     void xbt_cfg_register_double(const char* name, double default_val, xbt_cfg_cb_t cb_set, const char* desc);
125 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::declare_flag<int>") XBT_PUBLIC
126     void xbt_cfg_register_int(const char* name, int default_val, xbt_cfg_cb_t cb_set, const char* desc);
127 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::declare_flag<std::string>") XBT_PUBLIC
128     void xbt_cfg_register_string(const char* name, const char* default_val, xbt_cfg_cb_t cb_set, const char* desc);
129 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::declare_flag<bool>") XBT_PUBLIC
130     void xbt_cfg_register_boolean(const char* name, const char* default_val, xbt_cfg_cb_t cb_set, const char* desc);
131 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::alias") XBT_PUBLIC
132     void xbt_cfg_register_alias(const char* newname, const char* oldname);
133
134 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::show_aliases") XBT_PUBLIC void xbt_cfg_aliases();
135 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::help") XBT_PUBLIC void xbt_cfg_help();
136
137 /*  @} */
138 /** @defgroup XBT_cfg_get Getting the stored values
139  *  @ingroup XBT_config
140  *
141  * This is how to retrieve the values stored in the configuration set. This is only intended to configurable code,
142  * naturally.
143  *
144  * Note that those function return a pointer to the values actually stored in the set. Do not modify them unless you
145  * really know what you're doing. Likewise, do not free the strings after use, they are not copy of the data, but the
146  * data themselves.
147  *
148  *  @{
149  */
150
151 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::get_value<int>") XBT_PUBLIC
152     int xbt_cfg_get_int(const char* name);
153 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::get_value<double>") XBT_PUBLIC
154     double xbt_cfg_get_double(const char* name);
155 XBT_ATTRIB_DEPRECATED_v323("Please use simgrid::config::get_value<bool>") XBT_PUBLIC
156     int xbt_cfg_get_boolean(const char* name);
157
158 /** @} */
159
160 SG_END_DECL()
161 #endif /* XBT_CONFIG_H */