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