.. documentation, but it should remain readable directly.
-S4U Examples
-************
+Examples
+********
SimGrid comes with an extensive set of examples, documented on this
page. Most of them only demonstrate one single feature, with some
of the provided examples to constitute the skeleton of what you plan
to simulate.
+.. _s4u_ex_actors:
+
===========================
Actors: the Active Entities
===========================
-.. _s4u_ex_actors:
-
Starting and Stoping Actors
---------------------------
- Directly with :py:func:`simgrid.Actor.create()`
- From XML with :py:func:`simgrid.Engine.register_actor()` and then :py:func:`simgrid.Engine.load_deployment()`
+ .. example-tab:: examples/c/actor-create/actor-create.c
+
+ You create actors either:
+
+ - Directly with :cpp:func:`sg_actor_create()` followed by :cpp:func:`sg_actor_start`.
+ - From XML with :cpp:func:`simgrid_register_function` and then :cpp:func:`simgrid_load_deployment`.
+
.. example-tab:: examples/python/actor-create/actor-create_d.xml
The following file is used in both C++ and Python.
- the end of any actor: :cpp:member:`simgrid::s4u::Actor::on_termination()`
- the destruction of any actor: :cpp:member:`simgrid::s4u::Actor::on_destruction()`
+ .. example-tab:: examples/c/actor-exiting/actor-exiting.c
+
+ This example shows how to attach a callback to the end of a specific actor with
+ :cpp:func:`sg_actor_on_exit()`.
+
- **Kill actors:**
Actors can forcefully stop other actors.
-
+
.. tabs::
-
+
.. example-tab:: examples/s4u/actor-kill/s4u-actor-kill.cpp
-
+
See also :cpp:func:`void simgrid::s4u::Actor::kill(void)`, :cpp:func:`void simgrid::s4u::Actor::kill_all()`,
- :cpp:func:`simgrid::s4u::this_actor::exit`.
+ :cpp:func:`simgrid::s4u::this_actor::exit`, :cpp:func:`simgrid::s4u::this_actor::on_exit`.
.. example-tab:: examples/python/actor-kill/actor-kill.py
- See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`.
+ See also :py:func:`simgrid.Actor.kill`, :py:func:`simgrid.Actor.kill_all`, :py:func:`simgrid.this_actor.exit`,
+ :py:func:`simgrid.this_actor.on_exit`.
+
+ .. example-tab:: examples/c/actor-kill/actor-kill.c
+
+ See also :cpp:func:`sg_actor_kill`, :cpp:func:`sg_actor_kill_all`, :cpp:func:`sg_actor_exit`, :cpp:func:`sg_actor_on_exit`.
- **Controling the actor life cycle from the XML:**
You can specify a start time and a kill time in the deployment file.
See also :py:func:`simgrid.Actor.daemonize()` and :py:func:`simgrid.Actor.is_daemon()`.
+ .. example-tab:: examples/c/actor-daemon/actor-daemon.c
+
+ See also :cpp:func:`sg_actor_daemonize` and :cpp:func:`sg_actor_is_daemon`.
+
Inter-Actors Interactions
-------------------------
.. example-tab:: examples/s4u/actor-suspend/s4u-actor-suspend.cpp
See also :cpp:func:`simgrid::s4u::this_actor::suspend()`,
- :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()` and
+ :cpp:func:`simgrid::s4u::Actor::suspend()`, :cpp:func:`simgrid::s4u::Actor::resume()`, and
:cpp:func:`simgrid::s4u::Actor::is_suspended()`.
.. example-tab:: examples/python/actor-suspend/actor-suspend.py
See also :py:func:`simgrid.this_actor.suspend()`,
- :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()` and
+ :py:func:`simgrid.Actor.suspend()`, :py:func:`simgrid.Actor.resume()`, and
:py:func:`simgrid.Actor.is_suspended()`.
+ .. example-tab:: examples/c/actor-suspend/actor-suspend.c
+
+ See also :cpp:func:`sg_actor_suspend()`, :cpp:func:`sg_actor_resume()`, and
+ :cpp:func:`sg_actor_is_suspended()`.
+
- **Migrating Actors:**
- Actors can move or be moved from a host to another very easily.
+ Actors can move or be moved from a host to another very easily. It amount to setting them on a new host.
.. tabs::
.. example-tab:: examples/s4u/actor-migrate/s4u-actor-migrate.cpp
- See also :cpp:func:`simgrid::s4u::this_actor::migrate()` and :cpp:func:`simgrid::s4u::Actor::migrate()`.
+ See also :cpp:func:`simgrid::s4u::this_actor::set_host()` and :cpp:func:`simgrid::s4u::Actor::set_host()`.
.. example-tab:: examples/python/actor-migrate/actor-migrate.py
- See also :py:func:`simgrid.this_actor.migrate()` and :py:func:`simgrid.Actor.migrate()`.
+ See also :py:func:`simgrid.this_actor.set_host()` and :py:func:`simgrid.Actor.set_host()`.
+
+ .. example-tab:: examples/c/actor-migrate/actor-migrate.c
+
+ See also :cpp:func:`sg_actor_set_host()`.
- **Waiting for the termination of an actor:** (joining on it)
You can block the current actor until the end of another actor.
See also :py:func:`simgrid.Actor.join()`.
+ .. example-tab:: examples/c/actor-join/actor-join.c
+
+ See also :cpp:func:`sg_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
See also :py:func:`simgrid.this_actor.yield_()`.
+ .. example-tab:: examples/c/actor-yield/actor-yield.c
+
+ See also :cpp:func:`sg_actor_yield()`.
+
Traces Replay as a Workload
---------------------------
.. example-tab:: examples/python/async-waitany/async-waitany.py
See also :py:func:`simgrid.Comm.wait_any()`.
+
+ .. example-tab:: examples/c/async-waitany/async-waitany.c
+
+ See also :cpp:func:`sg_comm_wait_any`.
.. _s4u_ex_execution:
.. example-tab:: examples/platforms/energy_platform.xml
+.. _s4u_ex_disk_io:
+
I/O on Disks and Files
----------------------
Classical synchronization objects
---------------------------------
- - **Mutex:**
- Shows how to use simgrid::s4u::Mutex synchronization objects.
+ - **Barrier:**
+ Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
.. tabs::
- .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
+ .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
- - **Barrier:**
- Shows how to use simgrid::s4u::Barrier synchronization objects.
+ - **Condition variable:**
+ Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
.. tabs::
- .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
+ .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
+
+ - **Mutex:**
+ Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
+
+ .. tabs::
+
+ .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
- **Semaphore:**
- Shows how to use simgrid::s4u::Semaphore synchronization objects.
+ Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
.. tabs::