X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/45aa913504591455ff834cb93886ba69f3db3a18..5937b88aaa18de687b2de15a97ee3ae0dc480f64:/docs/source/app_s4u.rst diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index f386d13bec..8d4ec2be63 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -17,10 +17,20 @@ 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. +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,15 +44,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 +82,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,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 ` that consumes the *transmiting power* of :ref:`s4u::Link ` 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() `. 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 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() `. Finally, to wait at most until a specified time limit, use :cpp:func:`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() `. Finally, the actor waits for the completion of all of them at once with @@ -197,8 +211,8 @@ 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 @@ -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 +`_ +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 +`_ +), 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