X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/11ae3bfac7b4c85a23e220b9d0755449a622a37b..f364225c23f541330fdc9a512d551a683cf374c9:/include/simgrid/s4u/Mailbox.hpp diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp index 78354d4936..035a928d05 100644 --- a/include/simgrid/s4u/Mailbox.hpp +++ b/include/simgrid/s4u/Mailbox.hpp @@ -1,4 +1,4 @@ -/* Copyright (c) 2006-2015. The SimGrid Team. All rights reserved. */ +/* Copyright (c) 2006-2018. The SimGrid Team. All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ @@ -9,6 +9,7 @@ #include #include +#include #include #include @@ -26,7 +27,7 @@ namespace s4u { * 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. + * 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 @@ -67,8 +68,8 @@ namespace s4u { * cumbersome for your simulations anyway. You probably want something * simpler, that turns our to be easy to build with the mailboxes. * - * Many examples in the archive use a sort of yellow page system where - * the mailbox names are the name of the service (such as "worker", + * 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 @@ -76,6 +77,15 @@ namespace s4u { * the first relevant actor that can deal with the request will handle * it. * + * @section s4u_mb_matching 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 incomming + * 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. + * * @section s4u_mb_receiver Declaring a receiving actor * * The last twist is that by default in the simulator, the data starts @@ -84,8 +94,8 @@ namespace s4u { * 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. - * + * 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 @@ -94,25 +104,26 @@ namespace s4u { * * @section s4u_mb_api The API */ -XBT_PUBLIC_CLASS Mailbox { +class XBT_PUBLIC Mailbox { friend Comm; - friend simgrid::s4u::Engine; - friend simgrid::simix::Mailbox; + friend simgrid::kernel::activity::MailboxImpl; - simgrid::simix::Mailbox *pimpl_; + simgrid::kernel::activity::MailboxImpl* pimpl_; - Mailbox(smx_mailbox_t mbox): pimpl_(mbox) {} + explicit Mailbox(kernel::activity::MailboxImpl * mbox) : pimpl_(mbox) {} /** private function to manage the mailboxes' lifetime (see @ref s4u_raii) */ - friend void intrusive_ptr_add_ref(Mailbox*) {} + friend XBT_PUBLIC void intrusive_ptr_add_ref(Mailbox*) {} /** private function to manage the mailboxes' lifetime (see @ref s4u_raii) */ - friend void intrusive_ptr_release(Mailbox*) {} + friend XBT_PUBLIC void intrusive_ptr_release(Mailbox*) {} public: /** private function, do not use. FIXME: make me protected */ - smx_mailbox_t getImpl() { return pimpl_; } + kernel::activity::MailboxImpl* getImpl() { return pimpl_; } - /** Gets the name of that mailbox */ - const char *getName(); + /** @brief Retrieves the name of that mailbox as a C++ string */ + const simgrid::xbt::string& getName() const; + /** @brief Retrieves the name of that mailbox as a C string */ + const char* getCname() const; /** Retrieve the mailbox associated to the given C string */ static MailboxPtr byName(const char *name); @@ -123,6 +134,9 @@ public: /** Returns whether the mailbox contains queued communications */ bool empty(); + /** Check if there is a communication going on in a mailbox. */ + bool listen(); + /** Gets the first element in the queue (without dequeuing it), or nullptr if none is there */ smx_activity_t front(); @@ -135,7 +149,29 @@ public: void setReceiver(ActorPtr actor); /** Return the actor declared as permanent receiver, or nullptr if none **/ - ActorPtr receiver(); + ActorPtr getReceiver(); + + /** Creates (but don't start) a data emission to that mailbox */ + CommPtr put_init(); + /** Creates (but don't start) a data emission to that mailbox */ + CommPtr put_init(void* data, uint64_t simulatedSizeInBytes); + /** Creates and start a data emission to that mailbox */ + CommPtr put_async(void* data, uint64_t simulatedSizeInBytes); + + /** Blocking data emission */ + void put(void* payload, uint64_t simulatedSizeInBytes); + /** Blocking data emission with timeout */ + void put(void* payload, uint64_t simulatedSizeInBytes, double timeout); + + /** Creates (but don't start) a data reception onto that mailbox */ + CommPtr get_init(); + /** Creates and start an async data reception to that mailbox */ + CommPtr get_async(void** data); + + /** Blocking data reception */ + void* get(); + /** Blocking data reception with timeout */ + void* get(double timeout); }; }} // namespace simgrid::s4u