1 #####################################################################
2 ########################### CORE ###################################
3 #####################################################################
5 /** \addtogroup GRAS_API
9 <div class="tocTitle">Table of content</div>
11 <li> <a href="#GRAS_funct">API documentation</a>
12 <li> <a href="#GRAS_example">Examples</a>
13 <li> <a href="#GRAS_tut_presentation">Tutorial</a>
14 <li> <a href="#GRAS_howto_presentation">HOWTOs</a>
18 \section GRAS_funct API documentation
19 GRAS offers the following functionnalities
20 - <b>\ref GRAS_comm</b>: Exchanging messages between peers
21 - \ref GRAS_dd : any data which may transit on the network must be
22 described beforehand so that GRAS can handle the platform
23 heterogeneity and convert them if needed.
24 - \ref GRAS_sock : this is how to open a communication channel to
25 other processes, and retrive information about them.
26 - \ref GRAS_msg : communications are message oriented. You have to
27 describe all possible messages and their payload beforehand, and
28 can then attach callbacks to the arrival of a given kind of message.
29 - \ref GRAS_timer : this is how to program repetitive and delayed
30 tasks, not unlike cron(8) and at(1). This cannot be used to timeout
31 a function (like setitimer(2) or signal(2) games could do).
32 - <b>\ref GRAS_run</b>: Running both on top of the simulator and on
33 top of real platforms, and portability support.
34 - \ref GRAS_virtu : You naturally don't want to call the
35 gettimeofday(2) function in simulation mode since it would give
36 you the time on the host running the simulation, not the time in
37 the simulated world (you are belonging to).\n
38 This a system call virtualization layer, which also acts as a
40 - \ref GRAS_globals : The use of globals is forbidden since the
41 "processes" are threads in simulation mode. \n
42 This is how to let GRAS handle your globals properly.
43 - \ref GRAS_emul : Support to emulate code excution (ie, reporting
44 execution time into the simulator and having code sections specific
45 to simulation or to real mode).
47 \section GRAS_example Examples
49 There is for now rather few examples of GRAS, but it's better than
57 \section GRAS_tut_presentation Tutorial
59 We even have a tutorial for the GRAS framework. It details in a
60 hopefully pedagogic order all the points of the API, along with example
61 of use for each of them. Unfortunately, it is not finished yet (the main
62 part missing is the one on how to describe data). Here is the table of
66 - \ref GRAS_tut_intro_what
67 - \ref GRAS_tut_intro_model
69 - \ref GRAS_tut_tour_install
70 - \ref GRAS_tut_tour_setup
71 - \ref GRAS_tut_tour_simpleexchange
72 - \ref GRAS_tut_tour_args
73 - \ref GRAS_tut_tour_callbacks
74 - \ref GRAS_tut_tour_globals
75 - \ref GRAS_tut_tour_logs
76 - \ref GRAS_tut_tour_timers
77 - \ref GRAS_tut_tour_exceptions
78 - \ref GRAS_tut_tour_rpc
79 - \ref GRAS_tut_tour_explicitwait
80 - \ref GRAS_tut_tour_message_recaping
82 \section GRAS_howto_presentation HOWTOs
84 The tutorial and the API documentation present the framework little
85 piece by little piece and provide a lot of information on each of them.
86 Quite orthogonally to this, the HOWTOs try to present transversal
87 aspects of the framework to give you some broader point of view on it.
88 How infortunate it is that only one such HOWTO exist for now...
91 - \ref GRAS_howto_design
94 /** @defgroup GRAS_comm Communication facilities */
95 /** @defgroup GRAS_run Virtualization */
96 /** @defgroup GRAS_ex Examples */
97 /** @defgroup GRAS_tut GRAS Tutorial */
99 #####################################################################
100 /** @addtogroup GRAS_comm
102 Here are the communication facilities. GRAS allows you to exchange
103 <i>messages</i> on <i>sockets</i> (which can be seen as pipes between
104 processes). On reception, messages start <i>callbacks</i> (that's the
105 default communication mode, not the only one). All messages of a given
106 type convey the same kind of data, and you have to describe it
109 Timers are also seen as a mean of communication (with yourself). It
110 allows you to run a repetitive task ("do this every N second until I tell
111 you to stop"), or to deffer a treatment ("do this in 3 sec").
114 /** @defgroup GRAS_dd Data description */
115 /** @defgroup GRAS_sock Sockets */
116 /** @defgroup GRAS_msg Messages */
117 /** @defgroup GRAS_timer Timers */
120 #####################################################################
121 /** @addtogroup GRAS_run
123 Virtualization facilities allow your code to run both on top of the simulator or in real setting.
127 /** @defgroup GRAS_globals Globals */
128 /** @defgroup GRAS_emul Emulation support */
129 /** @defgroup GRAS_virtu Syscalls */
133 #####################################################################
134 /** @addtogroup GRAS_ex
136 There is for now rather few examples of GRAS, but it's better than
145 DOXYGEN_NAVBAR_CHILD "Ping-Pong"=GRAS_ex_ping.html
146 DOXYGEN_NAVBAR_CHILD "RPC"=GRAS_ex_mmrpc.html
147 DOXYGEN_NAVBAR_CHILD "Token Ring"=GRAS_ex_token.html
148 DOXYGEN_NAVBAR_CHILD "Timers"=GRAS_ex_timer.html
151 There is some more examples in the distribution, under the directory
152 <tt>examples/gras</tt>.
155 #####################################################################
156 ######################### EXAMPLES #################################
157 #####################################################################
159 ---------------------------------------------------------------------
160 ------------------------- Ping Pong ---------------------------------
161 ---------------------------------------------------------------------
163 /** \page GRAS_ex_ping The classical Ping-Pong in GRAS
165 This example implements the very classical ping-pong in GRAS. It
166 involves a client (initiating the ping-pong) and a server (answering to
169 It works the following way:
170 - Both the client and the server register all needed messages
171 - The server registers a callback to the ping message, which sends pong
173 - The client sends the ping message to the server, and waits for the
174 pong message as an answer.
176 This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
177 the code of the client and of the server is placed in the same file. See
178 the \ref GRAS_tut_tour_setup of the tutorial if wondering.
180 \section GRAS_ex_ping_toc Table of contents of the ping example
181 - \ref GRAS_ex_ping_common
182 - \ref GRAS_ex_ping_initial
183 - \ref GRAS_ex_ping_register
184 - \ref GRAS_ex_ping_server
185 - \ref GRAS_ex_ping_serdata
186 - \ref GRAS_ex_ping_sercb
187 - \ref GRAS_ex_ping_sermain
188 - \ref GRAS_ex_ping_client
189 - \ref GRAS_ex_ping_climain
193 \dontinclude gras/ping/ping_common.c
195 \section GRAS_ex_ping_common 1) Common code to the client and the server
197 \subsection GRAS_ex_ping_initial 1.a) Initial settings
199 Let's first load the module header and declare a logging category (see
200 \ref XBT_log for more info on logging).
205 The module header <tt>ping.h</tt> reads:
207 \dontinclude gras/ping/ping.h
212 \subsection GRAS_ex_ping_register 1.b) Register the messages
214 This function, called by both the client and the server is in charge of
215 declaring the existing messages to GRAS. Since the payload does not
216 involve any newly created types but only int, this is quite easy.
217 (to exchange more complicated types, see \ref GRAS_dd or
218 \ref GRAS_ex_mmrpc for an example).
220 \dontinclude gras/ping/ping_common.c
221 \skip register_messages
224 [Back to \ref GRAS_ex_ping_toc]
226 \section GRAS_ex_ping_server 2) Server's code
228 \subsection GRAS_ex_ping_serdata 2.a) The server's globals
230 In order to ensure the communication between the "main" and the callback
231 of the server, we need to declare some globals. We have to put them in a
232 struct definition so that they can be handled properly in GRAS (see the
233 \ref GRAS_tut_tour_globals for more info).
235 \dontinclude gras/ping/ping_server.c
239 \subsection GRAS_ex_ping_sercb 2.b) The callback to the ping message
241 Here is the callback run when the server receives any ping message (this
242 will be registered later by the server).
244 \skip server_cb_ping_handler
245 \until end_of_server_cb_ping_handler
247 \subsection GRAS_ex_ping_sermain 2.c) The "main" of the server
249 This is the "main" of the server. As explained in the tutorial, \ref
250 GRAS_tut_tour_setup, you must not write any main()
251 function yourself. Instead, you just have to write a regular function
252 like this one which will act as a main.
257 [Back to \ref GRAS_ex_ping_toc]
259 \section GRAS_ex_ping_client 3) Client's code
261 \subsection GRAS_ex_ping_climain 3.a) Client's "main" function
263 This function is quite straightforward, and the inlined comments should
264 be enough to understand it.
266 \dontinclude gras/ping/ping_client.c
270 [Back to \ref GRAS_ex_ping_toc]
273 ---------------------------------------------------------------------
274 --------------------- Simple Token Ring -----------------------------
275 ---------------------------------------------------------------------
277 /** \page GRAS_ex_token Token Ring example
279 This example implements the token ring algorithm. It involves several
280 nodes arranged in a ring (each of them have a left and a right neighbour)
281 and exchanging a "token". This algorithm is one of the solution to ensure
282 the mutual exclusion between distributed processes. There is only one
283 token at any time, so the process in its possession is ensured to be the
284 only one having it. So, if there is an action you want all processes to
285 do alternativly, but you cannot afford to have two processes doing it at
286 the same time, let the process having the token doing it.
288 Actually, there is a lot of different token ring algorithms in the
289 litterature, so this example implements one of them: the simplest one.
290 The ring is static (no new node can join it, and you'll get trouble if
291 one node dies or leaves), and nothing is done for the case in which the
294 - \ref GRAS_ex_stoken_deploy
295 - \ref GRAS_ex_stoken_global
296 - \ref GRAS_ex_stoken_callback
297 - \ref GRAS_ex_stoken_main
299 \section GRAS_ex_stoken_deploy 1) Deployment file
301 Here is the deployment file:
302 \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
304 The neighbour of each node is given at startup as command line argument.
305 Moreover, one of the nodes is instructed by a specific argument (the one
306 on Tremblay here) to create the token at the begining of the algorithm.
308 \section GRAS_ex_stoken_global 2) Global definition
310 The token is incarned by a specific message, which circulates from node
311 to node (the payload is an integer incremented at each hop). So, the most
312 important part of the code is the message callback, which forwards the
313 message to the next node. That is why we have to store all variable in a
314 global, as explained in the \ref GRAS_globals section.
316 \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
320 \section GRAS_ex_stoken_callback 3) The callback
322 Even if this is the core of this algorithm, this function is quite
325 \skip node_cb_stoken_handler
326 \until end_of_node_cb_stoken_handler
328 \section GRAS_ex_stoken_main 4) The main function
330 This function is splited in two parts: The first one performs all the
331 needed initialisations (points 1-7) while the end (point 8. below) calls
332 gras_msg_handle() as long as the planned amount of ring loops are not
340 ---------------------------------------------------------------------
341 -------------------------- MM RPC -----------------------------------
342 ---------------------------------------------------------------------
344 /** \page GRAS_ex_mmrpc A simple RPC for matrix multiplication
346 This example implements a remote matrix multiplication. It involves a client
347 (creating the matrices and sending the multiplications requests) and a server
348 (computing the multiplication on client's behalf).
350 This example also constitutes a more advanced example of data description
351 mechanisms, since the message payload type is a bit more complicated than in
352 other examples such as the ping one (\ref GRAS_ex_ping).
354 It works the following way (not very different from the ping example):
355 - Both the client and the server register all needed messages and datatypes
356 - The server registers a callback to the "request" message, which computes
357 what needs to be and returns the result to the expeditor.
358 - The client creates two matrices, ask for their multiplication and check
361 This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file. (See
362 the \ref GRAS_tut_tour_setup of the tutorial if wondering why both the server
363 and the client live in the same source file)
365 \section GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
366 - \ref GRAS_ex_mmrpc_common
367 - \ref GRAS_ex_mmrpc_header
368 - \ref GRAS_ex_mmrpc_dataregister
369 - \ref GRAS_ex_mmrpc_logdef
370 - \ref GRAS_ex_mmrpc_msgregister
371 - \ref GRAS_ex_mmrpc_matdump
372 - \ref GRAS_ex_mmrpc_server
373 - \ref GRAS_ex_mmrpc_serinc
374 - \ref GRAS_ex_mmrpc_sercb
375 - \ref GRAS_ex_mmrpc_sermain
376 - \ref GRAS_ex_mmrpc_client
377 - \ref GRAS_ex_mmrpc_cliinc
378 - \ref GRAS_ex_mmrpc_climain
383 \section GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
386 \subsection GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
388 This loads the gras header and declare the function's prototypes as well
391 \dontinclude gras/mmrpc/mmrpc.h
396 \subsection GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
398 The messages involved in this example do use structures as payload,
399 so we have to declare it to GRAS. Hopefully, this can be done easily by enclosing
400 the structure declaration within a \ref GRAS_DEFINE_TYPE macro call. It will then copy this
401 declaration into an hidden string variable, which can be automatically parsed at
402 run time. Of course, the declaration is also copied unmodified by this macro, so that it
403 gets parsed by the compiler also.
405 There is some semantic that GRAS cannot guess alone and you need to <i>annotate</i>
406 your declaration to add some. For example, the ctn pointer can be a reference to an
407 object or a whole array (in which case you also has to specify its size). This is done
408 with the GRAS_ANNOTE call. It is removed from the text passed to the compiler, but it helps
409 GRAS getting some information about the semantic of your data. Here, it says that \a ctn is an
410 array, which size is the result of the operation \a rows * \a cols (with \a rows and \a cols
411 being the other fields of the structure).
413 Please note that this annotation mechanism is not as robust and cool as this example seems to
414 imply. If you want to use it yourself, you'd better use the exact right syntax, which is
415 detailed in the \ref GRAS_dd section.
417 \skip GRAS_DEFINE_TYPE
420 \subsection GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
422 Let's first load the module header and declare a logging category (see
423 \ref XBT_log for more info on logging). This logging category does live
424 in this file (ie the required symbols are defined here and declared as
425 "extern" in any other file using them). That is why we use
426 \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
427 \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
429 \dontinclude gras/mmrpc/mmrpc_common.c
433 \subsection GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
435 This function, called by both the client and the server is in charge of
436 declaring the existing messages to GRAS. Note the use of the \ref gras_datadesc_by_symbol
437 function to parse and retrieve the structure declaration which were passed to \ref GRAS_DEFINE_TYPE
440 The datatype description builded that way can then be used to build an array datatype or
443 \skip register_messages
446 \subsection GRAS_ex_mmrpc_matdump 1.e) Helper debugging function (mmrpc_common.c)
448 This function dumps a matrix to screen for debugging.
454 [Back to \ref GRAS_ex_mmrpc_toc]
456 \section GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
458 \subsection GRAS_ex_mmrpc_serinc 2.a) Server intial settings
460 All module symbols live in the mmrpc_common.c file. We thus have to
461 define \ref GRAS_DEFINE_TYPE_EXTERN to the preprocessor so that the
462 \ref GRAS_DEFINE_TYPE symbols don't get included here. Likewise, we use
463 \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
465 \dontinclude gras/mmrpc/mmrpc_server.c
469 \subsection GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
471 Here is the callback run when the server receives any mmrpc message (this
472 will be registered later by the server). Note the way we get the message
473 payload. In the ping example, there was one additional level of pointer
474 indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
475 an array here (ie a pointer) whereas it is a scalar in the ping example.
477 \skip server_cb_request_handler
478 \until end_of_server_cb_request_handler
480 \subsection GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
482 This is the "main" of the server. As explained in the tutorial, \ref
483 GRAS_tut_tour_setup, you must not write any main()
484 function yourself. Instead, you just have to write a regular function
485 like this one which will act as a main.
490 [Back to \ref GRAS_ex_mmrpc_toc]
492 \section GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
494 \subsection GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
496 As for the server, some extra love is needed to make sure that automatic
497 datatype parsing and log categories do work even if we are using several
500 \dontinclude gras/mmrpc/mmrpc_client.c
504 \subsection GRAS_ex_mmrpc_climain 3.b) Client's "main" function
506 This function is quite straightforward, and the inlined comments should
507 be enough to understand it.
509 \dontinclude gras/mmrpc/mmrpc_client.c
513 [Back to \ref GRAS_ex_mmrpc_toc]
516 ---------------------------------------------------------------------
517 ---------------------------- Timers ---------------------------------
518 ---------------------------------------------------------------------
520 /** \page GRAS_ex_timer Some timer games
522 This example fools around with the GRAS timers (\ref GRAS_timer). It is
523 mainly a regression test, since it uses almost all timer features.
525 The main program registers a repetititive task and a delayed one, and
526 then loops until the <tt>still_to_do</tt> variables of its globals reach
527 0. The delayed task set it to 5, and the repetititive one decrease it
528 each time. Here is an example of output:
529 \verbatim Initialize GRAS
531 [1108335471] Programming the repetitive_action with a frequency of 1.000000 sec
532 [1108335471] Programming the delayed_action for after 2.000000 sec
533 [1108335471] Have a rest
534 [1108335472] Canceling the delayed_action.
535 [1108335472] Re-programming the delayed_action for after 2.000000 sec
536 [1108335472] Repetitive_action has nothing to do yet
537 [1108335473] Repetitive_action has nothing to do yet
538 [1108335473] delayed_action setting globals->still_to_do to 5
539 [1108335474] repetitive_action decrementing globals->still_to_do. New value: 4
540 [1108335475] repetitive_action decrementing globals->still_to_do. New value: 3
541 [1108335476] repetitive_action decrementing globals->still_to_do. New value: 2
542 [1108335477] repetitive_action decrementing globals->still_to_do. New value: 1
543 [1108335478] repetitive_action decrementing globals->still_to_do. New value: 0
544 Exiting GRAS\endverbatim
547 - \ref GRAS_ex_timer_decl
548 - \ref GRAS_ex_timer_delay
549 - \ref GRAS_ex_timer_repeat
550 - \ref GRAS_ex_timer_main
554 \section GRAS_ex_timer_decl 1. Declarations and headers
558 \section GRAS_ex_timer_delay 2. Source code of the delayed action
559 \skip repetitive_action
560 \until end_of_repetitive_action
562 \section GRAS_ex_timer_repeat 3. Source code of the repetitive action
564 \until end_of_delayed_action
566 \section GRAS_ex_timer_main 4. Source code of main function