Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
explain why I hate doxygen so much tonight, and go have a decent sleep
[simgrid.git] / include / gras / datadesc.h
1 /* $Id$ */
2
3 /* gras/datadesc.h - Describing the data you want to exchange               */
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 #ifndef GRAS_DATADESC_H
11 #define GRAS_DATADESC_H
12
13 #include "xbt/misc.h" /* BEGIN_DECL */
14
15 BEGIN_DECL()
16
17 /** @defgroup GRAS_dd Data description
18  *  @brief Describing data to be exchanged (Communication facility)
19  *
20  * @section Overview
21  *
22  * Since GRAS takes care of potential representation conversion when the platform is heterogeneous, 
23  * any data which transits on the network must be described beforehand.
24  * 
25  * There is several possible interfaces for this, ranging from the really completely automatic parsing to 
26  * completely manual. Let's study each of them from the simplest to the more advanced.
27  * 
28  * \warning At least, I would like to present those sections in the right order, but doxygen prevents me 
29  * from doing so. There is a weird bug I fail to circumvent here. The right order is naturally:
30  *   - a) basic operations
31  *   - b) Automatic parsing
32  *   - c) Simple manual definitions
33  *   - d) Callback Persistant State: Simple push/pop mecanism
34  *   - e) Callback Persistant State: Full featured mecanism
35  */
36   
37 /** @name a) basic operations
38  *  @ingroup GRAS_dd
39  *
40  * If you only want to send pre-existing types, simply retrieve the pre-defined description with 
41  * the \ref gras_datadesc_by_name function. Existing types entail:
42  *  - char (both signed and unsigned)
43  *  - int (short, regular, long and long long, both signed and unsigned)
44  *  - float and double
45  *  - string (which is indeed a reference to a dynamically sized array of char, strlen being used to retrive the size)
46  * 
47  * Example:\verbatim gras_datadesc_type_t i = gras_datadesc_by_name("int");
48  gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char");
49  gras_datadesc_type_t str = gras_datadesc_by_name("string");\endverbatim
50  */
51 /* @{ */
52   
53 /** @brief Opaque type describing a type description. */
54 typedef struct s_gras_datadesc_type *gras_datadesc_type_t;
55
56 /** \brief Search a type description from its name */
57 gras_datadesc_type_t gras_datadesc_by_name(const char *name);
58
59 /* @} */
60     
61 /** @name b) Automatic parsing
62  *  @ingroup GRAS_dd
63  * 
64  *  If you need to declare a new datatype, this is the simplest way to describe it to GRAS. Simply
65  *  enclose its type definition  into a \ref GRAS_DEFINE_TYPE macro call, and you're set. Here is 
66  *  an type declaration  example: \verbatim GRAS_DEFINE_TYPE(mytype,struct mytype {
67    int myfirstfield;
68    char mysecondfield;
69  });\endverbatim
70  *  The type is then both copied verbatim into your source file and stored for further parsing. This allows
71  *  you to let GRAS parse the exact version you are actually using in your program.
72  *  You can then retrieve the corresponding type description with \ref gras_datadesc_by_symbol.
73  *  Don't worry too much for the performances, the type is only parsed once and a binary representation 
74  *  is stored and used in any subsequent calls.
75  * 
76  *  If your structure contains any pointer, you have to explain GRAS the size of the pointed array. This
77  *  can be 1 in the case of simple references, or more in the case of regular arrays. For that, use the 
78  *  \ref GRAS_ANNOTE macro within the type declaration you are passing to \ref GRAS_DEFINE_TYPE. This macro
79  *  rewrites itself to nothing in the declaration (so they won't pollute the type definition copied verbatim
80  *  into your code), and give some information to GRAS about your pointer. 
81  
82  *  GRAS_ANNOTE takes two arguments being the key name and the key value. For now, the only accepted key name 
83  *  is "size", to specify the length of the pointed array. It can either be the string "1" (without the quote)
84  *  or the name of another field of the structure.
85  *  
86  *  Here is an example:\verbatim GRAS_DEFINE_TYPE(s_clause,
87   struct s_array {
88     int length;
89     int *data GRAS_ANNOTE(size,length);
90     struct s_array *father GRAS_ANNOTE(size,1);
91  }
92 ;)\endverbatim
93  * It specifies that the structure s_array contains two fields, and that the size of the array pointed 
94  * by \a data is the \a length field, and that the \a father field is a simple reference.
95  * 
96  * If you cannot express your datadescs with this mecanism, you'll have to use the more advanced 
97  * (and somehow complex) one described below.
98  * 
99  *  \warning Since GRAS_DEFINE_TYPE is a macro, you shouldn't  put any comma in your type definition 
100  *  (comma separates macro args). 
101  * 
102  *  For example, change \verbatim int a, b;\endverbatim to \verbatim int a;
103  int b:\endverbatim
104  */
105 /** @{ */
106
107  
108 /**   @brief Automatically parse C code
109  *    @hideinitializer
110  */
111 #define GRAS_DEFINE_TYPE(name,def) \
112   static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def
113  
114 /** @brief Retrieve a datadesc which was previously parsed 
115  *  @hideinitializer
116  */
117 #define gras_datadesc_by_symbol(name)  \
118   (gras_datadesc_by_name(#name) ?      \
119    gras_datadesc_by_name(#name) :      \
120      gras_datadesc_parse(#name,        \
121                          _gras_this_type_symbol_does_not_exist__##name) \
122   )
123
124 /** @def GRAS_ANNOTE
125  *  @brief Add an annotation to a type to be automatically parsed
126  */
127 #define GRAS_ANNOTE(key,val)
128
129 /*@}*/
130
131 gras_datadesc_type_t 
132 gras_datadesc_parse(const char *name, const char *C_statement);
133
134 /** @name c) Simple manual definitions
135  *  @ingroup GRAS_dd
136  * 
137  * Here are the functions to use if you want to declare your description manually. 
138  * The function names should be self-explanatory in most cases.
139  * 
140  * You can add callbacks to the datatypes doing any kind of action you may want. Usually, 
141  * pre-send callbacks are used to prepare the type expedition while post-receive callbacks 
142  * are used to fix any issue after the receive.
143  * 
144  * If your types are dynamic, you'll need to add some extra callback. For example, there is a
145  * specific callback for the string type which is in charge of computing the length of the char
146  * array. This is done with the cbps mecanism, explained in next section.
147  * 
148  * If your types may contain pointer cycle, you must specify it to GRAS using the @ref gras_datadesc_cycle_set. 
149  * 
150  * Example:\verbatim
151  typedef struct {
152    unsigned char c1;
153    unsigned long int l1;
154    unsigned char c2;
155    unsigned long int l2;
156  } mystruct;
157  [...]
158   my_type=gras_datadesc_struct("mystruct");
159   gras_datadesc_struct_append(my_type,"c1", gras_datadesc_by_name("unsigned char"));
160   gras_datadesc_struct_append(my_type,"l1", gras_datadesc_by_name("unsigned long"));
161   gras_datadesc_struct_append(my_type,"c2", gras_datadesc_by_name("unsigned char"));
162   gras_datadesc_struct_append(my_type,"l2", gras_datadesc_by_name("unsigned long int"));
163   gras_datadesc_struct_close(my_type);
164
165   my_type=gras_datadesc_ref("mystruct*", gras_datadesc_by_name("mystruct"));
166   
167   [Use my_type to send pointers to mystruct data]\endverbatim
168  */
169 /*@{*/
170
171
172 /** \brief Opaque type describing a type description callback persistant state. */
173 typedef struct s_gras_cbps *gras_cbps_t;
174
175 /* callbacks prototypes */
176 /** \brief Prototype of type callbacks returning nothing. */
177 typedef void (*gras_datadesc_type_cb_void_t)(gras_cbps_t vars, void *data);
178 /** \brief Prototype of type callbacks returning an int. */
179 typedef int (*gras_datadesc_type_cb_int_t)(gras_cbps_t vars, void *data);
180 /** \brief Prototype of type callbacks selecting a type. */
181 typedef gras_datadesc_type_t (*gras_datadesc_selector_t)(gras_cbps_t vars, void *data);
182
183
184 /******************************************
185  **** Declare datadescription yourself ****
186  ******************************************/
187
188 /** \brief Declare a new structure description */
189 gras_datadesc_type_t gras_datadesc_struct(const char *name);
190
191 /** \brief Append a new field to a structure description */
192 void
193   gras_datadesc_struct_append(gras_datadesc_type_t  struct_type,
194                               const char           *name,
195                               gras_datadesc_type_t  field_type);
196 /** \brief Close a structure description */
197 void
198   gras_datadesc_struct_close(gras_datadesc_type_t   struct_type);
199
200 /** \brief Declare a new union description */
201 gras_datadesc_type_t 
202   gras_datadesc_union(const char                   *name,
203                       gras_datadesc_type_cb_int_t   selector);
204 /** \brief Append a new field to an union description */
205 void
206   gras_datadesc_union_append(gras_datadesc_type_t   union_type,
207                              const char            *name,
208                              gras_datadesc_type_t   field_type);
209 /** \brief Close an union description */
210 void
211   gras_datadesc_union_close(gras_datadesc_type_t    union_type);
212
213
214 /** \brief Declare a new type being a reference to the one passed in arg */
215 gras_datadesc_type_t 
216   gras_datadesc_ref(const char                     *name,
217                     gras_datadesc_type_t            referenced_type);
218 /** \brief Declare a new type being a generic reference. */
219 gras_datadesc_type_t 
220   gras_datadesc_ref_generic(const char                *name,
221                             gras_datadesc_selector_t   selector);
222
223 /** \brief Declare a new type being an array of fixed size and content */
224 gras_datadesc_type_t 
225   gras_datadesc_array_fixed(const char             *name,
226                             gras_datadesc_type_t    element_type,
227                             long int                fixed_size);
228
229 /** \brief Declare a new type being an array of fixed size, but accepting several content types. */
230 gras_datadesc_type_t 
231   gras_datadesc_array_dyn(const char                 *name,
232                           gras_datadesc_type_t        element_type,
233                           gras_datadesc_type_cb_int_t dynamic_size);
234
235 /** \brief Declare a new type being an array which size can be found with \ref gras_cbps_i_pop */
236 gras_datadesc_type_t 
237   gras_datadesc_ref_pop_arr(gras_datadesc_type_t  element_type);
238
239 /*********************************
240  * Change stuff within datadescs *
241  *********************************/
242
243 /** \brief Specify that this type may contain cycles */
244 void gras_datadesc_cycle_set(gras_datadesc_type_t type);
245 /** \brief Specify that this type do not contain any cycles (default) */
246 void gras_datadesc_cycle_unset(gras_datadesc_type_t type);
247 /** \brief Add a pre-send callback to this datadesc. */
248 void gras_datadesc_cb_send (gras_datadesc_type_t         type,
249                             gras_datadesc_type_cb_void_t pre);
250 /** \brief Add a post-receive callback to this datadesc.*/
251 void gras_datadesc_cb_recv(gras_datadesc_type_t          type,
252                            gras_datadesc_type_cb_void_t  post);
253 /** \brief Add a pre-send callback to the given field of the datadesc */
254 void gras_datadesc_cb_field_send (gras_datadesc_type_t   type,
255                                   const char            *field_name,
256                                   gras_datadesc_type_cb_void_t  pre);
257 /** \brief Add a post-receive callback to the given field of the datadesc */
258 void gras_datadesc_cb_field_recv(gras_datadesc_type_t    type,
259                                  const char             *field_name,
260                                  gras_datadesc_type_cb_void_t  post);
261 /** \brief Add a pre-send callback to the given field resulting in its value to be pushed */
262 void gras_datadesc_cb_field_push (gras_datadesc_type_t   type,
263                                   const char            *field_name);
264
265 /******************************
266  * Get stuff within datadescs *
267  ******************************/
268 /** \brief Returns the name of a datadescription */
269 char * gras_datadesc_get_name(gras_datadesc_type_t ddt);
270 /** \brief Returns the identifier of a datadescription */
271 int gras_datadesc_get_id(gras_datadesc_type_t ddt);
272
273 /*@}*/
274
275 /** @name d) Callback Persistant State: Simple push/pop mecanism
276  *  @ingroup GRAS_dd
277  * 
278  * Sometimes, one of the callbacks need to leave information for the next ones. If this is a simple integer (such as
279  * an array size), you can use the functions described here. If not, you'll have to play with the complete cbps interface.
280  * 
281  * Here is an example:\verbatim
282 struct s_array {
283   int length;
284   int *data;
285 }
286 [...]
287 my_type=gras_datadesc_struct("s_array");
288 gras_datadesc_struct_append(my_type,"length", gras_datadesc_by_name("int"));
289 gras_datadesc_cb_field_send (my_type, "length", gras_datadesc_cb_push_int);
290
291 gras_datadesc_struct_append(my_type,"data",
292                             gras_datadesc_array_dyn ("s_array::data",gras_datadesc_by_name("int"), gras_datadesc_cb_pop));
293 gras_datadesc_struct_close(my_type);
294 \endverbatim
295
296  */
297 /*@{*/
298
299 void
300 gras_cbps_i_push(gras_cbps_t ps, int val);
301 int 
302 gras_cbps_i_pop(gras_cbps_t ps);
303
304 int gras_datadesc_cb_pop(gras_cbps_t vars, void *data);
305 void gras_datadesc_cb_push_int(gras_cbps_t vars, void *data);
306 void gras_datadesc_cb_push_uint(gras_cbps_t vars, void *data);
307 void gras_datadesc_cb_push_lint(gras_cbps_t vars, void *data);
308 void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data);
309
310
311 /*@}*/
312
313 /** @name e) Callback Persistant State: Full featured mecanism
314  *  @ingroup GRAS_dd
315  * 
316  * Sometimes, one of the callbacks need to leave information for the next ones. If the simple push/pop mecanism
317  * introduced in previous section isn't enough, you can always use this full featured one.
318  */
319
320 /*@{*/
321
322 xbt_error_t
323   gras_cbps_v_pop (gras_cbps_t            ps, 
324                    const char            *name,
325          /* OUT */ gras_datadesc_type_t  *ddt,
326          /* OUT */ void                 **res);
327 xbt_error_t
328 gras_cbps_v_push(gras_cbps_t            ps,
329                  const char            *name,
330                  void                  *data,
331                  gras_datadesc_type_t   ddt);
332 void
333 gras_cbps_v_set (gras_cbps_t            ps,
334                  const char            *name,
335                  void                  *data,
336                  gras_datadesc_type_t   ddt);
337
338 void *
339 gras_cbps_v_get (gras_cbps_t            ps, 
340                  const char            *name,
341        /* OUT */ gras_datadesc_type_t  *ddt);
342
343 void
344 gras_cbps_block_begin(gras_cbps_t ps);
345 void
346 gras_cbps_block_end(gras_cbps_t ps);
347
348 /* @} */
349
350
351 /*******************************
352  **** About data convertion ****
353  *******************************/
354 int gras_arch_selfid(void); /* ID of this arch */
355
356
357 /*****************************
358  **** NWS datadescription * FIXME: obsolete?
359  *****************************/
360
361 /**
362  * Basic types we can embeed in DataDescriptors.
363  */
364 typedef enum
365   {CHAR_TYPE, DOUBLE_TYPE, FLOAT_TYPE, INT_TYPE, LONG_TYPE, SHORT_TYPE,
366    UNSIGNED_INT_TYPE, UNSIGNED_LONG_TYPE, UNSIGNED_SHORT_TYPE, STRUCT_TYPE}
367   DataTypes;
368 #define SIMPLE_TYPE_COUNT 9
369
370 /*!  \brief Describe a collection of data.
371  * 
372 ** A description of a collection of #type# data.  #repetitions# is used only
373 ** for arrays; it contains the number of elements.  #offset# is used only for
374 ** struct members in host format; it contains the offset of the member from the
375 ** beginning of the struct, taking into account internal padding added by the
376 ** compiler for alignment purposes.  #members#, #length#, and #tailPadding# are
377 ** used only for STRUCT_TYPE data; the #length#-long array #members# describes
378 ** the members of the nested struct, and #tailPadding# indicates how many
379 ** padding bytes the compiler adds to the end of the structure.
380 */
381
382 typedef struct DataDescriptorStruct {
383   DataTypes type;
384   size_t repetitions;
385   size_t offset;
386   /*@null@*/ struct DataDescriptorStruct *members;
387   size_t length;
388   size_t tailPadding;
389 } DataDescriptor;
390 /** DataDescriptor for an array */
391 #define SIMPLE_DATA(type,repetitions) \
392   {type, repetitions, 0, NULL, 0, 0}
393 /** DataDescriptor for an structure member */
394 #define SIMPLE_MEMBER(type,repetitions,offset) \
395   {type, repetitions, offset, NULL, 0, 0}
396 /** DataDescriptor for padding bytes */
397 #define PAD_BYTES(structType,lastMember,memberType,repetitions) \
398   sizeof(structType) - offsetof(structType, lastMember) - \
399   sizeof(memberType) * repetitions
400
401 xbt_error_t
402 gras_datadesc_import_nws(const char           *name,
403                          const DataDescriptor *desc,
404                          unsigned long         howmany,
405                /* OUT */ gras_datadesc_type_t *dst);
406
407
408 END_DECL()
409
410 #endif /* GRAS_DATADESC_H */