X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/3fcd7bb0c3ac7b82304bb59c529d0d7999fa8a23..4299696f4a0ac31e2758ee601f09c607ed42676a:/docs/source/tuto_s4u.rst diff --git a/docs/source/tuto_s4u.rst b/docs/source/tuto_s4u.rst index cc56bdbe4d..df2feec376 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. @@ -128,7 +143,7 @@ That being said, an algorithm alone is not enough to define a simulation: SimGrid is a library, not a program. So you need to define your own ``main()`` function as follows. This function is in charge of creating a SimGrid simulation engine (on line 3), register the actor -functions to the engine (on lines 7 and 8), load the virtual platform +functions to the engine (on lines 7 and 8), load the simulated platform 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. @@ -144,11 +159,10 @@ file. Platform File ............. -Platform files define the virtual platform on which the provided +Platform files define the simulated 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? @@ -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 ............................ @@ -352,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 @@ -381,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 `_ @@ -442,7 +455,7 @@ messages to all workers based on their number, for example as follows: ... } - + Wrap up ....... @@ -457,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 @@ -478,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 @@ -508,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 @@ -632,7 +645,7 @@ as explained on `this page .. todo:: Include here the minimal setting to view something in R. - + Lab 5: Better Scheduling ------------------------ @@ -664,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 -------------------