include/simgrid/s4u/Mailbox.hpp

   1 /* Copyright (c) 2006-2019. 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 class XBT_PUBLIC Mailbox {
  19   friend Comm;
  20   friend kernel::activity::MailboxImpl;
  21
  22   kernel::activity::MailboxImpl* const pimpl_;
  23
  24   explicit Mailbox(kernel::activity::MailboxImpl * mbox) : pimpl_(mbox) {}
  25
  26 public:
  27   /** private function, do not use. FIXME: make me protected */
  28   kernel::activity::MailboxImpl* get_impl() { return pimpl_; }
  29
  30   /** @brief Retrieves the name of that mailbox as a C++ string */
  31   const xbt::string& get_name() const;
  32   /** @brief Retrieves the name of that mailbox as a C string */
  33   const char* get_cname() const;
  34
  35   /** Retrieve the mailbox associated to the given name */
  36   static Mailbox* by_name(const std::string& name);
  37
  38   /** Returns whether the mailbox contains queued communications */
  39   bool empty();
  40
  41   /** Check if there is a communication going on in a mailbox. */
  42   bool listen();
  43
  44   /** Check if there is a communication ready to be consumed from a mailbox. */
  45   bool ready();
  46
  47   /** Gets the first element in the queue (without dequeuing it), or nullptr if none is there */
  48   kernel::activity::CommImplPtr front();
  49
  50   /** Declare that the specified actor is a permanent receiver on that mailbox
  51    *
  52    * It means that the communications sent to this mailbox will start flowing to
  53    * its host even before it does a get(). This models the real behavior of TCP
  54    * and MPI communications, amongst other. It will improve the accuracy of
  55    * predictions, in particular if your application exhibits swarms of small messages.
  56    *
  57    * SimGrid does not enforces any kind of ownership over the mailbox. Even if a receiver
  58    * was declared, any other actors can still get() data from the mailbox. The timings
  59    * will then probably be off tracks, so you should strive on your side to not get data
  60    * from someone else's mailbox.
  61    *
  62    * Note that being permanent receivers of a mailbox prevents actors to be garbage-collected.
  63    * If your simulation creates many short-lived actors that marked as permanent receiver, you
  64    * should call mailbox->set_receiver(nullptr) by the end of the actors so that their memory gets
  65    * properly reclaimed. This call should be at the end of the actor's function, not in a on_exit
  66    * callback.
  67    */
  68   void set_receiver(ActorPtr actor);
  69
  70   /** Return the actor declared as permanent receiver, or nullptr if none **/
  71   ActorPtr get_receiver();
  72
  73   /** Creates (but don't start) a data transmission to that mailbox */
  74   CommPtr put_init();
  75   /** Creates (but don't start) a data transmission to that mailbox */
  76   CommPtr put_init(void* data, uint64_t simulated_size_in_bytes);
  77   /** Creates and start a data transmission to that mailbox */
  78   CommPtr put_async(void* data, uint64_t simulated_size_in_bytes);
  79
  80   smx_activity_t iprobe(int type, int (*match_fun)(void*, void*, kernel::activity::CommImpl*), void* data);
  81   /** Blocking data transmission */
  82   void put(void* payload, uint64_t simulated_size_in_bytes);
  83   /** Blocking data transmission with timeout */
  84   void put(void* payload, uint64_t simulated_size_in_bytes, double timeout);
  85
  86   /** Creates (but don't start) a data reception onto that mailbox */
  87   CommPtr get_init();
  88   /** Creates and start an async data reception to that mailbox */
  89   CommPtr get_async(void** data);
  90
  91   /** Blocking data reception */
  92   void* get(); // FIXME: make a typed template version
  93   /** Blocking data reception with timeout */
  94   void* get(double timeout);
  95
  96   // Deprecated functions
  97 #ifndef DOXYGEN
  98   /** @deprecated Mailbox::set_receiver() */
  99   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::set_receiver()") void setReceiver(ActorPtr actor)
 100   {
 101     set_receiver(actor);
 102   }
 103   /** @deprecated Mailbox::get_receiver() */
 104   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_receiver()") ActorPtr getReceiver() { return get_receiver(); }
 105   /** @deprecated Mailbox::get_name() */
 106   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_name()") const xbt::string& getName() const { return get_name(); }
 107   /** @deprecated Mailbox::get_cname() */
 108   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_cname()") const char* getCname() const { return get_cname(); }
 109   /** @deprecated Mailbox::get_impl() */
 110   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::get_impl()") kernel::activity::MailboxImpl* getImpl()
 111   {
 112     return get_impl();
 113   }
 114   /** @deprecated Mailbox::by_name() */
 115   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::by_name()") static Mailbox* byName(const char* name)
 116   {
 117     return by_name(name);
 118   }
 119   /** @deprecated Mailbox::by_name() */
 120   XBT_ATTRIB_DEPRECATED_v323("Please use Mailbox::by_name()") static Mailbox* byName(const std::string& name)
 121   {
 122     return by_name(name);
 123   }
 124 #endif
 125 };
 126
 127 } // namespace s4u
 128 } // namespace simgrid
 129
 130 #endif /* SIMGRID_S4U_MAILBOX_HPP */