X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/16a912c5ab08403fde93ad11b93ce0f55aff7c7c..1298f825dbd95a3e38a6f0f0130fc1800670aeae:/doc/module-gras.doc diff --git a/doc/module-gras.doc b/doc/module-gras.doc index 1d34200716..d3a7587440 100644 --- a/doc/module-gras.doc +++ b/doc/module-gras.doc @@ -1,22 +1,6 @@ -##################################################################### -########################### CORE ################################### -##################################################################### - /** \addtogroup GRAS_API -\htmlonly -
-
Table of content
-
    -
  1. API documentation -
  2. Examples -
  3. Tutorial -
  4. HOWTOs -
-\endhtmlonly - - \section GRAS_funct API documentation - GRAS offers the following 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 @@ -44,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? @@ -53,7 +37,12 @@ - \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. It details in a @@ -79,7 +68,7 @@ - \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. @@ -94,7 +83,7 @@ /** @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 @@ -141,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. @@ -155,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 @@ -274,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) @@ -341,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 @@ -368,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 @@ -395,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) @@ -433,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. @@ -443,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) @@ -458,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 @@ -517,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.