doc/doxygen/module-msg.doc

   1 /** \addtogroup MSG_API
   2
   3 MSG was the first distributed programming environment provided within SimGrid,
   4 and is still the most commonly used nowadays. If you are unsure of the interface
   5 you should use, they you probably want to use MSG. It constitutes a convenient
   6 simplification of the reality of distributed systems. It can be used to build
   7 rather realistic simulations, but remains simple to use: most unpleasant
   8 technical elements can be abstracted away rather easily.  If you want to use the
   9 C programming language, your are in the right section. If you prefer not to use
  10 this venerable but demanding language, please refer to the @ref MSG_Java, the
  11 @ref MSG_LUA, or the @ref MSG_Ruby (that are distributed separately).
  12
  13 If you think that MSG may not be the interface you need, please consider the
  14 other user interfaces provided by SimGrid: If you want to use DAGs, have a look
  15 at the \ref SD_API programming environment. If you want to study an existing MPI
  16 program, have a look at the \ref SMPI_API one. If none of those programming
  17 environments fits your needs, you may consider implementing your own directly on
  18 top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
  19 us before digging into these badly documented internal modules).
  20
  21
  22
  23 \section MSG_funct Offered functionalities
  24    - \ref msg_simulation
  25    - \ref m_process_management
  26    - \ref m_host_management
  27    - \ref m_task_management
  28    - \ref msg_mailbox_management
  29    - \ref msg_file_management
  30    - \ref msg_task_usage
  31    - \ref msg_VMs
  32    - \ref msg_synchro
  33    - \ref msg_trace_driven
  34    - \ref MSG_examples
  35    - \ref msg_deprecated_functions
  36
  37
  38   Also make sure to visit the page @ref MSG_examples.
  39 */
  40
  41
  42
  43 /**
  44 @defgroup msg_simulation   Main MSG simulation Functions
  45 @ingroup MSG_API
  46 @brief Describes how to setup and control your simulation.
  47
  48 The basic workflow is the following (check the \ref MSG_examples for
  49 details).
  50
  51  -# Initialize the library with #MSG_init
  52  -# Create a platform (usually by parsing a file with
  53     #MSG_create_environment)
  54  -# Register the functions that your processes are supposed to run with
  55     #MSG_function_register (and maybe #MSG_function_register_default)
  56  -# Launch your processes from a deployment file with #MSG_launch_application
  57  -# Run the simulation with #MSG_main
  58
  59 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
  60 */
  61
  62 /** @defgroup m_process_management Process Management Functions
  63  *  @ingroup MSG_API
  64  *  @brief This section describes the process structure of MSG
  65  *         (#msg_process_t) and the functions for managing it.
  66  */
  67
  68 /** @defgroup m_host_management Host Management Functions
  69  *  @ingroup MSG_API
  70  *  @brief This section describes the host structure of MSG
  71  */
  72
  73 /** @defgroup m_task_management Task Management Functions
  74  *  @ingroup MSG_API
  75  *  @brief This section describes the task structure of MSG
  76  *         (#msg_task_t) and the functions for managing it. See
  77  *         \ref msg_task_usage to see how to put the tasks in action.
  78  *
  79  * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
  80  */
  81
  82 /** @defgroup msg_mailbox_management Mailbox Management Functions
  83  *  @ingroup MSG_API
  84  *  @brief This section describes the mailbox structure of MSG
  85  *         (#msg_mailbox_t) and the functions for managing it.
  86  *
  87  * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Mailbox" --> \endhtmlonly
  88  */
  89
  90 /** @defgroup msg_task_usage Task Actions
  91  *  @ingroup MSG_API
  92  *  @brief This section describes the functions that can be used
  93  *         by a process to execute, communicate or otherwise handle some task.
  94  */
  95
  96 /** @defgroup msg_synchro Explicit Synchronization Functions
  97  *  @ingroup MSG_API
  98  *  @brief This section describes several explicit synchronization
  99  *         mechanisms existing in MSG: semaphores (#msg_sem_t) and friends.
 100  *
 101  * In some situations, these things are very helpful to synchronize processes without message exchanges.
 102  */
 103
 104 /** @defgroup msg_VMs VMs
 105  *  @ingroup MSG_API
 106  *  @brief This section describes the interface created to mimic IaaS clouds.
 107  *
 108  *  With it, you can create virtual machines to put your processes
 109  *  into, and interact directly with the VMs to manage groups of
 110  *  processes.
 111  *
 112  *  This interface is highly experimental at this point. Testing is
 113  *  welcomed, but do not expect too much of it right now. Even the
 114  *  interfaces may be changed in future releases of SimGrid (although
 115  *  things are expected to stabilize nicely before SimGrid v3.8).
 116  *  There is no guaranty on the rest of SimGrid, and there is less
 117  *  than that on this part.
 118  *
 119  */
 120
 121 /** @defgroup msg_file_management File Management Functions
 122  *  @ingroup MSG_API
 123  *  @brief This section describes the file structure of MSG
 124  *         (#msg_file_t) and the functions for managing it. It
 125  *   is based on POSIX functions.
 126  */
 127
 128
 129 /**
 130 @defgroup msg_trace_driven Trace-driven simulations
 131 @ingroup MSG_API
 132 @brief This section describes the functions allowing to build trace-driven simulations.
 133
 134 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
 135
 136 This is very handy when you want to test an algorithm or protocol that
 137 does nothing unless it receives some events from outside. For example,
 138 a P2P protocol reacts to requests from the user, but does nothing if
 139 there is no such event.
 140
 141 In such situations, SimGrid allows to write your protocol in your C
 142 file, and the events to react to in a separate text file. Declare a
 143 function handling each of the events that you want to accept in your
 144 trace files, register them using #xbt_replay_action_register in your main,
 145 and then use #MSG_action_trace_run to launch the simulation. You can
 146 either have one trace file containing all your events, or a file per
 147 simulated process.
 148
 149 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 150
 151  */
 152
 153
 154
 155 /**
 156 @defgroup MSG_LUA      Lua bindings
 157 @ingroup MSG_API
 158 @brief Lua bindings to MSG (\ref MSG_API)
 159
 160 @htmlonly <!--  DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
 161
 162 This is the lua bindings of the \ref MSG_API interface.
 163
 164 \section lMSG_who Who should use this (and who shouldn't)
 165
 166 If you want to use MSG to study your algorithm, but you don't want to use the C
 167 language (using \ref MSG_API), then you should use some bindings such as this
 168 one. Just like the \ref MSG_Java, the advantage of the lua bindings is that they
 169 are distributed directly with the main archive (in contrary to Ruby bindings,
 170 that are distributed separately).  Another advantage of lua is that there is
 171 almost no performance loss with regard to the C version (at least there
 172 shouldn't be any -- it is still to be precisely assessed).
 173
 174 \section MSG_Lua_funct  Lua offered functionnalities in MSG
 175
 176 Almost all important features of the MSG interface are available from
 177 the lua bindings. Unfortunately, since doxygen does not support the
 178 lua modules implemented directly in C as we are using, there is no
 179 ready to use reference documentation for this module. Even more than
 180 for the other modules, you will have to dig into the source code of
 181 the examples to learn how to use it.
 182
 183 \section Lua_examples Examples of lua MSG
 184
 185   - \ref MSG_ex_master_slave_lua
 186   - \ref MSG_ex_master_slave_lua_bypass
 187   - Also, the lua version of the Chord example (in the source tree)
 188     is a working non-trivial example of use of the lua bindings
 189 */
 190
 191 /**
 192 @defgroup MSG_examples MSG examples
 193 @ingroup MSG_API
 194 @brief MSG examples from examples directory examples/msg
 195
 196 MSG comes with an extensive set of examples. It is sometimes difficult to find the one you need. This list aims at helping you finding the example from which you can learn what you want to.
 197
 198 \section msg_bsc_ex Basic examples
 199
 200 */
 201
 202 /**
 203 @defgroup msg_deprecated_functions MSG Deprecated
 204 @ingroup MSG_API
 205 @brief This section describes the deprecated functions. PLEASE STOP USING THEM.
 206
 207 We don't remove them because the ability to run old scientific
 208 code is something important to us. But these functionalities are
 209 not actively supported anymore.
 210
 211 To access these functions, you should define the relevant option
 212 at configuration time in ccmake.
 213  */
 214
 215
 216
 217
 218
 219