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/fafard_state.profile
 659
 660  - **Specifying speed profiles:** shows how to specify an external
 661    load to resources, variating their peak speed over time.
 662
 663    .. tabs::
 664
 665       .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
 666
 667       .. group-tab:: XML
 668
 669          .. showfile:: examples/platforms/small_platform_profile.xml
 670             :language: xml
 671
 672          .. showfile:: examples/platforms/profiles/jupiter_speed.profile
 673
 674          .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
 675
 676          .. showfile:: examples/platforms/profiles/link1_latency.profile
 677
 678 =================
 679 Energy Simulation
 680 =================
 681
 682   - **Describing the energy profiles in the platform:**
 683     The first platform file contains the energy profile of each link and
 684     host for a wired network, which is necessary to get energy consumption
 685     predictions. The second platform file is the equivalent for a wireless
 686     network. As usual, you should not trust our example, and you should
 687     strive to double-check that your instantiation matches your target
 688     platform.
 689
 690     .. tabs::
 691
 692        .. group-tab:: XML
 693
 694           .. showfile:: examples/platforms/energy_platform.xml
 695              :language: xml
 696
 697           .. showfile:: examples/platforms/wifi_energy.xml
 698              :language: xml
 699
 700   - **Consumption due to the CPU:**
 701     This example shows how to retrieve the amount of energy consumed
 702     by the CPU during computations, and the impact of the pstate.
 703
 704     .. tabs::
 705
 706        .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
 707
 708        .. example-tab:: examples/c/energy-exec/energy-exec.c
 709
 710   - **Consumption due to the wired network:**
 711     This example shows how to retrieve and display the energy consumed
 712     by the wired network during communications.
 713
 714     .. tabs::
 715
 716        .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
 717
 718   - **Consumption due to the wireless network:**
 719     This example shows how to retrieve and display the energy consumed
 720     by the wireless network during communications.
 721
 722     .. tabs::
 723
 724        .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
 725
 726   - **Modeling the shutdown and boot of hosts:**
 727     Simple example of a model for the energy consumption during
 728     the host boot and shutdown periods.
 729
 730     .. tabs::
 731
 732        .. example-tab:: examples/cpp/energy-boot/platform_boot.xml
 733
 734        .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
 735
 736 =======================
 737 Tracing and Visualizing
 738 =======================
 739
 740 Tracing can be activated by various configuration options which
 741 are illustrated in these examples. See also the
 742 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 743
 744 It is interesting to run the process-create example with the following
 745 options to see the task executions:
 746
 747   - **Platform Tracing:**
 748     This program is a toy example just loading the platform so that
 749     you can play with the platform visualization. Recommended options:
 750     ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 751
 752     .. tabs::
 753
 754        .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
 755
 756   - **Setting Categories**
 757     This example declares several tracing categories that are used to
 758     classify its tasks. When the program is executed, the tracing mechanism
 759     registers the resource utilization of hosts and links according to these
 760     categories. Recommended options:
 761     ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 762
 763     .. tabs::
 764
 765        .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
 766
 767   - **Master Workers tracing**
 768     This is an augmented version of our basic master/worker example using
 769     several tracing features. It traces resource usage, sorted out in several
 770     categories; Trace marks and user variables are also used. Recommended
 771     options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 772
 773     .. tabs::
 774
 775        .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
 776
 777   - **Process migration tracing**
 778     This version is enhanced so that the process migrations can be displayed
 779     as arrows in a Gantt-chart visualization. Recommended options to that
 780     extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
 781
 782     .. tabs::
 783
 784        .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
 785
 786 ..
 787     TODO: These tracing examples should be integrated in the examples to not
 788     duplicate the C++ files. A full command line to see the result in the right
 789     tool (vite/FrameSoc) should be given along with some screenshots.
 790
 791 Tracing user variables
 792 ----------------------
 793
 794 You can also attach your own variables to any resource described in the platform
 795 file. The following examples illustrate this feature.  They have to be run with
 796 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
 797
 798   - **Attaching variables to Hosts**
 799
 800     .. tabs::
 801
 802        .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
 803
 804   - **Attaching variables to Links**
 805     The tricky part is that you have to know the name of the link you want to
 806     enhance with a variable.
 807
 808     .. tabs::
 809
 810        .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
 811
 812   - **Attaching variables to network Routes**
 813     It is often easier to update a given variable for all links of a given
 814     network path (identified by its source and destination hosts) instead of
 815     knowing the name of each specific link.
 816
 817     .. tabs::
 818
 819        .. example-tab::  examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
 820
 821 ========================
 822 Larger SimGrid Exemplars
 823 ========================
 824
 825 This section contains application examples that are somewhat larger
 826 than the previous examples.
 827
 828   - **Token ring:**
 829     Shows how to implement a classical communication pattern, where a
 830     token is exchanged along a ring to reach every participant.
 831
 832     .. tabs::
 833
 834        .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
 835
 836        .. example-tab:: examples/c/app-token-ring/app-token-ring.c
 837
 838   - **Master Workers:**
 839     Another good old example, where one Master process has a bunch of tasks to dispatch to a set of several Worker
 840     processes.
 841
 842     .. tabs::
 843
 844        .. group-tab:: C++
 845
 846           This example comes in two equivalent variants, one where the actors
 847           are specified as simple functions (which is easier to understand for
 848           newcomers) and one where the actors are specified as classes (which is
 849           more powerful for the users wanting to build their own projects upon
 850           the example).
 851
 852           .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
 853              :language: cpp
 854
 855           .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
 856              :language: cpp
 857
 858        .. group-tab:: C
 859
 860           .. showfile:: examples/c/app-masterworker/app-masterworker.c
 861              :language: cpp
 862
 863 Data diffusion
 864 --------------
 865
 866   - **Bit Torrent:**
 867     Classical protocol for Peer-to-Peer data diffusion.
 868
 869     .. tabs::
 870
 871        .. group-tab:: C++
 872
 873           .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
 874              :language: cpp
 875
 876           .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
 877              :language: cpp
 878
 879           .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
 880              :language: cpp
 881
 882        .. group-tab:: C
 883
 884           .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
 885              :language: cpp
 886
 887           .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
 888              :language: cpp
 889
 890           .. showfile:: examples/c/app-bittorrent/tracker.c
 891              :language: cpp
 892
 893   - **Chained Send:**
 894     Data broadcast over a ring of processes.
 895
 896     .. tabs::
 897
 898        .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
 899
 900        .. group-tab:: C
 901
 902           .. showfile:: examples/c/app-chainsend/chainsend.c
 903              :language: c
 904
 905           .. showfile:: examples/c/app-chainsend/broadcaster.c
 906              :language: c
 907
 908           .. showfile:: examples/c/app-chainsend/peer.c
 909              :language: c
 910
 911 Distributed Hash Tables (DHT)
 912 -----------------------------
 913
 914   - **Chord Protocol**
 915     One of the most famous DHT protocol.
 916
 917     .. tabs::
 918
 919        .. group-tab:: C++
 920
 921           .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
 922              :language: cpp
 923
 924           .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
 925              :language: cpp
 926
 927   - **Kademlia**
 928     Another well-known DHT protocol.
 929
 930     .. tabs::
 931
 932        .. group-tab:: C++
 933
 934           .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
 935              :language: cpp
 936
 937           .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
 938              :language: cpp
 939
 940           .. showfile:: examples/cpp/dht-kademlia/answer.cpp
 941              :language: cpp
 942
 943           .. showfile:: examples/cpp/dht-kademlia/node.cpp
 944              :language: cpp
 945
 946        .. group-tab:: C
 947
 948           .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
 949              :language: cpp
 950
 951           .. showfile:: examples/c/dht-kademlia/routing_table.c
 952              :language: cpp
 953
 954           .. showfile:: examples/c/dht-kademlia/answer.c
 955              :language: cpp
 956
 957           .. showfile:: examples/c/dht-kademlia/message.c
 958              :language: cpp
 959
 960           .. showfile:: examples/c/dht-kademlia/node.c
 961              :language: cpp
 962
 963 .. _s4u_ex_clouds:
 964
 965 Simulating Clouds
 966 -----------------
 967
 968   - **Cloud basics**
 969     This example starts some computations both on PMs and VMs and
 970     migrates some VMs around.
 971
 972     .. tabs::
 973
 974        .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
 975
 976        .. example-tab:: examples/c/cloud-simple/cloud-simple.c
 977
 978   - **Migrating VMs**
 979     This example shows how to migrate VMs between PMs.
 980
 981     .. tabs::
 982
 983        .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
 984
 985        .. example-tab:: examples/c/cloud-migration/cloud-migration.c
 986
 987 =======================
 988 Model-Related Examples
 989 =======================
 990
 991   - **ns-3 as a SimGrid Network Model**
 992     This simple ping-pong example demonstrates how to use the bindings to the Network
 993     Simulator. The most interesting is probably not the C++ files since
 994     they are unchanged from the other simulations, but the associated files,
 995     such as the platform file to see how to declare a platform to be used
 996     with the ns-3 bindings of SimGrid and the tesh file to see how to
 997     start a simulation in these settings.
 998
 999     .. tabs::
1000
1001       .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1002
1003       .. group-tab:: XML
1004
1005          **Platform files:**
1006
1007          .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1008             :language: xml
1009
1010   - **wifi links**
1011
1012     This demonstrates how to declare a wifi zone in your platform and
1013     how to use it in your simulation. For that, you should have a link
1014     whose sharing policy is set to `WIFI`. Such links can have more
1015     than one bandwidth value (separated by commas), corresponding to
1016     the several SNR level of your wifi link.
1017
1018     In this case, SimGrid automatically switches to validated
1019     performance models of wifi networks, where the time is shared
1020     between users instead of the bandwidth for wired links (the
1021     corresponding publication is currently being written).
1022
1023     If your wifi link provides more than one SNR level, you can switch
1024     the level of a given host using
1025     :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1026     the first level is used.
1027
1028     .. tabs::
1029
1030       .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1031
1032       .. group-tab:: XML
1033
1034          **Platform files:**
1035
1036          .. showfile:: examples/platforms/wifi.xml
1037             :language: xml
1038
1039 ===============
1040 Plugin Examples
1041 ===============
1042
1043 It is possible to extend SimGrid without modifying its internals by
1044 attaching code to the existing signals and by adding extra data to the
1045 simulation objects through extensions. How to do that is not exactly
1046 documented yet, and you should look for examples in the src/plugins
1047 directory.
1048
1049 This section documents how the existing plugins can be used. Remember
1050 that you are very welcome to modify the plugins to fit your needs. It
1051 should be much easier than modifying the SimGrid kernel.
1052
1053   - **Monitoring the host load**
1054
1055     .. tabs::
1056
1057       .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1058
1059       .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1060
1061   - **Monitoring the link load**
1062
1063     .. tabs::
1064
1065       .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1066
1067 =======================
1068 Model-Checking Examples
1069 =======================
1070
1071 The model-checker can be used to exhaustively search for issues in the
1072 tested application. It must be activated at compile-time, but this
1073 mode is rather experimental in SimGrid (as of v3.25). You should not
1074 enable it unless you really want to formally verify your applications:
1075 SimGrid is slower and may be less robust when MC is enabled.
1076
1077   - **Failing assert**
1078     In this example, two actors send some data to a central server,
1079     which asserts that the messages are always received in the same order.
1080     This is wrong, and the model-checker correctly finds a
1081     counter-example to that assertion.
1082
1083     .. tabs::
1084
1085        .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp
1086
1087 .. |br| raw:: html
1088
1089    <br />