+
+ [Back to \ref GRAS_ex_ping_toc]
+ */
+
+---------------------------------------------------------------------
+--------------------- Simple Token Ring -----------------------------
+---------------------------------------------------------------------
+
+/** \page GRAS_ex_token Token Ring example
+
+ 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)
+ and exchanging a "token". This algorithm is one of the solution to ensure
+ the mutual exclusion between distributed processes. There is only one
+ token at any time, so the process in its possession is ensured to be the
+ only one having it. So, if there is an action you want all processes to
+ do alternativly, but you cannot afford to have two processes doing it at
+ the same time, let the process having the token doing it.
+
+ Actually, there is a lot of different token ring algorithms in the
+ litterature, so this example implements one of them: the simplest one.
+ The ring is static (no new node can join it, and you'll get trouble if
+ one node dies or leaves), and nothing is done for the case in which the
+ token is lost.
+
+ - \ref GRAS_ex_stoken_deploy
+ - \ref GRAS_ex_stoken_global
+ - \ref GRAS_ex_stoken_callback
+ - \ref GRAS_ex_stoken_main
+
+ \section GRAS_ex_stoken_deploy 1) Deployment file
+
+ Here is the deployment file:
+ \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
+
+ The neighbour of each node is given at startup as command line argument.
+ Moreover, one of the nodes is instructed by a specific argument (the one
+ on Tremblay here) to create the token at the begining of the algorithm.
+
+ \section GRAS_ex_stoken_global 2) Global definition
+
+ The token is incarned by a specific message, which circulates from node
+ to node (the payload is an integer incremented at each hop). So, the most
+ important part of the code is the message callback, which forwards the
+ message to the next node. That is why we have to store all variable in a
+ global, as explained in the \ref GRAS_globals section.
+
+ \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
+ \skip typedef
+ \until }
+
+ \section GRAS_ex_stoken_callback 3) The callback
+
+ Even if this is the core of this algorithm, this function is quite
+ straightforward.
+
+ \skip node_cb_stoken_handler
+ \until end_of_node_cb_stoken_handler
+
+ \section GRAS_ex_stoken_main 4) The main function
+
+ This function is splited in two parts: The first one performs all the
+ needed initialisations (points 1-7) while the end (point 8. below) calls
+ gras_msg_handle() as long as the planned amount of ring loops are not
+ performed.
+
+ \skip node
+ \until end_of_node
+
+*/
+
+---------------------------------------------------------------------
+-------------------------- MM RPC -----------------------------------
+---------------------------------------------------------------------
+
+/** \page GRAS_ex_mmrpc A simple RPC for matrix multiplication
+
+ This example implements a remote matrix multiplication. It involves a client
+ (creating the matrices and sending the multiplications requests) and a server
+ (computing the multiplication on client's behalf).
+
+ This example also constitutes a more advanced example of data description
+ mechanisms, since the message payload type is a bit more complicated than in
+ other examples such as the ping one (\ref GRAS_ex_ping).
+
+ It works the following way (not very different from the ping example):
+ - Both the client and the server register all needed messages and datatypes
+ - The server registers a callback to the "request" message, which computes
+ what needs to be and returns the result to the expeditor.
+ - The client creates two matrices, ask for their multiplication and check
+ the server's answer.
+
+ This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file. (See
+ the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server
+ and the client live in the same source file)
+
+ \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
+ - \ref GRAS_ex_mmrpc_common
+ - \ref GRAS_ex_mmrpc_header
+ - \ref GRAS_ex_mmrpc_dataregister
+ - \ref GRAS_ex_mmrpc_logdef
+ - \ref GRAS_ex_mmrpc_msgregister
+ - \ref GRAS_ex_mmrpc_server
+ - \ref GRAS_ex_mmrpc_serinc
+ - \ref GRAS_ex_mmrpc_sercb
+ - \ref GRAS_ex_mmrpc_sermain
+ - \ref GRAS_ex_mmrpc_client
+ - \ref GRAS_ex_mmrpc_cliinc
+ - \ref GRAS_ex_mmrpc_climain
+
+ <hr>
+
+
+ \section GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
+
+
+ \subsection GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
+
+ This loads the gras header and declare the function's prototypes as well
+ as the matrix size.
+
+ \dontinclude gras/mmrpc/mmrpc.h
+ \skip include
+ \until argv
+ \until argv
+
+ \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
+
+ 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)
+
+ Let's first load the module header and declare a logging category (see
+ \ref XBT_log for more info on logging). This logging category does live
+ in this file (ie the required symbols are defined here and declared as
+ "extern" in any other file using them). That is why we use
+ \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
+ \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
+
+ \dontinclude gras/mmrpc/mmrpc_common.c
+ \skip include
+ \until XBT_LOG
+
+ \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.
+
+ The datatype description builded that way can then be used to build an array datatype or
+ to declare messages.
+
+ \skip register_messages
+ \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 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
+ \skip define
+ \until XBT_LOG
+
+ \subsection GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
+
+ Here is the callback run when the server receives any mmrpc message (this
+ will be registered later by the server). Note the way we get the message
+ payload. In the ping example, there was one additional level of pointer
+ indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
+ an array here (ie a pointer) whereas it is a scalar in the ping example.
+
+ \skip server_cb_request_handler
+ \until end_of_server_cb_request_handler
+
+ \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
+
+ This is the "main" of the server. As explained in the tutorial, \ref
+ GRAS_tut_tour_setup, you must not write any main()
+ function yourself. Instead, you just have to write a regular function
+ like this one which will act as a main.
+
+ \skip server
+ \until end_of_server
+
+ [Back to \ref GRAS_ex_mmrpc_toc]
+
+ \section GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
+
+ \subsection GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
+
+ As for the server, some extra love is needed to make sure that automatic
+ datatype parsing and log categories do work even if we are using several
+ files.
+
+ \dontinclude gras/mmrpc/mmrpc_client.c
+ \skip define
+ \until XBT_LOG
+
+ \subsection GRAS_ex_mmrpc_climain 3.b) Client's "main" function
+
+ This function is quite straightforward, and the inlined comments should
+ be enough to understand it.
+
+ \dontinclude gras/mmrpc/mmrpc_client.c
+ \skip argv
+ \until end_of_client
+
+ [Back to \ref GRAS_ex_mmrpc_toc]