X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/f7dab9588dcb960ed22eb63cbf70916b74340ccb..5937b88aaa18de687b2de15a97ee3ae0dc480f64:/docs/source/tuto_s4u.rst diff --git a/docs/source/tuto_s4u.rst b/docs/source/tuto_s4u.rst index 0182c6e502..18c43c4131 100644 --- a/docs/source/tuto_s4u.rst +++ b/docs/source/tuto_s4u.rst @@ -4,44 +4,59 @@ Simulating Algorithms ===================== SimGrid was conceived as a tool to study distributed algorithms. Its -modern S4U interface makes it easy to assess Cloud, P2P, HPC, IoT and -similar settings. - -A typical SimGrid simulation is composed of several **Actors** -|api_s4u_Actor|_ , that execute user-provided functions. The actors -have to explicitly use the S4U interface to express their computation, -communication, disk usage and other **Activities** |api_s4u_Activity|_ -, so that they get reflected within the simulator. These activities -take place on **Resources** (CPUs, links, disks). SimGrid predicts the -time taken by each activity and orchestrates accordingly the actors -waiting for the completion of these activities. - -.. |api_s4u_Actor| image:: /images/extlink.png - :align: middle - :width: 12 -.. _api_s4u_Actor: api/classsimgrid_1_1s4u_1_1Actor.html#class-documentation +modern :ref:`S4U interface ` makes it easy to assess Cloud, +P2P, HPC, IoT and similar settings. -.. |api_s4u_Activity| image:: /images/extlink.png - :align: middle - :width: 12 -.. _api_s4u_Activity: api/classsimgrid_1_1s4u_1_1Activity.html#class-documentation +A typical SimGrid simulation is composed of several |Actors|_, that +execute user-provided functions. The actors have to explicitly use the +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 +activity and orchestrates accordingly the actors waiting for the +completion of these activities. +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 serve as rendez-vous point +between communicating actors. -Each actor executes a user-provided function on a simulated **Host** -|api_s4u_Host|_ with which it can interact. Communications are not -directly sent to actors, but posted onto **Mailboxes** -|api_s4u_Mailbox|_ that serve as rendez-vous points between -communicating processes. +.. |Actors| replace:: **Actors** +.. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html -.. |api_s4u_Host| image:: /images/extlink.png - :align: middle - :width: 12 -.. _api_s4u_Host: api/classsimgrid_1_1s4u_1_1Host.html#class-documentation +.. |Activities| replace:: **Activities** +.. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html + +.. |Hosts| replace:: **Hosts** +.. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html + +.. |Links| replace:: **Links** +.. _Links: api/classsimgrid_1_1s4u_1_1Link.html + +.. |Storages| replace:: **Storages** +.. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html + +.. |VirtualMachines| replace:: **VirtualMachines** +.. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html + +.. |Host| replace:: **Host** +.. _Host: api/classsimgrid_1_1s4u_1_1Host.html + +.. |Link| replace:: **Link** +.. _Link: api/classsimgrid_1_1s4u_1_1Link.html + +.. |Mailbox| replace:: **Mailbox** +.. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html + +.. |Barrier| replace:: **Barrier** +.. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html + +.. |ConditionVariable| replace:: **ConditionVariable** +.. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html + +.. |Mutex| replace:: **Mutex** +.. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html -.. |api_s4u_Mailbox| image:: /images/extlink.png - :align: middle - :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 @@ -58,7 +73,7 @@ Discover the Master/Workers This section introduces a first example of SimGrid simulation. This simple application is composed of two kind of actors: the **master** is in charge of distributing some computational tasks to a set of -**workers** that execute them. +**workers** that execute them. .. image:: /tuto_s4u/img/intro.svg :align: center @@ -95,8 +110,8 @@ this example are :cpp:func:`simgrid::s4u::Mailbox::by_name` and :cpp:func:`simgrid::s4u::Mailbox::put`. Also, :c:macro:`XBT_INFO` is used as a replacement to printf() or to cout to ensure that the messages are nicely logged along with the simulated time and actor name. - - + + .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp :language: c++ :start-after: master-begin @@ -120,7 +135,7 @@ namespace contains many such helping functions. Starting the Simulation ....................... - + And this is it. In only a few lines, we defined the algorithm of our master/workers examples. @@ -146,9 +161,8 @@ Platform File Platform files define the virtual platform on which the provided application will take place. In contains one or several **Network -Zone** |api_s4u_NetZone|_ that contain both **Host-** |api_s4u_Host|_ -and **Link-** |api_s4u_Link|_ Resources, as well as routing -information. +Zone** |api_s4u_NetZone|_ that contain both |Host|_ and |Link|_ +Resources, as well as routing information. Such files can get rather long and boring, so the example below is only an excerpts of the full ``examples/platforms/small_platform.xml`` @@ -156,13 +170,13 @@ file. For example, most routing information are missing, and only the route between the hosts Tremblay and Fafard is given. This path traverses 6 links (named 4, 3, 2, 0, 1 and 8). There are several examples of platforms in the archive under ``examples/platforms``. - -.. |api_s4u_NetZone| image:: /images/extlink.png + +.. |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_Link| image:: /images/extlink.png +.. |api_s4u_Link| image:: /img/extlink.png :align: middle :width: 12 .. _api_s4u_Link: api/classsimgrid_1_1s4u_1_1Link.html#class-documentation @@ -188,14 +202,14 @@ Execution Example This time, we have all parts: once the program is compiled, we can execute it as follows. Note how the XBT_INFO() requests turned into informative messages. - + .. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers.tesh :language: shell :start-after: s4u-app-masterworkers-fun :prepend: $$$ ./masterworkers platform.xml deploy.xml :append: $$$ :dedent: 2 - + Improve it Yourself ------------------- @@ -232,7 +246,7 @@ This very simple setting raises many interesting questions: round-robin algorithm performs very well. Would it still hold true when transfer time is not negligible? What if some tasks are performed faster on some specific nodes? - + - The network topology interconnecting the master and the workers may be quite complicated. How does such a topology impact the previous result? @@ -277,15 +291,53 @@ was obtained with the Triva software. .. image:: /tuto_s4u/img/result.png :align: center -Prerequisite +Using Docker ............ -Before your proceed, you need to :ref:`install SimGrid `, a -C++ compiler and also ``pajeng`` to visualize the traces. You may want -to install `Vite `_ 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: +The easiest way to take the tutorial is to use the dedicated Docker +image. Once you `installed Docker itself +`_, simply do the following: + +.. code-block:: shell + + 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 +your host machine that will be visible as ``/source/tutorial`` within the +container. You can then edit the files you want with your favorite +editor in ``~/simgrid-tutorial``, and compile them within the +container to enjoy the provided dependencies. + +.. warning:: + + Any change to the container out of ``/source/tutorial`` will be lost + when you log out of the container, so don't edit the other files! + +All needed dependencies are already installed in this container +(SimGrid, a C++ compiler, cmake, pajeng and R). Vite being only +optional in this tutorial, it is not installed to reduce the image +size. + +The code template is available under ``/source/simgrid-template-s4u`` in +the image. You should copy it to your working directory when you first +log in: + +.. code-block:: shell + + cp -r /source/simgrid-template-s4u/* /source/tutorial + cd /source/tutorial + +Using your Computer Natively +............................ + +To take the tutorial on your machine, you first need to :ref:`install +SimGrid `, a C++ compiler and also ``pajeng`` to visualize +the traces. You may want to install `Vite +`_ 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 @@ -314,13 +366,12 @@ Discovering the Provided Code Please compile and execute the provided simulator as follows: - .. code-block:: shell make master-workers ./master-workers small_platform.xml master-workers_d.xml -For a more "fancy" output, you can use simgrid-colorizer. +For a more "fancy" output, you can use simgrid-colorizer. .. code-block:: shell @@ -343,7 +394,7 @@ is a better way to visualize SimGrid traces (see below). .. image:: /tuto_s4u/img/vite-screenshot.png :align: center - + If you want the full power to visualize SimGrid traces, you need to use R. As a start, you can download this `starter script `_ @@ -404,7 +455,7 @@ messages to all workers based on their number, for example as follows: ... } - + Wrap up ....... @@ -419,8 +470,8 @@ initiators' location and then the real communication occures between the involved parties. Please refer to the full `API of Mailboxes -`_ -|api_s4u_Mailbox|_ for more details. +`_ for +more details. Lab 2: Using the Whole Platform @@ -440,7 +491,7 @@ Creating the workers from the master For that, the master needs to retrieve the list of hosts declared in the platform with :cpp:func:`simgrid::s4u::Engine::get_all_hosts`. -Then, the master should start the worker processes with +Then, the master should start the worker actors with :cpp:func:`simgrid::s4u::Actor::create`. ``Actor::create(name, host, func, params...)`` is a very flexible @@ -470,11 +521,11 @@ Previously, the workers got from their parameter the name of the mailbox they should use. We can still do so: the master should build such a parameter before using it in the ``Actor::create()`` call. The master could even pass directly the mailbox as a parameter to the -workers. +workers. Since we want later to study concurrent applications, it is advised to use a mailbox name that is unique over the simulation even if there is -more than one master. +more than one master. One possibility for that is to use the actor ID (aid) of each worker as a mailbox name. The master can retrieve the aid of the newly @@ -594,7 +645,7 @@ as explained on `this page .. todo:: Include here the minimal setting to view something in R. - + Lab 5: Better Scheduling ------------------------ @@ -626,14 +677,14 @@ From this, many things can easily be added. For example, you could: - 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. + 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. + it with us so that we can extend this tutorial. After this Tutorial -------------------