#####################################################################
/** \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
- \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
- \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 */
- \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
- \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
\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_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.
\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)
\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
