=====================
SimGrid was conceived as a tool to study distributed algorithms. Its
-modern :ref:`S4U interface <S4U_doc>` makes it easy to assess Cloud,
-P2P, HPC, IoT, and similar settings.
+:ref:`S4U interface <S4U_doc>` makes it easy to assess Cloud,
+P2P, HPC, IoT, and other similar settings (:ref:`more info <index>`).
A typical SimGrid simulation is composed of several |Actors|_, that
execute user-provided functions. The actors have to explicitly use the
Each actor executes a user-provided function on a simulated |Host|_
with which it can interact. Communications are not directly sent to
-actors, but posted onto a |Mailbox|_ that serves as a rendezvous point
+actors, but posted onto a |Mailbox|_ that serves as a rendez-vous point
between communicating actors.
.. |Actors| replace:: **Actors**
application. We will detail each part of the code and the necessary
configuration to make it work. After this tour, several exercises
are proposed to let you discover some of the SimGrid features, hands
-on the keyboard. This practical session will be given in C++, which you
-are supposed to know beforehand.
+on the keyboard. This practical session will be given in C++ or Python,
+which you are supposed to know beforehand.
Discover the Master/Workers
Then, the tasks are sent one after the other, each on a mailbox named
after the worker's hosts. On the other side, a given worker (which
-code is given below) waits for incoming tasks on its
+code is given below) waits for incoming tasks on its
mailbox.
execute it as follows. Note how the XBT_INFO() requests turned into
informative messages.
-.. "WARNING: Over dedent has detected" is expected here as we remove the $ marker this way
+.. "WARNING: non-whitespace stripped by dedent" is expected here as we remove the $ marker this way
.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh
:language: shell
image. Once you `installed Docker itself
<https://docs.docker.com/install/>`_, simply do the following:
-.. code-block:: shell
+.. code-block:: console
- docker pull simgrid/tuto-s4u
- docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash
+ $ docker pull simgrid/tuto-s4u
+ $ docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/source/tutorial simgrid/tuto-s4u bash
This will start a new container with all you need to take this
tutorial, and create a ``simgrid-tutorial`` directory in your home on
in the image. You should copy it to your working directory and
recompile it when you first log in:
-.. code-block:: shell
+.. code-block:: console
- cp -r /source/simgrid-template-s4u.git/* /source/tutorial
- cd /source/tutorial
- cmake .
- make
+ $ cp -r /source/simgrid-template-s4u.git/* /source/tutorial
+ $ cd /source/tutorial
+ $ cmake .
+ $ make
Using your Computer Natively
............................
-To take the tutorial on your machine, you first need to :ref:`install
+To take the tutorial on your machine, you first need to :ref:`install
a recent version of SimGrid <install>`, a C++ compiler, and also
``pajeng`` to visualize the traces. You may want to install `Vite
<http://vite.gforge.inria.fr/>`_ to get a first glance at the traces.
The provided code template requires CMake to compile. On Debian and
Ubuntu for example, you can get them as follows:
-.. code-block:: shell
+.. code-block:: console
- sudo apt install simgrid pajeng cmake g++ vite
+ $ sudo apt install simgrid pajeng cmake g++ vite
For R analysis of the produced traces, you may want to install R
and the `pajengr <https://github.com/schnorr/pajengr#installation/>`_ package.
-.. code-block:: shell
+.. code-block:: console
- sudo apt install r-base r-cran-devtools cmake flex bison
- Rscript -e "library(devtools); install_github('schnorr/pajengr');"
+ # install R and necessary packages
+ $ sudo apt install r-base r-cran-devtools r-cran-tidyverse
+ # install pajengr dependencies
+ $ sudo apt install git cmake flex bison
+ # install the pajengr R package
+ $ Rscript -e "library(devtools); install_github('schnorr/pajengr');"
An initial version of the source code is provided on framagit. This
template compiles with CMake. If SimGrid is correctly installed, you
<https://framagit.org/simgrid/simgrid-template-s4u>`_ and recompile
everything as follows:
-.. code-block:: shell
+.. code-block:: console
# (exporting SimGrid_PATH is only needed if SimGrid is installed in a non-standard path)
- export SimGrid_PATH=/where/to/simgrid
+ $ export SimGrid_PATH=/where/to/simgrid
- git clone https://framagit.org/simgrid/simgrid-template-s4u.git
- cd simgrid-template-s4u/
- cmake .
- make
+ $ git clone https://framagit.org/simgrid/simgrid-template-s4u.git
+ $ cd simgrid-template-s4u/
+ $ cmake .
+ $ make
If you struggle with the compilation, then you should double-check
your :ref:`SimGrid installation <install>`. On need, please refer to
Please compile and execute the provided simulator as follows:
-.. code-block:: shell
+.. code-block:: console
- make master-workers
- ./master-workers small_platform.xml master-workers_d.xml
+ $ make master-workers
+ $ ./master-workers small_platform.xml master-workers_d.xml
For a more "fancy" output, you can use simgrid-colorizer.
-.. code-block:: shell
+.. code-block:: console
- ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer
+ $ ./master-workers small_platform.xml master-workers_d.xml 2>&1 | simgrid-colorizer
If you installed SimGrid to a non-standard path, you may have to
specify the full path to simgrid-colorizer on the above line, such as
follows. But do not spend too much time installing Vite, because there
is a better way to visualize SimGrid traces (see below).
-.. code-block:: shell
+.. code-block:: console
- ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
- vite simgrid.trace
+ $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
+ $ vite simgrid.trace
.. image:: /tuto_s4u/img/vite-screenshot.png
:align: center
+.. note::
+
+ If you use an older version of SimGrid (before v3.26), you should use
+ ``--cfg=tracing/msg/process:yes`` instead of ``--cfg=tracing/actor:yes``.
+
If you want the full power to visualize SimGrid traces, you need
to use R. As a start, you can download this `starter script
<https://framagit.org/simgrid/simgrid/raw/master/docs/source/tuto_s4u/draw_gantt.R>`_
and use it as follows:
-.. code-block:: shell
+.. code-block:: console
- ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
- Rscript draw_gantt.R simgrid.trace
+ $ ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/actor:yes
+ $ Rscript draw_gantt.R simgrid.trace
It produces a ``Rplots.pdf`` with the following content:
we could use their ID (which should be filled in one location
only).
-This could be done with the following deployment file. It's
+This could be done with the following deployment file. It's
not shorter than the previous one, but it's still simpler because the
information is only written once. It thus follows the `DRY
<https://en.wikipedia.org/wiki/Don't_repeat_yourself>`_ `SPOT
The mailboxes are a very powerful mechanism in SimGrid, allowing many
interesting application settings. They may feel unusual if you are
used to BSD sockets or other classical systems, but you will soon
-appreciate their power. They are only used to match
+appreciate their power. They are only used to match
communications but have no impact on the communication
timing. ``put()`` and ``get()`` are matched regardless of their
initiators' location and then the real communication occurs between
:cpp:func:`simgrid::s4u::Engine::get_clock`.
You can still stop your workers with a specific task as previously,
-or you may kill them forcefully with
-:cpp:func:`simgrid::s4u::Actor::kill` (if you already have a reference
-to the actor you want to kill) or
-:cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` (if you only have its ID).
-
+or you may kill them forcefully with :cpp:func:`simgrid::s4u::Actor::kill`.
Anyway, the new deployment `deployment3.xml` file should thus look
like this:
you could show only the total number of tasks processed by
default. You can still see the debug messages as follows:
-.. code-block:: shell
+.. code-block:: console
- ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug
+ $ ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug
Lab 4: Competing Applications
