docs/source/app_s4u.rst

   1 .. _S4U_doc:
   2
   3 The S4U Interface
   4 =================
   5
   6 .. raw:: html
   7
   8    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
   9    <script>
  10    window.onload=function() { // Wait for the SVG to be loaded before changing it
  11      var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
  12      elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
  13    }
  14    </script>
  15    <br/>
  16    <br/>
  17
  18 The S4U interface (SimGrid for you) mixes the full power of SimGrid
  19 with the full power of C++. This is the prefered interface to describe
  20 abstract algorithms in the domains of Cloud, P2P, HPC, IoT and similar
  21 settings.
  22
  23 Main Concepts
  24 -------------
  25
  26 A typical SimGrid simulation is composed of several |Actors|_, that
  27 execute user-provided functions. The actors have to explicitly use the
  28 S4U interface to express their
  29 :ref:`computation <exhale_class_classsimgrid_1_1s4u_1_1Exec>`,
  30 :ref:`communication <exhale_class_classsimgrid_1_1s4u_1_1Comm>`,
  31 :ref:`disk usage <exhale_class_classsimgrid_1_1s4u_1_1Io>`,
  32 and other |Activities|_, so that they get reflected within the
  33 simulator. These activities take place on resources such as |Hosts|_,
  34 |Links|_ and |Storages|_. SimGrid predicts the time taken by each
  35 activity and orchestrates accordingly the actors waiting for the
  36 completion of these activities.
  37
  38
  39 When **communicating**, data is not directly sent to other actors but
  40 posted onto a |Mailbox|_ that serve as rendez-vous point between
  41 communicating actors. This means that you don't need to know who you
  42 are talking to, you just put your communication `Send` request in a
  43 mailbox, and it will be matched with a complementary `Receive`
  44 request.  Alternatively, actors can interact through **classical
  45 synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
  46 |Mutex|_ and |ConditionVariable|_.
  47
  48 Each actor is located on a simulated |Host|_. Each host is located
  49 itself in a |NetZone|_, that knows the networking path between one
  50 resource to another. Each NetZone is included in another one, forming
  51 a tree of NetZones which root zone contains the whole platform.
  52
  53 The :ref:`simgrid::s4u::this_actor
  54 <namespace_simgrid__s4u__this_actor>` namespace provides many helper
  55 functions to simplify the code of actors.
  56
  57 - **Global Classes**
  58
  59   - :ref:`class s4u::Actor <exhale_class_classsimgrid_1_1s4u_1_1Actor>`:
  60     Active entities executing your application.
  61   - :ref:`class s4u::Engine <exhale_class_classsimgrid_1_1s4u_1_1Engine>`
  62     Simulation engine (singleton).
  63   - :ref:`class s4u::Mailbox <exhale_class_classsimgrid_1_1s4u_1_1Mailbox>`
  64     Communication rendez-vous.
  65
  66 - **Platform Elements**
  67
  68   - :ref:`class s4u::Host <exhale_class_classsimgrid_1_1s4u_1_1Host>`:
  69     Actor location, providing computational power.
  70   - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
  71     Interconnecting hosts.
  72   - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
  73     Sub-region of the platform, containing resources (Hosts, Link, etc).
  74   - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
  75     Resource on which actors can write and read data.
  76   - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
  77     Execution containers that can be moved between Hosts.
  78
  79 - **Activities** (:ref:`class s4u::Activity <exhale_class_classsimgrid_1_1s4u_1_1Activity>`):
  80   The things that actors can do on resources
  81
  82   - :ref:`class s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>`
  83     Communication activity, started on Mailboxes and consuming links.
  84   - :ref:`class s4u::Exec <exhale_class_classsimgrid_1_1s4u_1_1Exec>`
  85     Computation activity, started on Host and consuming CPU resources.
  86   - :ref:`class s4u::Io <exhale_class_classsimgrid_1_1s4u_1_1Io>`
  87     I/O activity, started on and consumming Storages.
  88
  89 - **Synchronization Mechanisms**: Classical IPC that actors can use
  90
  91   - :ref:`class s4u::Barrier <exhale_class_classsimgrid_1_1s4u_1_1Barrier>`
  92   - :ref:`class s4u::ConditionVariable <exhale_class_classsimgrid_1_1s4u_1_1ConditionVariable>`
  93   - :ref:`class s4u::Mutex <exhale_class_classsimgrid_1_1s4u_1_1Mutex>`
  94   - :ref:`class s4u::Semaphore <exhale_class_classsimgrid_1_1s4u_1_1Semaphore>`
  95
  96
  97 .. |Actors| replace:: **Actors**
  98 .. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html
  99
 100 .. |Activities| replace:: **Activities**
 101 .. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html
 102
 103 .. |Hosts| replace:: **Hosts**
 104 .. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html
 105
 106 .. |Links| replace:: **Links**
 107 .. _Links: api/classsimgrid_1_1s4u_1_1Link.html
 108
 109 .. |Storages| replace:: **Storages**
 110 .. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html
 111
 112 .. |VirtualMachines| replace:: **VirtualMachines**
 113 .. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html
 114
 115 .. |Host| replace:: **Host**
 116 .. _Host: api/classsimgrid_1_1s4u_1_1Host.html
 117
 118 .. |Mailbox| replace:: **Mailbox**
 119 .. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html
 120
 121 .. |NetZone| replace:: **NetZone**
 122 .. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html
 123
 124 .. |Barrier| replace:: **Barrier**
 125 .. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html
 126
 127 .. |ConditionVariable| replace:: **ConditionVariable**
 128 .. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html
 129
 130 .. |Mutex| replace:: **Mutex**
 131 .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html