Commit 725708ab by Jonathan Wakely Committed by Jonathan Wakely

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
parent d727fdc4
2019-05-02 Jonathan Wakely <jwakely@redhat.com> 2019-05-02 Jonathan Wakely <jwakely@redhat.com>
* 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_dir.h: Fix/improve doxygen markup.
* include/bits/fs_fwd.h: Likewise. * include/bits/fs_fwd.h: Likewise.
* include/bits/fs_ops.h: Likewise. * include/bits/fs_ops.h: Likewise.
......
...@@ -43,17 +43,14 @@ namespace std _GLIBCXX_VISIBILITY(default) ...@@ -43,17 +43,14 @@ namespace std _GLIBCXX_VISIBILITY(default)
{ {
_GLIBCXX_BEGIN_NAMESPACE_VERSION _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @ingroup mutexes
* @{
*/
/** @brief A movable scoped lock type. /** @brief A movable scoped lock type.
* *
* A unique_lock controls mutex ownership within a scope. Ownership of the * A unique_lock controls mutex ownership within a scope. Ownership of the
* mutex can be delayed until after construction and can be transferred * mutex can be delayed until after construction and can be transferred
* to another unique_lock by move construction or move assignment. If a * to another unique_lock by move construction or move assignment. If a
* mutex lock is owned when the destructor runs ownership will be released. * mutex lock is owned when the destructor runs ownership will be released.
*
* @ingroup mutexes
*/ */
template<typename _Mutex> template<typename _Mutex>
class unique_lock class unique_lock
...@@ -232,12 +229,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -232,12 +229,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}; };
/// Swap overload for unique_lock objects. /// Swap overload for unique_lock objects.
/// @relates unique_lock
template<typename _Mutex> template<typename _Mutex>
inline void inline void
swap(unique_lock<_Mutex>& __x, unique_lock<_Mutex>& __y) noexcept swap(unique_lock<_Mutex>& __x, unique_lock<_Mutex>& __y) noexcept
{ __x.swap(__y); } { __x.swap(__y); }
// @} group mutexes
_GLIBCXX_END_NAMESPACE_VERSION _GLIBCXX_END_NAMESPACE_VERSION
} // namespace } // namespace
......
...@@ -55,7 +55,7 @@ namespace std _GLIBCXX_VISIBILITY(default) ...@@ -55,7 +55,7 @@ namespace std _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION _GLIBCXX_BEGIN_NAMESPACE_VERSION
/** /**
* @ingroup mutexes * @addtogroup mutexes
* @{ * @{
*/ */
...@@ -463,6 +463,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -463,6 +463,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif #endif
#endif // _GLIBCXX_HAS_GTHREADS #endif // _GLIBCXX_HAS_GTHREADS
/// @cond undocumented
template<typename _Lock> template<typename _Lock>
inline unique_lock<_Lock> inline unique_lock<_Lock>
__try_to_lock(_Lock& __l) __try_to_lock(_Lock& __l)
...@@ -504,6 +505,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -504,6 +505,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
} }
} }
}; };
/// @endcond
/** @brief Generic try_lock. /** @brief Generic try_lock.
* @param __l1 Meets Lockable requirements (try_lock() may throw). * @param __l1 Meets Lockable requirements (try_lock() may throw).
...@@ -624,7 +626,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -624,7 +626,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif // C++17 #endif // C++17
#ifdef _GLIBCXX_HAS_GTHREADS #ifdef _GLIBCXX_HAS_GTHREADS
/// once_flag /// Flag type used by std::call_once
struct once_flag struct once_flag
{ {
private: private:
...@@ -645,6 +647,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -645,6 +647,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
call_once(once_flag& __once, _Callable&& __f, _Args&&... __args); call_once(once_flag& __once, _Callable&& __f, _Args&&... __args);
}; };
/// @cond undocumented
#ifdef _GLIBCXX_HAVE_TLS #ifdef _GLIBCXX_HAVE_TLS
extern __thread void* __once_callable; extern __thread void* __once_callable;
extern __thread void (*__once_call)(); extern __thread void (*__once_call)();
...@@ -659,8 +662,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -659,8 +662,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif #endif
extern "C" void __once_proxy(void); extern "C" void __once_proxy(void);
/// @endcond
/// call_once /// Invoke a callable and synchronize with other calls using the same flag
template<typename _Callable, typename... _Args> template<typename _Callable, typename... _Args>
void void
call_once(once_flag& __once, _Callable&& __f, _Args&&... __args) call_once(once_flag& __once, _Callable&& __f, _Args&&... __args)
......
...@@ -42,7 +42,7 @@ namespace std _GLIBCXX_VISIBILITY(default) ...@@ -42,7 +42,7 @@ namespace std _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION _GLIBCXX_BEGIN_NAMESPACE_VERSION
/** /**
* @ingroup mutexes * @addtogroup mutexes
* @{ * @{
*/ */
...@@ -56,6 +56,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -56,6 +56,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#define __cpp_lib_shared_timed_mutex 201402 #define __cpp_lib_shared_timed_mutex 201402
class shared_timed_mutex; class shared_timed_mutex;
/// @cond undocumented
#if _GLIBCXX_USE_PTHREAD_RWLOCK_T #if _GLIBCXX_USE_PTHREAD_RWLOCK_T
#ifdef __gthrw #ifdef __gthrw
#define _GLIBCXX_GTHRW(name) \ #define _GLIBCXX_GTHRW(name) \
...@@ -395,6 +397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -395,6 +397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
} }
}; };
#endif #endif
/// @endcond
#if __cplusplus > 201402L #if __cplusplus > 201402L
/// The standard shared mutex type. /// The standard shared mutex type.
...@@ -432,11 +435,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -432,11 +435,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}; };
#endif // C++17 #endif // C++17
/// @cond undocumented
#if _GLIBCXX_USE_PTHREAD_RWLOCK_T && _GTHREAD_USE_MUTEX_TIMEDLOCK #if _GLIBCXX_USE_PTHREAD_RWLOCK_T && _GTHREAD_USE_MUTEX_TIMEDLOCK
using __shared_timed_mutex_base = __shared_mutex_pthread; using __shared_timed_mutex_base = __shared_mutex_pthread;
#else #else
using __shared_timed_mutex_base = __shared_mutex_cv; using __shared_timed_mutex_base = __shared_mutex_cv;
#endif #endif
/// @endcond
/// The standard shared timed mutex type. /// The standard shared timed mutex type.
class shared_timed_mutex class shared_timed_mutex
...@@ -754,6 +759,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION ...@@ -754,6 +759,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}; };
/// Swap specialization for shared_lock /// Swap specialization for shared_lock
/// @relates shared_mutex
template<typename _Mutex> template<typename _Mutex>
void void
swap(shared_lock<_Mutex>& __x, shared_lock<_Mutex>& __y) noexcept swap(shared_lock<_Mutex>& __x, shared_lock<_Mutex>& __y) noexcept
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment