From: Martin Quinson Date: Fri, 3 Jan 2020 23:03:47 +0000 (+0100) Subject: document ConditionVariables in the new way X-Git-Tag: v3.25~167 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/32d57acf569c0266d65dda02fbf3d54ad2f4e9f5 document ConditionVariables in the new way --- diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index 85088212dc..a30d969d83 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -956,12 +956,60 @@ Synchronization Objects ⁣  class ConditionVariable ========================== -.. doxygentypedef:: ConditionVariablePtr +.. autodoxyclass:: simgrid::s4u::ConditionVariable -.. doxygenclass:: simgrid::s4u::ConditionVariable - :members: - :protected-members: - :undoc-members: +Basic management +---------------- + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C + + #include + + .. doxygentypedef:: ConditionVariablePtr + + .. autodoxymethod:: simgrid::s4u::ConditionVariable::create() + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_cond_t + .. doxygenfunction:: sg_cond_init + .. doxygenfunction:: sg_cond_destroy + +Waiting and notifying +--------------------- + + .. tabs:: + + .. group-tab:: C++ + + .. 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(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) + + .. group-tab:: C + + .. doxygenfunction:: sg_cond_notify_all + .. doxygenfunction:: sg_cond_notify_one + .. doxygenfunction:: sg_cond_wait + .. doxygenfunction:: sg_cond_wait_for .. _API_s4u_Mutex: @@ -989,22 +1037,6 @@ Synchronization Objects :protected-members: :undoc-members: - -C API Reference -*************** - -================== -Condition Variable -================== - -See also the :ref:`C++ API `. - -.. doxygenfunction:: sg_cond_init -.. doxygenfunction:: sg_cond_notify_all -.. doxygenfunction:: sg_cond_notify_one -.. doxygenfunction:: sg_cond_wait -.. doxygenfunction:: sg_cond_wait_for - Python API Reference ******************** @@ -1018,13 +1050,6 @@ this_actor .. automodule:: simgrid.this_actor :members: -=========== -Class Actor -=========== - -.. autoclass:: simgrid.Actor - :members: - ========== Class Comm ========== @@ -1032,13 +1057,6 @@ Class Comm .. autoclass:: simgrid.Comm :members: -============ -Class Engine -============ - -.. autoclass:: simgrid.Engine - :members: - ========== Class Exec ========== diff --git a/include/simgrid/cond.h b/include/simgrid/cond.h index 464c6c8c9f..b7986245f1 100644 --- a/include/simgrid/cond.h +++ b/include/simgrid/cond.h @@ -18,11 +18,11 @@ XBT_PUBLIC void sg_cond_wait(sg_cond_t cond, sg_mutex_t mutex); /** @brief Blocks onto the given condition variable, but only for the given amount of time. * @return 0 on success, 1 on timeout */ XBT_PUBLIC int sg_cond_wait_for(sg_cond_t cond, sg_mutex_t mutex, double delay); -/** @brief Signals the given mutex variable */ +/** @brief Signals the given condition variable */ XBT_PUBLIC void sg_cond_notify_one(sg_cond_t cond); -/** @brief Broadcasts the given mutex variable */ +/** @brief Broadcasts the given condition variable */ XBT_PUBLIC void sg_cond_notify_all(sg_cond_t cond); -/** @brief Destroys the given mutex variable */ +/** @brief Destroys the given condition variable */ XBT_PUBLIC void sg_cond_destroy(const_sg_cond_t cond); SG_END_DECL diff --git a/include/simgrid/forward.h b/include/simgrid/forward.h index 607810d5d3..517c473b43 100644 --- a/include/simgrid/forward.h +++ b/include/simgrid/forward.h @@ -36,7 +36,10 @@ XBT_PUBLIC void intrusive_ptr_release(Comm* c); XBT_PUBLIC void intrusive_ptr_add_ref(Comm* c); class ConditionVariable; -/** Smart pointer to a simgrid::s4u::ConditionVariable */ +/** @beginrst + * Smart pointer to a :cpp:type:`simgrid::s4u::ConditionVariable` + * @endrst + */ typedef boost::intrusive_ptr ConditionVariablePtr; XBT_PUBLIC void intrusive_ptr_release(const ConditionVariable* c); XBT_PUBLIC void intrusive_ptr_add_ref(const ConditionVariable* c); diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp index f10780c410..d33ee9ac11 100644 --- a/include/simgrid/s4u/ConditionVariable.hpp +++ b/include/simgrid/s4u/ConditionVariable.hpp @@ -16,12 +16,12 @@ namespace simgrid { namespace s4u { -/** @brief A condition variable - * @ingroup s4u_api - * - * This is a drop-in replacement of `std::condition_variable` and should respect the same - * semantic. But we currently use (only) double for both durations and - * timestamp timeouts. +/** + * @rst + * SimGrid's Condition Variables are meant to be drop-in replacements of + * `std::condition_variable `_ + * and should respect the same semantic. + * @endrst */ class XBT_PUBLIC ConditionVariable { private: @@ -29,9 +29,9 @@ private: kernel::activity::ConditionVariableImpl* const cond_; public: +#ifndef DOXYGEN explicit ConditionVariable(kernel::activity::ConditionVariableImpl* cond) : cond_(cond) {} -#ifndef DOXYGEN ConditionVariable(ConditionVariable const&) = delete; ConditionVariable& operator=(ConditionVariable const&) = delete; @@ -39,6 +39,12 @@ public: friend XBT_PUBLIC void intrusive_ptr_release(const ConditionVariable* cond); #endif + /** Create a new condition variable and return a smart pointer + * + * @rst + * You should only manipulate :cpp:type:`simgrid::s4u::ConditionVariablePtr`, as created by this function (see also :ref:`s4u_raii`). + * @endrst + */ static ConditionVariablePtr create(); // Wait functions without time: