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 ----------------------------
38 Most actors are started from the deployment XML file because this
39 is a :ref:`better scientific habit <howto_science>`, but you can
40 also create them directly from your code.
44 .. example-tab:: examples/cpp/actor-create/s4u-actor-create.cpp
46 You create actors either:
48 - Directly with :cpp:func:`simgrid::s4u::Actor::create`
49 - From XML with :cpp:func:`simgrid::s4u::Engine::register_actor` (if your actor is a class)
50 or :cpp:func:`simgrid::s4u::Engine::register_function` (if your actor is a function)
51 and then :cpp:func:`simgrid::s4u::Engine::load_deployment`
53 .. example-tab:: examples/python/actor-create/actor-create.py
55 You create actors either:
57 - Directly with :py:func:`simgrid.Actor.create()`
58 - From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
60 .. example-tab:: examples/c/actor-create/actor-create.c
62 You create actors either:
64 - Directly with :cpp:func:`sg_actor_create` followed by :cpp:func:`sg_actor_start`.
65 - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
67 .. example-tab:: examples/python/actor-create/actor-create_d.xml
69 The following file is used in both C++ and Python.
71 Reacting to actors' end
72 ^^^^^^^^^^^^^^^^^^^^^^^
74 You can attach callbacks to the end of actors. There are several ways of doing so, depending on whether you want to
75 attach your callback to a given actor and on how you define the end of a
76 given actor. User code probably wants to react to the termination of an actor
77 while some plugins want to react to the destruction (memory collection) of
82 .. example-tab:: examples/cpp/actor-exiting/s4u-actor-exiting.cpp
84 This example shows how to attach a callback to:
86 - the end of a specific actor: :cpp:func:`simgrid::s4u::Actor::on_exit()`
87 - the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
88 - the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
90 .. example-tab:: examples/c/actor-exiting/actor-exiting.c
92 This example shows how to attach a callback to the end of a specific actor with
93 :cpp:func:`sg_actor_on_exit()`.
98 Actors can forcefully stop other actors.
102 .. example-tab:: examples/cpp/actor-kill/s4u-actor-kill.cpp
104 See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
105 :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::Actor::on_exit`.
107 .. example-tab:: examples/python/actor-kill/actor-kill.py
109 See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
110 :py:func:`simgrid.this_actor.on_exit`.
112 .. example-tab:: examples/c/actor-kill/actor-kill.c
114 See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
116 Actors' life cycle from XML_reference
117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
119 You can specify a start time and a kill time in the deployment file.
123 .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime.cpp
125 This file is not really interesting: the important matter is in the XML file.
127 .. example-tab:: examples/cpp/actor-lifetime/s4u-actor-lifetime_d.xml
129 This demonstrates the ``start_time`` and ``kill_time`` attribute of the :ref:`pf_tag_actor` tag.
131 .. example-tab:: examples/python/actor-lifetime/actor-lifetime.py
133 This file is not really interesting: the important matter is in the XML file.
135 .. example-tab:: examples/c/actor-lifetime/actor-lifetime.c
137 This file is not really interesting: the important matter is in the XML file.
142 Some actors may be intended to simulate daemons that run in the background.
143 This example shows how to transform a regular
144 actor into a daemon that will be automatically killed once the simulation is over.
148 .. example-tab:: examples/cpp/actor-daemon/s4u-actor-daemon.cpp
150 See also :cpp:func:`simgrid::s4u::Actor::daemonize()` and :cpp:func:`simgrid::s4u::Actor::is_daemon()`.
152 .. example-tab:: examples/python/actor-daemon/actor-daemon.py
154 See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
156 .. example-tab:: examples/c/actor-daemon/actor-daemon.c
158 See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
160 Specifying the stack size
161 ^^^^^^^^^^^^^^^^^^^^^^^^^
163 The stack size can be specified by default on the command line,
164 globally by changing the configuration with :cpp:func:`simgrid::s4u::Engine::set_config`,
165 or for a specific actor using :cpp:func:`simgrid::s4u::Actor::set_stacksize` before its start.
169 .. example-tab:: examples/cpp/actor-stacksize/s4u-actor-stacksize.cpp
171 .. example-tab:: examples/c/actor-stacksize/actor-stacksize.c
173 Inter-Actors Interactions
174 -------------------------
176 See also the examples on :ref:`inter-actors communications
177 <s4u_ex_communication>` and the ones on :ref:`classical
178 synchronization objects <s4u_ex_IPC>`.
180 Suspending/resuming Actors
181 ^^^^^^^^^^^^^^^^^^^^^^^^^^
183 Actors can be suspended and resumed during their executions.
187 .. example-tab:: examples/cpp/actor-suspend/s4u-actor-suspend.cpp
189 See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
190 :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
191 :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
193 .. example-tab:: examples/python/actor-suspend/actor-suspend.py
195 See also :py:func:`simgrid.this_actor.suspend()`,
196 :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
197 :py:func:`simgrid.Actor.is_suspended()`.
199 .. example-tab:: examples/c/actor-suspend/actor-suspend.c
201 See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
202 :cpp:func:`sg_actor_is_suspended()`.
207 Actors can move or be moved from a host to another very easily. It amounts to setting them on a new host.
211 .. example-tab:: examples/cpp/actor-migrate/s4u-actor-migrate.cpp
213 See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
215 .. example-tab:: examples/python/actor-migrate/actor-migrate.py
217 See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
219 .. example-tab:: examples/c/actor-migrate/actor-migrate.c
221 See also :cpp:func:`sg_actor_set_host()`.
223 Waiting for the termination of an actor (joining on it)
224 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
226 You can block the current actor until the end of another actor.
230 .. example-tab:: examples/cpp/actor-join/s4u-actor-join.cpp
232 See also :cpp:func:`simgrid::s4u::Actor::join()`.
234 .. example-tab:: examples/python/actor-join/actor-join.py
236 See also :py:func:`simgrid.Actor.join()`.
238 .. example-tab:: examples/c/actor-join/actor-join.c
240 See also :cpp:func:`sg_actor_join`.
242 Yielding to other actors
243 ^^^^^^^^^^^^^^^^^^^^^^^^
245 The ```yield()``` function interrupts the execution of the current
246 actor, leaving a chance to the other actors that are ready to run
251 .. example-tab:: examples/cpp/actor-yield/s4u-actor-yield.cpp
253 See also :cpp:func:`simgrid::s4u::this_actor::yield()`.
255 .. example-tab:: examples/python/actor-yield/actor-yield.py
257 See also :py:func:`simgrid.this_actor.yield_()`.
259 .. example-tab:: examples/c/actor-yield/actor-yield.c
261 See also :cpp:func:`sg_actor_yield()`.
263 Traces Replay as a Workload
264 ---------------------------
266 This section details how to run trace-driven simulations. It is very
267 handy when you want to test an algorithm or protocol that only reacts
268 to external events. For example, many P2P protocols react to user
269 requests, but do nothing if there is no such event.
271 In such situations, you should write your protocol in C++, and separate
272 the workload that you want to play onto your protocol in a separate
273 text file. Declare a function handling each type of the events in your
274 trace, register them using :cpp:func:`xbt_replay_action_register()` in
275 your main, and then run the simulation.
277 Then, you can either have one trace file containing all your events,
278 or a file per simulated process: the former may be easier to work
279 with, but the second is more efficient on very large traces. Check
280 also the tesh files in the example directories for details.
285 Presents a set of event handlers reproducing classical communication primitives (asynchronous send/receive at the moment).
289 .. example-tab:: examples/cpp/replay-comm/s4u-replay-comm.cpp
294 Presents a set of event handlers reproducing classical I/O primitives (open, read, close).
298 .. example-tab:: examples/cpp/replay-io/s4u-replay-io.cpp
300 ==========================
301 Activities: what Actors do
302 ==========================
304 .. _s4u_ex_communication:
306 Communications on the Network
307 -----------------------------
312 This simple example just sends one message back and forth.
313 The tesh file laying in the directory shows how to start the simulator binary, highlighting how to pass options to
314 the simulators (as detailed in Section :ref:`options`).
318 .. example-tab:: examples/cpp/comm-pingpong/s4u-comm-pingpong.cpp
320 .. example-tab:: examples/c/comm-pingpong/comm-pingpong.c
323 Basic asynchronous communications
324 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
326 Illustrates how to have non-blocking communications, that are communications running in the background leaving the process
327 free to do something else during their completion.
331 .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
333 See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
335 .. example-tab:: examples/python/comm-wait/comm-wait.py
337 See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
339 .. example-tab:: examples/c/comm-wait/comm-wait.c
341 See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm_wait()`.
343 Waiting for communications with timeouts
344 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
346 This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
350 .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
352 See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
354 Suspending communications
355 ^^^^^^^^^^^^^^^^^^^^^^^^^
357 The ``suspend()`` and ``resume()`` functions block the progression of a given communication for a while and then unblock it.
358 ``is_suspended()`` returns whether that activity is currently blocked or not.
362 .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
364 See also :cpp:func:`simgrid::s4u::Activity::suspend()`
365 :cpp:func:`simgrid::s4u::Activity::resume()` and
366 :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
368 Waiting for all communications in a set
369 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
371 The ``wait_all()`` function is useful when you want to block until all activities in a given set have been completed.
375 .. example-tab:: examples/cpp/comm-waitall/s4u-comm-waitall.cpp
377 See also :cpp:func:`simgrid::s4u::Comm::wait_all()`.
379 .. example-tab:: examples/python/comm-waitall/comm-waitall.py
381 See also :py:func:`simgrid.Comm.wait_all()`.
383 .. example-tab:: examples/c/comm-waitall/comm-waitall.c
385 See also :cpp:func:`sg_comm_wait_all()`.
387 Waiting for the first completed communication in a set
388 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
390 The ``wait_any()`` function is useful when you want to block until one activity of the set completes, no matter which terminates first.
394 .. example-tab:: examples/cpp/comm-waitany/s4u-comm-waitany.cpp
396 See also :cpp:func:`simgrid::s4u::Comm::wait_any()`.
398 .. example-tab:: examples/python/comm-waitany/comm-waitany.py
400 See also :py:func:`simgrid.Comm.wait_any()`.
402 .. example-tab:: examples/c/comm-waitany/comm-waitany.c
404 See also :cpp:func:`sg_comm_wait_any`.
406 .. _s4u_ex_execution:
408 Executions on the CPU
409 ---------------------
414 The computations done in your program are not reported to the
415 simulated world unless you explicitly request the simulator to pause
416 the actor until a given amount of flops gets computed on its simulated
417 host. Some executions can be given a higher priority so that they
422 .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
424 See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
425 and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
427 .. example-tab:: examples/python/exec-basic/exec-basic.py
429 See also :py:func:`simgrid.this_actor.execute()`.
431 .. example-tab:: examples/c/exec-basic/exec-basic.c
433 See also :cpp:func:`void sg_actor_execute(double)`
434 and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
436 Asynchronous execution
437 ^^^^^^^^^^^^^^^^^^^^^^
439 You can start asynchronous executions, just like you would fire background threads.
443 .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
445 See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
446 :cpp:func:`simgrid::s4u::Activity::start()`,
447 :cpp:func:`simgrid::s4u::Activity::wait()`,
448 :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
449 :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
450 :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
451 :cpp:func:`simgrid::s4u::Activity::cancel()`.
453 .. example-tab:: examples/python/exec-async/exec-async.py
455 See also :py:func:`simgrid.this_actor.exec_init()`,
456 :py:func:`simgrid.Activity.start()`,
457 :py:func:`simgrid.Activity.wait()`,
458 :py:func:`simgrid.Activity.get_remaining()`,
459 :py:func:`simgrid.Exec.get_remaining_ratio()`,
460 :py:func:`simgrid.this_actor.exec_async()` and
461 :py:func:`simgrid.Activity.cancel()`.
463 .. example-tab:: examples/c/exec-async/exec-async.c
465 See also :cpp:func:`sg_actor_exec_init()`,
466 :cpp:func:`sg_exec_start()`,
467 :cpp:func:`sg_exec_wait()`,
468 :cpp:func:`sg_exec_get_remaining()`,
469 :cpp:func:`sg_exec_get_remaining_ratio()`,
470 :cpp:func:`sg_actor_exec_async()` and
471 :cpp:func:`sg_exec_cancel()`,
476 You can start executions on remote hosts, or even change the host on which they occur during their execution.
480 .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
482 See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
484 .. example-tab:: examples/python/exec-remote/exec-remote.py
486 See also :py:func:`simgrid.Exec.set_host()`.
488 .. example-tab:: examples/c/exec-remote/exec-remote.c
490 See also :cpp:func:`sg_exec_set_host()`.
495 These objects are convenient abstractions of parallel
496 computational kernels that span over several machines, such as a
497 PDGEM and the other ScaLAPACK routines. Note that this only works
498 with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
500 This example demonstrates several kinds of parallel tasks: regular
501 ones, communication-only (without computation), computation-only
502 (without communication), synchronization-only (neither
503 communication nor computation). It also shows how to reconfigure a
504 task after its start, to change the number of hosts it runs onto.
505 This allows simulating malleable tasks.
509 .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
511 See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
516 This example shows how to define a set of pstates in the XML. The current pstate
517 of a host can then be accessed and changed from the program.
521 .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
523 See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
525 .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
527 See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
529 .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
531 See also :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
533 .. example-tab:: examples/platforms/energy_platform.xml
537 I/O on Disks and Files
538 ----------------------
540 SimGrid provides two levels of abstraction to interact with the
541 simulated disks. At the simplest level, you simply create read and
542 write actions on the disk resources.
544 Access to raw disk devices
545 ^^^^^^^^^^^^^^^^^^^^^^^^^^
547 This example illustrates how to simply read and write data on a simulated disk resource.
551 .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
553 .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
555 .. example-tab:: examples/platforms/hosts_with_disks.xml
557 This shows how to declare disks in XML.
562 The FileSystem plugin provides a more detailed view, with the
563 classical operations over files: open, move, unlink, and of course,
564 read and write. The file and disk sizes are also dealt with and can
565 result in short reads and short writes, as in reality.
567 - **File Management:**
568 This example illustrates the use of operations on files
569 (read, write, seek, tell, unlink, etc).
573 .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
576 I/O operations on files can also be done remotely,
577 i.e. when the accessed disk is not mounted on the caller's host.
581 .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
583 .. example-tab:: examples/c/io-file-remote/io-file-remote.c
587 Classical synchronization objects
588 ---------------------------------
593 Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
597 .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
599 Condition variable: basic usage
600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
602 Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
606 .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
608 Condition variable: timeouts
609 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
611 Shows how to specify timeouts when blocking on condition variables.
615 .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
620 Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
624 .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
629 Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
633 .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
635 .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
637 =============================
638 Interacting with the Platform
639 =============================
641 User-defined properties
642 -----------------------
644 You can attach arbitrary information to most platform elements from the XML file, and then interact with these values from your
645 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
650 .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
652 - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
653 - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
654 - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
655 - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
657 .. example-tab:: examples/c/platform-properties/platform-properties.c
659 - :cpp:func:`sg_actor_get_property_value()`
660 - :cpp:func:`sg_host_get_property_value()` and :cpp:func:sg_host_set_property_value()`
661 - :cpp:func:`sg_zone_get_property_value()` and :cpp:func:`sg_zone_set_property_value()`
667 .. showfile:: examples/platforms/prop.xml
673 Retrieving the netzones matching given criteria
674 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
676 Shows how to filter the cluster netzones.
680 .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
682 Retrieving the list of hosts matching given criteria
683 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
685 Shows how to filter the actors that match given criteria.
689 .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
694 Specifying state profiles
695 ^^^^^^^^^^^^^^^^^^^^^^^^^
697 Shows how to specify when the resources must be turned off and on again, and how to react to such
698 failures in your code. See also :ref:`howto_churn`.
702 .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
704 .. example-tab:: examples/c/platform-failures/platform-failures.c
708 .. showfile:: examples/platforms/small_platform_failures.xml
711 .. showfile:: examples/platforms/profiles/jupiter_state.profile
713 .. showfile:: examples/platforms/profiles/fafard_state.profile
715 Specifying speed profiles
716 ^^^^^^^^^^^^^^^^^^^^^^^^^
718 Shows how to specify an external load to resources, variating their peak speed over time.
722 .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
726 .. showfile:: examples/platforms/small_platform_profile.xml
729 .. showfile:: examples/platforms/profiles/jupiter_speed.profile
731 .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
733 .. showfile:: examples/platforms/profiles/link1_latency.profile
742 Describing the energy profiles in the platform
743 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
745 The first platform file contains the energy profile of each link and host for a wired network, which is necessary to get energy consumption
746 predictions. The second platform file is the equivalent for a wireless network. As usual, you should not trust our example, and you should
747 strive to double-check that your instantiation matches your target platform.
753 .. showfile:: examples/platforms/energy_platform.xml
756 .. showfile:: examples/platforms/wifi_energy.xml
762 CPU energy consumption
763 ^^^^^^^^^^^^^^^^^^^^^^
765 This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate.
769 .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
771 .. example-tab:: examples/c/energy-exec/energy-exec.c
773 Wired network energy consumption
774 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
776 This example shows how to retrieve and display the energy consumed by the wired network during communications.
780 .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
782 WiFi network energy consumption
783 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
785 This example shows how to retrieve and display the energy consumed by the wireless network during communications.
789 .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
791 Modeling the shutdown and boot of hosts
792 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
794 Simple example of a model for the energy consumption during the host boot and shutdown periods.
798 .. example-tab:: examples/platforms/energy_boot.xml
800 .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
802 =======================
803 Tracing and Visualizing
804 =======================
806 Tracing can be activated by various configuration options which are illustrated in these examples. See also the
807 :ref:`full list of options related to tracing <tracing_tracing_options>`.
808 The following introduces some option sets of interest that you may want to pass to your simulators.
811 These tracing examples should be integrated in the examples to not duplicate the C++ files.
812 A full command line to see the result in the right tool (vite/FrameSoc) should be given along with some screenshots.
820 This program is a toy example just loading the platform so that you can play with the platform visualization. Recommended options:
821 ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
825 .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
830 This example declares several tracing categories that are used to
831 classify its tasks. When the program is executed, the tracing mechanism
832 registers the resource utilization of hosts and links according to these
833 categories. Recommended options:
834 ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
838 .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
840 Master Workers tracing
841 ^^^^^^^^^^^^^^^^^^^^^^
843 This is an augmented version of our basic master/worker example using
844 several tracing features. It traces resource usage, sorted out in several
845 categories; Trace marks and user variables are also used. Recommended
846 options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
850 .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
852 .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
854 Process migration tracing
855 ^^^^^^^^^^^^^^^^^^^^^^^^^
857 This version is enhanced so that the process migrations can be displayed
858 as arrows in a Gantt-chart visualization. Recommended options to that
859 extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
863 .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
865 Tracing user variables
866 ----------------------
868 You can also attach your own variables to any resource described in the platform
869 file. The following examples illustrate this feature. They have to be run with
870 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
872 Attaching variables to Hosts
873 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
877 .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
879 Attaching variables to Links
880 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
882 The tricky part is that you have to know the name of the link you want to enhance with a variable.
886 .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
888 Attaching variables to network routes
889 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
891 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
892 knowing the name of each specific link.
896 .. example-tab:: examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
898 ========================
899 Larger SimGrid Exemplars
900 ========================
902 This section contains application examples that are somewhat larger than the previous examples.
910 Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant.
914 .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
916 .. example-tab:: examples/c/app-token-ring/app-token-ring.c
921 Another good old example, where one Master acto$ has a bunch of tasks to dispatch to a set of several Worker actors.
922 This example is used in the :ref:`SimGrid tutorial <usecase_simalgo>`.
928 This example comes in two equivalent variants, one where the actors
929 are specified as simple functions (which is easier to understand for
930 newcomers) and one where the actors are specified as classes (which is
931 more powerful for the users wanting to build their own projects upon
934 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
937 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
942 .. showfile:: examples/c/app-masterworker/app-masterworker.c
951 Classical protocol for Peer-to-Peer data diffusion.
957 .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
960 .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
963 .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
968 .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
971 .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
974 .. showfile:: examples/c/app-bittorrent/tracker.c
980 Data broadcast over a ring of processes.
984 .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
988 .. showfile:: examples/c/app-chainsend/chainsend.c
991 .. showfile:: examples/c/app-chainsend/broadcaster.c
994 .. showfile:: examples/c/app-chainsend/peer.c
997 Distributed Hash Tables (DHT)
998 -----------------------------
1003 One of the most famous DHT protocol.
1009 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
1012 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
1018 Another well-known DHT protocol.
1024 .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
1027 .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
1030 .. showfile:: examples/cpp/dht-kademlia/answer.cpp
1033 .. showfile:: examples/cpp/dht-kademlia/node.cpp
1038 .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
1041 .. showfile:: examples/c/dht-kademlia/routing_table.c
1044 .. showfile:: examples/c/dht-kademlia/answer.c
1047 .. showfile:: examples/c/dht-kademlia/message.c
1050 .. showfile:: examples/c/dht-kademlia/node.c
1061 This example starts some computations both on PMs and VMs and migrates some VMs around.
1065 .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
1067 .. example-tab:: examples/c/cloud-simple/cloud-simple.c
1072 This example shows how to migrate VMs between PMs.
1076 .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
1078 .. example-tab:: examples/c/cloud-migration/cloud-migration.c
1080 =======================
1081 Model-Related Examples
1082 =======================
1087 This simple ping-pong example demonstrates how to use the bindings to the Network
1088 Simulator. The most interesting is probably not the C++ files since
1089 they are unchanged from the other simulations, but the associated files,
1090 such as the platform file to see how to declare a platform to be used
1091 with the ns-3 bindings of SimGrid and the tesh file to see how to
1092 start a simulation in these settings.
1096 .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1102 .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1108 This demonstrates how to declare a wifi zone in your platform and
1109 how to use it in your simulation. For that, you should have a link
1110 whose sharing policy is set to `WIFI`. Such links can have more
1111 than one bandwidth value (separated by commas), corresponding to
1112 the several SNR level of your wifi link.
1114 In this case, SimGrid automatically switches to validated
1115 performance models of wifi networks, where the time is shared
1116 between users instead of the bandwidth for wired links (the
1117 corresponding publication is currently being written).
1119 If your wifi link provides more than one SNR level, you can switch
1120 the level of a given host using
1121 :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1122 the first level is used.
1126 .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1132 .. showfile:: examples/platforms/wifi.xml
1139 It is possible to extend SimGrid without modifying its internals by
1140 attaching code to the existing signals and by adding extra data to the
1141 simulation objects through extensions. How to do that is not exactly
1142 documented yet, and you should look for examples in the src/plugins
1145 This section documents how the existing plugins can be used. Remember
1146 that you are very welcome to modify the plugins to fit your needs. It
1147 should be much easier than modifying the SimGrid kernel.
1149 Monitoring the host load
1150 ------------------------
1154 .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1156 .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1158 Monitoring the link load
1159 ------------------------
1163 .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1165 =======================
1166 Model-Checking Examples
1167 =======================
1169 The model-checker can be used to exhaustively search for issues in the tested application. It must be activated at compile-time, but this
1170 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
1175 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
1176 This is wrong, and the model-checker correctly finds a counter-example to that assertion.
1180 .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp