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 +*/