1 /*! \page use Using SimGrid
3 SimGrid comes with many examples provided in the examples/ directory. Those examples are described in section \ref MSG_examples . Those examples are commented and should be easy to understand. for a first step into SimGrid we also provide some more detailed examples in the sections below.
6 You should also check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a generic tutorial about using SimGrid.
10 \section using_msg Using MSG
12 You should also check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
17 Here are some examples on how to use MSG, the most used API.
20 MSG comes with an extensive set of examples. It is sometimes difficult
21 to find the one you need. This list aims at helping you finding the
22 example from which you can learn what you want to.
24 \subsection MSG_ex_basics Basic examples and features
26 \subsubsection MSG_ex_asynchronous_communications Asynchronous communications
29 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
30 an external description of the deployment.
32 - \ref MSG_ext_icomms_code
33 - \ref MSG_ext_icomms_preliminary
34 - \ref MSG_ext_icomms_Sender
35 - \ref MSG_ext_icomms_Receiver
36 - \ref MSG_ext_icomms_core
37 - \ref MSG_ext_icomms_Main
38 - \ref MSG_ext_icomms_fct_Waitall
39 - \ref MSG_ext_icomms_fct_Waitany
43 \dontinclude msg/icomms/peer.c
45 \paragraph MSG_ext_icomms_code Code of the application
47 \paragraph MSG_ext_icomms_preliminary Preliminary declarations
49 \until Sender function
51 \paragraph MSG_ext_icomms_Sender Sender function
53 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
54 we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
55 It also available to "make MSG_comm_wait()" which make both of them.
57 C style arguments (argc/argv) are interpreted as:
58 - the number of tasks to distribute
59 - the computation size of each task
60 - the size of the files associated to each task
61 - a list of host that will accept those tasks.
62 - the time to sleep at the beginning of the function
63 - This time defined the process sleep time
64 if time = 0 use of MSG_comm_wait()
65 if time > 0 use of MSG_comm_test()
68 \until Receiver function
70 \paragraph MSG_ext_icomms_Receiver Receiver function
72 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
73 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
75 C style arguments (argc/argv) are interpreted as:
76 - the id to use for received the communication.
77 - the time to sleep at the beginning of the function
78 - This time defined the process sleep time
79 if time = 0 use of MSG_comm_wait()
80 if time > 0 use of MSG_comm_test()
84 \paragraph MSG_ext_icomms_core Simulation core
86 This function is the core of the simulation and is divided only into 3 parts
87 thanks to MSG_create_environment() and MSG_launch_application().
88 -# Simulation settings : MSG_create_environment() creates a realistic
90 -# Application deployment : create the processes on the right locations with
91 MSG_launch_application()
92 -# The simulation is run with #MSG_main()
95 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
96 - <i>application_file</i>: the name of a file containing a valid surfxml application description
100 \paragraph MSG_ext_icomms_Main Main function
102 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
106 \dontinclude msg/icomms/peer2.c
108 \paragraph MSG_ext_icomms_fct_Waitall Waitall function for sender
110 The use of this function permit to send all messages and wait for the completion of all in one time.
112 \skipline Sender function
115 \paragraph MSG_ext_icomms_fct_Waitany Waitany function
117 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
119 \paragraph MSG_ext_icomms_fct_Waitany_sender From a sender
120 We can use this function to wait all sent messages.
121 \dontinclude msg/icomms/peer3.c
122 \skipline Sender function
125 \paragraph MSG_ext_icomms_fct_Waitany_receiver From a receiver
126 We can also wait for the arrival of all messages.
127 \dontinclude msg/icomms/peer3.c
128 \skipline Receiver function
129 \until end_of_receiver
131 \subsubsection MSG_ex_master_slave Basic Master/Slaves
133 Simulation of a master-slave application using a realistic platform
134 and an external description of the deployment.
136 \paragraph MSG_ex_ms_TOC Table of contents:
138 - \ref MSG_ext_ms_preliminary
139 - \ref MSG_ext_ms_master
140 - \ref MSG_ext_ms_slave
141 - \ref MSG_ext_ms_forwarder
142 - \ref MSG_ext_ms_core
143 - \ref MSG_ext_ms_main
144 - \ref MSG_ext_ms_helping
145 - \ref MSG_ext_ms_application
146 - \ref MSG_ext_ms_platform
150 \dontinclude msg/masterslave/masterslave_forwarder.c
153 \paragraph MSG_ext_ms_preliminary Preliminary declarations
159 \paragraph MSG_ext_ms_master Master code
161 This function has to be assigned to a msg_process_t that will behave as
162 the master. It should not be called directly but either given as a
163 parameter to #MSG_process_create() or registered as a public function
164 through #MSG_function_register() and then automatically assigned to a
165 process through #MSG_launch_application().
167 C style arguments (argc/argv) are interpreted as:
168 - the number of tasks to distribute
169 - the computation size of each task
170 - the size of the files associated to each task
171 - a list of host that will accept those tasks.
173 Tasks are dumbly sent in a round-robin style.
177 \paragraph MSG_ext_ms_slave Slave code
179 This function has to be assigned to a #msg_process_t that has to behave
180 as a slave. Just like the master fuction (described in \ref
181 MSG_ext_ms_master), it should not be called directly.
183 This function keeps waiting for tasks and executes them as it receives them.
187 \paragraph MSG_ext_ms_forwarder Forwarder code
189 This function has to be assigned to a #msg_process_t that has to behave
190 as a forwarder. Just like the master function (described in \ref
191 MSG_ext_ms_master), it should not be called directly.
193 C style arguments (argc/argv) are interpreted as a list of host that
194 will accept those tasks.
196 This function keeps waiting for tasks and dispathes them to its slaves.
198 \until end_of_forwarder
200 \paragraph MSG_ext_ms_core Simulation core
202 This function is the core of the simulation and is divided only into 3 parts
203 thanks to MSG_create_environment() and MSG_launch_application().
204 -# Simulation settings : MSG_create_environment() creates a realistic
206 -# Application deployment : create the processes on the right locations with
207 MSG_launch_application()
208 -# The simulation is run with #MSG_main()
211 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
212 - <i>application_file</i>: the name of a file containing a valid surfxml application description
214 \until end_of_test_all
216 \paragraph MSG_ext_ms_main Main() function
218 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
222 \subsubsection MSG_ext_ms_helping Helping files
224 \paragraph MSG_ext_ms_application Example of application file
226 \include msg/masterslave/deployment_masterslave.xml
228 \paragraph MSG_ext_ms_platform Example of platform file
230 \include msg/small_platform.xml
232 \section using_gras Using GRAS
234 Here are some examples on how to use GRAS.
236 You should also check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
241 There is for now rather few examples of GRAS, but it's better than
250 \subsection GRAS_ex_ping Ping-Pong
252 This example implements the very classical ping-pong in GRAS. It
253 involves a client (initiating the ping-pong) and a server (answering to
256 It works the following way:
257 - Both the client and the server register all needed messages
258 - The server registers a callback to the ping message, which sends pong
260 - The client sends the ping message to the server, and waits for the
261 pong message as an answer.
263 This example resides in the <b>examples/gras/ping/ping.c</b> file. Yes, both
264 the code of the client and of the server is placed in the same file.
266 \subsubsection GRAS_ex_ping_toc Table of contents of the ping example
267 - \ref GRAS_ex_ping_common
268 - \ref GRAS_ex_ping_initial
269 - \ref GRAS_ex_ping_register
270 - \ref GRAS_ex_ping_server
271 - \ref GRAS_ex_ping_serdata
272 - \ref GRAS_ex_ping_sercb
273 - \ref GRAS_ex_ping_sermain
274 - \ref GRAS_ex_ping_client
275 - \ref GRAS_ex_ping_climain
279 \dontinclude gras/ping/ping_common.c
281 \subsubsection GRAS_ex_ping_common 1) Common code to the client and the server
283 \paragraph GRAS_ex_ping_initial 1.a) Initial settings
285 Let's first load the module header and declare a logging category (see
286 \ref XBT_log for more info on logging).
291 The module header <tt>ping.h</tt> reads:
293 \dontinclude gras/ping/ping.h
298 \paragraph GRAS_ex_ping_register 1.b) Register the messages
300 This function, called by both the client and the server is in charge of
301 declaring the existing messages to GRAS. Since the payload does not
302 involve any newly created types but only int, this is quite easy.
303 (to exchange more complicated types, see \ref GRAS_dd or
304 \ref GRAS_ex_mmrpc for an example).
306 \dontinclude gras/ping/ping_common.c
307 \skip register_messages
310 [Back to \ref GRAS_ex_ping_toc]
312 \subsubsection GRAS_ex_ping_server 2) Server's code
314 \paragraph GRAS_ex_ping_serdata 2.a) The server's globals
316 In order to ensure the communication between the "main" and the callback
317 of the server, we need to declare some globals. We have to put them in a
318 struct definition so that they can be handled properly in GRAS.
320 \dontinclude gras/ping/ping_server.c
324 \paragraph GRAS_ex_ping_sercb 2.b) The callback to the ping message
326 Here is the callback run when the server receives any ping message (this
327 will be registered later by the server).
329 \skip server_cb_ping_handler
330 \until end_of_server_cb_ping_handler
332 \paragraph GRAS_ex_ping_sermain 2.c) The "main" of the server
334 This is the "main" of the server. You must not write any main()
335 function yourself. Instead, you just have to write a regular function
336 like this one which will act as a main.
341 [Back to \ref GRAS_ex_ping_toc]
343 \subsubsection GRAS_ex_ping_client 3) Client's code
345 \paragraph GRAS_ex_ping_climain 3.a) Client's "main" function
347 This function is quite straightforward, and the inlined comments should
348 be enough to understand it.
350 \dontinclude gras/ping/ping_client.c
354 [Back to \ref GRAS_ex_ping_toc]
356 \subsection GRAS_ex_token Token Ring example
358 This example implements the token ring algorithm. It involves several
359 nodes arranged in a ring (each of them have a left and a right neighbour)
360 and exchanging a "token". This algorithm is one of the solution to ensure
361 the mutual exclusion between distributed processes. There is only one
362 token at any time, so the process in its possession is ensured to be the
363 only one having it. So, if there is an action you want all processes to
364 do alternativly, but you cannot afford to have two processes doing it at
365 the same time, let the process having the token doing it.
367 Actually, there is a lot of different token ring algorithms in the
368 litterature, so this example implements one of them: the simplest one.
369 The ring is static (no new node can join it, and you'll get trouble if
370 one node dies or leaves), and nothing is done for the case in which the
373 - \ref GRAS_ex_stoken_deploy
374 - \ref GRAS_ex_stoken_global
375 - \ref GRAS_ex_stoken_callback
376 - \ref GRAS_ex_stoken_main
378 \subsection GRAS_ex_stoken_deploy 1) Deployment file
380 Here is the deployment file:
381 \include examples/gras/mutual_exclusion/simple_token/simple_token.xml
383 The neighbour of each node is given at startup as command line argument.
384 Moreover, one of the nodes is instructed by a specific argument (the one
385 on Tremblay here) to create the token at the begining of the algorithm.
387 \subsection GRAS_ex_stoken_global 2) Global definition
389 The token is incarned by a specific message, which circulates from node
390 to node (the payload is an integer incremented at each hop). So, the most
391 important part of the code is the message callback, which forwards the
392 message to the next node. That is why we have to store all variable in a
393 global, as explained in the \ref GRAS_globals section.
395 \dontinclude examples/gras/mutual_exclusion/simple_token/simple_token.c
399 \subsection GRAS_ex_stoken_callback 3) The callback
401 Even if this is the core of this algorithm, this function is quite
404 \skip node_cb_stoken_handler
405 \until end_of_node_cb_stoken_handler
407 \subsection GRAS_ex_stoken_main 4) The main function
409 This function is splited in two parts: The first one performs all the
410 needed initialisations (points 1-7) while the end (point 8. below) calls
411 gras_msg_handle() as long as the planned amount of ring loops are not
417 \subsection GRAS_ex_mmrpc A simple RPC for matrix multiplication
419 This example implements a remote matrix multiplication. It involves a client
420 (creating the matrices and sending the multiplications requests) and a server
421 (computing the multiplication on client's behalf).
423 This example also constitutes a more advanced example of data description
424 mechanisms, since the message payload type is a bit more complicated than in
425 other examples such as the ping one (\ref GRAS_ex_ping).
427 It works the following way (not very different from the ping example):
428 - Both the client and the server register all needed messages and datatypes
429 - The server registers a callback to the "request" message, which computes
430 what needs to be and returns the result to the expeditor.
431 - The client creates two matrices, ask for their multiplication and check
434 This example resides in the <b>examples/gras/mmrpc/mmrpc.c</b> file.
436 \subsubsection GRAS_ex_mmrpc_toc Table of contents of the mmrpc example
437 - \ref GRAS_ex_mmrpc_common
438 - \ref GRAS_ex_mmrpc_header
439 - \ref GRAS_ex_mmrpc_dataregister
440 - \ref GRAS_ex_mmrpc_logdef
441 - \ref GRAS_ex_mmrpc_msgregister
442 - \ref GRAS_ex_mmrpc_server
443 - \ref GRAS_ex_mmrpc_serinc
444 - \ref GRAS_ex_mmrpc_sercb
445 - \ref GRAS_ex_mmrpc_sermain
446 - \ref GRAS_ex_mmrpc_client
447 - \ref GRAS_ex_mmrpc_cliinc
448 - \ref GRAS_ex_mmrpc_climain
453 \subsubsection GRAS_ex_mmrpc_common 1) Common code to the client and the server (mmrpc_common.c and mmrpc.h)
456 \paragraph GRAS_ex_mmrpc_header 1.a) Module header (mmrpc.h)
458 This loads the gras header and declare the function's prototypes as well
461 \dontinclude gras/mmrpc/mmrpc.h
466 \paragraph GRAS_ex_mmrpc_dataregister 1.b) Register the data types (mmrpc.h)
468 The messages involved in a matrix of double. This type is automatically
469 known by the GRAS mecanism, using the gras_datadesc_matrix() function of the
472 \paragraph GRAS_ex_mmrpc_logdef 1.c) Logging category definition (mmrpc_common.c)
474 Let's first load the module header and declare a logging category (see
475 \ref XBT_log for more info on logging). This logging category does live
476 in this file (ie the required symbols are defined here and declared as
477 "extern" in any other file using them). That is why we use
478 \ref XBT_LOG_NEW_DEFAULT_CATEGORY here and
479 \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY in mmrpc_client.c and mmrpc_server.c.
481 \dontinclude gras/mmrpc/mmrpc_common.c
485 \paragraph GRAS_ex_mmrpc_msgregister 1.d) Register the messages (mmrpc_common.c)
487 This function, called by both the client and the server is in charge of
488 declaring the existing messages to GRAS.
490 The datatype description builded that way can then be used to build an array datatype or
493 \skip register_messages
496 [Back to \ref GRAS_ex_mmrpc_toc]
498 \subsubsection GRAS_ex_mmrpc_server 2) Server's code (mmrpc_server.c)
500 \paragraph GRAS_ex_mmrpc_serinc 2.a) Server intial settings
502 All module symbols live in the mmrpc_common.c file. We thus have to
503 define \ref XBT_DEFINE_TYPE_EXTERN to the preprocessor so that the
504 \ref XBT_DEFINE_TYPE symbols don't get included here. Likewise, we use
505 \ref XBT_LOG_EXTERNAL_DEFAULT_CATEGORY to get the log category in here.
507 \dontinclude gras/mmrpc/mmrpc_server.c
511 \paragraph GRAS_ex_mmrpc_sercb 2.b) The callback to the mmrpc message
513 Here is the callback run when the server receives any mmrpc message (this
514 will be registered later by the server). Note the way we get the message
515 payload. In the ping example, there was one additional level of pointer
516 indirection (see \ref GRAS_ex_ping_sercb). This is because the payload is
517 an array here (ie a pointer) whereas it is a scalar in the ping example.
519 \skip server_cb_request_handler
520 \until end_of_server_cb_request_handler
522 \paragraph GRAS_ex_mmrpc_sermain 2.c) The "main" of the server
524 This is the "main" of the server. You must not write any main()
525 function yourself. Instead, you just have to write a regular function
526 like this one which will act as a main.
531 [Back to \ref GRAS_ex_mmrpc_toc]
533 \subsubsection GRAS_ex_mmrpc_client 3) Client's code (mmrpc_client.c)
535 \paragraph GRAS_ex_mmrpc_cliinc 2.a) Server intial settings
537 As for the server, some extra love is needed to make sure that automatic
538 datatype parsing and log categories do work even if we are using several
541 \dontinclude gras/mmrpc/mmrpc_client.c
545 \paragraph GRAS_ex_mmrpc_climain 3.b) Client's "main" function
547 This function is quite straightforward, and the inlined comments should
548 be enough to understand it.
550 \dontinclude gras/mmrpc/mmrpc_client.c
554 [Back to \ref GRAS_ex_mmrpc_toc]
556 \subsection GRAS_ex_timer Some timer games
558 This example fools around with the GRAS timers (\ref GRAS_timer). It is
559 mainly a regression test, since it uses almost all timer features.
561 The main program registers a repetititive task and a delayed one, and
562 then loops until the <tt>still_to_do</tt> variables of its globals reach
563 0. The delayed task set it to 5, and the repetititive one decrease it
564 each time. Here is an example of output:
565 \verbatim Initialize GRAS
567 [1108335471] Programming the repetitive_action with a frequency of 1.000000 sec
568 [1108335471] Programming the delayed_action for after 2.000000 sec
569 [1108335471] Have a rest
570 [1108335472] Canceling the delayed_action.
571 [1108335472] Re-programming the delayed_action for after 2.000000 sec
572 [1108335472] Repetitive_action has nothing to do yet
573 [1108335473] Repetitive_action has nothing to do yet
574 [1108335473] delayed_action setting globals->still_to_do to 5
575 [1108335474] repetitive_action decrementing globals->still_to_do. New value: 4
576 [1108335475] repetitive_action decrementing globals->still_to_do. New value: 3
577 [1108335476] repetitive_action decrementing globals->still_to_do. New value: 2
578 [1108335477] repetitive_action decrementing globals->still_to_do. New value: 1
579 [1108335478] repetitive_action decrementing globals->still_to_do. New value: 0
580 Exiting GRAS\endverbatim
583 - \ref GRAS_ex_timer_decl
584 - \ref GRAS_ex_timer_delay
585 - \ref GRAS_ex_timer_repeat
586 - \ref GRAS_ex_timer_main
590 \subsubsection GRAS_ex_timer_decl 1. Declarations and headers
594 \subsubsection GRAS_ex_timer_delay 2. Source code of the delayed action
595 \skip repetitive_action
596 \until end_of_repetitive_action
598 \subsubsection GRAS_ex_timer_repeat 3. Source code of the repetitive action
600 \until end_of_delayed_action
602 \subsubsection GRAS_ex_timer_main 4. Source code of main function
606 \section using_smpi Using SMPI
608 You should check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
611 \section using_MC Using Model Checking
613 You should check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
616 \section using_trace Using Trace
617 Check out the \ref tracing section.
619 You should check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
622 \section using_simdag Using SimDag
624 You should check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.
627 \section using_simix Using SIMIX
629 You should check our online <a href="http://simgrid.gforge.inria.fr/101/index.php"> tutorial section</a> that contains a dedicated tutorial.