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 section.
  11
  12 If you think that MSG may not be the interface you need, please consider the
  13 other user interfaces provided by SimGrid: If you want to use DAGs, have a look
  14 at the \ref SD_API programming environment. If you want to study an existing MPI
  15 program, have a look at the \ref SMPI_API one. If none of those programming
  16 environments fits your needs, you may consider implementing your own directly on
  17 top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
  18 us before digging into these badly documented internal modules).
  19
  20
  21
  22 \section MSG_funct Offered functionalities
  23    - \ref msg_simulation
  24    - \ref m_process_management
  25    - \ref m_host_management
  26    - \ref m_task_management
  27    - \ref msg_mailbox_management
  28    - \ref msg_file_management
  29    - \ref msg_task_usage
  30    - \ref msg_VMs
  31    - \ref msg_synchro
  32    - \ref msg_trace_driven
  33    - \ref MSG_examples
  34    - \ref msg_deprecated_functions
  35
  36
  37   Also make sure to visit the page @ref MSG_examples.
  38 */
  39
  40
  41
  42 /**
  43 @defgroup msg_simulation   Main MSG simulation Functions
  44 @ingroup MSG_API
  45 @brief Describes how to setup and control your simulation.
  46
  47 The basic workflow is the following (check the \ref MSG_examples for
  48 details).
  49
  50  -# Initialize the library with #MSG_init
  51  -# Create a platform (usually by parsing a file with
  52     #MSG_create_environment)
  53  -# Register the functions that your processes are supposed to run with
  54     #MSG_function_register (and maybe #MSG_function_register_default)
  55  -# Launch your processes from a deployment file with #MSG_launch_application
  56  -# Run the simulation with #MSG_main
  57
  58 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
  59 */
  60
  61 /** @defgroup m_process_management Process Management Functions
  62  *  @ingroup MSG_API
  63  *  @brief This section describes the process structure of MSG
  64  *         (#msg_process_t) and the functions for managing it.
  65  */
  66
  67 /** @defgroup m_host_management Host Management Functions
  68  *  @ingroup MSG_API
  69  *  @brief This section describes the host structure of MSG
  70  */
  71
  72 /** @defgroup m_task_management Task Management Functions
  73  *  @ingroup MSG_API
  74  *  @brief This section describes the task structure of MSG
  75  *         (#msg_task_t) and the functions for managing it. See
  76  *         \ref msg_task_usage to see how to put the tasks in action.
  77  *
  78  * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
  79  */
  80
  81 /** @defgroup msg_mailbox_management Mailbox Management Functions
  82  *  @ingroup MSG_API
  83  *  @brief This section describes the mailbox structure of MSG
  84  *         (#msg_mailbox_t) and the functions for managing it.
  85  *
  86  * \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Mailbox" --> \endhtmlonly
  87  */
  88
  89 /** @defgroup msg_task_usage Task Actions
  90  *  @ingroup MSG_API
  91  *  @brief This section describes the functions that can be used
  92  *         by a process to execute, communicate or otherwise handle some task.
  93  */
  94
  95 /** @defgroup msg_synchro Explicit Synchronization Functions
  96  *  @ingroup MSG_API
  97  *  @brief This section describes several explicit synchronization
  98  *         mechanisms existing in MSG: semaphores (#msg_sem_t) and friends.
  99  *
 100  * In some situations, these things are very helpful to synchronize processes without message exchanges.
 101  */
 102
 103 /** @defgroup msg_VMs VMs
 104  *  @ingroup MSG_API
 105  *  @brief This section describes the interface created to mimic IaaS clouds.
 106  *
 107  *  With it, you can create virtual machines to put your processes
 108  *  into, and interact directly with the VMs to manage groups of
 109  *  processes.
 110  *
 111  *  This interface is highly experimental at this point. Testing is
 112  *  welcomed, but do not expect too much of it right now. Even the
 113  *  interfaces may be changed in future releases of SimGrid (although
 114  *  things are expected to stabilize nicely before SimGrid v3.8).
 115  *  There is no guaranty on the rest of SimGrid, and there is less
 116  *  than that on this part.
 117  *
 118  */
 119
 120 /** @defgroup msg_storage_management Storage Management Functions
 121  *  @ingroup MSG_API
 122  *  @brief This section describes the storage structure of MSG
 123  *         (#msg_storage_t) and the functions for managing it. It
 124  *   is based on POSIX functions.
 125  */
 126
 127 /** @defgroup msg_file_management File Management Functions
 128  *  @ingroup MSG_API
 129  *  @brief This section describes the file structure of MSG
 130  *         (#msg_file_t) and the functions for managing it. It
 131  *   is based on POSIX functions.
 132  */
 133
 134 /**
 135 @defgroup msg_trace_driven Trace-driven simulations
 136 @ingroup MSG_API
 137 @brief This section describes the functions allowing to build trace-driven simulations.
 138
 139 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
 140
 141 This is very handy when you want to test an algorithm or protocol that
 142 does nothing unless it receives some events from outside. For example,
 143 a P2P protocol reacts to requests from the user, but does nothing if
 144 there is no such event.
 145
 146 In such situations, SimGrid allows to write your protocol in your C
 147 file, and the events to react to in a separate text file. Declare a
 148 function handling each of the events that you want to accept in your
 149 trace files, register them using #xbt_replay_action_register in your main,
 150 and then use #MSG_action_trace_run to launch the simulation. You can
 151 either have one trace file containing all your events, or a file per
 152 simulated process.
 153
 154 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
 155
 156  */
 157
 158
 159 /**
 160 @defgroup MSG_examples MSG examples
 161 @ingroup MSG_API
 162 @brief MSG examples from examples directory examples/msg
 163
 164 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.
 165
 166 \section msg_bsc_ex Basic examples
 167
 168 */
 169
 170 /**
 171 @defgroup msg_deprecated_functions MSG Deprecated
 172 @ingroup MSG_API
 173 @brief This section describes the deprecated functions. PLEASE STOP USING THEM.
 174
 175 We don't remove them because the ability to run old scientific
 176 code is something important to us. But these functionalities are
 177 not actively supported anymore.
 178
 179 To access these functions, you should define the relevant option
 180 at configuration time in ccmake.
 181  */
 182
 183
 184
 185
 186
 187