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