S4U interface to express their computation, communication, disk usage
and other |Activities|_, so that they get reflected within the
simulator. These activities take place on **Resources** (|Hosts|_,
-|Links|_, |Storages|_). SimGrid predicts the time taken by each
+|Links|_, |Disks|_). SimGrid predicts the time taken by each
activity and orchestrates accordingly the actors waiting for the
completion of these activities.
between communicating actors.
.. |Actors| replace:: **Actors**
-.. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html
+.. _Actors: app_s4u.html#s4u-actor
.. |Activities| replace:: **Activities**
-.. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html
+.. _Activities: app_s4u.html#s4u-activity
.. |Hosts| replace:: **Hosts**
-.. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html
+.. _Hosts: app_s4u.html#s4u-host
.. |Links| replace:: **Links**
-.. _Links: api/classsimgrid_1_1s4u_1_1Link.html
+.. _Links: app_s4u.html#s4u-link
-.. |Storages| replace:: **Storages**
-.. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html
+.. |Disks| replace:: **Disks**
+.. _Disks: app_s4u.html#s4u-disk
.. |VirtualMachines| replace:: **VirtualMachines**
-.. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html
+.. _VirtualMachines: app_s4u.html#s4u-virtualmachine
.. |Host| replace:: **Host**
-.. _Host: api/classsimgrid_1_1s4u_1_1Host.html
+.. _Host: app_s4u.html#s4u-host
.. |Link| replace:: **Link**
-.. _Link: api/classsimgrid_1_1s4u_1_1Link.html
+.. _Link: app_s4u.html#s4u-link
.. |Mailbox| replace:: **Mailbox**
-.. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html
+.. _Mailbox: app_s4u.html#s4u-mailbox
.. |Barrier| replace:: **Barrier**
-.. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html
+.. _Barrier: app_s4u.html#s4u-barrier
.. |ConditionVariable| replace:: **ConditionVariable**
-.. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html
+.. _ConditionVariable: app_s4u.html#s4u-conditionvariable
.. |Mutex| replace:: **Mutex**
-.. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
-
+.. _Mutex: app_s4u.html#s4u-mutex
**In the remainder of this tutorial**, you will discover a simple yet
fully functioning example of SimGrid simulation: the Master/Workers
The Actors
..........
-Let's start with the code of the worker. It is represented by the
+Let's start with the code of the master. It is represented by the
*master* function below. This simple function takes at least 3
parameters (the amount of tasks to dispatch, their computational size
in flops to compute and their communication size in bytes to
are nicely logged along with the simulated time and actor name.
-.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
+.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
:language: c++
:start-after: master-begin
:end-before: master-end
:ref:`simgrid::s4u::this_actor <API_s4u_this_actor>`
namespace contains many such helping functions.
-.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
+.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
:language: c++
:start-after: worker-begin
:end-before: worker-end
from its description file (on line 11), map actors onto that platform
(on line 12) and run the simulation until its completion on line 15.
-.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
+.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
:language: c++
:start-after: main-begin
:end-before: main-end
.. |api_s4u_NetZone| image:: /img/extlink.png
:align: middle
:width: 12
-.. _api_s4u_NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html#class-documentation
+.. _api_s4u_NetZone: app_s4u.html#s4u-netzone
.. |api_s4u_Link| image:: /img/extlink.png
:align: middle
:width: 12
-.. _api_s4u_Link: api/classsimgrid_1_1s4u_1_1Link.html#class-documentation
+.. _api_s4u_Link: app_s4u.html#s4u-link
.. literalinclude:: ../../examples/platforms/small_platform.xml
:language: xml
that should be started, along with their parameter. In the following
example, we start 6 actors: one master and 5 workers.
-.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers_d.xml
+.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers_d.xml
:language: xml
Execution Example
execute it as follows. Note how the XBT_INFO() requests turned into
informative messages.
-.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers.tesh
+.. "WARNING: Over dedent has detected" is expected here as we remove the $ marker this way
+
+.. literalinclude:: ../../examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh
:language: shell
:start-after: s4u-app-masterworkers-fun
:prepend: $$$ ./masterworkers platform.xml deploy.xml
:append: $$$
:dedent: 2
+Each example included in the SimGrid distribution comes with a `tesh`
+file that presents how to start the example once compiled, along with
+the expected output. These files are used for the automatic testing of
+the framework, but can be used to see the examples' output without
+compiling them. See e.g. the file
+`examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh <https://framagit.org/simgrid/simgrid/-/blob/master/examples/cpp/app-masterworkers/s4u-app-masterworkers.tesh>`_.
+Lines starting with `$` are the commands to execute;
+lines starting with `>` are the expected output of each command while
+lines starting with `!` are configuration items for the test runner.
+
Improve it Yourself
-------------------
hierarchical algorithm, with some forwarders taking large pools of
tasks from the master, each of them distributing their tasks to a
sub-pool of workers? Or should we introduce super-peers,
- dupplicating the master's role in a peer-to-peer manner? Do the
+ duplicating the master's role in a peer-to-peer manner? Do the
algorithms require a perfect knowledge of the network?
- How is such an algorithm sensitive to external workload variation?
optional in this tutorial, it is not installed to reduce the image
size.
-The code template is available under ``/source/simgrid-template-s4u.git``
+The code template is available under ``/source/simgrid-template-s4u.git``
in the image. You should copy it to your working directory and
-recompile it when you first log in:
+recompile it when you first log in:
.. code-block:: shell
Using your Computer Natively
............................
-To take the tutorial on your machine, you first need to :ref:`install
-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:
+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
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
+
+ sudo apt install r-base r-cran-devtools cmake flex bison
+ 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
should be able to clone the `repository
# (exporting SimGrid_PATH is only needed if SimGrid is installed in a non-standard path)
export SimGrid_PATH=/where/to/simgrid
-
- git clone git@framagit.org:simgrid/simgrid-template-s4u.git
+
+ git clone https://framagit.org/simgrid/simgrid-template-s4u.git
cd simgrid-template-s4u/
- cmake .
+ cmake .
make
If you struggle with the compilation, then you should double check
.. code-block:: shell
- ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/msg/process:yes
+ ./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
.. code-block:: shell
- ./master-workers small_platform.xml master-workers_d.xml --cfg=tracing:yes --cfg=tracing/msg/process:yes
- pj_dump --ignore-incomplete-links simgrid.trace | grep STATE > gantt.csv
- Rscript draw_gantt.R gantt.csv
+ ./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:
for (int i = 0; i < tasks_count; i++) {
std::string worker_rank = std::to_string(i % workers_count);
std::string mailbox_name = std::string("worker-") + worker_rank;
- simgrid::s4u::MailboxPtr mailbox = simgrid::s4u::Mailbox::by_name(mailbox_name);
+ simgrid::s4u::Mailbox* mailbox = simgrid::s4u::Mailbox::by_name(mailbox_name);
mailbox->put(...);
appreciate their power. They are only used to match the
communications, but have no impact on the communication
timing. ``put()`` and ``get()`` are matched regardless of their
-initiators' location and then the real communication occures between
+initiators' location and then the real communication occurs between
the involved parties.
-Please refer to the full `API of Mailboxes
-<api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation>`_ for
-more details.
+Please refer to the full `Mailboxes' documentation
+<app_s4u.html#s4u-mailbox>`_ for more details.
Lab 2: Using the Whole Platform
trend. This simplification is another application of the good old DRY/SPOT
programming principle (`Don't Repeat Yourself / Single Point Of Truth
<https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>`_), and you
-really want your programming artefacts to follow these software
+really want your programming artifacts to follow these software
engineering principles.
But at the same time, you should be careful in separating your
scientific contribution (the master/workers algorithm) and the
-artefacts used to test it (platform, deployment and workload). This is
+artifacts used to test it (platform, deployment and workload). This is
why SimGrid forces you to express your platform and deployment files
in XML instead of using a programming interface: it forces a clear
separation of concerns between things of very different nature.
.. code-block:: shell
- ./master-workers-lab3 small_platform.xml deployment3.xml --log=msg_test.thres:debug
+ ./master-workers-lab3 small_platform.xml deployment3.xml --log=s4u_app_masterworker.thres:debug
Lab 4: Competing Applications
vite is not enough to understand the situation, because it does not
deal with categorization. This time, you absolutely must switch to R,
as explained on `this page
-<http://simgrid.gforge.inria.fr/contrib/R_visualization.php>`_.
+<https://simgrid.org/contrib/R_visualization.html>`_.
.. todo::
for more work. We will move to a First-Come First-Served mechanism
instead.
-For that, your workers should explicitely request for work with a
+For that, your workers should explicitly request for work with a
message sent to a channel that is specific to their master. The name
of that private channel can be the one used to categorize the
executions, as it is already specific to each master.
The master should serve in a round-robin manner the requests it
receives, until the time is up. Changing the communication schema can
be a bit hairy, but once it works, you will see that such as simple
-FCFS schema allows to double the amount of tasks handled over time
+FCFS schema allows one to double the amount of tasks handled over time
here. Things may be different with another platform file.
Further Improvements