2 /** \defgroup MSG_C MSG native
4 \brief Native interface to MSG (\ref MSG_API)
6 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Native interface" --> \endhtmlonly
8 MSG was the first distributed programming environment provided within
9 SimGrid. While almost realistic, it remains quite simple (simplistic?).
10 This describes the native to MSG.
12 \section jMSG_who Who should use this (and who shouldn't)
14 You should use MSG if you want to study some heuristics for a
15 given problem you don't really want to implement. If you want to
16 use the C programming language, your are in the right
17 section. To use the Java programming interface, please refer to
24 \defgroup MSG_LUA lMSG
26 \brief Lua bindings to MSG (\ref MSG_API)
29 DOXYGEN_NAVBAR_LABEL="LUA bindings"
32 MSG was the first distributed programming environment provided within
33 SimGrid. While almost realistic, it remains quite simple (simplistic?).
34 This describes the Lua bindings to this interface.
36 \section lMSG_who Who should use this (and who shouldn't)
38 You should use MSG if you want to study some heuristics for a
39 given problem you don't really want to implement. If you want to
40 use the Lua script language, your are in the right
41 section. To use the C interface, please refer to \ref MSG_C.
47 \section MSG_funct Offered functionnalities
48 - \ref m_process_management
49 - \ref m_datatypes_management
50 - \ref m_host_management
51 - \ref m_task_management
52 - \ref msg_gos_functions
53 - \ref m_channel_management
54 - \ref msg_easier_life
57 \section MSG_examples Examples of MSG
59 - \ref MSG_ex_master_slave
60 - \ref MSG_ex_asynchronous_communications
61 - \ref MSG_ex_master_slave_scrip_lua
64 /** @addtogroup MSG_LUA
66 \section MSG_Lua_funct Lua offered functionnalities in MSG
67 - \ref host_management
68 - \ref tasks_management
69 - \ref environment_management
70 \section Lua_examples Examples of lua MSG
72 - \ref MSG_ex_master_slave_lua
73 - \ref MSG_ex_master_slave_lua_bypass
77 /** @defgroup m_datatypes_management MSG Data Types
79 @brief This section describes the different datatypes provided by MSG.
81 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
83 /** \addtogroup m_process_management
85 /** \addtogroup m_host_management
87 /** \addtogroup m_task_management
89 /** \addtogroup msg_gos_functions
91 /** \addtogroup m_channel_management
93 /** \addtogroup msg_easier_life
95 /** \addtogroup msg_simulation
99 /** \page MSG_ex_asynchronous_communications Asynchronous communication applications
101 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
102 an external description of the deployment.
104 \section MSG_ex_ms_TOC Table of contents:
105 - \ref MSG_ext_icomms_code
106 - \ref MSG_ext_icomms_preliminary
107 - \ref MSG_ext_icomms_Sender
108 - \ref MSG_ext_icomms_Receiver
109 - \ref MSG_ext_icomms_core
110 - \ref MSG_ext_icomms_Main
111 - \ref MSG_ext_icomms_fct_Waitall
112 - \ref MSG_ext_icomms_fct_Waitany
116 \dontinclude msg/icomms/peer.c
118 \section MSG_ext_icomms_code Code of the application
120 \subsection MSG_ext_icomms_preliminary Preliminary declarations
122 \until Sender function
124 \subsection MSG_ext_icomms_Sender Sender function
126 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
127 we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
128 It also available to "make MSG_comm_wait()" which make both of them.
130 C style arguments (argc/argv) are interpreted as:
131 - the number of tasks to distribute
132 - the computation size of each task
133 - the size of the files associated to each task
134 - a list of host that will accept those tasks.
135 - the time to sleep at the beginning of the function
136 - This time defined the process sleep time
137 if time = 0 use of MSG_comm_wait()
138 if time > 0 use of MSG_comm_test()
141 \until Receiver function
143 \subsection MSG_ext_icomms_Receiver Receiver function
145 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
146 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
148 C style arguments (argc/argv) are interpreted as:
149 - the id to use for received the communication.
150 - the time to sleep at the beginning of the function
151 - This time defined the process sleep time
152 if time = 0 use of MSG_comm_wait()
153 if time > 0 use of MSG_comm_test()
157 \subsection MSG_ext_icomms_core Simulation core
159 This function is the core of the simulation and is divided only into 3 parts
160 thanks to MSG_create_environment() and MSG_launch_application().
161 -# Simulation settings : MSG_create_environment() creates a realistic
163 -# Application deployment : create the agents on the right locations with
164 MSG_launch_application()
165 -# The simulation is run with #MSG_main()
168 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
169 - <i>application_file</i>: the name of a file containing a valid surfxml application description
173 \subsection MSG_ext_icomms_Main Main function
175 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
179 \dontinclude msg/icomms/peer2.c
181 \section MSG_ext_icomms_fct_Waitall Waitall function for sender
183 The use of this function permit to send all messages and wait for the completion of all in one time.
185 \skipline Sender function
188 \section MSG_ext_icomms_fct_Waitany Waitany function
190 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
192 \subsection MSG_ext_icomms_fct_Waitany_sender From a sender
193 We can use this function to wait all sended messages.
194 \dontinclude msg/icomms/peer3.c
195 \skipline Sender function
198 \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver
199 We can also wait for the receiving of all messages.
200 \dontinclude msg/icomms/peer3.c
201 \skipline Receiver function
202 \until end_of_receiver
206 /** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
208 Simulation of a master-slave application using a realistic platform and
209 an external description of the deployment via a lua script.
211 \section MSG_ex_msl_TOC Table of contents:
213 - \ref MSG_ext_msl_code
214 - \ref MSG_ext_msl_preliminary
215 - \ref MSG_ext_msl_master
216 - \ref MSG_ext_msl_slave
217 - \ref MSG_ext_msl_core
218 - \ref MSG_ext_msl_main
219 - \ref MSG_ext_msl_helping
220 - \ref MSG_ext_msl_platform
224 \dontinclude msg/masterslave/masterslave_console.c
226 \section MSG_ext_msl_code Code of the application
228 \subsection MSG_ext_msl_preliminary Preliminary declarations
233 \subsection MSG_ext_msl_master Master code
235 This function has to be assigned to a m_process_t that will behave as the master.
236 It should not be called directly but either given as a parameter to
237 #MSG_process_create() or registered as a public function through
238 #MSG_function_register() and then automatically assigned to a process through
239 #MSG_load_platform_script().
241 C style arguments (argc/argv) are interpreted as:
242 - the number of tasks to distribute
243 - the computation size of each task
244 - the size of the files associated to each task
245 - number of hosts that will accept those tasks.
247 Tasks are dumbly sent in a round-robin style.
250 \subsection MSG_ext_msl_slave Slave code
252 This function has to be assigned to a #m_process_t that has to behave as a slave.
253 Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
255 This function keeps waiting for tasks and executes them as it receives them.
259 \subsection MSG_ext_msl_core Simulation core
261 This function is the core of the simulation and is divided now only into 2 parts
262 thanks to MSG_load_platform_script().
263 -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic
264 environment and the agents on the right locations, described in the lua script file (see example below).
265 Note that the use of this function require a lua installation on your machine.
266 -# The simulation is run with #MSG_main().
269 - <i>platform_script_file</i>: the name of the script file containing a valid platform and application description, using bound lua methods to bypass the surfxml parser.
271 \until end_of_test_all
273 \subsection MSG_ext_msl_main Main() function
275 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
279 \section MSG_ext_msl_helping Helping files
281 \subsection MSG_ext_msl_platform Example of platform script file
283 \include msg/masterslave/platform_script.lua
288 /** \page MSG_ex_master_slave Master/slave application
290 Simulation of a master-slave application using a realistic platform and
291 an external description of the deployment.
293 \section MSG_ex_ms_TOC Table of contents:
295 - \ref MSG_ext_ms_code
296 - \ref MSG_ext_ms_preliminary
297 - \ref MSG_ext_ms_master
298 - \ref MSG_ext_ms_slave
299 - \ref MSG_ext_ms_forwarder
300 - \ref MSG_ext_ms_core
301 - \ref MSG_ext_ms_main
302 - \ref MSG_ext_ms_helping
303 - \ref MSG_ext_ms_application
304 - \ref MSG_ext_ms_platform
308 \dontinclude msg/masterslave/masterslave_forwarder.c
310 \section MSG_ext_ms_code Code of the application
312 \subsection MSG_ext_ms_preliminary Preliminary declarations
318 \subsection MSG_ext_ms_master Master code
320 This function has to be assigned to a m_process_t that will behave as the master.
321 It should not be called directly but either given as a parameter to
322 #MSG_process_create() or registered as a public function through
323 #MSG_function_register() and then automatically assigned to a process through
324 #MSG_launch_application().
326 C style arguments (argc/argv) are interpreted as:
327 - the number of tasks to distribute
328 - the computation size of each task
329 - the size of the files associated to each task
330 - a list of host that will accept those tasks.
332 Tasks are dumbly sent in a round-robin style.
336 \subsection MSG_ext_ms_slave Slave code
338 This function has to be assigned to a #m_process_t that has to behave as a slave.
339 Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
341 This function keeps waiting for tasks and executes them as it receives them.
345 \subsection MSG_ext_ms_forwarder Forwarder code
347 This function has to be assigned to a #m_process_t that has to behave as a forwarder.
348 Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly.
350 C style arguments (argc/argv) are interpreted as a list of host
351 that will accept those tasks.
353 This function keeps waiting for tasks and dispathes them to its slaves.
355 \until end_of_forwarder
357 \subsection MSG_ext_ms_core Simulation core
359 This function is the core of the simulation and is divided only into 3 parts
360 thanks to MSG_create_environment() and MSG_launch_application().
361 -# Simulation settings : MSG_create_environment() creates a realistic
363 -# Application deployment : create the agents on the right locations with
364 MSG_launch_application()
365 -# The simulation is run with #MSG_main()
368 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
369 - <i>application_file</i>: the name of a file containing a valid surfxml application description
371 \until end_of_test_all
373 \subsection MSG_ext_ms_main Main() function
375 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
379 \section MSG_ext_ms_helping Helping files
381 \subsection MSG_ext_ms_application Example of application file
383 \include msg/masterslave/deployment_masterslave.xml
385 \subsection MSG_ext_ms_platform Example of platform file
387 \include msg/small_platform.xml
391 /** \page MSG_ex_master_slave_lua Master/slave Lua application
393 Simulation of a master-slave application using lua bindings
394 - \ref MSG_ext_ms_code_lua
395 - \ref MSG_ext_ms_master_lua
396 - \ref MSG_ext_ms_slave_lua
397 - \ref MSG_ext_ms_core_lua
399 - \ref MSG_ext_ms_helping
400 - \ref MSG_ext_ms_application
401 - \ref MSG_ext_ms_platform
404 \dontinclude lua/masterslave/master_slave.lua
406 \section MSG_ext_ms_code_lua Code of the application
408 \subsection MSG_ext_ms_master_lua Master code
410 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.
412 Lua style arguments (...) in for the master are interpreted as:
413 - the number of tasks to distribute
414 - the computation size of each task
415 - the size of the files associated to each task
416 - a list of host that will accept those tasks.
418 Tasks are dumbly sent in a round-robin style.
423 \subsection MSG_ext_ms_slave_lua Slave code
425 This function has to be assigned to a #m_process_t that has to behave as a slave.
426 This function keeps waiting for tasks and executes them as it receives them.
429 \subsection MSG_ext_ms_core_lua Simulation core
431 in this section the core of the simulation which start by including the simgrid lib for bindings
432 : <i>require "simgrid" </i>
434 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
436 -# Application deployment : create the agents on the right locations with
437 <i>simgrid.application</i>
438 -# The simulation is run with <i>simgrid.run</i>
441 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
442 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
444 \until simgrid.clean()
448 /** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
450 Simulation of a master-slave application using lua bindings, Bypassing the XML parser
451 - \ref MSG_ext_ms_code_lua
452 - \ref MSG_ext_ms_master_lua
453 - \ref MSG_ext_ms_slave_lua
454 - \ref MSG_ext_ms_core_lua
457 \dontinclude lua/console/master_slave_bypass.lua
459 \section MSG_ext_ms_code_lua Code of the application
461 \subsection MSG_ext_ms_master_lua Master code
463 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.
465 Lua style arguments (...) in for the master are interpreted as:
466 - the number of tasks to distribute
467 - the computation size of each task
468 - the size of the files associated to each task
469 - a list of host that will accept those tasks.
471 Tasks are dumbly sent in a round-robin style.
476 \subsection MSG_ext_ms_slave_lua Slave code
478 This function has to be assigned to a #m_process_t that has to behave as a slave.
479 This function keeps waiting for tasks and executes them as it receives them.
482 \subsection MSG_ext_ms_core_lua Simulation core
484 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.
485 : <i>require "simgrid" </i>
487 -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
488 -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
489 -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
490 -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
492 we can also bypass the XML deployment file, and associate functions for each of defined hosts.
493 - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
494 - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
496 \until simgrid.clean()