From: Martin Quinson Date: Fri, 24 Aug 2018 08:54:56 +0000 (+0200) Subject: docs: move S4U to its own (sub-)page X-Git-Tag: v3_21~197 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/60723cc9062e7d1ef8216d1e85d90892603e0df6 docs: move S4U to its own (sub-)page --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst new file mode 100644 index 0000000000..dd610a0a45 --- /dev/null +++ b/docs/source/app_s4u.rst @@ -0,0 +1,131 @@ +.. _S4U_doc: + +The S4U Interface +================= + +.. raw:: html + + + +
+
+ +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 `, +:ref:`communication `, +:ref:`disk usage `, +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 provides many helper +functions to simplify the code of actors. + +- **Global Classes** + + - :ref:`class s4u::Actor `: + Active entities executing your application. + - :ref:`class s4u::Engine ` + Simulation engine (singleton). + - :ref:`class s4u::Mailbox ` + Communication rendez-vous. + +- **Platform Elements** + + - :ref:`class s4u::Host `: + Actor location, providing computational power. + - :ref:`class s4u::Link ` + Interconnecting hosts. + - :ref:`class s4u::NetZone `: + Sub-region of the platform, containing resources (Hosts, Link, etc). + - :ref:`class s4u::Storage ` + Resource on which actors can write and read data. + - :ref:`class s4u::VirtualMachine `: + Execution containers that can be moved between Hosts. + +- **Activities** (:ref:`class s4u::Activity `): + The things that actors can do on resources + + - :ref:`class s4u::Comm ` + Communication activity, started on Mailboxes and consuming links. + - :ref:`class s4u::Exec ` + Computation activity, started on Host and consuming CPU resources. + - :ref:`class s4u::Io ` + I/O activity, started on and consumming Storages. + +- **Synchronization Mechanisms**: Classical IPC that actors can use + + - :ref:`class s4u::Barrier ` + - :ref:`class s4u::ConditionVariable ` + - :ref:`class s4u::Mutex ` + - :ref:`class s4u::Semaphore ` + + +.. |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 diff --git a/docs/source/application.rst b/docs/source/application.rst index 7b8a9b7271..3898c38b7d 100644 --- a/docs/source/application.rst +++ b/docs/source/application.rst @@ -1,5 +1,8 @@ .. _application: +Describing your Application +*************************** + .. raw:: html @@ -12,140 +15,18 @@

-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 - -
- -.. _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 `, -:ref:`communication `, -:ref:`disk usage `, -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 provides many helper -functions to simplify the code of actors. - -- **Global Classes** - - - :ref:`class s4u::Actor `: - Active entities executing your application. - - :ref:`class s4u::Engine ` - Simulation engine (singleton). - - :ref:`class s4u::Mailbox ` - Communication rendez-vous. - -- **Platform Elements** - - - :ref:`class s4u::Host `: - Actor location, providing computational power. - - :ref:`class s4u::Link ` - Interconnecting hosts. - - :ref:`class s4u::NetZone `: - Sub-region of the platform, containing resources (Hosts, Link, etc). - - :ref:`class s4u::Storage ` - Resource on which actors can write and read data. - - :ref:`class s4u::VirtualMachine `: - Execution containers that can be moved between Hosts. - -- **Activities** (:ref:`class s4u::Activity `): - The things that actors can do on resources - - - :ref:`class s4u::Comm ` - Communication activity, started on Mailboxes and consuming links. - - :ref:`class s4u::Exec ` - Computation activity, started on Host and consuming CPU resources. - - :ref:`class s4u::Io ` - I/O activity, started on and consumming Storages. - -- **Synchronization Mechanisms**: Classical IPC that actors can use - - - :ref:`class s4u::Barrier ` - - :ref:`class s4u::ConditionVariable ` - - :ref:`class s4u::Mutex ` - - :ref:`class s4u::Semaphore ` - - -.. |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 diff --git a/docs/source/conf.py b/docs/source/conf.py index df3339542c..2aeb763209 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -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', diff --git a/docs/source/img/graphical-toc.svg b/docs/source/img/graphical-toc.svg index e887737540..699873a257 100644 --- a/docs/source/img/graphical-toc.svg +++ b/docs/source/img/graphical-toc.svg @@ -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" @@ -2304,12 +2304,35 @@ + + + + ▸ External Events - + ▸ Actors: + 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">▸ Actors: + ▸ Centralized Algo -