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 exemplars 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 are 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 wants 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 the background.
 133     This example shows how to transform a regular
 134     actor into a daemon that will be automatically killed once the simulation is over.
 135
 136     .. tabs::
 137
 138        .. example-tab:: examples/cpp/actor-daemon/s4u-actor-daemon.cpp
 139
 140           See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
 141
 142        .. example-tab:: examples/python/actor-daemon/actor-daemon.py
 143
 144           See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
 145
 146        .. example-tab:: examples/c/actor-daemon/actor-daemon.c
 147
 148           See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
 149
 150   - **Specify the stack size to use**
 151     The stack size can be specified by default on the command line,
 152     globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config`,
 153     or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
 154
 155     .. tabs::
 156
 157        .. example-tab:: examples/cpp/actor-stacksize/s4u-actor-stacksize.cpp
 158
 159        .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
 160
 161 Inter-Actors Interactions
 162 -------------------------
 163
 164 See also the examples on :ref:`inter-actors communications
 165 <s4u_ex_communication>` and the ones on :ref:`classical
 166 synchronization objects <s4u_ex_IPC>`.
 167
 168   - **Suspend and Resume actors:**
 169     Actors can be suspended and resumed during their executions.
 170
 171     .. tabs::
 172
 173        .. example-tab:: examples/cpp/actor-suspend/s4u-actor-suspend.cpp
 174
 175           See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
 176           :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
 177           :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
 178
 179        .. example-tab:: examples/python/actor-suspend/actor-suspend.py
 180
 181           See also :py:func:`simgrid.this_actor.suspend()`,
 182           :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
 183           :py:func:`simgrid.Actor.is_suspended()`.
 184
 185        .. example-tab:: examples/c/actor-suspend/actor-suspend.c
 186
 187           See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
 188           :cpp:func:`sg_actor_is_suspended()`.
 189
 190   - **Migrating Actors:**
 191     Actors can move or be moved from a host to another very easily. It amounts to setting them on a new host.
 192
 193     .. tabs::
 194
 195        .. example-tab:: examples/cpp/actor-migrate/s4u-actor-migrate.cpp
 196
 197           See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
 198
 199        .. example-tab:: examples/python/actor-migrate/actor-migrate.py
 200
 201           See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
 202
 203        .. example-tab:: examples/c/actor-migrate/actor-migrate.c
 204
 205           See also :cpp:func:`sg_actor_set_host()`.
 206
 207   - **Waiting for the termination of an actor:** (joining on it)
 208     You can block the current actor until the end of another actor.
 209
 210     .. tabs::
 211
 212        .. example-tab:: examples/cpp/actor-join/s4u-actor-join.cpp
 213
 214           See also :cpp:func:`simgrid::s4u::Actor::join()`.
 215
 216        .. example-tab:: examples/python/actor-join/actor-join.py
 217
 218           See also :py:func:`simgrid.Actor.join()`.
 219
 220        .. example-tab:: examples/c/actor-join/actor-join.c
 221
 222           See also :cpp:func:`sg_actor_join`.
 223
 224   - **Yielding to other actors**.
 225     The ```yield()``` function interrupts the execution of the current
 226     actor, leaving a chance to the other actors that are ready to run
 227     at this timestamp.
 228
 229     .. tabs::
 230
 231        .. example-tab:: examples/cpp/actor-yield/s4u-actor-yield.cpp
 232
 233           See also :cpp:func:`simgrid::s4u::this_actor::yield()`.
 234
 235        .. example-tab:: examples/python/actor-yield/actor-yield.py
 236
 237           See also :py:func:`simgrid.this_actor.yield_()`.
 238
 239        .. example-tab:: examples/c/actor-yield/actor-yield.c
 240
 241           See also :cpp:func:`sg_actor_yield()`.
 242
 243 Traces Replay as a Workload
 244 ---------------------------
 245
 246 This section details how to run trace-driven simulations. It is very
 247 handy when you want to test an algorithm or protocol that only reacts
 248 to external events. For example, many P2P protocols react to user
 249 requests, but do nothing if there is no such event.
 250
 251 In such situations, you should write your protocol in C++, and separate
 252 the workload that you want to play onto your protocol in a separate
 253 text file. Declare a function handling each type of the events in your
 254 trace, register them using :cpp:func:`xbt_replay_action_register()` in
 255 your main, and then run the simulation.
 256
 257 Then, you can either have one trace file containing all your events,
 258 or a file per simulated process: the former may be easier to work
 259 with, but the second is more efficient on very large traces. Check
 260 also the tesh files in the example directories for details.
 261
 262   - **Communication replay:**
 263     Presents a set of event handlers reproducing classical communication
 264     primitives (asynchronous send/receive at the moment).
 265
 266     .. tabs::
 267
 268        .. example-tab:: examples/cpp/replay-comm/s4u-replay-comm.cpp
 269
 270   - **I/O replay:**
 271     Presents a set of event handlers reproducing classical I/O
 272     primitives (open, read, close).
 273
 274     .. tabs::
 275
 276        .. example-tab:: examples/cpp/replay-io/s4u-replay-io.cpp
 277
 278 ==========================
 279 Activities: what Actors do
 280 ==========================
 281
 282 .. _s4u_ex_communication:
 283
 284 Communications on the Network
 285 -----------------------------
 286
 287   - **Basic communications:**
 288     This simple example just sends one message back and forth.
 289     The tesh file laying in the directory shows how to start the simulator binary, highlighting how to pass options to
 290     the simulators (as detailed in Section :ref:`options`).
 291
 292     .. tabs::
 293
 294        .. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp
 295
 296        .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
 297
 298
 299  - **Basic asynchronous communications:**
 300    Illustrates how to have non-blocking communications, that are
 301    communications running in the background leaving the process free
 302    to do something else during their completion.
 303
 304    .. tabs::
 305
 306       .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
 307
 308          See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
 309
 310       .. example-tab:: examples/python/comm-wait/comm-wait.py
 311
 312          See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
 313
 314       .. example-tab:: examples/c/comm-wait/comm-wait.c
 315
 316          See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm_wait()`.
 317
 318  - **Waiting for communications with timeouts:**
 319    This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
 320
 321    .. tabs::
 322
 323       .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
 324
 325          See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
 326
 327  - **Suspending communications:**
 328    The ``suspend()`` and ``resume()`` functions allow to block the
 329    progression of a given communication for a while and then unblock it.
 330    ``is_suspended()`` can be used to retrieve whether the activity is
 331    currently blocked or not.
 332
 333    .. tabs::
 334
 335       .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
 336
 337          See also :cpp:func:`simgrid::s4u::Activity::suspend()`
 338          :cpp:func:`simgrid::s4u::Activity::resume()` and
 339          :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
 340
 341
 342  - **Waiting for all communications in a set:**
 343    The ``wait_all()`` function is useful when you want to block until
 344    all activities in a given set have been completed.
 345
 346    .. tabs::
 347
 348       .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
 349
 350          See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
 351
 352       .. example-tab:: examples/python/comm-waitall/comm-waitall.py
 353
 354          See also :py:func:`simgrid.Comm.wait_all()`.
 355
 356       .. example-tab:: examples/c/comm-waitall/comm-waitall.c
 357
 358          See also :cpp:func:`sg_comm_wait_all()`.
 359
 360  - **Waiting for the first completed communication in a set:**
 361    The ``wait_any()`` function is useful
 362    when you want to block until one activity of the set completes, no
 363    matter which terminates first.
 364
 365    .. tabs::
 366
 367       .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
 368
 369          See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
 370
 371       .. example-tab:: examples/python/comm-waitany/comm-waitany.py
 372
 373          See also :py:func:`simgrid.Comm.wait_any()`.
 374
 375       .. example-tab:: examples/c/comm-waitany/comm-waitany.c
 376
 377          See also :cpp:func:`sg_comm_wait_any`.
 378
 379 .. _s4u_ex_execution:
 380
 381 Executions on the CPU
 382 ---------------------
 383
 384   - **Basic execution:**
 385     The computations done in your program are not reported to the
 386     simulated world unless you explicitly request the simulator to pause
 387     the actor until a given amount of flops gets computed on its simulated
 388     host. Some executions can be given a higher priority so that they
 389     get more resources.
 390
 391     .. tabs::
 392
 393        .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
 394
 395           See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
 396           and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
 397
 398        .. example-tab:: examples/python/exec-basic/exec-basic.py
 399
 400           See also :py:func:`simgrid.this_actor.execute()`.
 401
 402        .. example-tab:: examples/c/exec-basic/exec-basic.c
 403
 404           See also :cpp:func:`void sg_actor_execute(double)`
 405           and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
 406
 407   - **Asynchronous execution:**
 408     You can start asynchronous executions, just like you would fire
 409     background threads.
 410
 411     .. tabs::
 412
 413        .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
 414
 415           See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
 416           :cpp:func:`simgrid::s4u::Activity::start()`,
 417           :cpp:func:`simgrid::s4u::Activity::wait()`,
 418           :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
 419           :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
 420           :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
 421           :cpp:func:`simgrid::s4u::Activity::cancel()`.
 422
 423        .. example-tab:: examples/python/exec-async/exec-async.py
 424
 425           See also :py:func:`simgrid.this_actor::exec_init()`,
 426           :py:func:`simgrid.Activity::start()`,
 427           :py:func:`simgrid.Activity.wait()`,
 428           :py:func:`simgrid.Activity.get_remaining()`,
 429           :py:func:`simgrid.Exec.get_remaining_ratio()`,
 430           :py:func:`simgrid.this_actor.exec_async()` and
 431           :py:func:`simgrid.Activity.cancel()`.
 432
 433        .. example-tab:: examples/c/exec-async/exec-async.c
 434
 435           See also :cpp:func:`sg_actor_exec_init()`,
 436           :cpp:func:`sg_exec_start()`,
 437           :cpp:func:`sg_exec_wait()`,
 438           :cpp:func:`sg_exec_get_remaining()`,
 439           :cpp:func:`sg_exec_get_remaining_ratio()`,
 440           :cpp:func:`sg_actor_exec_async()` and
 441           :cpp:func:`sg_exec_cancel()`,
 442
 443   - **Remote execution:**
 444     You can start executions on remote hosts, or even change the host
 445     on which they occur during their execution.
 446
 447     .. tabs::
 448
 449        .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
 450
 451           See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
 452
 453        .. example-tab:: examples/python/exec-remote/exec-remote.py
 454
 455           See also :py:func:`simgrid.Exec.set_host()`.
 456
 457        .. example-tab:: examples/c/exec-remote/exec-remote.c
 458
 459           See also :cpp:func:`sg_exec_set_host()`.
 460
 461   - **Parallel executions:**
 462     These objects are convenient abstractions of parallel
 463     computational kernels that span over several machines, such as a
 464     PDGEM and the other ScaLAPACK routines. Note that this only works
 465     with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
 466
 467     This example demonstrates several kinds of parallel tasks: regular
 468     ones, communication-only (without computation), computation-only
 469     (without communication), synchronization-only (neither
 470     communication nor computation). It also shows how to reconfigure a
 471     task after its start, to change the number of hosts it runs onto.
 472     This allows simulating malleable tasks.
 473
 474     .. tabs::
 475
 476        .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
 477
 478           See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
 479
 480   - **Using Pstates on a host:**
 481     This example shows how to define a set of pstates in the XML. The current pstate
 482     of a host can then be accessed and changed from the program.
 483
 484     .. tabs::
 485
 486        .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
 487
 488           See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 489
 490        .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
 491
 492           See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
 493
 494        .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 495
 496           See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
 497
 498        .. example-tab:: examples/platforms/energy_platform.xml
 499
 500 .. _s4u_ex_disk_io:
 501
 502 I/O on Disks and Files
 503 ----------------------
 504
 505 SimGrid provides two levels of abstraction to interact with the
 506 simulated disks. At the simplest level, you simply create read and
 507 write actions on the disk resources.
 508
 509   - **Access to raw disk devices:**
 510     This example illustrates how to simply read and write data on a
 511     simulated disk resource.
 512
 513     .. tabs::
 514
 515        .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
 516
 517        .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
 518
 519        .. example-tab:: examples/platforms/hosts_with_disks.xml
 520
 521           This shows how to declare disks in XML.
 522
 523 The FileSystem plugin provides a more detailed view, with the
 524 classical operations over files: open, move, unlink, and of course,
 525 read and write. The file and disk sizes are also dealt with and can
 526 result in short reads and short writes, as in reality.
 527
 528   - **File Management:**
 529     This example illustrates the use of operations on files
 530     (read, write, seek, tell, unlink, etc).
 531
 532     .. tabs::
 533
 534        .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
 535
 536   - **Remote I/O:**
 537     I/O operations on files can also be done remotely,
 538     i.e. when the accessed disk is not mounted on the caller's host.
 539
 540     .. tabs::
 541
 542        .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
 543
 544        .. example-tab:: examples/c/io-file-remote/io-file-remote.c
 545
 546 .. _s4u_ex_IPC:
 547
 548 Classical synchronization objects
 549 ---------------------------------
 550
 551  - **Barrier:**
 552    Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 553
 554    .. tabs::
 555
 556       .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
 557
 558  - **Condition variable: basic usage**
 559    Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 560
 561    .. tabs::
 562
 563       .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 564
 565  - **Condition variable: timeouts**
 566    Shows how to specify timeouts when blocking on condition variables.
 567
 568    .. tabs::
 569
 570       .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
 571
 572  - **Mutex:**
 573    Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 574
 575    .. tabs::
 576
 577       .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
 578
 579  - **Semaphore:**
 580    Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 581
 582    .. tabs::
 583
 584       .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
 585
 586       .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
 587
 588 =============================
 589 Interacting with the Platform
 590 =============================
 591
 592  - **User-defined properties:**
 593    You can attach arbitrary information to most platform elements from
 594    the XML file, and then interact with these values from your
 595    program. Note that the changes are not written permanently on disk,
 596    in the XML file nor anywhere else. They only last until the end of
 597    your simulation.
 598
 599    .. tabs::
 600
 601       .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
 602
 603          - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 604          - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 605          - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 606          - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 607
 608       .. example-tab:: examples/c/platform-properties/platform-properties.c
 609
 610          - :cpp:func:`sg_actor_get_property_value()`
 611          - :cpp:func:`sg_host_get_property_value()` and :cpp:func:sg_host_set_property_value()`
 612          - :cpp:func:`sg_zone_get_property_value()` and :cpp:func:`sg_zone_set_property_value()`
 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 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 given criteria:**
 635    Shows how to filter the actors that match 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 link and
 686     host 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 a 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 examples. 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 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 Exemplars
 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 tasks 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
 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 zone in your platform and
1015     how to use it in your simulation. For that, you should have a link
1016     whose 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.25). You should not
1076 enable it unless you really want to formally verify your applications:
1077 SimGrid is slower and may be 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 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 />