From 87c7d517e23f88cb837b66da392e53259aedc825 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Fri, 15 Dec 2017 08:54:42 +0100 Subject: [PATCH 1/1] reorganize the S4U examples in the doc --- examples/s4u/README.doc | 217 +++++++++++++++++++++------------------- 1 file changed, 116 insertions(+), 101 deletions(-) diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc index 799e738c51..11cb1db23a 100644 --- a/examples/s4u/README.doc +++ b/examples/s4u/README.doc @@ -13,43 +13,116 @@ 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_activities - - @ref s4u_ex_activity_comm - - @ref s4u_ex_activity_exec - - @ref s4u_ex_activity_io +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_actors_start - @ref s4u_ex_actors_synchro - @ref s4u_ex_actors_replay - - @ref s4u_ex_synchro + - @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_energy + - @ref s4u_ex_tracing + - @ref s4u_ex_examplars TODO: document here the examples about plugins + +@section s4u_ex_actors Actors: the active entities -@section s4u_ex_basics Basics of SimGrid simulation +@subsection s4u_ex_actors_start Starting and stoping actors - - 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. + - 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. - - 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). + - 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. - - 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. + - 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. - - 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. + - 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. -@section s4u_ex_activities Activities that consume Resources (communications, executions and disks) +@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. + +@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 +to external events. For example, many P2P protocols react to user +requests, but do nothing if there is no such event. + +In such situations, you should write your protocol in C++, and separate +the workload that you want to play onto your protocol in a separate +text file. Declare a function handling each type of the events in your +trace, register them using @ref xbt_replay_action_register in your +main, and then run the simulation. + +Then, you can either have one trace file containing all your events, +or a file per simulated process: the former may be easier to work +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 + 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 + Presents a set of event handlers reproducing classical I/O + primitives (open, read, close). + +@section s4u_ex_activities Activities: the things that Actors do -@subsection s4u_ex_activity_comm Communications (using the network) +@subsection s4u_ex_activity_comm Communications on the network - Basic asynchronous communications. @ref examples/s4u/async-wait/s4u-async-wait.cpp \n @@ -70,7 +143,7 @@ TODO: document here the examples about plugins until one activity of the set completes, no matter which terminates first. -@subsection s4u_ex_activity_exec Executions (using the CPU) +@subsection s4u_ex_activity_exec Executions on the CPU - Basic execution. @ref examples/s4u/exec-basic/s4u-exec-basic.cpp \n @@ -102,7 +175,7 @@ TODO: document here the examples about plugins TODO: add an example about parallel executions. -@subsection s4u_ex_activity_io I/O (using disks and files) +@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 @@ -127,83 +200,7 @@ result in short reads and short write, as in reality. 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 - 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. - - - 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. - -@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 -to external events. For example, many P2P protocols react to user -requests, but do nothing if there is no such event. - -In such situations, you should write your protocol in C++, and separate -the workload that you want to play onto your protocol in a separate -text file. Declare a function handling each type of the events in your -trace, register them using @ref xbt_replay_action_register in your -main, and then run the simulation. - -Then, you can either have one trace file containing all your events, -or a file per simulated process: the former may be easier to work -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 - 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 - Presents a set of event handlers reproducing classical I/O - primitives (open, read, close). - -@section s4u_ex_synchro Classical synchronization objects +@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. @@ -246,6 +243,24 @@ options to see the task executions: @verbatim --cfg=tracing:yes --cfg=tracing/categorized:yes @endverbatim +@section s4u_ex_examplars 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. + */ /** -- 2.20.1