doc cosmetics, and cleanup the API

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

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 7fb6664..3f3aaec 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -56,7 +56,10 @@ synchronization mechanisms** such as |API_s4u_Barrier|_, |API_s4u_Semaphore|_,
 Each actor is located on a simulated |API_s4u_Host|_. Each host is located
 itself in a |API_s4u_NetZone|_, that knows the networking path between one
 resource to another. Each NetZone is included in another one, forming
-a tree of NetZones which root zone contains the whole platform.
+a tree of NetZones which root zone contains the whole platform. The
+actors can also be located on a |API_s4U_VirtualMachine|_ that may
+restrict the activities it contains to a limited amount of cores.
+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.
@@ -116,8 +119,7 @@ provides many helper functions to simplify the code of actors.
 .. |API_s4u_Storages| replace:: **Storages**
 .. _API_s4u_Storages: #s4u-storage
 
-.. |API_s4u_VirtualMachines| replace:: **VirtualMachines**
-.. _API_s4u_VirtualMachines: #s4u-virtualmachine
+.. |API_s4u_VirtualMachine| replace:: **VirtualMachines**
 
 .. |API_s4u_Host| replace:: **Host**
 
@@ -298,7 +300,7 @@ balancing for free if more than one actor pulls from the mailbox:
 the first actor that can deal with the request will handle it.
 
 =========================================
-How put() and get() Requests are Matched?
+How are put() and get() requests matched?
 =========================================
 
 The matching algorithm simple: first come, first serve. When a new
@@ -315,7 +317,7 @@ Declaring a Receiving Actor
 
 The last twist is that by default in the simulator, the data starts
 to be exchanged only when both the sender and the receiver are
-declared (it waits until both :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
+announced (it waits until both :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
 and :cpp:func:`get() <simgrid::s4u::Mailbox::get()>` are posted). 
 In TCP, since you establish connexions beforehand, the data starts to
 flow as soon as the sender posts it, even if the receiver did not post
@@ -329,6 +331,13 @@ posted to that mailbox will start as soon as possible, and the data
 will already be there on the receiver host when the receiver actor
 posts its :cpp:func:`get() <simgrid::s4u::Mailbox::get()>`
 
+Note that being permanent receivers of a mailbox prevents actors to be
+garbage-collected. If your simulation creates many short-lived actors
+that marked as permanent receiver, you should call
+``mailbox->set_receiver(nullptr)`` by the end of the actors so that their
+memory gets properly reclaimed. This call should be at the end of the
+actor's function, not in a on_exit callback.
+
 Memory Management
 *****************
 
@@ -356,8 +365,8 @@ Here is a little example:
   
    } // The mutex gets automatically freed because the only existing reference gets out of scope
 
-API Reference
-*************
+C++ API Reference
+*****************
 
 .. _API_s4u_this_actor:
 
@@ -385,6 +394,8 @@ s4u::Actor
 
 .. doxygentypedef:: ActorPtr
 
+.. doxygentypedef:: aid_t
+
 .. doxygenclass:: simgrid::s4u::Actor
    :members:
    :protected-members:
@@ -562,3 +573,44 @@ s4u::VirtualMachine
    :protected-members:
    :undoc-members:
 
+
+Python API Reference
+********************
+
+The Python API is generated with pybind11. It closely mimicks the C++
+API, to which you should refer for more information.
+
+==========
+this_actor
+==========
+
+.. automodule:: simgrid.this_actor
+   :members:
+
+===========
+Class Actor
+===========
+
+.. autoclass:: simgrid.Actor
+   :members:
+
+============
+Class Engine
+============
+
+.. autoclass:: simgrid.Engine
+   :members:
+
+==========
+Class Host
+==========
+
+.. autoclass:: simgrid.Host
+   :members:
+
+=============
+Class Mailbox
+=============
+
+.. autoclass:: simgrid.Mailbox
+   :members: