improve the documentation of churn in platform [no ci]

diff --git a/doc/doxygen/howtos.doc b/doc/doxygen/howtos.doc
index 8da21aa..42d1459 100644 (file)
--- a/doc/doxygen/howtos.doc
+++ b/doc/doxygen/howtos.doc
@@ -18,6 +18,34 @@ Of course, you should also check the @ref examples page, that shows
 more detailed usage examples. As for the rest of the documentation
 (and of SimGrid, actually), any contribution is welcome.
 
 more detailed usage examples. As for the rest of the documentation
 (and of SimGrid, actually), any contribution is welcome.
 

+@section howto_churn How to model churn
+
+One of the biggest challenges in P2P settings is to cope with the
+churn, meaning that resources keep appearing and disappearing. In
+SimGrid, you can always change the state of each host manually, with
+eg simgrid::s4u::Host::on(). To reduce the burden when the churn is
+high, you can also attach a **state profile** to the host directly.
+
+This is not possible from S4U yet (TODO), and you should use the \c
+state_file attribute of @ref pf_tag_host or @ref pf_tag_cluster. 
+
+Every lines (but the last) of such files describe timed events with
+the form "date value". Example:
+
+~~~{.py}
+  1 0
+  2 1
+ WAITFOR 8
+~~~
+
+ - At time t=1, the host is turned off (value 0 means OFF)
+ - At time t=2, it is turned back on (other values means ON)
+ - At time t=10, the history is reset (because that's 8 seconds after
+   the last event). So the host will be turned off again at t=11.
+
+If your trace does not contain a WAITFOR line, then your profile is
+only executed once and not repetitively.
+

 @section howto_multicore How to model multicore machines
 
 Multicore machines are very complex, and there is many way to model
 @section howto_multicore How to model multicore machines
 
 Multicore machines are very complex, and there is many way to model

diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc
index ed5af1d..89ee5f6 100644 (file)
--- a/doc/doxygen/platform.doc
+++ b/doc/doxygen/platform.doc
@@ -119,7 +119,7 @@ speed             | double (mandatory)                     | Computational power
 core              | int (defaults to 1)                    | Number of cores (see @ref howto_multicore)
 state             | optionally "OFF"                       | If set to OFF, the host is initially turned off.
 availability_file | File name (optional) | (Relative or absolute) filename to use as input; must contain availability traces for this host. The syntax of this file is defined below.
 core              | int (defaults to 1)                    | Number of cores (see @ref howto_multicore)
 state             | optionally "OFF"                       | If set to OFF, the host is initially turned off.
 availability_file | File name (optional) | (Relative or absolute) filename to use as input; must contain availability traces for this host. The syntax of this file is defined below.

-state_file        | File name (optional) |  Same mechanism as availability_file.<br /> 
+state_file        | File name (optional) |  File to use as a state profile (see @ref howto_churn)

 coordinates       | String (mandatory when using Vivaldi routing) | The coordinates of this host (see @ref pf_P2P_tags).
 pstate     | Double (Defaults to 0) | FIXME: Not yet documented.
 
 coordinates       | String (mandatory when using Vivaldi routing) | The coordinates of this host (see @ref pf_P2P_tags).
 pstate     | Double (Defaults to 0) | FIXME: Not yet documented.
 


@@ -175,37 +175,6 @@ will start delivering 80\% of its power. In this example, this amounts to 400 Mf
 Since the periodicity in line 1 was set to be 1.0, i.e., 1 timestep, this host will
 continue to provide 500 Mflop/s from time 21. From time 32 it will provide 250 MFlop/s and so on.
 
 Since the periodicity in line 1 was set to be 1.0, i.e., 1 timestep, this host will
 continue to provide 500 Mflop/s from time 21. From time 32 it will provide 250 MFlop/s and so on.
 

-\anchor pf_host_churn
-### Expressing churn ###
-
-To express the fact that a host can change state over time (as in P2P
-systems, for instance), it is possible to use a file describing the time
-at which the host is turned on or off. An example of the content
-of such a file is presented below.
-
-#### Adding a state file ####
-
-\verbatim
-<platform version="4">
-  <host id="bob" power="500Gf" state_file="bob.fail" />
-</platform>
-\endverbatim
-
-#### Example of "bob.fail" file ####
-
-~~~{.py}
-  PERIODICITY 10.0
-  1.0 0
-  2.0 1
-~~~
-
-A zero value means <b>down</b> (i.e., OFF) while a positive one means <b>up and
-  running</b> (i.e., ON). From time 0.0 to time 1.0, the host is on as usual. At time 1.0, it is
-turned off and at time 2.0, it is turned on again until time 12 (2 plus the
-periodicity 10). It will be turned off again at time 13.0 until time 23.0, and
-so on.
-
-

 \subsubsection pf_tag_cluster &lt;cluster&gt;
 
 ``<cluster />`` represents a machine-cluster. It is most commonly used
 \subsubsection pf_tag_cluster &lt;cluster&gt;
 
 ``<cluster />`` represents a machine-cluster. It is most commonly used