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 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 */
 212
 213 /** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
 214
 215     Simulation of a master-slave application using a realistic platform and
 216     an external description of the deployment via a lua script.
 217
 218     \section MSG_ex_msl_TOC Table of contents:
 219
 220      - \ref MSG_ext_msl_code
 221        - \ref MSG_ext_msl_preliminary
 222        - \ref MSG_ext_msl_master
 223        - \ref MSG_ext_msl_slave
 224        - \ref MSG_ext_msl_core
 225        - \ref MSG_ext_msl_main
 226      - \ref MSG_ext_msl_helping
 227        - \ref MSG_ext_msl_platform
 228
 229 <hr>
 230
 231     \dontinclude msg/masterslave/masterslave_console.c
 232
 233     \section MSG_ext_msl_code Code of the application
 234
 235     \subsection MSG_ext_msl_preliminary Preliminary declarations
 236
 237     \skip include
 238     \until } channel_t;
 239
 240     \subsection MSG_ext_msl_master Master code
 241
 242       This function has to be assigned to a m_process_t that will behave as the master.
 243       It should not be called directly but either given as a parameter to
 244       #MSG_process_create() or registered as a public function through
 245       #MSG_function_register() and then automatically assigned to a process through
 246       #MSG_load_platform_script().
 247
 248       C style arguments (argc/argv) are interpreted as:
 249        - the number of tasks to distribute
 250        - the computation size of each task
 251        - the size of the files associated to each task
 252        - number of hosts that will accept those tasks.
 253
 254       Tasks are dumbly sent in a round-robin style.
 255
 256       \until end_of_master
 257 \subsection MSG_ext_msl_slave Slave code
 258
 259       This function has to be assigned to a #m_process_t that has to behave as a slave.
 260       Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
 261
 262       This function keeps waiting for tasks and executes them as it receives them.
 263
 264       \until end_of_slave
 265
 266 \subsection MSG_ext_msl_core Simulation core
 267
 268       This function is the core of the simulation and is divided now only into 2 parts
 269       thanks to MSG_load_platform_script().
 270          -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic
 271             environment and the agents on the right locations, described in the lua script file (see example below).
 272             Note that the use of this function require a lua installation on your machine.
 273          -# The simulation is run with #MSG_main().
 274
 275       Its arguments are:
 276         - <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.
 277
 278       \until end_of_test_all
 279
 280 \subsection MSG_ext_msl_main Main() function
 281
 282       This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 283
 284       \until end_of_main
 285
 286    \section MSG_ext_msl_helping Helping files
 287
 288    \subsection MSG_ext_msl_platform Example of platform script file
 289
 290    \include msg/masterslave/platform_script.lua
 291
 292
 293 */
 294
 295 /** \page MSG_ex_master_slave Master/slave application
 296
 297     Simulation of a master-slave application using a realistic platform and
 298     an external description of the deployment.
 299
 300     \section MSG_ex_ms_TOC Table of contents:
 301
 302      - \ref MSG_ext_ms_code
 303        - \ref MSG_ext_ms_preliminary
 304        - \ref MSG_ext_ms_master
 305        - \ref MSG_ext_ms_slave
 306        - \ref MSG_ext_ms_forwarder
 307        - \ref MSG_ext_ms_core
 308        - \ref MSG_ext_ms_main
 309      - \ref MSG_ext_ms_helping
 310        - \ref MSG_ext_ms_application
 311        - \ref MSG_ext_ms_platform
 312
 313     <hr>
 314
 315     \dontinclude msg/masterslave/masterslave_forwarder.c
 316
 317     \section MSG_ext_ms_code Code of the application
 318
 319     \subsection MSG_ext_ms_preliminary Preliminary declarations
 320
 321     \skip include
 322     \until printf
 323     \until }
 324
 325     \subsection MSG_ext_ms_master Master code
 326
 327       This function has to be assigned to a m_process_t that will behave as the master.
 328       It should not be called directly but either given as a parameter to
 329       #MSG_process_create() or registered as a public function through
 330       #MSG_function_register() and then automatically assigned to a process through
 331       #MSG_launch_application().
 332
 333       C style arguments (argc/argv) are interpreted as:
 334        - the number of tasks to distribute
 335        - the computation size of each task
 336        - the size of the files associated to each task
 337        - a list of host that will accept those tasks.
 338
 339       Tasks are dumbly sent in a round-robin style.
 340
 341       \until end_of_master
 342
 343     \subsection MSG_ext_ms_slave Slave code
 344
 345       This function has to be assigned to a #m_process_t that has to behave as a slave.
 346       Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
 347
 348       This function keeps waiting for tasks and executes them as it receives them.
 349
 350       \until end_of_slave
 351
 352    \subsection MSG_ext_ms_forwarder Forwarder code
 353
 354       This function has to be assigned to a #m_process_t that has to behave as a forwarder.
 355       Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly.
 356
 357       C style arguments (argc/argv) are interpreted as a list of host
 358       that will accept those tasks.
 359
 360       This function keeps waiting for tasks and dispathes them to its slaves.
 361
 362       \until end_of_forwarder
 363
 364    \subsection MSG_ext_ms_core Simulation core
 365
 366       This function is the core of the simulation and is divided only into 3 parts
 367       thanks to MSG_create_environment() and MSG_launch_application().
 368          -# Simulation settings : MSG_create_environment() creates a realistic
 369             environment
 370          -# Application deployment : create the agents on the right locations with
 371             MSG_launch_application()
 372          -# The simulation is run with #MSG_main()
 373
 374       Its arguments are:
 375         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
 376         - <i>application_file</i>: the name of a file containing a valid surfxml application description
 377
 378       \until end_of_test_all
 379
 380    \subsection MSG_ext_ms_main Main() function
 381
 382       This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 383
 384       \until end_of_main
 385
 386    \section MSG_ext_ms_helping Helping files
 387
 388    \subsection MSG_ext_ms_application Example of application file
 389
 390    \include msg/masterslave/deployment_masterslave.xml
 391
 392    \subsection MSG_ext_ms_platform Example of platform file
 393
 394    \include msg/small_platform.xml
 395
 396 */
 397
 398 /** \page MSG_ex_master_slave_lua Master/slave Lua application
 399
 400     Simulation of a master-slave application using lua bindings
 401        - \ref MSG_ext_ms_code_lua
 402        - \ref MSG_ext_ms_master_lua
 403        - \ref MSG_ext_ms_slave_lua
 404        - \ref MSG_ext_ms_core_lua
 405
 406      - \ref MSG_ext_ms_helping
 407        - \ref MSG_ext_ms_application
 408        - \ref MSG_ext_ms_platform
 409
 410
 411       \dontinclude lua/master_slave.lua
 412
 413       \section MSG_ext_ms_code_lua Code of the application
 414
 415       \subsection MSG_ext_ms_master_lua Master code
 416
 417             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.
 418
 419       Lua style arguments (...) in for the master are interpreted as:
 420        - the number of tasks to distribute
 421        - the computation size of each task
 422        - the size of the files associated to each task
 423        - a list of host that will accept those tasks.
 424
 425       Tasks are dumbly sent in a round-robin style.
 426
 427       \until end_of_master
 428
 429
 430       \subsection MSG_ext_ms_slave_lua Slave code
 431
 432       This function has to be assigned to a #m_process_t that has to behave as a slave.
 433       This function keeps waiting for tasks and executes them as it receives them.
 434
 435       \until end_of_slave
 436          \subsection MSG_ext_ms_core_lua Simulation core
 437
 438       in this section the core of the simulation which start by including the simgrid lib for bindings
 439       : <i>require "simgrid" </i>
 440
 441          -# Simulation settings : <i>simgrid.platform</i> creates a realistic
 442             environment
 443          -# Application deployment : create the agents on the right locations with
 444             <i>simgrid.application</i>
 445          -# The simulation is run with <i>simgrid.run</i>
 446
 447       Its arguments are:
 448         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
 449         - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
 450
 451       \until simgrid.clean()
 452
 453 */
 454
 455 /** \page MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application
 456
 457     Simulation of a master-slave application using lua bindings, Bypassing the XML parser
 458        - \ref MSG_ext_ms_code_lua
 459        - \ref MSG_ext_ms_master_lua
 460        - \ref MSG_ext_ms_slave_lua
 461        - \ref MSG_ext_ms_core_lua
 462
 463
 464       \dontinclude lua/master_slave_bypass.lua
 465
 466       \section MSG_ext_ms_code_lua Code of the application
 467
 468       \subsection MSG_ext_ms_master_lua Master code
 469
 470             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.
 471
 472       Lua style arguments (...) in for the master are interpreted as:
 473        - the number of tasks to distribute
 474        - the computation size of each task
 475        - the size of the files associated to each task
 476        - a list of host that will accept those tasks.
 477
 478       Tasks are dumbly sent in a round-robin style.
 479
 480       \until end_of_master
 481
 482
 483       \subsection MSG_ext_ms_slave_lua Slave code
 484
 485       This function has to be assigned to a #m_process_t that has to behave as a slave.
 486       This function keeps waiting for tasks and executes them as it receives them.
 487
 488       \until end_of_slave
 489          \subsection MSG_ext_ms_core_lua Simulation core
 490
 491       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.
 492       : <i>require "simgrid" </i>
 493
 494          -# Hosts : <i>simgrid.Host.new</i> instanciate a new host with an id, and power.
 495          -# Links : <i>simgrid.Link.new</i> instanictae a new link that will require an id, bandwith and latency values.
 496          -# Route : <i>simgrid.Route.new</i> define a route between two hosts specifying the links to use.
 497          -# Simulation settings : <i>simgrid.register_platform();</i> register own platform without using the XML SURF parser.
 498
 499          we can also bypass the XML deployment file, and associate functions for each of defined hosts.
 500         - <i>simgrid.Host.setFunction</i>: associate a function to a host, specifying arguments if needed.
 501         - <i>simgrid.register_application()</i>: saving the deployment settings before running the simualtion.
 502
 503       \until simgrid.clean()
 504
 505 */