Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
docs: move S4U to its own (sub-)page
authorMartin Quinson <martin.quinson@loria.fr>
Fri, 24 Aug 2018 08:54:56 +0000 (10:54 +0200)
committerMartin Quinson <martin.quinson@loria.fr>
Fri, 24 Aug 2018 08:54:56 +0000 (10:54 +0200)
docs/source/app_s4u.rst [new file with mode: 0644]
docs/source/application.rst
docs/source/conf.py
docs/source/img/graphical-toc.svg

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
new file mode 100644 (file)
index 0000000..dd610a0
--- /dev/null
@@ -0,0 +1,131 @@
+.. _S4U_doc:
+
+The S4U Interface
+=================
+
+.. raw:: html
+
+   <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
+   <script>
+   window.onload=function() { // Wait for the SVG to be loaded before changing it
+     var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
+     elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
+   }
+   </script>
+   <br/>
+   <br/>
+
+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
+:ref:`computation <exhale_class_classsimgrid_1_1s4u_1_1Exec>`,
+:ref:`communication <exhale_class_classsimgrid_1_1s4u_1_1Comm>`,
+:ref:`disk usage <exhale_class_classsimgrid_1_1s4u_1_1Io>`,
+and other |Activities|_, so that they get reflected within the
+simulator. These activities take place on resources such as |Hosts|_,
+|Links|_ and |Storages|_. SimGrid predicts the time taken by each
+activity and orchestrates accordingly the actors waiting for the
+completion of these activities.
+
+
+When **communicating**, data is not directly sent to other actors but
+posted onto a |Mailbox|_ that serve as rendez-vous point between
+communicating actors. This means that you don't need to know who you
+are talking to, you just put your communication `Send` request in a
+mailbox, and it will be matched with a complementary `Receive`
+request.  Alternatively, actors can interact through **classical
+synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
+|Mutex|_ and |ConditionVariable|_.
+
+Each actor is located on a simulated |Host|_. Each host is located
+itself in a |NetZone|_, that knows the networking path between one
+resource to another. Each NetZone is included in another one, forming
+a tree of NetZones which root zone contains the whole platform.
+
+The :ref:`simgrid::s4u::this_actor
+<namespace_simgrid__s4u__this_actor>` namespace provides many helper
+functions to simplify the code of actors.
+
+- **Global Classes**
+
+  - :ref:`class s4u::Actor <exhale_class_classsimgrid_1_1s4u_1_1Actor>`:
+    Active entities executing your application.
+  - :ref:`class s4u::Engine <exhale_class_classsimgrid_1_1s4u_1_1Engine>`
+    Simulation engine (singleton).
+  - :ref:`class s4u::Mailbox <exhale_class_classsimgrid_1_1s4u_1_1Mailbox>`
+    Communication rendez-vous.
+
+- **Platform Elements**
+
+  - :ref:`class s4u::Host <exhale_class_classsimgrid_1_1s4u_1_1Host>`:
+    Actor location, providing computational power.
+  - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
+    Interconnecting hosts.
+  - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
+    Sub-region of the platform, containing resources (Hosts, Link, etc).
+  - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
+    Resource on which actors can write and read data.
+  - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
+    Execution containers that can be moved between Hosts.
+
+- **Activities** (:ref:`class s4u::Activity <exhale_class_classsimgrid_1_1s4u_1_1Activity>`):
+  The things that actors can do on resources
+
+  - :ref:`class s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>`
+    Communication activity, started on Mailboxes and consuming links.
+  - :ref:`class s4u::Exec <exhale_class_classsimgrid_1_1s4u_1_1Exec>`
+    Computation activity, started on Host and consuming CPU resources.
+  - :ref:`class s4u::Io <exhale_class_classsimgrid_1_1s4u_1_1Io>`
+    I/O activity, started on and consumming Storages.
+
+- **Synchronization Mechanisms**: Classical IPC that actors can use
+
+  - :ref:`class s4u::Barrier <exhale_class_classsimgrid_1_1s4u_1_1Barrier>`
+  - :ref:`class s4u::ConditionVariable <exhale_class_classsimgrid_1_1s4u_1_1ConditionVariable>`
+  - :ref:`class s4u::Mutex <exhale_class_classsimgrid_1_1s4u_1_1Mutex>`
+  - :ref:`class s4u::Semaphore <exhale_class_classsimgrid_1_1s4u_1_1Semaphore>`
+
+
+.. |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
+
+.. |NetZone| replace:: **NetZone**
+.. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.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
index 7b8a9b7..3898c38 100644 (file)
@@ -1,5 +1,8 @@
 .. _application:
 
+Describing your Application
+***************************
+
 .. raw:: html
 
    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
    <br/>
    <br/>
 
-Describing your Application
-***************************
-
 Every SimGrid simulation entails a distributed application, that
 virtually executes on the simulated platform. This application can
 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.
 
-.. raw:: html
-
-   <hr/>
-
-.. _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
-:ref:`computation <exhale_class_classsimgrid_1_1s4u_1_1Exec>`,
-:ref:`communication <exhale_class_classsimgrid_1_1s4u_1_1Comm>`,
-:ref:`disk usage <exhale_class_classsimgrid_1_1s4u_1_1Io>`,
-and other |Activities|_, so that they get reflected within the
-simulator. These activities take place on resources such as |Hosts|_,
-|Links|_ and |Storages|_. SimGrid predicts the time taken by each
-activity and orchestrates accordingly the actors waiting for the
-completion of these activities.
-
-
-When **communicating**, data is not directly sent to other actors but
-posted onto a |Mailbox|_ that serve as rendez-vous point between
-communicating actors. This means that you don't need to know who you
-are talking to, you just put your communication `Send` request in a
-mailbox, and it will be matched with a complementary `Receive`
-request.  Alternatively, actors can interact through **classical
-synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
-|Mutex|_ and |ConditionVariable|_.
-
-Each actor is located on a simulated |Host|_. Each host is located
-itself in a |NetZone|_, that knows the networking path between one
-resource to another. Each NetZone is included in another one, forming
-a tree of NetZones which root zone contains the whole platform.
-
-The :ref:`simgrid::s4u::this_actor
-<namespace_simgrid__s4u__this_actor>` namespace provides many helper
-functions to simplify the code of actors.
-
-- **Global Classes**
-
-  - :ref:`class s4u::Actor <exhale_class_classsimgrid_1_1s4u_1_1Actor>`:
-    Active entities executing your application.
-  - :ref:`class s4u::Engine <exhale_class_classsimgrid_1_1s4u_1_1Engine>`
-    Simulation engine (singleton).
-  - :ref:`class s4u::Mailbox <exhale_class_classsimgrid_1_1s4u_1_1Mailbox>`
-    Communication rendez-vous.
-
-- **Platform Elements**
-
-  - :ref:`class s4u::Host <exhale_class_classsimgrid_1_1s4u_1_1Host>`:
-    Actor location, providing computational power.
-  - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
-    Interconnecting hosts.
-  - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
-    Sub-region of the platform, containing resources (Hosts, Link, etc).
-  - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
-    Resource on which actors can write and read data.
-  - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
-    Execution containers that can be moved between Hosts.
-
-- **Activities** (:ref:`class s4u::Activity <exhale_class_classsimgrid_1_1s4u_1_1Activity>`):
-  The things that actors can do on resources
-
-  - :ref:`class s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>`
-    Communication activity, started on Mailboxes and consuming links.
-  - :ref:`class s4u::Exec <exhale_class_classsimgrid_1_1s4u_1_1Exec>`
-    Computation activity, started on Host and consuming CPU resources.
-  - :ref:`class s4u::Io <exhale_class_classsimgrid_1_1s4u_1_1Io>`
-    I/O activity, started on and consumming Storages.
-
-- **Synchronization Mechanisms**: Classical IPC that actors can use
-
-  - :ref:`class s4u::Barrier <exhale_class_classsimgrid_1_1s4u_1_1Barrier>`
-  - :ref:`class s4u::ConditionVariable <exhale_class_classsimgrid_1_1s4u_1_1ConditionVariable>`
-  - :ref:`class s4u::Mutex <exhale_class_classsimgrid_1_1s4u_1_1Mutex>`
-  - :ref:`class s4u::Semaphore <exhale_class_classsimgrid_1_1s4u_1_1Semaphore>`
-
-
-.. |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
-
-.. |NetZone| replace:: **NetZone**
-.. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.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
 
 .. include:: app_legacy.rst
+
+.. toctree::
+   :hidden:
+
+      The S4U Interface <app_s4u.rst>
index df33395..2aeb763 100644 (file)
@@ -40,7 +40,7 @@ release = u'3.21'
 extensions = [
     'sphinx.ext.todo',
 #    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
+#    'sphinx.ext.mathjax',
 #    'sphinx.ext.ifconfig',
     'breathe',
     'exhale',
index e887737..699873a 100644 (file)
@@ -24,9 +24,9 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="1.4"
-     inkscape:cx="341.7252"
-     inkscape:cy="358.35835"
+     inkscape:zoom="3.959798"
+     inkscape:cx="131.77503"
+     inkscape:cy="253.06312"
      inkscape:document-units="mm"
      inkscape:current-layer="layer1"
      showgrid="true"
     </rdf:RDF>
   </metadata>
   <g
+     inkscape:groupmode="layer"
+     id="layer2"
+     inkscape:label="underlining">
+    <rect
+       transform="translate(-2.308124,-62.995622)"
+       style="display:inline;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:none;stroke-width:0.52899998;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="S4UBox"
+       width="50.270832"
+       height="7.9375029"
+       x="5.2916665"
+       y="81.854164"
+       inkscape:label="#rect6249" />
+  </g>
+  <g
      id="layer1"
      inkscape:groupmode="layer"
      inkscape:label="Calque 1"
      transform="translate(-2.308124,-62.995623)"
      style="display:inline">
+    <rect
+       style="opacity:0.93999999;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="ApplicationBox"
+       width="50.270832"
+       height="26.458334"
+       x="5.2916665"
+       y="81.854164"
+       ry="2.6458309"
+       inkscape:label="#rect1020-7" />
     <a
        id="a6161"
        xlink:href="http://simgrid.gforge.inria.fr/contrib/smpi-calibration-doc/"
          x="69.055466"
          y="108.99284"
          style="font-size:4.93888903px;stroke-width:0.26458332px">▸ External Events</tspan></text>
-    <text
-       xml:space="preserve"
-       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;line-height:6.61458349px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       x="6.6014075"
-       y="87.184937"
-       id="Actors"
-       inkscape:label="#text1028-9"><tspan
-         sodipodi:role="line"
-         id="tspan1026-3"
-         x="6.6014075"
+    <a
+       xlink:href="app_s4u.html"
+       id="a6253">
+      <text
+         inkscape:label="#text1028-9"
+         id="Actors"
          y="87.184937"
-         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';stroke-width:0.26458332px">▸ Actors:</tspan></text>
+         x="6.6014075"
+         style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;line-height:6.61458349px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         xml:space="preserve"><tspan
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';stroke-width:0.26458332px"
+           y="87.184937"
+           x="6.6014075"
+           id="tspan1026-3"
+           sodipodi:role="line">▸ Actors:</tspan></text>
+    </a>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;line-height:6.61458349px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;opacity:0.93000034;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="6.6014075"
          y="105.61705"
          style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.93888903px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';stroke-width:0.26458332px">▸ Centralized Algo</tspan></text>
-    <rect
-       style="opacity:0.93999999;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
-       id="ApplicationBox"
-       width="50.270832"
-       height="26.458334"
-       x="5.2916665"
-       y="81.854164"
-       ry="2.6458309"
-       inkscape:label="#rect1020-7" />
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333311px;line-height:6.61458349px;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;opacity:0.93000034;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"