include/simgrid/s4u/Mailbox.hpp

   1 /* Copyright (c) 2006-2018. The SimGrid Team. All rights reserved.          */
   2
   3 /* This program is free software; you can redistribute it and/or modify it
   4  * under the terms of the license (GNU LGPL) which comes with this package. */
   5
   6 #ifndef SIMGRID_S4U_MAILBOX_HPP
   7 #define SIMGRID_S4U_MAILBOX_HPP
   8
   9 #include <xbt/string.hpp>
  10 #include <simgrid/s4u/Actor.hpp>
  11
  12 #include <string>
  13
  14 namespace simgrid {
  15 namespace s4u {
  16
  17 /** @brief Mailboxes: Network rendez-vous points.
  18  *
  19  * <b>What are mailboxes?</b>
  20  *
  21  * Rendez-vous point for network communications, similar to URLs on
  22  * which you could post and retrieve data. Actually, the mailboxes are
  23  * not involved in the communication once it starts, but only to find
  24  * the contact with which you want to communicate.
  25
  26  * Here are some mechanisms similar to the mailbox in other
  27  * communication systems: The phone number, which allows the caller to
  28  * find the receiver. The twitter hashtag, which help senders and
  29  * receivers to find each others. In TCP, the pair {host name, host
  30  * port} to which you can connect to find your interlocutor. In HTTP,
  31  * URLs through which the clients can connect to the servers. In ZeroMQ
  32  * and other queuing systems, the queues are used to match senders
  33  * and receivers.
  34  *
  35  * One big difference with most of these systems is that no actor is
  36  * the exclusive owner of a mailbox, neither in sending nor in
  37  * receiving. Many actors can send into and/or receive from the
  38  * same mailbox.  This is a big difference to the socket ports for
  39  * example, that are definitely exclusive in receiving.
  40  *
  41  * Mailboxes can optionally have a @i receiver with `simgrid::s4u::Mailbox::set_receiver()`.
  42  * It means that the data exchange starts as soon as the sender has
  43  * done the `put()`, even before the corresponding `get()`
  44  * (usually, it starts as soon as both  `put()` and `get()` are posted).
  45  * This is closer to the BSD semantic and can thus help to improve
  46  * the timing accuracy, but this is not mandatory at all.
  47  *
  48  * A big difference with twitter hashtags is that SimGrid does not
  49  * offer easy support to broadcast a given message to many
  50  * receivers. So that would be like a twitter tag where each message
  51  * is consumed by the first coming receiver.
  52  *
  53  * A big difference with the ZeroMQ queues is that you cannot filter
  54  * on the data you want to get from the mailbox. To model such settings
  55  * in SimGrid, you'd have one mailbox per potential topic, and subscribe
  56  * to each topic individually with a `get_async()` on each mailbox.
  57  * Then, use `Comm::wait_any()` to get the first message on any of the
  58  * mailbox you are subscribed onto.
  59  *
  60  * The mailboxes are not located on the network, and you can access
  61  * them without any latency. The network delay are only related to the
  62  * location of the sender and receiver once the match between them is
  63  * done on the mailbox. This is just like the phone number that you
  64  * can use locally, and the geographical distance only comes into play
  65  * once you start the communication by dialing this number.
  66  *
  67  * <b>How to use mailboxes?</b>
  68  *
  69  * Any existing mailbox can be retrieve from its name (which are
  70  * unique strings, just like with twitter tags). This results in a
  71  * versatile mechanism that can be used to build many different
  72  * situations.
  73  *
  74  * For something close to classical socket communications, use
  75  * "hostname:port" as mailbox names, and make sure that only one actor
  76  * reads into that mailbox. It's hard to build a perfectly realistic
  77  * model of the TCP sockets, but most of the time, this system is too
  78  * cumbersome for your simulations anyway. You probably want something
  79  * simpler, that turns our to be easy to build with the mailboxes.
  80  *
  81  * Many SimGrid examples use a sort of yellow page system where the
  82  * mailbox names are the name of the service (such as "worker",
  83  * "master" or "reducer"). That way, you don't have to know where your
  84  * peer is located to contact it. You don't even need its name. Its
  85  * function is enough for that. This also gives you some sort of load
  86  * balancing for free if more than one actor pulls from the mailbox:
  87  * the first relevant actor that can deal with the request will handle
  88  * it.
  89  *
  90  * <b>How are sends and receives matched?</b>
  91  *
  92  * The matching algorithm is as simple as a first come, first
  93  * serve. When a new send arrives, it matches the oldest enqueued
  94  * receive. If no receive is currently enqueued, then the incoming
  95  * send is enqueued. As you can see, the mailbox cannot contain both
  96  * send and receive requests: all enqueued requests must be of the
  97  * same sort.
  98  *
  99  * <b>Declaring a receiving actor</b>
 100  *
 101  * The last twist is that by default in the simulator, the data starts
 102  * to be exchanged only when both the sender and the receiver are
 103  * declared while in real systems (such as TCP or MPI), the data
 104  * starts to flow as soon as the sender posts it, even if the receiver
 105  * did not post its recv() yet. This can obviously lead to bad
 106  * simulation timings, as the simulated communications do not start at
 107  * the exact same time than the real ones.
 108  *
 109  * If the simulation timings are very important to you, you can
 110  * declare a specific receiver to a given mailbox (with the function
 111  * setReceiver()). That way, any send() posted to that mailbox will
 112  * start as soon as possible, and the data will already be there on
 113  * the receiver host when the receiver actor posts its receive().
 114  *
 115  * <b>The API</b>
 116  *
 117  */
 118 class XBT_PUBLIC Mailbox {
 119 #ifndef DOXYGEN
 120   friend Comm;
 121   friend simgrid::kernel::activity::MailboxImpl;
 122 #endif
 123
 124   simgrid::kernel::activity::MailboxImpl* pimpl_;
 125
 126   explicit Mailbox(kernel::activity::MailboxImpl * mbox) : pimpl_(mbox) {}
 127
 128   /** private function to manage the mailboxes' lifetime (see @ref s4u_raii) */
 129   friend void intrusive_ptr_add_ref(Mailbox*) {}
 130   /** private function to manage the mailboxes' lifetime (see @ref s4u_raii) */
 131   friend void intrusive_ptr_release(Mailbox*) {}
 132 public:
 133   /** private function, do not use. FIXME: make me protected */
 134   kernel::activity::MailboxImpl* get_impl() { return pimpl_; }
 135
 136   /** @brief Retrieves the name of that mailbox as a C++ string */
 137   const simgrid::xbt::string& get_name() const;
 138   /** @brief Retrieves the name of that mailbox as a C string */
 139   const char* get_cname() const;
 140
 141   /** Retrieve the mailbox associated to the given name */
 142   static MailboxPtr by_name(std::string name);
 143
 144   /** Returns whether the mailbox contains queued communications */
 145   bool empty();
 146
 147   /** Check if there is a communication going on in a mailbox. */
 148   bool listen();
 149
 150   /** Check if there is a communication ready to be consumed from a mailbox. */
 151   bool ready();
 152
 153   /** Gets the first element in the queue (without dequeuing it), or nullptr if none is there */
 154   smx_activity_t front();
 155
 156   /** Declare that the specified actor is a permanent receiver on that mailbox
 157    *
 158    * It means that the communications sent to this mailbox will start flowing to
 159    * its host even before he does a recv(). This models the real behavior of TCP
 160    * and MPI communications, amongst other. It will improve the accuracy of
 161    * predictions, in particular if your application exhibits swarms of small messages.
 162    *
 163    * SimGrid does not enforces any kind of ownership over the mailbox. Even if a receiver
 164    * was declared, any other actors can still get() data from the mailbox. The timings
 165    * will then probably be off tracks, so you should strive on your side to not get data
 166    * from someone else's mailbox.
 167    */
 168   void set_receiver(ActorPtr actor);
 169
 170   /** Return the actor declared as permanent receiver, or nullptr if none **/
 171   ActorPtr get_receiver();
 172
 173   /** Creates (but don't start) a data emission to that mailbox */
 174   CommPtr put_init();
 175   /** Creates (but don't start) a data emission to that mailbox */
 176   CommPtr put_init(void* data, uint64_t simulated_size_in_bytes);
 177   /** Creates and start a data emission to that mailbox */
 178   CommPtr put_async(void* data, uint64_t simulated_size_in_bytes);
 179
 180   /** Blocking data emission */
 181   void put(void* payload, uint64_t simulated_size_in_bytes);
 182   /** Blocking data emission with timeout */
 183   void put(void* payload, uint64_t simulated_size_in_bytes, double timeout);
 184
 185   /** Creates (but don't start) a data reception onto that mailbox */
 186   CommPtr get_init();
 187   /** Creates and start an async data reception to that mailbox */
 188   CommPtr get_async(void** data);
 189
 190   /** Blocking data reception */
 191   void* get(); // FIXME: make a typed template version
 192   /** Blocking data reception with timeout */
 193   void* get(double timeout);
 194
 195   // Deprecated functions
 196   /** @deprecated Mailbox::set_receiver() */
 197   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::set_receiver()") void setReceiver(ActorPtr actor)
 198   {
 199     set_receiver(actor);
 200   }
 201   /** @deprecated Mailbox::get_receiver() */
 202   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_receiver()") ActorPtr getReceiver() { return get_receiver(); }
 203   /** @deprecated Mailbox::get_name() */
 204   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_name()") const simgrid::xbt::string& getName() const
 205   {
 206     return get_name();
 207   }
 208   /** @deprecated Mailbox::get_cname() */
 209   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_cname()") const char* getCname() const { return get_cname(); }
 210   /** @deprecated Mailbox::get_impl() */
 211   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_impl()") kernel::activity::MailboxImpl* getImpl()
 212   {
 213     return get_impl();
 214   }
 215   /** @deprecated Mailbox::by_name() */
 216   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::by_name()") static MailboxPtr byName(const char* name)
 217   {
 218     return by_name(name);
 219   }
 220   /** @deprecated Mailbox::by_name() */
 221   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::by_name()") static MailboxPtr byName(std::string name)
 222   {
 223     return by_name(name);
 224   }
 225 };
 226
 227 }} // namespace simgrid::s4u
 228
 229 #endif /* SIMGRID_S4U_MAILBOX_HPP */