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