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