X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/36a6fab77ef7d4e4a24aa06d5648ec7a0df7f111..d4729dbbb22bd34542046d553605a57f356d94fe:/docs/source/app_s4u.rst

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index a4a661a074..8d4ec2be63 100644
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -17,10 +17,20 @@ The S4U Interface
    <br/>
 
 The S4U interface (SimGrid for you) mixes the full power of SimGrid
-with the full power of C++. This is the prefered interface to describe
-abstract algorithms in the domains of Cloud, P2P, HPC, IoT and similar
+with the full power of C++. This is the preferred interface to describe
+abstract algorithms in the domains of Cloud, P2P, HPC, IoT, and similar
 settings.
 
+Currently (v3.21), S4U is definitely the way to go for long-term
+projects. It is feature complete, but may still evolve slightly in the
+future releases. It can already be used to do everything that can be
+done in SimGrid, but you may have to adapt your code in future
+releases. When this happens, compiling your code will produce
+deprecation warnings for 4 releases (one year) before the removal of
+the old symbols. 
+If you want an API that will never ever evolve in the future, you
+should use the deprecated MSG API instead. 
+
 -------------
 Main Concepts
 -------------
@@ -34,12 +44,12 @@ S4U interface to express their
 and other |Activities|_, so that they get reflected within the
 simulator. These activities take place on resources such as |Hosts|_,
 |Links|_ and |Storages|_. SimGrid predicts the time taken by each
-activity and orchestrates accordingly the actors waiting for the
+activity and orchestrates the actors accordingly, waiting for the
 completion of these activities.
 
 
 When **communicating**, data is not directly sent to other actors but
-posted onto a |Mailbox|_ that serve as rendez-vous point between
+posted onto a |Mailbox|_ that serves as a rendez-vous point between
 communicating actors. This means that you don't need to know who you
 are talking to, you just put your communication `Put` request in a
 mailbox, and it will be matched with a complementary `Get`
@@ -72,7 +82,7 @@ functions to simplify the code of actors.
   - :ref:`class s4u::Link <exhale_class_classsimgrid_1_1s4u_1_1Link>`
     Interconnecting hosts.
   - :ref:`class s4u::NetZone <exhale_class_classsimgrid_1_1s4u_1_1NetZone>`:
-    Sub-region of the platform, containing resources (Hosts, Link, etc).
+    Sub-region of the platform, containing resources (Hosts, Links, etc).
   - :ref:`class s4u::Storage <exhale_class_classsimgrid_1_1s4u_1_1Storage>`
     Resource on which actors can write and read data.
   - :ref:`class s4u::VirtualMachine <exhale_class_classsimgrid_1_1s4u_1_1VirtualMachine>`:
@@ -132,11 +142,15 @@ functions to simplify the code of actors.
 .. |Mutex| replace:: **Mutex**
 .. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
 
+.. THE EXAMPLES
+
+.. include:: ../../examples/s4u/README.rst
+
 ----------
 Activities
 ----------
 
-Activities represent the actions that consumes a resource, such as
+Activities represent the actions that consume a resource, such as a
 :ref:`s4u::Comm <exhale_class_classsimgrid_1_1s4u_1_1Comm>` that
 consumes the *transmiting power* of :ref:`s4u::Link
 <exhale_class_classsimgrid_1_1s4u_1_1Link>` resources.
@@ -152,11 +166,11 @@ create blocking communications: the actor is blocked until the
 completion of that communication. Asynchronous communications do not
 block the actor during their execution but progress on their own.
 
-Once your asynchronous activity is started, you can test for
+Once your asynchronous activity is started, you can test for its
 completion using :cpp:func:`s4u::Activity::test() <simgrid::s4u::Activity::test>`.
 This function returns ``true`` if the activity completed already.
 You can also use :cpp:func:`s4u::Activity::wait() <simgrid::s4u::Activity::wait>`
-to block until the completion of the activity. To wait at most for a given period,
+to block until the completion of the activity. To wait for at most a given amount of time,
 use  :cpp:func:`s4u::Activity::wait_for() <simgrid::s4u::Activity::wait_for>`.
 Finally, to wait at most until a specified time limit, use
 :cpp:func:`s4u::Activity::wait_until() <simgrid::s4u::Activity::wait_until>`.
@@ -189,7 +203,7 @@ vector of mailboxes.
    :end-before: init-end
    :dedent: 4
 
-You then start all communications that should occur concurrently with
+Then, you start all the communications that should occur concurrently with
 :cpp:func:`s4u::Mailbox::put_async() <simgrid::s4u::Mailbox::put_async>`.  
 Finally, the actor waits for the completion of all of them at once
 with 
@@ -207,3 +221,33 @@ Activities Life cycle
 .....................
 
 Sometimes, you want to change the setting of an activity before it even starts. 
+
+.. todo:: write this section
+
+-----------------
+Memory Management
+-----------------
+
+For sake of simplicity, we use `RAII
+<https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
+everywhere in S4U. This is an idiom where resources are automatically
+managed through the context. Provided that you never manipulate
+objects of type Foo directly but always FooPtr references (which are
+defined as `boost::intrusive_ptr
+<http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
+<Foo>), you will never have to explicitely release the resource that
+you use nor to free the memory of unused objects.
+
+Here is a little example:
+
+.. code-block:: cpp
+
+   void myFunc() 
+   {
+     simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
+
+     mutex->lock();   // use the mutex as a simple reference
+     //  bla bla
+     mutex->unlock(); 
+  
+   } // The mutex gets automatically freed because the only existing reference gets out of scope