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 .. _s4u_examples:
   7
   8 Examples
   9 ********
  10
  11 SimGrid comes with an extensive set of examples, documented on this
  12 page. Most of them only demonstrate one single feature, with some
  13 larger examplars listed below.
  14
  15 The C++ examples can be found under examples/cpp while python examples
  16 are in examples/python. Each such directory contains the source code (also listed
  17 from this page), and the so-called tesh file containing how to call
  18 the binary obtained by compiling this example and also the expected
  19 output. Tesh files are used to turn each of our examples into an
  20 integration test. Some examples also contain other files, on need.
  21
  22 A good way to bootstrap your own project is to copy and combine some
  23 of the provided examples to constitute the skeleton of what you plan
  24 to simulate.
  25
  26 .. _s4u_ex_actors:
  27
  28 ===========================
  29 Actors: the Active Entities
  30 ===========================
  31
  32 Starting and Stopping Actors
  33 ----------------------------
  34
  35   - **Creating actors:**
  36     Most actors are started from the deployment XML file, because this
  37     is a :ref:`better scientific habit <howto_science>`, but you can
  38     also create them directly from your code.
  39
  40     .. tabs::
  41
  42        .. example-tab:: examples/cpp/actor-create/s4u-actor-create.cpp
  43
  44           You create actors either:
  45
  46           - Directly with :cpp:func:`simgrid::s4u::Actor::create`
  47           - From XML with :cpp:func:`simgrid::s4u::Engine::register_actor` (if your actor is a class)
  48             or :cpp:func:`simgrid::s4u::Engine::register_function` (if your actor is a function)
  49             and then :cpp:func:`simgrid::s4u::Engine::load_deployment`
  50
  51        .. example-tab:: examples/python/actor-create/actor-create.py
  52
  53           You create actors either:
  54
  55           - Directly with :py:func:`simgrid.Actor.create()`
  56           - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
  57
  58        .. example-tab:: examples/c/actor-create/actor-create.c
  59
  60           You create actors either:
  61
  62           - Directly with :cpp:func:`sg_actor_create()` followed by :cpp:func:`sg_actor_start`.
  63           - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
  64
  65        .. example-tab:: examples/python/actor-create/actor-create_d.xml
  66
  67           The following file is used in both C++ and Python.
  68
  69   - **React to the end of actors:** You can attach callbacks to the end of
  70     actors. There is several ways of doing so, depending on whether you want to
  71     attach your callback to a given actor and on how you define the end of a
  72     given actor. User code probably want to react to the termination of an actor
  73     while some plugins want to react to the destruction (memory collection) of
  74     actors.
  75
  76     .. tabs::
  77
  78        .. example-tab:: examples/cpp/actor-exiting/s4u-actor-exiting.cpp
  79
  80           This example shows how to attach a callback to:
  81
  82           - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()`
  83           - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
  84           - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
  85
  86        .. example-tab:: examples/c/actor-exiting/actor-exiting.c
  87
  88           This example shows how to attach a callback to the end of a specific actor with
  89           :cpp:func:`sg_actor_on_exit()`.
  90
  91   - **Kill actors:**
  92     Actors can forcefully stop other actors.
  93
  94     .. tabs::
  95
  96        .. example-tab:: examples/cpp/actor-kill/s4u-actor-kill.cpp
  97
  98           See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
  99           :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`.
 100
 101        .. example-tab:: examples/python/actor-kill/actor-kill.py
 102
 103           See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
 104           :py:func:`simgrid.this_actor.on_exit`.
 105
 106        .. example-tab:: examples/c/actor-kill/actor-kill.c
 107
 108           See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
 109
 110   - **Controlling the actor life cycle from the XML:**
 111     You can specify a start time and a kill time in the deployment file.
 112
 113     .. tabs::
 114
 115        .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime.cpp
 116
 117           This file is not really interesting: the important matter is in the XML file.
 118
 119        .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime_d.xml
 120
 121           This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
 122
 123        .. example-tab:: examples/python/actor-lifetime/actor-lifetime.py
 124
 125           This file is not really interesting: the important matter is in the XML file.
 126
 127       .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
 128
 129           This file is not really interesting: the important matter is in the XML file.
 130
 131   - **Daemonize actors:**
 132     Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
 133     actor into a daemon that will be automatically killed once the simulation is over.
 134
 135     .. tabs::
 136
 137        .. example-tab:: examples/cpp/actor-daemon/s4u-actor-daemon.cpp
 138
 139           See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
 140
 141        .. example-tab:: examples/python/actor-daemon/actor-daemon.py
 142
 143           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 144
 145        .. example-tab:: examples/c/actor-daemon/actor-daemon.c
 146
 147           See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
 148
 149   - **Specify the stack size to use**
 150     The stack size can be specified by default on the command line,
 151     globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config`,
 152     or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
 153
 154     .. tabs::
 155
 156        .. example-tab:: examples/cpp/actor-stacksize/s4u-actor-stacksize.cpp
 157
 158        .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
 159
 160 Inter-Actors Interactions
 161 -------------------------
 162
 163 See also the examples on :ref:`inter-actors communications
 164 <s4u_ex_communication>` and the ones on :ref:`classical
 165 synchronization objects <s4u_ex_IPC>`.
 166
 167   - **Suspend and Resume actors:**
 168     Actors can be suspended and resumed during their executions.
 169
 170     .. tabs::
 171
 172        .. example-tab:: examples/cpp/actor-suspend/s4u-actor-suspend.cpp
 173
 174           See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
 175           :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
 176           :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 177
 178        .. example-tab:: examples/python/actor-suspend/actor-suspend.py
 179
 180           See also :py:func:`simgrid.this_actor.suspend()`,
 181           :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
 182           :py:func:`simgrid.Actor.is_suspended()`.
 183
 184        .. example-tab:: examples/c/actor-suspend/actor-suspend.c
 185
 186           See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
 187           :cpp:func:`sg_actor_is_suspended()`.
 188
 189   - **Migrating Actors:**
 190     Actors can move or be moved from a host to another very easily. It amount to setting them on a new host.
 191
 192     .. tabs::
 193
 194        .. example-tab:: examples/cpp/actor-migrate/s4u-actor-migrate.cpp
 195
 196           See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
 197
 198        .. example-tab:: examples/python/actor-migrate/actor-migrate.py
 199
 200           See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
 201
 202        .. example-tab:: examples/c/actor-migrate/actor-migrate.c
 203
 204           See also :cpp:func:`sg_actor_set_host()`.
 205
 206   - **Waiting for the termination of an actor:** (joining on it)
 207     You can block the current actor until the end of another actor.
 208
 209     .. tabs::
 210
 211        .. example-tab:: examples/cpp/actor-join/s4u-actor-join.cpp
 212
 213           See also :cpp:func:`simgrid::s4u::Actor::join()`.
 214
 215        .. example-tab:: examples/python/actor-join/actor-join.py
 216
 217           See also :py:func:`simgrid.Actor.join()`.
 218
 219        .. example-tab:: examples/c/actor-join/actor-join.c
 220
 221           See also :cpp:func:`sg_actor_join`.
 222
 223   - **Yielding to other actors**.
 224     The ```yield()``` function interrupts the execution of the current
 225     actor, leaving a chance to the other actors that are ready to run
 226     at this timestamp.
 227
 228     .. tabs::
 229
 230        .. example-tab:: examples/cpp/actor-yield/s4u-actor-yield.cpp
 231
 232           See also :cpp:func:`simgrid::s4u::this_actor::yield()`.
 233
 234        .. example-tab:: examples/python/actor-yield/actor-yield.py
 235
 236           See also :py:func:`simgrid.this_actor.yield_()`.
 237
 238        .. example-tab:: examples/c/actor-yield/actor-yield.c
 239
 240           See also :cpp:func:`sg_actor_yield()`.
 241
 242 Traces Replay as a Workload
 243 ---------------------------
 244
 245 This section details how to run trace-driven simulations. It is very
 246 handy when you want to test an algorithm or protocol that only react
 247 to external events. For example, many P2P protocols react to user
 248 requests, but do nothing if there is no such event.
 249
 250 In such situations, you should write your protocol in C++, and separate
 251 the workload that you want to play onto your protocol in a separate
 252 text file. Declare a function handling each type of the events in your
 253 trace, register them using :cpp:func:`xbt_replay_action_register()` in
 254 your main, and then run the simulation.
 255
 256 Then, you can either have one trace file containing all your events,
 257 or a file per simulated process: the former may be easier to work
 258 with, but the second is more efficient on very large traces. Check
 259 also the tesh files in the example directories for details.
 260
 261   - **Communication replay:**
 262     Presents a set of event handlers reproducing classical communication
 263     primitives (asynchronous send/receive at the moment).
 264
 265     .. tabs::
 266
 267        .. example-tab:: examples/cpp/replay-comm/s4u-replay-comm.cpp
 268
 269   - **I/O replay:**
 270     Presents a set of event handlers reproducing classical I/O
 271     primitives (open, read, close).
 272
 273     .. tabs::
 274
 275        .. example-tab:: examples/cpp/replay-io/s4u-replay-io.cpp
 276
 277 ==========================
 278 Activities: what Actors do
 279 ==========================
 280
 281 .. _s4u_ex_communication:
 282
 283 Communications on the Network
 284 -----------------------------
 285
 286   - **Basic communications:**
 287     This simple example just sends one message back and forth.
 288     The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to
 289     the simulators (as detailed in Section :ref:`options`).
 290
 291     .. tabs::
 292
 293        .. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp
 294
 295        .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
 296
 297
 298  - **Basic asynchronous communications:**
 299    Illustrates how to have non-blocking communications, that are
 300    communications running in the background leaving the process free
 301    to do something else during their completion.
 302
 303    .. tabs::
 304
 305       .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
 306
 307          See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
 308
 309       .. example-tab:: examples/python/comm-wait/comm-wait.py
 310
 311          See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
 312
 313       .. example-tab:: examples/c/comm-wait/comm-wait.c
 314
 315          See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm__wait()`.
 316
 317  - **Waiting communications with timeouts:**
 318    This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
 319
 320    .. tabs::
 321
 322       .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
 323
 324          See also :cpp:func:`simgrid::s4u::Mailbox::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
 325
 326  - **Suspending communications:**
 327    The ``suspend()`` and ``resume()`` functions allow to block the
 328    progression of a given communication for a while and then unblock it.
 329    ``is_suspended()`` can be used to retrieve whether the activity is
 330    currently blocked or not.
 331
 332    .. tabs::
 333
 334       .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
 335
 336          See also :cpp:func:`simgrid::s4u::Activity::suspend()`
 337          :cpp:func:`simgrid::s4u::Activity::resume()` and
 338          :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
 339
 340
 341  - **Waiting for all communications in a set:**
 342    The ``wait_all()`` function is useful when you want to block until
 343    all activities in a given set have completed.
 344
 345    .. tabs::
 346
 347       .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
 348
 349          See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
 350
 351       .. example-tab:: examples/python/comm-waitall/comm-waitall.py
 352
 353          See also :py:func:`simgrid.Comm.wait_all()`.
 354
 355       .. example-tab:: examples/c/comm-waitall/comm-waitall.c
 356
 357          See also :cpp:func:`sg_comm_wait_all()`.
 358
 359  - **Waiting for the first completed communication in a set:**
 360    The ``wait_any()`` function is useful
 361    when you want to block until one activity of the set completes, no
 362    matter which terminates first.
 363
 364    .. tabs::
 365
 366       .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
 367
 368          See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
 369
 370       .. example-tab:: examples/python/comm-waitany/comm-waitany.py
 371
 372          See also :py:func:`simgrid.Comm.wait_any()`.
 373
 374       .. example-tab:: examples/c/comm-waitany/comm-waitany.c
 375
 376          See also :cpp:func:`sg_comm_wait_any`.
 377
 378 .. _s4u_ex_execution:
 379
 380 Executions on the CPU
 381 ---------------------
 382
 383   - **Basic execution:**
 384     The computations done in your program are not reported to the
 385     simulated world, unless you explicitly request the simulator to pause
 386     the actor until a given amount of flops gets computed on its simulated
 387     host. Some executions can be given an higher priority so that they
 388     get more resources.
 389
 390     .. tabs::
 391
 392        .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
 393
 394           See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
 395           and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
 396
 397        .. example-tab:: examples/python/exec-basic/exec-basic.py
 398
 399           See also :py:func:`simgrid.this_actor.execute()`.
 400
 401        .. example-tab:: examples/c/exec-basic/exec-basic.c
 402
 403           See also :cpp:func:`void sg_actor_execute(double)`
 404           and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
 405
 406   - **Asynchronous execution:**
 407     You can start asynchronous executions, just like you would fire
 408     background threads.
 409
 410     .. tabs::
 411
 412        .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
 413
 414           See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
 415           :cpp:func:`simgrid::s4u::Activity::start()`,
 416           :cpp:func:`simgrid::s4u::Activity::wait()`,
 417           :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
 418           :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
 419           :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
 420           :cpp:func:`simgrid::s4u::Activity::cancel()`.
 421
 422        .. example-tab:: examples/python/exec-async/exec-async.py
 423
 424           See also :py:func:`simgrid.this_actor::exec_init()`,
 425           :py:func:`simgrid.Activity::start()`,
 426           :py:func:`simgrid.Activity.wait()`,
 427           :py:func:`simgrid.Activity.get_remaining()`,
 428           :py:func:`simgrid.Exec.get_remaining_ratio()`,
 429           :py:func:`simgrid.this_actor.exec_async()` and
 430           :py:func:`simgrid.Activity.cancel()`.
 431
 432        .. example-tab:: examples/c/exec-async/exec-async.c
 433
 434           See also :cpp:func:`sg_actor_exec_init()`,
 435           :cpp:func:`sg_exec_start()`,
 436           :cpp:func:`sg_exec_wait()`,
 437           :cpp:func:`sg_exec_get_remaining()`,
 438           :cpp:func:`sg_exec_get_remaining_ratio()`,
 439           :cpp:func:`sg_actor_exec_async()` and
 440           :cpp:func:`sg_exec_cancel()`,
 441
 442   - **Remote execution:**
 443     You can start executions on remote hosts, or even change the host
 444     on which they occur during their execution.
 445
 446     .. tabs::
 447
 448        .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
 449
 450           See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
 451
 452        .. example-tab:: examples/python/exec-remote/exec-remote.py
 453
 454           See also :py:func:`simgrid.Exec.set_host()`.
 455
 456        .. example-tab:: examples/c/exec-remote/exec-remote.c
 457
 458           See also :cpp:func:`sg_exec_set_host()`.
 459
 460   - **Parallel executions:**
 461     These objects are convenient abstractions of parallel
 462     computational kernels that span over several machines, such as a
 463     PDGEM and the other ScaLAPACK routines. Note that this only works
 464     with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
 465
 466     This example demonstrates several kind of parallel tasks: regular
 467     ones, communication-only (without computation), computation-only
 468     (without communication), synchronization-only (neither
 469     communication nor computation). It also shows how to reconfigure a
 470     task after its start, to change the amount of hosts it runs onto.
 471     This allows to simulate malleable tasks.
 472
 473     .. tabs::
 474
 475        .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
 476
 477           See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
 478
 479   - **Using Pstates on a host:**
 480     This example shows how define a set of pstates in the XML. The current pstate
 481     of a host can then be accessed and changed from the program.
 482
 483     .. tabs::
 484
 485        .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
 486
 487           See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 488
 489        .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
 490
 491           See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
 492
 493        .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 494
 495           See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 496
 497        .. example-tab:: examples/platforms/energy_platform.xml
 498
 499 .. _s4u_ex_disk_io:
 500
 501 I/O on Disks and Files
 502 ----------------------
 503
 504 SimGrid provides two levels of abstraction to interact with the
 505 simulated disks. At the simplest level, you simply create read and
 506 write actions on the disk resources.
 507
 508   - **Access to raw disk devices:**
 509     This example illustrates how to simply read and write data on a
 510     simulated disk resource.
 511
 512     .. tabs::
 513
 514        .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
 515
 516        .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
 517
 518        .. example-tab:: examples/platforms/hosts_with_disks.xml
 519
 520           This shows how to declare disks in XML.
 521
 522 The FileSystem plugin provides a more detailed view, with the
 523 classical operations over files: open, move, unlink, and of course
 524 read and write. The file and disk sizes are also dealt with and can
 525 result in short reads and short write, as in reality.
 526
 527   - **File Management:**
 528     This example illustrates the use of operations on files
 529     (read, write, seek, tell, unlink, etc).
 530
 531     .. tabs::
 532
 533        .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
 534
 535   - **Remote I/O:**
 536     I/O operations on files can also be done in a remote fashion,
 537     i.e. when the accessed disk is not mounted on the caller's host.
 538
 539     .. tabs::
 540
 541        .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
 542
 543        .. example-tab:: examples/c/io-file-remote/io-file-remote.c
 544
 545 .. _s4u_ex_IPC:
 546
 547 Classical synchronization objects
 548 ---------------------------------
 549
 550  - **Barrier:**
 551    Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 552
 553    .. tabs::
 554
 555       .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
 556
 557  - **Condition variable: basic usage**
 558    Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 559
 560    .. tabs::
 561
 562       .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 563
 564  - **Condition variable: timeouts**
 565    Shows how to specify timeouts when blocking on condition variables.
 566
 567    .. tabs::
 568
 569       .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
 570
 571  - **Mutex:**
 572    Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 573
 574    .. tabs::
 575
 576       .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
 577
 578  - **Semaphore:**
 579    Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 580
 581    .. tabs::
 582
 583       .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
 584
 585       .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
 586
 587 =============================
 588 Interacting with the Platform
 589 =============================
 590
 591  - **User-defined properties:**
 592    You can attach arbitrary information to most platform elements from
 593    the XML file, and then interact with these values from your
 594    program. Note that the changes are not written permanently on disk,
 595    in the XML file nor anywhere else. They only last until the end of
 596    your simulation.
 597
 598    .. tabs::
 599
 600       .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
 601
 602          - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 603          - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 604          - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 605          - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 606
 607       .. example-tab:: examples/c/platform-properties/platform-properties.c
 608
 609          - :cpp:func:`sg_actor_get_property()` and :cpp:func:`sg_actor_set_property()`
 610          - :cpp:func:`sg_host_get_property()` and :cpp:func:sg_host_set_property()`
 611          - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
 612          - :cpp:func:`sg_link_get_property()` and :cpp:func:`sg_link_set_property()`
 613
 614       .. group-tab:: XML
 615
 616          **Deployment file:**
 617
 618          .. showfile:: examples/cpp/platform-properties/s4u-platform-properties_d.xml
 619             :language: xml
 620
 621          |br|
 622          **Platform file:**
 623
 624          .. showfile:: examples/platforms/prop.xml
 625             :language: xml
 626
 627  - **Retrieving the netzones matching a given criteria:**
 628    Shows how to filter the cluster netzones.
 629
 630    .. tabs::
 631
 632       .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
 633
 634  - **Retrieving the list of hosts matching a given criteria:**
 635    Shows how to filter the actors that match a given criteria.
 636
 637    .. tabs::
 638
 639       .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
 640
 641  - **Specifying state profiles:** shows how to specify when the
 642    resources must be turned off and on again, and how to react to such
 643    failures in your code. See also :ref:`howto_churn`.
 644
 645    .. tabs::
 646
 647       .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
 648
 649       .. example-tab:: examples/c/platform-failures/platform-failures.c
 650
 651       .. group-tab:: XML
 652
 653          .. showfile:: examples/platforms/small_platform_failures.xml
 654             :language: xml
 655
 656          .. showfile:: examples/platforms/profiles/jupiter_state.profile
 657
 658          .. showfile:: examples/platforms/profiles/bourassa_state.profile
 659
 660          .. showfile:: examples/platforms/profiles/fafard_state.profile
 661
 662  - **Specifying speed profiles:** shows how to specify an external
 663    load to resources, variating their peak speed over time.
 664
 665    .. tabs::
 666
 667       .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
 668
 669       .. group-tab:: XML
 670
 671          .. showfile:: examples/platforms/small_platform_profile.xml
 672             :language: xml
 673
 674          .. showfile:: examples/platforms/profiles/jupiter_speed.profile
 675
 676          .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
 677
 678          .. showfile:: examples/platforms/profiles/link1_latency.profile
 679
 680 =================
 681 Energy Simulation
 682 =================
 683
 684   - **Describing the energy profiles in the platform:**
 685     The first platform file contains the energy profile of each links and
 686     hosts for a wired network, which is necessary to get energy consumption
 687     predictions. The second platform file is the equivalent for a wireless
 688     network. As usual, you should not trust our example, and you should
 689     strive to double-check that your instantiation matches your target
 690     platform.
 691
 692     .. tabs::
 693
 694        .. group-tab:: XML
 695
 696           .. showfile:: examples/platforms/energy_platform.xml
 697              :language: xml
 698
 699           .. showfile:: examples/platforms/wifi_energy.xml
 700              :language: xml
 701
 702   - **Consumption due to the CPU:**
 703     This example shows how to retrieve the amount of energy consumed
 704     by the CPU during computations, and the impact of the pstate.
 705
 706     .. tabs::
 707
 708        .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
 709
 710        .. example-tab:: examples/c/energy-exec/energy-exec.c
 711
 712   - **Consumption due to the wired network:**
 713     This example shows how to retrieve and display the energy consumed
 714     by the wired network during communications.
 715
 716     .. tabs::
 717
 718        .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
 719
 720   - **Consumption due to the wireless network:**
 721     This example shows how to retrieve and display the energy consumed
 722     by the wireless network during communications.
 723
 724     .. tabs::
 725
 726        .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
 727
 728   - **Modeling the shutdown and boot of hosts:**
 729     Simple example of model of model for the energy consumption during
 730     the host boot and shutdown periods.
 731
 732     .. tabs::
 733
 734        .. example-tab:: examples/cpp/energy-boot/platform_boot.xml
 735
 736        .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
 737
 738 =======================
 739 Tracing and Visualizing
 740 =======================
 741
 742 Tracing can be activated by various configuration options which
 743 are illustrated in these example. See also the
 744 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 745
 746 It is interesting to run the process-create example with the following
 747 options to see the task executions:
 748
 749   - **Platform Tracing:**
 750     This program is a toy example just loading the platform, so that
 751     you can play with the platform visualization. Recommended options:
 752     ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 753
 754     .. tabs::
 755
 756        .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
 757
 758   - **Setting Categories**
 759     This example declares several tracing categories to that are used to
 760     classify its tasks. When the program is executed, the tracing mechanism
 761     registers the resource utilization of hosts and links according to these
 762     categories. Recommended options:
 763     ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 764
 765     .. tabs::
 766
 767        .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
 768
 769   - **Master Workers tracing**
 770     This is an augmented version of our basic master/worker example using
 771     several tracing features. It traces resource usage, sorted out in several
 772     categories; Trace marks and user variables are also used. Recommended
 773     options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 774
 775     .. tabs::
 776
 777        .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
 778
 779   - **Process migration tracing**
 780     This version is enhanced so that the process migrations can be displayed
 781     as arrows in a Gantt-chart visualization. Recommended options to that
 782     extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
 783
 784     .. tabs::
 785
 786        .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
 787
 788 ..
 789     TODO: These tracing examples should be integrated in the examples to not
 790     duplicate the C++ files. A full command line to see the result in the right
 791     tool (vite/FrameSoc) should be given along with some screenshots.
 792
 793 Tracing user variables
 794 ----------------------
 795
 796 You can also attach your own variables to any resource described in the platform
 797 file. The following examples illustrate this feature.  They have to be run with
 798 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
 799
 800   - **Attaching variables to Hosts**
 801
 802     .. tabs::
 803
 804        .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
 805
 806   - **Attaching variables to Links**
 807     The tricky part is that you have to know the name of the link you want to
 808     enhance with a variable.
 809
 810     .. tabs::
 811
 812        .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
 813
 814   - **Attaching variables to network Routes**
 815     It is often easier to update a given variable for all links of a given
 816     network path (identified by its source and destination hosts) instead of
 817     knowing the name of each specific link.
 818
 819     .. tabs::
 820
 821        .. example-tab::  examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
 822
 823 ========================
 824 Larger SimGrid Examplars
 825 ========================
 826
 827 This section contains application examples that are somewhat larger
 828 than the previous examples.
 829
 830   - **Token ring:**
 831     Shows how to implement a classical communication pattern, where a
 832     token is exchanged along a ring to reach every participant.
 833
 834     .. tabs::
 835
 836        .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
 837
 838        .. example-tab:: examples/c/app-token-ring/app-token-ring.c
 839
 840   - **Master Workers:**
 841     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
 842     processes.
 843
 844     .. tabs::
 845
 846        .. group-tab:: C++
 847
 848           This example comes in two equivalent variants, one where the actors
 849           are specified as simple functions (which is easier to understand for
 850           newcomers) and one where the actors are specified as classes (which is
 851           more powerful for the users wanting to build their own projects upon
 852           the example).
 853
 854           .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
 855              :language: cpp
 856
 857           .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
 858              :language: cpp
 859
 860        .. group-tab:: C
 861
 862           .. showfile:: examples/c/app-masterworker/app-masterworker.c
 863              :language: cpp
 864
 865 Data diffusion
 866 --------------
 867
 868   - **Bit Torrent:**
 869     Classical protocol for Peer-to-Peer data diffusion.
 870
 871     .. tabs::
 872
 873        .. group-tab:: C++
 874
 875           .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
 876              :language: cpp
 877
 878           .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
 879              :language: cpp
 880
 881           .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
 882              :language: cpp
 883
 884        .. group-tab:: C
 885
 886           .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
 887              :language: cpp
 888
 889           .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
 890              :language: cpp
 891
 892           .. showfile:: examples/c/app-bittorrent/tracker.c
 893              :language: cpp
 894
 895   - **Chained Send:**
 896     Data broadcast over a ring of processes.
 897
 898     .. tabs::
 899
 900        .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
 901
 902        .. group-tab:: C
 903
 904           .. showfile:: examples/c/app-chainsend/chainsend.c
 905              :language: c
 906
 907           .. showfile:: examples/c/app-chainsend/broadcaster.c
 908              :language: c
 909
 910           .. showfile:: examples/c/app-chainsend/peer.c
 911              :language: c
 912
 913 Distributed Hash Tables (DHT)
 914 -----------------------------
 915
 916   - **Chord Protocol**
 917     One of the most famous DHT protocol.
 918
 919     .. tabs::
 920
 921        .. group-tab:: C++
 922
 923           .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
 924              :language: cpp
 925
 926           .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
 927              :language: cpp
 928
 929   - **Kademlia**
 930     Another well-known DHT protocol.
 931
 932     .. tabs::
 933
 934        .. group-tab:: C++
 935
 936           .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
 937              :language: cpp
 938
 939           .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
 940              :language: cpp
 941
 942           .. showfile:: examples/cpp/dht-kademlia/answer.cpp
 943              :language: cpp
 944
 945           .. showfile:: examples/cpp/dht-kademlia/node.cpp
 946              :language: cpp
 947
 948        .. group-tab:: C
 949
 950           .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
 951              :language: cpp
 952
 953           .. showfile:: examples/c/dht-kademlia/routing_table.c
 954              :language: cpp
 955
 956           .. showfile:: examples/c/dht-kademlia/answer.c
 957              :language: cpp
 958
 959           .. showfile:: examples/c/dht-kademlia/message.c
 960              :language: cpp
 961
 962           .. showfile:: examples/c/dht-kademlia/node.c
 963              :language: cpp
 964
 965 .. _s4u_ex_clouds:
 966
 967 Simulating Clouds
 968 -----------------
 969
 970   - **Cloud basics**
 971     This example starts some computations both on PMs and VMs, and
 972     migrates some VMs around.
 973
 974     .. tabs::
 975
 976        .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
 977
 978        .. example-tab:: examples/c/cloud-simple/cloud-simple.c
 979
 980   - **Migrating VMs**
 981     This example shows how to migrate VMs between PMs.
 982
 983     .. tabs::
 984
 985        .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
 986
 987        .. example-tab:: examples/c/cloud-migration/cloud-migration.c
 988
 989 =======================
 990 Model-Related Examples
 991 =======================
 992
 993   - **ns-3 as a SimGrid Network Model**
 994     This simple ping-pong example demonstrates how to use the bindings to the Network
 995     Simulator. The most interesting is probably not the C++ files since
 996     they are unchanged from the other simulations, but the associated files,
 997     such as the platform file to see how to declare a platform to be used
 998     with the ns-3 bindings of SimGrid and the tesh file to see how to actually
 999     start a simulation in these settings.
1000
1001     .. tabs::
1002
1003       .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1004
1005       .. group-tab:: XML
1006
1007          **Platform files:**
1008
1009          .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1010             :language: xml
1011
1012   - **wifi links**
1013
1014     This demonstrates how to declare a wifi link in your platform and
1015     how to use it in your simulation. The basics is to have a link
1016     which sharing policy is set to `WIFI`. Such links can have more
1017     than one bandwidth value (separated by commas), corresponding to
1018     the several SNR level of your wifi link.
1019
1020     In this case, SimGrid automatically switches to validated
1021     performance models of wifi networks, where the time is shared
1022     between users instead of the bandwidth for wired links (the
1023     corresponding publication is currently being written).
1024
1025     If your wifi link provides more than one SNR level, you can switch
1026     the level of a given host using
1027     :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1028     the first level is used.
1029
1030     .. tabs::
1031
1032       .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1033
1034       .. group-tab:: XML
1035
1036          **Platform files:**
1037
1038          .. showfile:: examples/platforms/wifi.xml
1039             :language: xml
1040
1041 ===============
1042 Plugin Examples
1043 ===============
1044
1045 It is possible to extend SimGrid without modifying its internals by
1046 attaching code to the existing signals and by adding extra data to the
1047 simulation objects through extensions. How to do that is not exactly
1048 documented yet, and you should look for examples in the src/plugins
1049 directory.
1050
1051 This section documents how the existing plugins can be used. Remember
1052 that you are very welcome to modify the plugins to fit your needs. It
1053 should be much easier than modifying the SimGrid kernel.
1054
1055   - **Monitoring the host load**
1056
1057     .. tabs::
1058
1059       .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1060
1061       .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1062
1063   - **Monitoring the link load**
1064
1065     .. tabs::
1066
1067       .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1068
1069 =======================
1070 Model-Checking Examples
1071 =======================
1072
1073 The model-checker can be used to exhaustively search for issues in the
1074 tested application. It must be activated at compile time, but this
1075 mode is rather experimental in SimGrid (as of v3.22). You should not
1076 enable it unless you really want to formally verify your applications:
1077 SimGrid is slower and maybe less robust when MC is enabled.
1078
1079   - **Failing assert**
1080     In this example, two actors send some data to a central server,
1081     which asserts that the messages are always received in the same order.
1082     This is obviously wrong, and the model-checker correctly finds a
1083     counter-example to that assertion.
1084
1085     .. tabs::
1086
1087        .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp
1088
1089 .. |br| raw:: html
1090
1091    <br />
1092
1093 .. |cpp| image:: /img/lang_cpp.png
1094    :align: middle
1095    :width: 12
1096
1097 .. |py| image:: /img/lang_python.png
1098    :align: middle
1099    :width: 12