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/python/comm-pingpong/comm-pingpong.py
 323
 324    .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
 325
 326
 327 Basic asynchronous communications
 328 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 329
 330 Illustrates how to have non-blocking communications, that are communications running in the background leaving the process
 331 free to do something else during their completion.
 332
 333 .. tabs::
 334
 335    .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
 336
 337       See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
 338
 339    .. example-tab:: examples/python/comm-wait/comm-wait.py
 340
 341       See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
 342
 343    .. example-tab:: examples/c/comm-wait/comm-wait.c
 344
 345       See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm_wait()`.
 346
 347 Waiting for communications with timeouts
 348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 349
 350 This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
 351
 352 .. tabs::
 353
 354    .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
 355
 356       See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
 357
 358    .. example-tab:: examples/python/comm-waituntil/comm-waituntil.py
 359
 360       See also :py:func:`simgrid.Comm.wait_until()`
 361
 362 Suspending communications
 363 ^^^^^^^^^^^^^^^^^^^^^^^^^
 364
 365 The ``suspend()`` and ``resume()`` functions block the progression of a given communication for a while and then unblock it.
 366 ``is_suspended()`` returns whether that activity is currently blocked or not.
 367
 368 .. tabs::
 369
 370    .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
 371
 372       See also :cpp:func:`simgrid::s4u::Activity::suspend()`
 373       :cpp:func:`simgrid::s4u::Activity::resume()` and
 374       :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
 375
 376    .. example-tab:: examples/python/comm-suspend/comm-suspend.py
 377
 378       See also :py:func:`simgrid.Comm::suspend()` and
 379       :py:func:`simgrid.Comm.resume()`.
 380
 381 Waiting for all communications in a set
 382 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 383
 384 The ``wait_all()`` function is useful when you want to block until all activities in a given set have been completed.
 385
 386 .. tabs::
 387
 388    .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
 389
 390       See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
 391
 392    .. example-tab:: examples/python/comm-waitall/comm-waitall.py
 393
 394       See also :py:func:`simgrid.Comm.wait_all()`.
 395
 396    .. example-tab:: examples/c/comm-waitall/comm-waitall.c
 397
 398       See also :cpp:func:`sg_comm_wait_all()`.
 399
 400 Waiting for the first completed communication in a set
 401 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 402
 403 The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first.
 404
 405 .. tabs::
 406
 407    .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
 408
 409       See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
 410
 411    .. example-tab:: examples/python/comm-waitany/comm-waitany.py
 412
 413       See also :py:func:`simgrid.Comm.wait_any()`.
 414
 415    .. example-tab:: examples/c/comm-waitany/comm-waitany.c
 416
 417       See also :cpp:func:`sg_comm_wait_any`.
 418
 419 Testing whether at least one communication completed
 420 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 421
 422 The ``test_any()`` returns whether at least one activity of the set has completed, or -1.
 423
 424 .. tabs::
 425
 426    .. example-tab:: examples/cpp/comm-testany/s4u-comm-testany.cpp
 427
 428       See also :cpp:func:`simgrid::s4u::Comm::test_any()`.
 429
 430    .. example-tab:: examples/python/comm-testany/comm-testany.py
 431
 432       See also :py:func:`simgrid.Comm.test_any()`.
 433
 434 .. _s4u_ex_execution:
 435
 436 Executions on the CPU
 437 ---------------------
 438
 439 Basic execution
 440 ^^^^^^^^^^^^^^^
 441
 442 The computations done in your program are not reported to the
 443 simulated world unless you explicitly request the simulator to pause
 444 the actor until a given amount of flops gets computed on its simulated
 445 host. Some executions can be given a higher priority so that they
 446 get more resources.
 447
 448 .. tabs::
 449
 450    .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
 451
 452       See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
 453       and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
 454
 455    .. example-tab:: examples/python/exec-basic/exec-basic.py
 456
 457       See also :py:func:`simgrid.this_actor.execute()`.
 458
 459    .. example-tab:: examples/c/exec-basic/exec-basic.c
 460
 461       See also :cpp:func:`void sg_actor_execute(double)`
 462       and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
 463
 464 Asynchronous execution
 465 ^^^^^^^^^^^^^^^^^^^^^^
 466
 467 You can start asynchronous executions, just like you would fire background threads.
 468
 469 .. tabs::
 470
 471    .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
 472
 473       See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
 474       :cpp:func:`simgrid::s4u::Activity::start()`,
 475       :cpp:func:`simgrid::s4u::Activity::wait()`,
 476       :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
 477       :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
 478       :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
 479       :cpp:func:`simgrid::s4u::Activity::cancel()`.
 480
 481    .. example-tab:: examples/python/exec-async/exec-async.py
 482
 483       See also :py:func:`simgrid.this_actor.exec_init()`,
 484       :py:func:`simgrid.Exec.start()`,
 485       :py:func:`simgrid.Exec.wait()`,
 486       :py:attr:`simgrid.Exec.remaining`,
 487       :py:attr:`simgrid.Exec.remaining_ratio`,
 488       :py:func:`simgrid.this_actor.exec_async()` and
 489       :py:func:`simgrid.Exec.cancel()`.
 490
 491    .. example-tab:: examples/c/exec-async/exec-async.c
 492
 493       See also :cpp:func:`sg_actor_exec_init()`,
 494       :cpp:func:`sg_exec_start()`,
 495       :cpp:func:`sg_exec_wait()`,
 496       :cpp:func:`sg_exec_get_remaining()`,
 497       :cpp:func:`sg_exec_get_remaining_ratio()`,
 498       :cpp:func:`sg_actor_exec_async()` and
 499       :cpp:func:`sg_exec_cancel()`,
 500
 501 Remote execution
 502 ^^^^^^^^^^^^^^^^
 503
 504 You can start executions on remote hosts, or even change the host on which they occur during their execution.
 505
 506 .. tabs::
 507
 508    .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
 509
 510       See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
 511
 512    .. example-tab:: examples/python/exec-remote/exec-remote.py
 513
 514       See also :py:attr:`simgrid.Exec.host`.
 515
 516    .. example-tab:: examples/c/exec-remote/exec-remote.c
 517
 518       See also :cpp:func:`sg_exec_set_host()`.
 519
 520 .. _s4u_ex_ptasks:
 521
 522 Parallel executions
 523 ^^^^^^^^^^^^^^^^^^^
 524
 525 These objects are convenient abstractions of parallel
 526 computational kernels that span over several machines, such as a
 527 PDGEM and the other ScaLAPACK routines. Note that this only works
 528 with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
 529
 530 This example demonstrates several kinds of parallel tasks: regular
 531 ones, communication-only (without computation), computation-only
 532 (without communication), synchronization-only (neither
 533 communication nor computation). It also shows how to reconfigure a
 534 task after its start, to change the number of hosts it runs onto.
 535 This allows simulating malleable tasks.
 536
 537 .. tabs::
 538
 539    .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
 540
 541       See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
 542
 543    .. example-tab:: examples/python/exec-ptask/exec-ptask.py
 544
 545       See also :ref:`simgrid.this_actor.parallel_execute()`
 546
 547 DVFS and pstates
 548 ^^^^^^^^^^^^^^^^
 549
 550 This example shows how to define a set of pstates in the XML. The current pstate
 551 of a host can then be accessed and changed from the program.
 552
 553 .. tabs::
 554
 555    .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
 556
 557       See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 558
 559    .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
 560
 561       See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
 562
 563    .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 564
 565       See also :py:func:`simgrid.Host.pstate_speed()` and :py:attr:`simgrid.Host.pstate`.
 566
 567    .. example-tab:: examples/platforms/energy_platform.xml
 568
 569 .. _s4u_ex_disk_io:
 570
 571 I/O on Disks and Files
 572 ----------------------
 573
 574 SimGrid provides two levels of abstraction to interact with the
 575 simulated disks. At the simplest level, you simply create read and
 576 write actions on the disk resources.
 577
 578 Access to raw disk devices
 579 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 580
 581 This example illustrates how to simply read and write data on a simulated disk resource.
 582
 583 .. tabs::
 584
 585    .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
 586
 587    .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
 588
 589    .. example-tab:: examples/platforms/hosts_with_disks.xml
 590
 591       This shows how to declare disks in XML.
 592
 593 Filesystem plugin
 594 ^^^^^^^^^^^^^^^^^
 595
 596 The FileSystem plugin provides a more detailed view, with the
 597 classical operations over files: open, move, unlink, and of course,
 598 read and write. The file and disk sizes are also dealt with and can
 599 result in short reads and short writes, as in reality.
 600
 601   - **File Management:**
 602     This example illustrates the use of operations on files
 603     (read, write, seek, tell, unlink, etc).
 604
 605     .. tabs::
 606
 607        .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
 608
 609   - **Remote I/O:**
 610     I/O operations on files can also be done remotely,
 611     i.e. when the accessed disk is not mounted on the caller's host.
 612
 613     .. tabs::
 614
 615        .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
 616
 617        .. example-tab:: examples/c/io-file-remote/io-file-remote.c
 618
 619 .. _s4u_ex_IPC:
 620
 621 Classical synchronization objects
 622 ---------------------------------
 623
 624 Barrier
 625 ^^^^^^^
 626
 627 Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 628
 629 .. tabs::
 630
 631    .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
 632
 633    .. example-tab:: examples/python/synchro-barrier/synchro-barrier.py
 634
 635 Condition variable: basic usage
 636 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 637
 638 Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 639
 640 .. tabs::
 641
 642    .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 643
 644 Condition variable: timeouts
 645 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 646
 647 Shows how to specify timeouts when blocking on condition variables.
 648
 649 .. tabs::
 650
 651    .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
 652
 653 Mutex
 654 ^^^^^
 655
 656 Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 657
 658 .. tabs::
 659
 660    .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
 661
 662    .. example-tab:: examples/python/synchro-mutex/synchro-mutex.py
 663
 664 Semaphore
 665 ^^^^^^^^^
 666
 667 Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 668
 669 .. tabs::
 670
 671    .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
 672
 673    .. example-tab:: examples/python/synchro-semaphore/synchro-semaphore.py
 674
 675    .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
 676
 677 =============================
 678 Interacting with the Platform
 679 =============================
 680
 681 User-defined properties
 682 -----------------------
 683
 684 You can attach arbitrary information to most platform elements from the XML file, and then interact with these values from your
 685 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
 686 your simulation.
 687
 688 .. tabs::
 689
 690    .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
 691
 692       - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 693       - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 694       - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 695       - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 696
 697    .. example-tab:: examples/c/platform-properties/platform-properties.c
 698
 699       - :cpp:func:`sg_actor_get_property_value()`
 700       - :cpp:func:`sg_host_get_property_value()` and :cpp:func:sg_host_set_property_value()`
 701       - :cpp:func:`sg_zone_get_property_value()` and :cpp:func:`sg_zone_set_property_value()`
 702
 703    .. group-tab:: XML
 704
 705       **Platform file:**
 706
 707       .. showfile:: examples/platforms/prop.xml
 708          :language: xml
 709
 710 Element filtering
 711 -----------------
 712
 713 Retrieving the netzones matching given criteria
 714 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 715
 716 Shows how to filter the cluster netzones.
 717
 718 .. tabs::
 719
 720    .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
 721
 722 Retrieving the list of hosts matching given criteria
 723 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 724
 725 Shows how to filter the actors that match given criteria.
 726
 727 .. tabs::
 728
 729    .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
 730
 731 Profiles
 732 --------
 733
 734 Specifying state profiles
 735 ^^^^^^^^^^^^^^^^^^^^^^^^^
 736
 737 Shows how to specify when the resources must be turned off and on again, and how to react to such
 738 failures in your code. See also :ref:`howto_churn`.
 739
 740 .. tabs::
 741
 742    .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
 743
 744    .. example-tab:: examples/c/platform-failures/platform-failures.c
 745
 746    .. example-tab:: examples/python/platform-failures/platform-failures.py
 747
 748    .. group-tab:: XML
 749
 750       .. showfile:: examples/platforms/small_platform_failures.xml
 751          :language: xml
 752
 753       .. showfile:: examples/platforms/profiles/jupiter_state.profile
 754
 755       .. showfile:: examples/platforms/profiles/fafard_state.profile
 756
 757 Specifying speed profiles
 758 ^^^^^^^^^^^^^^^^^^^^^^^^^
 759
 760 Shows how to specify an external load to resources, variating their peak speed over time.
 761
 762    .. tabs::
 763
 764       .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
 765
 766       .. example-tab:: examples/python/platform-profile/platform-profile.py
 767
 768       .. group-tab:: XML
 769
 770          .. showfile:: examples/platforms/small_platform_profile.xml
 771             :language: xml
 772
 773          .. showfile:: examples/platforms/profiles/jupiter_speed.profile
 774
 775          .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
 776
 777          .. showfile:: examples/platforms/profiles/link1_latency.profile
 778
 779 =================
 780 Energy Simulation
 781 =================
 782
 783 Setup
 784 -----
 785
 786 Describing the energy profiles in the platform
 787 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 788
 789 The first platform file contains the energy profile of each link and host for a wired network, which is necessary to get energy consumption
 790 predictions. The second platform file is the equivalent for a wireless network. As usual, you should not trust our example, and you should
 791 strive to double-check that your instantiation matches your target platform.
 792
 793 .. tabs::
 794
 795    .. group-tab:: XML
 796
 797 .. showfile:: examples/platforms/energy_platform.xml
 798    :language: xml
 799
 800 .. showfile:: examples/platforms/wifi_energy.xml
 801    :language: xml
 802
 803 Usage
 804 -----
 805
 806 CPU energy consumption
 807 ^^^^^^^^^^^^^^^^^^^^^^
 808
 809 This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate.
 810
 811 .. tabs::
 812
 813    .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
 814
 815    .. example-tab:: examples/c/energy-exec/energy-exec.c
 816
 817 Virtual machines consumption
 818 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 819
 820 This example is very similar to the previous one, adding VMs to the picture.
 821
 822 .. tabs::
 823
 824    .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp
 825
 826    .. example-tab:: examples/c/energy-vm/energy-vm.c
 827
 828 Wired network energy consumption
 829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 830
 831 This example shows how to retrieve and display the energy consumed by the wired network during communications.
 832
 833 .. tabs::
 834
 835    .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
 836
 837 WiFi network energy consumption
 838 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 839
 840 This example shows how to retrieve and display the energy consumed by the wireless network during communications.
 841
 842 .. tabs::
 843
 844    .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
 845
 846 Modeling the shutdown and boot of hosts
 847 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 848
 849 Simple example of a model for the energy consumption during the host boot and shutdown periods.
 850
 851 .. tabs::
 852
 853    .. example-tab:: examples/platforms/energy_boot.xml
 854
 855    .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
 856
 857 =======================
 858 Tracing and Visualizing
 859 =======================
 860
 861 Tracing can be activated by various configuration options which are illustrated in these examples. See also the
 862 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 863 The following introduces  some option sets of interest that you may want to pass to your simulators.
 864
 865 .. todo::
 866    These tracing examples should be integrated in the examples to not duplicate the C++ files.
 867    A full command line to see the result in the right tool (vite/FrameSoc) should be given along with some screenshots.
 868
 869 Platform Tracing
 870 ----------------
 871
 872 Basic example
 873 ^^^^^^^^^^^^^
 874
 875 This program is a toy example just loading the platform so that you can play with the platform visualization. Recommended options:
 876 ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 877
 878 .. tabs::
 879
 880    .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
 881
 882 Setting Categories
 883 ^^^^^^^^^^^^^^^^^^
 884
 885 This example declares several tracing categories that are used to
 886 classify its tasks. When the program is executed, the tracing mechanism
 887 registers the resource utilization of hosts and links according to these
 888 categories. Recommended options:
 889 ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 890
 891 .. tabs::
 892
 893    .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
 894
 895 Master Workers tracing
 896 ^^^^^^^^^^^^^^^^^^^^^^
 897
 898 This is an augmented version of our basic master/worker example using
 899 several tracing features. It traces resource usage, sorted out in several
 900 categories; Trace marks and user variables are also used. Recommended
 901 options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 902
 903 .. tabs::
 904
 905    .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
 906
 907    .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
 908
 909 Process migration tracing
 910 ^^^^^^^^^^^^^^^^^^^^^^^^^
 911
 912 This version is enhanced so that the process migrations can be displayed
 913 as arrows in a Gantt-chart visualization. Recommended options to that
 914 extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
 915
 916 .. tabs::
 917
 918    .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
 919
 920 Tracing user variables
 921 ----------------------
 922
 923 You can also attach your own variables to any resource described in the platform
 924 file. The following examples illustrate this feature.  They have to be run with
 925 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
 926
 927 Attaching variables to Hosts
 928 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 929
 930 .. tabs::
 931
 932    .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
 933
 934 Attaching variables to Links
 935 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 936
 937 The tricky part is that you have to know the name of the link you want to enhance with a variable.
 938
 939 .. tabs::
 940
 941    .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
 942
 943 Attaching variables to network routes
 944 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 945
 946 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
 947 knowing the name of each specific link.
 948
 949 .. tabs::
 950
 951    .. example-tab::  examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
 952
 953 ========================
 954 Larger SimGrid Exemplars
 955 ========================
 956
 957 This section contains application examples that are somewhat larger than the previous examples.
 958
 959 Classical examples
 960 ------------------
 961
 962 Token ring
 963 ^^^^^^^^^^
 964
 965 Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant.
 966
 967 .. tabs::
 968
 969    .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
 970
 971    .. example-tab:: examples/c/app-token-ring/app-token-ring.c
 972
 973 Master Workers
 974 ^^^^^^^^^^^^^^
 975
 976 Another good old example, where one Master actor has a bunch of tasks to dispatch to a set of several Worker actors.
 977 This example is used in the :ref:`SimGrid tutorial <usecase_simalgo>`.
 978
 979 .. tabs::
 980
 981    .. group-tab:: C++
 982
 983       This example comes in two equivalent variants, one where the actors
 984       are specified as simple functions (which is easier to understand for
 985       newcomers) and one where the actors are specified as classes (which is
 986       more powerful for the users wanting to build their own projects upon
 987       the example).
 988
 989       .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
 990          :language: cpp
 991
 992       .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
 993          :language: cpp
 994
 995    .. group-tab:: C
 996
 997       .. showfile:: examples/c/app-masterworker/app-masterworker.c
 998          :language: cpp
 999
1000    .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
1001
1002 Data diffusion
1003 --------------
1004
1005 Bit Torrent
1006 ^^^^^^^^^^^
1007
1008 Classical protocol for Peer-to-Peer data diffusion.
1009
1010 .. tabs::
1011
1012    .. group-tab:: C++
1013
1014       .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
1015          :language: cpp
1016
1017       .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
1018          :language: cpp
1019
1020       .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
1021          :language: cpp
1022
1023    .. group-tab:: C
1024
1025       .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
1026          :language: cpp
1027
1028       .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
1029          :language: cpp
1030
1031       .. showfile:: examples/c/app-bittorrent/tracker.c
1032          :language: cpp
1033
1034 Chained Send
1035 ^^^^^^^^^^^^
1036
1037 Data broadcast over a ring of processes.
1038
1039 .. tabs::
1040
1041    .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
1042
1043    .. group-tab:: C
1044
1045       .. showfile:: examples/c/app-chainsend/chainsend.c
1046          :language: c
1047
1048       .. showfile:: examples/c/app-chainsend/broadcaster.c
1049          :language: c
1050
1051       .. showfile:: examples/c/app-chainsend/peer.c
1052          :language: c
1053
1054 Distributed Hash Tables (DHT)
1055 -----------------------------
1056
1057 Chord Protocol
1058 ^^^^^^^^^^^^^^
1059
1060 One of the most famous DHT protocol.
1061
1062 .. tabs::
1063
1064    .. group-tab:: C++
1065
1066       .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
1067          :language: cpp
1068
1069       .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
1070          :language: cpp
1071
1072 Kademlia
1073 ^^^^^^^^
1074
1075 Another well-known DHT protocol.
1076
1077 .. tabs::
1078
1079    .. group-tab:: C++
1080
1081       .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
1082          :language: cpp
1083
1084       .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
1085          :language: cpp
1086
1087       .. showfile:: examples/cpp/dht-kademlia/answer.cpp
1088          :language: cpp
1089
1090       .. showfile:: examples/cpp/dht-kademlia/node.cpp
1091          :language: cpp
1092
1093    .. group-tab:: C
1094
1095       .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
1096          :language: cpp
1097
1098       .. showfile:: examples/c/dht-kademlia/routing_table.c
1099          :language: cpp
1100
1101       .. showfile:: examples/c/dht-kademlia/answer.c
1102          :language: cpp
1103
1104       .. showfile:: examples/c/dht-kademlia/message.c
1105          :language: cpp
1106
1107       .. showfile:: examples/c/dht-kademlia/node.c
1108          :language: cpp
1109
1110 Pastry
1111 ^^^^^^
1112
1113 Yet another well-known DHT protocol.
1114
1115 .. tabs::
1116
1117    .. example-tab:: examples/c/dht-pastry/dht-pastry.c
1118
1119 .. _s4u_ex_clouds:
1120
1121 Simulating Clouds
1122 -----------------
1123
1124 Cloud basics
1125 ^^^^^^^^^^^^
1126
1127 This example starts some computations both on PMs and VMs and migrates some VMs around.
1128
1129 .. tabs::
1130
1131    .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
1132
1133    .. example-tab:: examples/c/cloud-simple/cloud-simple.c
1134
1135 Migrating VMs
1136 ^^^^^^^^^^^^^
1137
1138 This example shows how to migrate VMs between PMs.
1139
1140 .. tabs::
1141
1142    .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
1143
1144    .. example-tab:: examples/c/cloud-migration/cloud-migration.c
1145
1146 =======================
1147 Model-Related Examples
1148 =======================
1149
1150 ns-3 as a model
1151 ---------------
1152
1153 This simple ping-pong example demonstrates how to use the bindings to the Network
1154 Simulator. The most interesting is probably not the C++ files since
1155 they are unchanged from the other simulations, but the associated files,
1156 such as the platform file to see how to declare a platform to be used
1157 with the ns-3 bindings of SimGrid and the tesh file to see how to
1158 start a simulation in these settings.
1159
1160 .. tabs::
1161
1162    .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1163
1164    .. group-tab:: XML
1165
1166       **Platform files:**
1167
1168       .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1169          :language: xml
1170
1171 WiFi links
1172 ----------
1173
1174 This demonstrates how to declare a wifi zone in your platform and
1175 how to use it in your simulation. For that, you should have a link
1176 whose sharing policy is set to `WIFI`. Such links can have more
1177 than one bandwidth value (separated by commas), corresponding to
1178 the several SNR level of your wifi link.
1179
1180 In this case, SimGrid automatically switches to validated
1181 performance models of wifi networks, where the time is shared
1182 between users instead of the bandwidth for wired links (the
1183 corresponding publication is currently being written).
1184
1185 If your wifi link provides more than one SNR level, you can switch
1186 the level of a given host using
1187 :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1188 the first level is used.
1189
1190 .. tabs::
1191
1192    .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1193
1194    .. group-tab:: XML
1195
1196       **Platform files:**
1197
1198       .. showfile:: examples/platforms/wifi.xml
1199          :language: xml
1200
1201
1202
1203 ===============
1204 Plugin Examples
1205 ===============
1206
1207 It is possible to extend SimGrid without modifying its internals by
1208 attaching code to the existing signals and by adding extra data to the
1209 simulation objects through extensions. How to do that is not exactly
1210 documented yet, and you should look for examples in the src/plugins
1211 directory.
1212
1213 This section documents how the existing plugins can be used. Remember
1214 that you are very welcome to modify the plugins to fit your needs. It
1215 should be much easier than modifying the SimGrid kernel.
1216
1217 Monitoring the host load
1218 ------------------------
1219
1220 .. tabs::
1221
1222    .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1223
1224    .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1225
1226 Monitoring the link load
1227 ------------------------
1228
1229 .. tabs::
1230
1231    .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1232
1233 =======================
1234 Model-Checking Examples
1235 =======================
1236
1237 The model-checker can be used to exhaustively search for issues in the tested application. It must be activated at compile-time, but this
1238 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
1239
1240 Failing assert
1241 --------------
1242
1243 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
1244 This is wrong, and the model-checker correctly finds a counter-example to that assertion.
1245
1246 .. tabs::
1247
1248    .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp
1249
1250 .. |br| raw:: html
1251
1252    <br />