From c09a6a63464d6f40c9edd889748005f470561e22 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Thu, 9 Aug 2018 15:21:20 +0200 Subject: [PATCH] new version of the masterworkers tuto, with s4u and sphinx --- doc/doxygen/examples.doc | 113 -- .../images/tuto-masterworkers-intro.svg | 1221 +++++++++++++++++ docs/source/usecase_algorithms.rst | 192 +++ tools/cmake/Documentation.cmake | 1 + 4 files changed, 1414 insertions(+), 113 deletions(-) delete mode 100644 doc/doxygen/examples.doc create mode 100644 docs/source/images/tuto-masterworkers-intro.svg create mode 100644 docs/source/usecase_algorithms.rst diff --git a/doc/doxygen/examples.doc b/doc/doxygen/examples.doc deleted file mode 100644 index 78ca077bec..0000000000 --- a/doc/doxygen/examples.doc +++ /dev/null @@ -1,113 +0,0 @@ -/*! @page examples SimGrid Examples - -@tableofcontents - -SimGrid comes with many examples provided in the examples/ directory. -Those examples are described in section @ref msg_examples. Those -examples are commented and should be easy to understand. for a first -step into SimGrid we also provide some more detailed examples in the -sections below. - -@htmlonly -You should also check our online tutorial section that contains a generic tutorial about using SimGrid. -@endhtmlonly - -@section using_msg Using MSG - -@htmlonly -You should also check our online tutorial section that contains a dedicated tutorial. -@endhtmlonly - -Here are some examples on how to use MSG, the most used API. - -MSG comes with an extensive set of examples. It is sometimes difficult -to find the one you need. This list aims at helping you finding the -example from which you can learn what you want to. - -@subsection MSG_ex_basics Basic examples and features - -@subsubsection MSG_ex_master_worker Basic Master/Workers - -Simulation of a master-worker application using a realistic platform and an external description of the deployment. - -@paragraph MSG_ex_mw_TOC Table of contents: - - - @ref MSG_ext_mw_preliminary - - @ref MSG_ext_mw_master - - @ref MSG_ext_mw_worker - - @ref MSG_ext_mw_core - - @ref MSG_ext_mw_platform - - @ref MSG_ext_mw_application - -
- -@dontinclude msg/app-masterworker/app-masterworker.c - -@paragraph MSG_ext_mw_preliminary Preliminary declarations - -@skip include -@until example"); -@skipline Master expects - -@paragraph MSG_ext_mw_master Master code - -This function has to be assigned to a #msg_process_t that will behave as the master. It should not be called directly -but either given as a parameter to #MSG_process_create() or registered as a public function through -#MSG_function_register() and then automatically assigned to a process through #MSG_launch_application(). - -C style arguments (argc/argv) are interpreted as: - - the number of tasks to distribute - - the computational size of each task - - the communication size of each task - - the number of workers managed by the master. - -Tasks are evenly sent in a round-robin style. - -@until return 0; -@until } -@skipline Worker expects - -@paragraph MSG_ext_mw_worker Worker code - -This function has to be assigned to a #msg_process_t that has to behave as a worker. Just like the master function -(described in @ref MSG_ext_mw_master), it should not be called directly. - -C style arguments (argc/argv) are interpreted as: - - a unique id used to build the mailbox name of the worker - -This function keeps waiting for tasks and executes them as it receives them. When a special task named 'finalize' is -received from the master, the process ends its execution. - -@until return 0; -@until } - -@paragraph MSG_ext_mw_core Main function - -This function is the core of the simulation and is divided only into 3 parts: - -# Simulation settings : #MSG_create_environment() creates a realistic - environment - -# Application deployment : create the processes on the right locations with - #MSG_launch_application() - -# The simulation is run with #MSG_main() - -Its arguments are: - - platform_file: the name of a file containing an valid platform description. - - deployment_file: the name of a file containing a valid application description -@line main -@until OK; -@until } - -@paragraph MSG_ext_mw_platform Example of a platform file - -The following platform description can be found in @c examples/msg/platforms/small_platform.xml -@include platforms/small_platform.xml - -@paragraph MSG_ext_mw_application Example of a deployment file - -The following application description can be found in @c examples/msg/app-masterworker/app-masterworker_d.xml: - -@include msg/app-masterworker/app-masterworker_d.xml - -*/ - - diff --git a/docs/source/images/tuto-masterworkers-intro.svg b/docs/source/images/tuto-masterworkers-intro.svg new file mode 100644 index 0000000000..7a207033cf --- /dev/null +++ b/docs/source/images/tuto-masterworkers-intro.svg @@ -0,0 +1,1221 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + Master + + + + T + + + + T + + + + Worker + + + + Worker + + + + Worker + + + + Worker + + + + Worker + + + + + + + + + The master dispatchesthe tasks to the workers + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + + T + + + diff --git a/docs/source/usecase_algorithms.rst b/docs/source/usecase_algorithms.rst new file mode 100644 index 0000000000..a66d8b8d81 --- /dev/null +++ b/docs/source/usecase_algorithms.rst @@ -0,0 +1,192 @@ +.. _usecase_simalgo: + +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 inteface 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 + +.. |api_s4u_Activity| image:: /images/extlink.png + :align: middle + :width: 12 +.. _api_s4u_Activity: api/classsimgrid_1_1s4u_1_1Activity.html#class-documentation + + +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. + +.. |api_s4u_Host| image:: /images/extlink.png + :align: middle + :width: 12 +.. _api_s4u_Host: api/classsimgrid_1_1s4u_1_1Host.html#class-documentation + +.. |api_s4u_Mailbox| image:: /images/extlink.png + :align: middle + :width: 12 +.. _api_s4u_Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html#class-documentation + + +The Master/Workers Example +-------------------------- + +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. + +.. image:: /images/tuto-masterworkers-intro.svg + :align: center + +We first present a round-robin version of this application, where the +master dispatches the tasks to the workers, one after the other, until +all tasks are dispatched. Later in this tutorial, you will be given +the opportunity to improve this scheme. + +The Actors +.......... + +Let's start with the code of the worker. It is represented by the +*master* function below. This simple function takes 4 parameters, +given as a vector of strings: + + - the number of workers managed by the master. + - the number of tasks to dispatch + - the computational size (in flops to compute) of each task + - the communication size (in bytes to exchange) of each task + +Then, the tasks are sent one after the other, each on a mailbox named +"worker-XXX" where XXX is the number of an existing worker. On the +other side, a given worker (which code is given below) wait for +incomming tasks on its own mailbox. Notice how this mailbox mechanism +allow the actors to find each other without having all information: +the master don't have to know the actors nor even where they are, it +simply pushes the messages on mailbox which name is predetermined. + +At the end, once all tasks are dispatched, the master dispatches +another task per worker, but this time with a negative amount of flops +to compute. Indeed, this application decided by convention, that the +workers should stop when encountering such a negative compute_size. + +At the end of the day, the only SimGrid specific functions used in +this example are :func:`simgrid::s4u::Mailbox::by_name` and +:func:`simgrid::s4u::Mailbox::put`. Also, XBT_INFO() is used as a +replacement to printf() or to cout to ensure that the messages are +nicely loggued along with the simulated time and actor name. + + +.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp + :language: c++ + :start-after: master-begin + :end-before: master-end + +Here comes the code of the worker actors. This function expects only one +parameter from its vector of strings: its identifier so that it knows +on which mailbox its incomming tasks will arrive. Its code is very +simple: as long as it gets valid computation requests (whose +compute_amount is positive), it compute this task and waits for the +next one. + +.. literalinclude:: ../../examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp + :language: c++ + :start-after: worker-begin + :end-before: worker-end + +Starting the Simulation +....................... + +And this is it. In only a few lines, we defined the algorithm of our +master/workers examples. Well, this is true, but an algorithm alone is +not enough to define a simulation. + +First, 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 +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 + :language: c++ + :start-after: main-begin + :end-before: main-end + :linenos: + +After that, the missing pieces are the platform and deployment +files. + +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. + +Such files can get rather long and boring, so the example below is +only an excerpts of the full ``examples/platforms/small_platform.xml`` +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 (4, 3, 2, 0, 1 and 8). The full file, along with +other examples, can be found in the archive under +``examples/platforms``. + +.. |api_s4u_NetZone| image:: /images/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 + :align: middle + :width: 12 +.. _api_s4u_Link: api/classsimgrid_1_1s4u_1_1Link.html#class-documentation + +.. literalinclude:: ../../examples/platforms/small_platform.xml + :language: xml + :lines: 1-10,12-20,56-63,192- + :caption: (excerpts of the small_platform.xml file) + +Deployment File +............... + +Deployment files specify the execution scenario: it lists the actors +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 + :language: xml + +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 + + +.. LocalWords: SimGrid diff --git a/tools/cmake/Documentation.cmake b/tools/cmake/Documentation.cmake index cff5b2c0f8..c25c77769d 100644 --- a/tools/cmake/Documentation.cmake +++ b/tools/cmake/Documentation.cmake @@ -25,6 +25,7 @@ if(enable_documentation) COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/doc/html COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/doc/html COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/doc/xml + COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/docs/source/api WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/doc ) -- 2.20.1