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