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 "xbt/dynar.h"
  15 #include <stdarg.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_as_string(xbt_cfg_t cfg, const char *name, const char *val);
 108
 109 /*
 110   Set the default value of the cell \a name in \a cfg with the provided value.
 111   If it was already set to something (possibly from the command line), do nothing.
 112  */
 113 XBT_PUBLIC(void) xbt_cfg_setdefault_int(xbt_cfg_t cfg, const char *name,
 114                                         int val);
 115 XBT_PUBLIC(void) xbt_cfg_setdefault_double(xbt_cfg_t cfg, const char *name,
 116                                            double val);
 117 XBT_PUBLIC(void) xbt_cfg_setdefault_string(xbt_cfg_t cfg, const char *name,
 118                                            const char *val);
 119 XBT_PUBLIC(void) xbt_cfg_setdefault_boolean(xbt_cfg_t cfg, const char *name,
 120                                         const char *val);
 121
 122 /*
 123  Remove the provided value from the cell @name in @cfg.
 124  */
 125 XBT_PUBLIC(void) xbt_cfg_rm_int(xbt_cfg_t cfg, const char *name, int val);
 126 XBT_PUBLIC(void) xbt_cfg_rm_double(xbt_cfg_t cfg, const char *name,
 127                                    double val);
 128 XBT_PUBLIC(void) xbt_cfg_rm_string(xbt_cfg_t cfg, const char *name,
 129                                    const char *val);
 130 XBT_PUBLIC(void) xbt_cfg_rm_boolean(xbt_cfg_t cfg, const char *name, int val);
 131
 132 /*
 133  Remove the value at position \e pos from the config \e cfg
 134  */
 135 XBT_PUBLIC(void) xbt_cfg_rm_at(xbt_cfg_t cfg, const char *name, int pos);
 136
 137 /* rm every values */
 138 XBT_PUBLIC(void) xbt_cfg_empty(xbt_cfg_t cfg, const char *name);
 139
 140 /* Return if configuration is set by default*/
 141 XBT_PUBLIC(int) xbt_cfg_is_default_value(xbt_cfg_t cfg, const char *name);
 142
 143 /* @} */
 144
 145 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
 146  *  @ingroup XBT_config
 147  *
 148  *  @{
 149  */
 150
 151   /** @brief possible content of each configuration cell */
 152 typedef enum {
 153   xbt_cfgelm_int = 0,
 154                        /**< int */
 155   xbt_cfgelm_double,
 156                        /**< double */
 157   xbt_cfgelm_string,
 158                        /**< char* */
 159   xbt_cfgelm_boolean,  /**< int */
 160
 161   //! @cond
 162   xbt_cfgelm_any,               /* not shown to users to prevent errors */
 163   xbt_cfgelm_type_count
 164   //! @endcond
 165 } e_xbt_cfgelm_type_t;
 166
 167 /** Boolean possible values **/
 168
 169 struct xbt_boolean_couple {
 170   const char *true_val;
 171   const char *false_val;
 172 };
 173
 174
 175
 176
 177 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
 178 typedef void (*xbt_cfg_cb_t) (const char *, int);
 179
 180 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
 181 XBT_PUBLIC(void) xbt_cfg_cpy(xbt_cfg_t tocopy,  /* OUT */
 182                              xbt_cfg_t * whereto);
 183 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
 184 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent,
 185                               xbt_cfg_t cfg);
 186
 187  /** @} */
 188
 189 /** @defgroup XBT_cfg_register  Registering stuff
 190  *  @ingroup XBT_config
 191  *
 192  *  This how to add new variables to an existing configuration set. Use it to make your code
 193  *  configurable.
 194  *
 195  *  @{
 196  */
 197 XBT_PUBLIC(void) xbt_cfg_register(xbt_cfg_t * cfg,
 198                                   const char *name,
 199                                   const char *description,
 200                                   e_xbt_cfgelm_type_t type,
 201                                   int min, int max,
 202                                   xbt_cfg_cb_t cb_set, xbt_cfg_cb_t cb_rm);
 203 XBT_PUBLIC(void) xbt_cfg_unregister(xbt_cfg_t cfg, const char *name);
 204 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
 205 XBT_PUBLIC(void) xbt_cfg_help(xbt_cfg_t cfg);
 206 XBT_PUBLIC(void) xbt_cfg_check(xbt_cfg_t cfg);
 207 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg,
 208                                                  const char *name);
 209 /*  @} */
 210 /** @defgroup XBT_cfg_get Getting the stored values
 211  *  @ingroup XBT_config
 212  *
 213  * This is how to retrieve the values stored in the configuration set. This is only
 214  * intended to configurable code, naturally.
 215  *
 216  * Note that those function return a pointer to the values actually stored
 217  * in the set. Do not modify them unless you really know what you're doing.
 218  * Likewise, do not free the strings after use, they are not copy of the data,
 219  * but the data themselves.
 220  *
 221  *  @{
 222  */
 223
 224 XBT_PUBLIC(int) xbt_cfg_get_int(xbt_cfg_t cfg, const char *name);
 225 XBT_PUBLIC(double) xbt_cfg_get_double(xbt_cfg_t cfg, const char *name);
 226 XBT_PUBLIC(char *) xbt_cfg_get_string(xbt_cfg_t cfg, const char *name);
 227 XBT_PUBLIC(int) xbt_cfg_get_boolean(xbt_cfg_t cfg, const char *name);
 228 XBT_PUBLIC(xbt_dynar_t) xbt_cfg_get_dynar(xbt_cfg_t cfg, const char *name);
 229
 230 XBT_PUBLIC(int) xbt_cfg_get_int_at(xbt_cfg_t cfg, const char *name,
 231                                    int pos);
 232 XBT_PUBLIC(double) xbt_cfg_get_double_at(xbt_cfg_t cfg, const char *name,
 233                                          int pos);
 234 XBT_PUBLIC(char *) xbt_cfg_get_string_at(xbt_cfg_t cfg, const char *name,
 235                                          int pos);
 236 XBT_PUBLIC(int) xbt_cfg_get_boolean_at(xbt_cfg_t cfg, const char *name,
 237                                    int pos);
 238
 239 /** @} */
 240
 241 SG_END_DECL()
 242 #endif                          /* _XBT_CONFIG_H_ */