allow to get the number of queued communications in a Mailbox

[simgrid.git] / include / simgrid / s4u / Mailbox.hpp

diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp
index 6837914..4daf375 100644 (file)
--- a/include/simgrid/s4u/Mailbox.hpp
+++ b/include/simgrid/s4u/Mailbox.hpp
@@ -1,4 +1,4 @@
-/* Copyright (c) 2006-2020. The SimGrid Team. All rights reserved.          */
+/* Copyright (c) 2006-2021. 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. */
@@ -44,6 +44,9 @@ public:
   /** Returns whether the mailbox contains queued communications */
   bool empty() const;
 
+  /* Returns the number of queued communications */
+  unsigned int size() const;
+
   /** Check if there is a communication going on in a mailbox. */
   bool listen() const;
 
@@ -81,14 +84,26 @@ public:
 
   /** Creates (but don't start) a data transmission to that mailbox */
   CommPtr put_init();
-  /** Creates (but don't start) a data transmission to that mailbox */
+  /** Creates (but don't start) a data transmission to that mailbox.
+   *
+   * Please note that if you send a pointer to some data, you must ensure that your data remains live during the
+   * communication, or the receiver will get a pointer to a garbled memory area.
+   */
   CommPtr put_init(void* data, uint64_t simulated_size_in_bytes);
-  /** Creates and start a data transmission to that mailbox */
+  /** Creates and start a data transmission to that mailbox.
+   *
+   * Please note that if you send a pointer to some data, you must ensure that your data remains live during the
+   * communication, or the receiver will get a pointer to a garbled memory area.
+   */
   CommPtr put_async(void* data, uint64_t simulated_size_in_bytes);
 
   kernel::activity::ActivityImplPtr iprobe(int type, bool (*match_fun)(void*, void*, kernel::activity::CommImpl*),
                                            void* data);
-  /** Blocking data transmission */
+  /** Blocking data transmission.
+   *
+   * Please note that if you send a pointer to some data, you must ensure that your data remains live during the
+   * communication, or the receiver will get a pointer to a garbled memory area.
+   */
   void put(void* payload, uint64_t simulated_size_in_bytes);
   /** Blocking data transmission with timeout */
   void put(void* payload, uint64_t simulated_size_in_bytes, double timeout);
@@ -112,8 +127,7 @@ public:
 
 template <typename T> CommPtr Mailbox::get_async(T** data)
 {
-  CommPtr res = get_init();
-  res->set_dst_data(reinterpret_cast<void**>(data), sizeof(void*));
+  CommPtr res = get_init()->set_dst_data(reinterpret_cast<void**>(data), sizeof(void*));
   res->vetoable_start();
   return res;
 }