docs/source/app_s4u.rst

   1 .. _S4U_doc:
   2
   3 =================
   4 The S4U Interface
   5 =================
   6
   7 .. raw:: html
   8
   9    <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
  10    <script>
  11    window.onload=function() { // Wait for the SVG to be loaded before changing it
  12      var elem=document.querySelector("#TOC").contentDocument.getElementById("S4UBox")
  13      elem.style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1";
  14    }
  15    </script>
  16    <br/>
  17    <br/>
  18
  19 The S4U interface (SimGrid for you) mixes the full power of SimGrid
  20 with the full power of C++. This is the preferred interface to describe
  21 abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar
  22 settings.
  23
  24 Currently (v3.21), S4U is definitely the way to go for long-term
  25 projects. It is feature complete, but may still evolve slightly in the
  26 future releases. It can already be used to do everything that can be
  27 done in SimGrid, but you may have to adapt your code in future
  28 releases. When this happens, compiling your code will produce
  29 deprecation warnings for 4 releases (one year) before the removal of
  30 the old symbols.
  31 If you want an API that will never ever evolve in the future, you
  32 should use the deprecated MSG API instead.
  33
  34 -------------
  35 Main Concepts
  36 -------------
  37
  38 A typical SimGrid simulation is composed of several |Actors|_, that
  39 execute user-provided functions. The actors have to explicitly use the
  40 S4U interface to express their
  41 :ref:`computation <exhale_class_classsimgrid_1_1s4u_1_1Exec>`,
  42 :ref:`communication <exhale_class_classsimgrid_1_1s4u_1_1Comm>`,
  43 :ref:`disk usage <exhale_class_classsimgrid_1_1s4u_1_1Io>`,
  44 and other |Activities|_, so that they get reflected within the
  45 simulator. These activities take place on resources such as |Hosts|_,
  46 |Links|_ and |Storages|_. SimGrid predicts the time taken by each
  47 activity and orchestrates the actors accordingly, waiting for the
  48 completion of these activities.
  49
  50
  51 When **communicating**, data is not directly sent to other actors but
  52 posted onto a |Mailbox|_ that serves as a rendez-vous point between
  53 communicating actors. This means that you don't need to know who you
  54 are talking to, you just put your communication `Put` request in a
  55 mailbox, and it will be matched with a complementary `Get`
  56 request.  Alternatively, actors can interact through **classical
  57 synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
  58 |Mutex|_ and |ConditionVariable|_.
  59
  60 Each actor is located on a simulated |Host|_. Each host is located
  61 itself in a |NetZone|_, that knows the networking path between one
  62 resource to another. Each NetZone is included in another one, forming
  63 a tree of NetZones which root zone contains the whole platform.
  64
  65 The :ref:`simgrid::s4u::this_actor
  66 <namespace_simgrid__s4u__this_actor>` namespace provides many helper
  67 functions to simplify the code of actors.
  68
  69 - **Global Classes**
  70
  71   - :ref:`class s4u::Actor <exhale_class_classsimgrid_1_1s4u_1_1Actor>`:
  72     Active entities executing your application.
  73   - :ref:`class s4u::Engine <exhale_class_classsimgrid_1_1s4u_1_1Engine>`
  74     Simulation engine (singleton).
  75   - :ref:`class s4u::Mailbox <exhale_class_classsimgrid_1_1s4u_1_1Mailbox>`
  76     Communication rendez-vous.
  77
  78 - **Platform Elements**
  79
  80   - :ref:`class s4u::Host <exhale_class_classsimgrid_1_1s4u_1_1Host>`:
  81     Actor location, providing computational power.
  82   - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
  83     Interconnecting hosts.
  84   - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
  85     Sub-region of the platform, containing resources (Hosts, Links, etc).
  86   - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
  87     Resource on which actors can write and read data.
  88   - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
  89     Execution containers that can be moved between Hosts.
  90
  91 - **Activities** (:ref:`class s4u::Activity <exhale_class_classsimgrid_1_1s4u_1_1Activity>`):
  92   The things that actors can do on resources
  93
  94   - :ref:`class s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>`
  95     Communication activity, started on Mailboxes and consuming links.
  96   - :ref:`class s4u::Exec <exhale_class_classsimgrid_1_1s4u_1_1Exec>`
  97     Computation activity, started on Host and consuming CPU resources.
  98   - :ref:`class s4u::Io <exhale_class_classsimgrid_1_1s4u_1_1Io>`
  99     I/O activity, started on and consumming Storages.
 100
 101 - **Synchronization Mechanisms**: Classical IPC that actors can use
 102
 103   - :ref:`class s4u::Barrier <exhale_class_classsimgrid_1_1s4u_1_1Barrier>`
 104   - :ref:`class s4u::ConditionVariable <exhale_class_classsimgrid_1_1s4u_1_1ConditionVariable>`
 105   - :ref:`class s4u::Mutex <exhale_class_classsimgrid_1_1s4u_1_1Mutex>`
 106   - :ref:`class s4u::Semaphore <exhale_class_classsimgrid_1_1s4u_1_1Semaphore>`
 107
 108
 109 .. |Actors| replace:: **Actors**
 110 .. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html
 111
 112 .. |Activities| replace:: **Activities**
 113 .. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html
 114
 115 .. |Hosts| replace:: **Hosts**
 116 .. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html
 117
 118 .. |Links| replace:: **Links**
 119 .. _Links: api/classsimgrid_1_1s4u_1_1Link.html
 120
 121 .. |Storages| replace:: **Storages**
 122 .. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html
 123
 124 .. |VirtualMachines| replace:: **VirtualMachines**
 125 .. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html
 126
 127 .. |Host| replace:: **Host**
 128 .. _Host: api/classsimgrid_1_1s4u_1_1Host.html
 129
 130 .. |Mailbox| replace:: **Mailbox**
 131 .. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html
 132
 133 .. |NetZone| replace:: **NetZone**
 134 .. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html
 135
 136 .. |Barrier| replace:: **Barrier**
 137 .. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html
 138
 139 .. |ConditionVariable| replace:: **ConditionVariable**
 140 .. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html
 141
 142 .. |Mutex| replace:: **Mutex**
 143 .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
 144
 145 .. THE EXAMPLES
 146
 147 .. include:: ../../examples/s4u/README.rst
 148
 149 ----------
 150 Activities
 151 ----------
 152
 153 Activities represent the actions that consume a resource, such as a
 154 :ref:`s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>` that
 155 consumes the *transmiting power* of :ref:`s4u::Link
 156 <exhale_class_classsimgrid_1_1s4u_1_1Link>` resources.
 157
 158 .......................
 159 Asynchronous Activities
 160 .......................
 161
 162 Every activity can be either **blocking** or **asynchronous**. For
 163 example, :cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>`
 164 and :cpp:func:`s4u::Mailbox::get() <simgrid::s4u::Mailbox::get>`
 165 create blocking communications: the actor is blocked until the
 166 completion of that communication. Asynchronous communications do not
 167 block the actor during their execution but progress on their own.
 168
 169 Once your asynchronous activity is started, you can test for its
 170 completion using :cpp:func:`s4u::Activity::test() <simgrid::s4u::Activity::test>`.
 171 This function returns ``true`` if the activity completed already.
 172 You can also use :cpp:func:`s4u::Activity::wait() <simgrid::s4u::Activity::wait>`
 173 to block until the completion of the activity. To wait for at most a given amount of time,
 174 use  :cpp:func:`s4u::Activity::wait_for() <simgrid::s4u::Activity::wait_for>`.
 175 Finally, to wait at most until a specified time limit, use
 176 :cpp:func:`s4u::Activity::wait_until() <simgrid::s4u::Activity::wait_until>`.
 177
 178 .. todo::
 179
 180    wait_for and wait_until are currently not implemented for Exec and Io activities.
 181
 182 Every kind of activities can be asynchronous:
 183
 184   - :ref:`s4u::CommPtr <exhale_class_classsimgrid_1_1s4u_1_1Comm>` are created with
 185     :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
 186     :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
 187   - :ref:`s4u::IoPtr <exhale_class_classsimgrid_1_1s4u_1_1Io>` are created with
 188     :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
 189     :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.
 190   - :ref:`s4u::ExecPtr <exhale_class_classsimgrid_1_1s4u_1_1Exec>` are created with
 191     :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
 192   - In the future, it will become possible to have asynchronous IPC
 193     such as asynchronous mutex lock requests.
 194
 195 The following example shows how to have several concurrent
 196 communications ongoing.  First, you have to declare a vector in which
 197 we will store the ongoing communications. It is also useful to have a
 198 vector of mailboxes.
 199
 200 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 201    :language: c++
 202    :start-after: init-begin
 203    :end-before: init-end
 204    :dedent: 4
 205
 206 Then, you start all the communications that should occur concurrently with
 207 :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.
 208 Finally, the actor waits for the completion of all of them at once
 209 with
 210 :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.
 211
 212 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 213    :language: c++
 214    :start-after: put-begin
 215    :end-before: put-end
 216    :dedent: 4
 217
 218
 219 .....................
 220 Activities Life cycle
 221 .....................
 222
 223 Sometimes, you want to change the setting of an activity before it even starts.
 224
 225 .. todo:: write this section
 226
 227 -----------------
 228 Memory Management
 229 -----------------
 230
 231 For sake of simplicity, we use `RAII
 232 <https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
 233 everywhere in S4U. This is an idiom where resources are automatically
 234 managed through the context. Provided that you never manipulate
 235 objects of type Foo directly but always FooPtr references (which are
 236 defined as `boost::intrusive_ptr
 237 <http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
 238 <Foo>), you will never have to explicitely release the resource that
 239 you use nor to free the memory of unused objects.
 240
 241 Here is a little example:
 242
 243 .. code-block:: cpp
 244
 245    void myFunc()
 246    {
 247      simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
 248
 249      mutex->lock();   // use the mutex as a simple reference
 250      //  bla bla
 251      mutex->unlock();
 252
 253    } // The mutex gets automatically freed because the only existing reference gets out of scope