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-waitfor/comm-waitfor.py
 359
 360       See also :py:func:`simgrid.Comm.wait_for()` and :py:func:`simgrid.Comm.wait_any_for()`
 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 DVFS and pstates
 544 ^^^^^^^^^^^^^^^^
 545
 546 This example shows how to define a set of pstates in the XML. The current pstate
 547 of a host can then be accessed and changed from the program.
 548
 549 .. tabs::
 550
 551    .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
 552
 553       See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
 554
 555    .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
 556
 557       See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
 558
 559    .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
 560
 561       See also :py:func:`simgrid.Host.pstate_speed()` and :py:attr:`simgrid.Host.pstate`.
 562
 563    .. example-tab:: examples/platforms/energy_platform.xml
 564
 565 .. _s4u_ex_disk_io:
 566
 567 I/O on Disks and Files
 568 ----------------------
 569
 570 SimGrid provides two levels of abstraction to interact with the
 571 simulated disks. At the simplest level, you simply create read and
 572 write actions on the disk resources.
 573
 574 Access to raw disk devices
 575 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 576
 577 This example illustrates how to simply read and write data on a simulated disk resource.
 578
 579 .. tabs::
 580
 581    .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
 582
 583    .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
 584
 585    .. example-tab:: examples/platforms/hosts_with_disks.xml
 586
 587       This shows how to declare disks in XML.
 588
 589 Filesystem plugin
 590 ^^^^^^^^^^^^^^^^^
 591
 592 The FileSystem plugin provides a more detailed view, with the
 593 classical operations over files: open, move, unlink, and of course,
 594 read and write. The file and disk sizes are also dealt with and can
 595 result in short reads and short writes, as in reality.
 596
 597   - **File Management:**
 598     This example illustrates the use of operations on files
 599     (read, write, seek, tell, unlink, etc).
 600
 601     .. tabs::
 602
 603        .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
 604
 605   - **Remote I/O:**
 606     I/O operations on files can also be done remotely,
 607     i.e. when the accessed disk is not mounted on the caller's host.
 608
 609     .. tabs::
 610
 611        .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
 612
 613        .. example-tab:: examples/c/io-file-remote/io-file-remote.c
 614
 615 .. _s4u_ex_IPC:
 616
 617 Classical synchronization objects
 618 ---------------------------------
 619
 620 Barrier
 621 ^^^^^^^
 622
 623 Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 624
 625 .. tabs::
 626
 627    .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
 628
 629    .. example-tab:: examples/python/synchro-barrier/synchro-barrier.py
 630
 631 Condition variable: basic usage
 632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 633
 634 Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 635
 636 .. tabs::
 637
 638    .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 639
 640 Condition variable: timeouts
 641 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 642
 643 Shows how to specify timeouts when blocking on condition variables.
 644
 645 .. tabs::
 646
 647    .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
 648
 649 Mutex
 650 ^^^^^
 651
 652 Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 653
 654 .. tabs::
 655
 656    .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
 657
 658    .. example-tab:: examples/python/synchro-mutex/synchro-mutex.py
 659
 660 Semaphore
 661 ^^^^^^^^^
 662
 663 Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 664
 665 .. tabs::
 666
 667    .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
 668
 669    .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
 670
 671 =============================
 672 Interacting with the Platform
 673 =============================
 674
 675 User-defined properties
 676 -----------------------
 677
 678 You can attach arbitrary information to most platform elements from the XML file, and then interact with these values from your
 679 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
 680 your simulation.
 681
 682 .. tabs::
 683
 684    .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
 685
 686       - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
 687       - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
 688       - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
 689       - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
 690
 691    .. example-tab:: examples/c/platform-properties/platform-properties.c
 692
 693       - :cpp:func:`sg_actor_get_property_value()`
 694       - :cpp:func:`sg_host_get_property_value()` and :cpp:func:sg_host_set_property_value()`
 695       - :cpp:func:`sg_zone_get_property_value()` and :cpp:func:`sg_zone_set_property_value()`
 696
 697    .. group-tab:: XML
 698
 699       **Platform file:**
 700
 701       .. showfile:: examples/platforms/prop.xml
 702          :language: xml
 703
 704 Element filtering
 705 -----------------
 706
 707 Retrieving the netzones matching given criteria
 708 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 709
 710 Shows how to filter the cluster netzones.
 711
 712 .. tabs::
 713
 714    .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
 715
 716 Retrieving the list of hosts matching given criteria
 717 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 718
 719 Shows how to filter the actors that match given criteria.
 720
 721 .. tabs::
 722
 723    .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
 724
 725 Profiles
 726 --------
 727
 728 Specifying state profiles
 729 ^^^^^^^^^^^^^^^^^^^^^^^^^
 730
 731 Shows how to specify when the resources must be turned off and on again, and how to react to such
 732 failures in your code. See also :ref:`howto_churn`.
 733
 734 .. tabs::
 735
 736    .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
 737
 738    .. example-tab:: examples/c/platform-failures/platform-failures.c
 739
 740    .. group-tab:: XML
 741
 742       .. showfile:: examples/platforms/small_platform_failures.xml
 743          :language: xml
 744
 745       .. showfile:: examples/platforms/profiles/jupiter_state.profile
 746
 747       .. showfile:: examples/platforms/profiles/fafard_state.profile
 748
 749 Specifying speed profiles
 750 ^^^^^^^^^^^^^^^^^^^^^^^^^
 751
 752 Shows how to specify an external load to resources, variating their peak speed over time.
 753
 754    .. tabs::
 755
 756       .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
 757
 758       .. example-tab:: examples/python/platform-profile/platform-profile.py
 759
 760       .. group-tab:: XML
 761
 762          .. showfile:: examples/platforms/small_platform_profile.xml
 763             :language: xml
 764
 765          .. showfile:: examples/platforms/profiles/jupiter_speed.profile
 766
 767          .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
 768
 769          .. showfile:: examples/platforms/profiles/link1_latency.profile
 770
 771 =================
 772 Energy Simulation
 773 =================
 774
 775 Setup
 776 -----
 777
 778 Describing the energy profiles in the platform
 779 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 780
 781 The first platform file contains the energy profile of each link and host for a wired network, which is necessary to get energy consumption
 782 predictions. The second platform file is the equivalent for a wireless network. As usual, you should not trust our example, and you should
 783 strive to double-check that your instantiation matches your target platform.
 784
 785 .. tabs::
 786
 787    .. group-tab:: XML
 788
 789 .. showfile:: examples/platforms/energy_platform.xml
 790    :language: xml
 791
 792 .. showfile:: examples/platforms/wifi_energy.xml
 793    :language: xml
 794
 795 Usage
 796 -----
 797
 798 CPU energy consumption
 799 ^^^^^^^^^^^^^^^^^^^^^^
 800
 801 This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate.
 802
 803 .. tabs::
 804
 805    .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
 806
 807    .. example-tab:: examples/c/energy-exec/energy-exec.c
 808
 809 Virtual machines consumption
 810 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 811
 812 This example is very similar to the previous one, adding VMs to the picture.
 813
 814 .. tabs::
 815
 816    .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp
 817
 818    .. example-tab:: examples/c/energy-vm/energy-vm.c
 819
 820 Wired network energy consumption
 821 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 822
 823 This example shows how to retrieve and display the energy consumed by the wired network during communications.
 824
 825 .. tabs::
 826
 827    .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
 828
 829 WiFi network energy consumption
 830 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 831
 832 This example shows how to retrieve and display the energy consumed by the wireless network during communications.
 833
 834 .. tabs::
 835
 836    .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
 837
 838 Modeling the shutdown and boot of hosts
 839 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 840
 841 Simple example of a model for the energy consumption during the host boot and shutdown periods.
 842
 843 .. tabs::
 844
 845    .. example-tab:: examples/platforms/energy_boot.xml
 846
 847    .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
 848
 849 =======================
 850 Tracing and Visualizing
 851 =======================
 852
 853 Tracing can be activated by various configuration options which are illustrated in these examples. See also the
 854 :ref:`full list of options related to tracing <tracing_tracing_options>`.
 855 The following introduces  some option sets of interest that you may want to pass to your simulators.
 856
 857 .. todo::
 858    These tracing examples should be integrated in the examples to not duplicate the C++ files.
 859    A full command line to see the result in the right tool (vite/FrameSoc) should be given along with some screenshots.
 860
 861 Platform Tracing
 862 ----------------
 863
 864 Basic example
 865 ^^^^^^^^^^^^^
 866
 867 This program is a toy example just loading the platform so that you can play with the platform visualization. Recommended options:
 868 ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
 869
 870 .. tabs::
 871
 872    .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
 873
 874 Setting Categories
 875 ^^^^^^^^^^^^^^^^^^
 876
 877 This example declares several tracing categories that are used to
 878 classify its tasks. When the program is executed, the tracing mechanism
 879 registers the resource utilization of hosts and links according to these
 880 categories. Recommended options:
 881 ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 882
 883 .. tabs::
 884
 885    .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
 886
 887 Master Workers tracing
 888 ^^^^^^^^^^^^^^^^^^^^^^
 889
 890 This is an augmented version of our basic master/worker example using
 891 several tracing features. It traces resource usage, sorted out in several
 892 categories; Trace marks and user variables are also used. Recommended
 893 options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
 894
 895 .. tabs::
 896
 897    .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
 898
 899    .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
 900
 901 Process migration tracing
 902 ^^^^^^^^^^^^^^^^^^^^^^^^^
 903
 904 This version is enhanced so that the process migrations can be displayed
 905 as arrows in a Gantt-chart visualization. Recommended options to that
 906 extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
 907
 908 .. tabs::
 909
 910    .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
 911
 912 Tracing user variables
 913 ----------------------
 914
 915 You can also attach your own variables to any resource described in the platform
 916 file. The following examples illustrate this feature.  They have to be run with
 917 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
 918
 919 Attaching variables to Hosts
 920 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 921
 922 .. tabs::
 923
 924    .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
 925
 926 Attaching variables to Links
 927 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 928
 929 The tricky part is that you have to know the name of the link you want to enhance with a variable.
 930
 931 .. tabs::
 932
 933    .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
 934
 935 Attaching variables to network routes
 936 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 937
 938 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
 939 knowing the name of each specific link.
 940
 941 .. tabs::
 942
 943    .. example-tab::  examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
 944
 945 ========================
 946 Larger SimGrid Exemplars
 947 ========================
 948
 949 This section contains application examples that are somewhat larger than the previous examples.
 950
 951 Classical examples
 952 ------------------
 953
 954 Token ring
 955 ^^^^^^^^^^
 956
 957 Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant.
 958
 959 .. tabs::
 960
 961    .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
 962
 963    .. example-tab:: examples/c/app-token-ring/app-token-ring.c
 964
 965 Master Workers
 966 ^^^^^^^^^^^^^^
 967
 968 Another good old example, where one Master acto$ has a bunch of tasks to dispatch to a set of several Worker actors.
 969 This example is used in the :ref:`SimGrid tutorial <usecase_simalgo>`.
 970
 971 .. tabs::
 972
 973    .. group-tab:: C++
 974
 975       This example comes in two equivalent variants, one where the actors
 976       are specified as simple functions (which is easier to understand for
 977       newcomers) and one where the actors are specified as classes (which is
 978       more powerful for the users wanting to build their own projects upon
 979       the example).
 980
 981       .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
 982          :language: cpp
 983
 984       .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
 985          :language: cpp
 986
 987    .. group-tab:: C
 988
 989       .. showfile:: examples/c/app-masterworker/app-masterworker.c
 990          :language: cpp
 991
 992 Data diffusion
 993 --------------
 994
 995 Bit Torrent
 996 ^^^^^^^^^^^
 997
 998 Classical protocol for Peer-to-Peer data diffusion.
 999
1000 .. tabs::
1001
1002    .. group-tab:: C++
1003
1004       .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
1005          :language: cpp
1006
1007       .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
1008          :language: cpp
1009
1010       .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
1011          :language: cpp
1012
1013    .. group-tab:: C
1014
1015       .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
1016          :language: cpp
1017
1018       .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
1019          :language: cpp
1020
1021       .. showfile:: examples/c/app-bittorrent/tracker.c
1022          :language: cpp
1023
1024 Chained Send
1025 ^^^^^^^^^^^^
1026
1027 Data broadcast over a ring of processes.
1028
1029 .. tabs::
1030
1031    .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
1032
1033    .. group-tab:: C
1034
1035       .. showfile:: examples/c/app-chainsend/chainsend.c
1036          :language: c
1037
1038       .. showfile:: examples/c/app-chainsend/broadcaster.c
1039          :language: c
1040
1041       .. showfile:: examples/c/app-chainsend/peer.c
1042          :language: c
1043
1044 Distributed Hash Tables (DHT)
1045 -----------------------------
1046
1047 Chord Protocol
1048 ^^^^^^^^^^^^^^
1049
1050 One of the most famous DHT protocol.
1051
1052 .. tabs::
1053
1054    .. group-tab:: C++
1055
1056       .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
1057          :language: cpp
1058
1059       .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
1060          :language: cpp
1061
1062 Kademlia
1063 ^^^^^^^^
1064
1065 Another well-known DHT protocol.
1066
1067 .. tabs::
1068
1069    .. group-tab:: C++
1070
1071       .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
1072          :language: cpp
1073
1074       .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
1075          :language: cpp
1076
1077       .. showfile:: examples/cpp/dht-kademlia/answer.cpp
1078          :language: cpp
1079
1080       .. showfile:: examples/cpp/dht-kademlia/node.cpp
1081          :language: cpp
1082
1083    .. group-tab:: C
1084
1085       .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
1086          :language: cpp
1087
1088       .. showfile:: examples/c/dht-kademlia/routing_table.c
1089          :language: cpp
1090
1091       .. showfile:: examples/c/dht-kademlia/answer.c
1092          :language: cpp
1093
1094       .. showfile:: examples/c/dht-kademlia/message.c
1095          :language: cpp
1096
1097       .. showfile:: examples/c/dht-kademlia/node.c
1098          :language: cpp
1099
1100 Pastry
1101 ^^^^^^
1102
1103 Yet another well-known DHT protocol.
1104
1105 .. tabs::
1106
1107    .. example-tab:: examples/c/dht-pastry/dht-pastry.c
1108
1109 .. _s4u_ex_clouds:
1110
1111 Simulating Clouds
1112 -----------------
1113
1114 Cloud basics
1115 ^^^^^^^^^^^^
1116
1117 This example starts some computations both on PMs and VMs and migrates some VMs around.
1118
1119 .. tabs::
1120
1121    .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
1122
1123    .. example-tab:: examples/c/cloud-simple/cloud-simple.c
1124
1125 Migrating VMs
1126 ^^^^^^^^^^^^^
1127
1128 This example shows how to migrate VMs between PMs.
1129
1130 .. tabs::
1131
1132    .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
1133
1134    .. example-tab:: examples/c/cloud-migration/cloud-migration.c
1135
1136 =======================
1137 Model-Related Examples
1138 =======================
1139
1140 ns-3 as a model
1141 ---------------
1142
1143 This simple ping-pong example demonstrates how to use the bindings to the Network
1144 Simulator. The most interesting is probably not the C++ files since
1145 they are unchanged from the other simulations, but the associated files,
1146 such as the platform file to see how to declare a platform to be used
1147 with the ns-3 bindings of SimGrid and the tesh file to see how to
1148 start a simulation in these settings.
1149
1150 .. tabs::
1151
1152    .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1153
1154    .. group-tab:: XML
1155
1156       **Platform files:**
1157
1158       .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1159          :language: xml
1160
1161 WiFi links
1162 ----------
1163
1164 This demonstrates how to declare a wifi zone in your platform and
1165 how to use it in your simulation. For that, you should have a link
1166 whose sharing policy is set to `WIFI`. Such links can have more
1167 than one bandwidth value (separated by commas), corresponding to
1168 the several SNR level of your wifi link.
1169
1170 In this case, SimGrid automatically switches to validated
1171 performance models of wifi networks, where the time is shared
1172 between users instead of the bandwidth for wired links (the
1173 corresponding publication is currently being written).
1174
1175 If your wifi link provides more than one SNR level, you can switch
1176 the level of a given host using
1177 :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1178 the first level is used.
1179
1180 .. tabs::
1181
1182    .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1183
1184    .. group-tab:: XML
1185
1186       **Platform files:**
1187
1188       .. showfile:: examples/platforms/wifi.xml
1189          :language: xml
1190
1191 ===============
1192 Plugin Examples
1193 ===============
1194
1195 It is possible to extend SimGrid without modifying its internals by
1196 attaching code to the existing signals and by adding extra data to the
1197 simulation objects through extensions. How to do that is not exactly
1198 documented yet, and you should look for examples in the src/plugins
1199 directory.
1200
1201 This section documents how the existing plugins can be used. Remember
1202 that you are very welcome to modify the plugins to fit your needs. It
1203 should be much easier than modifying the SimGrid kernel.
1204
1205 Monitoring the host load
1206 ------------------------
1207
1208 .. tabs::
1209
1210    .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1211
1212    .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1213
1214 Monitoring the link load
1215 ------------------------
1216
1217 .. tabs::
1218
1219    .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1220
1221 =======================
1222 Model-Checking Examples
1223 =======================
1224
1225 The model-checker can be used to exhaustively search for issues in the tested application. It must be activated at compile-time, but this
1226 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
1227
1228 Failing assert
1229 --------------
1230
1231 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
1232 This is wrong, and the model-checker correctly finds a counter-example to that assertion.
1233
1234 .. tabs::
1235
1236    .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp
1237
1238 .. |br| raw:: html
1239
1240    <br />