docs: dupplicate platform examples in the right section

[simgrid.git] / docs / source / app_s4u.rst

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 74fb609..dcad90b 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -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,12 +138,16 @@ provides many helper functions to simplify the code of actors.
 
 .. |API_s4u_Mutex| replace:: **Mutex**
 
+.. _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
@@ -372,32 +376,17 @@ shouldn't), using :cpp:func:`simgrid::s4u::Host::destroy`.
 API Reference
 *************
 
-.. _API_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
-=============
+.. _API_s4u_simulation_object:
 
-.. doxygenclass:: simgrid::s4u::Activity
-   :members:
-   :protected-members:
-   :undoc-members:
+==================
+Simulation objects
+==================
 
 .. _API_s4u_Actor:
 
-===========
-class Actor
-===========
+==============
+⁣  class Actor
+==============
 
 .. doxygentypedef:: ActorPtr
 
@@ -455,10 +444,10 @@ Querying info about actors
       .. autodoxymethod:: simgrid::s4u::Actor::set_property(const std::string &key, const std::string &value) 
 
       .. autodoxymethod:: simgrid::s4u::Actor::get_host
-      .. autodoxymethod:: simgrid::s4u::Actor::migrate
+      .. autodoxymethod:: simgrid::s4u::Actor::set_host
 
       .. autodoxymethod:: simgrid::s4u::Actor::get_refcount()
-      .. autodoxymethod:: simgrid::s4u::Actor::get_impl()
+      .. autodoxymethod:: simgrid::s4u::Actor::get_impl
 
    .. group-tab:: Python
                   
@@ -467,8 +456,6 @@ Querying info about actors
       .. autoattribute:: simgrid.Actor.pid
       .. autoattribute:: simgrid.Actor.ppid
 
-      .. automethod:: simgrid.Actor.migrate
-
 Suspending and resuming actors
 ------------------------------
 
@@ -486,8 +473,8 @@ Suspending and resuming actors
       .. automethod:: simgrid.Actor.suspend
       .. automethod:: simgrid.Actor.is_suspended
 
-Killing actors
---------------
+Specifying when actors should terminate
+---------------------------------------
 
 .. tabs::
 
@@ -517,7 +504,7 @@ Reacting to the end of actors
 
    .. group-tab:: C++
 
-      .. autodoxymethod:: simgrid::s4u::Actor::on_exit(const std::function< void(bool)> &fun)
+      .. 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)
@@ -538,77 +525,156 @@ Signals
       .. 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:
+.. _API_s4u_this_actor:
 
-============
-s4u::Barrier
-============
+====================
+⁣  The current actor
+====================
 
-.. doxygentypedef:: BarrierPtr
+Static methods working on the current actor (see :ref:`API_s4u_Actor`).
+
+.. doxygennamespace:: simgrid::s4u::this_actor
+
+.. _API_s4u_Engine:
 
-.. doxygenclass:: simgrid::s4u::Barrier
+====================
+⁣  Simulation Engine
+====================
+
+.. doxygenclass:: simgrid::s4u::Engine
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Comm:
+.. _API_s4u_Mailbox:
+
+================
+⁣  class Mailbox
+================
+
+Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
+
+.. doxygenclass:: simgrid::s4u::Mailbox
+   :members:
+   :protected-members:
+   :undoc-members:
+.. _API_s4u_Resource:
 
 =========
-s4u::Comm
+Resources
 =========
 
-.. doxygentypedef:: CommPtr
+.. _API_s4u_Disk:
 
-.. doxygenclass:: simgrid::s4u::Comm
+=============
+⁣  class Disk
+=============
+
+.. doxygenclass:: simgrid::s4u::Disk
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_ConditionVariable:
 
-======================
-s4u::ConditionVariable
-======================
 
-.. doxygentypedef:: ConditionVariablePtr
+.. _API_s4u_Host:
 
-.. doxygenclass:: simgrid::s4u::ConditionVariable
+=============
+⁣  class Host
+=============
+
+.. doxygenclass:: simgrid::s4u::Host
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Disk:
+.. _API_s4u_Link:
 
-============
-s4u::Disk
-============
+=============
+⁣  class Link
+=============
 
-.. doxygenclass:: simgrid::s4u::Disk
+.. doxygenclass:: simgrid::s4u::Link
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Engine:
+.. _API_s4u_NetZone:
 
-===========
-s4u::Engine
-===========
+================
+⁣  class NetZone
+================
 
-.. doxygenclass:: simgrid::s4u::Engine
+.. doxygenclass:: simgrid::s4u::NetZone
+   :members:
+   :protected-members:
+   :undoc-members:
+
+.. _API_s4u_VirtualMachine:
+
+=======================
+⁣  class VirtualMachine
+=======================
+
+.. doxygenclass:: simgrid::s4u::VirtualMachine
+   :members:
+   :protected-members:
+   :undoc-members:
+
+
+.. _API_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)
+
+.. _API_s4u_Comm:
+
+=============
+⁣  class Comm
+=============
+
+.. doxygentypedef:: CommPtr
+
+.. doxygenclass:: simgrid::s4u::Comm
    :members:
    :protected-members:
    :undoc-members:
 
 .. _API_s4u_Exec:
 
-=========
-s4u::Exec
-=========
+=============
+⁣  class Exec
+=============
 
 .. doxygentypedef:: ExecPtr
 
@@ -619,9 +685,9 @@ s4u::Exec
 
 .. _API_s4u_ExecSeq:
 
-============
-s4u::ExecSeq
-============
+==================
+⁣    class ExecSeq
+==================
 
 .. doxygentypedef:: ExecSeqPtr
 
@@ -632,9 +698,9 @@ s4u::ExecSeq
 
 .. _API_s4u_ExecPar:
 
-============
-s4u::ExecPar
-============
+==================
+⁣    class ExecPar
+==================
 
 .. doxygentypedef:: ExecParPtr
 
@@ -643,22 +709,11 @@ s4u::ExecPar
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Host:
-
-=========
-s4u::Host
-=========
-
-.. doxygenclass:: simgrid::s4u::Host
-   :members:
-   :protected-members:
-   :undoc-members:
-
 .. _API_s4u_Io:
 
-=======
-s4u::Io
-=======
+===========
+⁣  class Io
+===========
 
 .. doxygentypedef:: IoPtr
 
@@ -667,78 +722,71 @@ s4u::Io
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Link:
+.. _API_s4u_Synchronizations:
 
-=========
-s4u::Link
-=========
+=======================
+Synchronization Objects
+=======================
 
-.. doxygenclass:: simgrid::s4u::Link
-   :members:
-   :protected-members:
-   :undoc-members:
+.. _API_s4u_Barrier:
 
-.. _API_s4u_Mailbox:
+================
+⁣  class Barrier
+================
 
-============
-s4u::Mailbox
-============
+.. doxygentypedef:: BarrierPtr
 
-Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
+.. autodoxyclass:: simgrid::s4u::Barrier
 
-.. doxygenclass:: simgrid::s4u::Mailbox
-   :members:
-   :protected-members:
-   :undoc-members:
+   .. tabs::
 
-.. _API_s4u_Mutex:
+      .. group-tab:: C++
 
-==========
-s4u::Mutex
-==========
+         .. autodoxymethod:: simgrid::s4u::Barrier::Barrier(unsigned int count)
+         .. autodoxymethod:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
+         .. autodoxymethod:: simgrid::s4u::Barrier::wait()
 
-.. doxygentypedef:: MutexPtr
 
-.. doxygenclass:: simgrid::s4u::Mutex
-   :members:
-   :protected-members:
-   :undoc-members:
+.. _API_s4u_ConditionVariable:
 
-.. _API_s4u_NetZone:
+==========================
+⁣  class ConditionVariable
+==========================
 
-============
-s4u::NetZone
-============
+.. doxygentypedef:: ConditionVariablePtr
 
-.. doxygenclass:: simgrid::s4u::NetZone
+.. doxygenclass:: simgrid::s4u::ConditionVariable
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_Semaphore:
+.. _API_s4u_Mutex:
 
 ==============
-s4u::Semaphore
+⁣  class Mutex
 ==============
 
-.. doxygentypedef:: SemaphorePtr
+.. doxygentypedef:: MutexPtr
 
-.. doxygenclass:: simgrid::s4u::Semaphore
+.. doxygenclass:: simgrid::s4u::Mutex
    :members:
    :protected-members:
    :undoc-members:
 
-.. _API_s4u_VirtualMachine:
+.. _API_s4u_Semaphore:
 
-===================
-s4u::VirtualMachine
-===================
+==================
+⁣  class Semaphore
+==================
 
-.. doxygenclass:: simgrid::s4u::VirtualMachine
+.. doxygentypedef:: SemaphorePtr
+
+.. doxygenclass:: simgrid::s4u::Semaphore
    :members:
    :protected-members:
    :undoc-members:
 
+
 C API Reference
 ***************