doc/module-msg.doc

   1 /** \addtogroup MSG_API
   2
   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.
   6
   7       \section jMSG_who Who should use this (and who shouldn't)
   8
   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.
  14
  15   \section MSG_funct Offered functionnalities
  16    - \ref msg_simulation
  17    - \ref m_process_management
  18    - \ref m_host_management
  19    - \ref m_task_management
  20    - \ref msg_file_management
  21    - \ref msg_task_usage
  22    - \ref msg_trace_driven
  23    - \ref msg_deprecated_functions
  24
  25
  26   Also make sure to visit the page @ref MSG_examples.
  27 */
  28
  29 /**
  30 @defgroup MSG_examples MSG Examples
  31 @ingroup MSG_API
  32
  33 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Examples" --> @endhtmlonly
  34
  35 MSG comes with an extensive set of examples. It is sometimes difficult
  36 to find the one you need. This list aims at helping you finding the
  37 example from which you can learn what you want to.
  38
  39 @section MSG_ex_basics Basic examples and features
  40
  41 */
  42
  43 /**
  44 @defgroup msg_simulation   Main MSG simulation Functions
  45 @ingroup MSG_API
  46 @brief Describes how to setup and control your simulation.
  47
  48 The basic workflow is the following (check the \ref MSG_examples for
  49 details).
  50
  51  -# Initialize the library with #MSG_global_init
  52  -# Create a platform (usually by parsing a file with
  53     #MSG_create_environment)
  54  -# Register the functions that your processes are supposed to run with
  55     #MSG_function_register (and maybe #MSG_function_register_default)
  56  -# Launch your processes from a deployment file with #MSG_launch_application
  57  -# Run the simulation with #MSG_main
  58  -# Cleanup the library with #MSG_clean before ending your program
  59     (optional).
  60
  61 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
  62 */
  63
  64 /** @defgroup m_process_management Process Management Functions
  65  *  @ingroup MSG_API
  66  *  @brief This section describes the process structure of MSG
  67  *         (#m_process_t) and the functions for managing it.
  68  */
  69
  70 /** @defgroup m_host_management Host Management Functions
  71  *  @ingroup MSG_API
  72  *  @brief This section describes the host structure of MSG
  73  */
  74
  75 /** @defgroup m_task_management Task Management Functions
  76  *  @ingroup MSG_API
  77  *  @brief This section describes the task structure of MSG
  78  *         (#m_task_t) and the functions for managing it. See
  79  *         \ref msg_task_usage to see how to put the tasks in action.
  80  *
  81  * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
  82  */
  83
  84 /** @defgroup msg_task_usage Task Actions
  85  *  @ingroup MSG_API
  86  *  @brief This section describes the functions that can be used
  87  *         by a process to execute, communicate or otherwise handle some task.
  88  */
  89
  90 /** @defgroup msg_file_management File Management Functions
  91  *  @ingroup MSG_API
  92  *  @brief This section describes the file structure of MSG
  93  *         (#msg_file_t) and the functions for managing it. It
  94  *   is based on POSIX functions.
  95  */
  96
  97
  98 /**
  99 @defgroup msg_trace_driven Trace-driven simulations
 100 @ingroup MSG_API
 101 @brief This section describes the functions allowing to build trace-driven simulations.
 102
 103 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
 104
 105 This is very handy when you want to test an algorithm or protocol that
 106 does nothing unless it receives some events from outside. For example,
 107 a P2P protocol reacts to requests from the user, but does nothing if
 108 there is no such event.
 109
 110 In such situations, SimGrid allows to write your protocol in your C
 111 file, and the events to react to in a separate text file. Declare a
 112 function handling each of the events that you want to accept in your
 113 trace files, register them using #MSG_action_register in your main,
 114 and then use #MSG_action_trace_run to launch the simulation. You can
 115 either have one trace file containing all your events, or a file per
 116 simulated process.
 117
 118 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 119
 120  */
 121
 122
 123
 124 /**
 125 @defgroup MSG_LUA      Lua bindings
 126 @ingroup MSG_API
 127 @brief Lua bindings to MSG (\ref MSG_API)
 128
 129 @htmlonly <!--  DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
 130
 131 This is the lua bindings of the \ref MSG_API interface.
 132
 133 \section lMSG_who Who should use this (and who shouldn't)
 134
 135 If you want to use MSG to study your algorithm, but you don't want to
 136 use the C language (using \ref MSG_API), then you should use some
 137 bindings such as this one. The advantage of the lua bindings is that
 138 they are distributed directly with the main archive (in contrary to
 139 Java and Ruby bindings, for example, that are distributed separately).
 140 Another advantage of lua is that there is almost no performance loss
 141 with regard to the C version (at least there shouln't be any -- it is
 142 still to be precisely assessed).
 143
 144 \section MSG_Lua_funct  Lua offered functionnalities in MSG
 145
 146 Almost all important features of the MSG interface are available from
 147 the lua bindings. Unfortunately, since doxygen does not support the
 148 lua modules implemented directly in C as we are using, there is no
 149 ready to use reference documentation for this module. Even more than
 150 for the other modules, you will have to dig into the source code of
 151 the examples to learn how to use it.
 152
 153 \section Lua_examples Examples of lua MSG
 154
 155   - \ref MSG_ex_master_slave_lua
 156   - \ref MSG_ex_master_slave_lua_bypass
 157   - Also, the lua version of the Chord example (in the source tree)
 158     is a working non-trivial example of use of the lua bindings
 159 */
 160
 161 /**
 162 @defgroup msg_deprecated_functions MSG Deprecated
 163 @ingroup MSG_API
 164 @brief This section describes the deprecated functions. PLEASE STOP USING THEM.
 165
 166 We don't remove them because the ability to run old scientific
 167 code is something important to us. But these functionalities are
 168 not actively supported anymore.
 169
 170 To access these functions, you should define the relevant option
 171 at configuration time in ccmake.
 172  */
 173
 174
 175 /**
 176 @defgroup MSG_ex_asynchronous_communications Asynchronous communications
 177 @ingroup MSG_examples
 178
 179 Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
 180 an external description of the deployment.
 181
 182 \section MSG_ex_ms_TOC Table of contents:
 183  - \ref MSG_ext_icomms_code
 184    - \ref MSG_ext_icomms_preliminary
 185    - \ref MSG_ext_icomms_Sender
 186    - \ref MSG_ext_icomms_Receiver
 187    - \ref MSG_ext_icomms_core
 188    - \ref MSG_ext_icomms_Main
 189  - \ref MSG_ext_icomms_fct_Waitall
 190  - \ref MSG_ext_icomms_fct_Waitany
 191
 192 <hr>
 193
 194 \dontinclude msg/icomms/peer.c
 195
 196 \section MSG_ext_icomms_code Code of the application
 197
 198 \subsection MSG_ext_icomms_preliminary Preliminary declarations
 199 \skip include
 200 \until Sender function
 201
 202 \subsection MSG_ext_icomms_Sender Sender function
 203
 204 The sender send to a receiver an asynchronous message with the function "MSG_task_isend()". Cause this function is non-blocking
 205 we have to make "MSG_comm_test()" to know   if the communication is finished for finally destroy it with function "MSG_comm_destroy()".
 206 It also available to "make MSG_comm_wait()" which make both of them.
 207
 208   C style arguments (argc/argv) are interpreted as:
 209    - the number of tasks to distribute
 210    - the computation size of each task
 211    - the size of the files associated to each task
 212    - a list of host that will accept those tasks.
 213    - the time to sleep at the beginning of the function
 214    - This time defined the process sleep time
 215                         if time = 0 use of MSG_comm_wait()
 216                         if time > 0 use of MSG_comm_test()
 217
 218
 219 \until Receiver function
 220
 221 \subsection MSG_ext_icomms_Receiver Receiver function
 222
 223 This function executes tasks when it receives them. As the receiving is asynchronous we have to test the communication to know
 224 if it is completed or not with "MSG_comm_test()" or wait for the completion "MSG_comm_wait()".
 225
 226   C style arguments (argc/argv) are interpreted as:
 227    - the id to use for received the communication.
 228    - the time to sleep at the beginning of the function
 229    - This time defined the process sleep time
 230                         if time = 0 use of MSG_comm_wait()
 231                         if time > 0 use of MSG_comm_test()
 232
 233 \until Test function
 234
 235 \subsection MSG_ext_icomms_core Simulation core
 236
 237   This function is the core of the simulation and is divided only into 3 parts
 238   thanks to MSG_create_environment() and MSG_launch_application().
 239      -# Simulation settings : MSG_create_environment() creates a realistic
 240         environment
 241      -# Application deployment : create the processes on the right locations with
 242         MSG_launch_application()
 243      -# The simulation is run with #MSG_main()
 244
 245   Its arguments are:
 246         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
 247         - <i>application_file</i>: the name of a file containing a valid surfxml application description
 248
 249 \until Main function
 250
 251 \subsection MSG_ext_icomms_Main Main function
 252
 253 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 254
 255 \until end_of_main
 256
 257 \dontinclude msg/icomms/peer2.c
 258
 259 \section MSG_ext_icomms_fct_Waitall Waitall function for sender
 260
 261 The use of this function permit to send all messages and wait for the completion of all in one time.
 262
 263 \skipline Sender function
 264 \until end_of_sender
 265
 266 \section MSG_ext_icomms_fct_Waitany Waitany function
 267
 268 The MSG_comm_waitany() function return the place of the first message send or receive from a xbt_dynar_t table.
 269
 270 \subsection MSG_ext_icomms_fct_Waitany_sender From a sender
 271 We can use this function to wait all sent messages.
 272 \dontinclude msg/icomms/peer3.c
 273 \skipline Sender function
 274 \until end_of_sender
 275
 276 \subsection MSG_ext_icomms_fct_Waitany_receiver From a receiver
 277 We can also wait for the arrival of all messages.
 278 \dontinclude msg/icomms/peer3.c
 279 \skipline Receiver function
 280 \until end_of_receiver
 281
 282 */
 283
 284 /**
 285 @defgroup MSG_ex_master_slave Basic Master/Slaves
 286 @ingroup MSG_examples
 287
 288 Simulation of a master-slave application using a realistic platform
 289 and an external description of the deployment.
 290
 291 \section MSG_ex_ms_TOC Table of contents:
 292
 293  - \ref MSG_ext_ms_code
 294    - \ref MSG_ext_ms_preliminary
 295    - \ref MSG_ext_ms_master
 296    - \ref MSG_ext_ms_slave
 297    - \ref MSG_ext_ms_forwarder
 298    - \ref MSG_ext_ms_core
 299    - \ref MSG_ext_ms_main
 300  - \ref MSG_ext_ms_helping
 301    - \ref MSG_ext_ms_application
 302    - \ref MSG_ext_ms_platform
 303
 304 <hr>
 305
 306 \dontinclude msg/masterslave/masterslave_forwarder.c
 307
 308 \section MSG_ext_ms_code Code of the application
 309
 310 \subsection MSG_ext_ms_preliminary Preliminary declarations
 311
 312 \skip include
 313 \until printf
 314 \until }
 315
 316 \subsection MSG_ext_ms_master Master code
 317
 318 This function has to be assigned to a m_process_t that will behave as
 319 the master. It should not be called directly but either given as a
 320 parameter to #MSG_process_create() or registered as a public function
 321 through #MSG_function_register() and then automatically assigned to a
 322 process through #MSG_launch_application().
 323
 324 C style arguments (argc/argv) are interpreted as:
 325    - the number of tasks to distribute
 326    - the computation size of each task
 327    - the size of the files associated to each task
 328    - a list of host that will accept those tasks.
 329
 330 Tasks are dumbly sent in a round-robin style.
 331
 332 \until end_of_master
 333
 334 \subsection MSG_ext_ms_slave Slave code
 335
 336 This function has to be assigned to a #m_process_t that has to behave
 337 as a slave. Just like the master fuction (described in \ref
 338 MSG_ext_ms_master), it should not be called directly.
 339
 340 This function keeps waiting for tasks and executes them as it receives them.
 341
 342 \until end_of_slave
 343
 344 \subsection MSG_ext_ms_forwarder Forwarder code
 345
 346 This function has to be assigned to a #m_process_t that has to behave
 347 as a forwarder. Just like the master function (described in \ref
 348 MSG_ext_ms_master), it should not be called directly.
 349
 350 C style arguments (argc/argv) are interpreted as a list of host that
 351 will accept those tasks.
 352
 353 This function keeps waiting for tasks and dispathes them to its slaves.
 354
 355 \until end_of_forwarder
 356
 357 \subsection MSG_ext_ms_core Simulation core
 358
 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
 362       environment
 363    -# Application deployment : create the processes on the right locations with
 364       MSG_launch_application()
 365    -# The simulation is run with #MSG_main()
 366
 367 Its arguments are:
 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
 370
 371 \until end_of_test_all
 372
 373 \subsection MSG_ext_ms_main Main() function
 374
 375 This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 376
 377 \until end_of_main
 378
 379 \section MSG_ext_ms_helping Helping files
 380
 381 \subsection MSG_ext_ms_application Example of application file
 382
 383 \include msg/masterslave/deployment_masterslave.xml
 384
 385 \subsection MSG_ext_ms_platform Example of platform file
 386
 387 \include msg/small_platform.xml
 388
 389 */
 390
 391 /** \page MSG_ex_master_slave_lua Master/slave Lua application
 392
 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
 398
 399      - \ref MSG_ext_ms_helping
 400        - \ref MSG_ext_ms_application
 401        - \ref MSG_ext_ms_platform
 402
 403
 404       \dontinclude lua/masterslave/master_slave.lua
 405
 406       \section MSG_ext_ms_code_lua Code of the application
 407
 408       \subsection MSG_ext_ms_master_lua Master code
 409
 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.
 411
 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.
 417
 418       Tasks are dumbly sent in a round-robin style.
 419
 420       \until end_of_master
 421
 422
 423       \subsection MSG_ext_ms_slave_lua Slave code
 424
 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.
 427
 428       \until end_of_slave
 429          \subsection MSG_ext_ms_core_lua Simulation core
 430
 431       in this section the core of the simulation which start by including the simgrid lib for bindings
 432       : <i>require "simgrid" </i>
 433
 434          -# Simulation settings : <i>simgrid.platform</i> creates a realistic
 435             environment
 436          -# Application deployment : create the processes on the right locations with
 437             <i>simgrid.application</i>
 438          -# The simulation is run with <i>simgrid.run</i>
 439
 440       Its arguments are:
 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 )
 443
 444       \until simgrid.clean()
 445
 446 */
 447
 448 /** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
 449
 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
 455
 456
 457       \dontinclude lua/console/master_slave_bypass.lua
 458
 459       \section MSG_ext_ms_code_lua Code of the application
 460
 461       \subsection MSG_ext_ms_master_lua Master code
 462
 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.
 464
 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.
 470
 471       Tasks are dumbly sent in a round-robin style.
 472
 473       \until end_of_master
 474
 475
 476       \subsection MSG_ext_ms_slave_lua Slave code
 477
 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.
 480
 481       \until end_of_slave
 482          \subsection MSG_ext_ms_core_lua Simulation core
 483
 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>
 486
 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.
 491
 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.
 495
 496       \until simgrid.clean()
 497
 498 */
 499