X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/06053662d38a9206e3bbd0f81d710378a65ddb29..d4154756e7e32e753994ec84345c1679e70cde2a:/examples/s4u/README.doc diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc index 6ab9071d83..1780dde6c5 100644 --- a/examples/s4u/README.doc +++ b/examples/s4u/README.doc @@ -13,115 +13,93 @@ documentation, but it should remain readable directly. @ingroup s4u_api @brief Find the S4U example fitting your needs in the archive. - - @ref s4u_ex_basics - - @ref s4u_ex_async +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_basics Basics of SimGrid simulation - - - Creating actors: @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. - - - 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). - - - 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 - 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_actors Actors: the active entities - - Basic asynchronous communications. - @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 - involved are @ref simgrid::s4u::Mailbox::put_async and - @ref simgrid::s4u::Comm::wait(). - - - Waiting for all communications in a set. - @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 - 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. - -@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. - - Actors using CPU time. - @ref examples/s4u/actor-execute/s4u-actor-execute.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. + - Kill actors. + @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. + + - Kill actors (other function). + @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. + + - 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 + 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. - - Kill actors. - @ref examples/s4u/actor-kill/s4u-actor-kill.cpp \n - Actors can forcefully stop other actors with the @ref - simgrid::s4u::Actor::kill() method. - - - 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 - You can specify a start time and a kill time in the deployment file. - - 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 - - - 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. - - - 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 @@ -140,48 +118,89 @@ 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/actions-comm/s4u-actions-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/actions-storage/s4u-actions-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). -@section s4u_ex_platf Interacting with the platform +@section s4u_ex_activities Activities: the things that Actors do - - 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 - 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() +@subsection s4u_ex_activity_comm Communications on the network + + - Basic asynchronous communications. + @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 + involved are @ref simgrid::s4u::Mailbox::put_async and + @ref simgrid::s4u::Comm::wait(). -@section s4u_ex_io Simulating disks and files + - Waiting for all communications in a set. + @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 + 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. -The examples of this section demonstrate how to interact with the -simulated storages. +@subsection s4u_ex_activity_exec Executions on the CPU -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. + - 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. + + - 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. + + - 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. + + - 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 + +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, ...). @@ -191,24 +210,107 @@ respective advantages, depending on what you want to model. 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 + Shows how to use simgrid::s4u::Mutex synchronization objects. + +@section s4u_ex_platf Interacting with the platform + + - 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 + 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() + @section s4u_ex_energy Simulating the energy consumption - - Using Pstates on a host - @ref examples/s4u/energy-pstate/s4u-energy-pstate.cpp and + - Describing the energy profiles in the platform @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. + 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 + 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 +are illustrated in these example. See also the +@ref tracing_tracing_options "full list of options related to tracing". + +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 + 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. + + - 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). + + - 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 + 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 + + - Bit Torrent + @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 + Data broadcast over a ring of processes. + +@subsection s4u_ex_app_dht Distributed Hash Tables (DHT) + + - Chord Protocol + @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/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 @@ -216,20 +318,35 @@ respective advantages, depending on what you want to model. @example examples/s4u/actor-migration/s4u-actor-migration.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/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/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 \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/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 +*/