X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/32d57acf569c0266d65dda02fbf3d54ad2f4e9f5..b6dde5ff6f208b83545a4b4e9e81712d0d8617a1:/include/simgrid/s4u/ConditionVariable.hpp

diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp
index d33ee9ac11..7b0cab04d4 100644
--- a/include/simgrid/s4u/ConditionVariable.hpp
+++ b/include/simgrid/s4u/ConditionVariable.hpp
@@ -18,9 +18,9 @@ namespace s4u {
 
 /**
  * @rst
- * SimGrid's Condition Variables are meant to be drop-in replacements of
- * `std::condition_variable <https://en.cppreference.com/w/cpp/thread/condition_variable>`_
- * and should respect the same semantic.
+ * SimGrid's condition variables are meant to be drop-in replacements of ``std::condition_variable``.
+ * Please refer to the `documentation of standard C++ <https://en.cppreference.com/w/cpp/thread/condition_variable>`_
+ * for more information on condition variables. A SimGrid example is available in Section :ref:`s4u_ex_IPC`.
  * @endrst
  */
 class XBT_PUBLIC ConditionVariable {
@@ -47,62 +47,68 @@ public:
    */
   static ConditionVariablePtr create();
 
-  //  Wait functions without time:
-
-  void wait(MutexPtr lock);
-  void wait(const std::unique_lock<Mutex>& lock);
+  ///  Wait until notification, with no timeout
+  void wait(s4u::MutexPtr lock);
+  ///  Wait until notification, with no timeout
+  void wait(const std::unique_lock<s4u::Mutex>& lock);
   template <class P> void wait(const std::unique_lock<Mutex>& lock, P pred)
   {
     while (not pred())
       wait(lock);
   }
 
-  // Wait function taking a plain double as time:
-
-  std::cv_status wait_until(const std::unique_lock<Mutex>& lock, double timeout_time);
-  std::cv_status wait_for(const std::unique_lock<Mutex>& lock, double duration);
-  template <class P> bool wait_until(const std::unique_lock<Mutex>& lock, double timeout_time, P pred)
+  /// Wait until the given instant (specified as a plain double)
+  std::cv_status wait_until(const std::unique_lock<s4u::Mutex>& lock, double timeout_time);
+  /// Wait for the given amount of seconds (specified as a plain double)
+  std::cv_status wait_for(const std::unique_lock<s4u::Mutex>& lock, double duration);
+  /// Wait until predicate is true, or the given instant (specified as a plain double)
+  template <class P> bool wait_until(const std::unique_lock<s4u::Mutex>& lock, double timeout_time, P pred)
   {
     while (not pred())
       if (this->wait_until(lock, timeout_time) == std::cv_status::timeout)
         return pred();
     return true;
   }
-  template <class P> bool wait_for(const std::unique_lock<Mutex>& lock, double duration, P pred)
+  /// As long as the predicate is false, wait for the given amount of seconds (specified as a plain double)
+  template <class P> bool wait_for(const std::unique_lock<s4u::Mutex>& lock, double duration, P pred)
   {
     return this->wait_until(lock, SIMIX_get_clock() + duration, std::move(pred));
   }
 
   // Wait function taking a C++ style time:
 
+  /// As long as the predicate is false, wait for the given amount of seconds (specified in C++ style)
   template <class Rep, class Period, class P>
-  bool wait_for(const std::unique_lock<Mutex>& lock, std::chrono::duration<Rep, Period> duration, P pred)
+  bool wait_for(const std::unique_lock<s4u::Mutex>& lock, std::chrono::duration<Rep, Period> duration, P pred)
   {
     auto seconds = std::chrono::duration_cast<SimulationClockDuration>(duration);
     return this->wait_for(lock, seconds.count(), pred);
   }
+  /// Wait for the given amount of seconds (specified in C++ style)
   template <class Rep, class Period>
-  std::cv_status wait_for(const std::unique_lock<Mutex>& lock, std::chrono::duration<Rep, Period> duration)
+  std::cv_status wait_for(const std::unique_lock<s4u::Mutex>& lock, std::chrono::duration<Rep, Period> duration)
   {
     auto seconds = std::chrono::duration_cast<SimulationClockDuration>(duration);
     return this->wait_for(lock, seconds.count());
   }
+  /** Wait until the given instant (specified in C++ style) */
   template <class Duration>
-  std::cv_status wait_until(const std::unique_lock<Mutex>& lock, const SimulationTimePoint<Duration>& timeout_time)
+  std::cv_status wait_until(const std::unique_lock<s4u::Mutex>& lock, const SimulationTimePoint<Duration>& timeout_time)
   {
     auto timeout_native = std::chrono::time_point_cast<SimulationClockDuration>(timeout_time);
     return this->wait_until(lock, timeout_native.time_since_epoch().count());
   }
+  /** Wait until predicate is true, or the given instant (specified in C++ style) */
   template <class Duration, class P>
-  bool wait_until(const std::unique_lock<Mutex>& lock, const SimulationTimePoint<Duration>& timeout_time, P pred)
+  bool wait_until(const std::unique_lock<s4u::Mutex>& lock, const SimulationTimePoint<Duration>& timeout_time, P pred)
   {
     auto timeout_native = std::chrono::time_point_cast<SimulationClockDuration>(timeout_time);
     return this->wait_until(lock, timeout_native.time_since_epoch().count(), std::move(pred));
   }
 
-  // Notify functions
-
+  /** Unblock one actor blocked on that condition variable. If none was blocked, nothing happens. */
   void notify_one();
+  /** Unblock all actors blocked on that condition variable. If none was blocked, nothing happens. */
   void notify_all();
 };