From ff70cc9af33d4cdafec15edf7b1b716dcf9c5b3b Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 4 Jan 2020 19:15:53 +0100 Subject: [PATCH] document Mutex and Semaphores in the new way --- docs/find-missing.py | 12 ++- docs/source/app_s4u.rst | 126 +++++++++++++++++++++++++----- include/simgrid/s4u/Mutex.hpp | 19 +++-- include/simgrid/s4u/Semaphore.hpp | 22 +++--- 4 files changed, 140 insertions(+), 39 deletions(-) diff --git a/docs/find-missing.py b/docs/find-missing.py index 4546b370a7..2043dcc82f 100755 --- a/docs/find-missing.py +++ b/docs/find-missing.py @@ -42,8 +42,18 @@ xml_files = [ 'build/xml/classsimgrid_1_1s4u_1_1Semaphore.xml', 'build/xml/classsimgrid_1_1s4u_1_1VirtualMachine.xml', 'build/xml/actor_8h.xml', + 'build/xml/barrier_8h.xml', + 'build/xml/cond_8h.xml', 'build/xml/engine_8h.xml', - 'build/xml/vm_8h.xml' + 'build/xml/forward_8h.xml', + 'build/xml/host_8h.xml', + 'build/xml/link_8h.xml', + 'build/xml/mailbox_8h.xml', + 'build/xml/msg_8h.xml', + 'build/xml/mutex_8h.xml', + 'build/xml/semaphore_8h.xml', + 'build/xml/vm_8h.xml', + 'build/xml/zone_8h.xml' ] python_modules = [ diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst index fac7ad0724..2944e11fe1 100644 --- a/docs/source/app_s4u.rst +++ b/docs/source/app_s4u.rst @@ -931,6 +931,62 @@ Activities lifecycle Synchronization Objects ======================= +.. _API_s4u_Mutex: + +============== +⁣  Mutex +============== + +.. autodoxyclass:: simgrid::s4u::Mutex + +Basic management +---------------- + + .. tabs:: + + .. group-tab:: C++ + + .. code-block:: C++ + + #include + + .. doxygentypedef:: MutexPtr + + .. autodoxymethod:: simgrid::s4u::Mutex::Mutex(kernel::activity::MutexImpl *mutex) + .. autodoxymethod:: simgrid::s4u::Mutex::create() + .. autodoxymethod:: simgrid::s4u::Mutex::~Mutex() + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_mutex_t + .. cpp:type:: const s4u_Mutex* const_sg_mutex_t + + Constant pointer to a SimGrid mutex object. + + .. autodoxymethod:: sg_mutex_init() + .. autodoxymethod:: sg_mutex_destroy(const_sg_mutex_t mutex) + +Locking +------- + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Mutex::lock() + .. autodoxymethod:: simgrid::s4u::Mutex::try_lock() + .. autodoxymethod:: simgrid::s4u::Mutex::unlock() + + .. group-tab:: C + + .. autodoxymethod:: sg_mutex_lock(sg_mutex_t mutex) + .. autodoxymethod:: sg_mutex_try_lock(sg_mutex_t mutex) + .. autodoxymethod:: sg_mutex_unlock(sg_mutex_t mutex) + .. _API_s4u_Barrier: ================ @@ -1030,31 +1086,65 @@ Waiting and notifying .. doxygenfunction:: sg_cond_wait .. doxygenfunction:: sg_cond_wait_for -.. _API_s4u_Mutex: +.. _API_s4u_Semaphore: -============== -⁣  class Mutex -============== +================== +⁣  Semaphore +================== -.. doxygentypedef:: MutexPtr +.. autodoxyclass:: simgrid::s4u::Semaphore -.. doxygenclass:: simgrid::s4u::Mutex - :members: - :protected-members: - :undoc-members: -.. _API_s4u_Semaphore: +Basic management +---------------- -================== -⁣  class Semaphore -================== + .. tabs:: -.. doxygentypedef:: SemaphorePtr + .. group-tab:: C++ -.. doxygenclass:: simgrid::s4u::Semaphore - :members: - :protected-members: - :undoc-members: + .. code-block:: C++ + + #include + + .. doxygentypedef:: SemaphorePtr + .. autodoxymethod:: simgrid::s4u::Semaphore::Semaphore(unsigned int initial_capacity) + .. autodoxymethod:: simgrid::s4u::Semaphore::~Semaphore() + .. autodoxymethod:: simgrid::s4u::Semaphore::create(unsigned int initial_capacity) + + .. group-tab:: C + + .. code-block:: C + + #include + + .. doxygentypedef:: sg_sem_t + .. cpp:type:: const s4u_Semaphore* const_sg_sem_t + + Constant pointer to a SimGrid semaphore object. + + .. autodoxymethod:: sg_sem_init(int initial_value) + .. autodoxymethod:: sg_sem_destroy(const_sg_sem_t sem) + +Locking +------- + + .. tabs:: + + .. group-tab:: C++ + + .. autodoxymethod:: simgrid::s4u::Semaphore::acquire() + .. autodoxymethod:: simgrid::s4u::Semaphore::acquire_timeout(double timeout) + .. autodoxymethod:: simgrid::s4u::Semaphore::get_capacity() + .. autodoxymethod:: simgrid::s4u::Semaphore::release() + .. autodoxymethod:: simgrid::s4u::Semaphore::would_block() + + .. group-tab:: C + + .. autodoxymethod:: sg_sem_acquire(sg_sem_t sem) + .. autodoxymethod:: sg_sem_acquire_timeout(sg_sem_t sem, double timeout) + .. autodoxymethod:: sg_sem_get_capacity(sg_sem_t sem) + .. autodoxymethod:: sg_sem_release(sg_sem_t sem) + .. autodoxymethod:: sg_sem_would_block(sg_sem_t sem) Python API Reference ******************** diff --git a/include/simgrid/s4u/Mutex.hpp b/include/simgrid/s4u/Mutex.hpp index e28f58a812..8cf22d61ea 100644 --- a/include/simgrid/s4u/Mutex.hpp +++ b/include/simgrid/s4u/Mutex.hpp @@ -12,22 +12,21 @@ namespace simgrid { namespace s4u { -/** @brief A classical mutex, but blocking in the simulation world - * @ingroup s4u_api +/** @brief A classical mutex, but blocking in the simulation world. * + * @rst * It is strictly impossible to use a real mutex, such as - * std::mutex - * or pthread_mutex_t, + * `std::mutex `_ + * or `pthread_mutex_t `_, * because it would block the whole simulation. - * Instead, you should use the present class, that is a drop-in replacement of - * std::mutex. + * Instead, you should use the present class, that is a drop-in replacement of these mechanisms. * - * @beginrst - * As for any S4U object, Mutexes are using the :ref:`RAII idiom ` for memory management. + * An example is available in Section :ref:`s4u_ex_IPC`. + * + * As for any S4U object, you can use the :ref:`RAII idiom ` for memory management of Mutexes. * Use :cpp:func:`create() ` to get a :cpp:type:`simgrid::s4u::MutexPtr` to a newly * created mutex, and only manipulate :cpp:type:`simgrid::s4u::MutexPtr`. * @endrst - * */ class XBT_PUBLIC Mutex { friend ConditionVariable; @@ -39,9 +38,9 @@ class XBT_PUBLIC Mutex { friend XBT_PUBLIC void intrusive_ptr_release(const Mutex* mutex); public: -#ifndef DOXYGEN explicit Mutex(kernel::activity::MutexImpl* mutex) : pimpl_(mutex) {} ~Mutex(); +#ifndef DOXYGEN Mutex(Mutex const&) = delete; // No copy constructor; Use MutexPtr instead Mutex& operator=(Mutex const&) = delete; // No direct assignment either. Use MutexPtr instead #endif diff --git a/include/simgrid/s4u/Semaphore.hpp b/include/simgrid/s4u/Semaphore.hpp index 50a3c366f6..602553d4cb 100644 --- a/include/simgrid/s4u/Semaphore.hpp +++ b/include/simgrid/s4u/Semaphore.hpp @@ -13,16 +13,19 @@ namespace simgrid { namespace s4u { /** @brief A classical semaphore, but blocking in the simulation world - * @ingroup s4u_api * + * @rst * It is strictly impossible to use a real semaphore, such as - * sem_init, + * `sem_init `_, * because it would block the whole simulation. * Instead, you should use the present class, that offers a very similar interface. * - * As for any S4U object, Semaphores are using the @ref s4u_raii "RAII idiom" for memory management. - * Use #create() to get a simgrid::s4u::SemaphorePtr to a newly created semaphore - * and only manipulate simgrid::s4u::SemaphorePtr. + * An example is available in Section :ref:`s4u_ex_IPC`. + * + * As for any S4U object, you can use the :ref:`RAII idiom ` for memory management of semaphores. + * Use :cpp:func:`create() ` to get a :cpp:type:`simgrid::s4u::SemaphorePtr` to a newly + * created semaphore, that will get automatically freed when the variable goes out of scope. + * @endrst * */ class XBT_PUBLIC Semaphore { @@ -36,11 +39,10 @@ public: explicit Semaphore(unsigned int initial_capacity); ~Semaphore(); - // No copy: - /** You cannot create a new semaphore by copying an existing one. Use SemaphorePtr instead */ - Semaphore(Semaphore const&) = delete; - /** You cannot create a new semaphore by value assignment either. Use SemaphorePtr instead */ - Semaphore& operator=(Semaphore const&) = delete; +#ifndef DOXYGEN + Semaphore(Semaphore const&) = delete; // No copy constructor. Use SemaphorePtr instead + Semaphore& operator=(Semaphore const&) = delete; // No direct assignment either. Use SemaphorePtr instead +#endif /** Constructs a new semaphore */ static SemaphorePtr create(unsigned int initial_capacity); -- 2.20.1