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