1 /** \addtogroup MSG_API
3 MSG was the first distributed programming environment provided within
4 SimGrid. While almost realistic, it remains quite simple (simplistic?).
5 This describes the native to MSG.
7 \section jMSG_who Who should use this (and who shouldn't)
9 You should use MSG if you want to study some heuristics for a
10 given problem you don't really want to implement. If you want to
11 use the C programming language, your are in the right
12 section. To use the Java or Ruby programming interfaces, please refer to
13 the documentation provided in the relevant packages.
15 \section MSG_funct Offered functionnalities
17 - \ref m_process_management
18 - \ref m_host_management
19 - \ref m_task_management
20 - \ref msg_file_management
23 - \ref msg_trace_driven
24 - \ref msg_deprecated_functions
27 Also make sure to visit the page @ref MSG_examples.
31 @defgroup MSG_examples MSG Examples
34 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Examples" --> @endhtmlonly
36 MSG comes with an extensive set of examples. It is sometimes difficult
37 to find the one you need. This list aims at helping you finding the
38 example from which you can learn what you want to.
40 @section MSG_ex_basics Basic examples and features
45 @defgroup msg_simulation Main MSG simulation Functions
47 @brief Describes how to setup and control your simulation.
49 The basic workflow is the following (check the \ref MSG_examples for
52 -# Initialize the library with #MSG_global_init
53 -# Create a platform (usually by parsing a file with
54 #MSG_create_environment)
55 -# Register the functions that your processes are supposed to run with
56 #MSG_function_register (and maybe #MSG_function_register_default)
57 -# Launch your processes from a deployment file with #MSG_launch_application
58 -# Run the simulation with #MSG_main
59 -# Cleanup the library with #MSG_clean before ending your program
62 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
65 /** @defgroup m_process_management Process Management Functions
67 * @brief This section describes the process structure of MSG
68 * (#m_process_t) and the functions for managing it.
71 /** @defgroup m_host_management Host Management Functions
73 * @brief This section describes the host structure of MSG
76 /** @defgroup m_task_management Task Management Functions
78 * @brief This section describes the task structure of MSG
79 * (#m_task_t) and the functions for managing it. See
80 * \ref msg_task_usage to see how to put the tasks in action.
82 * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
85 /** @defgroup msg_task_usage Task Actions
87 * @brief This section describes the functions that can be used
88 * by a process to execute, communicate or otherwise handle some task.
91 /** @defgroup msg_VMs VMs
93 * @brief This section describes the interface created to mimick IaaS clouds.
95 * With it, you can create virtual machines to put your processes
96 * into, and interact directly with the VMs to manage groups of
99 * This interface is highly experimental at this point. Testing is
100 * welcomed, but do not expect too much of it right now. Even the
101 * interfaces may be changed in future releases of SimGrid (although
102 * things are expected to stabilize nicely before SimGrid v3.8).
103 * There is no guaranty on the rest of SimGrid, and there is less
104 * than that on this part.
108 /** @defgroup msg_file_management File Management Functions
110 * @brief This section describes the file structure of MSG
111 * (#msg_file_t) and the functions for managing it. It
112 * is based on POSIX functions.
117 @defgroup msg_trace_driven Trace-driven simulations
119 @brief This section describes the functions allowing to build trace-driven simulations.
121 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
123 This is very handy when you want to test an algorithm or protocol that
124 does nothing unless it receives some events from outside. For example,
125 a P2P protocol reacts to requests from the user, but does nothing if
126 there is no such event.
128 In such situations, SimGrid allows to write your protocol in your C
129 file, and the events to react to in a separate text file. Declare a
130 function handling each of the events that you want to accept in your
131 trace files, register them using #MSG_action_register in your main,
132 and then use #MSG_action_trace_run to launch the simulation. You can
133 either have one trace file containing all your events, or a file per
136 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
143 @defgroup MSG_LUA Lua bindings
145 @brief Lua bindings to MSG (\ref MSG_API)
147 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
149 This is the lua bindings of the \ref MSG_API interface.
151 \section lMSG_who Who should use this (and who shouldn't)
153 If you want to use MSG to study your algorithm, but you don't want to
154 use the C language (using \ref MSG_API), then you should use some
155 bindings such as this one. The advantage of the lua bindings is that
156 they are distributed directly with the main archive (in contrary to
157 Java and Ruby bindings, for example, that are distributed separately).
158 Another advantage of lua is that there is almost no performance loss
159 with regard to the C version (at least there shouln't be any -- it is
160 still to be precisely assessed).
162 \section MSG_Lua_funct Lua offered functionnalities in MSG
164 Almost all important features of the MSG interface are available from
165 the lua bindings. Unfortunately, since doxygen does not support the
166 lua modules implemented directly in C as we are using, there is no
167 ready to use reference documentation for this module. Even more than
168 for the other modules, you will have to dig into the source code of
169 the examples to learn how to use it.
171 \section Lua_examples Examples of lua MSG
173 - \ref MSG_ex_master_slave_lua
174 - \ref MSG_ex_master_slave_lua_bypass
175 - Also, the lua version of the Chord example (in the source tree)
176 is a working non-trivial example of use of the lua bindings
180 @defgroup msg_deprecated_functions MSG Deprecated
182 @brief This section describes the deprecated functions. PLEASE STOP USING THEM.
184 We don't remove them because the ability to run old scientific
185 code is something important to us. But these functionalities are
186 not actively supported anymore.
188 To access these functions, you should define the relevant option
189 at configuration time in ccmake.
194 @defgroup MSG_ex_asynchronous_communications Asynchronous communications
195 @ingroup MSG_examples
197 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
198 an external description of the deployment.
200 \section MSG_ex_ms_TOC Table of contents:
201 - \ref MSG_ext_icomms_code
202 - \ref MSG_ext_icomms_preliminary
203 - \ref MSG_ext_icomms_Sender
204 - \ref MSG_ext_icomms_Receiver
205 - \ref MSG_ext_icomms_core
206 - \ref MSG_ext_icomms_Main
207 - \ref MSG_ext_icomms_fct_Waitall
208 - \ref MSG_ext_icomms_fct_Waitany
212 \don'tinclude msg/icomms/peer.c
214 \section MSG_ext_icomms_code Code of the application
216 \subsection MSG_ext_icomms_preliminary Preliminary declarations
218 \until Sender function
220 \subsection MSG_ext_icomms_Sender Sender function
222 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
223 we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
224 It also available to "make MSG_comm_wait()" which make both of them.
226 C style arguments (argc/argv) are interpreted as:
227 - the number of tasks to distribute
228 - the computation size of each task
229 - the size of the files associated to each task
230 - a list of host that will accept those tasks.
231 - the time to sleep at the beginning of the function
232 - This time defined the process sleep time
233 if time = 0 use of MSG_comm_wait()
234 if time > 0 use of MSG_comm_test()
237 \until Receiver function
239 \subsection MSG_ext_icomms_Receiver Receiver function
241 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
242 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
244 C style arguments (argc/argv) are interpreted as:
245 - the id to use for received the communication.
246 - the time to sleep at the beginning of the function
247 - This time defined the process sleep time
248 if time = 0 use of MSG_comm_wait()
249 if time > 0 use of MSG_comm_test()
253 \subsection MSG_ext_icomms_core Simulation core
255 This function is the core of the simulation and is divided only into 3 parts
256 thanks to MSG_create_environment() and MSG_launch_application().
257 -# Simulation settings : MSG_create_environment() creates a realistic
259 -# Application deployment : create the processes on the right locations with
260 MSG_launch_application()
261 -# The simulation is run with #MSG_main()
264 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
265 - <i>application_file</i>: the name of a file containing a valid surfxml application description
269 \subsection MSG_ext_icomms_Main Main function
271 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
275 \don'tinclude msg/icomms/peer2.c
277 \section MSG_ext_icomms_fct_Waitall Waitall function for sender
279 The use of this function permit to send all messages and wait for the completion of all in one time.
281 \skipline Sender function
284 \section MSG_ext_icomms_fct_Waitany Waitany function
286 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
288 \subsection MSG_ext_icomms_fct_Waitany_sender From a sender
289 We can use this function to wait all sent messages.
290 \don'tinclude msg/icomms/peer3.c
291 \skipline Sender function
294 \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver
295 We can also wait for the arrival of all messages.
296 \don'tinclude msg/icomms/peer3.c
297 \skipline Receiver function
298 \until end_of_receiver
303 @defgroup MSG_ex_master_slave Basic Master/Slaves
304 @ingroup MSG_examples
306 Simulation of a master-slave application using a realistic platform
307 and an external description of the deployment.
309 \section MSG_ex_ms_TOC Table of contents:
311 - \ref MSG_ext_ms_code
312 - \ref MSG_ext_ms_preliminary
313 - \ref MSG_ext_ms_master
314 - \ref MSG_ext_ms_slave
315 - \ref MSG_ext_ms_forwarder
316 - \ref MSG_ext_ms_core
317 - \ref MSG_ext_ms_main
318 - \ref MSG_ext_ms_helping
319 - \ref MSG_ext_ms_application
320 - \ref MSG_ext_ms_platform
324 \don'tinclude msg/masterslave/masterslave_forwarder.c
326 \section MSG_ext_ms_code Code of the application
328 \subsection MSG_ext_ms_preliminary Preliminary declarations
334 \subsection MSG_ext_ms_master Master code
336 This function has to be assigned to a m_process_t that will behave as
337 the master. It should not be called directly but either given as a
338 parameter to #MSG_process_create() or registered as a public function
339 through #MSG_function_register() and then automatically assigned to a
340 process through #MSG_launch_application().
342 C style arguments (argc/argv) are interpreted as:
343 - the number of tasks to distribute
344 - the computation size of each task
345 - the size of the files associated to each task
346 - a list of host that will accept those tasks.
348 Tasks are dumbly sent in a round-robin style.
352 \subsection MSG_ext_ms_slave Slave code
354 This function has to be assigned to a #m_process_t that has to behave
355 as a slave. Just like the master fuction (described in \ref
356 MSG_ext_ms_master), it should not be called directly.
358 This function keeps waiting for tasks and executes them as it receives them.
362 \subsection MSG_ext_ms_forwarder Forwarder code
364 This function has to be assigned to a #m_process_t that has to behave
365 as a forwarder. Just like the master function (described in \ref
366 MSG_ext_ms_master), it should not be called directly.
368 C style arguments (argc/argv) are interpreted as a list of host that
369 will accept those tasks.
371 This function keeps waiting for tasks and dispathes them to its slaves.
373 \until end_of_forwarder
375 \subsection MSG_ext_ms_core Simulation core
377 This function is the core of the simulation and is divided only into 3 parts
378 thanks to MSG_create_environment() and MSG_launch_application().
379 -# Simulation settings : MSG_create_environment() creates a realistic
381 -# Application deployment : create the processes on the right locations with
382 MSG_launch_application()
383 -# The simulation is run with #MSG_main()
386 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
387 - <i>application_file</i>: the name of a file containing a valid surfxml application description
389 \until end_of_test_all
391 \subsection MSG_ext_ms_main Main() function
393 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
397 \section MSG_ext_ms_helping Helping files
399 \subsection MSG_ext_ms_application Example of application file
401 \include msg/masterslave/deployment_masterslave.xml
403 \subsection MSG_ext_ms_platform Example of platform file
405 \include msg/small_platform.xml
409 /** \page MSG_ex_master_slave_lua Master/slave Lua application
411 Simulation of a master-slave application using lua bindings
412 - \ref MSG_ext_ms_code_lua
413 - \ref MSG_ext_ms_master_lua
414 - \ref MSG_ext_ms_slave_lua
415 - \ref MSG_ext_ms_core_lua
417 - \ref MSG_ext_ms_helping
418 - \ref MSG_ext_ms_application
419 - \ref MSG_ext_ms_platform
422 \don'tinclude lua/masterslave/master_slave.lua
424 \section MSG_ext_ms_code_lua Code of the application
426 \subsection MSG_ext_ms_master_lua Master code
428 as described ine the C native master/Slave exmaple , this function has to be assigned to a m_process_t that will behave as the master.
430 Lua style arguments (...) in for the master are interpreted as:
431 - the number of tasks to distribute
432 - the computation size of each task
433 - the size of the files associated to each task
434 - a list of host that will accept those tasks.
436 Tasks are dumbly sent in a round-robin style.
441 \subsection MSG_ext_ms_slave_lua Slave code
443 This function has to be assigned to a #m_process_t that has to behave as a slave.
444 This function keeps waiting for tasks and executes them as it receives them.
447 \subsection MSG_ext_ms_core_lua Simulation core
449 in this section the core of the simulation which start by including the simgrid lib for bindings
450 : <i>require "simgrid" </i>
452 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
454 -# Application deployment : create the processes on the right locations with
455 <i>simgrid.application</i>
456 -# The simulation is run with <i>simgrid.run</i>
459 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
460 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
462 \until simgrid.clean()
466 /** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
468 Simulation of a master-slave application using lua bindings, Bypassing the XML parser
469 - \ref MSG_ext_ms_code_lua
470 - \ref MSG_ext_ms_master_lua
471 - \ref MSG_ext_ms_slave_lua
472 - \ref MSG_ext_ms_core_lua
475 \don'tinclude lua/console/master_slave_bypass.lua
477 \section MSG_ext_ms_code_lua Code of the application
479 \subsection MSG_ext_ms_master_lua Master code
481 as described ine the C native master/Slave exmaple , this function has to be assigned to a m_process_t that will behave as the master.
483 Lua style arguments (...) in for the master are interpreted as:
484 - the number of tasks to distribute
485 - the computation size of each task
486 - the size of the files associated to each task
487 - a list of host that will accept those tasks.
489 Tasks are dumbly sent in a round-robin style.
494 \subsection MSG_ext_ms_slave_lua Slave code
496 This function has to be assigned to a #m_process_t that has to behave as a slave.
497 This function keeps waiting for tasks and executes them as it receives them.
500 \subsection MSG_ext_ms_core_lua Simulation core
502 in this section the core of the simulation which start by including the simgrid lib for bindings, then create the resources we need to set up our environment bypassing the XML parser.
503 : <i>require "simgrid" </i>
505 -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
506 -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
507 -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
508 -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
510 we can also bypass the XML deployment file, and associate functions for each of defined hosts.
511 - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
512 - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
514 \until simgrid.clean()