examples/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 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 .. _s4u_ex_actors:
  26
  27 ===========================
  28 Actors: the Active Entities
  29 ===========================
  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        .. example-tab:: examples/s4u/actor-create/s4u-actor-create.cpp
  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        .. example-tab:: examples/python/actor-create/actor-create.py
  51
  52           You create actors either:
  53
  54           - Directly with :py:func:`simgrid.Actor.create()`
  55           - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
  56
  57        .. example-tab:: examples/c/actor-create/actor-create.c
  58
  59           You create actors either:
  60
  61           - Directly with :cpp:func:`sg_actor_create()` followed by :cpp:func:`sg_actor_start`.
  62           - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
  63
  64        .. example-tab:: examples/python/actor-create/actor-create_d.xml
  65
  66           The following file is used in both C++ and Python.
  67
  68   - **React to the end of actors:** You can attach callbacks to the end of
  69     actors. There is several ways of doing so, depending on whether you want to
  70     attach your callback to a given actor and on how you define the end of a
  71     given actor. User code probably want to react to the termination of an actor
  72     while some plugins want to react to the destruction (memory collection) of
  73     actors.
  74
  75     .. tabs::
  76
  77        .. example-tab:: examples/s4u/actor-exiting/s4u-actor-exiting.cpp
  78
  79           This example shows how to attach a callback to:
  80
  81           - the end of a specific actor: :cpp:func:`simgrid::s4u::this_actor::on_exit()`
  82           - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
  83           - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
  84
  85        .. example-tab:: examples/c/actor-exiting/actor-exiting.c
  86
  87           This example shows how to attach a callback to the end of a specific actor with
  88           :cpp:func:`sg_actor_on_exit()`.
  89
  90   - **Kill actors:**
  91     Actors can forcefully stop other actors.
  92
  93     .. tabs::
  94
  95        .. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
  96
  97           See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
  98           :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.
  99
 100        .. example-tab:: examples/python/actor-kill/actor-kill.py
 101
 102           See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
 103           :py:func:`simgrid.this_actor.on_exit`.
 104
 105        .. example-tab:: examples/c/actor-kill/actor-kill.c
 106
 107           See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
 108
 109   - **Controling the actor life cycle from the XML:**
 110     You can specify a start time and a kill time in the deployment file.
 111
 112     .. tabs::
 113
 114        .. example-tab:: examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp
 115
 116           This file is not really interesting: the important matter is in the XML file.
 117
 118        .. example-tab:: examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml
 119
 120           This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
 121
 122        .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
 123
 124           This file is not really interesting: the important matter is in the XML file.
 125
 126   - **Daemonize actors:**
 127     Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
 128     actor into a daemon that will be automatically killed once the simulation is over.
 129
 130     .. tabs::
 131
 132        .. example-tab:: examples/s4u/actor-daemon/s4u-actor-daemon.cpp
 133
 134           See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
 135
 136        .. example-tab:: examples/python/actor-daemon/actor-daemon.py
 137
 138           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 139
 140        .. example-tab:: examples/c/actor-daemon/actor-daemon.c
 141
 142           See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
 143
 144   - **Specify the stack size to use**
 145     The stack size can be specified by default on the command line,
 146     globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config(std::string)`,
 147     or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
 148
 149     .. tabs::
 150
 151        .. example-tab:: examples/s4u/actor-stacksize/s4u-actor-stacksize.cpp
 152
 153 Inter-Actors Interactions
 154 -------------------------
 155
 156 See also the examples on :ref:`inter-actors communications
 157 <s4u_ex_communication>` and the ones on :ref:`classical
 158 synchronization objects <s4u_ex_IPC>`.
 159
 160   - **Suspend and Resume actors:**
 161     Actors can be suspended and resumed during their executions.
 162
 163     .. tabs::
 164
 165        .. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp
 166
 167           See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
 168           :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
 169           :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 170
 171        .. example-tab:: examples/python/actor-suspend/actor-suspend.py
 172
 173           See also :py:func:`simgrid.this_actor.suspend()`,
 174           :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
 175           :py:func:`simgrid.Actor.is_suspended()`.
 176
 177        .. example-tab:: examples/c/actor-suspend/actor-suspend.c
 178
 179           See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
 180           :cpp:func:`sg_actor_is_suspended()`.
 181
 182   - **Migrating Actors:**
 183     Actors can move or be moved from a host to another very easily. It amount to setting them on a new host.
 184
 185     .. tabs::
 186
 187        .. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp
 188
 189           See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
 190
 191        .. example-tab:: examples/python/actor-migrate/actor-migrate.py
 192
 193           See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
 194
 195        .. example-tab:: examples/c/actor-migrate/actor-migrate.c
 196
 197           See also :cpp:func:`sg_actor_set_host()`.
 198
 199   - **Waiting for the termination of an actor:** (joining on it)
 200     You can block the current actor until the end of another actor.
 201
 202     .. tabs::
 203
 204        .. example-tab:: examples/s4u/actor-join/s4u-actor-join.cpp
 205
 206           See also :cpp:func:`simgrid::s4u::Actor::join()`.
 207
 208        .. example-tab:: examples/python/actor-join/actor-join.py
 209
 210           See also :py:func:`simgrid.Actor.join()`.
 211
 212        .. example-tab:: examples/c/actor-join/actor-join.c
 213
 214           See also :cpp:func:`sg_actor_join`.
 215
 216   - **Yielding to other actors**.
 217     The ```yield()``` function interrupts the execution of the current
 218     actor, leaving a chance to the other actors that are ready to run
 219     at this timestamp.
 220
 221     .. tabs::
 222
 223        .. example-tab:: examples/s4u/actor-yield/s4u-actor-yield.cpp
 224
 225           See also :cpp:func:`simgrid::s4u::this_actor::yield()`.
 226
 227        .. example-tab:: examples/python/actor-yield/actor-yield.py
 228
 229           See also :py:func:`simgrid.this_actor.yield_()`.
 230
 231        .. example-tab:: examples/c/actor-yield/actor-yield.c
 232
 233           See also :cpp:func:`sg_actor_yield()`.
 234
 235 Traces Replay as a Workload
 236 ---------------------------
 237
 238 This section details how to run trace-driven simulations. It is very
 239 handy when you want to test an algorithm or protocol that only react
 240 to external events. For example, many P2P protocols react to user
 241 requests, but do nothing if there is no such event.
 242
 243 In such situations, you should write your protocol in C++, and separate
 244 the workload that you want to play onto your protocol in a separate
 245 text file. Declare a function handling each type of the events in your
 246 trace, register them using :cpp:func:`xbt_replay_action_register()` in
 247 your main, and then run the simulation.
 248
 249 Then, you can either have one trace file containing all your events,
 250 or a file per simulated process: the former may be easier to work
 251 with, but the second is more efficient on very large traces. Check
 252 also the tesh files in the example directories for details.
 253
 254   - **Communication replay:**
 255     Presents a set of event handlers reproducing classical communication
 256     primitives (asynchronous send/receive at the moment).
 257
 258     .. tabs::
 259
 260        .. example-tab:: 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
 266     .. tabs::
 267
 268        .. example-tab:: examples/s4u/replay-io/s4u-replay-io.cpp
 269
 270 ==========================
 271 Activities: what Actors do
 272 ==========================
 273
 274 .. _s4u_ex_communication:
 275
 276 Communications on the Network
 277 -----------------------------
 278
 279  - **Basic asynchronous communications:**
 280    Illustrates how to have non-blocking communications, that are
 281    communications running in the background leaving the process free
 282    to do something else during their completion.
 283
 284    .. tabs::
 285
 286       .. example-tab:: examples/s4u/async-wait/s4u-async-wait.cpp
 287
 288          See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
 289
 290       .. example-tab:: examples/python/async-wait/async-wait.py
 291
 292          See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
 293
 294       .. example-tab:: examples/c/async-wait/async-wait.c
 295
 296          See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
 297
 298  - **Waiting for all communications in a set:**
 299    The ``wait_all()`` function is useful when you want to block until
 300    all activities in a given set have completed.
 301
 302    .. tabs::
 303
 304       .. example-tab:: examples/s4u/async-waitall/s4u-async-waitall.cpp
 305
 306          See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
 307
 308       .. example-tab:: examples/python/async-waitall/async-waitall.py
 309
 310          See also :py:func:`simgrid.Comm.wait_all()`.
 311
 312       .. example-tab:: examples/c/async-waitall/async-waitall.c
 313
 314          See also :cpp:func:`sg_comm_wait_all()`.
 315
 316  - **Waiting for the first completed communication in a set:**
 317    The ``wait_any()`` function is useful
 318    when you want to block until one activity of the set completes, no
 319    matter which terminates first.
 320
 321    .. tabs::
 322
 323       .. example-tab:: examples/s4u/async-waitany/s4u-async-waitany.cpp
 324
 325          See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
 326
 327       .. example-tab:: examples/python/async-waitany/async-waitany.py
 328
 329          See also :py:func:`simgrid.Comm.wait_any()`.
 330
 331       .. example-tab:: examples/c/async-waitany/async-waitany.c
 332
 333          See also :cpp:func:`sg_comm_wait_any`.
 334
 335 .. _s4u_ex_execution:
 336
 337 Executions on the CPU
 338 ---------------------
 339
 340   - **Basic execution:**
 341     The computations done in your program are not reported to the
 342     simulated world, unless you explicitly request the simulator to pause
 343     the actor until a given amount of flops gets computed on its simulated
 344     host. Some executions can be given an higher priority so that they
 345     get more resources.
 346
 347     .. tabs::
 348
 349        .. example-tab:: examples/s4u/exec-basic/s4u-exec-basic.cpp
 350
 351           See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
 352           and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
 353
 354        .. example-tab:: examples/python/exec-basic/exec-basic.py
 355
 356           See also :py:func:`simgrid.this_actor.execute()`.
 357
 358        .. example-tab:: examples/c/exec-basic/exec-basic.c
 359
 360           See also :cpp:func:`void sg_actor_execute(double)`
 361           and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
 362
 363   - **Asynchronous execution:**
 364     You can start asynchronous executions, just like you would fire
 365     background threads.
 366
 367     .. tabs::
 368
 369        .. example-tab:: examples/s4u/exec-async/s4u-exec-async.cpp
 370
 371           See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
 372           :cpp:func:`simgrid::s4u::Activity::start()`,
 373           :cpp:func:`simgrid::s4u::Activity::wait()`,
 374           :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
 375           :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
 376           :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
 377           :cpp:func:`simgrid::s4u::Activity::cancel()`.
 378
 379        .. example-tab:: examples/python/exec-async/exec-async.py
 380
 381           See also :py:func:`simgrid.this_actor::exec_init()`,
 382           :py:func:`simgrid.Activity::start()`,
 383           :py:func:`simgrid.Activity.wait()`,
 384           :py:func:`simgrid.Activity.get_remaining()`,
 385           :py:func:`simgrid.Exec.get_remaining_ratio()`,
 386           :py:func:`simgrid.this_actor.exec_async()` and
 387           :py:func:`simgrid.Activity.cancel()`.
 388
 389   - **Remote execution:**
 390     You can start executions on remote hosts, or even change the host
 391     on which they occur during their execution.
 392
 393     .. tabs::
 394
 395        .. example-tab:: examples/s4u/exec-remote/s4u-exec-remote.cpp
 396
 397           See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
 398
 399        .. example-tab:: examples/python/exec-remote/exec-remote.py
 400
 401           See also :py:func:`simgrid.Exec.set_host()`.
 402
 403        .. example-tab:: examples/c/exec-remote/exec-remote.c
 404
 405           See also :cpp:func:`sg_exec_set_host()`.
 406
 407   - **Parallel executions:**
 408     These objects are convenient abstractions of parallel
 409     computational kernels that span over several machines, such as a
 410     PDGEM and the other ScaLAPACK routines. Note that this only works
 411     with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
 412
 413     .. tabs::
 414
 415        .. example-tab:: examples/s4u/exec-ptask/s4u-exec-ptask.cpp
 416
 417           See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
 418
 419   - **Using Pstates on a host:**
 420     This example shows how define a set of pstates in the XML. The current pstate
 421     of an host can then be accessed and changed from the program.
 422
 423     .. tabs::
 424
 425        .. example-tab:: examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp
 426
 427           See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 428
 429        .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
 430
 431           See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
 432
 433        .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 434
 435           See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 436
 437        .. example-tab:: examples/platforms/energy_platform.xml
 438
 439 .. _s4u_ex_disk_io:
 440
 441 I/O on Disks and Files
 442 ----------------------
 443
 444 SimGrid provides two levels of abstraction to interact with the
 445 simulated disks. At the simplest level, you simply create read and
 446 write actions on the disk resources.
 447
 448   - **Access to raw disk devices:**
 449     This example illustrates how to simply read and write data on a
 450     simulated disk resource.
 451
 452     .. tabs::
 453
 454        .. example-tab:: examples/s4u/io-disk-raw/s4u-io-disk-raw.cpp
 455
 456        .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
 457
 458        .. example-tab:: examples/platforms/hosts_with_disks.xml
 459
 460           This shows how to declare disks in XML.
 461
 462 The FileSystem plugin provides a more detailed view, with the
 463 classical operations over files: open, move, unlink, and of course
 464 read and write. The file and disk sizes are also dealt with and can
 465 result in short reads and short write, as in reality.
 466
 467   - **File Management:**
 468     This example illustrates the use of operations on files
 469     (read, write, seek, tell, unlink, etc).
 470
 471     .. tabs::
 472
 473        .. example-tab:: examples/s4u/io-file-system/s4u-io-file-system.cpp
 474
 475   - **Remote I/O:**
 476     I/O operations on files can also be done in a remote fashion,
 477     i.e. when the accessed disk is not mounted on the caller's host.
 478
 479     .. tabs::
 480
 481        .. example-tab:: examples/s4u/io-file-remote/s4u-io-file-remote.cpp
 482
 483        .. example-tab:: examples/c/io-file-remote/io-file-remote.c
 484
 485 .. _s4u_ex_IPC:
 486
 487 Classical synchronization objects
 488 ---------------------------------
 489
 490  - **Barrier:**
 491    Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 492
 493    .. tabs::
 494
 495       .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
 496
 497  - **Condition variable:**
 498    Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 499
 500    .. tabs::
 501
 502       .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 503
 504  - **Mutex:**
 505    Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 506
 507    .. tabs::
 508
 509       .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
 510
 511  - **Semaphore:**
 512    Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 513
 514    .. tabs::
 515
 516       .. example-tab:: examples/s4u/synchro-semaphore/s4u-synchro-semaphore.cpp
 517
 518 =============================
 519 Interacting with the Platform
 520 =============================
 521
 522  - **User-defined properties:**
 523    You can attach arbitrary information to most platform elements from
 524    the XML file, and then interact with these values from your
 525    program. Note that the changes are not written permanently on disk,
 526    in the XML file nor anywhere else. They only last until the end of
 527    your simulation.
 528
 529    .. tabs::
 530
 531       .. example-tab:: examples/s4u/platform-properties/s4u-platform-properties.cpp
 532
 533          - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 534          - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 535          - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 536          - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 537
 538       .. group-tab:: XML
 539
 540          **Deployment file:**
 541
 542          .. showfile:: examples/s4u/platform-properties/s4u-platform-properties_d.xml
 543             :language: xml
 544
 545          |br|
 546          **Platform file:**
 547
 548          .. showfile:: examples/platforms/prop.xml
 549             :language: xml
 550
 551  - **Retrieving the netzones matching a given criteria:**
 552    Shows how to filter the cluster netzones.
 553
 554    .. tabs::
 555
 556       .. example-tab:: examples/s4u/routing-get-clusters/s4u-routing-get-clusters.cpp
 557
 558  - **Retrieving the list of hosts matching a given criteria:**
 559    Shows how to filter the actors that match a given criteria.
 560
 561    .. tabs::
 562
 563       .. example-tab:: examples/s4u/engine-filtering/s4u-engine-filtering.cpp
 564
 565  - **Specifying state profiles:** shows how to specify when the
 566    resources must be turned off and on again, and how to react to such
 567    failures in your code. See also :ref:`howto_churn`.
 568
 569    .. tabs::
 570
 571       .. example-tab:: examples/s4u/platform-failures/s4u-platform-failures.cpp
 572
 573       .. group-tab:: XML
 574
 575          .. showfile:: examples/platforms/small_platform_failures.xml
 576             :language: xml
 577
 578          .. showfile:: examples/platforms/profiles/jupiter_state.profile
 579
 580          .. showfile:: examples/platforms/profiles/bourassa_state.profile
 581
 582          .. showfile:: examples/platforms/profiles/fafard_state.profile
 583
 584  - **Specifying speed profiles:** shows how to specify an external
 585    load to resources, variating their peak speed over time.
 586
 587    .. tabs::
 588
 589       .. example-tab:: examples/s4u/platform-profile/s4u-platform-profile.cpp
 590
 591       .. group-tab:: XML
 592
 593          .. showfile:: examples/platforms/small_platform_profile.xml
 594             :language: xml
 595
 596          .. showfile:: examples/platforms/profiles/jupiter_speed.profile
 597
 598          .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
 599
 600          .. showfile:: examples/platforms/profiles/link1_latency.profile
 601
 602 =================
 603 Energy Simulation
 604 =================
 605
 606   - **Describing the energy profiles in the platform:**
 607     This platform file contains the energy profile of each links and
 608     hosts, which is necessary to get energy consumption predictions.
 609     As usual, you should not trust our example, and you should strive
 610     to double-check that your instantiation matches your target platform.
 611
 612     .. tabs::
 613
 614        .. example-tab:: examples/platforms/energy_platform.xml
 615
 616   - **Consumption due to the CPU:**
 617     This example shows how to retrieve the amount of energy consumed
 618     by the CPU during computations, and the impact of the pstate.
 619
 620     .. tabs::
 621
 622        .. example-tab:: examples/s4u/energy-exec/s4u-energy-exec.cpp
 623
 624        .. example-tab:: examples/c/energy-exec/energy-exec.c
 625
 626   - **Consumption due to the network:**
 627     This example shows how to retrieve and display the energy consumed
 628     by the network during communications.
 629
 630     .. tabs::
 631
 632        .. example-tab:: examples/s4u/energy-link/s4u-energy-link.cpp
 633
 634   - **Modeling the shutdown and boot of hosts:**
 635     Simple example of model of model for the energy consumption during
 636     the host boot and shutdown periods.
 637
 638     .. tabs::
 639
 640        .. example-tab:: examples/s4u/energy-boot/platform_boot.xml
 641
 642        .. example-tab:: examples/s4u/energy-boot/s4u-energy-boot.cpp
 643
 644 =======================
 645 Tracing and Visualizing
 646 =======================
 647
 648 Tracing can be activated by various configuration options which
 649 are illustrated in these example. See also the
 650 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 651
 652 It is interesting to run the process-create example with the following
 653 options to see the task executions:
 654
 655   - **Platform Tracing:**
 656     This program is a toy example just loading the platform, so that
 657     you can play with the platform visualization. Recommanded options:
 658     ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 659
 660     .. tabs::
 661
 662        .. example-tab:: examples/s4u/trace-platform/s4u-trace-platform.cpp
 663
 664 ========================
 665 Larger SimGrid Examplars
 666 ========================
 667
 668 This section contains application examples that are somewhat larger
 669 than the previous examples.
 670
 671   - **Ping Pong:**
 672     This simple example just sends one message back and forth.
 673     The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to
 674     the simulators (as detailed in Section :ref:`options`).
 675
 676     .. tabs::
 677
 678        .. example-tab:: examples/s4u/app-pingpong/s4u-app-pingpong.cpp
 679
 680        .. example-tab:: examples/c/app-pingpong/app-pingpong.c
 681
 682   - **Token ring:**
 683     Shows how to implement a classical communication pattern, where a
 684     token is exchanged along a ring to reach every participant.
 685
 686     .. tabs::
 687
 688        .. example-tab:: examples/s4u/app-token-ring/s4u-app-token-ring.cpp
 689
 690        .. example-tab:: examples/c/app-token-ring/app-token-ring.c
 691
 692   - **Master Workers:**
 693     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
 694     processes.
 695
 696     .. tabs::
 697
 698        .. group-tab:: C++
 699
 700           This example comes in two equivalent variants, one where the actors
 701           are specified as simple functions (which is easier to understand for
 702           newcomers) and one where the actors are specified as classes (which is
 703           more powerful for the users wanting to build their own projects upon
 704           the example).
 705
 706           .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp
 707              :language: cpp
 708
 709           .. showfile:: examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
 710              :language: cpp
 711
 712 Data diffusion
 713 --------------
 714
 715   - **Bit Torrent:**
 716     Classical protocol for Peer-to-Peer data diffusion.
 717
 718     .. tabs::
 719
 720        .. group-tab:: C++
 721
 722           .. showfile:: examples/s4u/app-bittorrent/s4u-bittorrent.cpp
 723              :language: cpp
 724
 725           .. showfile:: examples/s4u/app-bittorrent/s4u-peer.cpp
 726              :language: cpp
 727
 728           .. showfile:: examples/s4u/app-bittorrent/s4u-tracker.cpp
 729              :language: cpp
 730
 731   - **Chained Send:**
 732     Data broadcast over a ring of processes.
 733
 734     .. tabs::
 735
 736        .. example-tab:: examples/s4u/app-chainsend/s4u-app-chainsend.cpp
 737
 738        .. group-tab:: C
 739
 740           .. showfile:: examples/c/app-chainsend/chainsend.c
 741              :language: c
 742
 743           .. showfile:: examples/c/app-chainsend/broadcaster.c
 744              :language: c
 745
 746           .. showfile:: examples/c/app-chainsend/peer.c
 747              :language: c
 748
 749 Distributed Hash Tables (DHT)
 750 -----------------------------
 751
 752   - **Chord Protocol**
 753     One of the most famous DHT protocol.
 754
 755     .. tabs::
 756
 757        .. group-tab:: C++
 758
 759           .. showfile:: examples/s4u/dht-chord/s4u-dht-chord.cpp
 760              :language: cpp
 761
 762           .. showfile:: examples/s4u/dht-chord/s4u-dht-chord-node.cpp
 763              :language: cpp
 764
 765   - **Kademlia**
 766     Another well-known DHT protocol.
 767
 768     .. tabs::
 769
 770        .. group-tab:: C++
 771
 772           .. showfile:: examples/s4u/dht-kademlia/s4u-dht-kademlia.cpp
 773              :language: cpp
 774
 775           .. showfile:: examples/s4u/dht-kademlia/routing_table.cpp
 776              :language: cpp
 777
 778           .. showfile:: examples/s4u/dht-kademlia/answer.cpp
 779              :language: cpp
 780
 781           .. showfile:: examples/s4u/dht-kademlia/node.cpp
 782              :language: cpp
 783
 784 .. _s4u_ex_clouds:
 785
 786 Simulating Clouds
 787 -----------------
 788
 789   - **Cloud basics**
 790     This example starts some computations both on PMs and VMs, and
 791     migrates some VMs around.
 792
 793     .. tabs::
 794
 795        .. example-tab:: examples/s4u/cloud-simple/s4u-cloud-simple.cpp
 796
 797        .. example-tab:: examples/c/cloud-simple/cloud-simple.c
 798
 799   - **Migrating VMs**
 800     This example shows how to migrate VMs between PMs.
 801
 802     .. tabs::
 803
 804        .. example-tab:: examples/s4u/cloud-migration/s4u-cloud-migration.cpp
 805
 806        .. example-tab:: examples/c/cloud-migration/cloud-migration.c
 807
 808 =======================
 809 Model-Checking Examples
 810 =======================
 811
 812 The model-checker can be used to exhaustively search for issues in the
 813 tested application. It must be activated at compile time, but this
 814 mode is rather experimental in SimGrid (as of v3.22). You should not
 815 enable it unless you really want to formally verify your applications:
 816 SimGrid is slower and maybe less robust when MC is enabled.
 817
 818   - **Failing assert**
 819     In this example, two actors send some data to a central server,
 820     which asserts that the messages are always received in the same order.
 821     This is obviously wrong, and the model-checker correctly finds a
 822     counter-example to that assertion.
 823
 824     .. tabs::
 825
 826        .. example-tab:: examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp
 827
 828 .. |br| raw:: html
 829
 830    <br />
 831
 832 .. |cpp| image:: /img/lang_cpp.png
 833    :align: middle
 834    :width: 12
 835
 836 .. |py| image:: /img/lang_python.png
 837    :align: middle
 838    :width: 12