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 preferred interface to describe
  20 abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar
  21 settings.
  22
  23 Currently (v3.21), S4U is definitely the way to go for long-term
  24 projects. It is feature complete, but may still evolve slightly in the
  25 future releases. It can already be used to do everything that can be
  26 done in SimGrid, but you may have to adapt your code in future
  27 releases. When this happens, compiling your code will produce
  28 deprecation warnings for 4 releases (one year) before the removal of
  29 the old symbols.
  30 If you want an API that will never ever evolve in the future, you
  31 should use the deprecated MSG API instead.
  32
  33 Main Concepts
  34 *************
  35
  36 A typical SimGrid simulation is composed of several |Actors|_, that
  37 execute user-provided functions. The actors have to explicitly use the
  38 S4U interface to express their :ref:`computation <API_s4u_Exec>`,
  39 :ref:`communication <API_s4u_Comm>`, :ref:`disk usage <API_s4u_Io>`,
  40 and other |Activities|_, so that they get reflected within the
  41 simulator. These activities take place on resources such as |Hosts|_,
  42 |Links|_ and |Storages|_. SimGrid predicts the time taken by each
  43 activity and orchestrates the actors accordingly, waiting for the
  44 completion of these activities.
  45
  46
  47 When **communicating**, data is not directly sent to other actors but
  48 posted onto a |Mailbox|_ that serves as a rendez-vous point between
  49 communicating actors. This means that you don't need to know who you
  50 are talking to, you just put your communication `Put` request in a
  51 mailbox, and it will be matched with a complementary `Get`
  52 request.  Alternatively, actors can interact through **classical
  53 synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
  54 |Mutex|_ and |ConditionVariable|_.
  55
  56 Each actor is located on a simulated |Host|_. Each host is located
  57 itself in a |NetZone|_, that knows the networking path between one
  58 resource to another. Each NetZone is included in another one, forming
  59 a tree of NetZones which root zone contains the whole platform.
  60
  61 The :ref:`simgrid::s4u::this_actor <API_s4u_this_actor>` namespace
  62 provides many helper functions to simplify the code of actors.
  63
  64 - **Global Classes**
  65
  66   - :ref:`class s4u::Actor <API_s4u_Actor>`:
  67     Active entities executing your application.
  68   - :ref:`class s4u::Engine <API_s4u_Engine>`
  69     Simulation engine (singleton).
  70   - :ref:`class s4u::Mailbox <API_s4u_Mailbox>`
  71     Communication rendez-vous.
  72
  73 - **Platform Elements**
  74
  75   - :ref:`class s4u::Host <API_s4u_Host>`:
  76     Actor location, providing computational power.
  77   - :ref:`class s4u::Link <API_s4u_Link>`
  78     Interconnecting hosts.
  79   - :ref:`class s4u::NetZone <API_s4u_NetZone>`:
  80     Sub-region of the platform, containing resources (Hosts, Links, etc).
  81   - :ref:`class s4u::Storage <API_s4u_Storage>`
  82     Resource on which actors can write and read data.
  83   - :ref:`class s4u::VirtualMachine <API_s4u_VirtualMachine>`:
  84     Execution containers that can be moved between Hosts.
  85
  86 - **Activities** (:ref:`class s4u::Activity <API_s4u_Activity>`):
  87   The things that actors can do on resources
  88
  89   - :ref:`class s4u::Comm <API_s4u_Comm>`
  90     Communication activity, started on Mailboxes and consuming links.
  91   - :ref:`class s4u::Exec <API_s4u_Exec>`
  92     Computation activity, started on Host and consuming CPU resources.
  93   - :ref:`class s4u::Io <API_s4u_Io>`
  94     I/O activity, started on and consumming Storages.
  95
  96 - **Synchronization Mechanisms**: Classical IPC that actors can use
  97
  98   - :ref:`class s4u::Barrier <API_s4u_Barrier>`
  99   - :ref:`class s4u::ConditionVariable <API_s4u_ConditionVariable>`
 100   - :ref:`class s4u::Mutex <API_s4u_Mutex>`
 101   - :ref:`class s4u::Semaphore <API_s4u_Semaphore>`
 102
 103
 104 .. |Actors| replace:: **Actors**
 105 .. _Actors: api/classsimgrid_1_1s4u_1_1Actor.html
 106
 107 .. |Activities| replace:: **Activities**
 108 .. _Activities: api/classsimgrid_1_1s4u_1_1Activity.html
 109
 110 .. |Hosts| replace:: **Hosts**
 111 .. _Hosts: api/classsimgrid_1_1s4u_1_1Host.html
 112
 113 .. |Links| replace:: **Links**
 114 .. _Links: api/classsimgrid_1_1s4u_1_1Link.html
 115
 116 .. |Storages| replace:: **Storages**
 117 .. _Storages: api/classsimgrid_1_1s4u_1_1Storage.html
 118
 119 .. |VirtualMachines| replace:: **VirtualMachines**
 120 .. _VirtualMachines: api/classsimgrid_1_1s4u_1_1VirtualMachine.html
 121
 122 .. |Host| replace:: **Host**
 123 .. _Host: api/classsimgrid_1_1s4u_1_1Host.html
 124
 125 .. |Mailbox| replace:: **Mailbox**
 126 .. _Mailbox: api/classsimgrid_1_1s4u_1_1Mailbox.html
 127
 128 .. |NetZone| replace:: **NetZone**
 129 .. _NetZone: api/classsimgrid_1_1s4u_1_1NetZone.html
 130
 131 .. |Barrier| replace:: **Barrier**
 132 .. _Barrier: api/classsimgrid_1_1s4u_1_1Barrier.html
 133
 134 .. |ConditionVariable| replace:: **ConditionVariable**
 135 .. _ConditionVariable: api/classsimgrid_1_1s4u_1_1ConditionVariable.html
 136
 137 .. |Mutex| replace:: **Mutex**
 138 .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
 139
 140 .. THE EXAMPLES
 141
 142 .. include:: ../../examples/s4u/README.rst
 143
 144 Activities
 145 **********
 146
 147 Activities represent the actions that consume a resource, such as a
 148 :ref:`s4u::Comm <API_s4u_Comm>` that consumes the *transmiting power* of
 149 :ref:`s4u::Link <API_s4u_Link>` resources.
 150
 151 =======================
 152 Asynchronous Activities
 153 =======================
 154
 155 Every activity can be either **blocking** or **asynchronous**. For
 156 example, :cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>`
 157 and :cpp:func:`s4u::Mailbox::get() <simgrid::s4u::Mailbox::get>`
 158 create blocking communications: the actor is blocked until the
 159 completion of that communication. Asynchronous communications do not
 160 block the actor during their execution but progress on their own.
 161
 162 Once your asynchronous activity is started, you can test for its
 163 completion using :cpp:func:`s4u::Activity::test() <simgrid::s4u::Activity::test>`.
 164 This function returns ``true`` if the activity completed already.
 165 You can also use :cpp:func:`s4u::Activity::wait() <simgrid::s4u::Activity::wait>`
 166 to block until the completion of the activity. To wait for at most a given amount of time,
 167 use  :cpp:func:`s4u::Activity::wait_for() <simgrid::s4u::Activity::wait_for>`.
 168 Finally, to wait at most until a specified time limit, use
 169 :cpp:func:`s4u::Activity::wait_until() <simgrid::s4u::Activity::wait_until>`.
 170
 171 .. todo::
 172
 173    wait_for and wait_until are currently not implemented for Exec and Io activities.
 174
 175 Every kind of activities can be asynchronous:
 176
 177   - :ref:`s4u::CommPtr <API_s4u_Comm>` are created with
 178     :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
 179     :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
 180   - :ref:`s4u::IoPtr <API_s4u_Io>` are created with
 181     :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
 182     :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.
 183   - :ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
 184     :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
 185   - In the future, it will become possible to have asynchronous IPC
 186     such as asynchronous mutex lock requests.
 187
 188 The following example shows how to have several concurrent
 189 communications ongoing.  First, you have to declare a vector in which
 190 we will store the ongoing communications. It is also useful to have a
 191 vector of mailboxes.
 192
 193 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 194    :language: c++
 195    :start-after: init-begin
 196    :end-before: init-end
 197    :dedent: 4
 198
 199 Then, you start all the communications that should occur concurrently with
 200 :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.
 201 Finally, the actor waits for the completion of all of them at once
 202 with
 203 :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.
 204
 205 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 206    :language: c++
 207    :start-after: put-begin
 208    :end-before: put-end
 209    :dedent: 4
 210
 211
 212 =====================
 213 Activities Life cycle
 214 =====================
 215
 216 Sometimes, you want to change the setting of an activity before it even starts.
 217
 218 .. todo:: write this section
 219
 220 Memory Management
 221 *****************
 222
 223 For sake of simplicity, we use `RAII
 224 <https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
 225 everywhere in S4U. This is an idiom where resources are automatically
 226 managed through the context. Provided that you never manipulate
 227 objects of type Foo directly but always FooPtr references (which are
 228 defined as `boost::intrusive_ptr
 229 <http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
 230 <Foo>), you will never have to explicitely release the resource that
 231 you use nor to free the memory of unused objects.
 232
 233 Here is a little example:
 234
 235 .. code-block:: cpp
 236
 237    void myFunc()
 238    {
 239      simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
 240
 241      mutex->lock();   // use the mutex as a simple reference
 242      //  bla bla
 243      mutex->unlock();
 244
 245    } // The mutex gets automatically freed because the only existing reference gets out of scope
 246
 247 API Reference
 248 *************
 249
 250 .. _API_s4u_Activity:
 251
 252 =============
 253 s4u::Activity
 254 =============
 255
 256 .. doxygenclass:: simgrid::s4u::Activity
 257    :members:
 258    :protected-members:
 259    :undoc-members:
 260
 261 .. _API_s4u_Actor:
 262
 263 ==========
 264 s4u::Actor
 265 ==========
 266
 267 .. doxygentypedef:: ActorPtr
 268
 269 .. doxygenclass:: simgrid::s4u::Actor
 270    :members:
 271    :protected-members:
 272    :undoc-members:
 273
 274 .. _API_s4u_Barrier:
 275
 276 ============
 277 s4u::Barrier
 278 ============
 279
 280 .. doxygentypedef:: BarrierPtr
 281
 282 .. doxygenclass:: simgrid::s4u::Barrier
 283    :members:
 284    :protected-members:
 285    :undoc-members:
 286
 287 .. _API_s4u_Comm:
 288
 289 =========
 290 s4u::Comm
 291 =========
 292
 293 .. doxygentypedef:: CommPtr
 294
 295 .. doxygenclass:: simgrid::s4u::Comm
 296    :members:
 297    :protected-members:
 298    :undoc-members:
 299
 300 .. _API_s4u_ConditionVariable:
 301
 302 ======================
 303 s4u::ConditionVariable
 304 ======================
 305
 306 .. doxygentypedef:: ConditionVariablePtr
 307
 308 .. doxygenclass:: simgrid::s4u::ConditionVariable
 309    :members:
 310    :protected-members:
 311    :undoc-members:
 312
 313 .. _API_s4u_Engine:
 314
 315 ===========
 316 s4u::Engine
 317 ===========
 318
 319 .. doxygenclass:: simgrid::s4u::Engine
 320    :members:
 321    :protected-members:
 322    :undoc-members:
 323
 324 .. _API_s4u_Exec:
 325
 326 =========
 327 s4u::Exec
 328 =========
 329
 330 .. doxygentypedef:: ExecPtr
 331
 332 .. doxygenclass:: simgrid::s4u::Exec
 333    :members:
 334    :protected-members:
 335    :undoc-members:
 336
 337 .. _API_s4u_Host:
 338
 339 =========
 340 s4u::Host
 341 =========
 342
 343 .. doxygenclass:: simgrid::s4u::Host
 344    :members:
 345    :protected-members:
 346    :undoc-members:
 347
 348 .. _API_s4u_Io:
 349
 350 =======
 351 s4u::Io
 352 =======
 353
 354 .. doxygentypedef:: IoPtr
 355
 356 .. doxygenclass:: simgrid::s4u::Io
 357    :members:
 358    :protected-members:
 359    :undoc-members:
 360
 361 .. _API_s4u_Link:
 362
 363 =========
 364 s4u::Link
 365 =========
 366
 367 .. doxygenclass:: simgrid::s4u::Link
 368    :members:
 369    :protected-members:
 370    :undoc-members:
 371
 372 .. _API_s4u_Mailbox:
 373
 374 ============
 375 s4u::Mailbox
 376 ============
 377
 378 .. doxygentypedef:: MailboxPtr
 379
 380 .. doxygenclass:: simgrid::s4u::Mailbox
 381    :members:
 382    :protected-members:
 383    :undoc-members:
 384
 385 .. _API_s4u_Mutex:
 386
 387 ==========
 388 s4u::Mutex
 389 ==========
 390
 391 .. doxygentypedef:: MutexPtr
 392
 393 .. doxygenclass:: simgrid::s4u::Mutex
 394    :members:
 395    :protected-members:
 396    :undoc-members:
 397
 398 .. _API_s4u_NetZone:
 399
 400 ============
 401 s4u::NetZone
 402 ============
 403
 404 .. doxygenclass:: simgrid::s4u::NetZone
 405    :members:
 406    :protected-members:
 407    :undoc-members:
 408
 409 .. _API_s4u_Semaphore:
 410
 411 ==============
 412 s4u::Semaphore
 413 ==============
 414
 415 .. doxygentypedef:: SemaphorePtr
 416
 417 .. doxygenclass:: simgrid::s4u::Semaphore
 418    :members:
 419    :protected-members:
 420    :undoc-members:
 421
 422 .. _API_s4u_Storage:
 423
 424 ============
 425 s4u::Storage
 426 ============
 427
 428 .. doxygenclass:: simgrid::s4u::Storage
 429    :members:
 430    :protected-members:
 431    :undoc-members:
 432
 433 .. _API_s4u_VirtualMachine:
 434
 435 ===================
 436 s4u::VirtualMachine
 437 ===================
 438
 439 .. doxygenclass:: simgrid::s4u::VirtualMachine
 440    :members:
 441    :protected-members:
 442    :undoc-members:
 443
 444 .. _API_s4u_this_actor:
 445
 446 =========================
 447 namespace s4u::this_actor
 448 =========================
 449
 450
 451 .. doxygennamespace:: simgrid::s4u::this_actor