+
+.. todo:: write this section
+
+.. _s4u_mailbox:
+
+Mailboxes
+*********
+
+Please also refer to the :ref:`API reference for s4u::Mailbox
+<API_s4u_Mailbox>`.
+
+===================
+What are Mailboxes?
+===================
+
+|API_s4u_Mailboxes|_ are rendez-vous points for network communications,
+similar to URLs on which you could post and retrieve data. Actually,
+the mailboxes are not involved in the communication once it starts,
+but only to find the contact with which you want to communicate.
+
+They are similar to many common things: The phone number, which allows
+the caller to find the receiver. The twitter hashtag, which help
+senders and receivers to find each others. In TCP, the pair
+``{host name, host port}`` to which you can connect to find your peer.
+In HTTP, URLs through which the clients can connect to the servers.
+In ZeroMQ, the queues are used to match senders and receivers.
+
+One big difference with most of these systems is that no actor is the
+exclusive owner of a mailbox, neither in sending nor in receiving.
+Many actors can send into and/or receive from the same mailbox. TCP
+socket ports for example are shared on the sender side but exclusive
+on the receiver side (only one process can receive from a given socket
+at a given point of time).
+
+A big difference with TCP sockets or MPI communications is that
+communications do not start right away after a
+:cpp:func:`Mailbox::put() <simgrid::s4u::Mailbox::put()>`, but wait
+for the corresponding :cpp:func:`Mailbox::get() <simgrid::s4u::Mailbox::get()>`.
+You can change this by :ref:`declaring a receiving actor <s4u_receiving_actor>`.
+
+A big difference with twitter hashtags is that SimGrid does not
+offer easy support to broadcast a given message to many
+receivers. So that would be like a twitter tag where each message
+is consumed by the first receiver.
+
+A big difference with the ZeroMQ queues is that you cannot filter
+on the data you want to get from the mailbox. To model such settings
+in SimGrid, you'd have one mailbox per potential topic, and subscribe
+to each topic individually with a
+:cpp:func:`get_async() <simgrid::s4u::Mailbox::get_async()>` on each mailbox.
+Then, use :cpp:func:`Comm::wait_any() <simgrid::s4u::Comm::wait_any()>`
+to get the first message on any of the mailbox you are subscribed onto.
+
+The mailboxes are not located on the network, and you can access
+them without any latency. The network delay are only related to the
+location of the sender and receiver once the match between them is
+done on the mailbox. This is just like the phone number that you
+can use locally, and the geographical distance only comes into play
+once you start the communication by dialing this number.
+
+=====================
+How to use Mailboxes?
+=====================
+
+You can retrieve any existing mailbox from its name (which is a
+unique string, just like a twitter tag). This results in a
+versatile mechanism that can be used to build many different
+situations.
+
+To model classical socket communications, use "hostname:port" as
+mailbox names, and make sure that only one actor reads into a given
+mailbox. This does not make it easy to build a perfectly realistic
+model of the TCP sockets, but in most cases, this system is too
+cumbersome for your simulations anyway. You probably want something
+simpler, that turns our to be easy to build with the mailboxes.
+
+Many SimGrid examples use a sort of yellow page system where the
+mailbox names are the name of the service (such as "worker",
+"master" or "reducer"). That way, you don't have to know where your
+peer is located to contact it. You don't even need its name. Its
+function is enough for that. This also gives you some sort of load
+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 are put() and get() requests matched?
+=========================================
+
+The matching algorithm simple: first come, first serve. When a new
+send arrives, it matches the oldest enqueued receive. If no receive is
+currently enqueued, then the incoming send is enqueued. As you can
+see, the mailbox cannot contain both send and receive requests: all
+enqueued requests must be of the same sort.
+
+.. _s4u_receiving_actor:
+
+===========================
+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
+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
+its :cpp:func:`recv() <simgrid::s4u::Mailbox::recv()>` yet.
+
+To model this in SimGrid, you can declare a specific receiver to a
+given mailbox (with the function
+:cpp:func:`set_receiver() <simgrid::s4u::Mailbox::set_receiver()>`).
+That way, any :cpp:func:`put() <simgrid::s4u::Mailbox::put()>`
+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
+*****************
+
+For sake of simplicity, we use `RAII
+<https://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization>`_
+everywhere in S4U. This is an idiom where resources are automatically
+managed through the context. Provided that you never manipulate
+objects of type Foo directly but always FooPtr references (which are
+defined as `boost::intrusive_ptr
+<http://www.boost.org/doc/libs/1_61_0/libs/smart_ptr/intrusive_ptr.html>`_
+<Foo>), you will never have to explicitely release the resource that
+you use nor to free the memory of unused objects.
+
+Here is a little example:
+
+.. code-block:: cpp
+
+ void myFunc()
+ {
+ simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new`
+
+ mutex->lock(); // use the mutex as a simple reference
+ // bla bla
+ mutex->unlock();
+
+ } // The mutex gets automatically freed because the only existing reference gets out of scope
+
+C++ API Reference
+*****************
+
+.. _API_s4u_this_actor:
+
+=========================
+namespace s4u::this_actor
+=========================
+
+.. doxygennamespace:: simgrid::s4u::this_actor
+.. _API_s4u_Activity:
+
+=============
+s4u::Activity
+=============
+
+.. doxygenclass:: simgrid::s4u::Activity
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Actor:
+
+==========
+s4u::Actor
+==========
+
+.. doxygentypedef:: ActorPtr
+
+.. doxygentypedef:: aid_t
+
+.. doxygenclass:: simgrid::s4u::Actor
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Barrier:
+
+============
+s4u::Barrier
+============
+
+.. doxygentypedef:: BarrierPtr
+
+.. doxygenclass:: simgrid::s4u::Barrier
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Comm:
+
+=========
+s4u::Comm
+=========
+
+.. doxygentypedef:: CommPtr
+
+.. doxygenclass:: simgrid::s4u::Comm
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_ConditionVariable:
+
+======================
+s4u::ConditionVariable
+======================
+
+.. doxygentypedef:: ConditionVariablePtr
+
+.. doxygenclass:: simgrid::s4u::ConditionVariable
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Engine:
+
+===========
+s4u::Engine
+===========
+
+.. doxygenclass:: simgrid::s4u::Engine
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Exec:
+
+=========
+s4u::Exec
+=========
+
+.. doxygentypedef:: ExecPtr
+
+.. doxygenclass:: simgrid::s4u::Exec
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Host:
+
+=========
+s4u::Host
+=========
+
+.. doxygenclass:: simgrid::s4u::Host
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Io:
+
+=======
+s4u::Io
+=======
+
+.. doxygentypedef:: IoPtr
+
+.. doxygenclass:: simgrid::s4u::Io
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Link:
+
+=========
+s4u::Link
+=========
+
+.. doxygenclass:: simgrid::s4u::Link
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Mailbox:
+
+============
+s4u::Mailbox
+============
+
+Please also refer to the :ref:`full doc on s4u::Mailbox <s4u_mailbox>`.
+
+.. doxygentypedef:: MailboxPtr
+
+.. doxygenclass:: simgrid::s4u::Mailbox
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Mutex:
+
+==========
+s4u::Mutex
+==========
+
+.. doxygentypedef:: MutexPtr
+
+.. doxygenclass:: simgrid::s4u::Mutex
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_NetZone:
+
+============
+s4u::NetZone
+============
+
+.. doxygenclass:: simgrid::s4u::NetZone
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Semaphore:
+
+==============
+s4u::Semaphore
+==============
+
+.. doxygentypedef:: SemaphorePtr
+
+.. doxygenclass:: simgrid::s4u::Semaphore
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_Storage:
+
+============
+s4u::Storage
+============
+
+.. doxygenclass:: simgrid::s4u::Storage
+ :members:
+ :protected-members:
+ :undoc-members:
+
+.. _API_s4u_VirtualMachine:
+
+===================
+s4u::VirtualMachine
+===================
+
+.. doxygenclass:: simgrid::s4u::VirtualMachine
+ :members:
+ :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: