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 their own configuration.
  24  *
  25  *  A configuration set contain several \e variables which have a unique name in the set and can take a given type of
  26  *  value. For example, it may contain a \a size variable, accepting \e int values.
  27  *
  28  *  It is impossible to set a value to a variable which has not been registered before.
  29  *  Usually, the module registers all the options it accepts in the configuration set, during its initialization and
  30  *  user code then set and unset values.
  31  *
  32  *  The easiest way to register a variable is to use the xbt_str_register_str function, which accepts a string
  33  *  representation of the config element descriptor. The syntax is the following:
  34  *  \verbatim <name>:<min nb>_to_<max nb>_<type>\endverbatim
  35  *
  36  *  For example, <tt>size:1_to_1_int</tt> describes a variable called \e size which must take exactly one value, and
  37  *  the value being an integer. Set the maximum to 0 to disable the upper bound on data count.
  38  *
  39  *  Another example could be <tt>outputfiles:0_to_10_string</tt> which describes a variable called \e outputfiles and
  40  *  which can take between 0 and 10 strings as value.
  41  *
  42  *  To some extend, configuration sets can be seen as typed hash structures.
  43  *
  44  *  \section XBT_cfg_ex Example of use
  45  *
  46  *  TBD
  47  */
  48 /** @defgroup XBT_cfg_use User interface: changing values
  49  *  @ingroup XBT_config
  50  *
  51  * This is the only interface you should use unless you want to let your own code become configurable with this.
  52  *
  53  * If the variable accept at most one value, those functions replace the current value with the provided one. If max>1,
  54  * the provided value is appended to the list.
  55  *
  56  * string values are strdup'ed before use, so you can (and should) free your copy
  57  *
  58  * @{
  59  */
  60 /** @brief Configuration set's data type is opaque. */
  61 #ifdef __cplusplus
  62 namespace simgrid {
  63 namespace config {
  64 class Config;
  65 }
  66 }
  67 typedef simgrid::config::Config* xbt_cfg_t;
  68 #else
  69 typedef void* xbt_cfg_t;
  70 #endif
  71
  72 XBT_PUBLIC(void) xbt_cfg_set_parse(const char *options);
  73
  74 /* Set the value of the cell \a name in \a cfg with the provided value.*/
  75 XBT_PUBLIC(void) xbt_cfg_set_int       (const char *name, int val);
  76 XBT_PUBLIC(void) xbt_cfg_set_double    (const char *name, double val);
  77 XBT_PUBLIC(void) xbt_cfg_set_string    (const char *name, const char *val);
  78 XBT_PUBLIC(void) xbt_cfg_set_boolean   (const char *name, const char *val);
  79 XBT_PUBLIC(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_PUBLIC(void) xbt_cfg_setdefault_int    (const char *name, int val);
  86 XBT_PUBLIC(void) xbt_cfg_setdefault_double (const char *name, double val);
  87 XBT_PUBLIC(void) xbt_cfg_setdefault_string (const char *name, const char *val);
  88 XBT_PUBLIC(void) xbt_cfg_setdefault_boolean(const char *name, const char *val);
  89
  90 /** @brief Return if configuration is set by default*/
  91 XBT_PUBLIC(int) xbt_cfg_is_default_value(const char *name);
  92
  93 /* @} */
  94
  95 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
  96  *  @ingroup XBT_config
  97  *
  98  *  @{
  99  */
 100
 101 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
 102 typedef void (*xbt_cfg_cb_t) (const char * name);
 103
 104 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
 105 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
 106 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent, xbt_cfg_t cfg);
 107
 108  /** @} */
 109
 110 /** @defgroup XBT_cfg_register  Registering stuff
 111  *  @ingroup XBT_config
 112  *
 113  *  This how to add new variables to an existing configuration set. Use it to make your code configurable.
 114  *
 115  *  @{
 116  */
 117 XBT_PUBLIC(void) xbt_cfg_register_double (const char *name, double default_val,    xbt_cfg_cb_t cb_set, const char *desc);
 118 XBT_PUBLIC(void) xbt_cfg_register_int    (const char *name, int default_val,       xbt_cfg_cb_t cb_set, const char *desc);
 119 XBT_PUBLIC(void) xbt_cfg_register_string (const char *name, const char*default_val,xbt_cfg_cb_t cb_set, const char *desc);
 120 XBT_PUBLIC(void) xbt_cfg_register_boolean(const char *name, const char*default_val,xbt_cfg_cb_t cb_set, const char *desc);
 121 XBT_PUBLIC(void) xbt_cfg_register_alias(const char *newname, const char *oldname);
 122
 123 XBT_PUBLIC(void) xbt_cfg_aliases(void);
 124 XBT_PUBLIC(void) xbt_cfg_help(void);
 125
 126 /*  @} */
 127 /** @defgroup XBT_cfg_get Getting the stored values
 128  *  @ingroup XBT_config
 129  *
 130  * This is how to retrieve the values stored in the configuration set. This is only intended to configurable code,
 131  * naturally.
 132  *
 133  * Note that those function return a pointer to the values actually stored in the set. Do not modify them unless you
 134  * really know what you're doing. Likewise, do not free the strings after use, they are not copy of the data, but the
 135  * data themselves.
 136  *
 137  *  @{
 138  */
 139
 140 XBT_PUBLIC(int)    xbt_cfg_get_int(const char *name);
 141 XBT_PUBLIC(double) xbt_cfg_get_double(const char *name);
 142 XBT_PUBLIC(char *) xbt_cfg_get_string(const char *name);
 143 XBT_PUBLIC(int)    xbt_cfg_get_boolean(const char *name);
 144
 145 /** @} */
 146
 147 SG_END_DECL()
 148 #endif                          /* _XBT_CONFIG_H_ */