6 SimGrid was conceived as a tool to study distributed algorithms. Its
7 :ref:`S4U interface <S4U_doc>` makes it easy to assess Cloud,
8 P2P, HPC, IoT, and other similar settings (:ref:`more info <index>`).
10 A typical SimGrid simulation is composed of several |Actors|_, that
11 execute user-provided functions. The actors have to explicitly use the
12 S4U interface to express their computation, communication, disk usage,
13 and other |Activities|_ so that they get reflected within the
14 simulator. These activities take place on **Resources** (|Hosts|_,
15 |Links|_, |Disks|_). SimGrid predicts the time taken by each
16 activity and orchestrates accordingly the actors waiting for the
17 completion of these activities.
19 Each actor executes a user-provided function on a simulated |Host|_
20 with which it can interact. Communications are not directly sent to
21 actors, but posted onto a |Mailbox|_ that serves as a rendez-vous point
22 between communicating actors.
24 .. |Actors| replace:: **Actors**
25 .. _Actors: app_s4u.html#s4u-actor
27 .. |Activities| replace:: **Activities**
28 .. _Activities: app_s4u.html#s4u-activity
30 .. |Hosts| replace:: **Hosts**
31 .. _Hosts: app_s4u.html#s4u-host
33 .. |Links| replace:: **Links**
34 .. _Links: app_s4u.html#s4u-link
36 .. |Disks| replace:: **Disks**
37 .. _Disks: app_s4u.html#s4u-disk
39 .. |VirtualMachines| replace:: **VirtualMachines**
40 .. _VirtualMachines: app_s4u.html#s4u-virtualmachine
42 .. |Host| replace:: **Host**
43 .. _Host: app_s4u.html#s4u-host
45 .. |Link| replace:: **Link**
46 .. _Link: app_s4u.html#s4u-link
48 .. |Mailbox| replace:: **Mailbox**
49 .. _Mailbox: app_s4u.html#s4u-mailbox
51 .. |Barrier| replace:: **Barrier**
52 .. _Barrier: app_s4u.html#s4u-barrier
54 .. |ConditionVariable| replace:: **ConditionVariable**
55 .. _ConditionVariable: app_s4u.html#s4u-conditionvariable
57 .. |Mutex| replace:: **Mutex**
58 .. _Mutex: app_s4u.html#s4u-mutex
60 **In the remainder of this tutorial**, you will discover a simple yet
61 fully-functioning example of SimGrid simulation: the Master/Workers
62 application. We will detail each part of the code and the necessary
63 configuration to make it work. After this tour, several exercises
64 are proposed to let you discover some of the SimGrid features, hands
65 on the keyboard. This practical session will be given in C++ or Python,
66 which you are supposed to know beforehand.
69 Discover the Master/Workers
70 ---------------------------
72 This section introduces an example of SimGrid simulation. This
73 simple application is composed of two kinds of actors: the **master**
74 is in charge of distributing some computational tasks to a set of
75 **workers** that execute them.
77 .. image:: /tuto_s4u/img/intro.svg
80 The provided code dispatches these tasks in `round-robin scheduling <https://en.wikipedia.org/wiki/Round-robin_scheduling>`_,
81 i.e. in circular order: tasks are dispatched to each worker one after the other, until all tasks are dispatched.
82 You will improve this scheme later in this tutorial.
87 Let's start with the code of the master. It is represented by the
88 *master* function below. This simple function takes at least 3
89 parameters (the number of tasks to dispatch, their computational size
90 in flops to compute, and their communication size in bytes to
91 exchange). Every parameter after the third one must be the name of a
92 host on which a worker is waiting for something to compute.
94 Then, the tasks are sent one after the other, each on a mailbox named
95 after the worker's hosts. On the other side, a given worker (which
96 code is given below) waits for incoming tasks on its mailbox.
99 In the end, once all tasks are dispatched, the master dispatches
100 another task per worker, but this time with a negative amount of flops
101 to compute. Indeed, this application decided by convention, that the
102 workers should stop when encountering such a negative compute_size.
108 At the end of the day, the only SimGrid specific functions used in
109 this example are :cpp:func:`simgrid::s4u::Mailbox::by_name` (to retrieve or create a mailbox) and
110 :cpp:func:`simgrid::s4u::Mailbox::put` (so send something over a mailbox). Also, :c:macro:`XBT_INFO` is used
111 as a replacement to ``printf()`` or ``std::cout`` to ensure that the messages
112 are nicely logged along with the simulated time and actor name.
114 .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
116 :start-after: master-begin
117 :end-before: master-end
119 .. group-tab:: Python
121 At the end of the day, the only SimGrid specific functions used in
122 this example are :py:func:`simgrid.Mailbox.by_name` (to retrieve or create a mailbox) and
123 :py:func:`simgrid.Mailbox.put` (so send something over a mailbox). Also, :py:func:`simgrid.this_actor.info` is used
124 as a replacement to `print` to ensure that the messages
125 are nicely logged along with the simulated time and actor name.
127 .. literalinclude:: ../../examples/python/app-masterworkers/app-masterworkers.py
129 :start-after: master-begin
130 :end-before: master-end
132 Then comes the code of the worker actors. This function expects no
133 parameter from its vector of strings. Its code is very simple: it
134 expects messages on the mailbox that is named after its host. As long as it gets valid
135 computation requests (whose compute_amount is positive), it computes
136 this task and waits for the next one.
142 The worker retrieves its own host with
143 :cpp:func:`simgrid::s4u::this_actor::get_host`. The
144 :ref:`simgrid::s4u::this_actor <API_s4u_this_actor>`
145 namespace contains many such helping functions.
147 .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
149 :start-after: worker-begin
150 :end-before: worker-end
152 .. group-tab:: Python
154 The worker retrieves its own host with :py:func:`simgrid.this_actor.get_host`. The
155 :ref:`this_actor <API_s4u_this_actor>` object contains many such helping functions.
157 .. literalinclude:: ../../examples/python/app-masterworkers/app-masterworkers.py
159 :start-after: worker-begin
160 :end-before: worker-end
162 Starting the Simulation
163 .......................
165 And this is it. In only a few lines, we defined the algorithm of our master/workers example.
171 That being said, an algorithm alone is not enough to define a
172 simulation: SimGrid is a library, not a program. So you need to define
173 your own ``main()`` function as follows. This function is in charge of
174 creating a SimGrid simulation engine (on line 3), register the actor
175 functions to the engine (on lines 7 and 8), load the simulated platform
176 from its description file (on line 11), map actors onto that platform
177 (on line 12) and run the simulation until its completion on line 15.
179 .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
181 :start-after: main-begin
182 :end-before: main-end
185 .. group-tab:: Python
187 That being said, an algorithm alone is not enough to define a simulation:
188 you need a main block to setup the simulation and its components as follows.
189 This code creates a SimGrid simulation engine (on line 4), registers the actor
190 functions to the engine (on lines 7 and 8), loads the simulated platform
191 from its description file (on line 11), map actors onto that platform
192 (on line 12) and run the simulation until its completion on line 15.
194 .. literalinclude:: ../../examples/python/app-masterworkers/app-masterworkers.py
196 :start-after: main-begin
197 :end-before: main-end
200 Finally, this example requires a platform file and a deployment file.
205 Platform files define the simulated platform on which the provided
206 application will take place. It contains one or several **Network
207 Zone** |api_s4u_NetZone|_ that contains both |Host|_ and |Link|_
208 Resources, as well as routing information.
210 Such files can get rather long and boring, so the example below is
211 only an excerpt of the full ``examples/platforms/small_platform.xml``
212 file. For example, most routing information is missing, and only the
213 route between the hosts Tremblay and Fafard is given. This path
214 traverses 6 links (named 4, 3, 2, 0, 1, and 8). There are several
215 examples of platforms in the archive under ``examples/platforms``.
217 .. |api_s4u_NetZone| image:: /img/extlink.png
220 .. _api_s4u_NetZone: app_s4u.html#s4u-netzone
222 .. |api_s4u_Link| image:: /img/extlink.png
225 .. _api_s4u_Link: app_s4u.html#s4u-link
227 .. literalinclude:: ../../examples/platforms/small_platform.xml
229 :lines: 1-10,12-20,56-62,192-
230 :caption: (excerpts of the small_platform.xml file)
235 Deployment files specify the execution scenario: it lists the actors
236 that should be started, along with their parameters. In the following
237 example, we start 6 actors: one master and 5 workers.
239 .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers_d.xml
245 This time, we have all parts: once the program is compiled, we can execute it as follows.
251 Note how the :c:macro:`XBT_INFO` requests turned into informative messages.
253 .. "WARNING: non-whitespace stripped by dedent" is expected here as we remove the $ marker this way
255 .. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh
257 :start-after: s4u-app-masterworkers-fun
258 :prepend: $$$ ./masterworkers platform.xml deploy.xml
262 .. group-tab:: Python
264 Note how the :py:func:`simgrid.this_actor.info` calls turned into informative messages.
266 .. literalinclude:: ../../examples/python/app-masterworkers/app-masterworkers.tesh
268 :start-after: app-masterworkers_d.xml
269 :prepend: $$$ python ./app-masterworkers.py platform.xml deploy.xml
273 Each example included in the SimGrid distribution comes with a `tesh`
274 file that presents how to start the example once compiled, along with
275 the expected output. These files are used for the automatic testing of
276 the framework but can be used to see the examples' output without
277 compiling them. See e.g. the file
278 `examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh <https://framagit.org/simgrid/simgrid/-/blob/master/examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh>`_.
279 Lines starting with `$` are the commands to execute;
280 lines starting with `>` are the expected output of each command, while
281 lines starting with `!` are configuration items for the test runner.
287 In this section, you will modify the example presented earlier to
288 explore the quality of the proposed algorithm. It already works, and
289 the simulation prints things, but the truth is that we have no idea of
290 whether this is a good algorithm to dispatch tasks to the workers.
291 This very simple setting raises many interesting questions:
293 .. image:: /tuto_s4u/img/question.svg
296 - Which algorithm should the master use? Or should the worker decide
299 Round Robin is not an efficient algorithm when all tasks are not
300 processed at the same speed. It would probably be more efficient
301 if the workers were asking for tasks when ready.
303 - Should tasks be grouped in batches or sent separately?
305 The workers will starve if they don't get the tasks fast
306 enough. One possibility to reduce latency would be to send tasks
307 in pools instead of one by one. But if the pools are too big, the
308 load balancing will likely get uneven, in particular when
309 distributing the last tasks.
311 - How does the quality of such an algorithm dependent on the platform
312 characteristics and on the task characteristics?
314 Whenever the input communication time is very small compared to
315 processing time and workers are homogeneous, it is likely that the
316 round-robin algorithm performs very well. Would it still hold true
317 when transfer time is not negligible? What if some tasks are
318 performed faster on some specific nodes?
320 - The network topology interconnecting the master and the workers
321 may be quite complicated. How does such a topology impact the
324 When data transfers are the bottleneck, it is likely that good
325 modeling of the platform becomes essential. The SimGrid platform
326 models are particularly handy to account for complex platform
329 - What is the best applicative topology?
331 Is a flat master-worker deployment sufficient? Should we go for a
332 hierarchical algorithm, with some forwarders taking large pools of
333 tasks from the master, each of them distributing their tasks to a
334 sub-pool of workers? Or should we introduce super-peers,
335 duplicating the master's role in a peer-to-peer manner? Do the
336 algorithms require a perfect knowledge of the network?
338 - How is such an algorithm sensitive to external workload variation?
340 What if bandwidth, latency, and computing speed can vary with no
341 warning? Shouldn't you study whether your algorithm is sensitive
342 to such load variations?
344 - Although an algorithm may be more efficient than another, how does
345 it interfere with unrelated applications executing on the same
348 **SimGrid was invented to answer such questions.** Do not believe the
349 fools saying that all you need to study such settings is a simple
350 discrete event simulator. Do you really want to reinvent the wheel,
351 debug and optimize your own tool, and validate its models against real
352 settings for ages, or do you prefer to sit on the shoulders of a
353 giant? With SimGrid, you can focus on your algorithm. The whole
354 simulation mechanism is already working.
356 Here is the visualization of a SimGrid simulation of two master-worker
357 applications (one in light gray and the other in dark gray) running in
358 concurrence and showing resource usage over a long period of time. It
359 was obtained with the Triva software.
361 .. image:: /tuto_s4u/img/result.png
367 The easiest way to take the tutorial is to use the dedicated Docker image.
368 Once you `installed Docker itself <https://docs.docker.com/install/>`_, simply do the following:
370 .. code-block:: console
372 $ docker pull simgrid/tuto-s4u
373 $ mkdir ~/simgrid-tutorial
374 $ docker run --user $UID:$GID -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash
376 This will start a new container with all you need to take this
377 tutorial, and create a ``simgrid-tutorial`` directory in your home on
378 your host machine that will be visible as ``/source/tutorial`` within the
379 container. You can then edit the files you want with your favorite
380 editor in ``~/simgrid-tutorial``, and compile them within the
381 container to enjoy the provided dependencies.
385 Any change to the container out of ``/source/tutorial`` will be lost
386 when you log out of the container, so don't edit the other files!
388 All needed dependencies are already installed in this container
389 (SimGrid, a C++ compiler, CMake, pajeng, and R). Vite being only
390 optional in this tutorial, it is not installed to reduce the image
393 The docker does not run as root, so that the files can easily be exchanged between within the container and the outer world.
394 If you need to run a command as root within the container, simply type the following in another terminal to join the same container as root:
396 .. code-block:: console
398 $ docker container ls
399 # This lists all containers running on your machine. For example:
400 # CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
401 # 7e921b1b18a7 simgrid/stable "bash" 7 minutes ago Up 7 minutes simgrid
403 $ docker exec --user root -it simgrid bash
405 The code template is available under ``/source/simgrid-template-s4u.git``
406 in the image. You should copy it to your working directory and
407 recompile it when you first log in:
409 .. code-block:: console
411 $ # Make sure the simgrid-tutorial directory can be read and written by the non-root user
412 $ sudo chown $UID:$GID ~/simgrid-tutorial
413 $ # Connect to the running container if needed
414 $ docker exec --user $UID:$GID -ti simgrid bash
415 $container) cp -r /source/simgrid-template-s4u.git/* /source/tutorial
416 $container) cd /source/tutorial
420 Using your Computer Natively
421 ............................
427 To take the tutorial on your machine, you first need to :ref:`install
428 a recent version of SimGrid <install>`, a C++ compiler, and also
429 ``pajeng`` to visualize the traces. You may want to install `Vite
430 <http://vite.gforge.inria.fr/>`_ to get a first glance at the traces.
431 The provided code template requires CMake to compile. On Debian and
432 Ubuntu for example, you can get them as follows:
434 .. code-block:: console
436 $ sudo apt install simgrid pajeng cmake g++ vite
438 An initial version of the source code is provided on framagit. This
439 template compiles with CMake. If SimGrid is correctly installed, you
440 should be able to clone the `repository
441 <https://framagit.org/simgrid/simgrid-template-s4u>`_ and recompile
442 everything as follows:
444 .. code-block:: console
446 # (exporting SimGrid_PATH is only needed if SimGrid is installed in a non-standard path)
447 $ export SimGrid_PATH=/where/to/simgrid
449 $ git clone https://framagit.org/simgrid/simgrid-template-s4u.git
450 $ cd simgrid-template-s4u/
454 If you struggle with the compilation, then you should double-check
455 your :ref:`SimGrid installation <install>`. On need, please refer to
456 the :ref:`Troubleshooting your Project Setup
457 <install_yours_troubleshooting>` section.
459 .. group-tab:: Python
461 To take the tutorial on your machine, you first need to :ref:`install
462 a recent version of SimGrid <install>` and ``pajeng`` to visualize the
463 traces. You may want to install `Vite <http://vite.gforge.inria.fr/>`_ to get a first glance at the traces.
464 On Debian and Ubuntu for example, you can get them as follows:
466 .. code-block:: console
468 $ sudo apt install simgrid pajeng vite
470 An initial version of the source code is provided on framagit.
471 If SimGrid is correctly installed, you should be able to clone the `repository
472 <https://framagit.org/simgrid/simgrid-template-s4u>`_ and execute it as follows:
474 .. code-block:: console
476 $ git clone https://framagit.org/simgrid/simgrid-template-s4u.git
477 $ cd simgrid-template-s4u/
478 $ python master-workers.py small_platform.xml master-workers_d.xml
480 If you get some errors, then you should double-check
481 your :ref:`SimGrid installation <install>`. On need, please refer to
482 the :ref:`Troubleshooting your Project Setup <install_yours_troubleshooting>` section.
486 If you use the stable version of Debian 11, Ubuntu 21.04 or Ubuntu 21.10, then you need the right version of this tutorial
487 (add ``--branch simgrid-v3.25`` as below). These distributions only contain SimGrid v3.25 while the latest version of this
488 tutorial needs at least SimGrid v3.27.
490 .. code-block:: console
492 $ git clone --branch simgrid-v3.25 https://framagit.org/simgrid/simgrid-template-s4u.git
494 For R analysis of the produced traces, you may want to install R
495 and the `pajengr <https://github.com/schnorr/pajengr#installation/>`_ package.
497 .. code-block:: console
499 # install R and necessary packages
500 $ sudo apt install r-base r-cran-devtools r-cran-tidyverse
501 # install pajengr dependencies
502 $ sudo apt install git cmake flex bison
503 # install the pajengr R package
504 $ Rscript -e "library(devtools); install_github('schnorr/pajengr');"
507 Discovering the Provided Code
508 .............................
514 Please compile and execute the provided simulator as follows:
516 .. code-block:: console
518 $ make master-workers
519 $ ./master-workers small_platform.xml master-workers_d.xml
521 If you get an error message complaining that ``simgrid::s4u::Mailbox::get()`` does not exist,
522 then your version of SimGrid is too old for the version of the tutorial that you got. Check again previous section.
524 .. group-tab:: Python
526 Please execute the provided simulator as follows:
528 .. code-block:: console
530 $ python master-workers.py small_platform.xml master-workers_d.xml
532 If you get an error stating that the simgrid module does not exist, you need to get a newer version of SimGrid.
533 You may want to take the tutorial from the docker to get the newest version.
535 For a more "fancy" output, you can use simgrid-colorizer.
537 .. code-block:: console
540 $ ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer
543 $ python master-workers.py small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer
545 If you installed SimGrid to a non-standard path, you may have to
546 specify the full path to simgrid-colorizer on the above line, such as
547 ``/opt/simgrid/bin/simgrid-colorizer``. If you did not install it at all,
548 you can find it in <simgrid_root_directory>/bin/colorize.
550 For a classical Gantt-Chart visualization, you can use `Vite
551 <http://vite.gforge.inria.fr/>`_ if you have it installed, as
552 follows. But do not spend too much time installing Vite, because there
553 is a better way to visualize SimGrid traces (see below).
555 .. code-block:: console
558 $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
560 $ python master-workers.py small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
562 # Visualize the produced trace
565 .. image:: /tuto_s4u/img/vite-screenshot.png
570 If you use an older version of SimGrid (before v3.26), you should use
571 ``--cfg=tracing/msg/process:yes`` instead of ``--cfg=tracing/actor:yes``.
573 If you want the full power to visualize SimGrid traces, you need
574 to use R. As a start, you can download this `starter script
575 <https://framagit.org/simgrid/simgrid/raw/master/docs/source/tuto_s4u/draw_gantt.R>`_
576 and use it as follows:
578 .. code-block:: console
581 $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
583 $ python master-workers.py small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
585 # Visualize the produced trace
586 $ Rscript draw_gantt.R simgrid.trace
588 It produces a ``Rplots.pdf`` with the following content:
590 .. image:: /tuto_s4u/img/Rscript-screenshot.png
594 Lab 1: Simpler deployments
595 --------------------------
597 .. rst-class:: compact-list
601 * Get your hands on the code and change the communication pattern
602 * Discover the Mailbox mechanism
604 In the provided example, adding more workers quickly becomes a pain:
605 You need to start them (at the bottom of the file) and inform the
606 master of its availability with an extra parameter. This is mandatory
607 if you want to inform the master of where the workers are running. But
608 actually, the master does not need to have this information.
610 We could leverage the mailbox mechanism flexibility, and use a sort of
611 yellow page system: Instead of sending data to the worker running on
612 Fafard, the master could send data to the third worker. Ie, instead of
613 using the worker location (which should be filled in two locations),
614 we could use their ID (which should be filled in one location
617 This could be done with the following deployment file. It's
618 not shorter than the previous one, but it's still simpler because the
619 information is only written once. It thus follows the `DRY
620 <https://en.wikipedia.org/wiki/Don't_repeat_yourself>`_ `SPOT
621 <http://wiki.c2.com/?SinglePointOfTruth>`_ design principle.
623 .. literalinclude:: tuto_s4u/deployment1.xml
630 Copy your ``master-workers.cpp`` into ``master-workers-lab1.cpp`` and
631 add a new executable into ``CMakeLists.txt``. Then modify your worker
632 function so that it gets its mailbox name not from the name of its
633 host, but from the string passed as ``args[1]``. The master will send
634 messages to all workers based on their number, for example as follows:
638 for (int i = 0; i < tasks_count; i++) {
639 std::string worker_rank = std::to_string(i % workers_count);
640 std::string mailbox_name = "worker-" + worker_rank;
641 simgrid::s4u::Mailbox* mailbox = simgrid::s4u::Mailbox::by_name(mailbox_name);
648 .. group-tab:: Python
650 Copy your ``master-workers.py`` into ``master-workers-lab1.py`` then
652 function so that it gets its mailbox name not from the name of its
653 host, but from the string passed as ``args[0]``. The master will send
654 messages to all workers based on their number, for example as follows:
658 for i in range(tasks_count):
659 mailbox = Mailbox.by_name(str(i % worker_count))
665 The mailboxes are a very powerful mechanism in SimGrid, allowing many
666 interesting application settings. They may feel unusual if you are
667 used to BSD sockets or other classical systems, but you will soon
668 appreciate their power. They are only used to match
669 communications but have no impact on the communication
670 timing. ``put()`` and ``get()`` are matched regardless of their
671 initiators' location and then the real communication occurs between
672 the involved parties.
674 Please refer to the full `Mailboxes' documentation <app_s4u.html#s4u-mailbox>`_
678 Lab 2: Using the Whole Platform
679 -------------------------------
681 .. rst-class:: compact-list
685 * Interact with the platform (get the list of all hosts)
686 * Create actors directly from your program instead of the deployment file
688 It is now easier to add a new worker, but you still have to do it
689 manually. It would be much easier if the master could start the
690 workers on its own, one per available host in the platform. The new
691 deployment file should be as simple as:
693 .. literalinclude:: tuto_s4u/deployment2.xml
697 Creating the workers from the master
698 ....................................
704 For that, the master needs to retrieve the list of hosts declared in
705 the platform with :cpp:func:`simgrid::s4u::Engine::get_all_hosts`.
706 Then, the master should start the worker actors with
707 :cpp:func:`simgrid::s4u::Actor::create`.
709 ``Actor::create(name, host, func, params...)`` is a very flexible
710 function. Its third parameter is the function that the actor should
711 execute. This function can take any kind of parameter, provided that
712 you pass similar parameters to ``Actor::create()``. For example, you
713 could have something like this:
717 void my_actor(int param1, double param2, std::string param3) {
720 int main(int argc, char argv**) {
722 simgrid::s4u::ActorPtr actor;
723 actor = simgrid::s4u::Actor::create("name", simgrid::s4u::Host::by_name("the_host"),
724 &my_actor, 42, 3.14, "thevalue");
728 .. group-tab:: Python
730 For that, the master needs to retrieve the list of hosts declared in
731 the platform with :py:func:`simgrid.Engine.get_all_hosts`. Since this method is not static,
732 you may want to call it on the Engine instance, as in ``Engine.instance().get_all_hosts()``.
733 Then, the master should start the worker actors with :py:func:`simgrid.Actor.create`.
735 ``Actor.create(name, host, func, params...)`` is a very flexible
736 function. Its third parameter is the function that the actor should
737 execute. This function can take any kind of parameter, provided that
738 you pass similar parameters to ``Actor.create()``. For example, you
739 could have something like this:
741 .. code-block:: python
743 def my_actor(param1, param2, param3):
744 # your code comes here
745 actor = simgrid.Actor.create("name", the_host, my_actor, 42, 3.14, "thevalue")
748 Master-Workers Communication
749 ............................
751 Previously, the workers got from their parameter the name of the
752 mailbox they should use. We can still do so: the master should build
753 such a parameter before using it in the ``Actor::create()`` call. The
754 master could even pass directly the mailbox as a parameter to the
757 Since we want later to study concurrent applications, it is advised to
758 use a mailbox name that is unique over the simulation even if there is
759 more than one master.
765 One possibility for that is to use the actor ID (aid) of each worker
766 as a mailbox name. The master can retrieve the aid of the newly
767 created actor with :cpp:func:`simgrid::s4u::Actor::get_pid()` while the actor itself can
768 retrieve its own aid with :cpp:func:`simgrid::s4u::this_actor::get_pid()`.
769 The retrieved value is an :cpp:type:`aid_t`, which is an alias for ``long``.
771 .. group-tab:: Python
773 One possibility for that is to use the actor ID of each worker
774 as a mailbox name. The master can retrieve the aid of the newly
775 created actor with :py:func:`simgrid.Actor.pid` while the actor itself can
776 retrieve its own aid with :py:func:`simgrid.this_actor.get_pid()`.
781 In this exercise, we reduced the amount of configuration that our
782 simulator requests. This is both a good idea and a dangerous
783 trend. This simplification is another application of the good old DRY/SPOT
784 programming principle (`Don't Repeat Yourself / Single Point Of Truth
785 <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_), and you
786 really want your programming artifacts to follow these software
787 engineering principles.
789 But at the same time, you should be careful in separating your
790 scientific contribution (the master/workers algorithm) and the
791 artifacts used to test it (platform, deployment, and workload). This is
792 why SimGrid forces you to express your platform and deployment files
793 in XML instead of using a programming interface: it forces a clear
794 separation of concerns between things of different nature.
796 Lab 3: Fixed Experiment Duration
797 --------------------------------
799 .. rst-class:: compact-list
803 * Forcefully kill actors, and stop the simulation at a given point of time
804 * Control the logging verbosity
806 In the current version, the number of tasks is defined through the
807 worker arguments. Hence, tasks are created at the very beginning of
808 the simulation. Instead, have the master dispatching tasks for a
809 predetermined amount of time. The tasks must now be created on need
810 instead of beforehand.
812 Of course, usual time functions like ``gettimeofday`` will give you the
813 time on your real machine, which is pretty useless in the
814 simulation. Instead, retrieve the time in the simulated world with
815 :cpp:func:`simgrid::s4u::Engine::get_clock` (C++) or
816 :py:func:`simgrid.Engine.get_clock()`) (Python).
818 You can still stop your workers with a specific task as previously,
819 or you may kill them forcefully with :cpp:func:`simgrid::s4u::Actor::kill` (C++)
820 :py:func:`simgrid.Actor.kill` (Python).
822 Anyway, the new deployment `deployment3.xml` file should thus look
825 .. literalinclude:: tuto_s4u/deployment3.xml
828 Controlling the message verbosity
829 .................................
831 Not all messages are equally informative, so you probably want to
832 change some of the *info* messages (C: :c:macro:`XBT_INFO`; Python: :py:func:`simgrid.this_actor.info`)
833 into *debug* messages`(C: :c:macro:`XBT_DEBUG`; Python: :py:func:`simgrid.this_actor.debug`) so that they are
834 hidden by default. For example, you may want to use an *info* message once
835 every 100 tasks and *debug* when sending all the other tasks. Or
836 you could show only the total number of tasks processed by
837 default. You can still see the debug messages as follows:
839 .. code-block:: console
841 $ ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug
843 Lab 4: What-if analysis
844 -----------------------
846 .. rst-class:: compact-list
850 * Change the platform characteristics during the simulation.
851 * Explore other communication patterns.
856 Attach a profile to your hosts, so that their computational speed automatically vary over time, modeling an external load on these machines.
857 This can be done with :cpp:func:`simgrid::s4u::Host::set_speed_profile` (C++) or :py:func:`simgrid.Host.set_speed_profile` (Python).
859 Make it so that one of the hosts get really really slow, and observe how your whole application performance decreases.
860 This is because one slow host slows down the whole process. Instead of a round-robin dispatch push,
861 you should completely reorganize your application in a First-Come First-Served manner (FCFS).
862 Actors should pull a task whenever they are ready, so that fast actors can overpass slow ones in the queue.
864 There is two ways to implement that: either the workers request a task to the master by sending their name to a specific mailbox,
865 or the master directly pushes the tasks to a centralized mailbox from which the workers pull their work. The first approach is closer
866 to what would happen with communications based on BSD sockets while the second is closer to message queues. You could also decide to
867 model your socket application in the second manner if you want to neglect these details and keep your simulator simple. It's your decision.
869 Changing the communication schema can be a bit hairy, but once it works, you will see that such as simple FCFS schema allows one to greatly
870 increase the amount of tasks handled over time here. Things may be different with another platform file.
875 Let's now modify the communication speed between hosts.
877 Retrieve a link from its name with :cpp:func:`simgrid::s4u::Link::by_name()` (C++) or :py:func:`simgrid.Link.by_name()` (python).
879 Retrieve all links in the platform with :cpp:func:`simgrid::s4u::Engine::get_all_links()` (C++) or :py:func:`simgrid.Engine.get_all_links()` (python).
881 Retrieve the list of links from one host to another with :cpp:func:`simgrid::s4u::Host::route_to` (C++) or :py:func:`simgrid.Host.route_to` (python).
883 Modify the bandwidth of a given link with :cpp:func:`simgrid::s4u::Link::set_bandwidth` (C++) or :py:func:`simgrid.Link.set_bandwidth` (python).
884 You can even have the bandwidth automatically vary over time with :cpp:func:`simgrid::s4u::Link::set_bandwidth_profile` (C++) or :py:func:`simgrid.Link.set_bandwidth_profile` (python).
886 Once implemented, you will notice that slow communications may still result in situations
887 where one worker only works at a given point of time. To overcome that, your master needs
888 to send data to several workers in parallel, using
889 :cpp:func:`simgrid::s4u::Mailbox::put_async` (C++) or :py:func:`simgrid.Mailbox.put_async` (Python)
890 to start several communications in parallel, and
891 :cpp:func:`simgrid::s4u::Comm::wait_any` (C++) or and :py:func:`simgrid.Comm.wait_any` (Python)
892 to react to the completion of one of these communications. Actually, since this code somewhat tricky
893 to write, it's provided as :ref:`an example <s4u_ex_communication>` in the distribution (search for
894 ``wait_any`` in that page).
896 Dealing with failures
897 .....................
899 Turn a given link off with :cpp:func:`simgrid::s4u::Link::turn_off` (C++) or :py:func:`simgrid.Link.turn_off` (python).
900 You can even implement churn where a link automatically turn off and on again over time with :cpp:func:`simgrid::s4u::Link::set_state_profile` (C++) or :py:func:`simgrid.Link.set_state_profile` (python).
902 If a link fails while you try to use it, ``wait()`` will raise a ``NetworkFailureException`` that you need to catch.
903 Again, there is a nice example demoing this feature, :ref:`under platform-failures <s4u_ex_communication>`.
905 Lab 5: Competing Applications
906 -----------------------------
908 .. rst-class:: compact-list
912 * Advanced vizualization through tracing categories
915 It is now time to start several applications at once, with the following ``deployment5.xml`` file.
917 .. literalinclude:: tuto_s4u/deployment5.xml
920 Things happen when you do so, but it remains utterly difficult to
921 understand what's happening exactly. Even Gantt visualizations
922 contain too much information to be useful: it is impossible to
923 understand which task belongs to which application. To fix this, we
924 will categorize the tasks.
926 Instead of starting the execution in one function call only with
927 ``this_actor::execute(cost)``, you need to
928 create the execution activity, set its tracing category, start it
929 and wait for its completion, as follows.
935 Use :cpp:func:`simgrid::s4u::Exec::set_tracing_category` to change the category of an execution.
939 simgrid::s4u::ExecPtr exec = simgrid::s4u::this_actor::exec_init(compute_cost);
940 exec->set_tracing_category(category);
941 // exec->start() is optional here as wait() starts the activity on need
944 You can shorten this code as follows:
948 simgrid::s4u::this_actor::exec_init(compute_cost)->set_tracing_category(category)->wait();
950 .. group-tab:: Python
952 Use :py:func:`simgrid.Exec.set_tracing_category` to change the category of an execution.
954 .. code-block:: python
956 exec = simgrid:.this_actor.exec_init(compute_cost)
957 exec.set_tracing_category(category)
958 # exec.start() is optional here as wait() starts the activity on need
961 You can shorten this code as follows:
963 .. code-block:: python
965 simgrid.this_actor.exec_init(compute_cost).set_tracing_category(category).wait()
968 Visualizing the result
969 .......................
971 vite is not enough to understand the situation, because it does not
972 deal with categorization. This time, you absolutely must switch to R,
973 as explained on `this page
974 <https://simgrid.org/contrib/R_visualization.html>`_.
978 Include here the minimal setting to view something in R.
983 From this, many things can easily be added. For example, you could:
985 - Allow workers to have several pending requests to overlap
986 communication and computations as much as possible. Non-blocking
987 communication will probably become handy here.
988 - Add a performance measurement mechanism, enabling the master to make smart scheduling choices.
989 - Test your code on other platforms, from the ``examples/platforms``
990 directory in your archive.
992 What is the largest number of tasks requiring 50e6 flops and 1e5
993 bytes that you manage to distribute and process in one hour on
995 - Optimize not only for the number of tasks handled but also for the total energy dissipated.
996 - And so on. If you come up with a nice extension, please share
997 it with us so that we can extend this tutorial.
1002 This tutorial is now terminated. You could keep reading the online documentation and
1003 tutorials, or you could head up to the :ref:`example section <s4u_examples>` to read some code.
1009 .. LocalWords: SimGrid