@ingroup s4u_api
@brief Find the S4U example fitting your needs in the archive.
- - @ref s4u_ex_basics
- - @ref s4u_ex_activities
+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_synchro
- - @ref s4u_ex_actions
+ - @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_io
- @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
-@section s4u_ex_basics Basics of SimGrid simulation
+@subsection s4u_ex_actors_start Starting and stoping actors
- - <b>Creating actors:</b> @ref examples/s4u/actor-create/s4u-actor-create.cpp and
- @ref examples/s4u/actor-create/s4u-actor-create_d.xml \n
- Shows how to start your actors to populate your simulation.
+ - <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>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>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) method.
- - <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>Kill actors (other function)</b>.
+ @ref examples/s4u/actor-kill-pid/s4u-actor-kill-pid.cpp \n
+ Actors can forcefully stop other actors with the @ref
+ simgrid::s4u::Actor::kill(aid_t) method.
- - <b>Master Workers:</b> @ref examples/s4u/app-masterworker/s4u-app-masterworker.cpp \n
- Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
- processes.
+ - <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.
-@section s4u_ex_activities Activities on Resources (communications and executions)
+@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).
-@subsection s4u_ex_activity_comm Communications (using the network)
+ - <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
until one activity of the set completes, no matter which terminates
first.
-@subsection s4u_ex_activity_exec Executions (using the CPU)
+@subsection s4u_ex_activity_exec Executions on the CPU
- <b>Basic execution</b>.
@ref examples/s4u/exec-basic/s4u-exec-basic.cpp \n
- <b>Asynchronous execution</b>.
@ref examples/s4u/exec-async/s4u-exec-async.cpp \n
- You can start asynchronous executions, in a way that is very
- similar to asynchronous communications.
+ 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.
- TODO: add an example about parallel executions.
-
-@section s4u_ex_actors Acting on Actors
+ - <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>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>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::getPstateSpeed and @ref simgrid::s4u::Host::setPstate.
- - <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.
+ - <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.
- - <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.
+@subsection s4u_ex_activity_io I/O on disks and files
- - <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() method.
+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>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>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.
- - <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.
+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>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.
+ - <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, ...).
-@section s4u_ex_synchro Inter-Actor Synchronization
+ - <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.
- - <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.
+@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_actions Following Workload Traces
-
-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/actions-comm/s4u-actions-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/actions-storage/s4u-actions-storage.cpp \n
- Presents a set of event handlers reproducing classical I/O
- primitives (open, read, close).
-
@section s4u_ex_platf Interacting with the platform
- <b>User-defined properties</b>.
- simgrid::s4u::Link::getProperty() and simgrid::s4u::Link::setProperty()
- simgrid::s4u::NetZone::getProperty() and simgrid::s4u::NetZone::setProperty()
-@section s4u_ex_io Simulating disks and files
+@section s4u_ex_energy Simulating the energy consumption
-The examples of this section demonstrate how to interact with the
-simulated storages.
+ - <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.
-SimGrid provides two levels of abstraction. You can either use the
-FileSystem plugin, or interact directly with the disks. At the file
-system level, you can open files and interact with them. A write
-operation may fail if the disk is already full. Using the direct (low
-level) interface, you just specify the amount of data that is written
-or read, and this is done unconditionnally. Both levels have
-respective advantages, depending on what you want to model.
+ - <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>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.
+ - <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>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>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.
- - <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.
+@section s4u_ex_tracing Tracing and visualization features
-@section s4u_ex_energy Simulating the energy consumption
+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".
- - <b>Using Pstates on a host</b>
- @ref examples/s4u/energy-pstate/s4u-energy-pstate.cpp and
- @ref examples/platforms/energy_platform.xml \n
- Show how define a set of pstates for a host and how the current
- pstate can be accessed/changed with @ref simgrid::s4u::Host::getPstateSpeed and @ref simgrid::s4u::Host::setPstate.
- See also the platform XML file for have a details on how to declare the CPU capacity for each pstate.
+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-masterworker/s4u-app-masterworker.cpp \n
+ Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker
+ processes.
+
+@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/actions-comm/s4u-actions-comm.cpp
-@example examples/s4u/actions-storage/s4u-actions-storage.cpp
@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/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-masterworker/s4u-app-masterworker.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/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/app-token-ring/s4u-app-token-ring.cpp
-@example examples/s4u/app-masterworker/s4u-app-masterworker.cpp
-@example examples/s4u/app-pingpong/s4u-app-pingpong.cpp
-@example examples/s4u/energy-pstate/s4u-energy-pstate.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
-*/
\ No newline at end of file
+*/
