X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/785b584576154c7ed738502ce20874313f5bf2a3..6574906fc7ef8966b3140b596df794b8e05cd504:/examples/s4u/README.doc
diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc
index 776b9b058e..3d564cadff 100644
--- a/examples/s4u/README.doc
+++ b/examples/s4u/README.doc
@@ -1,12 +1,12 @@
-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.
+// 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
@@ -51,45 +51,46 @@ TODO: document here the examples about plugins
@subsection s4u_ex_actors_start Starting and stoping actors
- Creating actors.
- @ref examples/s4u/actor-create/s4u-actor-create.cpp \n
+ @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.
- Kill actors.
- @ref examples/s4u/actor-kill/s4u-actor-kill.cpp \n
+ @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::s4u::Actor::kill(void) or the @ref
+ simgrid::s4u::Actor::kill(aid_t) methods.
- Controling the actor life cycle from the XML.
@ref examples/s4u/actor-lifetime/s4u-actor-lifetime.cpp
@ref examples/s4u/actor-lifetime/s4u-actor-lifetime_d.xml
- \n
+ @n
You can specify a start time and a kill time in the deployment file.
- Daemonize actors
- @ref examples/s4u/actor-daemon/s4u-actor-daemon.cpp \n
+ @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
- Suspend and Resume actors.
- @ref examples/s4u/actor-suspend/s4u-actor-suspend.cpp \n
+ @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.
- Migrating Actors.
- @ref examples/s4u/actor-migration/s4u-actor-migration.cpp \n
+ @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.
- Waiting for the termination of an actor (joining on it)
- @ref examples/s4u/actor-join/s4u-actor-join.cpp \n
+ @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.
- Yielding to other actor.
- @ref examples/s4u/actor-yield/s4u-actor-yield.cpp\n
+ @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.
@@ -113,12 +114,12 @@ with, but the second is more efficient on very large traces. Check
also the tesh files in the example directories for details.
- Communication replay.
- @ref examples/s4u/replay-comm/s4u-replay-comm.cpp \n
+ @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).
- I/O replay.
- @ref examples/s4u/replay-storage/s4u-replay-storage.cpp \n
+ @ref examples/s4u/replay-storage/s4u-replay-storage.cpp @n
Presents a set of event handlers reproducing classical I/O
primitives (open, read, close).
@@ -127,7 +128,7 @@ also the tesh files in the example directories for details.
@subsection s4u_ex_activity_comm Communications on the network
- Basic asynchronous communications.
- @ref examples/s4u/async-wait/s4u-async-wait.cpp \n
+ @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
@@ -135,12 +136,12 @@ also the tesh files in the example directories for details.
@ref simgrid::s4u::Comm::wait().
- Waiting for all communications in a set.
- @ref examples/s4u/async-waitall/s4u-async-waitall.cpp\n
+ @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.
- Waiting for the first completed communication in a set.
- @ref examples/s4u/async-waitany/s4u-async-waitany.cpp\n
+ @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.
@@ -148,7 +149,7 @@ also the tesh files in the example directories for details.
@subsection s4u_ex_activity_exec Executions on the CPU
- Basic execution.
- @ref examples/s4u/exec-basic/s4u-exec-basic.cpp \n
+ @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
@@ -156,26 +157,29 @@ also the tesh files in the example directories for details.
get more resources.
- Asynchronous execution.
- @ref examples/s4u/exec-async/s4u-exec-async.cpp \n
+ @ref examples/s4u/exec-async/s4u-exec-async.cpp @n
You can start asynchronous executions, just like you would fire
background threads.
- Monitoring asynchronous executions.
- @ref examples/s4u/exec-monitor/s4u-exec-monitor.cpp \n
+ @ref examples/s4u/exec-monitor/s4u-exec-monitor.cpp @n
This example shows how to start an asynchronous execution, and
monitor its status.
- Remote execution.
- @ref examples/s4u/exec-remote/s4u-exec-remote.cpp \n
+ @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.
- Using Pstates on a host
@ref examples/s4u/exec-dvfs/s4u-exec-dvfs.cpp and
- @ref examples/platforms/energy_platform.xml \n
+ @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.
+ pstate can be accessed/changed with @ref simgrid::s4u::Host::get_pstate_speed and @ref simgrid::s4u::Host::set_pstate.
- TODO: add an example about parallel executions.
+ - Parallel tasks
+ @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
@@ -184,7 +188,7 @@ simulated storages. At the simplest level, you simply create read and
write actions on the storage resources.
- Access to raw storage devices.
- @ref examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp \n
+ @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.
@@ -193,42 +197,65 @@ 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. @ref examples/s4u/io-file-system/s4u-io-file-system.cpp \n
+ - File Management. @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, ...).
- Remote I/O.
- @ref examples/s4u/io-file-remote/s4u-io-file-remote.cpp \n
+ @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
- - Mutex: @ref examples/s4u/mutex/s4u-mutex.cpp \n
+ - Mutex: @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
+ - Retrieving the list of hosts matching a given criteria.
+ @ref examples/s4u/engine-filtering/s4u-engine-filtering.cpp@n
+ Filtering the actors that match a given criteria is rather simple.
+
- User-defined properties.
@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
+ @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 into the XML file: they
- will only last until the end of your simulation.
- - simgrid::s4u::Actor::getProperty() and simgrid::s4u::Actor::setProperty()
- - simgrid::s4u::Host::getProperty() and simgrid::s4u::Host::setProperty()
- - simgrid::s4u::Link::getProperty() and simgrid::s4u::Link::setProperty()
- - simgrid::s4u::NetZone::getProperty() and simgrid::s4u::NetZone::setProperty()
+ 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
+ - Describing the energy profiles in the platform
+ @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.
+
- Consumption due to the CPU
- @ref examples/s4u/energy-exec/s4u-energy-exec.cpp \n
+ @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.
+ - Consumption due to the network
+ @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.
+
+ - Modeling the shutdown and boot of hosts
+ @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
@@ -239,7 +266,7 @@ It is interesting to run the process-create example with the following
options to see the task executions:
- Platform tracing.
- @ref examples/s4u/trace-platform/s4u-trace-platform.cpp \n
+ @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
@@ -250,33 +277,38 @@ options to see the task executions:
This section contains application examples that are somewhat larger
than the previous examples.
- - Ping Pong: @ref examples/s4u/app-pingpong/s4u-app-pingpong.cpp\n
+ - Ping Pong: @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).
+ the simulators (as detailed in Section @ref options).
- - Token ring: @ref examples/s4u/app-token-ring/s4u-app-token-ring.cpp \n
+ - Token ring: @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.
- - Master Workers: @ref examples/s4u/app-masterworker/s4u-app-masterworker.cpp \n
+ - Master Workers: @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.
+ 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
- Bit Torrent
- @ref examples/s4u/app-bittorrent/s4u-app-bittorrent.cpp\n
+ @ref examples/s4u/app-bittorrent/s4u-bittorrent.cpp@n
Classical protocol for Peer-to-Peer data diffusion.
- Chained send
- @ref examples/s4u/app-chainsend/s4u-app-chainsend.cpp\n
+ @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)
- Chord Protocol
- @ref examples/s4u/app-chord/s4u-app-chord.cpp\n
+ @ref examples/s4u/dht-chord/s4u-dht-chord.cpp@n
One of the most famous DHT protocol.
*/
@@ -295,17 +327,24 @@ than the previous examples.
@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/app-bittorrent/s4u-app-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/energy-exec/s4u-energy-exec.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
@@ -318,4 +357,4 @@ than the previous examples.
@example examples/platforms/energy_platform.xml
@example examples/platforms/prop.xml
-*/
\ No newline at end of file
+*/