From: Frederic Suter <frederic.suter@cc.in2p3.fr>
Date: Tue, 21 Mar 2017 12:35:20 +0000 (+0100)
Subject: update documentation with new examples
X-Git-Tag: v3_15~30^2~1
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/1422aec5120dbf35139586b0a27210b223601caf

update documentation with new examples
---

diff --git a/examples/s4u/README.doc b/examples/s4u/README.doc
index 9cdcf7aae1..6ecf35c1c3 100644
--- a/examples/s4u/README.doc
+++ b/examples/s4u/README.doc
@@ -14,7 +14,9 @@ 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_actors
   - @ref s4u_ex_synchro
+  - @ref s4u_ex_actions
 
 @section s4u_ex_basics Basics of SimGrid simulation
 
@@ -26,23 +28,60 @@ documentation, but it should remain readable directly.
     Shows how to implement a classical communication pattern, where a token is exchanged along a ring to reach every
     participant.
 
-  - <b>Master Workers:</b> @ref examples/s4u/app-token-ring/s4u_app-token-ring.cpp \n
+  - <b>Master Workers:</b> @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_actors Acting on Actors
+
+  - <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 migrate method.
+
 @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
+
+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.
+
+  - <b>Communication replay</b>.
+    @ref examples/s4u/actions-comm/s4u_actions-comm.cpp \n
+    Presents a set of event handlers reproducing classical communication
+    primitives (asynchronous send/receive at the moment).
+
+  - <b>I/O replay</b>.
+    @ref examples/s4u/actions-storage/s4u_actions-storage.cpp \n
+    Presents a set of event handlers reproducing classical I/O
+    primitives (open, read, close).
+
 */
 
 /**
-@example examples/s4u/launching/s4u_launching.cpp
+@example examples/s4u/actions-comm/s4u_actions-comm.cpp
+@example examples/s4u/actions-storage/s4u_actions-storage.cpp
+@example examples/s4u/actor-migration/s4u_actor-migration.cpp
 @example examples/s4u/app-token-ring/s4u_app-token-ring.cpp
 @example examples/s4u/app-master-worker/s4u_app-master-worker.cpp
 @example examples/s4u/launching/deployment.xml
 
+@example examples/s4u/launching/s4u_launching.cpp
 @example examples/s4u/mutex/s4u_mutex.cpp
 
 */
\ No newline at end of file
diff --git a/examples/s4u/actions-comm/s4u_actions-comm.cpp b/examples/s4u/actions-comm/s4u_actions-comm.cpp
index 1cbdbfbaa2..44b42d1b8c 100644
--- a/examples/s4u/actions-comm/s4u_actions-comm.cpp
+++ b/examples/s4u/actions-comm/s4u_actions-comm.cpp
@@ -104,7 +104,6 @@ int main(int argc, char *argv[])
   xbt_replay_action_register("send", Replayer::send);
   xbt_replay_action_register("recv", Replayer::recv);
 
-  /* Actually do the simulation using MSG_action_trace_run */
   if (argv[3]) {
     simgrid::xbt::action_fs = new std::ifstream(argv[3], std::ifstream::in);
   }
diff --git a/examples/s4u/actions-storage/s4u_actions-storage.cpp b/examples/s4u/actions-storage/s4u_actions-storage.cpp
index 0c10dedde9..21f9e13952 100644
--- a/examples/s4u/actions-storage/s4u_actions-storage.cpp
+++ b/examples/s4u/actions-storage/s4u_actions-storage.cpp
@@ -120,7 +120,6 @@ int main(int argc, char* argv[])
   xbt_replay_action_register("read", Replayer::read);
   xbt_replay_action_register("close", Replayer::close);
 
-  /* Actually do the simulation using MSG_action_trace_run */
   if (argv[3]) {
     simgrid::xbt::action_fs = new std::ifstream(argv[3], std::ifstream::in);
   }