include/gras/datadesc.h

   1 /* $Id$ */
   2
   3 /* gras/datadesc.h - Describing the data you want to exchange               */
   4
   5 /* Authors: Martin Quinson                                                  */
   6 /* Copyright (C) 2003, 2004 Martin Quinson.                                 */
   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 GRAS_DATADESC_H
  12 #define GRAS_DATADESC_H
  13
  14 #include <stddef.h>    /* offsetof() */
  15 #include <sys/types.h>  /* size_t */
  16 #include <stdarg.h>
  17
  18 #include "xbt/misc.h" /* BEGIN_DECL */
  19
  20 BEGIN_DECL
  21
  22 /**
  23  * gras_datadesc_type_t:
  24  *
  25  * Opaque type describing a type description you don't want to open.
  26  */
  27 typedef struct s_gras_datadesc_type gras_datadesc_type_t;
  28
  29 typedef struct s_gras_cbps gras_cbps_t;
  30
  31 /* callbacks prototypes */
  32 typedef void (*gras_datadesc_type_cb_void_t)(gras_cbps_t *vars, void *data);
  33 typedef int (*gras_datadesc_type_cb_int_t)(gras_cbps_t *vars, void *data);
  34 typedef gras_datadesc_type_t *(*gras_datadesc_selector_t)(gras_cbps_t *vars, void *data);
  35
  36 /***********************************************
  37  **** Search and retrieve declared datatype ****
  38  ***********************************************/
  39 gras_datadesc_type_t *gras_datadesc_by_name(const char *name);
  40
  41 /******************************************
  42  **** Declare datadescription yourself ****
  43  ******************************************/
  44
  45 gras_datadesc_type_t *
  46   gras_datadesc_struct(const char *name);
  47
  48 void
  49   gras_datadesc_struct_append(gras_datadesc_type_t    *struct_type,
  50                               const char              *name,
  51                               gras_datadesc_type_t    *field_type);
  52 void
  53   gras_datadesc_struct_close(gras_datadesc_type_t     *struct_type);
  54
  55 gras_datadesc_type_t *
  56   gras_datadesc_union(const char                      *name,
  57                       gras_datadesc_type_cb_int_t      selector);
  58 void
  59   gras_datadesc_union_append(gras_datadesc_type_t     *union_type,
  60                              const char               *name,
  61                              gras_datadesc_type_t     *field_type);
  62 void
  63   gras_datadesc_union_close(gras_datadesc_type_t      *union_type);
  64
  65 gras_datadesc_type_t *
  66   gras_datadesc_ref(const char                      *name,
  67                     gras_datadesc_type_t            *referenced_type);
  68 gras_datadesc_type_t *
  69   gras_datadesc_ref_generic(const char                *name,
  70                             gras_datadesc_selector_t   selector);
  71
  72 gras_datadesc_type_t *
  73   gras_datadesc_array_fixed(const char                    *name,
  74                             gras_datadesc_type_t          *element_type,
  75                             long int                       fixed_size);
  76 gras_datadesc_type_t *
  77   gras_datadesc_array_dyn(const char                      *name,
  78                           gras_datadesc_type_t            *element_type,
  79                           gras_datadesc_type_cb_int_t      dynamic_size);
  80
  81 gras_datadesc_type_t *
  82   gras_datadesc_ref_pop_arr(gras_datadesc_type_t  *element_type);
  83
  84 /*********************************
  85  * Change stuff within datadescs *
  86  *********************************/
  87
  88 void gras_datadesc_cycle_set(gras_datadesc_type_t *type);
  89 void gras_datadesc_cycle_unset(gras_datadesc_type_t *type);
  90
  91 void gras_datadesc_cb_send (gras_datadesc_type_t    *type,
  92                             gras_datadesc_type_cb_void_t  pre);
  93 void gras_datadesc_cb_recv(gras_datadesc_type_t    *type,
  94                            gras_datadesc_type_cb_void_t  post);
  95 void gras_datadesc_cb_field_send (gras_datadesc_type_t    *type,
  96                                   const char *field_name,
  97                                   gras_datadesc_type_cb_void_t  pre);
  98 void gras_datadesc_cb_field_recv(gras_datadesc_type_t    *type,
  99                                  const char *field_name,
 100                                  gras_datadesc_type_cb_void_t  post);
 101 void gras_datadesc_cb_field_push (gras_datadesc_type_t         *type,
 102                                   const char                   *field_name);
 103
 104 /******************************
 105  * Get stuff within datadescs *
 106  ******************************/
 107 char * gras_datadesc_get_name(gras_datadesc_type_t *ddt);
 108 int gras_datadesc_get_id(gras_datadesc_type_t *ddt);
 109
 110 /********************************************************
 111  * Advanced data describing: callback persistent states *
 112  ********************************************************/
 113 /* simple one: push/pop sizes of arrays */
 114 void
 115 gras_cbps_i_push(gras_cbps_t *ps, int val);
 116 int
 117 gras_cbps_i_pop(gras_cbps_t *ps);
 118
 119 int gras_datadesc_cb_pop(gras_cbps_t *vars, void *data);
 120 void gras_datadesc_cb_push_int(gras_cbps_t *vars, void *data);
 121 void gras_datadesc_cb_push_uint(gras_cbps_t *vars, void *data);
 122 void gras_datadesc_cb_push_lint(gras_cbps_t *vars, void *data);
 123 void gras_datadesc_cb_push_ulint(gras_cbps_t *vars, void *data);
 124
 125
 126
 127 /* complex one: complete variable environment support */
 128 gras_error_t
 129 gras_cbps_v_pop (gras_cbps_t        *ps,
 130                     const char            *name,
 131                     gras_datadesc_type_t **ddt,
 132                   void                 **res);
 133 gras_error_t
 134 gras_cbps_v_push(gras_cbps_t        *ps,
 135                     const char            *name,
 136                     void                  *data,
 137                     gras_datadesc_type_t  *ddt);
 138 void
 139 gras_cbps_v_set (gras_cbps_t        *ps,
 140                     const char            *name,
 141                     void                  *data,
 142                     gras_datadesc_type_t  *ddt);
 143
 144 void *
 145 gras_cbps_v_get (gras_cbps_t        *ps,
 146                     const char            *name,
 147                     gras_datadesc_type_t **ddt);
 148
 149 void
 150 gras_cbps_block_begin(gras_cbps_t *ps);
 151 void
 152 gras_cbps_block_end(gras_cbps_t *ps);
 153
 154
 155
 156
 157 /*******************************
 158  **** About data convertion ****
 159  *******************************/
 160 int gras_arch_selfid(void); /* ID of this arch */
 161
 162 /****************************
 163  **** Parse C statements ****
 164  ****************************/
 165 gras_datadesc_type_t *
 166 gras_datadesc_parse(const char *name,
 167                     const char *Cdefinition);
 168 #define GRAS_DEFINE_TYPE(name,def) \
 169   static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def
 170 #define GRAS_ANNOTE(key,val)
 171
 172 #define gras_datadesc_by_symbol(name)  \
 173   (gras_datadesc_by_name(#name) ?      \
 174    gras_datadesc_by_name(#name) :      \
 175      gras_datadesc_parse(#name,        \
 176                          _gras_this_type_symbol_does_not_exist__##name) \
 177   )
 178
 179 /*****************************
 180  **** NWS datadescription ****
 181  *****************************/
 182
 183 /**
 184  * Basic types we can embeed in DataDescriptors.
 185  */
 186 typedef enum
 187   {CHAR_TYPE, DOUBLE_TYPE, FLOAT_TYPE, INT_TYPE, LONG_TYPE, SHORT_TYPE,
 188    UNSIGNED_INT_TYPE, UNSIGNED_LONG_TYPE, UNSIGNED_SHORT_TYPE, STRUCT_TYPE}
 189   DataTypes;
 190 #define SIMPLE_TYPE_COUNT 9
 191
 192 /*!  \brief Describe a collection of data.
 193  *
 194 ** A description of a collection of #type# data.  #repetitions# is used only
 195 ** for arrays; it contains the number of elements.  #offset# is used only for
 196 ** struct members in host format; it contains the offset of the member from the
 197 ** beginning of the struct, taking into account internal padding added by the
 198 ** compiler for alignment purposes.  #members#, #length#, and #tailPadding# are
 199 ** used only for STRUCT_TYPE data; the #length#-long array #members# describes
 200 ** the members of the nested struct, and #tailPadding# indicates how many
 201 ** padding bytes the compiler adds to the end of the structure.
 202 */
 203
 204 typedef struct DataDescriptorStruct {
 205   DataTypes type;
 206   size_t repetitions;
 207   size_t offset;
 208   /*@null@*/ struct DataDescriptorStruct *members;
 209   size_t length;
 210   size_t tailPadding;
 211 } DataDescriptor;
 212 /** DataDescriptor for an array */
 213 #define SIMPLE_DATA(type,repetitions) \
 214   {type, repetitions, 0, NULL, 0, 0}
 215 /** DataDescriptor for an structure member */
 216 #define SIMPLE_MEMBER(type,repetitions,offset) \
 217   {type, repetitions, offset, NULL, 0, 0}
 218 /** DataDescriptor for padding bytes */
 219 #define PAD_BYTES(structType,lastMember,memberType,repetitions) \
 220   sizeof(structType) - offsetof(structType, lastMember) - \
 221   sizeof(memberType) * repetitions
 222
 223 gras_error_t
 224 gras_datadesc_import_nws(const char           *name,
 225                          const DataDescriptor *desc,
 226                          size_t                howmany,
 227                          gras_datadesc_type_t **dst);
 228
 229 END_DECL
 230
 231 #endif /* GRAS_DATADESC_H */