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