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