X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/ac3767af4bf9250b301870faf01140dd39676a4f..26f77b7dd18750482fccb9c88c437ccccfa91d66:/docs/source/app_s4u.rst
diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 82a0785bde..9d20e2b50a 100644
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -17,8 +17,8 @@ The S4U Interface
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.
-------------
@@ -34,15 +34,15 @@ 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 `Send` request in a
-mailbox, and it will be matched with a complementary `Receive`
+are talking to, you just put your communication `Put` request in a
+mailbox, and it will be matched with a complementary `Get`
request. Alternatively, actors can interact through **classical
synchronization mechanisms** such as |Barrier|_, |Semaphore|_,
|Mutex|_ and |ConditionVariable|_.
@@ -72,7 +72,7 @@ functions to simplify the code of actors.
- :ref:`class s4u::Link `
Interconnecting hosts.
- :ref:`class s4u::NetZone `:
- Sub-region of the platform, containing resources (Hosts, Link, etc).
+ Sub-region of the platform, containing resources (Hosts, Links, etc).
- :ref:`class s4u::Storage `
Resource on which actors can write and read data.
- :ref:`class s4u::VirtualMachine `:
@@ -132,23 +132,56 @@ functions to simplify the code of actors.
.. |Mutex| replace:: **Mutex**
.. _Mutex: api/classsimgrid_1_1s4u_1_1Mutex.html
------------------------
-Asynchronous Activities
------------------------
+----------
+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 ` that
consumes the *transmiting power* of :ref:`s4u::Link
-` resources. Every activity
-can be either **blocking** or **asynchronous**. For example,
-:cpp:func:`s4u::Mailbox::put() ` and
-:cpp:func:`s4u::Mailbox::get() ` create
-blocking communications: the actor is blocked until the completion of
-that communication. Asynchronous communications do not block the actor
-during their execution. The following example shows how to have
-several concurrent communications ongoing. First, you have to declare
-a vector in which we will store the ongoing communications. It is also
-useful to have a vector of mailboxes.
+` resources.
+
+.......................
+Asynchronous Activities
+.......................
+
+Every activity can be either **blocking** or **asynchronous**. For
+example, :cpp:func:`s4u::Mailbox::put() `
+and :cpp:func:`s4u::Mailbox::get() `
+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 its
+completion using :cpp:func:`s4u::Activity::test() `.
+This function returns ``true`` if the activity completed already.
+You can also use :cpp:func:`s4u::Activity::wait() `
+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() `.
+Finally, to wait at most until a specified time limit, use
+:cpp:func:`s4u::Activity::wait_until() `.
+
+.. todo::
+
+ wait_for and wait_until are currently not implemented for Exec and Io activities.
+
+Every kind of activities can be asynchronous:
+
+ - :ref:`s4u::CommPtr ` are created with
+ :cpp:func:`s4u::Mailbox::put_async() ` and
+ :cpp:func:`s4u::Mailbox::get_async() `.
+ - :ref:`s4u::IoPtr ` are created with
+ :cpp:func:`s4u::Storage::read_async() ` and
+ :cpp:func:`s4u::Storage::write_async() `.
+ - :ref:`s4u::ExecPtr ` are created with
+ :cpp:func:`s4u::Host::exec_async() `.
+ - In the future, it will become possible to have asynchronous IPC
+ such as asynchronous mutex lock requests.
+
+The following example shows how to have several concurrent
+communications ongoing. First, you have to declare a vector in which
+we will store the ongoing communications. It is also useful to have a
+vector of mailboxes.
.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
:language: c++
@@ -156,7 +189,7 @@ useful to have a 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() `.
Finally, the actor waits for the completion of all of them at once
with
@@ -164,19 +197,13 @@ with
.. literalinclude:: ../../examples/s4u/async-waitall/s4u-async-waitall.cpp
:language: c++
- :start-after: send-begin
- :end-before: send-end
+ :start-after: put-begin
+ :end-before: put-end
:dedent: 4
-Every kind of activities can be asynchronous:
- - :ref:`s4u::CommPtr ` are created with
- :cpp:func:`s4u::Mailbox::put_async() ` and
- :cpp:func:`s4u::Mailbox::get_async() `.
- - :ref:`s4u::IoPtr ` are created with
- :cpp:func:`s4u::Storage::read_async() ` and
- :cpp:func:`s4u::Storage::write_async() `.
- - :ref:`s4u::ExecPtr ` are created with
- :cpp:func:`s4u::Host::exec_async() `.
- - In the future, it will become possible to have asynchronous IPC
- such as asynchronous mutex lock requests.
+.....................
+Activities Life cycle
+.....................
+
+Sometimes, you want to change the setting of an activity before it even starts.