doc/gtut-tour-13-pointers.doc

   1 /**
   2 @page GRAS_tut_tour_pointers Lesson 13: Defining structure containing pointers (TODO)
   3
   4 This lesson is a bit different from the other ones. It aims at explaining
   5 several features of the automatic datadesc parsing. Since it would be a bit
   6 long otherwise, the lesson is organized as a FAQ, with little examples of
   7 how to do things.
   8
   9 \section GRAS_tut_tour_pointers_toc Table of Contents
  10  - \ref GRAS_tut_tour_pointers_cste
  11
  12 <hr>
  13
  14
  15 \section GRAS_tut_tour_pointers_cste How to have constants in parsed structures?
  16
  17 You can use gras_datadesc_set_const() to explain GRAS about the value of
  18 your \#define'd constants.
  19
  20 \verbatim
  21 #define SIZE 12
  22 GRAS_DEFINE_TYPE(array,struct array {
  23   int data[SIZE];
  24 };);
  25
  26 void declare_ddt() {
  27   gras_datadesc_type_t ddt;
  28
  29   gras_datadesc_set_const("SIZE",SIZE); /* Set it before */
  30   gras_datadesc_by_symbol(array);
  31 }
  32 \endverbatim
  33
  34
  35 */
  36
  37     and the this example do use structures as payload,
  38     so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
  39     the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
  40     declaration into an hidden string variable, which can be automatically parsed at
  41     run time. Of course, the declaration is also copied unmodified by this macro, so that it
  42     gets parsed by the compiler also.
  43
  44     There is some semantic that GRAS cannot guess alone and you need to  <i>annotate</i>
  45     your declaration to add some. For example, the ctn pointer can be a reference to an
  46     object or a whole array (in which case you also has to specify its size). This is done
  47     with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
  48     GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
  49     array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
  50     being the other fields of the structure).
  51
  52     Please note that this annotation mechanism is not as robust and cool as this example seems to
  53     imply. If you want to use it yourself, you'd better use the exact right syntax, which is
  54     detailed in the \ref GRAS_dd section.
  55
  56     \skip GRAS_DEFINE_TYPE
  57     \until matrix_t
  58
  59
  60
  61 #define COLS 16
  62 #define MAX_ROUTESET 10
  63 #define MAX_LEAFSET COLS
  64
  65 GRAS_DEFINE_TYPE(gras_row_t,
  66 struct gras_row_t {
  67   int which_row;
  68   int row[COLS][MAX_ROUTESET];
  69 };)
  70
  71 typedef struct gras_row_t gras_row_t;
  72
  73 GRAS_DEFINE_TYPE(gras_welcome_msg_t,
  74 struct gras_welcome_msg_t {
  75   int id;
  76   double time_sent;
  77
  78   int row_count;
  79   gras_row_t *rows GRAS_ANNOTE(size,row_count);
  80
  81   int leaves[MAX_LEAFSET];
  82 };)
  83
  84 void declare_ddt(void) {
  85   gras_datadesc_type_t ddt;
  86
  87   gras_datadesc_set_const("COLS",COLS);
  88   gras_datadesc_set_const("MAX_ROUTESET",MAX_ROUTESET);
  89   gras_datadesc_set_const("MAX_LEAFSET",MAX_LEAFSET);
  90
  91   gras_datadesc_by_symbol(gras_row_t); /* Parse it before */
  92   ddt=gras_datadesc_ref("welcome_msg_t*",gras_datadesc_by_symbol(gras_welcome_msg_t));
  93   gras_msgtype_declare("welcome",ddt);
  94 }