include/xbt/config.h

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