X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d4cc1617632cd9d23affa1338ba0bf7d4b0efd0e..717bb82fd56727b8a066418eaa654290373736ea:/include/simgrid/s4u/Mailbox.hpp diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp index ebc45a4317..197b2426f9 100644 --- a/include/simgrid/s4u/Mailbox.hpp +++ b/include/simgrid/s4u/Mailbox.hpp @@ -14,112 +14,10 @@ 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 { -#ifndef DOXYGEN - friend Comm; + friend simgrid::s4u::Comm; friend simgrid::kernel::activity::MailboxImpl; -#endif simgrid::kernel::activity::MailboxImpl* pimpl_;