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
326 Basic asynchronous communications
327 ---------------------------------
329 Illustrates how to have non-blocking communications, that are communications running in the background leaving the process
330 free to do something else during their completion.
334 .. example-tab:: examples/cpp/comm-wait/s4u-comm-wait.cpp
336 See also :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`.
338 .. example-tab:: examples/python/comm-wait/comm-wait.py
340 See also :py:func:`simgrid.Mailbox.put_async()` and :py:func:`simgrid.Comm.wait()`.
342 .. example-tab:: examples/c/comm-wait/comm-wait.c
344 See also :cpp:func:`sg_mailbox_put_async()` and :cpp:func:`sg_comm_wait()`.
346 Waiting for communications with timeouts
347 ----------------------------------------
349 There is two ways of declaring timeouts in SimGrid. ``waituntil`` let you specify the deadline until when you want to wait, while
350 ``waitfor`` expects the maximal wait duration.
351 This example is very similar to the previous one, simply adding how to declare timeouts when waiting on asynchronous communication.
355 .. example-tab:: examples/cpp/comm-waituntil/s4u-comm-waituntil.cpp
357 See also :cpp:func:`simgrid::s4u::Activity::wait_until()` and :cpp:func:`simgrid::s4u::Comm::wait_for()`.
359 .. example-tab:: examples/python/comm-waituntil/comm-waituntil.py
361 See also :py:func:`simgrid.Comm.wait_until()`
363 .. _s4u_ex_mailbox_ready:
365 Checking for incoming communications
366 ------------------------------------
368 This example uses ``Mailbox.ready()`` to check for completed communications. When this function returns true, then at least a message
369 is arrived, so you know that ``Mailbox.get()`` will complete immediately. This is thus another way toward asynchronous communications.
373 .. example-tab:: examples/cpp/comm-ready/s4u-comm-ready.cpp
375 See also :cpp:func:`simgrid::s4u::Mailbox::ready()`.
377 .. example-tab:: examples/python/comm-ready/comm-ready.py
379 See also :py:func:`simgrid.Mailbox.ready()`
382 Suspending communications
383 -------------------------
385 The ``suspend()`` and ``resume()`` functions block the progression of a given communication for a while and then unblock it.
386 ``is_suspended()`` returns whether that activity is currently blocked or not.
390 .. example-tab:: examples/cpp/comm-suspend/s4u-comm-suspend.cpp
392 See also :cpp:func:`simgrid::s4u::Activity::suspend()`
393 :cpp:func:`simgrid::s4u::Activity::resume()` and
394 :cpp:func:`simgrid::s4u::Activity::is_suspended()`.
396 .. example-tab:: examples/python/comm-suspend/comm-suspend.py
398 See also :py:func:`simgrid.Comm.suspend()` and
399 :py:func:`simgrid.Comm.resume()`.
401 .. _s4u_ex_comm_failure:
403 Dealing with network failures
404 -----------------------------
406 This examples shows how to survive to network exceptions that occurs when a link is turned off, or when the actor with whom
407 you communicate fails because its host is turned off. In this case, any blocking operation such as ``put``, ``get`` or
408 ``wait`` will raise an exception that you can catch and react to. See also :ref:`howto_churn`,
409 :ref:`this example <s4u_ex_platform_state_profile>` on how to attach a state profile to hosts and
410 :ref:`that example <s4u_ex_exec_failure>` on how to react to host failures.
414 .. example-tab:: examples/cpp/comm-failure/s4u-comm-failure.cpp
416 .. example-tab:: examples/python/comm-failure/comm-failure.py
418 .. _s4u_ex_comm_host2host:
420 Direct host-to-host communication
421 ---------------------------------
423 This example demonstrates the direct communication mechanism, that allows to send data from one host to another without
424 relying on the mailbox mechanism.
428 .. example-tab:: examples/cpp/comm-host2host/s4u-comm-host2host.cpp
430 See also :cpp:func:`simgrid::s4u::Comm::sendto_init()` and :cpp:func:`simgrid::s4u::Comm::sendto_async()`.
432 .. example-tab:: examples/python/comm-host2host/comm-host2host.py
434 See also :py:func:`simgrid.Comm.sendto_init()` and :py:func:`simgrid.Comm.sendto_async()`.
436 .. _s4u_ex_execution:
438 Executions on the CPU
439 =====================
444 The computations done in your program are not reported to the
445 simulated world unless you explicitly request the simulator to pause
446 the actor until a given amount of flops gets computed on its simulated
447 host. Some executions can be given a higher priority so that they
452 .. example-tab:: examples/cpp/exec-basic/s4u-exec-basic.cpp
454 See also :cpp:func:`void simgrid::s4u::this_actor::execute(double)`
455 and :cpp:func:`void simgrid::s4u::this_actor::execute(double, double)`.
457 .. example-tab:: examples/python/exec-basic/exec-basic.py
459 See also :py:func:`simgrid.this_actor.execute()`.
461 .. example-tab:: examples/c/exec-basic/exec-basic.c
463 See also :cpp:func:`void sg_actor_execute(double)`
464 and :cpp:func:`void sg_actor_execute_with_priority(double, double)`.
466 Asynchronous execution
467 ----------------------
469 You can start asynchronous executions, just like you would fire background threads.
473 .. example-tab:: examples/cpp/exec-async/s4u-exec-async.cpp
475 See also :cpp:func:`simgrid::s4u::this_actor::exec_init()`,
476 :cpp:func:`simgrid::s4u::Activity::start()`,
477 :cpp:func:`simgrid::s4u::Activity::wait()`,
478 :cpp:func:`simgrid::s4u::Activity::get_remaining()`,
479 :cpp:func:`simgrid::s4u::Exec::get_remaining_ratio()`,
480 :cpp:func:`simgrid::s4u::this_actor::exec_async()` and
481 :cpp:func:`simgrid::s4u::Activity::cancel()`.
483 .. example-tab:: examples/python/exec-async/exec-async.py
485 See also :py:func:`simgrid.this_actor.exec_init()`,
486 :py:func:`simgrid.Exec.start()`,
487 :py:func:`simgrid.Exec.wait()`,
488 :py:attr:`simgrid.Exec.remaining`,
489 :py:attr:`simgrid.Exec.remaining_ratio`,
490 :py:func:`simgrid.this_actor.exec_async()` and
491 :py:func:`simgrid.Exec.cancel()`.
493 .. example-tab:: examples/c/exec-async/exec-async.c
495 See also :cpp:func:`sg_actor_exec_init()`,
496 :cpp:func:`sg_exec_start()`,
497 :cpp:func:`sg_exec_wait()`,
498 :cpp:func:`sg_exec_get_remaining()`,
499 :cpp:func:`sg_exec_get_remaining_ratio()`,
500 :cpp:func:`sg_actor_exec_async()` and
501 :cpp:func:`sg_exec_cancel()`,
506 You can start executions on remote hosts, or even change the host on which they occur during their execution.
507 This is naturally not very realistic, but it's something handy to have.
511 .. example-tab:: examples/cpp/exec-remote/s4u-exec-remote.cpp
513 See also :cpp:func:`simgrid::s4u::Exec::set_host()`.
515 .. example-tab:: examples/python/exec-remote/exec-remote.py
517 See also :py:attr:`simgrid.Exec.host`.
519 .. example-tab:: examples/c/exec-remote/exec-remote.c
521 See also :cpp:func:`sg_exec_set_host()`.
528 These objects are convenient abstractions of parallel
529 computational kernels that span over several machines, such as a
530 PDGEM and the other ScaLAPACK routines. Note that this only works
531 with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
533 This example demonstrates several kinds of parallel tasks: regular
534 ones, communication-only (without computation), computation-only
535 (without communication), synchronization-only (neither
536 communication nor computation). It also shows how to reconfigure a
537 task after its start, to change the number of hosts it runs onto.
538 This allows simulating malleable tasks.
542 .. example-tab:: examples/cpp/exec-ptask/s4u-exec-ptask.cpp
544 See also :cpp:func:`simgrid::s4u::this_actor::parallel_execute()`.
546 .. example-tab:: examples/python/exec-ptask/exec-ptask.py
548 See also :ref:`simgrid.this_actor.parallel_execute()`
550 Ptasks play well with the host energy plugin, as shown in this example.
551 There is not much new compared to the above ptask example or the
552 :ref:`examples about energy <s4u_ex_energy>`. It just works.
556 .. example-tab:: examples/cpp/energy-exec-ptask/s4u-energy-exec-ptask.cpp
558 .. example-tab:: examples/c/energy-exec-ptask/energy-exec-ptask.c
560 .. _s4u_ex_exec_failure:
562 Dealing with host failures
563 --------------------------
565 This examples shows how to survive to host failure exceptions that occur when an host is turned off. The actors do not get notified when the host
566 on which they run is turned off: they are just terminated in this case, and their ``on_exit()`` callback gets executed. For remote executions on
567 failing hosts however, any blocking operation such as ``exec`` or ``wait`` will raise an exception that you can catch and react to. See also
569 :ref:`this example <s4u_ex_platform_state_profile>` on how to attach a state profile to hosts, and
570 :ref:`that example <s4u_ex_comm_failure>` on how to react to network failures.
574 .. example-tab:: examples/cpp/exec-failure/s4u-exec-failure.cpp
581 This example shows how to define a set of pstates in the XML. The current pstate
582 of a host can then be accessed and changed from the program.
586 .. example-tab:: examples/cpp/exec-dvfs/s4u-exec-dvfs.cpp
588 See also :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
590 .. example-tab:: examples/c/exec-dvfs/exec-dvfs.c
592 See also :cpp:func:`sg_host_get_pstate_speed` and :cpp:func:`sg_host_set_pstate`.
594 .. example-tab:: examples/python/exec-dvfs/exec-dvfs.py
596 See also :py:func:`simgrid.Host.pstate_speed()` and :py:attr:`simgrid.Host.pstate`.
598 .. example-tab:: examples/platforms/energy_platform.xml
600 The important parts are in the :ref:`pf_tag_host` tag. The ``pstate`` attribute is the initial pstate while the ``speed`` attribute must
601 be a comma-separated list of values: the speed at each pstate. This platform file also describes the ``wattage_per_state`` and
602 ``wattage_off`` properties, that are used by the :ref:`plugin_host_energy` plugin.
606 I/O on Disks and Files
607 ======================
609 SimGrid provides two levels of abstraction to interact with the
610 simulated disks. At the simplest level, you simply create read and
611 write actions on the disk resources.
613 Access to raw disk devices
614 --------------------------
616 This example illustrates how to simply read and write data on a simulated disk resource.
620 .. example-tab:: examples/cpp/io-disk-raw/s4u-io-disk-raw.cpp
622 .. example-tab:: examples/c/io-disk-raw/io-disk-raw.c
624 .. example-tab:: examples/platforms/hosts_with_disks.xml
626 This shows how to declare disks in XML.
628 Asynchronous raw accesses
629 -------------------------
631 As most other activities, raw IO accesses can be used asynchronously, as illustrated in this example.
635 .. example-tab:: examples/cpp/io-async/s4u-io-async.cpp
640 The FileSystem plugin provides a more detailed view, with the
641 classical operations over files: open, move, unlink, and of course,
642 read and write. The file and disk sizes are also dealt with and can
643 result in short reads and short writes, as in reality.
645 - **File Management:**
646 This example illustrates the use of operations on files
647 (read, write, seek, tell, unlink, etc).
651 .. example-tab:: examples/cpp/io-file-system/s4u-io-file-system.cpp
653 .. example-tab:: examples/c/io-file-system/io-file-system.c
656 I/O operations on files can also be done remotely,
657 i.e. when the accessed disk is not mounted on the caller's host.
661 .. example-tab:: examples/cpp/io-file-remote/s4u-io-file-remote.cpp
663 .. example-tab:: examples/c/io-file-remote/io-file-remote.c
665 .. _s4u_ex_activityset:
670 Sometimes, you want to block on a set of activities, getting unblocked when any activity of the set unblocks, or waiting for the
671 completion of all activities in the set. This is where the ActivitySet become useful.
673 Waiting for all activities in a set
674 -----------------------------------
676 The ``wait_all()`` function is useful when you want to block until all activities in a given set have been completed.
680 .. example-tab:: examples/cpp/activityset-waitall/s4u-activityset-waitall.cpp
682 See also :cpp:func:`simgrid::s4u::ActivitySet::wait_all()`.
684 .. example-tab:: examples/python/activityset-waitall/activityset-waitall.py
686 See also :py:func:`simgrid.ActivitySet.wait_all()`.
688 .. example-tab:: examples/c/activityset-waitall/activityset-waitall.c
690 See also :cpp:func:`sg_activity_set_wait_all()`.
692 Waiting for all activities in a set (with timeout)
693 --------------------------------------------------
695 The ``wait_all_for()`` function is very similar to ``wait_all()`` but allows to specify a timeout.
699 .. example-tab:: examples/cpp/activityset-waitallfor/s4u-activityset-waitallfor.cpp
701 See also :cpp:func:`simgrid::s4u::ActivitySet::wait_all_for()`.
703 .. example-tab:: examples/python/activityset-waitallfor/activityset-waitallfor.py
705 See also :py:func:`simgrid.ActivitySet.wait_all_for()`.
707 .. example-tab:: examples/c/activityset-waitallfor/activityset-waitallfor.c
709 See also :cpp:func:`sg_activity_set_wait_all_for()`.
711 Waiting for the first completed activity in a set
712 -------------------------------------------------
714 The ``wait_any()`` blocks until one activity of the set completes, no matter which terminates first.
718 .. example-tab:: examples/cpp/activityset-waitany/s4u-activityset-waitany.cpp
720 See also :cpp:func:`simgrid::s4u::ActivitySet::wait_any()`.
722 .. example-tab:: examples/python/activityset-waitany/activityset-waitany.py
724 See also :py:func:`simgrid.ActivitySet.wait_any()`.
726 .. example-tab:: examples/c/activityset-waitany/activityset-waitany.c
728 See also :cpp:func:`sg_activity_set_wait_any`.
730 Testing whether at least one activity completed
731 -----------------------------------------------
733 The ``test_any()`` returns whether at least one activity of the set has completed.
737 .. example-tab:: examples/cpp/activityset-testany/s4u-activityset-testany.cpp
739 See also :cpp:func:`simgrid::s4u::ActivitySet::test_any()`.
741 .. example-tab:: examples/python/activityset-testany/activityset-testany.py
743 See also :py:func:`simgrid.ActivitySet.test_any()`.
745 .. example-tab:: examples/c/activityset-testany/activityset-testany.c
747 See also :cpp:func:`sg_activity_set_test_any`.
751 Dependencies between activities
752 ===============================
754 SimGrid makes it easy to express dependencies between activities, where a given activity cannot start until the completion of
755 all its predecessors. You can even have simulation not involving any actors, where the main thread (called maestro) creates and
756 schedules activities itself.
761 When you declare dependencies between two activities, the dependent will not actually start until all its dependencies complete,
762 as shown in the following examples. The first one declare dependencies between executions while the second one declare
763 dependencies between communications. You could declare such dependencies between arbitrary activities.
767 .. example-tab:: examples/cpp/exec-dependent/s4u-exec-dependent.cpp
771 .. example-tab:: examples/cpp/comm-dependent/s4u-comm-dependent.cpp
776 To actually start, an activity needs to be assigned to a given resource. This examples illustrates how an execution that is not
777 assigned will not actually start until being assigned. In some sense, activities' assignment can be seen as a specific
778 dependency that can withdraw their execution.
782 .. example-tab:: examples/cpp/exec-unassigned/s4u-exec-unassigned.cpp
784 Simple DAG of activities
785 ------------------------
787 This example shows how to create activities from the maestro directly without relying on an actor, organize the dependencies of
788 activities as a DAG (direct acyclic graph), and start them. Each activity will start as soon as its dependencies are fulfilled.
792 .. example-tab:: examples/cpp/dag-simple/s4u-dag-simple.cpp
794 DAG with communication
795 ----------------------
797 This is a little example showing how add communication activities to your DAG, representing inter-task data exchanges.
801 .. example-tab:: examples/cpp/dag-comm/s4u-dag-comm.cpp
806 This is a little example showing how add I/O activities to your DAG, representing disk buffers.
810 .. example-tab:: examples/cpp/dag-io/s4u-dag-io.cpp
812 Scheduling activities
813 ---------------------
815 This example illustrates a simple scheduling algorithm, where the activities are placed on the "most adapted" host. Of course, there is many way
816 to determine which host is the better fit for a given activity, and this example just uses a simple algorithm.
820 .. example-tab:: examples/cpp/dag-scheduling/s4u-dag-scheduling.cpp
822 Loading DAGs from file
823 ----------------------
825 There is currently two file formats that you can load directly in SimGrid, but writing another loader for your beloved format should not be difficult.
829 .. example-tab:: examples/cpp/dag-from-dax/s4u-dag-from-dax.cpp
833 .. showfile:: examples/cpp/dag-from-dax/smalldax.xml
838 .. example-tab:: examples/cpp/dag-from-dot/s4u-dag-from-dot.cpp
842 .. showfile:: examples/cpp/dag-from-dot/dag.dot
845 Simulating a time slice
846 -----------------------
848 When you declare activities, :cpp:func:`simgrid::s4u::Engine::run()` runs up to the point of time where an activity completes.
849 Sometimes, you want to give a maximal duration to simulate up to a given date at most, for example to inject a new activity at that time.
850 This example shows how to do it.
854 .. example-tab:: examples/cpp/engine-run-partial/s4u-engine-run-partial.cpp
859 This example shows how to deal with host or network failures while scheduling DAGs of activities.
863 .. example-tab:: examples/cpp/dag-failure/s4u-dag-failure.cpp
867 Classical synchronization objects
868 =================================
873 Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
877 .. example-tab:: examples/cpp/synchro-barrier/s4u-synchro-barrier.cpp
879 .. example-tab:: examples/python/synchro-barrier/synchro-barrier.py
881 Condition variable: basic usage
882 -------------------------------
884 Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
888 .. example-tab:: examples/cpp/synchro-condition-variable/s4u-synchro-condition-variable.cpp
890 Condition variable: timeouts
891 ----------------------------
893 Shows how to specify timeouts when blocking on condition variables.
897 .. example-tab:: examples/cpp/synchro-condition-variable-waituntil/s4u-synchro-condition-variable-waituntil.cpp
902 Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
906 .. example-tab:: examples/cpp/synchro-mutex/s4u-synchro-mutex.cpp
908 .. example-tab:: examples/python/synchro-mutex/synchro-mutex.py
913 Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
917 .. example-tab:: examples/cpp/synchro-semaphore/s4u-synchro-semaphore.cpp
919 .. example-tab:: examples/python/synchro-semaphore/synchro-semaphore.py
921 .. example-tab:: examples/c/synchro-semaphore/synchro-semaphore.c
923 *****************************
924 Interacting with the Platform
925 *****************************
927 User-defined properties
928 =======================
930 You can attach arbitrary information to most platform elements from the XML file, and then interact with these values from your
931 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
936 .. example-tab:: examples/cpp/platform-properties/s4u-platform-properties.cpp
938 - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
939 - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
940 - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
941 - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
943 .. example-tab:: examples/c/platform-properties/platform-properties.c
945 - :cpp:func:`sg_actor_get_property_value()`
946 - :cpp:func:`sg_host_get_property_value()` and :cpp:func:sg_host_set_property_value()`
947 - :cpp:func:`sg_zone_get_property_value()` and :cpp:func:`sg_zone_set_property_value()`
953 .. showfile:: examples/platforms/prop.xml
959 Retrieving the netzones matching given criteria
960 -----------------------------------------------
962 Shows how to filter the cluster netzones.
966 .. example-tab:: examples/cpp/routing-get-clusters/s4u-routing-get-clusters.cpp
968 Retrieving the list of hosts matching given criteria
969 ----------------------------------------------------
971 Shows how to filter the actors that match given criteria.
975 .. example-tab:: examples/cpp/engine-filtering/s4u-engine-filtering.cpp
980 .. _s4u_ex_platform_state_profile:
982 Specifying state profiles
983 -------------------------
985 Shows how to specify when the resources must be turned off and on again, and how to react to such
986 failures in your code. See also :ref:`howto_churn`,
987 :ref:`this example <s4u_ex_comm_failure>` on how to react to communication failures, and
988 :ref:`that example <s4u_ex_exec_failure>` on how to react to host failures.
992 .. example-tab:: examples/cpp/platform-failures/s4u-platform-failures.cpp
994 .. example-tab:: examples/c/platform-failures/platform-failures.c
996 .. example-tab:: examples/python/platform-failures/platform-failures.py
1000 .. showfile:: examples/platforms/small_platform_failures.xml
1003 .. showfile:: examples/platforms/profiles/jupiter_state.profile
1005 .. showfile:: examples/platforms/profiles/fafard_state.profile
1007 Specifying speed profiles
1008 -------------------------
1010 Shows how to specify an external load to resources, variating their peak speed over time.
1014 .. example-tab:: examples/cpp/platform-profile/s4u-platform-profile.cpp
1016 .. example-tab:: examples/python/platform-profile/platform-profile.py
1020 .. showfile:: examples/platforms/small_platform_profile.xml
1023 .. showfile:: examples/platforms/profiles/jupiter_speed.profile
1025 .. showfile:: examples/platforms/profiles/link1_bandwidth.profile
1027 .. showfile:: examples/platforms/profiles/link1_latency.profile
1029 Modifying the platform
1030 ======================
1032 Serializing communications
1033 --------------------------
1035 This example shows how to limit the amount of communications going through a given link.
1036 It is very similar to the other asynchronous communication examples, but messages get serialized by the platform.
1037 Without this call to ``Link::set_concurrency_limit(2)``, all messages would be received at the exact same timestamp since
1038 they are initiated at the same instant and are of the same size. But with this extra configuration to the link, at most 2
1039 messages can travel through the link at the same time.
1043 .. example-tab:: examples/cpp/platform-comm-serialize/s4u-platform-comm-serialize.cpp
1045 See also :cpp:func:`simgrid::s4u::Link::set_concurrency_limit()`.
1047 .. example-tab:: examples/python/platform-comm-serialize/platform-comm-serialize.py
1049 See also :py:func:`simgrid.Link.set_concurrency_limit()`.
1060 Describing the energy profiles in the platform
1061 ----------------------------------------------
1063 The first platform file contains the energy profile of each link and host for a wired network, which is necessary to get energy consumption
1064 predictions. The second platform file is the equivalent for a wireless network. As usual, you should not trust our example, and you should
1065 strive to double-check that your instantiation matches your target platform.
1071 .. showfile:: examples/platforms/energy_platform.xml
1074 .. showfile:: examples/platforms/wifi_energy.xml
1080 CPU energy consumption
1081 ----------------------
1083 This example shows how to retrieve the amount of energy consumed by the CPU during computations, and the impact of the pstate.
1087 .. example-tab:: examples/cpp/energy-exec/s4u-energy-exec.cpp
1089 .. example-tab:: examples/c/energy-exec/energy-exec.c
1091 Virtual machines consumption
1092 ----------------------------
1094 This example is very similar to the previous one, adding VMs to the picture.
1098 .. example-tab:: examples/cpp/energy-vm/s4u-energy-vm.cpp
1100 .. example-tab:: examples/c/energy-vm/energy-vm.c
1102 Wired network energy consumption
1103 --------------------------------
1105 This example shows how to retrieve and display the energy consumed by the wired network during communications.
1109 .. example-tab:: examples/cpp/energy-link/s4u-energy-link.cpp
1111 WiFi network energy consumption
1112 -------------------------------
1114 This example shows how to retrieve and display the energy consumed by the wireless network during communications.
1118 .. example-tab:: examples/cpp/energy-wifi/s4u-energy-wifi.cpp
1120 Modeling the shutdown and boot of hosts
1121 ---------------------------------------
1123 Simple example of a model for the energy consumption during the host boot and shutdown periods.
1127 .. example-tab:: examples/platforms/energy_boot.xml
1129 .. example-tab:: examples/cpp/energy-boot/s4u-energy-boot.cpp
1131 ***********************
1132 Tracing and Visualizing
1133 ***********************
1135 Tracing can be activated by various configuration options which are illustrated in these examples. See also the
1136 :ref:`full list of options related to tracing <tracing_tracing_options>`.
1137 The following introduces some option sets of interest that you may want to pass to your simulators.
1140 These tracing examples should be integrated in the examples to not duplicate the C++ files.
1141 A full command line to see the result in the right tool (vite/FrameSoc) should be given along with some screenshots.
1149 This program is a toy example just loading the platform so that you can play with the platform visualization. Recommended options:
1150 ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
1154 .. example-tab:: examples/cpp/trace-platform/s4u-trace-platform.cpp
1159 This example declares several tracing categories that are used to
1160 classify its tasks. When the program is executed, the tracing mechanism
1161 registers the resource utilization of hosts and links according to these
1162 categories. Recommended options:
1163 ``--cfg=tracing:yes --cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
1167 .. example-tab:: examples/cpp/trace-categories/s4u-trace-categories.cpp
1169 Master Workers tracing
1170 ----------------------
1172 This is an augmented version of our basic master/worker example using
1173 several tracing features. It traces resource usage, sorted out in several
1174 categories; Trace marks and user variables are also used. Recommended
1175 options: ``--cfg=tracing/categorized:yes --cfg=tracing/uncategorized:yes``
1179 .. example-tab:: examples/cpp/trace-masterworkers/s4u-trace-masterworkers.cpp
1181 .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
1183 Process migration tracing
1184 -------------------------
1186 This version is enhanced so that the process migrations can be displayed
1187 as arrows in a Gantt-chart visualization. Recommended options to that
1188 extend: ``--cfg=tracing:yes --cfg=tracing/actor:yes``
1192 .. example-tab:: examples/cpp/trace-process-migration/s4u-trace-process-migration.cpp
1194 Tracing user variables
1195 ======================
1197 You can also attach your own variables to any resource described in the platform
1198 file. The following examples illustrate this feature. They have to be run with
1199 the following options: ``--cfg=tracing:yes --cfg=tracing/platform:yes``
1201 Attaching variables to Hosts
1202 ----------------------------
1206 .. example-tab:: examples/cpp/trace-host-user-variables/s4u-trace-host-user-variables.cpp
1208 Attaching variables to Links
1209 ----------------------------
1211 The tricky part is that you have to know the name of the link you want to enhance with a variable.
1215 .. example-tab:: examples/cpp/trace-link-user-variables/s4u-trace-link-user-variables.cpp
1217 Attaching variables to network routes
1218 -------------------------------------
1220 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
1221 knowing the name of each specific link.
1225 .. example-tab:: examples/cpp/trace-route-user-variables/s4u-trace-route-user-variables.cpp
1227 ************************
1228 Larger SimGrid Exemplars
1229 ************************
1231 This section contains application examples that are somewhat larger than the previous examples.
1239 Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every participant.
1243 .. example-tab:: examples/cpp/app-token-ring/s4u-app-token-ring.cpp
1245 .. example-tab:: examples/c/app-token-ring/app-token-ring.c
1250 Another good old example, where one Master actor has a bunch of tasks to dispatch to a set of several Worker actors.
1251 This example is used in the :ref:`SimGrid tutorial <usecase_simalgo>`.
1257 This example comes in two equivalent variants, one where the actors
1258 are specified as simple functions (which is easier to understand for
1259 newcomers) and one where the actors are specified as classes (which is
1260 more powerful for the users wanting to build their own projects upon
1263 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-class.cpp
1266 .. showfile:: examples/cpp/app-masterworkers/s4u-app-masterworkers-fun.cpp
1271 .. showfile:: examples/c/app-masterworker/app-masterworker.c
1274 .. example-tab:: examples/python/app-masterworkers/app-masterworkers.py
1282 Classical protocol for Peer-to-Peer data diffusion.
1288 .. showfile:: examples/cpp/app-bittorrent/s4u-bittorrent.cpp
1291 .. showfile:: examples/cpp/app-bittorrent/s4u-peer.cpp
1294 .. showfile:: examples/cpp/app-bittorrent/s4u-tracker.cpp
1299 .. showfile:: examples/c/app-bittorrent/app-bittorrent.c
1302 .. showfile:: examples/c/app-bittorrent/bittorrent-peer.c
1305 .. showfile:: examples/c/app-bittorrent/tracker.c
1311 Data broadcast over a ring of processes.
1315 .. example-tab:: examples/cpp/app-chainsend/s4u-app-chainsend.cpp
1319 .. showfile:: examples/c/app-chainsend/chainsend.c
1322 .. showfile:: examples/c/app-chainsend/broadcaster.c
1325 .. showfile:: examples/c/app-chainsend/peer.c
1328 Distributed Hash Tables (DHT)
1329 =============================
1334 One of the most famous DHT protocol.
1340 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord.cpp
1343 .. showfile:: examples/cpp/dht-chord/s4u-dht-chord-node.cpp
1349 Another well-known DHT protocol.
1355 .. showfile:: examples/cpp/dht-kademlia/s4u-dht-kademlia.cpp
1358 .. showfile:: examples/cpp/dht-kademlia/routing_table.cpp
1361 .. showfile:: examples/cpp/dht-kademlia/answer.cpp
1364 .. showfile:: examples/cpp/dht-kademlia/node.cpp
1369 .. showfile:: examples/c/dht-kademlia/dht-kademlia.c
1372 .. showfile:: examples/c/dht-kademlia/routing_table.c
1375 .. showfile:: examples/c/dht-kademlia/answer.c
1378 .. showfile:: examples/c/dht-kademlia/message.c
1381 .. showfile:: examples/c/dht-kademlia/node.c
1387 Yet another well-known DHT protocol.
1391 .. example-tab:: examples/c/dht-pastry/dht-pastry.c
1401 This example starts some computations both on PMs and VMs and migrates some VMs around.
1405 .. example-tab:: examples/cpp/cloud-simple/s4u-cloud-simple.cpp
1407 .. example-tab:: examples/c/cloud-simple/cloud-simple.c
1412 This example shows how to migrate VMs between PMs.
1416 .. example-tab:: examples/cpp/cloud-migration/s4u-cloud-migration.cpp
1418 .. example-tab:: examples/c/cloud-migration/cloud-migration.c
1420 ***********************
1421 Model-Related Examples
1422 ***********************
1427 This simple ping-pong example demonstrates how to use the bindings to the Network
1428 Simulator. The most interesting is probably not the C++ files since
1429 they are unchanged from the other simulations, but the associated files,
1430 such as the platform file to see how to declare a platform to be used
1431 with the ns-3 bindings of SimGrid and the tesh file to see how to
1432 start a simulation in these settings.
1436 .. example-tab:: examples/cpp/network-ns3/s4u-network-ns3.cpp
1442 .. showfile:: examples/platforms/small_platform_one_link_routes.xml
1448 This demonstrates how to declare a wifi zone in your platform and
1449 how to use it in your simulation. For that, you should have a link
1450 whose sharing policy is set to `WIFI`. Such links can have more
1451 than one bandwidth value (separated by commas), corresponding to
1452 the several SNR level of your wifi link.
1454 In this case, SimGrid automatically switches to validated
1455 performance models of wifi networks, where the time is shared
1456 between users instead of the bandwidth for wired links (the
1457 corresponding publication is currently being written).
1459 If your wifi link provides more than one SNR level, you can switch
1460 the level of a given host using
1461 :cpp:func:`simgrid::s4u::Link::set_host_wifi_rate`. By default,
1462 the first level is used.
1466 .. example-tab:: examples/cpp/network-wifi/s4u-network-wifi.cpp
1472 .. showfile:: examples/platforms/wifi.xml
1475 You can also use the **ns-3 models on your wifi networks** as follows:
1479 .. example-tab:: examples/cpp/network-ns3-wifi/s4u-network-ns3-wifi.cpp
1485 .. showfile:: examples/platforms/wifi_ns3.xml
1493 It is possible to extend SimGrid without modifying its internals by
1494 attaching code to the existing signals and by adding extra data to the
1495 simulation objects through extensions. How to do that is not exactly
1496 documented yet, and you should look for examples in the src/plugins
1499 This section documents how the existing plugins can be used. Remember
1500 that you are very welcome to modify the plugins to fit your needs. It
1501 should be much easier than modifying the SimGrid kernel.
1503 Monitoring the host load
1504 ========================
1508 .. example-tab:: examples/cpp/plugin-host-load/s4u-plugin-host-load.cpp
1510 .. example-tab:: examples/c/plugin-host-load/plugin-host-load.c
1512 Monitoring the link load
1513 ========================
1517 .. example-tab:: examples/cpp/plugin-link-load/s4u-plugin-link-load.cpp
1519 ***********************
1520 Model-Checking Examples
1521 ***********************
1523 The model-checker can be used to exhaustively search for issues in the tested application. It must be activated at compile-time, but this
1524 mode is rather experimental in SimGrid (as of v3.25). We are working on it :)
1529 In this example, two actors send some data to a central server, which asserts that the messages are always received in the same order.
1530 This is wrong, and the model-checker correctly finds a counter-example to that assertion.
1534 .. example-tab:: examples/cpp/mc-failing-assert/s4u-mc-failing-assert.cpp