doc/module-msg.doc

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