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 |API_s4u_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 |API_s4u_Activities|_, so that they get reflected within the
  41 simulator. These activities take place on resources such as |API_s4u_Hosts|_,
  42 |API_s4u_Links|_ and |API_s4u_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 |API_s4u_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 |API_s4u_Barrier|_, |API_s4u_Semaphore|_,
  54 |API_s4u_Mutex|_ and |API_s4u_ConditionVariable|_.
  55
  56 Each actor is located on a simulated |API_s4u_Host|_. Each host is located
  57 itself in a |API_s4u_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 .. |API_s4u_Actors| replace:: **Actors**
 105 .. _API_s4u_Actors: #s4u-actor
 106
 107 .. |API_s4u_Activities| replace:: **Activities**
 108 .. _API_s4u_Activities: #s4u-activity
 109
 110 .. |API_s4u_Hosts| replace:: **Hosts**
 111 .. _API_s4u_Hosts: #s4u-host
 112
 113 .. |API_s4u_Links| replace:: **Links**
 114 .. _API_s4u_Links: #s4u-link
 115
 116 .. |API_s4u_Storages| replace:: **Storages**
 117 .. _API_s4u_Storages: #s4u-storage
 118
 119 .. |API_s4u_VirtualMachines| replace:: **VirtualMachines**
 120 .. _API_s4u_VirtualMachines: #s4u-virtualmachine
 121
 122 .. |API_s4u_Host| replace:: **Host**
 123
 124 .. |API_s4u_Mailbox| replace:: **Mailbox**
 125
 126 .. |API_s4u_NetZone| replace:: **NetZone**
 127
 128 .. |API_s4u_Barrier| replace:: **Barrier**
 129
 130 .. |API_s4u_Semaphore| replace:: **Semaphore**
 131
 132 .. |API_s4u_ConditionVariable| replace:: **ConditionVariable**
 133
 134 .. |API_s4u_Mutex| replace:: **Mutex**
 135
 136 .. THE EXAMPLES
 137
 138 .. include:: ../../examples/s4u/README.rst
 139
 140 Activities
 141 **********
 142
 143 Activities represent the actions that consume a resource, such as a
 144 :ref:`s4u::Comm <API_s4u_Comm>` that consumes the *transmiting power* of
 145 :ref:`s4u::Link <API_s4u_Link>` resources.
 146
 147 =======================
 148 Asynchronous Activities
 149 =======================
 150
 151 Every activity can be either **blocking** or **asynchronous**. For
 152 example, :cpp:func:`s4u::Mailbox::put() <simgrid::s4u::Mailbox::put>`
 153 and :cpp:func:`s4u::Mailbox::get() <simgrid::s4u::Mailbox::get>`
 154 create blocking communications: the actor is blocked until the
 155 completion of that communication. Asynchronous communications do not
 156 block the actor during their execution but progress on their own.
 157
 158 Once your asynchronous activity is started, you can test for its
 159 completion using :cpp:func:`s4u::Activity::test() <simgrid::s4u::Activity::test>`.
 160 This function returns ``true`` if the activity completed already.
 161 You can also use :cpp:func:`s4u::Activity::wait() <simgrid::s4u::Activity::wait>`
 162 to block until the completion of the activity. To wait for at most a given amount of time,
 163 use  :cpp:func:`s4u::Activity::wait_for() <simgrid::s4u::Activity::wait_for>`.
 164 Finally, to wait at most until a specified time limit, use
 165 :cpp:func:`s4u::Activity::wait_until() <simgrid::s4u::Activity::wait_until>`.
 166
 167 .. todo::
 168
 169    wait_for and wait_until are currently not implemented for Exec and Io activities.
 170
 171 Every kind of activities can be asynchronous:
 172
 173   - :ref:`s4u::CommPtr <API_s4u_Comm>` are created with
 174     :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>` and
 175     :cpp:func:`s4u::Mailbox::get_async() <simgrid::s4u::Mailbox::get_async>`.
 176   - :ref:`s4u::IoPtr <API_s4u_Io>` are created with
 177     :cpp:func:`s4u::Storage::read_async() <simgrid::s4u::Storage::read_async>` and
 178     :cpp:func:`s4u::Storage::write_async() <simgrid::s4u::Storage::write_async>`.
 179   - :ref:`s4u::ExecPtr <API_s4u_Exec>` are created with
 180     :cpp:func:`s4u::Host::exec_async() <simgrid::s4u::Host::exec_async>`.
 181   - In the future, it will become possible to have asynchronous IPC
 182     such as asynchronous mutex lock requests.
 183
 184 The following example shows how to have several concurrent
 185 communications ongoing.  First, you have to declare a vector in which
 186 we will store the ongoing communications. It is also useful to have a
 187 vector of mailboxes.
 188
 189 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 190    :language: c++
 191    :start-after: init-begin
 192    :end-before: init-end
 193    :dedent: 4
 194
 195 Then, you start all the communications that should occur concurrently with
 196 :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.
 197 Finally, the actor waits for the completion of all of them at once
 198 with
 199 :cpp:func:`s4u::Comm::wait_all() <simgrid::s4u::Comm::wait_all>`.
 200
 201 .. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
 202    :language: c++
 203    :start-after: put-begin
 204    :end-before: put-end
 205    :dedent: 4
 206
 207
 208 =====================
 209 Activities Life cycle
 210 =====================
 211
 212 Sometimes, you want to change the setting of an activity before it even starts.
 213
 214 .. todo:: write this section
 215
 216 Memory Management
 217 *****************
 218
 219 For sake of simplicity, we use `RAII
 220 <https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
 221 everywhere in S4U. This is an idiom where resources are automatically
 222 managed through the context. Provided that you never manipulate
 223 objects of type Foo directly but always FooPtr references (which are
 224 defined as `boost::intrusive_ptr
 225 <http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
 226 <Foo>), you will never have to explicitely release the resource that
 227 you use nor to free the memory of unused objects.
 228
 229 Here is a little example:
 230
 231 .. code-block:: cpp
 232
 233    void myFunc()
 234    {
 235      simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
 236
 237      mutex->lock();   // use the mutex as a simple reference
 238      //  bla bla
 239      mutex->unlock();
 240
 241    } // The mutex gets automatically freed because the only existing reference gets out of scope
 242
 243 API Reference
 244 *************
 245
 246 .. _API_s4u_Activity:
 247
 248 =============
 249 s4u::Activity
 250 =============
 251
 252 .. doxygenclass:: simgrid::s4u::Activity
 253    :members:
 254    :protected-members:
 255    :undoc-members:
 256
 257 .. _API_s4u_Actor:
 258
 259 ==========
 260 s4u::Actor
 261 ==========
 262
 263 .. doxygentypedef:: ActorPtr
 264
 265 .. doxygenclass:: simgrid::s4u::Actor
 266    :members:
 267    :protected-members:
 268    :undoc-members:
 269
 270 .. _API_s4u_Barrier:
 271
 272 ============
 273 s4u::Barrier
 274 ============
 275
 276 .. doxygentypedef:: BarrierPtr
 277
 278 .. doxygenclass:: simgrid::s4u::Barrier
 279    :members:
 280    :protected-members:
 281    :undoc-members:
 282
 283 .. _API_s4u_Comm:
 284
 285 =========
 286 s4u::Comm
 287 =========
 288
 289 .. doxygentypedef:: CommPtr
 290
 291 .. doxygenclass:: simgrid::s4u::Comm
 292    :members:
 293    :protected-members:
 294    :undoc-members:
 295
 296 .. _API_s4u_ConditionVariable:
 297
 298 ======================
 299 s4u::ConditionVariable
 300 ======================
 301
 302 .. doxygentypedef:: ConditionVariablePtr
 303
 304 .. doxygenclass:: simgrid::s4u::ConditionVariable
 305    :members:
 306    :protected-members:
 307    :undoc-members:
 308
 309 .. _API_s4u_Engine:
 310
 311 ===========
 312 s4u::Engine
 313 ===========
 314
 315 .. doxygenclass:: simgrid::s4u::Engine
 316    :members:
 317    :protected-members:
 318    :undoc-members:
 319
 320 .. _API_s4u_Exec:
 321
 322 =========
 323 s4u::Exec
 324 =========
 325
 326 .. doxygentypedef:: ExecPtr
 327
 328 .. doxygenclass:: simgrid::s4u::Exec
 329    :members:
 330    :protected-members:
 331    :undoc-members:
 332
 333 .. _API_s4u_Host:
 334
 335 =========
 336 s4u::Host
 337 =========
 338
 339 .. doxygenclass:: simgrid::s4u::Host
 340    :members:
 341    :protected-members:
 342    :undoc-members:
 343
 344 .. _API_s4u_Io:
 345
 346 =======
 347 s4u::Io
 348 =======
 349
 350 .. doxygentypedef:: IoPtr
 351
 352 .. doxygenclass:: simgrid::s4u::Io
 353    :members:
 354    :protected-members:
 355    :undoc-members:
 356
 357 .. _API_s4u_Link:
 358
 359 =========
 360 s4u::Link
 361 =========
 362
 363 .. doxygenclass:: simgrid::s4u::Link
 364    :members:
 365    :protected-members:
 366    :undoc-members:
 367
 368 .. _API_s4u_Mailbox:
 369
 370 ============
 371 s4u::Mailbox
 372 ============
 373
 374 .. doxygentypedef:: MailboxPtr
 375
 376 .. doxygenclass:: simgrid::s4u::Mailbox
 377    :members:
 378    :protected-members:
 379    :undoc-members:
 380
 381 .. _API_s4u_Mutex:
 382
 383 ==========
 384 s4u::Mutex
 385 ==========
 386
 387 .. doxygentypedef:: MutexPtr
 388
 389 .. doxygenclass:: simgrid::s4u::Mutex
 390    :members:
 391    :protected-members:
 392    :undoc-members:
 393
 394 .. _API_s4u_NetZone:
 395
 396 ============
 397 s4u::NetZone
 398 ============
 399
 400 .. doxygenclass:: simgrid::s4u::NetZone
 401    :members:
 402    :protected-members:
 403    :undoc-members:
 404
 405 .. _API_s4u_Semaphore:
 406
 407 ==============
 408 s4u::Semaphore
 409 ==============
 410
 411 .. doxygentypedef:: SemaphorePtr
 412
 413 .. doxygenclass:: simgrid::s4u::Semaphore
 414    :members:
 415    :protected-members:
 416    :undoc-members:
 417
 418 .. _API_s4u_Storage:
 419
 420 ============
 421 s4u::Storage
 422 ============
 423
 424 .. doxygenclass:: simgrid::s4u::Storage
 425    :members:
 426    :protected-members:
 427    :undoc-members:
 428
 429 .. _API_s4u_VirtualMachine:
 430
 431 ===================
 432 s4u::VirtualMachine
 433 ===================
 434
 435 .. doxygenclass:: simgrid::s4u::VirtualMachine
 436    :members:
 437    :protected-members:
 438    :undoc-members:
 439
 440 .. _API_s4u_this_actor:
 441
 442 =========================
 443 namespace s4u::this_actor
 444 =========================
 445
 446
 447 .. doxygennamespace:: simgrid::s4u::this_actor