Release SimGrid v3.27

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

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index a605c7a..8b50a25 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -334,6 +334,26 @@ that are marked as permanent receiver, you should call
 memory gets properly reclaimed. This call should be at the end of the
 actor's function, not in an on_exit callback.
 
+===============================
+Communicating without Mailboxes
+===============================
+
+Sometimes you don't want to simulate communications between actors as
+allowed by mailboxes, but you want to create a direct communication
+between two arbitrary hosts. This can arise when you write a
+high-level model of a centralized scheduler, or when you model direct
+communications such as one-sided communications in MPI or remote
+memory direct access in PGAS.
+
+For that, :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`
+simulates a direct communication between the two specified hosts. No
+mailbox is used, and there is no rendezvous between actors. You can
+freely mix such direct communications and rendezvous-based
+communications. Alternatively, :cpp:func:`Comm::sendto_init()
+<simgrid::s4u::Comm::sendto_init()>` and
+:cpp:func:`Comm::sendto_async() <simgrid::s4u::Comm::sendto_async()>`
+create asynchronous direct communications.
+
 .. _s4u_raii:
 
 Memory Management
@@ -409,6 +429,8 @@ Basic management
 
          from simgrid import Actor
 
+      .. autoclass:: simgrid.Actor
+
    .. group-tab:: C
 
       .. code:: C
@@ -445,9 +467,9 @@ Creating actors
 
    .. group-tab:: C
 
-      .. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, const char *const *argv)
+      .. doxygenfunction:: sg_actor_create(const char *name, sg_host_t host, xbt_main_func_t code, int argc, char *const *argv)
       .. doxygenfunction:: sg_actor_init(const char *name, sg_host_t host)
-      .. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, const char *const *argv)
+      .. doxygenfunction:: sg_actor_start(sg_actor_t actor, xbt_main_func_t code, int argc, char *const *argv)
 
       .. doxygenfunction:: sg_actor_attach(const char *name, void *data, sg_host_t host, xbt_dict_t properties)
       .. doxygenfunction:: sg_actor_detach()
@@ -469,7 +491,7 @@ Retrieving actors
 
    .. group-tab:: C
 
-      .. doxygenfunction:: sg_actor_by_PID(aid_t pid)
+      .. doxygenfunction:: sg_actor_by_pid(aid_t pid)
       .. doxygenfunction:: sg_actor_self()
 
 Querying info
@@ -503,8 +525,8 @@ Querying info
    .. group-tab:: C
 
       .. doxygenfunction:: sg_actor_get_name(const_sg_actor_t actor)
-      .. doxygenfunction:: sg_actor_get_PID(const_sg_actor_t actor)
-      .. doxygenfunction:: sg_actor_get_PPID(const_sg_actor_t actor)
+      .. doxygenfunction:: sg_actor_get_pid(const_sg_actor_t actor)
+      .. doxygenfunction:: sg_actor_get_ppid(const_sg_actor_t actor)
       .. doxygenfunction:: sg_actor_get_properties(const_sg_actor_t actor)
       .. doxygenfunction:: sg_actor_get_property_value(const_sg_actor_t actor, const char *name)
 
@@ -591,6 +613,7 @@ Reacting to the end of actors
 
    .. group-tab:: C
 
+      .. doxygenfunction:: sg_actor_on_exit
       .. doxygenfunction:: sg_actor_join(const_sg_actor_t actor, double timeout)
       .. doxygenfunction:: sg_actor_set_auto_restart(sg_actor_t actor, int auto_restart)
 
@@ -748,6 +771,12 @@ Exiting
       .. autofunction:: simgrid.this_actor.exit
       .. autofunction:: simgrid.this_actor.on_exit
 
+   .. group-tab:: c
+
+      See also :cpp:func:`sg_actor_on_exit`.
+
+      .. doxygenfunction:: sg_actor_exit
+
 .. _API_s4u_Engine:
 
 ====================
@@ -925,15 +954,24 @@ Basic management
 
    .. group-tab:: Python
 
+      .. code-block:: C++
+
+         #include <simgrid/mailbox.h>
+
+      .. autoclass:: simgrid.Mailbox
+
       .. automethod:: simgrid.Mailbox.by_name
 
+   .. group-tab:: C
+
       .. code-block:: C
 
          #include <simgrid/s4u/mailbox.h>
       
-      .. doxygenfunction:: sg_mailbox_by_name(const char *alias)
+      .. doxygentypedef:: sg_mailbox_t
+      .. doxygentypedef:: const_sg_mailbox_t
 
-   .. group-tab:: C
+      .. doxygenfunction:: sg_mailbox_by_name(const char *alias)
 
 Querying info
 -------------
@@ -1282,6 +1320,9 @@ Execution
 Platform and routing
 --------------------
 
+You can also start direct communications between two arbitrary hosts
+using :cpp:func:`Comm::sendto() <simgrid::s4u::Comm::sendto()>`.
+
 .. tabs::
 
    .. group-tab:: C++
@@ -1290,8 +1331,6 @@ Platform and routing
       .. doxygenfunction:: simgrid::s4u::Host::get_netpoint() const
       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< Link * > &links, double *latency) const
       .. doxygenfunction:: simgrid::s4u::Host::route_to(const Host *dest, std::vector< kernel::resource::LinkImpl * > &links, double *latency) const
-      .. doxygenfunction:: simgrid::s4u::Host::sendto(Host *dest, double byte_amount)
-      .. doxygenfunction:: simgrid::s4u::Host::sendto_async(Host *dest, double byte_amount)
 
    .. group-tab:: C
 
@@ -1799,6 +1838,17 @@ Basic management
 
          from simgrid import Comm
 
+      .. autoclass:: simgrid.Comm
+
+   .. group-tab:: c
+
+      .. code:: c
+
+         #include <simgrid/comm.h>
+
+      .. doxygentypedef:: sg_comm_t
+      .. doxygentypedef:: const_sg_comm_t
+
 Querying info
 -------------
 
@@ -1813,6 +1863,7 @@ Querying info
       .. 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::set_payload_size(double 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)
@@ -1821,10 +1872,17 @@ Querying info
 Life cycle
 ----------
 
+Most communications are created using :ref:`s4u_mailbox`, but you can
+also start direct communications as shown below.
+
 .. tabs::
 
    .. group-tab:: C++
 
+      .. doxygenfunction:: simgrid::s4u::Comm::sendto
+      .. doxygenfunction:: simgrid::s4u::Comm::sendto_init
+      .. doxygenfunction:: simgrid::s4u::Comm::sendto_async
+      
       .. doxygenfunction:: simgrid::s4u::Comm::cancel
       .. doxygenfunction:: simgrid::s4u::Comm::start
       .. doxygenfunction:: simgrid::s4u::Comm::test
@@ -1878,13 +1936,18 @@ Basic management
       .. code:: Python
 
          from simgrid import Exec
-        
+
+      .. autoclass:: simgrid.Exec
+
    .. group-tab:: C
 
       .. code-block:: C
 
          #include <simgrid/exec.h>
 
+      .. doxygentypedef:: sg_exec_t
+      .. doxygentypedef:: const_sg_exec_t
+
 Querying info
 -------------
 
@@ -2139,6 +2202,7 @@ Basic management
             #include <simgrid/cond.h>
 
          .. doxygentypedef:: sg_cond_t
+         .. doxygentypedef:: const_sg_cond_t
          .. doxygenfunction:: sg_cond_init
          .. doxygenfunction:: sg_cond_destroy