X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/79f4c4c467150b3bea841b968cabd629e9d9282a..835e84e847761565cb9cd95c99cf85b462b47b24:/docs/source/app_s4u.rst

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 885a6a932d..01aada4b5e 100644
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -5,7 +5,7 @@ The S4U Interface
 
 .. raw:: html
 
-   <object id="TOC" data="graphical-toc.svg" width="100%" type="image/svg+xml"></object>
+   <object id="TOC" data="graphical-toc.svg" type="image/svg+xml"></object>
    <script>
    window.onload=function() { // Wait for the SVG to be loaded before changing it
      var elem=document.querySelector("#TOC").contentDocument.getElementById("ActorBox")
@@ -28,7 +28,7 @@ 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. 
+should use the :ref:`deprecated MSG API <MSG_doc>` instead. 
 
 Main Concepts
 *************
@@ -64,60 +64,60 @@ Virtual machines can also be migrated between hosts.
 The :ref:`simgrid::s4u::this_actor <API_s4u_this_actor>` namespace
 provides many helper functions to simplify the code of actors.
 
-- **Global Classes**
+- **Simulation Elements**
 
-  - :ref:`class s4u::Actor <API_s4u_Actor>`:
+  - :ref:`class Actor <API_s4u_Actor>`:
     Active entities executing your application.
-  - :ref:`class s4u::Engine <API_s4u_Engine>`
+  - :ref:`class Engine <API_s4u_Engine>`
     Simulation engine (singleton).
-  - :ref:`class s4u::Mailbox <API_s4u_Mailbox>`
-    Communication rendez-vous.
+  - :ref:`class Mailbox <API_s4u_Mailbox>`
+    Communication rendez-vous, with which actors meet each other.
 
-- **Platform Elements**
+- **Resources**
 
-  - :ref:`class s4u::Disk <API_s4u_Disk>`
+  - :ref:`class Disk <API_s4u_Disk>`
     Resource on which actors can write and read data.
-  - :ref:`class s4u::Host <API_s4u_Host>`:
+  - :ref:`class Host <API_s4u_Host>`:
     Actor location, providing computational power.
-  - :ref:`class s4u::Link <API_s4u_Link>`
+  - :ref:`class Link <API_s4u_Link>`
     Interconnecting hosts.
-  - :ref:`class s4u::NetZone <API_s4u_NetZone>`:
+  - :ref:`class NetZone <API_s4u_NetZone>`:
     Sub-region of the platform, containing resources (Hosts, Links, etc).
-  - :ref:`class s4u::VirtualMachine <API_s4u_VirtualMachine>`:
+  - :ref:`class VirtualMachine <API_s4u_VirtualMachine>`:
     Execution containers that can be moved between Hosts.
 
-- **Activities** (:ref:`class s4u::Activity <API_s4u_Activity>`):
+- **Activities** (:ref:`class Activity <API_s4u_Activity>`):
   The things that actors can do on resources
 
-  - :ref:`class s4u::Comm <API_s4u_Comm>`
+  - :ref:`class Comm <API_s4u_Comm>`
     Communication activity, started on Mailboxes and consuming links.
-  - :ref:`class s4u::Exec <API_s4u_Exec>`
+  - :ref:`class Exec <API_s4u_Exec>`
     Computation activity, started on Host and consuming CPU resources.
-  - :ref:`class s4u::Io <API_s4u_Io>`
+  - :ref:`class Io <API_s4u_Io>`
     I/O activity, started on and consumming disks.
 
-- **Synchronization Mechanisms**: Classical IPC that actors can use
+- **Synchronization Objects**: Classical IPC that actors can use
 
-  - :ref:`class s4u::Barrier <API_s4u_Barrier>`
-  - :ref:`class s4u::ConditionVariable <API_s4u_ConditionVariable>`
-  - :ref:`class s4u::Mutex <API_s4u_Mutex>`
-  - :ref:`class s4u::Semaphore <API_s4u_Semaphore>`
+  - :ref:`class Barrier <API_s4u_Barrier>`
+  - :ref:`class ConditionVariable <API_s4u_ConditionVariable>`
+  - :ref:`class Mutex <API_s4u_Mutex>`
+  - :ref:`class Semaphore <API_s4u_Semaphore>`
 
 
 .. |API_s4u_Actors| replace:: **Actors**
-.. _API_s4u_Actors: #s4u-actor
+.. _API_s4u_Actors: #api-s4u-actor
 
 .. |API_s4u_Activities| replace:: **Activities**
-.. _API_s4u_Activities: #s4u-activity
+.. _API_s4u_Activities: #api-s4u-activity
 
 .. |API_s4u_Hosts| replace:: **Hosts**
-.. _API_s4u_Hosts: #s4u-host
+.. _API_s4u_Hosts: #api-s4u-host
 
 .. |API_s4u_Links| replace:: **Links**
-.. _API_s4u_Links: #s4u-link
+.. _API_s4u_Links: #api-s4u-link
 
 .. |API_s4u_Disks| replace:: **Disks**
-.. _API_s4u_Disks: #s4u-disk
+.. _API_s4u_Disks: #api-s4u-disk
 
 .. |API_s4u_VirtualMachine| replace:: **VirtualMachines**
 
@@ -138,16 +138,16 @@ provides many helper functions to simplify the code of actors.
 
 .. |API_s4u_Mutex| replace:: **Mutex**
 
-.. THE EXAMPLES
-
-.. include:: ../../examples/s4u/README.rst
+.. _s4u_Activities:
 
 Activities
 **********
 
 Activities represent the actions that consume a resource, such as a
-:ref:`s4u::Comm <API_s4u_Comm>` that consumes the *transmitting power* of
-:ref:`s4u::Link <API_s4u_Link>` resources.
+:ref:`Comm <API_s4u_Comm>` that consumes the *transmitting power* of 
+:ref:`Link <API_s4u_Link>` resources, or an :ref:`Exec <API_s4u_Exec>`
+that consumes the *computing power* of :ref:`Host <API_s4u_Host>` resources.
+See also the :ref:`full API <API_s4u_Activity>` below.
 
 =======================
 Asynchronous Activities
@@ -369,54 +369,224 @@ pointers (yet?). This means that it is currently impossible to destroy a
 mailbox or a link. You can still destroy an host (but probably
 shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
 
-C++ API Reference
-*****************
+.. THE EXAMPLES
+
+.. include:: ../../examples/README.rst
+
+API Reference
+*************
 
 .. _API_s4u_this_actor:
 
-=========================
-namespace s4u::this_actor
-=========================
+==================================
+Interacting with the current actor
+==================================
+
+Static methods working on the current actor (see :ref:`API_s4u_Actor`).
 
 .. doxygennamespace:: simgrid::s4u::this_actor
+
 .. _API_s4u_Activity:
 
-=============
-s4u::Activity
-=============
+==============
+class Activity
+==============
+
+.. autodoxyclass:: simgrid::s4u::Activity
+
+   **Known subclasses:**
+   :ref:`Communications <API_s4u_Comm>` (started on Mailboxes and consuming links),
+   :ref:`Executions <API_s4u_Exec>` (started on Host and consuming CPU resources)
+   :ref:`I/O <API_s4u_Io>` (started on and consumming disks).
+   See also the :ref:`section on activities <s4u_Activities>` above.
+
+Querying info about activities
+------------------------------
+
+   .. autodoxymethod:: simgrid::s4u::Activity::get_remaining()
+   .. autodoxymethod:: simgrid::s4u::Activity::get_state()
+   .. autodoxymethod:: simgrid::s4u::Activity::set_remaining(double remains)
+   .. autodoxymethod:: simgrid::s4u::Activity::get_impl
+
+Activities lifecycle
+--------------------
+
+   .. autodoxymethod:: simgrid::s4u::Activity::start
+   .. autodoxymethod:: simgrid::s4u::Activity::cancel
+   .. autodoxymethod:: simgrid::s4u::Activity::test
+   .. autodoxymethod:: simgrid::s4u::Activity::wait
+   .. autodoxymethod:: simgrid::s4u::Activity::wait_for
+   .. autodoxymethod:: simgrid::s4u::Activity::wait_until(double time_limit)
 
-.. doxygenclass:: simgrid::s4u::Activity
-   :members:
-   :protected-members:
-   :undoc-members:
 
 .. _API_s4u_Actor:
 
-==========
-s4u::Actor
-==========
+===========
+class Actor
+===========
 
 .. doxygentypedef:: ActorPtr
 
 .. doxygentypedef:: aid_t
 
-.. doxygenclass:: simgrid::s4u::Actor
-   :members:
-   :protected-members:
-   :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Actor
+
+Creating actors
+---------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::function< void()> &code)
+      .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code)
+      .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, F code, Args... args)
+      .. autodoxymethod:: simgrid::s4u::Actor::create(const std::string &name, s4u::Host *host, const std::string &function, std::vector< std::string > args)
+
+      .. autodoxymethod:: simgrid::s4u::Actor::init(const std::string &name, s4u::Host *host)
+      .. autodoxymethod:: simgrid::s4u::Actor::start(const std::function< void()> &code)
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Actor.create
+
+Searching specific actors
+-------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::by_pid(aid_t pid)
+      .. autodoxymethod:: simgrid::s4u::Actor::self()
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Actor.by_pid
+      .. automethod:: simgrid.Actor.self
+
+Querying info about actors
+--------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::get_cname
+      .. autodoxymethod:: simgrid::s4u::Actor::get_name
+      .. autodoxymethod:: simgrid::s4u::Actor::get_pid
+      .. autodoxymethod:: simgrid::s4u::Actor::get_ppid
+      .. autodoxymethod:: simgrid::s4u::Actor::get_properties() const
+      .. autodoxymethod:: simgrid::s4u::Actor::get_property(const std::string &key) const
+      .. autodoxymethod:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value) 
+
+      .. autodoxymethod:: simgrid::s4u::Actor::get_host
+      .. autodoxymethod:: simgrid::s4u::Actor::set_host
+
+      .. autodoxymethod:: simgrid::s4u::Actor::get_refcount()
+      .. autodoxymethod:: simgrid::s4u::Actor::get_impl
+
+   .. group-tab:: Python
+                  
+      .. autoattribute:: simgrid.Actor.name
+      .. autoattribute:: simgrid.Actor.host
+      .. autoattribute:: simgrid.Actor.pid
+      .. autoattribute:: simgrid.Actor.ppid
+
+      .. automethod:: simgrid.Actor.migrate
+
+Suspending and resuming actors
+------------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::suspend()
+      .. autodoxymethod:: simgrid::s4u::Actor::resume()
+      .. autodoxymethod:: simgrid::s4u::Actor::is_suspended()
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Actor.resume
+      .. automethod:: simgrid.Actor.suspend
+      .. automethod:: simgrid.Actor.is_suspended
+
+Specifying when actors should terminate
+---------------------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::kill()
+      .. autodoxymethod:: simgrid::s4u::Actor::kill_all()
+      .. autodoxymethod:: simgrid::s4u::Actor::set_kill_time(double time)
+      .. autodoxymethod:: simgrid::s4u::Actor::get_kill_time()
+
+      .. autodoxymethod:: simgrid::s4u::Actor::restart()
+      .. autodoxymethod:: simgrid::s4u::Actor::daemonize()
+      .. autodoxymethod:: simgrid::s4u::Actor::is_daemon
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Actor.kill
+      .. automethod:: simgrid.Actor.kill_all
+
+      .. automethod:: simgrid.Actor.daemonize
+      .. automethod:: simgrid.Actor.is_daemon
+
+Reacting to the end of actors
+-----------------------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxymethod:: simgrid::s4u::Actor::on_exit
+      .. autodoxymethod:: simgrid::s4u::Actor::join()
+      .. autodoxymethod:: simgrid::s4u::Actor::join(double timeout)
+      .. autodoxymethod:: simgrid::s4u::Actor::set_auto_restart(bool autorestart)
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Actor.join
+
+Signals
+-------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. autodoxyvar:: simgrid::s4u::Actor::on_creation
+      .. autodoxyvar:: simgrid::s4u::Actor::on_suspend
+      .. autodoxyvar:: simgrid::s4u::Actor::on_resume
+      .. autodoxyvar:: simgrid::s4u::Actor::on_sleep
+      .. autodoxyvar:: simgrid::s4u::Actor::on_wake_up
+      .. autodoxyvar:: simgrid::s4u::Actor::on_migration_start
+      .. autodoxyvar:: simgrid::s4u::Actor::on_migration_end
+      .. autodoxyvar:: simgrid::s4u::Actor::on_termination
+      .. autodoxyvar:: simgrid::s4u::Actor::on_destruction
 
 .. _API_s4u_Barrier:
 
-============
-s4u::Barrier
-============
+=============
+class Barrier
+=============
 
 .. doxygentypedef:: BarrierPtr
 
-.. doxygenclass:: simgrid::s4u::Barrier
-   :members:
-   :protected-members:
-   :undoc-members:
+.. autodoxyclass:: simgrid::s4u::Barrier
+
+   .. tabs::
+
+      .. group-tab:: C++
+
+         .. autodoxymethod:: simgrid::s4u::Barrier::Barrier(unsigned int count)
+         .. autodoxymethod:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
+         .. autodoxymethod:: simgrid::s4u::Barrier::wait()
+
 
 .. _API_s4u_Comm:
 
@@ -601,11 +771,37 @@ s4u::VirtualMachine
    :protected-members:
    :undoc-members:
 
+C API Reference
+***************
+
+==============
+Main functions
+==============
+
+.. doxygenfunction:: simgrid_init
+.. doxygenfunction:: simgrid_get_clock
+.. doxygenfunction:: simgrid_load_deployment
+.. doxygenfunction:: simgrid_load_platform
+.. doxygenfunction:: simgrid_register_default
+.. doxygenfunction:: simgrid_register_function
+.. doxygenfunction:: simgrid_run
+
+==================
+Condition Variable
+==================
+
+See also the :ref:`C++ API <API_s4u_ConditionVariable>`.
+
+.. doxygenfunction:: sg_cond_init
+.. doxygenfunction:: sg_cond_notify_all
+.. doxygenfunction:: sg_cond_notify_one
+.. doxygenfunction:: sg_cond_wait
+.. doxygenfunction:: sg_cond_wait_for
 
 Python API Reference
 ********************
 
-The Python API is generated with pybind11. It closely mimicks the C++
+The Python API is automatically generated with pybind11. It closely mimicks the C++
 API, to which you should refer for more information.
 
 ==========
@@ -656,3 +852,7 @@ Class Mailbox
 
 .. autoclass:: simgrid.Mailbox
    :members:
+
+.. |hr| raw:: html
+
+   <hr />