1 /** \defgroup MSG_JAVA jMSG
3 \brief Java bindings to MSG (\ref MSG_API)
6 DOXYGEN_NAVBAR_LABEL="JAVA bindings"
7 DOXYGEN_NAVBAR_CHILD "Simulation functions"=classsimgrid_1_1msg_1_1Msg.html
8 DOXYGEN_NAVBAR_CHILD "Host"=classsimgrid_1_1msg_1_1Host.html
9 DOXYGEN_NAVBAR_CHILD "Process"=classsimgrid_1_1msg_1_1Process.html
10 DOXYGEN_NAVBAR_CHILD "Task"=classsimgrid_1_1msg_1_1Task.html
11 DOXYGEN_NAVBAR_CHILD "MsgException"=classsimgrid_1_1msg_1_1MsgException.html
14 MSG was the first distributed programming environment provided within
15 SimGrid. While almost realistic, it remains quite simple (simplistic?).
16 This describes the Java bindings to this interface.
18 \section jMSG_who Who should use this (and who shouldn't)
20 You should use MSG if you want to study some heuristics for a
21 given problem you don't really want to implement. If you want to
22 use the Java programming language, your are in the right
23 section. To use the C interface, please refer to \ref MSG_C.
26 /** \defgroup MSG_C MSG native
28 \brief Native interface to MSG (\ref MSG_API)
30 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Native interface" --> \endhtmlonly
32 MSG was the first distributed programming environment provided within
33 SimGrid. While almost realistic, it remains quite simple (simplistic?).
34 This describes the native to MSG.
36 \section jMSG_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 C programming language, your are in the right
41 section. To use the Java programming interface, please refer to
48 \defgroup MSG_LUA lMSG
50 \brief Lua bindings to MSG (\ref MSG_API)
53 DOXYGEN_NAVBAR_LABEL="LUA bindings"
56 MSG was the first distributed programming environment provided within
57 SimGrid. While almost realistic, it remains quite simple (simplistic?).
58 This describes the Lua bindings to this interface.
60 \section lMSG_who Who should use this (and who shouldn't)
62 You should use MSG if you want to study some heuristics for a
63 given problem you don't really want to implement. If you want to
64 use the Lua script language, your are in the right
65 section. To use the C interface, please refer to \ref MSG_C.
71 \section MSG_funct Offered functionnalities
72 - \ref m_process_management
73 - \ref m_datatypes_management
74 - \ref m_host_management
75 - \ref m_task_management
76 - \ref msg_gos_functions
77 - \ref m_channel_management
78 - \ref msg_easier_life
81 \section MSG_examples Examples of MSG
83 - \ref MSG_ex_master_slave
84 - \ref MSG_ex_asynchronous_communications
85 - \ref MSG_ex_master_slave_scrip_lua
88 /** @addtogroup MSG_LUA
90 \section MSG_Lua_funct Lua offered functionnalities in MSG
91 - \ref host_management
92 - \ref tasks_management
93 - \ref environment_management
94 \section Lua_examples Examples of lua MSG
96 - \ref MSG_ex_master_slave_lua
97 - \ref MSG_ex_master_slave_lua_bypass
101 /** @defgroup m_datatypes_management MSG Data Types
103 @brief This section describes the different datatypes provided by MSG.
105 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
107 /** \addtogroup m_process_management
109 /** \addtogroup m_host_management
111 /** \addtogroup m_task_management
113 /** \addtogroup msg_gos_functions
115 /** \addtogroup m_channel_management
117 /** \addtogroup msg_easier_life
119 /** \addtogroup msg_simulation
123 /** \page MSG_ex_asynchronous_communications Asynchronous communication applications
125 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
126 an external description of the deployment.
128 \section MSG_ex_ms_TOC Table of contents:
129 - \ref MSG_ext_icomms_code
130 - \ref MSG_ext_icomms_preliminary
131 - \ref MSG_ext_icomms_Sender
132 - \ref MSG_ext_icomms_Receiver
133 - \ref MSG_ext_icomms_core
134 - \ref MSG_ext_icomms_Main
135 - \ref MSG_ext_icomms_fct_Waitall
136 - \ref MSG_ext_icomms_fct_Waitany
140 \dontinclude msg/icomms/peer.c
142 \section MSG_ext_icomms_code Code of the application
144 \subsection MSG_ext_icomms_preliminary Preliminary declarations
146 \until Sender function
148 \subsection MSG_ext_icomms_Sender Sender function
150 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
151 we have to make "MSG_comm_test()" to know if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
152 It also available to "make MSG_comm_wait()" which make both of them.
154 C style arguments (argc/argv) are interpreted as:
155 - the number of tasks to distribute
156 - the computation size of each task
157 - the size of the files associated to each task
158 - a list of host that will accept those tasks.
159 - the time to sleep at the beginning of the function
160 - This time defined the process sleep time
161 if time = 0 use of MSG_comm_wait()
162 if time > 0 use of MSG_comm_test()
165 \until Receiver function
167 \subsection MSG_ext_icomms_Receiver Receiver function
169 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
170 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
172 C style arguments (argc/argv) are interpreted as:
173 - the id to use for received the communication.
174 - the time to sleep at the beginning of the function
175 - This time defined the process sleep time
176 if time = 0 use of MSG_comm_wait()
177 if time > 0 use of MSG_comm_test()
181 \subsection MSG_ext_icomms_core Simulation core
183 This function is the core of the simulation and is divided only into 3 parts
184 thanks to MSG_create_environment() and MSG_launch_application().
185 -# Simulation settings : MSG_create_environment() creates a realistic
187 -# Application deployment : create the agents on the right locations with
188 MSG_launch_application()
189 -# The simulation is run with #MSG_main()
192 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
193 - <i>application_file</i>: the name of a file containing a valid surfxml application description
197 \subsection MSG_ext_icomms_Main Main function
199 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
203 \dontinclude msg/icomms/peer2.c
205 \section MSG_ext_icomms_fct_Waitall Waitall function for sender
207 The use of this function permit to send all messages and wait for the completion of all in one time.
209 \skipline Sender function
212 \section MSG_ext_icomms_fct_Waitany Waitany function
214 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
216 \subsection MSG_ext_icomms_fct_Waitany_sender From a sender
217 We can use this function to wait all sended messages.
218 \dontinclude msg/icomms/peer3.c
219 \skipline Sender function
222 \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver
223 We can also wait for the receiving of all messages.
224 \dontinclude msg/icomms/peer3.c
225 \skipline Receiver function
226 \until end_of_receiver
230 /** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
232 Simulation of a master-slave application using a realistic platform and
233 an external description of the deployment via a lua script.
235 \section MSG_ex_msl_TOC Table of contents:
237 - \ref MSG_ext_msl_code
238 - \ref MSG_ext_msl_preliminary
239 - \ref MSG_ext_msl_master
240 - \ref MSG_ext_msl_slave
241 - \ref MSG_ext_msl_core
242 - \ref MSG_ext_msl_main
243 - \ref MSG_ext_msl_helping
244 - \ref MSG_ext_msl_platform
248 \dontinclude msg/masterslave/masterslave_console.c
250 \section MSG_ext_msl_code Code of the application
252 \subsection MSG_ext_msl_preliminary Preliminary declarations
257 \subsection MSG_ext_msl_master Master code
259 This function has to be assigned to a m_process_t that will behave as the master.
260 It should not be called directly but either given as a parameter to
261 #MSG_process_create() or registered as a public function through
262 #MSG_function_register() and then automatically assigned to a process through
263 #MSG_load_platform_script().
265 C style arguments (argc/argv) are interpreted as:
266 - the number of tasks to distribute
267 - the computation size of each task
268 - the size of the files associated to each task
269 - number of hosts that will accept those tasks.
271 Tasks are dumbly sent in a round-robin style.
274 \subsection MSG_ext_msl_slave Slave code
276 This function has to be assigned to a #m_process_t that has to behave as a slave.
277 Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
279 This function keeps waiting for tasks and executes them as it receives them.
283 \subsection MSG_ext_msl_core Simulation core
285 This function is the core of the simulation and is divided now only into 2 parts
286 thanks to MSG_load_platform_script().
287 -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic
288 environment and the agents on the right locations, described in the lua script file (see example below).
289 Note that the use of this function require a lua installation on your machine.
290 -# The simulation is run with #MSG_main().
293 - <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.
295 \until end_of_test_all
297 \subsection MSG_ext_msl_main Main() function
299 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
303 \section MSG_ext_msl_helping Helping files
305 \subsection MSG_ext_msl_platform Example of platform script file
307 \include msg/masterslave/platform_script.lua
312 /** \page MSG_ex_master_slave Master/slave application
314 Simulation of a master-slave application using a realistic platform and
315 an external description of the deployment.
317 \section MSG_ex_ms_TOC Table of contents:
319 - \ref MSG_ext_ms_code
320 - \ref MSG_ext_ms_preliminary
321 - \ref MSG_ext_ms_master
322 - \ref MSG_ext_ms_slave
323 - \ref MSG_ext_ms_forwarder
324 - \ref MSG_ext_ms_core
325 - \ref MSG_ext_ms_main
326 - \ref MSG_ext_ms_helping
327 - \ref MSG_ext_ms_application
328 - \ref MSG_ext_ms_platform
332 \dontinclude msg/masterslave/masterslave_forwarder.c
334 \section MSG_ext_ms_code Code of the application
336 \subsection MSG_ext_ms_preliminary Preliminary declarations
342 \subsection MSG_ext_ms_master Master code
344 This function has to be assigned to a m_process_t that will behave as the master.
345 It should not be called directly but either given as a parameter to
346 #MSG_process_create() or registered as a public function through
347 #MSG_function_register() and then automatically assigned to a process through
348 #MSG_launch_application().
350 C style arguments (argc/argv) are interpreted as:
351 - the number of tasks to distribute
352 - the computation size of each task
353 - the size of the files associated to each task
354 - a list of host that will accept those tasks.
356 Tasks are dumbly sent in a round-robin style.
360 \subsection MSG_ext_ms_slave Slave code
362 This function has to be assigned to a #m_process_t that has to behave as a slave.
363 Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
365 This function keeps waiting for tasks and executes them as it receives them.
369 \subsection MSG_ext_ms_forwarder Forwarder code
371 This function has to be assigned to a #m_process_t that has to behave as a forwarder.
372 Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly.
374 C style arguments (argc/argv) are interpreted as a list of host
375 that will accept those tasks.
377 This function keeps waiting for tasks and dispathes them to its slaves.
379 \until end_of_forwarder
381 \subsection MSG_ext_ms_core Simulation core
383 This function is the core of the simulation and is divided only into 3 parts
384 thanks to MSG_create_environment() and MSG_launch_application().
385 -# Simulation settings : MSG_create_environment() creates a realistic
387 -# Application deployment : create the agents on the right locations with
388 MSG_launch_application()
389 -# The simulation is run with #MSG_main()
392 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
393 - <i>application_file</i>: the name of a file containing a valid surfxml application description
395 \until end_of_test_all
397 \subsection MSG_ext_ms_main Main() function
399 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
403 \section MSG_ext_ms_helping Helping files
405 \subsection MSG_ext_ms_application Example of application file
407 \include msg/masterslave/deployment_masterslave.xml
409 \subsection MSG_ext_ms_platform Example of platform file
411 \include msg/small_platform.xml
415 /** \page MSG_ex_master_slave_lua Master/slave Lua application
417 Simulation of a master-slave application using lua bindings
418 - \ref MSG_ext_ms_code_lua
419 - \ref MSG_ext_ms_master_lua
420 - \ref MSG_ext_ms_slave_lua
421 - \ref MSG_ext_ms_core_lua
423 - \ref MSG_ext_ms_helping
424 - \ref MSG_ext_ms_application
425 - \ref MSG_ext_ms_platform
428 \dontinclude lua/master_slave.lua
430 \section MSG_ext_ms_code_lua Code of the application
432 \subsection MSG_ext_ms_master_lua Master code
434 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.
436 Lua style arguments (...) in for the master are interpreted as:
437 - the number of tasks to distribute
438 - the computation size of each task
439 - the size of the files associated to each task
440 - a list of host that will accept those tasks.
442 Tasks are dumbly sent in a round-robin style.
447 \subsection MSG_ext_ms_slave_lua Slave code
449 This function has to be assigned to a #m_process_t that has to behave as a slave.
450 This function keeps waiting for tasks and executes them as it receives them.
453 \subsection MSG_ext_ms_core_lua Simulation core
455 in this section the core of the simulation which start by including the simgrid lib for bindings
456 : <i>require "simgrid" </i>
458 -# Simulation settings : <i>simgrid.platform</i> creates a realistic
460 -# Application deployment : create the agents on the right locations with
461 <i>simgrid.application</i>
462 -# The simulation is run with <i>simgrid.run</i>
465 - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
466 - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
468 \until simgrid.clean()
472 /** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
474 Simulation of a master-slave application using lua bindings, Bypassing the XML parser
475 - \ref MSG_ext_ms_code_lua
476 - \ref MSG_ext_ms_master_lua
477 - \ref MSG_ext_ms_slave_lua
478 - \ref MSG_ext_ms_core_lua
481 \dontinclude lua/master_slave_bypass.lua
483 \section MSG_ext_ms_code_lua Code of the application
485 \subsection MSG_ext_ms_master_lua Master code
487 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.
489 Lua style arguments (...) in for the master are interpreted as:
490 - the number of tasks to distribute
491 - the computation size of each task
492 - the size of the files associated to each task
493 - a list of host that will accept those tasks.
495 Tasks are dumbly sent in a round-robin style.
500 \subsection MSG_ext_ms_slave_lua Slave code
502 This function has to be assigned to a #m_process_t that has to behave as a slave.
503 This function keeps waiting for tasks and executes them as it receives them.
506 \subsection MSG_ext_ms_core_lua Simulation core
508 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.
509 : <i>require "simgrid" </i>
511 -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
512 -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
513 -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
514 -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
516 we can also bypass the XML deployment file, and associate functions for each of defined hosts.
517 - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
518 - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
520 \until simgrid.clean()