X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/c42000db0f347a26ac1645d830ac949194ec4da0..ee55888d056642c8bff3c8aad86e6a84d05ab063:/include/xbt/set.h diff --git a/include/xbt/set.h b/include/xbt/set.h index 5ab5d1c124..7d4d86eaae 100644 --- a/include/xbt/set.h +++ b/include/xbt/set.h @@ -1,72 +1,122 @@ /* $Id$ */ -/* gras/set.h -- api to a generic dictionary */ +/* xbt/set.h -- api to a generic dictionary */ -/* Authors: Martin Quinson */ -/* Copyright (C) 2004 the OURAGAN project. */ +/* Copyright (c) 2004 Martin Quinson. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it - under the terms of the license (GNU LGPL) which comes with this package. */ + * under the terms of the license (GNU LGPL) which comes with this package. */ +#ifndef _XBT_SET_H +#define _XBT_SET_H -#ifndef _GRAS_SET_H -#define _GRAS_SET_H +#include "xbt/misc.h" /* SG_BEGIN_DECL */ +#include "xbt/function_types.h" -#ifdef __cplusplus -extern "C" -#endif +SG_BEGIN_DECL() -/*####[ Type definition ]####################################################*/ -typedef struct gras_set_ gras_set_t; -typedef struct gras_set_elm_ { - unsigned int ID; - char *name; - unsigned int name_len; -} gras_set_elm_t; +/** @addtogroup XBT_set + * @brief A data container consisting in \ref XBT_dict and \ref XBT_dynar + * + * 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 the following fields: + * \verbatim struct { + unsigned int ID; + char *name; + unsigned int name_len; + // my other fields, constituting the payload +} my_element_type_t; \endverbatim + * + * Since we are casting elements around, no protection is ensured by the + * compiler. It is thus safer to define the headers using the macro + * defined to that extend: + * \verbatim struct { + XBT_SET_HEADERS; + + // my other fields, constituting the payload +} my_element_type_t; \endverbatim + * + * It is now possible 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. + * + */ + + +/** @defgroup XBT_set_cons Set and set elements, constructor/destructor + * @ingroup XBT_set + * + * @{ + */ +/** \brief Opaque type representing a set */ +typedef struct xbt_set_ *xbt_set_t; + +#define XBT_SET_HEADERS \ + unsigned int ID; \ + char *name; \ + unsigned int name_len + +/** \brief It must be possible to cast set elements to this type */ +typedef struct xbt_set_elm_ { + unsigned int ID; /**< Identificator (system assigned) */ + char *name; /**< Name (user assigned) */ + unsigned int name_len;/**< Length of the name */ +} s_xbt_set_elm_t,*xbt_set_elm_t; /*####[ Functions ]##########################################################*/ +xbt_set_t xbt_set_new (void); +void xbt_set_free(xbt_set_t *set); + +/** @} */ +/** @defgroup XBT_set_basic Sets basic usage + * @ingroup XBT_set + * + * @{ + */ + +void xbt_set_add (xbt_set_t set, xbt_set_elm_t elm, void_f_pvoid_t *free_func); +void xbt_set_remove (xbt_set_t set, xbt_set_elm_t elm); +void xbt_set_remove_by_name (xbt_set_t set, const char *key); +void xbt_set_remove_by_name_ext (xbt_set_t set, const char *key, int key_len); +void xbt_set_remove_by_id (xbt_set_t set, int id); + +xbt_set_elm_t xbt_set_get_by_name (xbt_set_t set, const char *key); +xbt_set_elm_t xbt_set_get_by_name_ext(xbt_set_t set, const char *key, int key_len); +xbt_set_elm_t xbt_set_get_by_id (xbt_set_t set, int id); + +unsigned long xbt_set_length (const xbt_set_t set); + + +/** @} */ +/** @defgroup XBT_set_curs Sets cursors + * @ingroup XBT_set + * + * \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); +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 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) ) + +/* @} */ +SG_END_DECL() -gras_set_t *gras_set_new (void); -void gras_set_free(gras_set_t **set); - - -void gras_set_add (gras_set_t *set, - gras_set_elm_t *elm, - void_f_pvoid_t *free_func); - -/*----[ gras_set_retrieve ]-------------------------------------------------*/ -/* Search the given #key#. data=NULL when not found. */ -/*---------------------------------------------------------------------------*/ -gras_error_t gras_set_get_by_name (gras_set_t *set, - const char *key, - /* OUT */gras_set_elm_t **dst); -gras_error_t gras_set_get_by_name_ext(gras_set_t *set, - const char *name, - int name_len, - /* OUT */gras_set_elm_t **dst); -gras_error_t gras_set_get_by_id (gras_set_t *set, - int id, - /* OUT */gras_set_elm_t **dst); - -/*####[ Cache cursor functions ]#############################################*/ -/* To traverse (simple) caches */ -/* Don't add or remove entries to the cache while traversing !!! */ -/*###########################################################################*/ -typedef struct gras_set_cursor_ gras_set_cursor_t; -/* creator/destructor */ -void gras_set_cursor_first (gras_set_t *set, - gras_set_cursor_t **cursor); -void gras_set_cursor_step (gras_set_cursor_t *cursor); -int gras_set_cursor_get_or_free (gras_set_cursor_t **cursor, - gras_set_elm_t **elm); - -#define gras_set_foreach(set,cursor,elm) \ - for ((cursor) = NULL, gras_set_cursor_first((set),&(cursor)) ; \ - gras_set_cursor_get_or_free(&(cursor),(gras_set_elm_t**)&(elm)); \ - gras_set_cursor_step(cursor) ) - -#ifdef __cplusplus -} -#endif - -#endif /* _GRAS_SET_H */ +#endif /* _XBT_SET_H */