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 f43e02d..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
@@ -447,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()
@@ -471,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
@@ -505,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)
 
@@ -1300,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++
@@ -1308,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
 
@@ -1851,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