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