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