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