examples/README.rst

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