:width: 12
.. _api_s4u_Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation
+**In the remainder of this tutorial**, you will discover a simple yet
+fully functioning example of SimGrid simulation: the Master/Workers
+application. We will detail each part of the code and necessary
+configuration to make it working. After this tour, several exercises
+are proposed to let you discover some of the SimGrid features, hands
+on the keyboard.
+
Discover the Master/Workers
---------------------------
:align: center
-Lab 1: Simpler deployments
+Lab 1: Simpler Deployments
--------------------------
In the provided example, adding more workers quickly becomes a pain:
:language: xml
-Copy your ``master-workers.cpp`` into ``master-workers-exo1.cpp`` and
+Copy your ``master-workers.cpp`` into ``master-workers-lab1.cpp`` and
add a new executable into ``CMakeLists.txt``. Then modify your worker
function so that it gets its mailbox name not from the name of its
host, but from the string passed as ``args[1]``. The master will send
|api_s4u_Mailbox|_ for more details.
-Lab 2: Using the whole platform
+Lab 2: Using the Whole Platform
-------------------------------
It is now easier to add a new worker, but you still has to do it
....................................
For that, the master needs to retrieve the list of hosts declared in
-the platform with :cpp:func:`simgrid::s4u::Engine::get_all_host()`.
+the platform with :cpp:func:`simgrid::s4u::Engine::get_all_hosts`.
Then, the master should start the worker processes with
:cpp:func:`simgrid::s4u::Actor::create`.
mailbox, which should be passed as parameter to the workers. This
reduces the amount of mailboxes, but prevents the master from taking
any scheduling decision. It really depends on how you want to organize
-your application and what you want to study with your simulator.
+your application and what you want to study with your simulator. In
+this tutorial, that's probably not a good idea.
Wrap up
.......
in XML instead of using a programming interface: it forces a clear
separation of concerns between things of very different nature.
-Lab 3: Fixed experiment duration
+Lab 3: Fixed Experiment Duration
--------------------------------
In the current version, the number of tasks is defined through the
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:`simgrid::s4u::Actor::kill(aid_t)` (if you only have its ID).
+:cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` (if you only have its ID).
Anyway, the new deployment `deployment3.xml` file should thus look
.................................
Not all messages are equally informative, so you probably want to
-change most of the ``XBT_INFO`` into ``XBT_DEBUG`` so that they are hidden
-by default. You could for example show only the total number of tasks
-processed by default. You can still see the debug messages as follows:
+change some of the ``XBT_INFO`` into ``XBT_DEBUG`` so that they are
+hidden by default. For example, you may want to use ``XBT_INFO`` once
+every 100 tasks and ``XBT_DEBUG`` when sending all the other tasks. Or
+you could show only the total number of tasks processed by
+default. You can still see the debug messages as follows:
.. code-block:: shell
- ./masterworker examples/platforms/small_platform.xml deployment3.xml --log=msg_test.thres:debug
+ ./master-workers-lab3 small_platform.xml deployment3.xml --log=msg_test.thres:debug
-Lab 4: Understanding competing applications
--------------------------------------------
+Lab 4: Competing Applications
+-----------------------------
It is now time to start several applications at once, with the following ``deployment4.xml`` file.
understand which task belong to which application. To fix this, we
will categorize the tasks.
-For that, first let each master create its own category of tasks with
-@ref TRACE_category(), and then assign this category to each task using
-@ref MSG_task_set_category().
+Instead of starting the execution in one function call only with
+``this_actor::execute(cost)``, you need to
+create the execution activity, set its tracing category, and then start
+it and wait for its completion, as follows:
-The outcome can then be visualized as a Gantt-chart as follows:
+.. code-block:: cpp
-.. code-block:: shell
+ simgrid::s4u::ExecPtr exec = simgrid::s4u::this_actor::exec_init(compute_cost);
+ exec->set_tracing_category(category);
+ // exec->start() is optional here as wait() starts the activity on need
+ exec->wait();
- ./masterworker examples/platforms/small_platform.xml deployment4.xml --cfg=tracing:yes --cfg=tracing/msg/process:yes
- vite simgrid.trace
+You can make the same code shorter as follows:
-.. todo::
+.. code-block:: cpp
- Make it work
+ simgrid::s4u::this_actor::exec_init(compute_cost)->set_tracing_category(category)->wait();
-Going further
-.............
+Visualizing the result
+.......................
vite is not enough to understand the situation, because it does not
-deal with categorization. That is why you should switch to R to
-visualize your outcomes, as explained on `this page
+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>`_.
+.. todo::
+
+ Include here the minimal setting to view something in R.
+
+
+Lab 5: Better Scheduling
+------------------------
+
+You don't need a very advanced visualization solution to notice that
+round-robin is completely suboptimal: most of the workers keep waiting
+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
+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
+here. Things may be different with another platform file.
+
+Further Improvements
+....................
+
+From this, many things can easily be added. For example, you could:
+
+- Allow workers to have several pending requests so as to overlap
+ communication and computations as much as possible. Non-blocking
+ communication will probably become handy here.
+- Add a performance measurement mechanism, enabling the master to make smart scheduling choices.
+- Test your code on other platforms, from the ``examples/platforms``
+ directory in your archive.
+
+ What is the largest number of tasks requiring 50e6 flops and 1e5
+ bytes that you manage to distribute and process in one hour on
+ ``g5k.xml`` ?
+- Optimize not only for the amount of tasks handled, but also for the
+ total energy dissipated.
+- And so on. If you come up with a really nice extension, please share
+ it with us so that we can extend this tutorial.
+
+After this Tutorial
+-------------------
+
+This tutorial is now terminated. You could keep reading the [online documentation][fn:4] or
+[tutorials][fn:7], or you could head up to the example section to read some code.
+
+.. todo::
+
+ TODO: Points to improve for the next time
+
+ - Propose equivalent exercises and skeleton in java.
+ - Propose a virtualbox image with everything (simgrid, pajeng, ...) already set
+ up.
+ - Ease the installation on mac OS X (binary installer) and
+ windows.
+ - Explain that programming in C or java and having a working
+ development environment is a prerequisite.
+
+
+
.. LocalWords: SimGrid
