From 707e365f2ebe9132b004da4995f4a705df9e5582 Mon Sep 17 00:00:00 2001 From: mquinson Date: Sun, 13 Feb 2005 15:49:07 +0000 Subject: [PATCH] doxygenification git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@986 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/xbt/config.h | 201 +++++++++++++++++++++++++++-------------- include/xbt/context.h | 29 ++++-- include/xbt/dict.h | 1 + include/xbt/dynar.h | 203 +++++++++++++++++++++++++++++------------- include/xbt/error.h | 40 +++++---- include/xbt/heap.h | 1 + include/xbt/misc.h | 9 -- include/xbt/set.h | 94 +++++++++++-------- 8 files changed, 374 insertions(+), 204 deletions(-) diff --git a/include/xbt/config.h b/include/xbt/config.h index ed294df271..ec201ab4ef 100644 --- a/include/xbt/config.h +++ b/include/xbt/config.h @@ -15,64 +15,113 @@ #include "xbt/dynar.h" BEGIN_DECL() - -/* For now, a config is only a special dynar. But don't rely on it, */ -/* it may change in the future. */ -typedef xbt_dynar_t xbt_cfg_t; - -/* type of a typed hash cell */ -typedef enum { - xbt_cfgelm_int=0, xbt_cfgelm_double, xbt_cfgelm_string, xbt_cfgelm_host, - xbt_cfgelm_type_count -} e_xbt_cfgelm_type_t; - -/*----[ Memory management ]-----------------------------------------------*/ -xbt_cfg_t xbt_cfg_new (void); -void xbt_cfg_cpy(xbt_cfg_t tocopy, - /* OUT */ xbt_cfg_t *whereto); -void xbt_cfg_free(xbt_cfg_t *cfg); -void xbt_cfg_dump(const char *name,const char*indent,xbt_cfg_t cfg); - -/*----[ Registering stuff ]-----------------------------------------------*/ -/* Register a possible cell */ -void xbt_cfg_register(xbt_cfg_t cfg, - const char *name, e_xbt_cfgelm_type_t type, - int min, int max); -/* Unregister a possible cell */ -xbt_error_t xbt_cfg_unregister(xbt_cfg_t cfg, const char *name); - -/* Parse the configuration descriptor and register it */ -/* Should be of the form ":_to__", */ -/* with type being one of 'string','int', 'host' or 'double' */ -xbt_error_t xbt_cfg_register_str(xbt_cfg_t cfg, const char *entry); - -/* Check that each cell have the right amount of elements */ -xbt_error_t xbt_cfg_check(xbt_cfg_t cfg); - -/* Get the type of this option in that repository */ -xbt_error_t xbt_cfg_get_type(xbt_cfg_t cfg, const char *name, - /* OUT */ e_xbt_cfgelm_type_t *type); -/*----[ Setting ]--------------------------------------------------------- - * xbt_cfg_set_* functions. +/** @addtogroup XBT_config + * + * All modules of the SimGrid toolkit can be configured with this API. + * User modules and libraries can also use these facilities to handle + * their own configuration. + * + * A configuration set contain several \e variables which have a uniq name + * in the set and can take a given type of value. For example, it may + * contain a \a size variable, accepting \e int values. + * Moreover, of values. + * + * It is impossible to set a value to a variable which has not been registered before. + * Usually, the module registers all the options it accepts in the configuration set, + * during its initialization and user code then set and unset values. + * + * The easiest way to register a variable is to use the xbt_str_register_str function, + * which accepts a string representation of the config element descriptor. The syntax + * is the following: \verbatim :_to__\endverbatim + * + * For example, size:1_to_1_int describes a variable called \e size which + * must take exactly one value, and the value being an integer. + * + * Another example could be outputfiles:0_to_10_string which describes a variable + * called \e outputfiles and which can take between 0 and 10 strings as value. + * + * To some extend, configuration sets can be seen as typed hash structures. + * + * \todo This great mecanism is not used in SimGrid yet... + * + * \todo We need a callback mecanism so that the configurable code get + * notified of configuration changes. + * + * \section XBT_cfg_ex Example + * + * \dontinclude config_usage.c + * + * First, let's create a configuration set with some registered variables. + * This must be done by the configurable library before the user interactions. + * + * \skip make_set + * \until end_of_make_set + * + * Now, set and get a single value + * \skip get_single_value + * \skip int + * \until cfg_free + * + * And now, set and get a multiple value + * \skip get_multiple_value + * \skip dyn + * \until cfg_free + * + * All those functions throws mismatch_error if asked to deal with an + * unregistered variable. + * \skip myset + * \until cfg_free + * @{ + */ + +/** @name 1. Type declaration and memory management * - * If the registered maximum is equal to 1, those functions remplace the + * + * + * @{ + */ + /** @brief Configuration set are only special dynars. But don't rely on it, it may change. */ + typedef xbt_dynar_t xbt_cfg_t; + + /** @brief possible content of each configuration cell */ + typedef enum { + xbt_cfgelm_int=0, /**< int */ + xbt_cfgelm_double, /**< double */ + xbt_cfgelm_string, /**< char* */ + xbt_cfgelm_host, /**< both a char* (representing the hostname) and an integer (representing the port) */ + xbt_cfgelm_type_count + } e_xbt_cfgelm_type_t; + + xbt_cfg_t xbt_cfg_new (void); + void xbt_cfg_cpy(xbt_cfg_t tocopy, /* OUT */ xbt_cfg_t *whereto); + void xbt_cfg_free(xbt_cfg_t *cfg); + void xbt_cfg_dump(const char *name,const char*indent,xbt_cfg_t cfg); + + /** @} */ + +/** @name 2. User interface: changing values + * + * This is the only interface you should use unless you want to let your + * own code become configurable with this. + * + * If the variable accept at most one value, those functions replace the * current value with the provided one. If max>1, the provided value is * appended to the list. * - * string values are strdup'ed before use, so you have to free your copy */ - -xbt_error_t xbt_cfg_set_vargs(xbt_cfg_t cfg, va_list pa); -xbt_error_t xbt_cfg_set(xbt_cfg_t cfg, ...); - -/* - Add the cells described in a string to a typed hash. + * string values are strdup'ed before use, so you can (and should) free + * your copy + * + * @{ */ -xbt_error_t xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options); + + xbt_error_t xbt_cfg_set(xbt_cfg_t cfg, ...); + xbt_error_t xbt_cfg_set_vargs(xbt_cfg_t cfg, va_list pa); + xbt_error_t xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options); /* - Set the value of the cell @name in @cfg with the provided value. + Set the value of the cell \a name in \a cfg with the provided value. */ xbt_error_t xbt_cfg_set_int (xbt_cfg_t cfg, const char *name, int val); @@ -98,26 +147,42 @@ xbt_error_t xbt_cfg_rm_host (xbt_cfg_t cfg, const char *name, /* rm every values */ xbt_error_t xbt_cfg_empty(xbt_cfg_t cfg, const char *name); -/*----[ Getting ]---------------------------------------------------------*/ -/* Returns a pointer to the values actually stored in the cache. Do not */ -/* modify them unless you really know what you're doing. */ -xbt_error_t xbt_cfg_get_int (xbt_cfg_t cfg, - const char *name, - int *val); -xbt_error_t xbt_cfg_get_double(xbt_cfg_t cfg, - const char *name, - double *val); -xbt_error_t xbt_cfg_get_string(xbt_cfg_t cfg, - const char *name, - char **val); -xbt_error_t xbt_cfg_get_host (xbt_cfg_t cfg, - const char *name, - char **host, - int *port); -xbt_error_t xbt_cfg_get_dynar (xbt_cfg_t cfg, - const char *name, - /* OUT */ xbt_dynar_t *dynar); +/* @} */ +/** @name 3. Registering stuff + * + * This how to add new variables to an existing configuration set. Use it to make your code + * configurable. + * + * @{ + */ + void xbt_cfg_register(xbt_cfg_t cfg, + const char *name, e_xbt_cfgelm_type_t type, + int min, int max); + xbt_error_t xbt_cfg_unregister(xbt_cfg_t cfg, const char *name); + xbt_error_t xbt_cfg_register_str(xbt_cfg_t cfg, const char *entry); + xbt_error_t xbt_cfg_check(xbt_cfg_t cfg); + xbt_error_t xbt_cfg_get_type(xbt_cfg_t cfg, const char *name, + /* OUT */ e_xbt_cfgelm_type_t *type); +/* @} */ +/** @name 4. Getting the stored values + * + * This is how to retrieve the values stored in the configuration set. This is only + * intended to configurable code, naturally. + * + * Note that those function return a pointer to the values actually stored + * in the set. Do not modify them unless you really know what you're doing. + * + * @{ + */ + + xbt_error_t xbt_cfg_get_int (xbt_cfg_t cfg, const char *name, int *val); + xbt_error_t xbt_cfg_get_double(xbt_cfg_t cfg, const char *name, double *val); + xbt_error_t xbt_cfg_get_string(xbt_cfg_t cfg, const char *name, char **val); + xbt_error_t xbt_cfg_get_host (xbt_cfg_t cfg, const char *name, char **host, int *port); + xbt_error_t xbt_cfg_get_dynar (xbt_cfg_t cfg, const char *name, xbt_dynar_t *dynar); +/** @} */ +/** @} */ END_DECL() #endif /* _XBT_CONFIG_H_ */ diff --git a/include/xbt/context.h b/include/xbt/context.h index 8e7b6469e5..fd744d3b81 100644 --- a/include/xbt/context.h +++ b/include/xbt/context.h @@ -9,15 +9,26 @@ #define _XBT_CONTEXT_H #include "xbt/misc.h" +#include "xbt/dynar.h" /* void_f_pvoid_t */ + +/** @addtogroup XBT_context + * + * INTERNALS OF SIMGRID, DON'T USE IT. + * + * This is a portable to Unix and Windows context implementation. + * + * @{ + */ + +/** @name Context types + * @{ + */ + + /** @brief A context */ + typedef struct s_xbt_context *xbt_context_t; + /** @brief A context function */ + typedef int(*xbt_context_function_t)(int argc, char *argv[]); -/** \name Context types - * \ingroup XBT_context -*/ -/*@{*/ -typedef struct s_xbt_context *xbt_context_t; -/**< A context */ -typedef int(*xbt_context_function_t)(int argc, char *argv[]); -/**< A context function */ /*@}*/ void xbt_context_init(void); @@ -31,5 +42,5 @@ void xbt_context_free(xbt_context_t context); void xbt_context_start(xbt_context_t context); void xbt_context_yield(void); void xbt_context_schedule(xbt_context_t context); - +/*@} */ #endif /* _XBT_CONTEXT_H */ diff --git a/include/xbt/dict.h b/include/xbt/dict.h index 8153b3ede9..e9fdb4cc8f 100644 --- a/include/xbt/dict.h +++ b/include/xbt/dict.h @@ -13,6 +13,7 @@ #include "xbt/misc.h" /* BEGIN_DECL */ #include "xbt/error.h" +#include "xbt/dynar.h" /* void_f_pvoid_t */ BEGIN_DECL() diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h index 062e9442d6..7e09bb5745 100644 --- a/include/xbt/dynar.h +++ b/include/xbt/dynar.h @@ -14,69 +14,149 @@ BEGIN_DECL() -/** \brief Dictionnary data type - \ingroup XBT_dynar -*/ -typedef struct xbt_dynar_s *xbt_dynar_t; +/** \addtogroup XBT_dynar + * + * For performance concerns, the content of DynArr must be homogeneous (in + * contrary to dictionnaries -- see the \ref XBT_dict section). You thus + * have to provide the function which will be used to free the content at + * structure creation (of type void_f_ppvoid_t or void_f_pvoid_t). + * + * \section XBT_dynar_exscal Example with scalar + * \dontinclude dynar_int.c + * + * \skip Vars_decl + * \skip dyn + * \until iptr + * \skip Populate_ints + * \skip dyn + * \until end_of_traversal + * \skip shifting + * \skip val + * \until xbt_dynar_free + * + * \section XBT_dynar_exptr Example with pointed data + * \dontinclude dynar_string.c + * + * \skip doxygen_first_cruft + * \skip f + * \until xbt_init + * \skip Populate_str + * \skip dyn + * \until } + * \skip macro + * \until dynar_free + * \skip xbt_exit + * \until } + * @{ + */ + +/** @name 1. Constructor/destructor + * @{ + */ + /** \brief Dynar data type (opaque type) */ + typedef struct xbt_dynar_s *xbt_dynar_t; -xbt_dynar_t xbt_dynar_new(unsigned long elm_size, - void_f_pvoid_t *free_func); -void xbt_dynar_free(xbt_dynar_t *dynar); -void xbt_dynar_free_container(xbt_dynar_t *dynar); + /** \brief Pointer to a function freeing a pointed data */ + typedef void (void_f_ppvoid_t)(void**); + /** \brief Pointer to a function freeing some data */ + typedef void (void_f_pvoid_t) (void*); -unsigned long xbt_dynar_length(const xbt_dynar_t dynar); -void xbt_dynar_reset(xbt_dynar_t dynar); + xbt_dynar_t xbt_dynar_new(unsigned long elm_size, + void_f_pvoid_t *free_func); + void xbt_dynar_free(xbt_dynar_t *dynar); + void xbt_dynar_free_container(xbt_dynar_t *dynar); + unsigned long xbt_dynar_length(const xbt_dynar_t dynar); + void xbt_dynar_reset(xbt_dynar_t dynar); -/* regular array functions */ -void xbt_dynar_get_cpy(const xbt_dynar_t dynar, int idx, void *const dst); -void *xbt_dynar_get_ptr(const xbt_dynar_t dynar, - const int idx); +/** @name 2. regular array functions + * @{ + */ -#define xbt_dynar_get_as(dynar,idx,type) *(type*)xbt_dynar_get_ptr(dynar,idx) + void xbt_dynar_get_cpy(const xbt_dynar_t dynar, int idx, void *const dst); -void xbt_dynar_set(xbt_dynar_t dynar, int idx, const void *src); -void xbt_dynar_replace(xbt_dynar_t dynar, - int idx, const void *object); - -/* perl array function */ - -void xbt_dynar_insert_at(xbt_dynar_t dynar, - int idx, const void *src); -void xbt_dynar_remove_at(xbt_dynar_t dynar, - int idx, void *object); -void xbt_dynar_push (xbt_dynar_t dynar, const void *src); -void xbt_dynar_pop (xbt_dynar_t dynar, void *const dst); -void xbt_dynar_unshift (xbt_dynar_t dynar, const void *src); -void xbt_dynar_shift (xbt_dynar_t dynar, void *const dst); -void xbt_dynar_map (const xbt_dynar_t dynar, void_f_pvoid_t *operator); - -/* speed-optimized versions */ -void *xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar, - const int idx); -void *xbt_dynar_push_ptr(xbt_dynar_t dynar); -void *xbt_dynar_pop_ptr(xbt_dynar_t dynar); - -#define xbt_dynar_insert_at_as(dynar,idx,type,value) *(type*)xbt_dynar_insert_at_ptr(dynar,idx)=value -#define xbt_dynar_push_as(dynar,type,value) *(type*)xbt_dynar_push_ptr(dynar)=value -#define xbt_dynar_pop_as(dynar,type) *(type*)xbt_dynar_pop_ptr(dynar) - - -/* cursor functions */ -void xbt_dynar_cursor_first (const xbt_dynar_t dynar, int *cursor); -void xbt_dynar_cursor_step (const xbt_dynar_t dynar, int *cursor); -int xbt_dynar_cursor_get (const xbt_dynar_t dynar, int *cursor, void *whereto); - - -/** - \brief Dynar iterator - \ingroup XBT_dynar - * xbt_dynar_foreach: - * \param _dynar what to iterate over - * \param _cursor an integer used as cursor - * \param _data + void xbt_dynar_set(xbt_dynar_t dynar, int idx, const void *src); + void xbt_dynar_replace(xbt_dynar_t dynar, int idx, const void *object); + + void xbt_dynar_insert_at(xbt_dynar_t dynar, int idx, const void *src); + void xbt_dynar_remove_at(xbt_dynar_t dynar, int idx, void *object); + +/** @} */ +/** @name 2. Perl-like functions + * @{ + */ + + void xbt_dynar_push (xbt_dynar_t dynar, const void *src); + void xbt_dynar_pop (xbt_dynar_t dynar, void *const dst); + void xbt_dynar_unshift (xbt_dynar_t dynar, const void *src); + void xbt_dynar_shift (xbt_dynar_t dynar, void *const dst); + void xbt_dynar_map (const xbt_dynar_t dynar, void_f_pvoid_t *operator); + +/** @} */ +/** @name 3. Manipulating pointers to the content + * + * Those functions do not retrive the content, but only their address. + * + * @{ + */ + + void *xbt_dynar_get_ptr(const xbt_dynar_t dynar, const int idx); + void *xbt_dynar_insert_at_ptr(xbt_dynar_t const dynar, const int idx); + void *xbt_dynar_push_ptr(xbt_dynar_t dynar); + void *xbt_dynar_pop_ptr(xbt_dynar_t dynar); + +/** @} */ +/** @name 4. Speed optimized functions for scalars + * + * While the other functions use a memcpy to retrive the content into the + * user provided area, those ones use a regular affectation. It only works + * for scalar values, but should be a little faster. + * + * @{ + */ + + /** @brief Quick retrieval of scalar content + * @hideinitializer */ +# define xbt_dynar_get_as(dynar,idx,type) \ + *(type*)xbt_dynar_get_ptr(dynar,idx) + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_insert_at_as(dynar,idx,type,value) \ + *(type*)xbt_dynar_insert_at_ptr(dynar,idx)=value + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_push_as(dynar,type,value) \ + *(type*)xbt_dynar_push_ptr(dynar)=value + /** @brief Quick insertion of scalar content + * @hideinitializer */ +# define xbt_dynar_pop_as(dynar,type) \ + *(type*)xbt_dynar_pop_ptr(dynar) + +/** @} */ +/** @name 5. Cursors on DynArr + * + * Cursors are used to iterate over the structure. Never add elements to the + * DynArr during the traversal. To remove elements, use the + * xbt_dynar_cursor_rm() function + * + * @{ + */ + + void xbt_dynar_cursor_first (const xbt_dynar_t dynar, int *cursor); + void xbt_dynar_cursor_step (const xbt_dynar_t dynar, int *cursor); + int xbt_dynar_cursor_get (const xbt_dynar_t dynar, int *cursor, + void *whereto); + void xbt_dynar_cursor_rm(xbt_dynar_t dynar, + int *const cursor); + + +/** @brief Iterates over the whole dynar. + * + * @param _dynar what to iterate over + * @param _cursor an integer used as cursor + * @param _data + * @hideinitializer * - * Iterates over the whole dynar. * \note An example of usage: * \code xbt_dynar_t dyn; @@ -91,14 +171,9 @@ xbt_dynar_foreach (dyn,cpt,str) { for (xbt_dynar_cursor_first(_dynar,&(_cursor)) ; \ xbt_dynar_cursor_get(_dynar,&(_cursor),&_data) ; \ xbt_dynar_cursor_step(_dynar,&(_cursor)) ) -/* - for (xbt_dynar_length(_dynar) && (_xbt_dynar_cursor_first(_dynar,&_cursor), \ - 1); \ - xbt_dynar_length(_dynar) && xbt_dynar_cursor_get(_dynar,&_cursor,&_data); \ - xbt_dynar_cursor_step(_dynar,&_cursor)) -*/ -void xbt_dynar_cursor_rm(xbt_dynar_t dynar, - int *const cursor); + END_DECL() + +/*@}*/ #endif /* _XBT_DYNAR_H */ diff --git a/include/xbt/error.h b/include/xbt/error.h index 08647392a0..06a58aa3c0 100644 --- a/include/xbt/error.h +++ b/include/xbt/error.h @@ -15,10 +15,6 @@ #include "xbt/misc.h" /* BEGIN_DECL */ #include "xbt/log.h" -#ifdef HAVE_EXECINFO_H -#include /* to print the backtrace */ -#endif - BEGIN_DECL() #define _XBT_ERR_PRE do { @@ -27,15 +23,16 @@ BEGIN_DECL() } while (0) /** @addtogroup XBT_error + * + * This is how the errors get reported in the SimGrid toolkit. This mecanism is not + * as powerful as exceptions, but since we're using C, there is not much we can do. + * * @{*/ -/** \brief Kill the programm in silence */ -void xbt_abort(void) _XBT_GNUC_NORETURN; - -/** \brief Kill the programm with an error message */ -void xbt_die(const char *msg) _XBT_GNUC_NORETURN; - - +/** @name 1. Type definition and basic operations + * + * @{ + */ /** \brief Error types */ typedef enum { no_error=0, /**< succes */ @@ -56,9 +53,13 @@ typedef enum { remote_unknown_error } xbt_error_t; -const char *xbt_error_name(xbt_error_t errcode); + const char *xbt_error_name(xbt_error_t errcode); + void xbt_abort(void) _XBT_GNUC_NORETURN; + void xbt_die(const char *msg) _XBT_GNUC_NORETURN; -/** @name TRY macro family +/** @} */ + +/** @name 2. TRY macro family * * Those functions are used to launch a function call and react automatically * to its return value. They expect such a variable to be declared in the scope: @@ -109,9 +110,11 @@ const char *xbt_error_name(xbt_error_t errcode); } while(0) /** @}*/ -/** @name RAISE macro family +/** @name 3. RAISE macro family * * Return a error code, doing some logs on stderr. + * + * @todo This should use the logging features, not stderr * * @{ */ @@ -154,10 +157,10 @@ const char *xbt_error_name(xbt_error_t errcode); /**@}*/ /** - * \name assert macro familly + * \name 4. assert macro familly * * Those are the GRAS version of the good ol' assert macro. You can pass them a format message and - * arguments, just as if it where a printf. + * arguments, just as if it where a printf. It is converted to a CRITICALn logging request. * * @{ */ @@ -171,7 +174,8 @@ const char *xbt_error_name(xbt_error_t errcode); #define xbt_assert5(cond,msg,a,b,c,d,e) #define xbt_assert6(cond,msg,a,b,c,d,e,f) #else -/** @hideinitializer */ +/** @brief The condition which failed will be displayed. + @hideinitializer */ #define xbt_assert(cond) if (!(cond)) { CRITICAL1("Assertion %s failed", #cond); xbt_abort(); } /** @hideinitializer */ #define xbt_assert0(cond,msg) if (!(cond)) { CRITICAL0(msg); xbt_abort(); } @@ -191,7 +195,7 @@ const char *xbt_error_name(xbt_error_t errcode); /** @}*/ -/** @name Useful predefined errors +/** @name 5. Useful predefined errors * * @{ */ diff --git a/include/xbt/heap.h b/include/xbt/heap.h index 2b44138e67..377dbf21c1 100644 --- a/include/xbt/heap.h +++ b/include/xbt/heap.h @@ -9,6 +9,7 @@ #define _XBT_HEAP_H #include "xbt/misc.h" +#include "xbt/dynar.h" /* void_f_pvoid_t */ /** \brief Heap data type \ingroup XBT_heap diff --git a/include/xbt/misc.h b/include/xbt/misc.h index 1808b4d701..b38b9de568 100644 --- a/include/xbt/misc.h +++ b/include/xbt/misc.h @@ -49,15 +49,6 @@ typedef struct { int port; } xbt_host_t; -/** \name Free functions - * \ingroup XBT_dynar - * Pointer to a function freeing something -*/ -/*@{*/ -typedef void (void_f_ppvoid_t)(void**); /**< Pointer to a function freeing something */ -typedef void (void_f_pvoid_t) (void*); /**< Pointer to a function freeing something */ -/*@}*/ - END_DECL() #endif /* XBT_MISC_H */ diff --git a/include/xbt/set.h b/include/xbt/set.h index 7ee9285ff5..d0f0ab80f9 100644 --- a/include/xbt/set.h +++ b/include/xbt/set.h @@ -14,49 +14,75 @@ BEGIN_DECL() -/*####[ Type definition ]####################################################*/ -/** \name Set and set elements - \ingroup XBT_set - generic dictionary +/** @addtogroup XBT_set + * + * The elements stored in such a data structure can be retrieve both by + * name and by ID. For this to work, the first fields of the structures + * stored must begin with: + * \verbatim unsigned int ID; + char *name; + unsigned int name_len;\endverbatim + * + * It is impossible to remove an element from such a data structure. + * + * @todo + * Such a datastructure was necessary/useful to store the GRAS type + * descriptions, but it should be reworked to become generic. + * + * @{ */ -/*@{*/ -typedef struct xbt_set_ *xbt_set_t; /**< Set */ -typedef struct xbt_set_elm_ { - unsigned int ID; - char *name; - unsigned int name_len; -} s_xbt_set_elm_t,*xbt_set_elm_t; /**< Set element */ -/*####[ Functions ]##########################################################*/ +/** @name 1. Set and set elements, constructor/destructor + * + * @{ + */ +/** \brief Opaque type representing a set */ +typedef struct xbt_set_ *xbt_set_t; +/** \brief It must be possible to cast set elements to this type */ +struct xbt_set_elm_ { + unsigned int ID; /**< Identificator (system assigned) */ + char *name; /**< Name (user assigned) */ + unsigned int name_len;/**< Length of the name */ +}; + +/*####[ Functions ]##########################################################*/ xbt_set_t xbt_set_new (void); void xbt_set_free(xbt_set_t *set); +/** @} */ +typedef struct xbt_set_elm_ s_xbt_set_elm_t; +typedef struct xbt_set_elm_ * xbt_set_elm_t; +/** @name 2. Main functions + * + * @{ + */ void xbt_set_add (xbt_set_t set, xbt_set_elm_t elm, void_f_pvoid_t *free_func); -/*----[ xbt_set_retrieve ]-------------------------------------------------*/ -/* Search the given #key#. data=NULL when not found. */ -/*---------------------------------------------------------------------------*/ xbt_error_t xbt_set_get_by_name (xbt_set_t set, - const char *key, - /* OUT */xbt_set_elm_t *dst); + const char *key, + /* OUT */xbt_set_elm_t *dst); xbt_error_t xbt_set_get_by_name_ext(xbt_set_t set, - const char *name, - int name_len, - /* OUT */xbt_set_elm_t *dst); + const char *name, + int name_len, + /* OUT */xbt_set_elm_t *dst); xbt_error_t xbt_set_get_by_id (xbt_set_t set, - int id, - /* OUT */xbt_set_elm_t *dst); + int id, + /* OUT */xbt_set_elm_t *dst); -/*####[ Cache cursor functions ]#############################################*/ -/* To traverse (simple) caches */ -/* Don't add or remove entries to the cache while traversing !!! */ -/*###########################################################################*/ -typedef struct xbt_set_cursor_ *xbt_set_cursor_t; /**< Set cursor */ -/*@}*/ +/** @} */ +/** @name 3. Cursors + * + * \warning Don't add or remove entries to the cache while traversing + * + * @{ + */ + +/** @brief Cursor type */ +typedef struct xbt_set_cursor_ *xbt_set_cursor_t; void xbt_set_cursor_first (xbt_set_t set, xbt_set_cursor_t *cursor); @@ -64,20 +90,16 @@ void xbt_set_cursor_step (xbt_set_cursor_t cursor); int xbt_set_cursor_get_or_free (xbt_set_cursor_t *cursor, xbt_set_elm_t *elm); -/** - \brief Set iterator - \ingroup XBT_set - * \param set what to iterate over - * \param cursor a #xbt_set_cursor_t used as cursor - * \param elm a #xbt_set_elm_t - * - * Iterates over the whole set. +/** @brief Iterates over the whole set + * @hideinitializer */ #define xbt_set_foreach(set,cursor,elm) \ for ((cursor) = NULL, xbt_set_cursor_first((set),&(cursor)) ; \ xbt_set_cursor_get_or_free(&(cursor),(xbt_set_elm_t*)&(elm)); \ xbt_set_cursor_step(cursor) ) +/*@}*/ +/*@}*/ END_DECL() #endif /* _XBT_SET_H */ -- 2.20.1