improve the doc of condition variables

diff --git a/docs/Build.sh b/docs/Build.sh
index cf87166..51ab88d 100755 (executable)
--- a/docs/Build.sh
+++ b/docs/Build.sh
@@ -33,7 +33,10 @@ else
   echo "javasphinx relaunched"
 fi
 
-PYTHONPATH=../lib sphinx-build -M html source build ${SPHINXOPTS}
+PYTHONPATH=../lib sphinx-build -M html source build ${SPHINXOPTS} 2>&1 \
+  | grep -v 'WARNING: cpp:identifier reference target not found: simgrid$' \
+  | grep -v 'WARNING: cpp:identifier reference target not found: simgrid::s4u$' \
+  | grep -v 'WARNING: cpp:identifier reference target not found: boost' 
 
 set +x
 

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index a30d969..5828cfb 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -953,7 +953,7 @@ Synchronization Objects
 .. _API_s4u_ConditionVariable:
 
 ==========================
-⁣  class ConditionVariable
+⁣  Condition variable
 ==========================
 
 .. autodoxyclass:: simgrid::s4u::ConditionVariable
@@ -992,17 +992,17 @@ Waiting and notifying
 
          .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_all()
          .. autodoxymethod:: simgrid::s4u::ConditionVariable::notify_one()
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(MutexPtr lock)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(s4u::MutexPtr lock)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< s4u::Mutex > &lock)
          .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait(const std::unique_lock< Mutex > &lock, P pred)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, double duration)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, double duration, P pred)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, std::chrono::duration< Rep, Period > duration)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, double timeout_time)
-         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< Mutex > &lock, double timeout_time, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, double duration, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_for(const std::unique_lock< s4u::Mutex > &lock, std::chrono::duration< Rep, Period > duration, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, const SimulationTimePoint< Duration > &timeout_time, P pred)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time)
+         .. autodoxymethod:: simgrid::s4u::ConditionVariable::wait_until(const std::unique_lock< s4u::Mutex > &lock, double timeout_time, P pred)
 
       .. group-tab:: C
 

diff --git a/examples/README.rst b/examples/README.rst
index 1fb1eed..810c7b9 100644 (file)
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -408,28 +408,28 @@ Classical synchronization objects
 ---------------------------------
 
  - **Barrier:**
-   Shows how to use simgrid::s4u::Barrier synchronization objects.
+   Shows how to use :cpp:type:`simgrid::s4u::Barrier` synchronization objects.
 
    .. tabs::
 
       .. example-tab:: examples/s4u/synchro-barrier/s4u-synchro-barrier.cpp
 
  - **Condition variable:**
-   Shows how to use simgrid::s4u::ConditionVariable synchronization objects.
+   Shows how to use :cpp:type:`simgrid::s4u::ConditionVariable` synchronization objects.
 
    .. tabs::
 
       .. example-tab:: examples/s4u/synchro-condition-variable/s4u-synchro-condition-variable.cpp
 
  - **Mutex:**
-   Shows how to use simgrid::s4u::Mutex synchronization objects.
+   Shows how to use :cpp:type:`simgrid::s4u::Mutex` synchronization objects.
 
    .. tabs::
 
       .. example-tab:: examples/s4u/synchro-mutex/s4u-synchro-mutex.cpp
 
  - **Semaphore:**
-   Shows how to use simgrid::s4u::Semaphore synchronization objects.
+   Shows how to use :cpp:type:`simgrid::s4u::Semaphore` synchronization objects.
 
    .. tabs::
 

diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp
index d33ee9a..7b0cab0 100644 (file)
--- 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();
 };