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