Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Adding everything needed to develop GRAS benchmarking macros.
[simgrid.git] / include / xbt / dict.h
1 /* $Id$ */
2
3 /* xbt/dict.h -- api to a generic dictionary                                */
4
5 /* Copyright (c) 2003, 2004 Martin Quinson. All rights reserved.            */
6
7 /* This program is free software; you can redistribute it and/or modify it
8  * under the terms of the license (GNU LGPL) which comes with this package. */
9
10
11 #ifndef _XBT_DICT_H
12 #define _XBT_DICT_H
13
14 #include "xbt/misc.h" /* BEGIN_DECL */
15 #include "xbt/error.h"
16 #include "xbt/dynar.h" /* void_f_pvoid_t */
17
18 BEGIN_DECL()
19
20 /** @addtogroup XBT_dict
21  * 
22  *  This section describes the API to a dictionnary structure that
23  *  associates as string to a void* key. Even if it provides the same
24  *  functionnality than an hash table, the implementation differs and the
25  *  internal data-structure rather looks like a tree.
26  * 
27  *  Here is a little example of use:
28  *  \verbatim xbt_dict_t mydict = xbt_dict_new();
29  char buff[512];
30
31  sprintf(buff,"some very precious data");
32  xbt_dict_set(mydict,"my data", strdup(buff), free); 
33
34  sprintf(buff,"another good stuff");
35  xbt_dict_set(mydict,"my data", strdup(buff), free); // previous data gets erased (and freed) by second add \endverbatim
36
37  *
38  * \warning This section also gets bitten by the doxygen bug reordering the name sections. 
39  * Make sure to read in this order:
40  *  -# Constructor/destructor
41  *  -# Dictionnaries basic usage
42  *  -# Non-null terminated keys
43  *  -# Traversing dictionnaries with cursors
44  *
45  * @{
46 */
47
48 /**  @name 1. Constructor/destructor
49  *   @{
50  */
51
52   /** \brief Dictionnary data type (opaque structure) */
53   typedef struct xbt_dict_ *xbt_dict_t;
54   xbt_dict_t xbt_dict_new(void);
55   void xbt_dict_free(xbt_dict_t *dict);
56
57 /** @} */
58 /** @name 2. Dictionnaries basic usage
59  *
60  * Careful, those functions assume that the key is null-terminated.
61  *
62  *  @{ */
63
64   void xbt_dict_set(xbt_dict_t head, const char *key, void *data, void_f_pvoid_t *free_ctn);
65   xbt_error_t xbt_dict_get(xbt_dict_t head,const char *key, /* OUT */void **data);
66   xbt_error_t xbt_dict_remove(xbt_dict_t head,const char *key);
67   void xbt_dict_dump(xbt_dict_t head,void (*output)(void*));
68   
69 /** @} */
70 /** @name 3. Non-null terminated keys
71  *
72  * Those functions work even with non-null terminated keys.
73  *
74  *  @{
75  */
76   void xbt_dict_set_ext(xbt_dict_t     head,
77                         const char     *key, int  key_len,
78                         void           *data,
79                         void_f_pvoid_t *free_ctn);
80   xbt_error_t xbt_dict_get_ext(xbt_dict_t head,const char *key, int key_len,
81                                /* OUT */void **data);
82   xbt_error_t xbt_dict_remove_ext(xbt_dict_t head,
83                                   const char *key, int key_len);
84
85
86 /** @} */
87 /** @name 4. Cursors on dictionnaries 
88  *
89  *  Don't get impressed, there is a lot of functions here, but traversing a 
90  *  dictionnary is imediate with the xbt_dict_foreach macro.
91  *  You only need the other functions in rare cases (they are not used directly in SG itself).
92  *
93  *  Here is an example (assuming that the dictionnary contains strings, ie
94  *  that the <tt>data</tt> argument of xbt_dict_set was always a null-terminated char*):
95 \verbatim xbt_dict_cursor_t cursor=NULL;
96  char *key,*data;
97
98  xbt_dict_foreach(head,cursor,key,data) {
99     printf("   - Seen:  %s->%s\n",key,data);
100  }\endverbatim
101
102  *
103  *  \warning Do not add or remove entries to the cache while traversing !!
104  *
105  *  @{ */
106
107   /** \brief Cursor on dictionnaries (opaque type) */
108   typedef struct xbt_dict_cursor_ *xbt_dict_cursor_t;
109   xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head);
110   void               xbt_dict_cursor_free(xbt_dict_cursor_t *cursor);
111
112   void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor);
113
114
115   xbt_error_t xbt_dict_cursor_get_key     (xbt_dict_cursor_t cursor,
116                                            /*OUT*/char **key);
117   xbt_error_t xbt_dict_cursor_get_data    (xbt_dict_cursor_t cursor,
118                                            /*OUT*/void **data);
119
120   void xbt_dict_cursor_first (const xbt_dict_t   dict,
121                              xbt_dict_cursor_t *cursor);
122   void         xbt_dict_cursor_step        (xbt_dict_cursor_t  cursor);
123   int          xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor,
124                                             char              **key,
125                                             void              **data);
126   /** \brief toto 
127       \hideinitializer */
128 #  define xbt_dict_foreach(dict,cursor,key,data)                       \
129     for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ;        \
130          xbt_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\
131          xbt_dict_cursor_step(cursor) )
132
133 /** @} */
134 /** @} */
135
136 #if 0
137
138                          MULTI-DICTS ARE BROKEN
139
140
141 /*####[ Multi cache functions ]##############################################*/
142 /* The are cache of cache of data. Any function there works the same way     */
143 /*  than their simple cache counterpart.                                     */
144 /*###############################"###########################################*/
145 /* To dump multicache, this function dumps a cache                           */
146 void xbt_dict_print(void *data);
147 /* To dump multicache, this one dumps a string                               */
148 void xbt_dict_prints(void *data);
149
150 /*----[ xbt_multidict_free ]------------------------------------------------*/
151 /* This function does not exist. Use xbt_dict_free instead.                 */
152 /*---------------------------------------------------------------------------*/
153
154 /*----[ xbt_multidict_set ]-------------------------------------------------*/
155 /* Insert the data in the structure under the #keycount# #key#s.             */
156 /* The key are destroyed in the process. Think to strdup it before.          */
157 /* Returns if it was ok or not                                               */
158 /*---------------------------------------------------------------------------*/
159 xbt_error_t xbt_multidict_set(xbt_dict_t *head,
160                                 int keycount,char **key,
161                                 void *data,void (*free_ctn)(void*));
162
163 xbt_error_t xbt_multidict_set_ext(xbt_dict_t *head,
164                                     int keycount,char **key,int *key_len,
165                                     void *data,void_f_pvoid_t *free_ctn);
166
167 /*----[ xbt_multidict_get ]-------------------------------------------------*/
168 /* Search the given #key#. data=NULL when not found.                         */
169 /* Returns true if anything went ok, and false on internal error.            */
170 /*---------------------------------------------------------------------------*/
171 xbt_error_t xbt_multidict_get(xbt_dict_t head,
172                                 int keycount,const char **key,
173                                 /* OUT */void **data);
174
175 xbt_error_t xbt_multidict_get_ext(xbt_dict_t head,
176                                     int keycount,const char **key,int *key_len,
177                                     /* OUT */void **data);
178
179 /*----[ xbt_multidict_remove ]----------------------------------------------*/
180 /* Remove the entry associated with the given #key#.                         */
181 /* Returns if ok. Removing a non-existant key is ok.                         */
182 /*---------------------------------------------------------------------------*/
183 xbt_error_t xbt_multidict_remove(xbt_dict_t head,
184                                    int keycount,const char **key);
185
186 xbt_error_t xbt_multidict_remove_ext(xbt_dict_t head,
187                                        int keycount,const char **key,int *key_len);
188 #endif
189
190 END_DECL()
191
192 #endif /* _XBT_DICT_H */