Merge selected changes from branch 'simgrid-Jesse-McDonald-master-patch-09242'

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

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index be1381f..014a1e9 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -598,7 +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()
+      .. doxygenfunction:: simgrid::s4u::Actor::get_restart_count
 
    .. group-tab:: Python
 
@@ -743,9 +743,11 @@ 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
 
+      .. autofunction:: simgrid.this_actor.exec_async
       .. autofunction:: simgrid.this_actor.exec_init
       .. autofunction:: simgrid.this_actor.execute
 
@@ -907,6 +909,7 @@ Retrieving hosts
    .. group-tab:: Python
 
       .. autoattribute:: simgrid.Engine.all_hosts
+      .. automethod:: simgrid.Engine.host_by_name
 
    .. group-tab:: C
 
@@ -1079,6 +1082,7 @@ Receiving data
 
        .. automethod:: simgrid.Mailbox.get
        .. automethod:: simgrid.Mailbox.get_async
+       .. autoattribute:: simgrid.Mailbox.ready
 
    .. group-tab:: C
 
@@ -1171,7 +1175,7 @@ Querying info
       .. doxygenfunction:: simgrid::s4u::Disk::get_read_bandwidth() const
       .. doxygenfunction:: simgrid::s4u::Disk::get_write_bandwidth() const
       .. doxygenfunction:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value)
-      .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy(Operation op, SharingPolicy policy, const s4u::NonLinearResourceCb& cb = {})
+      .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy
 
    .. group-tab:: Python
 
@@ -1298,11 +1302,12 @@ Modifying characteristics
 
       .. doxygenfunction:: simgrid::s4u::Host::set_core_count(int core_count)
       .. doxygenfunction:: simgrid::s4u::Host::set_coordinates(const std::string& coords)
-      .. doxygenfunction:: simgrid::s4u::Host::set_sharing_policy(SharingPolicy policy, const s4u::NonLinearResourceCb& cb = {})
+      .. doxygenfunction:: simgrid::s4u::Host::set_sharing_policy
 
    .. group-tab:: Python
 
       .. autoattribute:: simgrid.Host.core_count
+         :noindex:
       .. automethod:: simgrid.Host.set_coordinates
       .. automethod:: simgrid.Host.set_sharing_policy
 
@@ -1325,7 +1330,6 @@ Querying info
       .. 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
 
@@ -1408,6 +1412,7 @@ DVFS
 
    .. group-tab:: Python
 
+      .. autoattribute:: simgrid.Host.pstate
       .. autoattribute:: simgrid.Host.pstate_count
       .. automethod:: simgrid.Host.pstate_speed
 
@@ -1606,7 +1611,7 @@ Modifying characteristics
       .. doxygenfunction:: simgrid::s4u::Link::set_latency(double value)
       .. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value)
       .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
-      .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy(SharingPolicy policy, const NonLinearResourceCb& cb = {})
+      .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
 
    .. group-tab:: Python
 
@@ -1865,16 +1870,16 @@ Zones
 
   .. group-tab:: C++
 
-     .. doxygenfunction:: simgrid::s4u::create_full_zone(const std::string& name)
-     .. doxygenfunction:: simgrid::s4u::create_empty_zone(const std::string& name)
-     .. doxygenfunction:: simgrid::s4u::create_star_zone(const std::string& name)
-     .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone(const std::string& name, bool cache)
-     .. doxygenfunction:: simgrid::s4u::create_floyd_zone(const std::string& name)
-     .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone(const std::string& name)
-     .. doxygenfunction:: simgrid::s4u::create_wifi_zone(const std::string& name)
+     .. doxygenfunction:: simgrid::s4u::create_full_zone
+     .. doxygenfunction:: simgrid::s4u::create_empty_zone
+     .. doxygenfunction:: simgrid::s4u::create_star_zone
+     .. doxygenfunction:: simgrid::s4u::create_dijkstra_zone
+     .. doxygenfunction:: simgrid::s4u::create_floyd_zone
+     .. doxygenfunction:: simgrid::s4u::create_vivaldi_zone
+     .. doxygenfunction:: simgrid::s4u::create_wifi_zone
      .. doxygenfunction:: simgrid::s4u::create_torus_zone
-     .. doxygenfunction:: simgrid::s4u::create_fatTree_zone(const std::string& name, const NetZone* parent, const FatTreeParams& parameters, const ClusterCallbacks& set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
-     .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone(const std::string& name, const NetZone* parent, const DragonflyParams& parameters, const ClusterCallbacks& set_callbacks, double bandwidth, double latency, Link::SharingPolicy sharing_policy)
+     .. doxygenfunction:: simgrid::s4u::create_fatTree_zone
+     .. doxygenfunction:: simgrid::s4u::create_dragonfly_zone
 
   .. group-tab:: Python
 
@@ -2122,6 +2127,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_suspended_cb
+      .. doxygenfunction:: simgrid::s4u::Activity::on_resumed_cb
+
 .. _API_s4u_Comm:
 
 =============
@@ -2187,7 +2203,13 @@ Querying info
 
    .. group-tab:: Python
 
+      .. autoattribute:: simgrid.Comm.dst_data_size
+      .. autoattribute:: simgrid.Comm.mailbox
+      .. autoattribute:: simgrid.Comm.sender
+      .. autoattribute:: simgrid.Comm.state_str
       .. automethod:: simgrid.Comm.detach
+      .. automethod:: simgrid.Comm.set_payload_size
+      .. automethod:: simgrid.Comm.set_rate
 
 Life cycle
 ----------
@@ -2214,16 +2236,25 @@ also start direct communications as shown below.
       .. doxygenfunction:: simgrid::s4u::Comm::wait_any(const std::vector< CommPtr >& comms)
       .. doxygenfunction:: simgrid::s4u::Comm::wait_any_for(const std::vector< CommPtr >& comms, double timeout)
       .. doxygenfunction:: simgrid::s4u::Comm::wait_for
+      .. doxygenfunction:: simgrid::s4u::Comm::wait_until
 
    .. group-tab:: Python
 
+      .. automethod:: simgrid.Comm.sendto
+      .. automethod:: simgrid.Comm.sendto_init
+      .. automethod:: simgrid.Comm.sendto_async
+
+      .. automethod:: simgrid.Comm.cancel
+      .. automethod:: simgrid.Comm.start
       .. automethod:: simgrid.Comm.test
+      .. automethod:: simgrid.Comm.test_any
       .. 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
+      .. automethod:: simgrid.Comm.wait_until
 
    .. group-tab:: C
 
@@ -2414,8 +2445,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
 
@@ -2484,6 +2515,8 @@ Basic management
                 # Access shared resource ...
                 pass
 
+         .. automethod:: simgrid.Mutex.__init__
+
       .. group-tab:: C
 
          .. code-block:: C
@@ -2511,9 +2544,9 @@ Locking
 
       .. group-tab:: Python
 
-         .. automethod:: simgrid.Mutex.lock()
-         .. automethod:: simgrid.Mutex.try_lock()
-         .. automethod:: simgrid.Mutex.unlock()
+         .. automethod:: simgrid.Mutex.lock
+         .. automethod:: simgrid.Mutex.try_lock
+         .. automethod:: simgrid.Mutex.unlock
 
       .. group-tab:: C
 
@@ -2527,7 +2560,15 @@ Locking
 ⁣  Barrier
 ================
 
-.. doxygenclass:: simgrid::s4u::Barrier
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenclass:: simgrid::s4u::Barrier
+
+   .. group-tab:: Python
+
+      .. autoclass:: simgrid.Barrier
 
 .. tabs::
 
@@ -2539,10 +2580,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
@@ -2624,8 +2674,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
 ----------------
@@ -2641,6 +2698,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
@@ -2668,6 +2738,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)