doc/module-msg.doc

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