examples/s4u/README.rst

   1 .. S4U (Simgrid for you) is the modern interface of SimGrid, which new project should use.
   2 ..
   3 .. This file follows the ReStructured syntax to be included in the
   4 .. documentation, but it should remain readable directly.
   5
   6
   7 S4U Examples
   8 ************
   9
  10 SimGrid comes with an extensive set of examples, documented on this
  11 page. Most of them only demonstrate one single feature, with some
  12 larger examplars listed below.
  13
  14 The C++ examples can be found under examples/s4u while python examples
  15 are in examples/python. Each such directory contains the source code (also listed
  16 from this page), and the so-called tesh file containing how to call
  17 the binary obtained by compiling this example and also the expected
  18 output. Tesh files are used to turn each of our examples into an
  19 integration test. Some examples also contain other files, on need.
  20
  21 A good way to bootstrap your own project is to copy and combine some
  22 of the provided examples to constitute the skeleton of what you plan
  23 to simulate.
  24
  25 ===========================
  26 Actors: the Active Entities
  27 ===========================
  28
  29 .. _s4u_ex_actors:
  30
  31 Starting and Stoping Actors
  32 ---------------------------
  33
  34   - **Creating actors:**
  35     Most actors are started from the deployment XML file, because this
  36     is a :ref:`better scientific habbit <howto_science>`, but you can
  37     also create them directly from your code.
  38
  39     .. tabs::
  40
  41        .. group-tab:: C++
  42
  43           You create actors either:
  44
  45           - Directly with :cpp:func:`simgrid::s4u::Actor::create`
  46           - From XML with :cpp:func:`simgrid::s4u::Engine::register_actor` (if your actor is a class)
  47             or :cpp:func:`simgrid::s4u::Engine::register_function` (if your actor is a function)
  48             and then :cpp:func:`simgrid::s4u::Engine::load_deployment`
  49
  50           .. toggle-header::
  51              :header: View examples/s4u/actor-create/s4u-actor-create.cpp
  52
  53              `Download s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-create/s4u-actor-create.cpp?inline=false>`_
  54
  55              .. literalinclude:: ../../examples/s4u/actor-create/s4u-actor-create.cpp
  56                 :language: cpp
  57
  58        .. group-tab:: Python
  59
  60           You create actors either:
  61
  62           - Directly with :py:func:`simgrid.Actor.create()`
  63           - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
  64
  65           .. toggle-header::
  66              :header: View examples/python/actor-create/actor-create.py
  67
  68              `Download actor-create.py <https://framagit.org/simgrid/simgrid/raw/master/examples/python/actor-create/actor-create.py?inline=false>`_
  69
  70              .. literalinclude:: ../../examples/python/actor-create/actor-create.py
  71
  72        .. group-tab:: XML
  73
  74           The following file is used in both C++ and Python.
  75
  76           .. toggle-header::
  77              :header: View examples/python/actor-create/actor-create_d.xml
  78
  79              `Download actor-create_d.xml <https://framagit.org/simgrid/simgrid/raw/master/examples/python/actor-create/actor-create_d.xml?inline=false>`_
  80
  81              .. literalinclude:: ../../examples/python/actor-create/actor-create_d.xml
  82                 :language: xml
  83
  84   - **React to the end of actors:** You can attach callbacks to the end of
  85     actors. There is several ways of doing so, depending on whether you want to
  86     attach your callback to a given actor and on how you define the end of a
  87     given actor. User code probably want to react to the termination of an actor
  88     while some plugins want to react to the destruction (memory collection) of
  89     actors.
  90
  91     .. tabs::
  92
  93        .. group-tab:: C++
  94
  95           This example shows how to attach a callback to:
  96
  97           - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()`
  98           - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
  99           - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
 100
 101           .. toggle-header::
 102              :header: View examples/s4u/actor-exiting/s4u-actor-exiting.cpp
 103
 104              `Download s4u-actor-exiting.cpp <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-exiting/s4u-actor-exiting.cpp?inline=false>`_
 105
 106              .. literalinclude:: ../../examples/s4u/actor-exiting/s4u-actor-exiting.cpp
 107                 :language: cpp
 108
 109   - **Kill actors:**
 110     Actors can forcefully stop other actors.
 111
 112     .. tabs::
 113
 114        .. group-tab:: C++
 115
 116           See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`, :cpp:func:`simgrid::s4u::this_actor::exit`.
 117
 118           .. toggle-header::
 119              :header: View examples/s4u/actor-kill/s4u-actor-kill.cpp
 120
 121              `Download s4u-actor-kill.cpp <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-kill/s4u-actor-kill.cpp?inline=false>`_
 122
 123              .. literalinclude:: ../../examples/s4u/actor-kill/s4u-actor-kill.cpp
 124                 :language: cpp
 125
 126        .. group-tab:: Python
 127
 128           See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`.
 129
 130           .. toggle-header::
 131              :header: View examples/python/actor-kill/actor-kill.py
 132
 133              `Download actor-kill.py <https://framagit.org/simgrid/simgrid/raw/master/examples/python/actor-kill/actor-kill.py>`_
 134
 135              .. literalinclude:: ../../examples/python/actor-kill/actor-kill.py
 136
 137   - **Controling the actor life cycle from the XML:**
 138     You can specify a start time and a kill time in the deployment file.
 139
 140     .. tabs::
 141
 142        .. group-tab:: C++
 143
 144           This file is not really interesting: the important matter is in the XML file.
 145
 146           .. toggle-header::
 147              :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp
 148
 149              `Download s4u-actor-lifetime.cpp <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp?inline=false>`_
 150
 151              .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp
 152                 :language: cpp
 153
 154        .. group-tab:: XML
 155
 156           This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
 157
 158           .. toggle-header::
 159              :header: View examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml
 160
 161              `Download s4u-actor-lifetime_d.xml <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml?inline=false>`_
 162
 163              .. literalinclude:: ../../examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml
 164                 :language: xml
 165
 166   - **Daemonize actors:**
 167     Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
 168     actor into a daemon that will be automatically killed once the simulation is over.
 169
 170     .. tabs::
 171
 172        .. group-tab:: C++
 173
 174           See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
 175
 176           .. toggle-header::
 177              :header: View examples/s4u/actor-daemon/s4u-actor-daemon.cpp
 178
 179              `Download s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/raw/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp?inline=false>`_
 180
 181              .. literalinclude:: ../../examples/s4u/actor-daemon/s4u-actor-daemon.cpp
 182                 :language: cpp
 183
 184        .. group-tab:: Python
 185
 186           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 187
 188           .. toggle-header::
 189              :header: View examples/python/actor-daemon/actor-daemon.py
 190
 191              `Download actor-daemon.py <https://framagit.org/simgrid/simgrid/raw/master/examples/python/actor-daemon/actor-daemon.py?inline=false>`_
 192
 193              .. literalinclude:: ../../examples/python/actor-daemon/actor-daemon.py
 194
 195 Inter-Actors Interactions
 196 -------------------------
 197
 198 See also the examples on :ref:`inter-actors communications
 199 <s4u_ex_communication>` and the ones on :ref:`classical
 200 synchronization objects <s4u_ex_IPC>`.
 201
 202   - **Suspend and Resume actors:**
 203     Actors can be suspended and resumed during their executions.
 204
 205     - |cpp| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-suspend/s4u-actor-suspend.cpp>`_
 206       :cpp:func:`simgrid::s4u::this_actor::suspend()`,
 207       :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 208     - |py|  `examples/python/actor-suspend/actor-suspend.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-suspend/actor-suspend.py>`_
 209       :py:func:`simgrid.this_actor.suspend()`,
 210       :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, :py:func:`simgrid.Actor.is_suspended()`.
 211
 212   - **Migrating Actors:**
 213     Actors can move or be moved from a host to another very easily.
 214
 215     - |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migrate/s4u-actor-migrate.cpp>`_
 216       :cpp:func:`simgrid::s4u::this_actor::migrate()`
 217     - |py|  `examples/python/actor-migrate/actor-migrate.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-migrate/actor-migrate.py>`_
 218       :py:func:`simgrid.this_actor.migrate()`
 219
 220   - **Waiting for the termination of an actor:** (joining on it)
 221     You can block the current actor until the end of another actor.
 222
 223     - |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
 224       :cpp:func:`simgrid::s4u::Actor::join()`
 225     - |py|  `examples/python/actor-join/actor-join.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-join/actor-join.py>`_
 226       :py:func:`simgrid.Actor.join()`
 227
 228   - **Yielding to other actors**.
 229     The ```yield()``` function interrupts the execution of the current
 230     actor, leaving a chance to the other actors that are ready to run
 231     at this timestamp.
 232
 233     - |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
 234       :cpp:func:`simgrid::s4u::this_actor::yield()`
 235     - |py|  `examples/python/actor-yield/actor-yield.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-yield/actor-yield.py>`_
 236       :py:func:`simgrid.this_actor.yield_()`
 237
 238 Traces Replay as a Workload
 239 ---------------------------
 240
 241 This section details how to run trace-driven simulations. It is very
 242 handy when you want to test an algorithm or protocol that only react
 243 to external events. For example, many P2P protocols react to user
 244 requests, but do nothing if there is no such event.
 245
 246 In such situations, you should write your protocol in C++, and separate
 247 the workload that you want to play onto your protocol in a separate
 248 text file. Declare a function handling each type of the events in your
 249 trace, register them using :cpp:func:`xbt_replay_action_register()` in
 250 your main, and then run the simulation.
 251
 252 Then, you can either have one trace file containing all your events,
 253 or a file per simulated process: the former may be easier to work
 254 with, but the second is more efficient on very large traces. Check
 255 also the tesh files in the example directories for details.
 256
 257   - **Communication replay:**
 258     Presents a set of event handlers reproducing classical communication
 259     primitives (asynchronous send/receive at the moment).
 260     |br| `examples/s4u/replay-comm/s4u-replay-comm.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/replay-comm/s4u-replay-comm.cpp>`_
 261
 262   - **I/O replay:**
 263     Presents a set of event handlers reproducing classical I/O
 264     primitives (open, read, close).
 265     |br| `examples/s4u/replay-io/s4u-replay-io.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/replay-io/s4u-replay-io.cpp>`_
 266
 267 ==========================
 268 Activities: what Actors do
 269 ==========================
 270
 271 .. _s4u_ex_communication:
 272
 273 Communications on the Network
 274 -----------------------------
 275
 276  - **Basic asynchronous communications:**
 277    Illustrates how to have non-blocking communications, that are
 278    communications running in the background leaving the process free
 279    to do something else during their completion.
 280
 281    - |cpp| `examples/s4u/async-wait/s4u-async-wait.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-wait/s4u-async-wait.cpp>`_
 282      :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`
 283    - |py|  `examples/python/async-wait/async-wait.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-wait/async-wait.py>`_
 284      :py:func:`simgrid.Mailbox.put_async()` :py:func:`simgrid.Comm.wait()`
 285
 286  - **Waiting for all communications in a set:**
 287    The `wait_all()` function is useful when you want to block until
 288    all activities in a given set have completed.
 289
 290    - |cpp| `examples/s4u/async-waitall/s4u-async-waitall.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitall/s4u-async-waitall.cpp>`_
 291      :cpp:func:`simgrid::s4u::Comm::wait_all()`
 292    - |py| `examples/python/async-waitall/async-waitall.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-waitall/async-waitall.py>`_
 293      :py:func:`simgrid.Comm.wait_all()`
 294
 295  - **Waiting for the first completed communication in a set:**
 296    The `wait_any()` function is useful
 297    when you want to block until one activity of the set completes, no
 298    matter which terminates first.
 299
 300    - |cpp| `examples/s4u/async-waitany/s4u-async-waitany.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitany/s4u-async-waitany.cpp>`_
 301      :cpp:func:`simgrid::s4u::Comm::wait_any()`
 302    - |py| `examples/python/async-waitany/async-waitany.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-waitany/async-waitany.py>`_
 303      :py:func:`simgrid.Comm.wait_any()`
 304
 305 .. todo:: review the `ready` and `waituntil` examples and add them here.
 306
 307 .. _s4u_ex_execution:
 308
 309 Executions on the CPU
 310 ---------------------
 311
 312   - **Basic execution:**
 313     The computations done in your program are not reported to the
 314     simulated world, unless you explicitly request the simulator to pause
 315     the actor until a given amount of flops gets computed on its simulated
 316     host. Some executions can be given an higher priority so that they
 317     get more resources.
 318
 319     - |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
 320     - |py|  `examples/python/exec-basic/exec-basic.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-basic/exec-basic.py>`_
 321
 322   - **Asynchronous execution:**
 323     You can start asynchronous executions, just like you would fire
 324     background threads.
 325
 326     - |cpp| `examples/s4u/exec-async/s4u-exec-async.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-async/s4u-exec-async.cpp>`_
 327     - |py|  `examples/python/exec-async/exec-async.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-async/exec-async.py>`_
 328
 329   - **Remote execution:**
 330     You can start executions on remote hosts, or even change the host
 331     on which they occur during their execution.
 332
 333     - |cpp| `examples/s4u/exec-remote/s4u-exec-remote.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-remote/s4u-exec-remote.cpp>`_
 334     - |py| `examples/python/exec-remote/exec-remote.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-remote/exec-remote.py>`_
 335
 336   - **Parallel executions:**
 337     These objects are convenient abstractions of parallel
 338     computational kernels that span over several machines, such as a
 339     PDGEM and the other ScaLAPACK routines. Note that this only works
 340     with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
 341     |br| `examples/s4u/exec-ptask/s4u-exec-ptask.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-ptask/s4u-exec-ptask.cpp>`_
 342
 343   - **Using Pstates on a host:**
 344     `examples/platforms/energy_platform.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/energy_platform.xml>`_
 345     shows how define a set of pstates in the XML. The current pstate
 346     of an host can then be accessed and changed from the program.
 347
 348     - |cpp| `examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp>`_
 349       :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 350     - |py|  `examples/python/exec-dvfs/exec-dvfs.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-dvfs/exec-dvfs.py>`_
 351       :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 352
 353 I/O on Disks and Files
 354 ----------------------
 355
 356 SimGrid provides two levels of abstraction to interact with the
 357 simulated disks. At the simplest level, you simply create read and
 358 write actions on the disk resources.
 359
 360   - **Access to raw disk devices:**
 361     This example illustrates how to simply read and write data on a
 362     simulated disk resource.
 363     |br| `examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp>`_
 364
 365 The FileSystem plugin provides a more detailed view, with the
 366 classical operations over files: open, move, unlink, and of course
 367 read and write. The file and disk sizes are also dealt with and can
 368 result in short reads and short write, as in reality.
 369
 370   - **File Management:**
 371     This example illustrates the use of operations on files
 372     (read, write, seek, tell, unlink, etc).
 373     |br| `examples/s4u/io-file-system/s4u-io-file-system.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-file-system/s4u-io-file-system.cpp>`_
 374
 375   - **Remote I/O:**
 376     I/O operations on files can also be done in a remote fashion,
 377     i.e. when the accessed disk is not mounted on the caller's host.
 378     |br| `examples/s4u/io-file-remote/s4u-io-file-remote.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-file-remote/s4u-io-file-remote.cpp>`_
 379
 380 .. _s4u_ex_IPC:
 381
 382 Classical synchronization objects
 383 ---------------------------------
 384
 385  - **Mutex:**
 386    Shows how to use simgrid::s4u::Mutex synchronization objects.
 387    |br| `examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp>`_
 388
 389  - **Barrier:**
 390    Shows how to use simgrid::s4u::Barrier synchronization objects.
 391    |br| `examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp>`_
 392
 393  - **Semaphore:**
 394    Shows how to use simgrid::s4u::Semaphore synchronization objects.
 395    |br| `examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp>`_
 396
 397 =============================
 398 Interacting with the Platform
 399 =============================
 400
 401  - **Retrieving the list of hosts matching a given criteria:**
 402    Shows how to filter the actors that match a given criteria.
 403    |br| `examples/s4u/engine-filtering/s4u-engine-filtering.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/engine-filtering/s4u-engine-filtering.cpp>`_
 404
 405  - **User-defined properties:**
 406    You can attach arbitrary information to most platform elements from
 407    the XML file, and then interact with these values from your
 408    program. Note that the changes are not written permanently on disk,
 409    in the XML file nor anywhere else. They only last until the end of
 410    your simulation.
 411
 412    - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 413    - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 414    - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 415    - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 416
 417    |br| `examples/s4u/platform-properties/s4u-platform-properties.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/platform-properties/s4u-platform-properties.cpp>`_
 418    |br| `examples/s4u/platform-properties/s4u-platform-properties_d.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/platform-properties/s4u-platform-properties_d.xml>`_
 419    |br| `examples/platforms/prop.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/prop.xml>`_
 420
 421  - **Specifying state profiles:** shows how to specify when the
 422    resources must be turned off and on again, and how to react to such
 423    failures in your code.
 424
 425    |br| `examples/platforms/small_platform_failures.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/small_platform_failures.xml>`_
 426    |br| The state profiles in `examples/platforms/profiles <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/profiles>`_
 427
 428  - **Specifying speed profiles:** shows how to specify an external
 429    load to resources, variating their peak speed over time.
 430
 431    |br| `examples/platforms/small_platform_profile.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/small_platform_profile.xml>`_
 432    |br| The speed, bandwidth and latency profiles in `examples/platforms/profiles  <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/profiles>`_
 433
 434 =================
 435 Energy Simulation
 436 =================
 437
 438   - **Describing the energy profiles in the platform:**
 439     This platform file contains the energy profile of each links and
 440     hosts, which is necessary to get energy consumption predictions.
 441     As usual, you should not trust our example, and you should strive
 442     to double-check that your instantiation matches your target platform.
 443     |br| `examples/platforms/energy_platform.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/energy_platform.xml>`_
 444
 445   - **Consumption due to the CPU:**
 446     This example shows how to retrieve the amount of energy consumed
 447     by the CPU during computations, and the impact of the pstate.
 448     |br| `examples/s4u/energy-exec/s4u-energy-exec.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-exec/s4u-energy-exec.cpp>`_
 449
 450   - **Consumption due to the network:**
 451     This example shows how to retrieve and display the energy consumed
 452     by the network during communications.
 453     |br| `examples/s4u/energy-link/s4u-energy-link.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-link/s4u-energy-link.cpp>`_
 454
 455   - **Modeling the shutdown and boot of hosts:**
 456     Simple example of model of model for the energy consumption during
 457     the host boot and shutdown periods.
 458     |br| `examples/s4u/energy-boot/platform_boot.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/platform_boot.xml>`_
 459     |br| `examples/s4u/energy-boot/s4u-energy-boot.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/s4u-energy-boot.cpp>`_
 460
 461 =======================
 462 Tracing and Visualizing
 463 =======================
 464
 465 Tracing can be activated by various configuration options which
 466 are illustrated in these example. See also the
 467 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 468
 469 It is interesting to run the process-create example with the following
 470 options to see the task executions:
 471
 472   - **Platform Tracing:**
 473     This program is a toy example just loading the platform, so that
 474     you can play with the platform visualization. Recommanded options:
 475     ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 476     |br| `examples/s4u/trace-platform/s4u-trace-platform.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/trace-platform/s4u-trace-platform.cpp>`_
 477
 478 ========================
 479 Larger SimGrid Examplars
 480 ========================
 481
 482 This section contains application examples that are somewhat larger
 483 than the previous examples.
 484
 485   - **Ping Pong:**
 486     This simple example just sends one message back and forth.
 487     The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to
 488     the simulators (as detailed in Section :ref:`options`).
 489     |br| `examples/s4u/app-pingpong/s4u-app-pingpong.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-pingpong/s4u-app-pingpong.cpp>`_
 490
 491   - **Token ring:**
 492     Shows how to implement a classical communication pattern, where a
 493     token is exchanged along a ring to reach every participant.
 494     |br| `examples/s4u/app-token-ring/s4u-app-token-ring.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-token-ring/s4u-app-token-ring.cpp>`_
 495
 496   - **Master Workers:**
 497     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
 498     processes. This example comes in two equivalent variants, one
 499     where the actors are specified as simple functions (which is easier to
 500     understand for newcomers) and one where the actors are specified
 501     as classes (which is more powerful for the users wanting to build
 502     their own projects upon the example).
 503     |br| `examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp>`_
 504     |br| `examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp>`_
 505
 506 Data diffusion
 507 --------------
 508
 509   - **Bit Torrent:**
 510     Classical protocol for Peer-to-Peer data diffusion.
 511     |br| `examples/s4u/app-bittorrent/s4u-bittorrent.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-bittorrent/s4u-bittorrent.cpp>`_
 512
 513   - **Chained Send:**
 514     Data broadcast over a ring of processes.
 515     |br| `examples/s4u/app-chainsend/s4u-app-chainsend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-chainsend/s4u-app-chainsend.cpp>`_
 516
 517 Distributed Hash Tables (DHT)
 518 -----------------------------
 519
 520   - **Chord Protocol**
 521     One of the most famous DHT protocol.
 522     |br| `examples/s4u/dht-chord/s4u-dht-chord.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/dht-chord/s4u-dht-chord.cpp>`_
 523
 524 .. _s4u_ex_clouds:
 525
 526 Simulating Clouds
 527 -----------------
 528
 529   - **Cloud basics**
 530     This example starts some computations both on PMs and VMs, and
 531     migrates some VMs around.
 532     |br| `examples/s4u/cloud-simple/s4u-cloud-simple.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/cloud-simple/s4u-cloud-simple.cpp>`_
 533
 534 .. TODO:: document here the examples about clouds and plugins
 535
 536 =======================
 537 Model-Checking Examples
 538 =======================
 539
 540 The model-checker can be used to exhaustively search for issues in the
 541 tested application. It must be activated at compile time, but this
 542 mode is rather experimental in SimGrid (as of v3.22). You should not
 543 enable it unless you really want to formally verify your applications:
 544 SimGrid is slower and maybe less robust when MC is enabled.
 545
 546   - **Failing assert**
 547     In this example, two actors send some data to a central server,
 548     which asserts that the messages are always received in the same order.
 549     This is obviously wrong, and the model-checker correctly finds a
 550     counter-example to that assertion.
 551     |br| `examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp>`_
 552
 553 .. |br| raw:: html
 554
 555    <br />
 556
 557 .. |cpp| image:: /img/lang_cpp.png
 558    :align: middle
 559    :width: 12
 560
 561 .. |py| image:: /img/lang_python.png
 562    :align: middle
 563    :width: 12