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 */
  85
  86 /** @addtogroup MSG_LUA
  87
  88   \section MSG_Lua_funct  Lua offered functionnalities in MSG
  89    - \ref host_management
  90    - \ref tasks_management
  91    - \ref environment_management
  92   \section Lua_examples Examples of lua MSG
  93
  94    - \ref MSG_ex_master_slave_lua
  95 */
  96
  97
  98 /** @defgroup m_datatypes_management MSG Data Types
  99     @ingroup MSG_C
 100     @brief This section describes the different datatypes provided by MSG.
 101
 102     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
 103 */
 104 /**     \addtogroup m_process_management
 105         \ingroup MSG_C  */
 106 /**     \addtogroup m_host_management
 107         \ingroup MSG_C  */
 108 /**     \addtogroup m_task_management
 109         \ingroup MSG_C  */
 110 /**     \addtogroup msg_gos_functions
 111         \ingroup MSG_C  */
 112 /**     \addtogroup m_channel_management
 113         \ingroup MSG_C  */
 114 /**     \addtogroup msg_easier_life
 115         \ingroup MSG_C  */
 116 /**     \addtogroup msg_simulation
 117         \ingroup MSG_C  */
 118
 119 /** \page MSG_ex_master_slave Master/slave application
 120
 121     Simulation of a master-slave application using a realistic platform and
 122     an external description of the deployment.
 123
 124     \section MSG_ex_ms_TOC Table of contents:
 125
 126      - \ref MSG_ext_ms_code
 127        - \ref MSG_ext_ms_preliminary
 128        - \ref MSG_ext_ms_master
 129        - \ref MSG_ext_ms_slave
 130        - \ref MSG_ext_ms_forwarder
 131        - \ref MSG_ext_ms_core
 132        - \ref MSG_ext_ms_main
 133      - \ref MSG_ext_ms_helping
 134        - \ref MSG_ext_ms_application
 135        - \ref MSG_ext_ms_platform
 136
 137     <hr>
 138
 139     \dontinclude msg/masterslave/masterslave_forwarder.c
 140
 141     \section MSG_ext_ms_code Code of the application
 142
 143     \subsection MSG_ext_ms_preliminary Preliminary declarations
 144
 145     \skip include
 146     \until printf
 147     \until }
 148
 149     \subsection MSG_ext_ms_master Master code
 150
 151       This function has to be assigned to a m_process_t that will behave as the master.
 152       It should not be called directly but either given as a parameter to
 153       #MSG_process_create() or registered as a public function through
 154       #MSG_function_register() and then automatically assigned to a process through
 155       #MSG_launch_application().
 156
 157       C style arguments (argc/argv) are interpreted as:
 158        - the number of tasks to distribute
 159        - the computation size of each task
 160        - the size of the files associated to each task
 161        - a list of host that will accept those tasks.
 162
 163       Tasks are dumbly sent in a round-robin style.
 164
 165       \until end_of_master
 166
 167     \subsection MSG_ext_ms_slave Slave code
 168
 169       This function has to be assigned to a #m_process_t that has to behave as a slave.
 170       Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
 171
 172       This function keeps waiting for tasks and executes them as it receives them.
 173
 174       \until end_of_slave
 175
 176    \subsection MSG_ext_ms_forwarder Forwarder code
 177
 178       This function has to be assigned to a #m_process_t that has to behave as a forwarder.
 179       Just like the master function (described in \ref MSG_ext_ms_master), it should not be called directly.
 180
 181       C style arguments (argc/argv) are interpreted as a list of host
 182       that will accept those tasks.
 183
 184       This function keeps waiting for tasks and dispathes them to its slaves.
 185
 186       \until end_of_forwarder
 187
 188    \subsection MSG_ext_ms_core Simulation core
 189
 190       This function is the core of the simulation and is divided only into 3 parts
 191       thanks to MSG_create_environment() and MSG_launch_application().
 192          -# Simulation settings : MSG_create_environment() creates a realistic
 193             environment
 194          -# Application deployment : create the agents on the right locations with
 195             MSG_launch_application()
 196          -# The simulation is run with #MSG_main()
 197
 198       Its arguments are:
 199         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.
 200         - <i>application_file</i>: the name of a file containing a valid surfxml application description
 201
 202       \until end_of_test_all
 203
 204    \subsection MSG_ext_ms_main Main() function
 205
 206       This initializes MSG, runs a simulation, and free all data-structures created by MSG.
 207
 208       \until end_of_main
 209
 210    \section MSG_ext_ms_helping Helping files
 211
 212    \subsection MSG_ext_ms_application Example of application file
 213
 214    \include msg/masterslave/deployment_masterslave.xml
 215
 216    \subsection MSG_ext_ms_platform Example of platform file
 217
 218    \include msg/small_platform.xml
 219
 220 */
 221
 222 /** \page MSG_ex_master_slave_lua Master/slave Lua application
 223
 224     Simulation of a master-slave application using lua bindings
 225        - \ref MSG_ext_ms_code_lua
 226        - \ref MSG_ext_ms_master_lua
 227        - \ref MSG_ext_ms_slave_lua
 228        - \ref MSG_ext_ms_core_lua
 229
 230      - \ref MSG_ext_ms_helping
 231        - \ref MSG_ext_ms_application
 232        - \ref MSG_ext_ms_platform
 233
 234
 235       \dontinclude lua/master_slave.lua
 236
 237       \section MSG_ext_ms_code_lua Code of the application
 238
 239       \subsection MSG_ext_ms_master_lua Master code
 240
 241             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.
 242
 243       Lua style arguments (...) in for the master are interpreted as:
 244        - the number of tasks to distribute
 245        - the computation size of each task
 246        - the size of the files associated to each task
 247        - a list of host that will accept those tasks.
 248
 249       Tasks are dumbly sent in a round-robin style.
 250
 251       \until end_of_master
 252
 253
 254       \subsection MSG_ext_ms_slave_lua Slave code
 255
 256       This function has to be assigned to a #m_process_t that has to behave as a slave.
 257       This function keeps waiting for tasks and executes them as it receives them.
 258
 259       \until end_of_slave
 260          \subsection MSG_ext_ms_core_lua Simulation core
 261
 262       in this section the core of the simulation which start by including the simgrid lib for bindings
 263       : <i>require "simgrid" </i>
 264
 265          -# Simulation settings : <i>simgrid.platform</i> creates a realistic
 266             environment
 267          -# Application deployment : create the agents on the right locations with
 268             <i>simgrid.application</i>
 269          -# The simulation is run with <i>simgrid.run</i>
 270
 271       Its arguments are:
 272         - <i>platform_file</i>: the name of a file containing an valid surfxml platform description.( first command line argument)
 273         - <i>application_file</i>: the name of a file containing a valid surfxml application description ( second commande line argument )
 274
 275       \until simgrid.clean()
 276
 277 */