From: Martin Quinson Date: Thu, 23 Aug 2018 21:07:40 +0000 (+0200) Subject: docs: start writing the S4U part X-Git-Tag: v3_21~206 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/3877d90836e4902835c5464074090c4d928dac6d?hp=8cdcfdf2f00416db8483442c4c9fd6a8965e2d75 docs: start writing the S4U part --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst deleted file mode 100644 index 43d79e8da8..0000000000 --- a/docs/source/app_s4u.rst +++ /dev/null @@ -1,4 +0,0 @@ -The S4U Interface -================= - - diff --git a/docs/source/application.rst b/docs/source/application.rst index f9e50f046a..c3555f21b2 100644 --- a/docs/source/application.rst +++ b/docs/source/application.rst @@ -21,7 +21,72 @@ be either an existing MPI program (if you use the SMPI interface), or a program specifically written to execute within SimGrid, using one of the dedicated APIs. -.. include:: app_s4u.rst +.. _S4U_doc: + +The S4U Interface +================= + +The S4U interface (SimGrid for you) mixes the full power of SimGrid +with the full power of C++. This is the prefered interface to describe +abstract algorithms in the domains of Cloud, P2P, HPC, IoT and similar +settings. + +Main Concepts +------------- + +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|_ and |VirtualMachines|_. 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 using the :ref:`simgrid::s4u::this_actor +` namespace. **Communications** +are not directly sent to actors, but posted onto a |Mailbox|_ that +serve as rendez-vous point between communicating actors. Actors can +also interact through **classical synchronization mechanisms** such as +|Barrier|_, |Semaphore|_, |Mutex|_ and |ConditionVariable|_. + +.. todo:: Add NetZone + +.. |Actors| replace:: **Actors** +.. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html + +.. |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 + +.. |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 + .. include:: app_smpi.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c9daac2d1..a092cde562 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,11 +12,10 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os +import os, subprocess # import sys # sys.path.insert(0, os.path.abspath('.')) - # -- Project information ----------------------------------------------------- project = u'SimGrid' @@ -53,6 +52,7 @@ breathe_projects = { 'simgrid': '../build/doxy/xml' } breathe_default_project = "simgrid" # Setup the exhale extension + exhale_args = { # These arguments are required "containmentFolder": "./api", @@ -66,7 +66,10 @@ exhale_args = { "exhaleExecutesDoxygen": True, "exhaleDoxygenStdin": """ INPUT = ../../include/simgrid/s4u ../../include/simgrid/forward.h ../../include/simgrid/xbt + FULL_PATH_NAMES = NO # Don't leak the path on which it was built GENERATE_XML = YES + XML_PROGRAMLISTING = NO # No program listings, please + PREDEFINED += \ __cplusplus \ DOXYGEN \ @@ -87,6 +90,7 @@ exhale_args = { """ } + # For cross-ref generation primary_domain = 'cpp' @@ -159,3 +163,4 @@ html_context = { "gitlab_version": "master", # Version "conf_py_path": "/docs/source/", # Path in the checkout to the docs root } + diff --git a/docs/source/tuto_s4u.rst b/docs/source/tuto_s4u.rst index 4ee094cebd..317df547fc 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 processes. -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 @@ -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`` @@ -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 diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp index 164da062a7..d46e69912c 100644 --- a/include/simgrid/s4u/Host.hpp +++ b/include/simgrid/s4u/Host.hpp @@ -25,14 +25,15 @@ namespace s4u { * * @tableofcontents * - * An host represents some physical resource with computing and networking capabilities. + * Some physical resource with computing and networking capabilities on which Actors execute. * * All hosts are automatically created during the call of the method - * @ref simgrid::s4u::Engine::loadPlatform(). + * @ref simgrid::s4u::Engine::load_platform(). * You cannot create a host yourself. * - * You can retrieve a particular host using simgrid::s4u::Host::byName() - * and actors can retrieve the host on which they run using simgrid::s4u::Host::current(). + * You can retrieve a particular host using @ref simgrid::s4u::Host::by_name() + * and actors can retrieve the host on which they run using @ref simgrid::s4u::Host::current() or + * @ref simgrid::s4u::this_actor::get_host(). */ class XBT_PUBLIC Host : public simgrid::xbt::Extendable { friend simgrid::vm::VMModel; // Use the pimpl_cpu to compute the VM sharing