+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.