Expose signals Activity::on_suspend and Activity::on_resume in s4u

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

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 117b85d..ededc62 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -484,6 +484,7 @@ Retrieving actors
 
       .. doxygenfunction:: sg_actor_by_pid(aid_t pid)
       .. doxygenfunction:: sg_actor_self()
+      .. doxygenfunction:: sg_actor_list()
 
 Querying info
 -------------
@@ -597,6 +598,7 @@ Reacting to the end of actors
       .. doxygenfunction:: simgrid::s4u::Actor::join() const
       .. doxygenfunction:: simgrid::s4u::Actor::join(double timeout) const
       .. doxygenfunction:: simgrid::s4u::Actor::set_auto_restart(bool autorestart)
+      .. doxygenfunction:: simgrid::s4u::Actor::get_restart_count
 
    .. group-tab:: Python
 
@@ -655,8 +657,8 @@ Querying info
       .. autofunction:: simgrid.this_actor.get_host
       .. autofunction:: simgrid.this_actor.set_host
 
-      .. autofunction:: simgrid.this_actor.get_pid()
-      .. autofunction:: simgrid.this_actor.get_ppid()
+      .. autofunction:: simgrid.this_actor.get_pid
+      .. autofunction:: simgrid.this_actor.get_ppid
 
    .. group-tab:: C
 
@@ -700,6 +702,7 @@ Logging messages
 
        .. autofunction:: simgrid.this_actor.debug
        .. autofunction:: simgrid.this_actor.info
+       .. autofunction:: simgrid.this_actor.warning
        .. autofunction:: simgrid.this_actor.error
 
 Sleeping
@@ -740,6 +743,7 @@ the execution, or start an asynchronous activity.
       .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop)
       .. doxygenfunction:: simgrid::s4u::this_actor::execute(double flop, double priority)
       .. doxygenfunction:: simgrid::s4u::this_actor::parallel_execute(const std::vector< s4u::Host * > &hosts, const std::vector< double > &flops_amounts, const std::vector< double > &bytes_amounts)
+      .. doxygenfunction:: simgrid::s4u::this_actor::thread_execute
 
    .. group-tab:: Python
 
@@ -806,7 +810,7 @@ Engin initialization
    .. group-tab:: Python
 
        .. automethod:: simgrid.Engine.__init__
-       .. automethod:: simgrid.Engine.instance
+       .. autoattribute:: simgrid.Engine.instance
 
    .. group-tab:: C
 
@@ -863,7 +867,7 @@ Run the simulation
 
    .. group-tab:: Python
 
-      .. automethod:: simgrid.Engine.get_clock
+      .. autoattribute:: simgrid.Engine.clock
       .. automethod:: simgrid.Engine.run
       .. automethod:: simgrid.Engine.run_until
 
@@ -903,7 +907,7 @@ Retrieving hosts
 
    .. group-tab:: Python
 
-      .. automethod:: simgrid.Engine.get_all_hosts
+      .. autoattribute:: simgrid.Engine.all_hosts
 
    .. group-tab:: C
 
@@ -922,6 +926,10 @@ Retrieving links
       .. doxygenfunction:: simgrid::s4u::Engine::link_by_name
       .. doxygenfunction:: simgrid::s4u::Engine::link_by_name_or_null
 
+   .. group-tab:: Python
+
+      .. autoattribute:: simgrid.Engine.all_links
+
 Interacting with the routing
 ----------------------------
 
@@ -934,7 +942,13 @@ Interacting with the routing
       .. doxygenfunction:: simgrid::s4u::Engine::get_netzone_root
       .. doxygenfunction:: simgrid::s4u::Engine::netpoint_by_name_or_null
       .. doxygenfunction:: simgrid::s4u::Engine::netzone_by_name_or_null
-      .. doxygenfunction:: simgrid::s4u::Engine::set_netzone_root(const NetZone *netzone)
+
+   .. group-tab:: Python
+
+      .. autoattribute:: simgrid.Engine.all_netpoints
+      .. autoattribute:: simgrid.Engine.netzone_root
+      .. automethod:: simgrid.Engine.netpoint_by_name
+      .. automethod:: simgrid.Engine.netzone_by_name
 
 Signals
 -------
@@ -946,6 +960,7 @@ Signals
       .. doxygenfunction:: simgrid::s4u::Engine::on_deadlock_cb
       .. doxygenfunction:: simgrid::s4u::Engine::on_platform_created_cb
       .. doxygenfunction:: simgrid::s4u::Engine::on_platform_creation_cb
+      .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_start_cb
       .. doxygenfunction:: simgrid::s4u::Engine::on_simulation_end_cb
       .. doxygenfunction:: simgrid::s4u::Engine::on_time_advance_cb
 
@@ -1035,6 +1050,7 @@ Sending data
 
       .. automethod:: simgrid.Mailbox.put
       .. automethod:: simgrid.Mailbox.put_async
+      .. automethod:: simgrid.Mailbox.put_init
 
    .. group-tab:: C
 
@@ -1056,7 +1072,7 @@ Receiving data
       .. doxygenfunction:: simgrid::s4u::Mailbox::get(double timeout)
       .. doxygenfunction:: simgrid::s4u::Mailbox::get_async(T **data)
       .. doxygenfunction:: simgrid::s4u::Mailbox::get_init()
-      .. doxygenfunction:: simgrid::s4u::Mailbox::iprobe(int type, bool(*match_fun)(void *, void *, kernel::activity::CommImpl *), void *data)
+      .. doxygenfunction:: simgrid::s4u::Mailbox::iprobe(int type, const std::function<bool(void *, void *, kernel::activity::CommImpl *)>& match_fun, void *data)
       .. doxygenfunction:: simgrid::s4u::Mailbox::listen
       .. doxygenfunction:: simgrid::s4u::Mailbox::ready
 
@@ -1110,6 +1126,11 @@ Resources
    
       .. autoclass:: simgrid.Disk
 
+   .. group-tab:: C
+
+      .. doxygentypedef:: sg_disk_t
+      .. doxygentypedef:: const_sg_disk_t
+
 Basic management
 ----------------
 
@@ -1258,7 +1279,7 @@ Retrieving hosts
 
    .. group-tab:: Python
 
-      See also :py:func:`simgrid.Engine.get_all_hosts`.
+      See also :py:attr:`simgrid.Engine.all_hosts`.
 
       .. automethod:: simgrid.Host.by_name
       .. automethod:: simgrid.Host.current
@@ -1282,7 +1303,7 @@ Modifying characteristics
 
    .. group-tab:: Python
 
-      .. automethod:: simgrid.Host.set_core_count
+      .. autoattribute:: simgrid.Host.core_count
       .. automethod:: simgrid.Host.set_coordinates
       .. automethod:: simgrid.Host.set_sharing_policy
 
@@ -1303,14 +1324,15 @@ Querying info
    .. group-tab:: Python
 
       .. autoattribute:: simgrid.Host.name
+      .. autoattribute:: simgrid.Host.core_count
       .. autoattribute:: simgrid.Host.load
       .. autoattribute:: simgrid.Host.pstate
       .. autoattribute:: simgrid.Host.speed
+      .. autoattribute:: simgrid.Host.available_speed
 
    .. group-tab:: C
 
       .. doxygenfunction:: sg_host_core_count(const_sg_host_t host)
-      .. doxygenfunction:: sg_host_dump(const_sg_host_t ws)
       .. doxygenfunction:: sg_host_get_name(const_sg_host_t host)
       .. doxygenfunction:: sg_host_get_load(const_sg_host_t host)
       .. doxygenfunction:: sg_host_get_speed(const_sg_host_t host)
@@ -1384,13 +1406,11 @@ DVFS
       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_count() const
       .. doxygenfunction:: simgrid::s4u::Host::get_pstate_speed(unsigned long pstate_index) const
       .. doxygenfunction:: simgrid::s4u::Host::set_pstate(unsigned long pstate_index)
-      .. doxygenfunction:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p)
-      .. doxygenfunction:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p)
 
    .. group-tab:: Python
 
-      .. automethod:: simgrid.Host.get_pstate_count
-      .. automethod:: simgrid.Host.get_pstate_speed
+      .. autoattribute:: simgrid.Host.pstate_count
+      .. automethod:: simgrid.Host.pstate_speed
 
    .. group-tab:: C
 
@@ -1400,6 +1420,21 @@ DVFS
       .. doxygenfunction:: sg_host_get_pstate_speed(const_sg_host_t host, unsigned long pstate_index)
       .. doxygenfunction:: sg_host_set_pstate(sg_host_t host, unsigned long pstate)
 
+Dynamic profiles
+----------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenfunction:: simgrid::s4u::Host::set_speed_profile(kernel::profile::Profile *p)
+      .. doxygenfunction:: simgrid::s4u::Host::set_state_profile(kernel::profile::Profile *p)
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Host.set_speed_profile
+      .. automethod:: simgrid.Host.set_state_profile
+
 Execution
 ---------
 
@@ -1430,8 +1465,10 @@ using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
 
    .. group-tab:: Python
 
-      .. automethod:: simgrid.Host.get_netpoint
+      .. autoattribute:: simgrid.Host.netpoint
       .. automethod:: simgrid.Host.create_disk
+         
+      .. automethod:: simgrid.Host.route_to
 
    .. group-tab:: C
 
@@ -1521,6 +1558,8 @@ Retrieving links
 
    .. group-tab:: Python
 
+      See also :py:attr:`simgrid.Engine.all_links`.
+
       .. automethod:: simgrid.Link.by_name
       .. autoattribute:: simgrid.Link.name
 
@@ -1545,6 +1584,11 @@ Querying info
       .. doxygenfunction:: simgrid::s4u::Link::get_usage() const
       .. doxygenfunction:: simgrid::s4u::Link::is_used() const
 
+   .. group-tab:: Python
+
+      .. autoattribute:: simgrid.Link.bandwidth
+      .. autoattribute:: simgrid.Link.latency
+
    .. group-tab:: C
 
       .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link)
@@ -1567,6 +1611,7 @@ Modifying characteristics
 
    .. group-tab:: Python
 
+      .. automethod:: simgrid.Link.set_bandwidth
       .. automethod:: simgrid.Link.set_latency
       .. automethod:: simgrid.Link.set_concurrency_limit
       .. automethod:: simgrid.Link.set_sharing_policy
@@ -1604,6 +1649,14 @@ On/Off
       .. doxygenfunction:: simgrid::s4u::Link::turn_off()
       .. doxygenfunction:: simgrid::s4u::Link::turn_on()
 
+   .. group-tab:: Python
+
+      See also :py:func:`simgrid.Link.set_state_profile`.
+
+      .. automethod:: simgrid.Link.is_on
+      .. automethod:: simgrid.Link.turn_off
+      .. automethod:: simgrid.Link.turn_on
+
 Dynamic profiles
 ----------------
 
@@ -1617,6 +1670,12 @@ See :ref:`howto_churn` for more details.
       .. doxygenfunction:: simgrid::s4u::Link::set_latency_profile(kernel::profile::Profile *profile)
       .. doxygenfunction:: simgrid::s4u::Link::set_state_profile(kernel::profile::Profile *profile)
 
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Link.set_bandwidth_profile
+      .. automethod:: simgrid.Link.set_latency_profile
+      .. automethod:: simgrid.Link.set_state_profile
+
 WIFI links
 ----------
 
@@ -1725,7 +1784,7 @@ Querying info
    .. group-tab:: Python
 
       .. autoattribute:: simgrid.NetZone.name
-      .. automethod:: simgrid.NetZone.get_netpoint
+      .. autoattribute:: simgrid.NetZone.netpoint
 
    .. group-tab:: C
 
@@ -2064,6 +2123,17 @@ Suspending and resuming an activity
       .. doxygenfunction:: simgrid::s4u::Activity::resume
       .. doxygenfunction:: simgrid::s4u::Activity::is_suspended
 
+Signals
+-------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenfunction:: simgrid::s4u::Activity::on_completion_cb
+      .. doxygenfunction:: simgrid::s4u::Activity::on_suspend_cb
+      .. doxygenfunction:: simgrid::s4u::Activity::on_resume_cb
+
 .. _API_s4u_Comm:
 
 =============
@@ -2106,7 +2176,6 @@ Basic management
          #include <simgrid/comm.h>
 
       .. doxygentypedef:: sg_comm_t
-      .. doxygentypedef:: const_sg_comm_t
 
 Querying info
 -------------
@@ -2121,13 +2190,17 @@ Querying info
       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff)
       .. doxygenfunction:: simgrid::s4u::Comm::set_dst_data(void **buff, size_t size)
       .. doxygenfunction:: simgrid::s4u::Comm::detach()
-      .. doxygenfunction:: simgrid::s4u::Comm::detach(void(*clean_function)(void *))
+      .. doxygenfunction:: simgrid::s4u::Comm::detach(const std::function<void(void*)>& clean_function)
       .. doxygenfunction:: simgrid::s4u::Comm::set_payload_size(uint64_t bytes)
       .. doxygenfunction:: simgrid::s4u::Comm::set_rate(double rate)
       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff)
       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data(void *buff, size_t size)
       .. doxygenfunction:: simgrid::s4u::Comm::set_src_data_size(size_t size)
 
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Comm.detach
+
 Life cycle
 ----------
 
@@ -2158,8 +2231,11 @@ also start direct communications as shown below.
 
       .. automethod:: simgrid.Comm.test
       .. automethod:: simgrid.Comm.wait
+      .. automethod:: simgrid.Comm.wait_for
       .. automethod:: simgrid.Comm.wait_all
+      .. automethod:: simgrid.Comm.wait_all_for
       .. automethod:: simgrid.Comm.wait_any
+      .. automethod:: simgrid.Comm.wait_any_for
 
    .. group-tab:: C
 
@@ -2350,8 +2426,8 @@ Life cycle
       .. doxygenfunction:: simgrid::s4u::Io::test
       .. doxygenfunction:: simgrid::s4u::Io::wait
       .. doxygenfunction:: simgrid::s4u::Io::wait_for
-      .. doxygenfunction:: simgrid::s4u::Io::wait_any
-      .. doxygenfunction:: simgrid::s4u::Io::wait_any_for
+      .. doxygenfunction:: simgrid::s4u::Io::wait_any(const std::vector<IoPtr> &ios)
+      .. doxygenfunction:: simgrid::s4u::Io::wait_any_for(const std::vector<IoPtr> &ios, double timeout)
 
    .. group-tab:: Python
 
@@ -2382,7 +2458,15 @@ Synchronization Objects
 ⁣  Mutex
 ==============
 
-.. doxygenclass:: simgrid::s4u::Mutex
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenclass:: simgrid::s4u::Mutex
+
+   .. group-tab:: Python
+
+      .. autoclass:: simgrid.Mutex
 
 Basic management
 ----------------
@@ -2399,6 +2483,21 @@ Basic management
 
          .. doxygenfunction:: simgrid::s4u::Mutex::create()
 
+      .. group-tab:: Python
+
+         .. code-block:: Python
+
+            from simgrid import Mutex
+            mutex = Mutex()
+
+            # Use a context manager to acquire and automatically release the mutex
+            # when leaving the scope.
+            with mutex:
+                # Access shared resource ...
+                pass
+
+         .. automethod:: simgrid.Mutex.__init__
+
       .. group-tab:: C
 
          .. code-block:: C
@@ -2424,6 +2523,12 @@ Locking
          .. doxygenfunction:: simgrid::s4u::Mutex::try_lock()
          .. doxygenfunction:: simgrid::s4u::Mutex::unlock()
 
+      .. group-tab:: Python
+
+         .. automethod:: simgrid.Mutex.lock
+         .. automethod:: simgrid.Mutex.try_lock
+         .. automethod:: simgrid.Mutex.unlock
+
       .. group-tab:: C
 
          .. doxygenfunction:: sg_mutex_lock(sg_mutex_t mutex)
@@ -2436,7 +2541,15 @@ Locking
 ⁣  Barrier
 ================
 
-.. doxygenclass:: simgrid::s4u::Barrier
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenclass:: simgrid::s4u::Barrier
+
+   .. group-tab:: Python
+
+      .. autoclass:: simgrid.Barrier
 
 .. tabs::
 
@@ -2448,10 +2561,19 @@ Locking
 
       .. doxygentypedef:: BarrierPtr
 
-      .. doxygenfunction:: simgrid::s4u::Barrier::Barrier(unsigned int expected_actors)
       .. doxygenfunction:: simgrid::s4u::Barrier::create(unsigned int expected_actors)
       .. doxygenfunction:: simgrid::s4u::Barrier::wait()
 
+   .. group-tab:: Python
+
+      .. code-block:: Python
+
+         from simgrid import Barrier
+         barrier = Barrier(2)
+
+      .. automethod:: simgrid.Barrier.__init__
+      .. automethod:: simgrid.Barrier.wait
+
    .. group-tab:: C
 
       .. code-block:: C
@@ -2459,12 +2581,9 @@ Locking
          #include <simgrid/barrier.hpp>
 
       .. doxygentypedef:: sg_bar_t
-      .. cpp:type:: const s4u_Barrier* const_sg_bar_t
-
-         Pointer to a constant barrier object.
 
       .. doxygenfunction:: sg_barrier_init(unsigned int count)
-      .. doxygenfunction:: sg_barrier_destroy(const_sg_bar_t bar)
+      .. doxygenfunction:: sg_barrier_destroy(sg_bar_t bar)
       .. doxygenfunction:: sg_barrier_wait(sg_bar_t bar)
 
 
@@ -2536,8 +2655,15 @@ Waiting and notifying
 ⁣  Semaphore
 ==================
 
-.. doxygenclass:: simgrid::s4u::Semaphore
+.. tabs::
 
+   .. group-tab:: C++
+
+      .. doxygenclass:: simgrid::s4u::Semaphore
+
+   .. group-tab:: Python
+
+      .. autoclass:: simgrid.Semaphore
 
 Basic management
 ----------------
@@ -2553,6 +2679,19 @@ Basic management
          .. doxygentypedef:: SemaphorePtr
          .. doxygenfunction:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity)
 
+      .. group-tab:: Python
+
+         .. code-block:: Python
+
+            from simgrid import Semaphore
+            semaphore = Semaphore(1)
+            # Automatically acquire the semaphore, and release it after leaving the scope.
+            with semaphore:
+                # Do something with the shared resource
+                pass
+
+         .. automethod:: simgrid.Semaphore.__init__
+
       .. group-tab:: C
 
          .. code-block:: C
@@ -2580,6 +2719,14 @@ Locking
          .. doxygenfunction:: simgrid::s4u::Semaphore::release()
          .. doxygenfunction:: simgrid::s4u::Semaphore::would_block() const
 
+      .. group-tab:: Python
+
+         .. automethod:: simgrid.Semaphore.acquire
+         .. automethod:: simgrid.Semaphore.acquire_timeout
+         .. autoattribute:: simgrid.Semaphore.capacity
+         .. automethod:: simgrid.Semaphore.release
+         .. autoattribute:: simgrid.Semaphore.would_block
+
       .. group-tab:: C
 
          .. doxygenfunction:: sg_sem_acquire(sg_sem_t sem)