Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
2241a153d31eb87b918eb18367a5731ad695d51d
[simgrid.git] / 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_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_VMs VMs
96  *  @ingroup MSG_API
97  *  @brief This section describes the interface created to mimic IaaS clouds.
98  *
99  *  With it, you can create virtual machines to put your processes
100  *  into, and interact directly with the VMs to manage groups of
101  *  processes.
102  *
103  *  This interface is highly experimental at this point. Testing is
104  *  welcomed, but do not expect too much of it right now. Even the
105  *  interfaces may be changed in future releases of SimGrid (although
106  *  things are expected to stabilize nicely before SimGrid v3.8).
107  *  There is no guaranty on the rest of SimGrid, and there is less
108  *  than that on this part.
109  *
110  */
111
112 /** @defgroup msg_file_management File Management Functions
113  *  @ingroup MSG_API
114  *  @brief This section describes the file structure of MSG
115  *         (#msg_file_t) and the functions for managing it. It
116  *   is based on POSIX functions.
117  */
118
119
120 /**
121 @defgroup msg_trace_driven Trace-driven simulations
122 @ingroup MSG_API
123 @brief This section describes the functions allowing to build trace-driven simulations.
124
125 \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
126
127 This is very handy when you want to test an algorithm or protocol that
128 does nothing unless it receives some events from outside. For example,
129 a P2P protocol reacts to requests from the user, but does nothing if
130 there is no such event.
131
132 In such situations, SimGrid allows to write your protocol in your C
133 file, and the events to react to in a separate text file. Declare a
134 function handling each of the events that you want to accept in your
135 trace files, register them using #xbt_replay_action_register in your main,
136 and then use #MSG_action_trace_run to launch the simulation. You can
137 either have one trace file containing all your events, or a file per
138 simulated process.
139
140 Check the examples in <b>examples/msg/actions/actions.c</b> for details.
141
142  */
143
144
145
146 /**
147 @defgroup MSG_LUA      Lua bindings
148 @ingroup MSG_API
149 @brief Lua bindings to MSG (\ref MSG_API)
150
151 @htmlonly <!--  DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly
152
153 This is the lua bindings of the \ref MSG_API interface.
154
155 \section lMSG_who Who should use this (and who shouldn't)
156
157 If you want to use MSG to study your algorithm, but you don't want to use the C
158 language (using \ref MSG_API), then you should use some bindings such as this
159 one. Just like the \ref MSG_Java, the advantage of the lua bindings is that they
160 are distributed directly with the main archive (in contrary to Ruby bindings,
161 that are distributed separately).  Another advantage of lua is that there is
162 almost no performance loss with regard to the C version (at least there
163 shouldn't be any -- it is still to be precisely assessed).
164
165 \section MSG_Lua_funct  Lua offered functionnalities in MSG
166
167 Almost all important features of the MSG interface are available from
168 the lua bindings. Unfortunately, since doxygen does not support the
169 lua modules implemented directly in C as we are using, there is no
170 ready to use reference documentation for this module. Even more than
171 for the other modules, you will have to dig into the source code of
172 the examples to learn how to use it.
173
174 \section Lua_examples Examples of lua MSG
175
176   - \ref MSG_ex_master_slave_lua
177   - \ref MSG_ex_master_slave_lua_bypass
178   - Also, the lua version of the Chord example (in the source tree)
179     is a working non-trivial example of use of the lua bindings
180 */
181
182 /**
183 @defgroup MSG_examples MSG examples
184 @ingroup MSG_API
185 @brief MSG examples from examples directory examples/msg
186
187 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.
188
189 \section msg_bsc_ex Basic examples
190
191 */
192
193 /**
194 @defgroup msg_deprecated_functions MSG Deprecated
195 @ingroup MSG_API
196 @brief This section describes the deprecated functions. PLEASE STOP USING THEM.
197
198 We don't remove them because the ability to run old scientific
199 code is something important to us. But these functionalities are
200 not actively supported anymore.
201
202 To access these functions, you should define the relevant option
203 at configuration time in ccmake.
204  */
205
206
207
208
209
210