X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/084ad52d4bc9b1c53f08795703e7fe2d0ada7764..34803ab5554b83e70a652800872a5de378e067c3:/examples/s4u/README.doc diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc index 24feb51311..90bdfa8f2c 100644 --- a/examples/s4u/README.doc +++ b/examples/s4u/README.doc @@ -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 - - @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_start + - @ref s4u_ex_actors_synchro + - @ref s4u_ex_actors_replay - @ref s4u_ex_synchro - - @ref s4u_ex_actions - @ref s4u_ex_platf - - @ref s4u_ex_io - @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. -@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) - Basic asynchronous communications. @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. -@section s4u_ex_actors Acting on Actors - - - Creating actors. - @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) - - Actors using CPU time. - @ref examples/s4u/actor-execute/s4u-actor-execute.cpp \n + - Basic execution. + @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. - - Daemonize actors - @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. + - Asynchronous execution. + @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 + 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 + Before its start, you can change the host on which a given execution will occur. - - Suspend and Resume actors. - @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. + - Using Pstates on a host + @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. - - Priority actors. - @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. + + - Access to raw storage devices. + @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. + + - 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 + 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 + + - Creating actors. + @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 @@ -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. + - Daemonize actors + @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 + 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 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 + 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 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 - - - Mutex: @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 @@ -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). +@section s4u_ex_synchro Classical synchronization objects + + - 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 - User-defined properties. @@ -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() -@section s4u_ex_io Simulating disks and files - -The examples of this section demonstrate how to interact with the -simulated storages. - - - Access to raw storage devices . - @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. - - - Remote I/O. - @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 - - Using Pstates on a host - @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. + - Consumption due to the CPU + @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-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-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/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/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-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