Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
convert S4U examples to sphinx
authorMartin Quinson <martin.quinson@loria.fr>
Thu, 20 Sep 2018 19:23:16 +0000 (21:23 +0200)
committerMartin Quinson <martin.quinson@loria.fr>
Thu, 20 Sep 2018 19:23:16 +0000 (21:23 +0200)
examples/s4u/README.doc [deleted file]
examples/s4u/README.rst [new file with mode: 0644]

index 9d20e2b..f9f93bb 100644 (file)
@@ -132,6 +132,10 @@ functions to simplify the code of actors.
 .. |Mutex| replace:: **Mutex**
 .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
+.. include:: ../../examples/s4u/README.rst
@@ -207,3 +211,7 @@ Activities Life cycle
 Sometimes, you want to change the setting of an activity before it even starts. 
+.. todo:: fill this section
diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc
deleted file mode 100644 (file)
index 3d564ca..0000000
+++ /dev/null
@@ -1,360 +0,0 @@
-// S4U (Simgrid for you) is the next interface of SimGrid, expected to be released with SimGrid 4.0.
-// Even if it is not completely rock stable yet, it may well already fit
-// your needs. You are welcome to try it and report any interface
-// glitches that you see. Be however warned that the interface may change
-// until the final release.  You will have to adapt your code on the way.
-// This file follows the Doxygen syntax to be included in the
-// documentation, but it should remain readable directly.
- @defgroup s4u_examples S4U examples
- @ingroup s4u_api
- @brief Find the S4U example fitting your needs in the archive.
-SimGrid comes with an extensive set of examples, documented on this
-page. Most of them only demonstrate one single feature, with some
-larger examplars listed below. 
-Each of these examples can be found in a subdirectory under
-examples/s4u in the archive. It contains the source code (also listed
-from this page), and the so-called tesh file containing how to call
-the binary obtained by compiling this example and also the expected
-output. Tesh files are used to turn each of our examples into an
-integration test. Some examples also contain other files, on need.
-A good way to bootstrap your own project is to copy and combine some
-of the provided examples to constitute the skeleton of what you plan
-to simulate.
-  - @ref s4u_ex_actors
-    - @ref s4u_ex_actors_start
-    - @ref s4u_ex_actors_synchro
-    - @ref s4u_ex_actors_replay
-  - @ref s4u_ex_activities
-    - @ref s4u_ex_activity_comm
-    - @ref s4u_ex_activity_exec
-    - @ref s4u_ex_activity_io
-    - @ref s4u_ex_activity_synchro
-  - @ref s4u_ex_platf
-  - @ref s4u_ex_energy
-  - @ref s4u_ex_tracing
-  - @ref s4u_ex_app
-    - @ref s4u_ex_app_data
-    - @ref s4u_ex_app_dht
-TODO: document here the examples about plugins
-@section s4u_ex_actors Actors: the active entities
-@subsection s4u_ex_actors_start Starting and stoping actors
-  - <b>Creating actors</b>. 
-    @ref examples/s4u/actor-create/s4u-actor-create.cpp @n
-    Most actors are started from the deployment XML file, but there is other methods.
-    This example show them all.
-  - <b>Kill actors</b>.
-    @ref examples/s4u/actor-kill/s4u-actor-kill.cpp @n
-    Actors can forcefully stop other actors with the @ref
-    simgrid::s4u::Actor::kill(void) or the @ref
-    simgrid::s4u::Actor::kill(aid_t) methods.
-  - <b>Controling the actor life cycle from the XML</b>.
-    @ref examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp 
-    @ref examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml 
-    @n
-    You can specify a start time and a kill time in the deployment file.
-  - <b>Daemonize actors</b>
-    @ref examples/s4u/actor-daemon/s4u-actor-daemon.cpp @n
-    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. 
-@subsection s4u_ex_actors_synchro Inter-actors interactions
-  - <b>Suspend and Resume actors</b>.
-    @ref examples/s4u/actor-suspend/s4u-actor-suspend.cpp @n
-    Actors can be suspended and resumed during their executions
-    thanks to the @ref simgrid::s4u::Actor::suspend and @ref simgrid::s4u::Actor::resume methods.
-  - <b>Migrating Actors</b>.
-    @ref examples/s4u/actor-migration/s4u-actor-migration.cpp @n
-    Actors can move or be moved from a host to another with the @ref
-    simgrid::s4u::this_actor::migrate() method.
-  - <b>Waiting for the termination of an actor</b> (joining on it)
-    @ref examples/s4u/actor-join/s4u-actor-join.cpp @n
-    The simgrid::s4u::Actor::join() method allows to block the current
-    actor until the end of the receiving actor.
-  - <b>Yielding to other actor</b>.
-    @ref examples/s4u/actor-yield/s4u-actor-yield.cpp@n
-    The simgrid::s4u::this_actor::yield() function interrupts the
-    execution of the current actor, leaving a chance to the other actors
-    that are ready to run at this timestamp.
-@subsection s4u_ex_actors_replay Traces Replay as a Workload
-This section details how to run trace-driven simulations. It is very
-handy when you want to test an algorithm or protocol that only react
-to external events. For example, many P2P protocols react to user
-requests, but do nothing if there is no such event.
-In such situations, you should write your protocol in C++, and separate
-the workload that you want to play onto your protocol in a separate
-text file. Declare a function handling each type of the events in your
-trace, register them using @ref xbt_replay_action_register in your
-main, and then run the simulation.
-Then, you can either have one trace file containing all your events,
-or a file per simulated process: the former may be easier to work
-with, but the second is more efficient on very large traces. Check
-also the tesh files in the example directories for details.
-  - <b>Communication replay</b>.
-    @ref examples/s4u/replay-comm/s4u-replay-comm.cpp @n
-    Presents a set of event handlers reproducing classical communication
-    primitives (asynchronous send/receive at the moment).
-  - <b>I/O replay</b>.
-    @ref examples/s4u/replay-storage/s4u-replay-storage.cpp @n
-    Presents a set of event handlers reproducing classical I/O
-    primitives (open, read, close).
-@section s4u_ex_activities Activities: the things that Actors do
-@subsection s4u_ex_activity_comm Communications on the network
- - <b>Basic asynchronous communications</b>. 
-   @ref examples/s4u/async-wait/s4u-async-wait.cpp @n
-   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 @ref simgrid::s4u::Mailbox::put_async and 
-   @ref simgrid::s4u::Comm::wait().
- - <b>Waiting for all communications in a set</b>.
-   @ref examples/s4u/async-waitall/s4u-async-waitall.cpp@n
-   The @ref simgrid::s4u::Comm::wait_all() function is useful when you want to block
-   until all activities in a given set have completed.
- - <b>Waiting for the first completed communication in a set</b>.
-   @ref examples/s4u/async-waitany/s4u-async-waitany.cpp@n
-   The @ref simgrid::s4u::Comm::wait_any() function is useful when you want to block
-   until one activity of the set completes, no matter which terminates
-   first.    
-@subsection s4u_ex_activity_exec Executions on the CPU
-  - <b>Basic execution</b>.
-    @ref examples/s4u/exec-basic/s4u-exec-basic.cpp @n
-    The computations done in your program are not reported to the
-    simulated world, unless you explicitely request the simulator to pause
-    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.
-  - <b>Asynchronous execution</b>.
-    @ref examples/s4u/exec-async/s4u-exec-async.cpp @n
-    You can start asynchronous executions, just like you would fire
-    background threads.
-  - <b>Monitoring asynchronous executions</b>.
-    @ref examples/s4u/exec-monitor/s4u-exec-monitor.cpp @n
-    This example shows how to start an asynchronous execution, and
-    monitor its status.
-  - <b>Remote execution</b>.
-    @ref examples/s4u/exec-remote/s4u-exec-remote.cpp @n
-    Before its start, you can change the host on which a given execution will occur.
-  - <b>Using Pstates on a host</b>
-    @ref examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp and 
-    @ref examples/platforms/energy_platform.xml @n
-    Show how define a set of pstatesfor a host in the XML, and how the current
-    pstate can be accessed/changed with @ref simgrid::s4u::Host::get_pstate_speed and @ref simgrid::s4u::Host::set_pstate.
-  - <b>Parallel tasks</b>
-    @ref examples/s4u/exec-ptask/s4u-exec-ptask.cpp@n
-    These objects are convenient abstractions of parallel
-    computational kernels that span over several machines. 
-@subsection s4u_ex_activity_io I/O on disks and files
-SimGrid provides two levels of abstraction to interact with the
-simulated storages. At the simplest level, you simply create read and
-write actions on the storage resources.
-  - <b>Access to raw storage devices</b>.
-    @ref examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp @n
-    This example illustrates how to simply read and write data on a
-    simulated storage resource.
-The FileSystem plugin provides a more detailed view, with the
-classical operations over files: open, move, unlink, and of course
-read and write. The file and disk sizes are also dealt with and can
-result in short reads and short write, as in reality.
-  - <b>File Management</b>. @ref examples/s4u/io-file-system/s4u-io-file-system.cpp @n
-    This example illustrates the use of operations on files
-    (read, write, seek, tell, unlink, ...).
-  - <b>Remote I/O</b>. 
-    @ref examples/s4u/io-file-remote/s4u-io-file-remote.cpp @n
-    I/O operations on files can also be done in a remote fashion, 
-    i.e. when the accessed disk is not mounted on the caller's host.
-@subsection s4u_ex_activity_synchro Classical synchronization objects
- - <b>Mutex: </b> @ref examples/s4u/mutex/s4u-mutex.cpp @n
-   Shows how to use simgrid::s4u::Mutex synchronization objects.
-@section s4u_ex_platf Interacting with the platform
- - <b>Retrieving the list of hosts matching a given criteria</b>.
-   @ref examples/s4u/engine-filtering/s4u-engine-filtering.cpp@n
-   Filtering the actors that match a given criteria is rather simple.
- - <b>User-defined properties</b>.
-   @ref examples/s4u/platform-properties/s4u-platform-properties.cpp and 
-   @ref examples/s4u/platform-properties/s4u-platform-properties_d.xml and
-   @ref examples/platforms/prop.xml @n
-   You can attach arbitrary information to most platform elements from
-   the XML file, and then interact with these values from your
-   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
-   your simulation. 
-   - simgrid::s4u::Actor::get_property() and simgrid::s4u::Actor::set_property()
-   - simgrid::s4u::Host::get_property() and simgrid::s4u::Host::set_property()
-   - simgrid::s4u::Link::get_property() and simgrid::s4u::Link::set_property()
-   - simgrid::s4u::NetZone::get_property() and simgrid::s4u::NetZone::set_property()
-@section s4u_ex_energy Simulating the energy consumption
-  - <b>Describing the energy profiles in the platform</b>
-    @ref examples/platforms/energy_platform.xml @n
-    This platform file contains the energy profile of each links and
-    hosts, which is necessary to get energy consumption predictions.
-    As usual, you should not trust our example, and you should strive
-    to double-check that your instanciation matches your target platform.
-  - <b>Consumption due to the CPU</b> 
-    @ref examples/s4u/energy-exec/s4u-energy-exec.cpp @n
-    This example shows how to retrieve the amount of energy consumed
-    by the CPU during computations, and the impact of the pstate.
-  - <b>Consumption due to the network</b>
-    @ref examples/s4u/energy-link/s4u-energy-link.cpp
-    This example shows how to retrieve and display the energy consumed
-    by the network during communications.
-  - <b>Modeling the shutdown and boot of hosts</b>
-    @ref examples/s4u/energy-boot/platform_boot.xml
-    @ref examples/s4u/energy-boot/s4u-energy-boot.cpp@n
-    Simple example of model of model for the energy consumption during
-    the host boot and shutdown periods.
-@section s4u_ex_tracing Tracing and visualization features
-Tracing can be activated by various configuration options which
-are illustrated in these example. See also the 
-@ref tracing_tracing_options "full list of options related to tracing".
-It is interesting to run the process-create example with the following
-options to see the task executions:
-  - <b>Platform tracing</b>.
-    @ref examples/s4u/trace-platform/s4u-trace-platform.cpp @n
-    This program is a toy example just loading the platform, so that
-    you can play with the platform visualization. Recommanded options:
-    @verbatim --cfg=tracing:yes --cfg=tracing/categorized:yes
-    @endverbatim
-@section s4u_ex_app Larger SimGrid examplars
-This section contains application examples that are somewhat larger
-than the previous examples.
-  - <b>Ping Pong</b>: @ref examples/s4u/app-pingpong/s4u-app-pingpong.cpp@n
-    This simple example just sends one message back and forth.
-    The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to 
-    the simulators (as detailed in Section @ref options). 
-  - <b>Token ring:</b> @ref examples/s4u/app-token-ring/s4u-app-token-ring.cpp @n
-    Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every
-    participant.
-  - <b>Master Workers:</b> @ref examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp 
-                           @ref examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp @n
-    Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
-    processes. This example comes in two equivalent variants, one
-    where the actors are specified as simple functions (which is easier to
-    understand for newcomers) and one where the actors are specified
-    as classes (which is more powerful for the users wanting to build
-    their own projects upon the example).
-@subsection s4u_ex_app_data Data diffusion
-  - <b>Bit Torrent</b> 
-    @ref examples/s4u/app-bittorrent/s4u-bittorrent.cpp@n
-    Classical protocol for Peer-to-Peer data diffusion.
-  - <b>Chained send</b> 
-    @ref examples/s4u/app-chainsend/s4u-app-chainsend.cpp@n
-    Data broadcast over a ring of processes.
-@subsection s4u_ex_app_dht Distributed Hash Tables (DHT)
-  - <b>Chord Protocol</b> 
-    @ref examples/s4u/dht-chord/s4u-dht-chord.cpp@n
-    One of the most famous DHT protocol.
-@example examples/s4u/actor-create/s4u-actor-create.cpp
-@example examples/s4u/actor-create/s4u-actor-create_d.xml
-@example examples/s4u/actor-daemon/s4u-actor-daemon.cpp
-@example examples/s4u/actor-join/s4u-actor-join.cpp
-@example examples/s4u/actor-kill/s4u-actor-kill.cpp
-@example examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp 
-@example examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml 
-@example examples/s4u/actor-migration/s4u-actor-migration.cpp
-@example examples/s4u/actor-suspend/s4u-actor-suspend.cpp
-@example examples/s4u/actor-yield/s4u-actor-yield.cpp
-@example examples/s4u/async-wait/s4u-async-wait.cpp
-@example examples/s4u/async-waitall/s4u-async-waitall.cpp
-@example examples/s4u/async-waitany/s4u-async-waitany.cpp
-@example examples/s4u/app-bittorrent/s4u-bittorrent.cpp
-@example examples/s4u/app-chainsend/s4u-app-chainsend.cpp
-@example examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp
-@example examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp
-@example examples/s4u/app-pingpong/s4u-app-pingpong.cpp
-@example examples/s4u/app-token-ring/s4u-app-token-ring.cpp
-@example examples/s4u/dht-chord/s4u-dht-chord.cpp
-@example examples/s4u/engine-filtering/s4u-engine-filtering.cpp
-@example examples/s4u/energy-boot/platform_boot.xml
-@example examples/s4u/energy-boot/s4u-energy-boot.cpp
-@example examples/s4u/energy-exec/s4u-energy-exec.cpp
-@example examples/s4u/energy-link/s4u-energy-link.cpp
-@example examples/s4u/exec-basic/s4u-exec-basic.cpp
-@example examples/s4u/exec-async/s4u-exec-async.cpp
-@example examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp
-@example examples/s4u/exec-monitor/s4u-exec-monitor.cpp
-@example examples/s4u/exec-ptask/s4u-exec-ptask.cpp
-@example examples/s4u/exec-remote/s4u-exec-remote.cpp 
-@example examples/s4u/io-file-system/s4u-io-file-system.cpp
-@example examples/s4u/io-file-remote/s4u-io-file-remote.cpp
-@example examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp
-@example examples/s4u/mutex/s4u-mutex.cpp
-@example examples/s4u/platform-properties/s4u-platform-properties.cpp
-@example examples/s4u/platform-properties/s4u-platform-properties_d.xml
-@example examples/s4u/replay-comm/s4u-replay-comm.cpp
-@example examples/s4u/replay-storage/s4u-replay-storage.cpp
-@example examples/s4u/trace-platform/s4u-trace-platform.cpp
-@example examples/platforms/energy_platform.xml
-@example examples/platforms/prop.xml
diff --git a/examples/s4u/README.rst b/examples/s4u/README.rst
new file mode 100644 (file)
index 0000000..d8e2522
--- /dev/null
@@ -0,0 +1,332 @@
+.. S4U (Simgrid for you) is the next interface of SimGrid, expected to be released with SimGrid 4.0.
+.. Even if it is not completely rock stable yet, it may well already fit
+.. your needs. You are welcome to try it and report any interface
+.. glitches that you see. Be however warned that the interface may change
+.. until the final release.  You will have to adapt your code on the way.
+.. This file follows the ReStructured syntax to be included in the
+.. documentation, but it should remain readable directly.
+S4U Examples
+SimGrid comes with an extensive set of examples, documented on this
+page. Most of them only demonstrate one single feature, with some
+larger examplars listed below. 
+Each of these examples can be found in a subdirectory under
+examples/s4u in the archive. It contains the source code (also listed
+from this page), and the so-called tesh file containing how to call
+the binary obtained by compiling this example and also the expected
+output. Tesh files are used to turn each of our examples into an
+integration test. Some examples also contain other files, on need.
+A good way to bootstrap your own project is to copy and combine some
+of the provided examples to constitute the skeleton of what you plan
+to simulate.
+Actors: the Active Entities
+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| `examples/s4u/actor-create/s4u-actor-create.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-create/s4u-actor-create.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>`_
+  - **Controling the actor life cycle from the XML:**
+    You can specify a start time and a kill time in the deployment
+    file.
+    |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp>`_
+    |br| `examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml>`_
+  - **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| `examples/s4u/actor-daemon/s4u-actor-daemon.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-daemon/s4u-actor-daemon.cpp>`_
+Inter-Actors Interactions
+  - **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>`_
+  - **Migrating Actors:**
+    Actors can move or be moved from a host to another with
+    :cpp:func:`simgrid::s4u::this_actor::migrate()`.
+    |br| `examples/s4u/actor-migration/s4u-actor-migration.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-migration/s4u-actor-migration.cpp>`_
+  - **Waiting for the termination of an actor:** (joining on it)
+    :cpp:func:`simgrid::s4u::Actor::join()` allows to block the current
+    actor until the end of the receiving actor.
+    |br| `examples/s4u/actor-join/s4u-actor-join.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-join/s4u-actor-join.cpp>`_
+  - **Yielding to other actor**.
+    The :cpp:func:`simgrid::s4u::this_actor::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| `examples/s4u/actor-yield/s4u-actor-yield.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/actor-yield/s4u-actor-yield.cpp>`_
+Traces Replay as a Workload
+This section details how to run trace-driven simulations. It is very
+handy when you want to test an algorithm or protocol that only react
+to external events. For example, many P2P protocols react to user
+requests, but do nothing if there is no such event.
+In such situations, you should write your protocol in C++, and separate
+the workload that you want to play onto your protocol in a separate
+text file. Declare a function handling each type of the events in your
+trace, register them using :cpp:func:`xbt_replay_action_register()` in
+your main, and then run the simulation.
+Then, you can either have one trace file containing all your events,
+or a file per simulated process: the former may be easier to work
+with, but the second is more efficient on very large traces. Check
+also the tesh files in the example directories for details.
+  - **Communication replay:**
+    Presents a set of event handlers reproducing classical communication
+    primitives (asynchronous send/receive at the moment).
+    |br| `examples/s4u/replay-comm/s4u-replay-comm.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/replay-comm/s4u-replay-comm.cpp>`_
+  - **I/O replay:**
+    Presents a set of event handlers reproducing classical I/O
+    primitives (open, read, close).
+    |br| `examples/s4u/replay-storage/s4u-replay-storage.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/replay-storage/s4u-replay-storage.cpp>`_
+Activities: what Actors do
+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>`_
+ - **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>`_
+ - **Waiting for the first completed communication in a set:**
+   The :cpp:func:`simgrid::s4u::Comm::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
+Executions on the CPU
+  - **Basic execution:**
+    The computations done in your program are not reported to the
+    simulated world, unless you explicitely request the simulator to pause
+    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| `examples/s4u/exec-basic/s4u-exec-basic.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-basic/s4u-exec-basic.cpp>`_
+  - **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>`_
+  - **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>`_
+  - **Parallel tasks:**
+    These objects are convenient abstractions of parallel
+    computational kernels that span over several machines. 
+    |br| `examples/s4u/exec-ptask/s4u-exec-ptask.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/exec-ptask/s4u-exec-ptask.cpp>`_
+I/O on Disks and Files
+SimGrid provides two levels of abstraction to interact with the
+simulated storages. At the simplest level, you simply create read and
+write actions on the storage resources.
+  - **Access to raw storage devices:**
+    This example illustrates how to simply read and write data on a
+    simulated storage resource.
+    |br| `examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp  <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp>`_
+The FileSystem plugin provides a more detailed view, with the
+classical operations over files: open, move, unlink, and of course
+read and write. The file and disk sizes are also dealt with and can
+result in short reads and short write, as in reality.
+  - **File Management:**
+    This example illustrates the use of operations on files
+    (read, write, seek, tell, unlink, etc).
+    |br| `examples/s4u/io-file-system/s4u-io-file-system.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/io-file-system/s4u-io-file-system.cpp>`_
+  - **Remote I/O:**
+    I/O operations on files can also be done in a remote fashion, 
+    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>`_
+Classical synchronization objects
+ - **Mutex:**
+   Shows how to use simgrid::s4u::Mutex synchronization objects.
+   |br| `examples/s4u/mutex/s4u-mutex.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/mutex/s4u-mutex.cpp>`_
+Interacting with the platform
+ - **Retrieving the list of hosts matching a given criteria:**
+   Shows how to filter the actors that match a given criteria.
+   |br| `examples/s4u/engine-filtering/s4u-engine-filtering.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/engine-filtering/s4u-engine-filtering.cpp>`_
+ - **User-defined properties:**
+   You can attach arbitrary information to most platform elements from
+   the XML file, and then interact with these values from your
+   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
+   your simulation.
+   - :cpp:func:`simgrid::s4u::Actor::get_property()` and :cpp:func:`simgrid::s4u::Actor::set_property()`
+   - :cpp:func:`simgrid::s4u::Host::get_property()` and :cpp:func:`simgrid::s4u::Host::set_property()`
+   - :cpp:func:`simgrid::s4u::Link::get_property()` and :cpp:func:`simgrid::s4u::Link::set_property()`
+   - :cpp:func:`simgrid::s4u::NetZone::get_property()` and :cpp:func:`simgrid::s4u::NetZone::set_property()`
+   |br| `examples/s4u/platform-properties/s4u-platform-properties.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/platform-properties/s4u-platform-properties.cpp>`_
+   |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>`_
+Energy Simulation
+  - **Describing the energy profiles in the platform:**
+    This platform file contains the energy profile of each links and
+    hosts, which is necessary to get energy consumption predictions.
+    As usual, you should not trust our example, and you should strive
+    to double-check that your instanciation matches your target platform.
+    |br| `examples/platforms/energy_platform.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/energy_platform.xml>`_
+  - **Consumption due to the CPU:** 
+    This example shows how to retrieve the amount of energy consumed
+    by the CPU during computations, and the impact of the pstate.
+    |br| `examples/s4u/energy-exec/s4u-energy-exec.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-exec/s4u-energy-exec.cpp>`_
+  - **Consumption due to the network:**
+    This example shows how to retrieve and display the energy consumed
+    by the network during communications.
+    |br| `examples/s4u/energy-link/s4u-energy-link.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-link/s4u-energy-link.cpp>`_
+  - **Modeling the shutdown and boot of hosts:**
+    Simple example of model of model for the energy consumption during
+    the host boot and shutdown periods.
+    |br| `examples/s4u/energy-boot/platform_boot.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/platform_boot.xml>`_
+    |br| `examples/s4u/energy-boot/s4u-energy-boot.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/energy-boot/s4u-energy-boot.cpp>`_
+Tracing and Visualizing
+Tracing can be activated by various configuration options which
+are illustrated in these example. See also the 
+:ref:`full list of options related to tracing <tracing_tracing_options>`.
+It is interesting to run the process-create example with the following
+options to see the task executions:
+  - **Platform Tracing:**
+    This program is a toy example just loading the platform, so that
+    you can play with the platform visualization. Recommanded options:
+    ``--cfg=tracing:yes --cfg=tracing/categorized:yes``
+    |br| `examples/s4u/trace-platform/s4u-trace-platform.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/trace-platform/s4u-trace-platform.cpp>`_
+Larger SimGrid Examplars
+This section contains application examples that are somewhat larger
+than the previous examples.
+  - **Ping Pong:**
+    This simple example just sends one message back and forth.
+    The tesh file laying in the directory show how to start the simulator binary, highlighting how to pass options to 
+    the simulators (as detailed in Section :ref:`options`). 
+    |br| `examples/s4u/app-pingpong/s4u-app-pingpong.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-pingpong/s4u-app-pingpong.cpp>`_
+  - **Token ring:**
+    Shows how to implement a classical communication pattern, where a
+    token is exchanged along a ring to reach every participant.
+    |br| `examples/s4u/app-token-ring/s4u-app-token-ring.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-token-ring/s4u-app-token-ring.cpp>`_
+  - **Master Workers:**
+    Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
+    processes. This example comes in two equivalent variants, one
+    where the actors are specified as simple functions (which is easier to
+    understand for newcomers) and one where the actors are specified
+    as classes (which is more powerful for the users wanting to build
+    their own projects upon the example).
+    |br| `examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-masterworkers/s4u-app-masterworkers-class.cpp>`_
+    |br| `examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-masterworkers/s4u-app-masterworkers-fun.cpp>`_
+Data diffusion
+  - **Bit Torrent:** 
+    Classical protocol for Peer-to-Peer data diffusion.
+    |br| `examples/s4u/app-bittorrent/s4u-bittorrent.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-bittorrent/s4u-bittorrent.cpp>`_
+  - **Chained Send:** 
+    Data broadcast over a ring of processes.
+    |br| `examples/s4u/app-chainsend/s4u-app-chainsend.cpp <https://framagit.org/simgrid/simgrid/tree/master/examples/s4u/app-chainsend/s4u-app-chainsend.cpp>`_
+Distributed Hash Tables (DHT)
+  - **Chord Protocol** 
+    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
+.. |br| raw:: html
+   <br />