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