Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
Removed some unused and out-of-date XML files, corrected some others in order to...
[simgrid.git] / doc / module-gras.doc
index eaa547d..d3a7587 100644 (file)
@@ -1,22 +1,6 @@
-#####################################################################
-###########################  CORE ###################################
-#####################################################################
-
 /** \addtogroup GRAS_API
 
 /** \addtogroup GRAS_API
 
-\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
+    \section GRAS_funct 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
@@ -44,8 +28,8 @@
          execution time into the simulator and having code sections specific
          to simulation or to real mode).     
          
          execution time into the simulator and having code sections specific
          to simulation or to real mode).     
          
-    \section GRAS_example Examples
-      
+    \section GRAS_examples Examples
     There is for now rather few examples of GRAS, but it's better than
     nothing, isn't it?
     
     There is for now rather few examples of GRAS, but it's better than
     nothing, isn't it?
     
@@ -58,7 +42,7 @@
      most proeminent one is:
       
        - \ref GRAS_tut_tour_explicitwait_use
      most proeminent one is:
       
        - \ref GRAS_tut_tour_explicitwait_use
-       
+
     \section GRAS_tut_presentation Tutorial
     
     We even have a tutorial for the GRAS framework. It details in a
     \section GRAS_tut_presentation Tutorial
     
     We even have a tutorial for the GRAS framework. It details in a
@@ -84,7 +68,7 @@
         - \ref GRAS_tut_tour_explicitwait
         - \ref GRAS_tut_tour_message_recaping
 
         - \ref GRAS_tut_tour_explicitwait
         - \ref GRAS_tut_tour_message_recaping
 
-    \section GRAS_howto_presentation HOWTOs
+    \section GRAS_howto_presentation HOWTOsbis
     
     The tutorial and the API documentation present the framework little
     piece by little piece and provide a lot of information on each of them.
     
     The tutorial and the API documentation present the framework little
     piece by little piece and provide a lot of information on each of them.
@@ -99,7 +83,7 @@
        /** @defgroup GRAS_comm    Communication facilities */
        /** @defgroup GRAS_run     Virtualization */
        /** @defgroup GRAS_ex      Examples */
        /** @defgroup GRAS_comm    Communication facilities */
        /** @defgroup GRAS_run     Virtualization */
        /** @defgroup GRAS_ex      Examples */
-       /** @defgroup GRAS_tut     GRAS Tutorial */
+       /** @defgroup GRAS_tut     Tutorial */
 /** @} */
 #####################################################################
 /** @addtogroup GRAS_comm
 /** @} */
 #####################################################################
 /** @addtogroup GRAS_comm
      most proeminent one is:
       
        - \ref GRAS_tut_tour_explicitwait_use
      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
-      DOXYGEN_NAVBAR_CHILD "Token Ring"=GRAS_ex_token.html
-      DOXYGEN_NAVBAR_CHILD "Timers"=GRAS_ex_timer.html
-    --> \endhtmlonly
 
   There is some more examples in the distribution, under the directory
   <tt>examples/gras</tt>.
 
   There is some more examples in the distribution, under the directory
   <tt>examples/gras</tt>.
 #####################################################################
 #########################  EXAMPLES #################################
 #####################################################################
 #####################################################################
 #########################  EXAMPLES #################################
 #####################################################################
-
 ---------------------------------------------------------------------
 ------------------------- Ping Pong ---------------------------------
 ---------------------------------------------------------------------
 ---------------------------------------------------------------------
 ------------------------- Ping Pong ---------------------------------
 ---------------------------------------------------------------------
-
-/** \page GRAS_ex_ping The classical Ping-Pong in GRAS
+/** @defgroup GRAS_ex_ping Ping-Pong
+    @ingroup GRAS_ex
 
     This example implements the very classical ping-pong in GRAS. It
     involves a client (initiating the ping-pong) and a server (answering to 
 
     This example implements the very classical ping-pong in GRAS. It
     involves a client (initiating the ping-pong) and a server (answering to 
 --------------------- Simple Token Ring -----------------------------
 ---------------------------------------------------------------------
 
 --------------------- Simple Token Ring -----------------------------
 ---------------------------------------------------------------------
 
-/** \page GRAS_ex_token Token Ring example
+/** @defgroup GRAS_ex_token Token Ring example
+    @ingroup GRAS_ex
 
    This example implements the token ring algorithm. It involves several
    nodes arranged in a ring (each of them have a left and a right neighbour)
 
    This example implements the token ring algorithm. It involves several
    nodes arranged in a ring (each of them have a left and a right neighbour)
 -------------------------- MM RPC -----------------------------------
 ---------------------------------------------------------------------
 
 -------------------------- MM RPC -----------------------------------
 ---------------------------------------------------------------------
 
-/** \page GRAS_ex_mmrpc A simple RPC for matrix multiplication
+/** @defgroup GRAS_ex_mmrpc A simple RPC for matrix multiplication
+    @ingroup GRAS_ex
 
     This example implements a remote matrix multiplication. It involves a client 
     (creating the matrices and sending the multiplications requests) and a server 
 
     This example implements a remote matrix multiplication. It involves a client 
     (creating the matrices and sending the multiplications requests) and a server 
         - \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)
     \subsection GRAS_ex_mmrpc_serinc 2.a) Server intial settings
     
     All module symbols live in the mmrpc_common.c file. We thus have to
     \subsection GRAS_ex_mmrpc_serinc 2.a) Server intial settings
     
     All module symbols live in the mmrpc_common.c file. We thus have to
-    define \ref GRAS_DEFINE_TYPE_EXTERN to the preprocessor so that the
-    \ref GRAS_DEFINE_TYPE symbols don't get included here. Likewise, we use 
+    define \ref XBT_DEFINE_TYPE_EXTERN to the preprocessor so that the
+    \ref XBT_DEFINE_TYPE symbols don't get included here. Likewise, we use 
     \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
     
     \dontinclude gras/mmrpc/mmrpc_server.c
     \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
     
     \dontinclude gras/mmrpc/mmrpc_server.c
 ---------------------------- Timers ---------------------------------
 ---------------------------------------------------------------------
 
 ---------------------------- Timers ---------------------------------
 ---------------------------------------------------------------------
 
-/** \page GRAS_ex_timer Some timer games
+/** @defgroup GRAS_ex_timer Some timer games
+    @ingroup GRAS_ex
 
     This example fools around with the GRAS timers (\ref GRAS_timer). It is
     mainly a regression test, since it uses almost all timer features.
 
     This example fools around with the GRAS timers (\ref GRAS_timer). It is
     mainly a regression test, since it uses almost all timer features.