From 725708ab752d707937ee26a710235ed45dd4cdd4 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 16:46:42 +0100 Subject: [PATCH] Improve docs for mutexes * include/bits/unique_lock.h: Fix/improve doxygen markup. * include/std/mutex: Likewise. * include/std/shared_mutex: Likewise. From-SVN: r270812 --- libstdc++-v3/ChangeLog | 4 ++++ libstdc++-v3/include/bits/unique_lock.h | 9 +++------ libstdc++-v3/include/std/mutex | 10 +++++++--- libstdc++-v3/include/std/shared_mutex | 8 +++++++- 4 files changed, 21 insertions(+), 10 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 52d3adf251e..8c4bee26994 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,9 @@ 2019-05-02 Jonathan Wakely + * include/bits/unique_lock.h: Fix/improve doxygen markup. + * include/std/mutex: Likewise. + * include/std/shared_mutex: Likewise. + * include/bits/fs_dir.h: Fix/improve doxygen markup. * include/bits/fs_fwd.h: Likewise. * include/bits/fs_ops.h: Likewise. diff --git a/libstdc++-v3/include/bits/unique_lock.h b/libstdc++-v3/include/bits/unique_lock.h index 9aceb6b6124..9eb5f227faa 100644 --- a/libstdc++-v3/include/bits/unique_lock.h +++ b/libstdc++-v3/include/bits/unique_lock.h @@ -43,17 +43,14 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION - /** - * @ingroup mutexes - * @{ - */ - /** @brief A movable scoped lock type. * * A unique_lock controls mutex ownership within a scope. Ownership of the * mutex can be delayed until after construction and can be transferred * to another unique_lock by move construction or move assignment. If a * mutex lock is owned when the destructor runs ownership will be released. + * + * @ingroup mutexes */ template class unique_lock @@ -232,12 +229,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; /// Swap overload for unique_lock objects. + /// @relates unique_lock template inline void swap(unique_lock<_Mutex>& __x, unique_lock<_Mutex>& __y) noexcept { __x.swap(__y); } - // @} group mutexes _GLIBCXX_END_NAMESPACE_VERSION } // namespace diff --git a/libstdc++-v3/include/std/mutex b/libstdc++-v3/include/std/mutex index dfb5f7eb31a..ca2c669db9a 100644 --- a/libstdc++-v3/include/std/mutex +++ b/libstdc++-v3/include/std/mutex @@ -55,7 +55,7 @@ namespace std _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @ingroup mutexes + * @addtogroup mutexes * @{ */ @@ -463,6 +463,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif #endif // _GLIBCXX_HAS_GTHREADS + /// @cond undocumented template inline unique_lock<_Lock> __try_to_lock(_Lock& __l) @@ -504,6 +505,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } } }; + /// @endcond /** @brief Generic try_lock. * @param __l1 Meets Lockable requirements (try_lock() may throw). @@ -624,7 +626,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++17 #ifdef _GLIBCXX_HAS_GTHREADS - /// once_flag + /// Flag type used by std::call_once struct once_flag { private: @@ -645,6 +647,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION call_once(once_flag& __once, _Callable&& __f, _Args&&... __args); }; + /// @cond undocumented #ifdef _GLIBCXX_HAVE_TLS extern __thread void* __once_callable; extern __thread void (*__once_call)(); @@ -659,8 +662,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif extern "C" void __once_proxy(void); + /// @endcond - /// call_once + /// Invoke a callable and synchronize with other calls using the same flag template void call_once(once_flag& __once, _Callable&& __f, _Args&&... __args) diff --git a/libstdc++-v3/include/std/shared_mutex b/libstdc++-v3/include/std/shared_mutex index be64144dfb0..ffd93fb1e15 100644 --- a/libstdc++-v3/include/std/shared_mutex +++ b/libstdc++-v3/include/std/shared_mutex @@ -42,7 +42,7 @@ namespace std _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @ingroup mutexes + * @addtogroup mutexes * @{ */ @@ -56,6 +56,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #define __cpp_lib_shared_timed_mutex 201402 class shared_timed_mutex; + /// @cond undocumented + #if _GLIBCXX_USE_PTHREAD_RWLOCK_T #ifdef __gthrw #define _GLIBCXX_GTHRW(name) \ @@ -395,6 +397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; #endif + /// @endcond #if __cplusplus > 201402L /// The standard shared mutex type. @@ -432,11 +435,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; #endif // C++17 + /// @cond undocumented #if _GLIBCXX_USE_PTHREAD_RWLOCK_T && _GTHREAD_USE_MUTEX_TIMEDLOCK using __shared_timed_mutex_base = __shared_mutex_pthread; #else using __shared_timed_mutex_base = __shared_mutex_cv; #endif + /// @endcond /// The standard shared timed mutex type. class shared_timed_mutex @@ -754,6 +759,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; /// Swap specialization for shared_lock + /// @relates shared_mutex template void swap(shared_lock<_Mutex>& __x, shared_lock<_Mutex>& __y) noexcept -- 2.30.2