X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/0ab9b29d089c4d3816333906545a1cbdfea2b079..2cfe340b9729c7ee55cf813f6a36f15dc918696b:/docs/source/tuto_s4u.rst diff --git a/docs/source/tuto_s4u.rst b/docs/source/tuto_s4u.rst index 4ee094cebd..5fc672cd8c 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:: /img/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:: /img/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:: /img/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:: /img/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,7 +170,7 @@ 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:: /img/extlink.png :align: middle :width: 12 @@ -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? @@ -287,18 +301,18 @@ image. Once you `installed Docker itself .. code-block:: shell docker pull simgrid/tuto-s4u - docker run -it --rm --name simgrid --volume ~/simgrid-tutorial:/src/tutorial simgrid/tuto-s4u bash + 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 ``/src/tutorial`` within the +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 ``/src/tutorial`` will be lost + 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 @@ -306,14 +320,14 @@ All needed dependencies are already installed in this container optional in this tutorial, it is not installed to reduce the image size. -The code template is available under ``/src/simgrid-template-s4u`` in +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 /src/simgrid-template-s4u/* /src/tutorial - cd /src/tutorial + cp -r /source/simgrid-template-s4u/* /source/tutorial + cd /source/tutorial Using your Computer Natively ............................ @@ -358,7 +372,7 @@ Please compile and execute the provided simulator as follows: 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 @@ -381,7 +395,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 `_ @@ -442,7 +456,7 @@ messages to all workers based on their number, for example as follows: ... } - + Wrap up ....... @@ -457,8 +471,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 @@ -478,7 +492,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 @@ -508,11 +522,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 @@ -632,7 +646,7 @@ as explained on `this page .. todo:: Include here the minimal setting to view something in R. - + Lab 5: Better Scheduling ------------------------ @@ -664,14 +678,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 -------------------