Actors: the Active Entities
===========================
+.. _s4u_ex_actors:
Starting and Stoping Actors
---------------------------
- **Creating actors:**
Most actors are started from the deployment XML file, but there is other methods.
This example show them all.
- |br| |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-create/s4u-actor-create.cpp>`_
- |br| |py| `examples/python/actor-create/actor-create.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-create/actor-create.py>`_
+ `examples/python/actor-create/actor-create_d.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-create/actor-create_d.xml>`_
+ - |cpp| `examples/s4u/actor-create/s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-create/s4u-actor-create.cpp>`_
+ - |py| `examples/python/actor-create/actor-create.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-create/actor-create.py>`_
+
+ - **React to the end of actors:**
+ You can attach a callback to the end of actors. There is two ways
+ of doing so, depending of whether you want your callback to be
+ executed when a specific actor ends (with ```this_actor::on_exit()```)
+ or whether it should be executed when any actor ends (with
+ ```Actor::on_termination()```) or when it gets destroyed (with
+ ```Actor::on_destruction()```)
+
+ - |cpp| `examples/s4u/actor-exiting/s4u-actor-exiting.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-exiting/s4u-actor-exiting.cpp>`_
+
- **Kill actors:**
- Actors can forcefully stop other actors with the
- :cpp:func:`void simgrid::s4u::Actor::kill(void)` or the
- :cpp:func:`void simgrid::s4u::Actor::kill(aid_t)` methods.
- |br| `examples/s4u/actor-kill/s4u-actor-kill.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-kill/s4u-actor-kill.cpp>`_
+ Actors can forcefully stop other actors.
+
+ - |cpp| `examples/s4u/actor-kill/s4u-actor-kill.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-kill/s4u-actor-kill.cpp>`_
+ :cpp:func:`void simgrid::s4u::Actor::kill(void)`,
+ :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
+ :cpp:func:`simgrid::s4u::this_actor::exit`.
+ - |py| `examples/python/actor-kill/actor-kill.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-kill/actor-kill.py>`_
+ :py:func:`simgrid.Actor.kill`,
+ :py:func:`simgrid.Actor.kill_all`,
+ :py:func:`simgrid.this_actor.exit`.
- **Controling the actor life cycle from the XML:**
You can specify a start time and a kill time in the deployment
- **Daemonize actors:**
Some actors may be intended to simulate daemons that run in background. This example show how to transform a regular
actor into a daemon that will be automatically killed once the simulation is over.
- |br| |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
- |br| |py| `examples/python/actor-daemon/actor-daemon.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-daemon/actor-daemon.py>`_
+
+ - |cpp| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
+ - |py| `examples/python/actor-daemon/actor-daemon.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-daemon/actor-daemon.py>`_
Inter-Actors Interactions
-------------------------
+See also the examples on :ref:`inter-actors communications
+<s4u_ex_communication>` and the ones on :ref:`classical
+synchronization objects <s4u_ex_IPC>`.
+
- **Suspend and Resume actors:**
- Actors can be suspended and resumed during their executions thanks
- to :cpp:func:`simgrid::s4u::Actor::suspend()` and
- :cpp:func:`simgrid::s4u::Actor::resume()`.
- |br| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-suspend/s4u-actor-suspend.cpp>`_
+ Actors can be suspended and resumed during their executions.
+
+ - |cpp| `examples/s4u/actor-suspend/s4u-actor-suspend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-suspend/s4u-actor-suspend.cpp>`_
+ :cpp:func:`simgrid::s4u::this_actor::suspend()`,
+ :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, :cpp:func:`simgrid::s4u::Actor::is_suspended()`.
+ - |py| `examples/python/actor-suspend/actor-suspend.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-suspend/actor-suspend.py>`_
+ :py:func:`simgrid.this_actor.suspend()`,
+ :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, :py:func:`simgrid.Actor.is_suspended()`.
- **Migrating Actors:**
Actors can move or be moved from a host to another very easily.
- |br| |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migrate/s4u-actor-migrate.cpp>`_
- :cpp:func:`simgrid::s4u::this_actor::migrate()` |cpp|
- |br| |py| `examples/python/actor-migrate/actor-migrate.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-migrate/actor-migrate.py>`_
- :py:func:`simgrid.this_actor.migrate()` |py|
+
+ - |cpp| `examples/s4u/actor-migrate/s4u-actor-migrate.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migrate/s4u-actor-migrate.cpp>`_
+ :cpp:func:`simgrid::s4u::this_actor::migrate()`
+ - |py| `examples/python/actor-migrate/actor-migrate.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-migrate/actor-migrate.py>`_
+ :py:func:`simgrid.this_actor.migrate()`
- **Waiting for the termination of an actor:** (joining on it)
You can block the current actor until the end of another actor.
- |br| |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
- :cpp:func:`simgrid::s4u::Actor::join()` |cpp|
- |br| |py| `examples/python/actor-join/actor-join.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-join/actor-join.py>`_
- :py:func:`simgrid.Actor.join()` |py|
+
+ - |cpp| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
+ :cpp:func:`simgrid::s4u::Actor::join()`
+ - |py| `examples/python/actor-join/actor-join.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-join/actor-join.py>`_
+ :py:func:`simgrid.Actor.join()`
- **Yielding to other actors**.
The ```yield()``` function interrupts the execution of the current
actor, leaving a chance to the other actors that are ready to run
- at this timestamp.
- |br| |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
- :cpp:func:`simgrid::s4u::this_actor::yield()` |cpp|
- |br| |py| `examples/python/actor-yield/actor-yield.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-yield/actor-yield.py>`_
- :py:func:`simgrid.this_actor.yield_()` |py|
+ at this timestamp.
+
+ - |cpp| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
+ :cpp:func:`simgrid::s4u::this_actor::yield()`
+ - |py| `examples/python/actor-yield/actor-yield.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/actor-yield/actor-yield.py>`_
+ :py:func:`simgrid.this_actor.yield_()`
Traces Replay as a Workload
---------------------------
Activities: what Actors do
==========================
+.. _s4u_ex_communication:
+
Communications on the Network
-----------------------------
- **Basic asynchronous communications:**
Illustrates how to have non-blocking communications, that are
communications running in the background leaving the process free
- to do something else during their completion. The main functions
- involved are :cpp:func:`simgrid::s4u::Mailbox::put_async()` and
- :cpp:func:`simgrid::s4u::Comm::wait()`.
- |br| `examples/s4u/async-wait/s4u-async-wait.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-wait/s4u-async-wait.cpp>`_
+ to do something else during their completion.
+
+ - |cpp| `examples/s4u/async-wait/s4u-async-wait.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-wait/s4u-async-wait.cpp>`_
+ :cpp:func:`simgrid::s4u::Mailbox::put_async()` and :cpp:func:`simgrid::s4u::Comm::wait()`
+ - |py| `examples/python/async-wait/async-wait.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-wait/async-wait.py>`_
+ :py:func:`simgrid.Mailbox.put_async()` :py:func:`simgrid.Comm.wait()`
- **Waiting for all communications in a set:**
- The :cpp:func:`simgrid::s4u::Comm::wait_all()` function is useful
- when you want to block until all activities in a given set have
- completed.
- |br| `examples/s4u/async-waitall/s4u-async-waitall.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitall/s4u-async-waitall.cpp>`_
+ The `wait_all()` function is useful when you want to block until
+ all activities in a given set have completed.
+
+ - |cpp| `examples/s4u/async-waitall/s4u-async-waitall.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitall/s4u-async-waitall.cpp>`_
+ :cpp:func:`simgrid::s4u::Comm::wait_all()`
+ - |py| `examples/python/async-waitall/async-waitall.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-waitall/async-waitall.py>`_
+ :py:func:`simgrid.Comm.wait_all()`
- **Waiting for the first completed communication in a set:**
- The :cpp:func:`simgrid::s4u::Comm::wait_any()` function is useful
+ The `wait_any()` function is useful
when you want to block until one activity of the set completes, no
- matter which terminates first.
- |br| `examples/s4u/async-waitany/s4u-async-waitany.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitany/s4u-async-waitany.cpp>`_
-
-.. todo:: add the `ready` example here
+ matter which terminates first.
+
+ - |cpp| `examples/s4u/async-waitany/s4u-async-waitany.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/async-waitany/s4u-async-waitany.cpp>`_
+ :cpp:func:`simgrid::s4u::Comm::wait_any()`
+ - |py| `examples/python/async-waitany/async-waitany.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/async-waitany/async-waitany.py>`_
+ :py:func:`simgrid.Comm.wait_any()`
+
+.. todo:: review the `ready` and `waituntil` examples and add them here.
.. _s4u_ex_execution:
the actor until a given amount of flops gets computed on its simulated
host. Some executions can be given an higher priority so that they
get more resources.
- |br| |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
- |br| |py| `examples/python/exec-basic/exec-basic.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-basic/exec-basic.py>`_
+
+ - |cpp| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
+ - |py| `examples/python/exec-basic/exec-basic.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-basic/exec-basic.py>`_
- **Asynchronous execution:**
You can start asynchronous executions, just like you would fire
background threads.
- |br| `examples/s4u/exec-async/s4u-exec-async.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-async/s4u-exec-async.cpp>`_
- - **Monitoring asynchronous executions:**
- This example shows how to start an asynchronous execution, and
- monitor its status.
- |br| `examples/s4u/exec-monitor/s4u-exec-monitor.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-monitor/s4u-exec-monitor.cpp>`_
+ - |cpp| `examples/s4u/exec-async/s4u-exec-async.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-async/s4u-exec-async.cpp>`_
+ - |py| `examples/python/exec-async/exec-async.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-async/exec-async.py>`_
- **Remote execution:**
- Before its start, you can change the host on which a given execution will occur.
- |br| `examples/s4u/exec-remote/s4u-exec-remote.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-remote/s4u-exec-remote.cpp>`_
-
- - **Using Pstates on a host:**
- Shows how define a set of pstatesfor a host in the XML, and how the current
- pstate can be accessed/changed with :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
- |br| `examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp>`_
- |br| `examples/platforms/energy_platform.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/energy_platform.xml>`_
+ You can start executions on remote hosts, or even change the host
+ on which they occur during their execution.
+
+ - |cpp| `examples/s4u/exec-remote/s4u-exec-remote.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-remote/s4u-exec-remote.cpp>`_
+ - |py| `examples/python/exec-remote/exec-remote.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-remote/exec-remote.py>`_
- **Parallel executions:**
These objects are convenient abstractions of parallel
computational kernels that span over several machines, such as a
- PDGEM and the other ScaLAPACK routines.
+ PDGEM and the other ScaLAPACK routines. Note that this only works
+ with the "ptask_L07" host model (``--cfg=host/model:ptask_L07``).
|br| `examples/s4u/exec-ptask/s4u-exec-ptask.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-ptask/s4u-exec-ptask.cpp>`_
+
+ - **Using Pstates on a host:**
+ `examples/platforms/energy_platform.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/energy_platform.xml>`_
+ shows how define a set of pstates in the XML. The current pstate
+ of an host can then be accessed and changed from the program.
+
+ - |cpp| `examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp>`_
+ :cpp:func:`simgrid::s4u::Host::get_pstate_speed` and :cpp:func:`simgrid::s4u::Host::set_pstate`.
+ - |py| `examples/python/exec-dvfs/exec-dvfs.py <https://framagit.org/simgrid/simgrid/tree/master/examples/python/exec-dvfs/exec-dvfs.py>`_
+ :py:func:`Host.get_pstate_speed` and :py:func:`Host.set_pstate`.
I/O on Disks and Files
----------------------
i.e. when the accessed disk is not mounted on the caller's host.
|br| `examples/s4u/io-file-remote/s4u-io-file-remote.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-file-remote/s4u-io-file-remote.cpp>`_
+.. _s4u_ex_IPC:
+
Classical synchronization objects
---------------------------------
|br| `examples/s4u/platform-properties/s4u-platform-properties_d.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/platform-properties/s4u-platform-properties_d.xml>`_
|br| `examples/platforms/prop.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/prop.xml>`_
+ - **Specifying state profiles:** shows how to specify when the
+ resources must be turned off and on again, and how to react to such
+ failures in your code.
+
+ |br| `examples/platforms/small_platform_failures.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/small_platform_failures.xml>`_
+ |br| The state profiles in `examples/platforms/profiles <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/profiles>`_
+
+ - **Specifying speed profiles:** shows how to specify an external
+ load to resources, variating their peak speed over time.
+
+ |br| `examples/platforms/small_platform_profile.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/small_platform_profile.xml>`_
+ |br| The speed, bandwidth and latency profiles in `examples/platforms/profiles <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/profiles>`_
+
=================
Energy Simulation
=================
One of the most famous DHT protocol.
|br| `examples/s4u/dht-chord/s4u-dht-chord.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/dht-chord/s4u-dht-chord.cpp>`_
-.. TODO:: document here the examples about plugins
+.. _s4u_ex_clouds:
+
+Simulating Clouds
+-----------------
+
+ - **Cloud basics**
+ This example starts some computations both on PMs and VMs, and
+ migrates some VMs around.
+ |br| `examples/s4u/cloud-simple/s4u-cloud-simple.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/cloud-simple/s4u-cloud-simple.cpp>`_
+
+.. TODO:: document here the examples about clouds and plugins
+
+=======================
+Model-Checking Examples
+=======================
+
+The model-checker can be used to exhaustively search for issues in the
+tested application. It must be activated at compile time, but this
+mode is rather experimental in SimGrid (as of v3.22). You should not
+enable it unless you really want to formally verify your applications:
+SimGrid is slower and maybe less robust when MC is enabled.
+
+ - **Failing assert**
+ In this example, two actors send some data to a central server,
+ which asserts that the messages are always received in the same order.
+ This is obviously wrong, and the model-checker correctly finds a
+ counter-example to that assertion.
+ |br| `examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/mc-failing-assert/s4u-mc-failing-assert.cpp>`_
.. |br| raw:: html
