X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/2137669fc54b364d20ae4debaef1744d55acce2c..e5922b4dce28002422ca9d68a4c44521f67c0f6f:/doc/gtut-tour-13-pointers.doc

diff --git a/doc/gtut-tour-13-pointers.doc b/doc/gtut-tour-13-pointers.doc
index 57db72aec3..3c0f6a9500 100644
--- a/doc/gtut-tour-13-pointers.doc
+++ b/doc/gtut-tour-13-pointers.doc
@@ -1,26 +1,100 @@
 /**
 @page GRAS_tut_tour_pointers Lesson 13: Defining structure containing pointers (TODO)
 
+This lesson is a bit different from the other ones. It aims at explaining
+several features of the automatic datadesc parsing. Since it would be a bit
+long otherwise, the lesson is organized as a FAQ, with little examples of
+how to do things.
+
 \section GRAS_tut_tour_pointers_toc Table of Contents
  - \ref GRAS_tut_tour_pointers_intro
  - \ref GRAS_tut_tour_pointers_use
  - \ref GRAS_tut_tour_pointers_recap
+ - \ref GRAS_tut_tour_pointers_cste
    
 <hr>
+\section GRAS_tut_tour_pointers_intro Introduction to pointers in datadesc
+\section GRAS_tut_tour_pointers_use Using pointers in datadesc
+\section GRAS_tut_tour_pointers_recap Recapping everything
 
-\section GRAS_tut_tour_pointers_intro Introduction
 
+\section GRAS_tut_tour_pointers_cste How to have constants in parsed structures?
 
-\section GRAS_tut_tour_pointers_use Defining structure containing pointers
+You can use gras_datadesc_set_const() to explain GRAS about the value of
+your \#define'd constants.
 
+\verbatim
+#define SIZE 12
+GRAS_DEFINE_TYPE(array,struct array {
+  int data[SIZE];
+};);
 
-\section GRAS_tut_tour_pointers_recap Recapping everything together
+void declare_ddt() {
+  gras_datadesc_type_t ddt;
+  
+  gras_datadesc_set_const("SIZE",SIZE); /* Set it before */
+  gras_datadesc_by_symbol(array); 
+}
+\endverbatim
 
-The program now reads:
-\include 12-pointers.c
 
-Which produces the expected output:
-\include 12-pointers.output
+*/
 
+    and the this example do use structures as payload, 
+    so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing 
+    the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this 
+    declaration into an hidden string variable, which can be automatically parsed at 
+    run time. Of course, the declaration is also copied unmodified by this macro, so that it
+    gets parsed by the compiler also. 
 
-*/
+    There is some semantic that GRAS cannot guess alone and you need to  <i>annotate</i>
+    your declaration to add some. For example, the ctn pointer can be a reference to an 
+    object or a whole array (in which case you also has to specify its size). This is done 
+    with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
+    GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an 
+    array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols 
+    being the other fields of the structure). 
+
+    Please note that this annotation mechanism is not as robust and cool as this example seems to 
+    imply. If you want to use it yourself, you'd better use the exact right syntax, which is 
+    detailed in the \ref GRAS_dd section.
+
+    \skip GRAS_DEFINE_TYPE
+    \until matrix_t
+
+
+
+#define COLS 16
+#define MAX_ROUTESET 10
+#define MAX_LEAFSET COLS
+
+GRAS_DEFINE_TYPE(gras_row_t,
+struct gras_row_t {         
+  int which_row;            
+  int row[COLS][MAX_ROUTESET];
+};)
+    
+typedef struct gras_row_t gras_row_t;
+    
+GRAS_DEFINE_TYPE(gras_welcome_msg_t, 
+struct gras_welcome_msg_t {
+  int id;
+  double time_sent;
+    
+  int row_count;
+  gras_row_t *rows GRAS_ANNOTE(size,row_count);
+	
+  int leaves[MAX_LEAFSET];
+};)              
+
+void declare_ddt(void) {
+  gras_datadesc_type_t ddt;
+  
+  gras_datadesc_set_const("COLS",COLS);
+  gras_datadesc_set_const("MAX_ROUTESET",MAX_ROUTESET);
+  gras_datadesc_set_const("MAX_LEAFSET",MAX_LEAFSET);
+  
+  gras_datadesc_by_symbol(gras_row_t); /* Parse it before */
+  ddt=gras_datadesc_ref("welcome_msg_t*",gras_datadesc_by_symbol(gras_welcome_msg_t));
+  gras_msgtype_declare("welcome",ddt);  
+}