1 .. S4U (Simgrid for you) is the modern interface of SimGrid, which new project should use.
3 .. This file follows the ReStructured syntax to be included in the
4 .. documentation, but it should remain readable directly.
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.
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.
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
28 ===========================
29 Actors: the Active Entities
30 ===========================
32 Starting and Stopping Actors
33 ----------------------------
35 .. _s4u_ex_actors_create:
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.
46 .. example-tab:: examples/cpp/actor-create/s4u-actor-create.cpp
48 You create actors either:
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`
55 .. example-tab:: examples/python/actor-create/actor-create.py
57 You create actors either:
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()`
62 .. example-tab:: examples/c/actor-create/actor-create.c
64 You create actors either:
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`.
69 .. example-tab:: examples/python/actor-create/actor-create_d.xml
71 The following file is used in both C++ and Python.
73 Reacting to actors' end
74 ^^^^^^^^^^^^^^^^^^^^^^^
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
84 .. example-tab:: examples/cpp/actor-exiting/s4u-actor-exiting.cpp
86 This example shows how to attach a callback to:
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`
92 .. example-tab:: examples/c/actor-exiting/actor-exiting.c
94 This example shows how to attach a callback to the end of a specific actor with
95 :cpp:func:`sg_actor_on_exit()`.
100 Actors can forcefully stop other actors.
104 .. example-tab:: examples/cpp/actor-kill/s4u-actor-kill.cpp
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`.
109 .. example-tab:: examples/python/actor-kill/actor-kill.py
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`.
114 .. example-tab:: examples/c/actor-kill/actor-kill.c
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`.
118 Actors' life cycle from XML_reference
119 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
121 You can specify a start time and a kill time in the deployment file.
125 .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime.cpp
127 This file is not really interesting: the important matter is in the XML file.
129 .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime_d.xml
131 This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
133 .. example-tab:: examples/python/actor-lifetime/actor-lifetime.py
135 This file is not really interesting: the important matter is in the XML file.
137 .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
139 This file is not really interesting: the important matter is in the XML file.
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.
150 .. example-tab:: examples/cpp/actor-daemon/s4u-actor-daemon.cpp
152 See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
154 .. example-tab:: examples/python/actor-daemon/actor-daemon.py
156 See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
158 .. example-tab:: examples/c/actor-daemon/actor-daemon.c
160 See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
162 Specifying the stack size
163 ^^^^^^^^^^^^^^^^^^^^^^^^^
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.
171 .. example-tab:: examples/cpp/actor-stacksize/s4u-actor-stacksize.cpp
173 .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
175 Inter-Actors Interactions
176 -------------------------
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>`.
182 Suspending/resuming Actors
183 ^^^^^^^^^^^^^^^^^^^^^^^^^^
185 Actors can be suspended and resumed during their executions.
189 .. example-tab:: examples/cpp/actor-suspend/s4u-actor-suspend.cpp
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()`.
195 .. example-tab:: examples/python/actor-suspend/actor-suspend.py
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()`.
201 .. example-tab:: examples/c/actor-suspend/actor-suspend.c
203 See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
204 :cpp:func:`sg_actor_is_suspended()`.
209 Actors can move or be moved from a host to another very easily. It amounts to setting them on a new host.
213 .. example-tab:: examples/cpp/actor-migrate/s4u-actor-migrate.cpp
215 See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
217 .. example-tab:: examples/python/actor-migrate/actor-migrate.py
219 See also :py:attr:`simgrid.Actor.host`.
221 .. example-tab:: examples/c/actor-migrate/actor-migrate.c
223 See also :cpp:func:`sg_actor_set_host()`.
225 Waiting for the termination of an actor (joining on it)
226 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
228 You can block the current actor until the end of another actor.
232 .. example-tab:: examples/cpp/actor-join/s4u-actor-join.cpp
234 See also :cpp:func:`simgrid::s4u::Actor::join()`.
236 .. example-tab:: examples/python/actor-join/actor-join.py
238 See also :py:func:`simgrid.Actor.join()`.
240 .. example-tab:: examples/c/actor-join/actor-join.c
242 See also :cpp:func:`sg_actor_join`.
244 Yielding to other actors
245 ^^^^^^^^^^^^^^^^^^^^^^^^
247 The ```yield()``` function interrupts the execution of the current
248 actor, leaving a chance to the other actors that are ready to run
253 .. example-tab:: examples/cpp/actor-yield/s4u-actor-yield.cpp
255 See also :cpp:func:`simgrid::s4u::this_actor::yield()`.
257 .. example-tab:: examples/python/actor-yield/actor-yield.py
259 See also :py:func:`simgrid.this_actor.yield_()`.
261 .. example-tab:: examples/c/actor-yield/actor-yield.c
263 See also :cpp:func:`sg_actor_yield()`.
265 Traces Replay as a Workload
266 ---------------------------
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.
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.
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.
287 Presents a set of event handlers reproducing classical communication primitives (asynchronous send/receive at the moment).
291 .. example-tab:: examples/cpp/replay-comm/s4u-replay-comm.cpp
296 Presents a set of event handlers reproducing classical I/O primitives (open, read, close).
300 .. example-tab:: examples/cpp/replay-io/s4u-replay-io.cpp
302 ==========================
303 Activities: what Actors do
304 ==========================
306 .. _s4u_ex_communication:
308 Communications on the Network
309 -----------------------------
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`).
320 .. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp
322 .. example-tab:: examples/python/comm-pingpong/comm-pingpong.py
324 .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
327 Basic asynchronous communications
328 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
335 .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
337 See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
339 .. example-tab:: examples/python/comm-wait/comm-wait.py
341 See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
343 .. example-tab:: examples/c/comm-wait/comm-wait.c
345 See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm_wait()`.
347 Waiting for communications with timeouts
348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
350 This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
354 .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
356 See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
358 .. example-tab:: examples/python/comm-waituntil/comm-waituntil.py
360 See also :py:func:`simgrid.Comm.wait_until()`
362 Suspending communications
363 ^^^^^^^^^^^^^^^^^^^^^^^^^
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.
370 .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
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()`.
376 .. example-tab:: examples/python/comm-suspend/comm-suspend.py
378 See also :py:func:`simgrid.Comm::suspend()` and
379 :py:func:`simgrid.Comm.resume()`.
381 Waiting for all communications in a set
382 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
384 The ``wait_all()`` function is useful when you want to block until all activities in a given set have been completed.
388 .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
390 See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
392 .. example-tab:: examples/python/comm-waitall/comm-waitall.py
394 See also :py:func:`simgrid.Comm.wait_all()`.
396 .. example-tab:: examples/c/comm-waitall/comm-waitall.c
398 See also :cpp:func:`sg_comm_wait_all()`.
400 Waiting for the first completed communication in a set
401 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
403 The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first.
407 .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
409 See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
411 .. example-tab:: examples/python/comm-waitany/comm-waitany.py
413 See also :py:func:`simgrid.Comm.wait_any()`.
415 .. example-tab:: examples/c/comm-waitany/comm-waitany.c
417 See also :cpp:func:`sg_comm_wait_any`.
419 Testing whether at least one communication completed
420 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
422 The ``test_any()`` returns whether at least one activity of the set has completed, or -1.
426 .. example-tab:: examples/cpp/comm-testany/s4u-comm-testany.cpp
428 See also :cpp:func:`simgrid::s4u::Comm::test_any()`.
430 .. example-tab:: examples/python/comm-testany/comm-testany.py
432 See also :py:func:`simgrid.Comm.test_any()`.
434 .. _s4u_ex_execution:
436 Executions on the CPU
437 ---------------------
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
450 .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
452 See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
453 and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
455 .. example-tab:: examples/python/exec-basic/exec-basic.py
457 See also :py:func:`simgrid.this_actor.execute()`.
459 .. example-tab:: examples/c/exec-basic/exec-basic.c
461 See also :cpp:func:`void sg_actor_execute(double)`
462 and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
464 Asynchronous execution
465 ^^^^^^^^^^^^^^^^^^^^^^
467 You can start asynchronous executions, just like you would fire background threads.
471 .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
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()`.
481 .. example-tab:: examples/python/exec-async/exec-async.py
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()`.
491 .. example-tab:: examples/c/exec-async/exec-async.c
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()`,
504 You can start executions on remote hosts, or even change the host on which they occur during their execution.
508 .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
510 See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
512 .. example-tab:: examples/python/exec-remote/exec-remote.py
514 See also :py:attr:`simgrid.Exec.host`.
516 .. example-tab:: examples/c/exec-remote/exec-remote.c
518 See also :cpp:func:`sg_exec_set_host()`.
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``).
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.
539 .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
541 See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
543 .. example-tab:: examples/python/exec-ptask/exec-ptask.py
545 See also :ref:`simgrid.this_actor.parallel_execute()`
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.
555 .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
557 See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
559 .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
561 See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
563 .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
565 See also :py:func:`simgrid.Host.pstate_speed()` and :py:attr:`simgrid.Host.pstate`.
567 .. example-tab:: examples/platforms/energy_platform.xml
571 I/O on Disks and Files
572 ----------------------
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.
578 Access to raw disk devices
579 ^^^^^^^^^^^^^^^^^^^^^^^^^^
581 This example illustrates how to simply read and write data on a simulated disk resource.
585 .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
587 .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
589 .. example-tab:: examples/platforms/hosts_with_disks.xml
591 This shows how to declare disks in XML.
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.
601 - **File Management:**
602 This example illustrates the use of operations on files
603 (read, write, seek, tell, unlink, etc).
607 .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
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.
615 .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
617 .. example-tab:: examples/c/io-file-remote/io-file-remote.c
621 Classical synchronization objects
622 ---------------------------------
627 Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
631 .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
633 .. example-tab:: examples/python/synchro-barrier/synchro-barrier.py
635 Condition variable: basic usage
636 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
638 Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
642 .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
644 Condition variable: timeouts
645 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
647 Shows how to specify timeouts when blocking on condition variables.
651 .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
656 Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
660 .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
662 .. example-tab:: examples/python/synchro-mutex/synchro-mutex.py
667 Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
671 .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
673 .. example-tab:: examples/python/synchro-semaphore/synchro-semaphore.py
675 .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
677 =============================
678 Interacting with the Platform
679 =============================
681 User-defined properties
682 -----------------------
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
690 .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
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()`
697 .. example-tab:: examples/c/platform-properties/platform-properties.c
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()`
707 .. showfile:: examples/platforms/prop.xml
713 Retrieving the netzones matching given criteria
714 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
716 Shows how to filter the cluster netzones.
720 .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
722 Retrieving the list of hosts matching given criteria
723 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
725 Shows how to filter the actors that match given criteria.
729 .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
734 Specifying state profiles
735 ^^^^^^^^^^^^^^^^^^^^^^^^^
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`.
742 .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
744 .. example-tab:: examples/c/platform-failures/platform-failures.c
746 .. example-tab:: examples/python/platform-failures/platform-failures.py
750 .. showfile:: examples/platforms/small_platform_failures.xml
753 .. showfile:: examples/platforms/profiles/jupiter_state.profile
755 .. showfile:: examples/platforms/profiles/fafard_state.profile
757 Specifying speed profiles
758 ^^^^^^^^^^^^^^^^^^^^^^^^^
760 Shows how to specify an external load to resources, variating their peak speed over time.
764 .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
766 .. example-tab:: examples/python/platform-profile/platform-profile.py
770 .. showfile:: examples/platforms/small_platform_profile.xml
773 .. showfile:: examples/platforms/profiles/jupiter_speed.profile
775 .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
777 .. showfile:: examples/platforms/profiles/link1_latency.profile
786 Describing the energy profiles in the platform
787 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
797 .. showfile:: examples/platforms/energy_platform.xml
800 .. showfile:: examples/platforms/wifi_energy.xml
806 CPU energy consumption
807 ^^^^^^^^^^^^^^^^^^^^^^
809 This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate.
813 .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
815 .. example-tab:: examples/c/energy-exec/energy-exec.c
817 Virtual machines consumption
818 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
820 This example is very similar to the previous one, adding VMs to the picture.
824 .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp
826 .. example-tab:: examples/c/energy-vm/energy-vm.c
828 Wired network energy consumption
829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
831 This example shows how to retrieve and display the energy consumed by the wired network during communications.
835 .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
837 WiFi network energy consumption
838 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
840 This example shows how to retrieve and display the energy consumed by the wireless network during communications.
844 .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
846 Modeling the shutdown and boot of hosts
847 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
849 Simple example of a model for the energy consumption during the host boot and shutdown periods.
853 .. example-tab:: examples/platforms/energy_boot.xml
855 .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
857 =======================
858 Tracing and Visualizing
859 =======================
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.
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.
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``
880 .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
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``
893 .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
895 Master Workers tracing
896 ^^^^^^^^^^^^^^^^^^^^^^
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``
905 .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
907 .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
909 Process migration tracing
910 ^^^^^^^^^^^^^^^^^^^^^^^^^
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``
918 .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
920 Tracing user variables
921 ----------------------
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``
927 Attaching variables to Hosts
928 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
932 .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
934 Attaching variables to Links
935 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
937 The tricky part is that you have to know the name of the link you want to enhance with a variable.
941 .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
943 Attaching variables to network routes
944 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
951 .. example-tab:: examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
953 ========================
954 Larger SimGrid Exemplars
955 ========================
957 This section contains application examples that are somewhat larger than the previous examples.
965 Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant.
969 .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
971 .. example-tab:: examples/c/app-token-ring/app-token-ring.c
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>`.
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
989 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
992 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
997 .. showfile:: examples/c/app-masterworker/app-masterworker.c
1000 .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
1008 Classical protocol for Peer-to-Peer data diffusion.
1014 .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
1017 .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
1020 .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
1025 .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
1028 .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
1031 .. showfile:: examples/c/app-bittorrent/tracker.c
1037 Data broadcast over a ring of processes.
1041 .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
1045 .. showfile:: examples/c/app-chainsend/chainsend.c
1048 .. showfile:: examples/c/app-chainsend/broadcaster.c
1051 .. showfile:: examples/c/app-chainsend/peer.c
1054 Distributed Hash Tables (DHT)
1055 -----------------------------
1060 One of the most famous DHT protocol.
1066 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
1069 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
1075 Another well-known DHT protocol.
1081 .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
1084 .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
1087 .. showfile:: examples/cpp/dht-kademlia/answer.cpp
1090 .. showfile:: examples/cpp/dht-kademlia/node.cpp
1095 .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
1098 .. showfile:: examples/c/dht-kademlia/routing_table.c
1101 .. showfile:: examples/c/dht-kademlia/answer.c
1104 .. showfile:: examples/c/dht-kademlia/message.c
1107 .. showfile:: examples/c/dht-kademlia/node.c
1113 Yet another well-known DHT protocol.
1117 .. example-tab:: examples/c/dht-pastry/dht-pastry.c
1127 This example starts some computations both on PMs and VMs and migrates some VMs around.
1131 .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
1133 .. example-tab:: examples/c/cloud-simple/cloud-simple.c
1138 This example shows how to migrate VMs between PMs.
1142 .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
1144 .. example-tab:: examples/c/cloud-migration/cloud-migration.c
1146 =======================
1147 Model-Related Examples
1148 =======================
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.
1162 .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1168 .. showfile:: examples/platforms/small_platform_one_link_routes.xml
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.
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).
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.
1192 .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1198 .. showfile:: examples/platforms/wifi.xml
1205 It is possible to extend SimGrid without modifying its internals by
1206 attaching code to the existing signals and by adding extra data to the
1207 simulation objects through extensions. How to do that is not exactly
1208 documented yet, and you should look for examples in the src/plugins
1211 This section documents how the existing plugins can be used. Remember
1212 that you are very welcome to modify the plugins to fit your needs. It
1213 should be much easier than modifying the SimGrid kernel.
1215 Monitoring the host load
1216 ------------------------
1220 .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1222 .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1224 Monitoring the link load
1225 ------------------------
1229 .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1231 =======================
1232 Model-Checking Examples
1233 =======================
1235 The model-checker can be used to exhaustively search for issues in the tested application. It must be activated at compile-time, but this
1236 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
1241 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
1242 This is wrong, and the model-checker correctly finds a counter-example to that assertion.
1246 .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp