\include msg/small_platform.xml
-\section using_gras Using GRAS
-
-Here are some examples on how to use GRAS.
-\htmlonly
-You should also check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
-\endhtmlonly
-
-There is for now rather few examples of GRAS, but it's better than
-nothing, isn't it?
-
-- \ref GRAS_ex_ping
-- \ref GRAS_ex_mmrpc
-- \ref GRAS_ex_token
-- \ref GRAS_ex_timer
-
-
-\subsection GRAS_ex_ping Ping-Pong
-
-This example implements the very classical ping-pong in GRAS. It
-involves a client (initiating the ping-pong) and a server (answering to
-client's requests).
-
-It works the following way:
-- Both the client and the server register all needed messages
-- The server registers a callback to the ping message, which sends pong
- to the expeditor
-- The client sends the ping message to the server, and waits for the
- pong message as an answer.
-
-This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
-the code of the client and of the server is placed in the same file.
-
-\subsubsection GRAS_ex_ping_toc Table of contents of the ping example
- - \ref GRAS_ex_ping_common
- - \ref GRAS_ex_ping_initial
- - \ref GRAS_ex_ping_register
- - \ref GRAS_ex_ping_server
- - \ref GRAS_ex_ping_serdata
- - \ref GRAS_ex_ping_sercb
- - \ref GRAS_ex_ping_sermain
- - \ref GRAS_ex_ping_client
- - \ref GRAS_ex_ping_climain
-
- <hr>
-
- \dontinclude gras/ping/ping_common.c
-
- \subsubsection GRAS_ex_ping_common 1) Common code to the client and the server
-
- \paragraph GRAS_ex_ping_initial 1.a) Initial settings
-
- Let's first load the module header and declare a logging category (see
- \ref XBT_log for more info on logging).
-
- \skip include
- \until XBT_LOG
-
- The module header <tt>ping.h</tt> reads:
-
- \dontinclude gras/ping/ping.h
- \skip include
- \until argv
- \until argv
-
- \paragraph GRAS_ex_ping_register 1.b) Register the messages
-
- This function, called by both the client and the server is in charge of
- declaring the existing messages to GRAS. Since the payload does not
- involve any newly created types but only int, this is quite easy.
- (to exchange more complicated types, see \ref GRAS_dd or
- \ref GRAS_ex_mmrpc for an example).
-
- \dontinclude gras/ping/ping_common.c
- \skip register_messages
- \until }
-
- [Back to \ref GRAS_ex_ping_toc]
-
- \subsubsection GRAS_ex_ping_server 2) Server's code
-
- \paragraph GRAS_ex_ping_serdata 2.a) The server's globals
-
- In order to ensure the communication between the "main" and the callback
- of the server, we need to declare some globals. We have to put them in a
- struct definition so that they can be handled properly in GRAS.
-
- \dontinclude gras/ping/ping_server.c
- \skip typedef struct
- \until }
-
- \paragraph GRAS_ex_ping_sercb 2.b) The callback to the ping message
-
- Here is the callback run when the server receives any ping message (this
- will be registered later by the server).
-
- \skip server_cb_ping_handler
- \until end_of_server_cb_ping_handler
-
- \paragraph GRAS_ex_ping_sermain 2.c) The "main" of the server
-
- This is the "main" of the server. 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_ping_toc]
-
- \subsubsection GRAS_ex_ping_client 3) Client's code
-
- \paragraph GRAS_ex_ping_climain 3.a) Client's "main" function
-
- This function is quite straightforward, and the inlined comments should
- be enough to understand it.
-
- \dontinclude gras/ping/ping_client.c
- \skip client
- \until end_of_client
-
- [Back to \ref GRAS_ex_ping_toc]
-
-\subsection 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
-
- \subsection 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.
-
- \subsection 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 }
-
- \subsection 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
-
- \subsection 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
-
-\subsection 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.
-
-\subsubsection 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>
-
-
- \subsubsection GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
-
-
- \paragraph 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
-
- \paragraph 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.
-
- \paragraph 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
-
- \paragraph 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]
-
- \subsubsection GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
-
- \paragraph 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
-
- \paragraph 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
-
- \paragraph GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
-
- This is the "main" of the server. 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]
-
- \subsubsection GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
-
- \paragraph 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
-
- \paragraph 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]
-
-\subsection GRAS_ex_timer Some timer games
-
-This example fools around with the GRAS timers (\ref GRAS_timer). It is
-mainly a regression test, since it uses almost all timer features.
-
-The main program registers a repetititive task and a delayed one, and
-then loops until the <tt>still_to_do</tt> variables of its globals reach
-0. The delayed task set it to 5, and the repetititive one decrease it
-each time. Here is an example of output:
-\verbatim Initialize GRAS
- Initialize XBT
- [1108335471] Programming the repetitive_action with a frequency of 1.000000 sec
- [1108335471] Programming the delayed_action for after 2.000000 sec
- [1108335471] Have a rest
- [1108335472] Canceling the delayed_action.
- [1108335472] Re-programming the delayed_action for after 2.000000 sec
- [1108335472] Repetitive_action has nothing to do yet
- [1108335473] Repetitive_action has nothing to do yet
- [1108335473] delayed_action setting globals->still_to_do to 5
- [1108335474] repetitive_action decrementing globals->still_to_do. New value: 4
- [1108335475] repetitive_action decrementing globals->still_to_do. New value: 3
- [1108335476] repetitive_action decrementing globals->still_to_do. New value: 2
- [1108335477] repetitive_action decrementing globals->still_to_do. New value: 1
- [1108335478] repetitive_action decrementing globals->still_to_do. New value: 0
- Exiting GRAS\endverbatim
-
- Source code:
- - \ref GRAS_ex_timer_decl
- - \ref GRAS_ex_timer_delay
- - \ref GRAS_ex_timer_repeat
- - \ref GRAS_ex_timer_main
-
- \dontinclude timer.c
-
- \subsubsection GRAS_ex_timer_decl 1. Declarations and headers
- \skip include
- \until my_globals
-
- \subsubsection GRAS_ex_timer_delay 2. Source code of the delayed action
- \skip repetitive_action
- \until end_of_repetitive_action
-
- \subsubsection GRAS_ex_timer_repeat 3. Source code of the repetitive action
- \skip delayed_action
- \until end_of_delayed_action
-
- \subsubsection GRAS_ex_timer_main 4. Source code of main function
- \skip client
- \until end_of_client
-
\section using_smpi Using SMPI
You should check our online <a href="http://simgrid.gforge.inria.fr/tutorials.html"> tutorial section</a> that contains a dedicated tutorial.
