X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/fe8f0007bbd37e5e104fda886ff613276082e4f9..ebf7be2320c9239e70924752b5d9833224113ab4:/doc/module-gras.doc
diff --git a/doc/module-gras.doc b/doc/module-gras.doc
index c653142c9e..d3a7587440 100644
--- a/doc/module-gras.doc
+++ b/doc/module-gras.doc
@@ -1,10 +1,6 @@
-#####################################################################
-########################### CORE ###################################
-#####################################################################
-
/** \addtogroup GRAS_API
-
- \section GRAS_funct Offered functionnalities
+
+ \section GRAS_funct GRAS offers the following functionnalities
- \ref GRAS_comm: 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
@@ -32,8 +28,8 @@
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?
@@ -41,11 +37,20 @@
- \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
- 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:
+
- \ref GRAS_tut_intro
- \ref GRAS_tut_intro_what
- \ref GRAS_tut_intro_model
@@ -60,12 +65,25 @@
- \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 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.
+ 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_run Virtualization */
/** @defgroup GRAS_ex Examples */
- /** @defgroup GRAS_tut GRAS Tutorial */
+ /** @defgroup GRAS_tut Tutorial */
/** @} */
#####################################################################
/** @addtogroup GRAS_comm
@@ -112,12 +130,10 @@
- \ref GRAS_ex_token
- \ref GRAS_ex_timer
- \htmlonly \endhtmlonly
+ The initiatic tour of the tutorial also contains several examples. The
+ most proeminent one is:
+
+ - \ref GRAS_tut_tour_explicitwait_use
There is some more examples in the distribution, under the directory
examples/gras.
@@ -126,12 +142,11 @@
#####################################################################
######################### EXAMPLES #################################
#####################################################################
-
---------------------------------------------------------------------
------------------------- 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
@@ -245,7 +260,8 @@
--------------------- 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)
@@ -312,7 +328,8 @@
-------------------------- 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
@@ -339,7 +356,6 @@
- \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
@@ -366,27 +382,9 @@
\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 annotate
- 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)
@@ -404,9 +402,7 @@
\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.
@@ -414,14 +410,6 @@
\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)
@@ -429,8 +417,8 @@
\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
@@ -488,7 +476,8 @@
---------------------------- 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.