Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
this is actually an example of exec, no link to energy things
[simgrid.git] / examples / s4u / README.doc
index 24feb51..90bdfa8 100644 (file)
@@ -14,12 +14,16 @@ documentation, but it should remain readable directly.
  @brief Find the S4U example fitting your needs in the archive.
 
   - @ref s4u_ex_basics
  @brief Find the S4U example fitting your needs in the archive.
 
   - @ref s4u_ex_basics
-  - @ref s4u_ex_async
+  - @ref s4u_ex_activities
+    - @ref s4u_ex_activity_comm
+    - @ref s4u_ex_activity_exec
+    - @ref s4u_ex_activity_io
   - @ref s4u_ex_actors
   - @ref s4u_ex_actors
+    - @ref s4u_ex_actors_start
+    - @ref s4u_ex_actors_synchro
+    - @ref s4u_ex_actors_replay
   - @ref s4u_ex_synchro
   - @ref s4u_ex_synchro
-  - @ref s4u_ex_actions
   - @ref s4u_ex_platf
   - @ref s4u_ex_platf
-  - @ref s4u_ex_io
   - @ref s4u_ex_energy
 
 TODO: document here the examples about plugins
   - @ref s4u_ex_energy
 
 TODO: document here the examples about plugins
@@ -43,7 +47,9 @@ TODO: document here the examples about plugins
     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
     processes. 
     
     Another good old example, where one Master process has a bunch of task to dispatch to a set of several Worker 
     processes. 
     
-@section s4u_ex_async Asynchronous communications
+@section s4u_ex_activities Activities that consume Resources (communications, executions and disks)
+
+@subsection s4u_ex_activity_comm Communications (using the network)
 
  - <b>Basic asynchronous communications</b>. 
    @ref examples/s4u/async-wait/s4u-async-wait.cpp \n
 
  - <b>Basic asynchronous communications</b>. 
    @ref examples/s4u/async-wait/s4u-async-wait.cpp \n
@@ -64,35 +70,71 @@ TODO: document here the examples about plugins
    until one activity of the set completes, no matter which terminates
    first.    
 
    until one activity of the set completes, no matter which terminates
    first.    
 
-@section s4u_ex_actors Acting on 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.
+@subsection s4u_ex_activity_exec Executions (using the CPU)
 
 
-  - <b>Actors using CPU time</b>.
-    @ref examples/s4u/actor-execute/s4u-actor-execute.cpp \n
+  - <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.
 
     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>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>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>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>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>Priority actors</b>.
-    @ref examples/s4u/actor-priority/s4u-actor-priority.cpp \n
-    Actors can be launched according their priorities thanks to the @ref
-    simgrid::s4u::this_actor::execute() method.
+  TODO: add an example about parallel executions.
+
+@subsection s4u_ex_activity_io I/O (using 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.
+
+@section s4u_ex_actors Acting on Actors
+
+@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
 
   - <b>Kill actors</b>.
     @ref examples/s4u/actor-kill/s4u-actor-kill.cpp \n
@@ -105,23 +147,35 @@ TODO: document here the examples about plugins
     \n
     You can specify a start time and a kill time in the deployment file.
 
     \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>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.
 
   - <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.
 
-@section s4u_ex_synchro Inter-Actor Synchronization 
-
- - <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
+@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
 
 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
@@ -149,6 +203,11 @@ also the tesh files in the example directories for details.
     Presents a set of event handlers reproducing classical I/O
     primitives (open, read, close).
 
     Presents a set of event handlers reproducing classical I/O
     primitives (open, read, close).
 
+@section s4u_ex_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>User-defined properties</b>.
 @section s4u_ex_platf Interacting with the platform
 
  - <b>User-defined properties</b>.
@@ -164,29 +223,13 @@ also the tesh files in the example directories for details.
    - simgrid::s4u::Link::getProperty() and simgrid::s4u::Link::setProperty()
    - simgrid::s4u::NetZone::getProperty() and simgrid::s4u::NetZone::setProperty()
 
    - 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
-
-The examples of this section demonstrate how to interact with the
-simulated storages.
-
-  - <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>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_energy Simulating the energy consumption
 
 
 @section s4u_ex_energy Simulating the energy consumption
 
-  - <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.
+  - <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.
 
 */
 
 
 */
 
@@ -196,23 +239,28 @@ simulated storages.
 @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-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-execute/s4u-actor-execute.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-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-priority/s4u-actor-priority.cpp
 @example examples/s4u/actor-suspend/s4u-actor-suspend.cpp
 @example examples/s4u/actor-yield/s4u-actor-yield.cpp
 @example examples/s4u/actor-suspend/s4u-actor-suspend.cpp
 @example examples/s4u/actor-yield/s4u-actor-yield.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/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/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/energy-pstate/s4u-energy-pstate.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-remote/s4u-exec-remote.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-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-file-remote/s4u-io-file-remote.cpp
-@example examples/s4u/io-storage-raw/s4u-io-storage-raw.cpp \n
+@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/mutex/s4u-mutex.cpp
 @example examples/s4u/platform-properties/s4u-platform-properties.cpp
 @example examples/s4u/platform-properties/s4u-platform-properties_d.xml