From: Martin Quinson Date: Mon, 8 Oct 2018 20:35:55 +0000 (+0200) Subject: improve the doc of s4u::Mailbox X-Git-Tag: v3_22~920 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/6c1487ed9411709f547ffb549cd21a6fb7b0aab2 improve the doc of s4u::Mailbox --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 0c26d1809e..a3c853cf79 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -123,6 +123,9 @@ provides many helper functions to simplify the code of actors. .. |API_s4u_Mailbox| replace:: **Mailbox** +.. |API_s4u_Mailboxes| replace:: **Mailboxes** +.. _API_s4u_Mailboxes: #s4u-mailbox + .. |API_s4u_NetZone| replace:: **NetZone** .. |API_s4u_Barrier| replace:: **Barrier** @@ -213,6 +216,119 @@ Sometimes, you want to change the setting of an activity before it even starts. .. todo:: write this section +.. _s4u_mailbox: + +Mailboxes +********* + +Please also refer to the :ref:`API reference for 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() `, but wait +for the corresponding :cpp:func:`Mailbox::get() `. +You can change this by :ref:`declaring a 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() ` on each mailbox. +Then, use :cpp:func:`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 put() and get() Requests are 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 +declared (it waits until both :cpp:func:`put() ` +and :cpp:func:`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() ` yet. + +To model this in SimGrid, you can declare a specific receiver to a +given mailbox (with the function +:cpp:func:`set_receiver() `). +That way, any :cpp:func:`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() ` + Memory Management ***************** @@ -371,6 +487,8 @@ s4u::Link s4u::Mailbox ============ +Please also refer to the :ref:`full doc on s4u::Mailbox `. + .. doxygentypedef:: MailboxPtr .. doxygenclass:: simgrid::s4u::Mailbox diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp index 5fbcf2f7f7..197b2426f9 100644 --- a/include/simgrid/s4u/Mailbox.hpp +++ b/include/simgrid/s4u/Mailbox.hpp @@ -14,107 +14,7 @@ namespace simgrid { namespace s4u { -/** @brief Mailboxes: Network rendez-vous points. - * - * What are mailboxes? - * - * Rendez-vous point 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. - - * Here are some mechanisms similar to the mailbox in other - * communication systems: 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 interlocutor. In HTTP, - * URLs through which the clients can connect to the servers. In ZeroMQ - * and other queuing systems, 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. This is a big difference to the socket ports for - * example, that are definitely exclusive in receiving. - * - * Mailboxes can optionally have a @i receiver with `simgrid::s4u::Mailbox::set_receiver()`. - * It means that the data exchange starts as soon as the sender has - * done the `put()`, even before the corresponding `get()` - * (usually, it starts as soon as both `put()` and `get()` are posted). - * This is closer to the BSD semantic and can thus help to improve - * the timing accuracy, but this is not mandatory at all. - * - * 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 coming 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 `get_async()` on each mailbox. - * Then, use `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? - * - * Any existing mailbox can be retrieve from its name (which are - * unique strings, just like with twitter tags). This results in a - * versatile mechanism that can be used to build many different - * situations. - * - * For something close to classical socket communications, use - * "hostname:port" as mailbox names, and make sure that only one actor - * reads into that mailbox. It's hard to build a perfectly realistic - * model of the TCP sockets, but most of the time, 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 relevant actor that can deal with the request will handle - * it. - * - * How are sends and receives matched? - * - * The matching algorithm is as simple as a 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. - * - * 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 while in real systems (such as TCP or MPI), the data - * starts to flow as soon as the sender posts it, even if the receiver - * did not post its recv() yet. This can obviously lead to bad - * simulation timings, as the simulated communications do not start at - * the exact same time than the real ones. - * - * If the simulation timings are very important to you, you can - * declare a specific receiver to a given mailbox (with the function - * setReceiver()). That way, any send() 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 receive(). - * - * The API - * - */ +/** @brief Mailboxes: Network rendez-vous points. */ class XBT_PUBLIC Mailbox { friend simgrid::s4u::Comm; friend simgrid::kernel::activity::MailboxImpl;