From 18278c24522cdb44cb578759dc34a1b39f591e22 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 4 Jan 2020 18:13:57 +0100 Subject: [PATCH] improve the doc of condition variables --- docs/Build.sh | 5 ++- docs/source/app_s4u.rst | 22 ++++++------ examples/README.rst | 8 ++--- include/simgrid/s4u/ConditionVariable.hpp | 44 +++++++++++++---------- 4 files changed, 44 insertions(+), 35 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index cf871665cf..51ab88da50 100755 --- 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 a30d969d83..5828cfb3a7 100644 --- 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 1fb1eedfbe..810c7b990f 100644 --- 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 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 `_ - * 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++ `_ + * 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& lock); + /// Wait until notification, with no timeout + void wait(s4u::MutexPtr lock); + /// Wait until notification, with no timeout + void wait(const std::unique_lock& lock); template void wait(const std::unique_lock& 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& lock, double timeout_time); - std::cv_status wait_for(const std::unique_lock& lock, double duration); - template bool wait_until(const std::unique_lock& 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& 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& lock, double duration); + /// Wait until predicate is true, or the given instant (specified as a plain double) + template bool wait_until(const std::unique_lock& 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 bool wait_for(const std::unique_lock& 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 bool wait_for(const std::unique_lock& 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 - bool wait_for(const std::unique_lock& lock, std::chrono::duration duration, P pred) + bool wait_for(const std::unique_lock& lock, std::chrono::duration duration, P pred) { auto seconds = std::chrono::duration_cast(duration); return this->wait_for(lock, seconds.count(), pred); } + /// Wait for the given amount of seconds (specified in C++ style) template - std::cv_status wait_for(const std::unique_lock& lock, std::chrono::duration duration) + std::cv_status wait_for(const std::unique_lock& lock, std::chrono::duration duration) { auto seconds = std::chrono::duration_cast(duration); return this->wait_for(lock, seconds.count()); } + /** Wait until the given instant (specified in C++ style) */ template - std::cv_status wait_until(const std::unique_lock& lock, const SimulationTimePoint& timeout_time) + std::cv_status wait_until(const std::unique_lock& lock, const SimulationTimePoint& timeout_time) { auto timeout_native = std::chrono::time_point_cast(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 - bool wait_until(const std::unique_lock& lock, const SimulationTimePoint& timeout_time, P pred) + bool wait_until(const std::unique_lock& lock, const SimulationTimePoint& timeout_time, P pred) { auto timeout_native = std::chrono::time_point_cast(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(); }; -- 2.20.1