Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Add missing XBT_PUBLIC in declaration.
[simgrid.git] / doc / module-gras.doc
index c653142..c91622e 100644 (file)
@@ -3,8 +3,20 @@
 #####################################################################
 
 /** \addtogroup GRAS_API
 #####################################################################
 
 /** \addtogroup GRAS_API
-  
-    \section GRAS_funct Offered functionnalities
+
+\htmlonly
+<div class="toc">
+<div class="tocTitle">Table of content</div>
+<ol type="1">
+<li> <a href="#GRAS_funct">API documentation</a>
+<li> <a href="#GRAS_example">Examples</a>
+<li> <a href="#GRAS_tut_presentation">Tutorial</a>
+<li> <a href="#GRAS_howto_presentation">HOWTOs</a>
+</div>
+\endhtmlonly
+
+    \section GRAS_funct API documentation
+     GRAS offers the following functionnalities
      - <b>\ref GRAS_comm</b>: Exchanging messages between peers
        - \ref GRAS_dd : any data which may transit on the network must be
          described beforehand so that GRAS can handle the platform
      - <b>\ref GRAS_comm</b>: Exchanging messages between peers
        - \ref GRAS_dd : any data which may transit on the network must be
          described beforehand so that GRAS can handle the platform
        - \ref GRAS_ex_mmrpc
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
        - \ref GRAS_ex_mmrpc
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
+      
+     The initiatic tour of the tutorial also contains several examples. The
+     most proeminent one is:
+      
+       - \ref GRAS_tut_tour_explicitwait_use
        
     \section GRAS_tut_presentation Tutorial
     
        
     \section GRAS_tut_presentation Tutorial
     
-    We even have a tutorial for the GRAS framework. Here is the table of
+    We even have a tutorial for the GRAS framework. It details in a
+    hopefully pedagogic order all the points of the API, along with example
+    of use for each of them. Unfortunately, it is not finished yet (the main
+    part missing is the one on how to describe data). Here is the table of
     content:
     content:
+    
        - \ref GRAS_tut_intro
          - \ref GRAS_tut_intro_what
          - \ref GRAS_tut_intro_model
        - \ref GRAS_tut_intro
          - \ref GRAS_tut_intro_what
          - \ref GRAS_tut_intro_model
         - \ref GRAS_tut_tour_timers
         - \ref GRAS_tut_tour_exceptions
         - \ref GRAS_tut_tour_rpc
         - \ref GRAS_tut_tour_timers
         - \ref GRAS_tut_tour_exceptions
         - \ref GRAS_tut_tour_rpc
+        - \ref GRAS_tut_tour_explicitwait
+        - \ref GRAS_tut_tour_message_recaping
+
+    \section GRAS_howto_presentation HOWTOs
+    
+    The tutorial and the API documentation present the framework little
+    piece by little piece and provide a lot of information on each of them.
+    Quite orthogonally to this, the HOWTOs try to present transversal
+    aspects of the framework to give you some broader point of view on it.
+    How infortunate it is that only one such HOWTO exist for now...
+
+       - \ref GRAS_howto
+         - \ref GRAS_howto_design
 
     @{ */
        /** @defgroup GRAS_comm    Communication facilities */
 
     @{ */
        /** @defgroup GRAS_comm    Communication facilities */
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
 
        - \ref GRAS_ex_token
        - \ref GRAS_ex_timer
 
+     The initiatic tour of the tutorial also contains several examples. The
+     most proeminent one is:
+      
+       - \ref GRAS_tut_tour_explicitwait_use
+       
     \htmlonly <!-- 
       DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
       DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
     \htmlonly <!-- 
       DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
       DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
         - \ref GRAS_ex_mmrpc_dataregister
         - \ref GRAS_ex_mmrpc_logdef
         - \ref GRAS_ex_mmrpc_msgregister
         - \ref GRAS_ex_mmrpc_dataregister
         - \ref GRAS_ex_mmrpc_logdef
         - \ref GRAS_ex_mmrpc_msgregister
-        - \ref GRAS_ex_mmrpc_matdump
       - \ref GRAS_ex_mmrpc_server
        - \ref GRAS_ex_mmrpc_serinc
        - \ref GRAS_ex_mmrpc_sercb
       - \ref GRAS_ex_mmrpc_server
        - \ref GRAS_ex_mmrpc_serinc
        - \ref GRAS_ex_mmrpc_sercb
 
     \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
 
 
     \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
 
-    The messages involved in 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
+    The messages involved in a matrix of double. This type is automatically
+    known by the GRAS mecanism, using the gras_datadesc_matrix() function of the
+    xbt/matrix module.
 
     \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
     
 
     \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
     
     \subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
     
     This function, called by both the client and the server is in charge of
     \subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
     
     This function, called by both the client and the server is in charge of
-    declaring the existing messages to GRAS. Note the use of the \ref gras_datadesc_by_symbol 
-    function to parse and retrieve the structure declaration which were passed to \ref GRAS_DEFINE_TYPE 
-    above. 
+    declaring the existing messages to GRAS.
 
     The datatype description builded that way can then be used to build an array datatype or 
     to declare messages.
 
     The datatype description builded that way can then be used to build an array datatype or 
     to declare messages.
     \skip register_messages
     \until }
 
     \skip register_messages
     \until }
 
-    \subsection GRAS_ex_mmrpc_matdump 1.e) Helper debugging function (mmrpc_common.c)
-
-    This function dumps a matrix to screen for debugging.
-    
-    \skip mat_dump
-    \until end_of_matrix
-    \until }
-
     [Back to \ref GRAS_ex_mmrpc_toc]
 
     \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
     [Back to \ref GRAS_ex_mmrpc_toc]
 
     \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)