1 /*! @page tutorial_msg SimGrid Tutorial with MSG
5 \section tuto-msg-intro Introduction
7 \subsection tuto-msg-intro-settings Settings
9 This tutorial will guide your create and run your first SimGrid
10 simulator. Let's consider the following scenario:
12 > Assume we have a (possibly large) bunch of (possibly large) data to
13 > process and which originally reside on a server (a.k.a. master). For
14 > sake of simplicity, we assume all input file require the same amount
15 > of computation. We assume the server can be helped by a (possibly
16 > large) set of worker machines. What is the best way to organize the
22 \htmlinclude tuto-msg/overview.svg
27 \subsection tuto-msg-intro-questions Raised Questions
29 Although this looks like a very simple setting it raises several
30 interesting questions:
32 - Which algorithm should the master use to send workload?
34 The provided code sends the tasks to the workers with a trivial
35 round-robin algorithm. It would probably be more efficient if the
36 workers were asking for tasks, to let the master distribute the
37 tasks in a more cleaver way.
39 - Should the worker specify how many tasks they want? Or should the
40 master decide everything?
42 The workers will starve if they don't get the tasks fast
43 enough. One possibility to reduce latency would be to send tasks
44 in pools instead of one by one. But if the pools are too big, the
45 load balancing will likely get uneven, in particular when
46 distributing the last tasks.
48 - How does the quality of such algorithm dependent on the platform
49 characteristics and on the task characteristics?
51 Whenever the input communication time is very small compared to
52 processing time and workers are homogeneous, it is likely that the
53 round-robin algorithm performs very well. Would it still hold true
54 when transfer time is not negligible and the platform is, say, a
55 volunteer computing system ? What if some tasks are performed
56 faster on some specific nodes?
58 - The network topology interconnecting the master and the workers
59 may be quite complicated. How does such a topology impact the
62 When data transfers are the bottleneck, it is likely that a good
63 modeling of the platform becomes essential. The SimGrid platform
64 models are particularly handy to account for complex platform
67 - What topology to use for the application?
69 Is a flat master worker deployment sufficient? Should we go for a
70 hierarchical algorithm, with some forwarders taking large pools of
71 tasks from the master, each of them distributing their tasks to a
72 sub-pool of workers? Or should we introduce super-peers,
73 dupplicating the master's role in a peer-to-peer manner? Do the
74 algorithms require a perfect knowledge of the network?
76 - How is such an algorithm sensitive to external workload variation?
78 What if bandwidth, latency and computing speed can vary with no
79 warning? Shouldn't you study whether your algorithm is sensitive
80 to such load variations?
82 - Although an algorithm may be more efficient than another, how
83 does it interfere with other applications?
88 As you can see, this very simple setting may need to evolve way beyond
89 what you initially imagined. And this is a good news.
91 But don't believe the fools saying that all you need to study such
92 settings is a simple discrete event simulator. Do you really want to
93 reinvent the wheel, write your own tool, debug it, optimize it and
94 validate its models against real settings for ages, or do you prefer
95 to sit on the shoulders of a giant?<br>
96 With SimGrid, you can forget about most technical details (but not
97 all), and focus on your algorithm. The whole simulation mechanism is
100 \subsection tuto-msg-intro-goal Envisionned Study
103 The following figure is a screenshot of [triva][fn:1] visualizing a [SimGrid
104 simulation][fn:2] of two master worker applications (one in light gray and
105 the other in dark gray) running in concurrence and showing resource
106 usage over a long period of time.
108 ![Test](./sc3-description.png)
110 \section tuto-msg-starting Getting Started
112 \subsection tuto-msg-prerequesite Prerequisite
114 In this example, we use Pajeng and Vite to visualize the result of
115 SimGrid simulations. These external tools are usually very easy to
116 install. On Debian and Ubuntu for example, you can get them as follows:
119 sudo apt-get install pajeng vite
122 \subsection tuto-msg-setup Setting up and Compiling
124 The corresponding source files can be obtained
125 [online on GitLab](https://gitlab.inria.fr/simgrid/simgrid/tree/master/doc/tuto-msg/src).
126 There is a button on the top right to download the whole
127 directory in one archive file. If you wish, other platform files are available from
128 [this GitLab directory](https://gitlab.inria.fr/simgrid/simgrid/tree/master/examples/platforms).
130 As you can see, there is already a little Makefile that compiles
131 everything for you. If you struggle with the compilation, then you should double check
132 your @ref install "SimGrid installation".
133 On need, please refer to the @ref install_yours_trouble section.
135 \section tuto-msg-ex0 Discovering the provided simulator
137 Please compile and execute the provided simulator as follows:
141 ./masterworker examples/platforms/small_platform.xml deployment0.xml
144 For a more "fancy" output, you can use simgrid-colorizer.
147 ./masterworker examples/platforms/small_platform.xml deployment0.xml 2>&1 | simgrid-colorizer
150 If you installed SimGrid to a non-standard path, you may have to
151 specify the full path to simgrid-colorizer on the above line, such as
152 \c /opt/simgrid/bin/simgrid-colorizer. If you did not install it at all,
153 you can find it in <simgrid_root_directory>/bin/colorize.
155 For a classical Gantt-Chart visualization, you can produce a [Paje][fn:5] trace:
158 ./masterworker platforms/platform.xml deployment0.xml --cfg=tracing:yes \
159 --cfg=tracing/msg/process:yes
163 Alternatively, you can use [vite][fn:6].
166 ./masterworker platforms/platform.xml deployment0.xml --cfg=tracing:yes \
167 --cfg=tracing/msg/process:yes --cfg=tracing/basic:yes
171 \subsection tuto-msg-exo0-source Understanding this source code
173 Explore the \ref doc/tuto-msg/masterworker.c source file. It contains 3 functions:
174 - \c master: that's the code executed by the master process.<br>
175 It creates a large array containing all tasks,
176 dispatches all tasks to the workers and then dispatch
177 specific tasks which name is "finalize".
178 - \c worker: each workers will execute this function.<br>
179 That's an infinite loop waiting for incomming tasks.
180 We exit the loop if the name of the received task is "finalize", or process the task otherwise.
181 - \c main: this setups the simulation.
183 How does SimGrid know that we need one master and several workers?
184 Because it's written in the deployment file (called \c
185 deployment0.xml), that we pass to MSG_create_environment() during the setup.
187 \include doc/tuto-msg/deployment0.xml
189 \section tuto-msg-exo1 Exercise 1: Simplifying the deployment file
191 In the provided example, the deployment file `deployment0.xml` is
192 tightly connected to the platform file `small_platform.xml` and adding
193 more workers quickly becomes a pain: You need to start them (at the
194 bottom of the file), add to inform the master that they are available
195 (in the master parameters list).
197 Instead, modify the simulator `masterworker.c` into `masterworker-exo1.c`
198 so that the master launches a worker process on all the other machines
199 at startup. The new deployment file `deployment1.xml` should be as
202 \include doc/tuto-msg/deployment1.xml
204 For that, the master needs to retrieve the list of hosts declared in
205 the platform, with the following functions (follow the links for their
209 int MSG_get_host_number(void);
210 xbt_dynar_t MSG_hosts_as_dynar(void);
211 void * xbt_dynar_to_array (xbt_dynar_t dynar);
214 Then, the master should start the worker processes with the following function:
217 msg_process_t MSG_process_create(const char *name, xbt_main_func_t code, void *data, msg_host_t host);
220 \subsection tuto-msg-exo1-config Increasing configurability
222 The worker processes wait for incomming messages on a channel which
223 name they need to know beforehand. In the provided code, each worker
224 uses the name of its host as a channel name. You can see this in the
225 receiver source code:
228 int res = MSG_task_receive(&(task), MSG_host_get_name(MSG_host_self()));
229 xbt_assert(res == MSG_OK, "MSG_task_receive failed");
232 This way, you can have at most one worker per host. To later study the
233 behavior of concurrent applications on the platform, we need to
234 alleviate this. Several solutions exist:
236 Now that the the master creates the workers, it knows their PID
237 (process ID -- given by @ref MSG_process_get_pid()), so you could use
238 it in the channel name.
240 Another possibility for the master is to determine a channel name
241 before the process creation, and give that name as a parameter to the
242 starting process. This is what the `data` parameter of @ref
243 MSG_process_create is meant for. You can pass any arbitrary pointer,
244 and the created process can retrieve this value later with the @ref
245 MSG_process_get_data and @ref MSG_process_self functions. Since we
246 want later to study concurrent applications, it is advised to use a
247 channel name such as `master_name:worker_name`.
249 A third possibility would be to inverse the communication architecture
250 and have the workers pulling work from the master. This require to
251 pass the master's channel to the workers.
253 \subsection tuto-msg-exo1-wrapup Wrap up
255 In this exercise, we reduced the amount of configuration that our
256 simulator requests. This is both a good idea, and a dangerous
257 trend. This simplification is an application of the good old DRY/SPOT
258 programming principle (Don't Repeat Yourself / Single Point Of Truth
259 -- <a href="https://en.wikipedia.org/wiki/Don%27t_repeat_yourself">more on wikipedia</a>),
260 and you really want your programming artefacts to follow these software engineering principles.
262 But at the same time, you should be careful in separating your
263 scientific contribution (the master/wokers algorithm) and the
264 artefacts used to test it (platform, deployment and workload). This is
265 why SimGrid forces you to expres your platform and deployment files in
266 XML instead of using a programming interface: it forces a clear
267 separation of concerns between things that are of very different
270 If you struggle with this exercise, have a look at
271 our solution in \ref doc/tuto-msg/masterworker-sol1.c
272 This is not perfect at all, and many other solutions would have been possible, of course.
274 \section tuto-msg-exo2 Exercise 2: Infinite amount of work, fixed experiment duration
276 In the current version, the number of tasks is defined through the
277 worker arguments. Hence, tasks are created at the very beginning of
278 the simulation. Instead, have the master dispatching tasks for a
279 predetermined amount of time. The tasks must now be created on demand
280 instead of beforehand.
282 Of course, usual time functions like `gettimeofday` will give you the
283 time on your real machine, which is prety useless in the
284 simulation. Instead, retrieve the time in the simulated world with
287 You can still stop your workers with a specific task as previously,
288 but other methods exist. You can forcefully stop processes with the
289 following functions, but be warned that SimGrid traditionnally had
290 issues with forcefully stopping procsses involved in computations or
291 communications. We hope that it's better now, but YMMV.
294 void MSG_process_kill(msg_process_t process);
295 int MSG_process_killall(int reset_PIDs);
298 Anyway, the new deployment `deployment2.xml` file should thus look
301 \include doc/tuto-msg/deployment2.xml
303 \subsection tuto-msg-exo2-verbosity Controlling the message verbosity
305 Not all messages are equally informative, so you probably want to
306 change most of the `XBT_INFO` into `XBT_DEBUG` so that they are hidden
307 by default. You could for example show only the total number of tasks
308 processed by default. You can still see the debug messages as follows:
311 ./masterworker examples/platforms/small_platform.xml deployment2.xml --log=msg_test.thres:debug
314 \subsection tuto-msg-exo2-wrapup Wrap up
316 Our imperfect solution to this exercise is available as @ref doc/tuto-msg/masterworker-sol2.c
317 But there is still much to improve in that code.
319 \section tuto-msg-exo3 Exercise 3: Understanding how competing applications behave
321 It is now time to start several applications at once, with the following `deployment3.xml` file.
323 \include doc/tuto-msg/deployment3.xml
325 Things happen when you do so, but it remains utterly difficult to
326 understand what's happening exactely. Even visualizations with pajeng
327 and Vite contain too much information to be useful: it is impossible
328 to understand which task belong to which application. To fix this, we
329 will categorize the tasks.
331 For that, first let each master create its own category of tasks with
332 @ref TRACE_category(), and then assign this category to each task using
333 @ref MSG_task_set_category().
335 The outcome can then be visualized as a Gantt-chart as follows:
338 ./masterworker examples/platforms/small_platform.xml deployment3.xml --cfg=tracing:yes --cfg=tracing/msg/process:yes
342 \subsection tuto-msg-exo3-further Going further
344 vite is not enough to understand the situation, because it does not
345 deal with categorization. That is why you should switch to R to
346 visualize your outcomes, as explained on <a
347 href="http://simgrid.gforge.inria.fr/contrib/R_visualization.php">this
350 As usual, you can explore our imperfect solution, in @ref doc/tuto-msg/masterworker-sol3.c.
352 \section tuto-msg-exo4 Exercise 4: Better scheduling: FCFS
354 You don't need a very advanced visualization solution to notice that
355 round-robin is completely suboptimal: most of the workers keep waiting
356 for more work. We will move to a First-Come First-Served mechanism
359 For that, your workers should explicitely request for work with a
360 message sent to a channel that is specific to their master. The name
361 of their private channel name should be attached (using the last
362 parameter of @ref MSG_task_create()) to the message sent, so that
363 their master can answer.
365 The master should serve requests in a round-robin manner, until the
366 time is up. Things get a bit more complex to stop the workers
367 afterward: the master cannot simply send a terminating task, as the
368 workers are blocked until their request for work is accepted. So
369 instead, the master should wait for incomming requests even once the
370 time is up, and answer with a terminating task.
372 Once it works, you will see that such as simple FCFS schema allows to
373 double the amount of tasks handled over time in this case.
375 \subsection tuto-msg-exo4-further Going further
377 From this, many things can easily be added. For example, you could:
378 - Allow workers to have several pending requests so as to overlap
379 communication and computations as much as possible. Non-blocking communication will probably become handy here.
380 - Add a performance measurement mechanism, enabling the master to make smart scheduling choices.
381 - Test your code on other platforms, from the `examples/platforms` directory in your archive.<br>
382 What is the largest number of tasks requiring 50e6 flops and 1e5
383 bytes that you manage to distribute and process in one hour on
384 `g5k.xml` (you should use `deployment_general.xml`)?
385 - Optimize not only for the amount of tasks handled, but also for the total energy dissipated.
386 - And so on. If you come up with a really nice extension, please share it with us so that we can extend this tutorial.
388 \section tuto-msg-further Where to go from here?
390 This tutorial is now terminated. You could keep reading the [online documentation][fn:4] or
391 [tutorials][fn:7], or you could head up to the example section to read some code.
393 \subsection tuto-msg-further-todo TODO: Points to improve for the next time
395 - Propose equivalent exercises and skeleton in java.
396 - Propose a virtualbox image with everything (simgrid, pajeng, ...) already set
398 - Ease the installation on mac OS X (binary installer) and
400 - Explain that programming in C or java and having a working
401 development environment is a prerequisite.
404 [fn:1]: http://triva.gforge.inria.fr/index.html
405 [fn:2]: http://hal.inria.fr/inria-00529569
406 [fn:3]: http://hal.inria.fr/hal-00738321
407 [fn:4]: http://simgrid.gforge.inria.fr/simgrid/latest/doc/
408 [fn:5]: https://github.com/schnorr/pajeng/
409 [fn:6]: http://vite.gforge.inria.fr/
410 [fn:7]: http://simgrid.org/tutorials/
417 * @example doc/tuto-msg/masterworker.c
418 * @example doc/tuto-msg/masterworker-sol1.c
419 * @example doc/tuto-msg/masterworker-sol2.c
420 * @example doc/tuto-msg/masterworker-sol3.c
421 * @example doc/tuto-msg/masterworker-sol4.c