libstdc++: Improve doxygen docs for <atomic>
libstdc++-v3/ChangeLog: * include/std/atomic: Suppress doxygen docs for implementation details. * include/bits/atomic_base.h: Likewise. * include/bits/shared_ptr_atomic.h: Use markdown. Fix grouping so that std::atomic is not added to the pointer abstractions group.
This commit is contained in:
Jonathan Wakely
parent
20b917e7c0
commit
1566ca0969
@ -86,6 +86,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
} memory_order;
|
||||
#endif
|
||||
|
||||
/// @cond undocumented
|
||||
enum __memory_order_modifier
|
||||
{
|
||||
__memory_order_mask = 0x0ffff,
|
||||
@ -93,6 +94,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
__memory_order_hle_acquire = 0x10000,
|
||||
__memory_order_hle_release = 0x20000
|
||||
};
|
||||
/// @endcond
|
||||
|
||||
constexpr memory_order
|
||||
operator|(memory_order __m, __memory_order_modifier __mod)
|
||||
@ -106,6 +108,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
return memory_order(int(__m) & int(__mod));
|
||||
}
|
||||
|
||||
/// @cond undocumented
|
||||
|
||||
// Drop release ordering as per [atomics.types.operations.req]/21
|
||||
constexpr memory_order
|
||||
__cmpexch_failure_order2(memory_order __m) noexcept
|
||||
@ -128,6 +132,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
&& (__m & __memory_order_mask) != memory_order_acq_rel;
|
||||
}
|
||||
|
||||
// Base types for atomics.
|
||||
template<typename _IntTp>
|
||||
struct __atomic_base;
|
||||
|
||||
/// @endcond
|
||||
|
||||
_GLIBCXX_ALWAYS_INLINE void
|
||||
atomic_thread_fence(memory_order __m) noexcept
|
||||
{ __atomic_thread_fence(int(__m)); }
|
||||
@ -145,17 +155,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
return __ret;
|
||||
}
|
||||
|
||||
// Base types for atomics.
|
||||
template<typename _IntTp>
|
||||
struct __atomic_base;
|
||||
|
||||
#if __cplusplus <= 201703L
|
||||
# define _GLIBCXX20_INIT(I)
|
||||
#else
|
||||
#if __cplusplus >= 202002L
|
||||
# define __cpp_lib_atomic_value_initialization 201911L
|
||||
# define _GLIBCXX20_INIT(I) = I
|
||||
#endif
|
||||
|
||||
/// @cond undocumented
|
||||
#if __cpp_lib_atomic_value_initialization
|
||||
# define _GLIBCXX20_INIT(I) = I
|
||||
#else
|
||||
# define _GLIBCXX20_INIT(I)
|
||||
#endif
|
||||
/// @endcond
|
||||
|
||||
#define ATOMIC_VAR_INIT(_VI) { _VI }
|
||||
|
||||
template<typename _Tp>
|
||||
@ -171,8 +182,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
typedef unsigned char __atomic_flag_data_type;
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Base type for atomic_flag.
|
||||
/// @cond undocumented
|
||||
|
||||
/*
|
||||
* Base type for atomic_flag.
|
||||
*
|
||||
* Base type is POD with data, allowing atomic_flag to derive from
|
||||
* it and meet the standard layout type requirement. In addition to
|
||||
@ -190,6 +203,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
|
||||
_GLIBCXX_END_EXTERN_C
|
||||
|
||||
/// @endcond
|
||||
|
||||
#define ATOMIC_FLAG_INIT { 0 }
|
||||
|
||||
/// atomic_flag
|
||||
@ -295,6 +310,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
{ return __i ? __GCC_ATOMIC_TEST_AND_SET_TRUEVAL : 0; }
|
||||
};
|
||||
|
||||
/// @cond undocumented
|
||||
|
||||
/// Base class for atomic integrals.
|
||||
//
|
||||
@ -936,7 +952,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
{ return __atomic_fetch_sub(&_M_p, _M_type_size(__d), int(__m)); }
|
||||
};
|
||||
|
||||
/// @endcond
|
||||
|
||||
#if __cplusplus > 201703L
|
||||
/// @cond undocumented
|
||||
|
||||
// Implementation details of atomic_ref and atomic<floating-point>.
|
||||
namespace __atomic_impl
|
||||
{
|
||||
@ -1936,6 +1956,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
_Tp** _M_ptr;
|
||||
};
|
||||
|
||||
/// @endcond
|
||||
#endif // C++2a
|
||||
|
||||
/// @} group atomics
|
||||
|
||||
@ -38,9 +38,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
|
||||
/**
|
||||
* @addtogroup pointer_abstractions
|
||||
* @relates shared_ptr
|
||||
* @{
|
||||
*/
|
||||
/// @relates shared_ptr @{
|
||||
|
||||
/// @cond undocumented
|
||||
|
||||
@ -94,8 +94,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
* @param __p A non-null pointer to a shared_ptr object.
|
||||
* @return @c *__p
|
||||
*
|
||||
* The memory order shall not be @c memory_order_release or
|
||||
* @c memory_order_acq_rel.
|
||||
* The memory order shall not be `memory_order_release` or
|
||||
* `memory_order_acq_rel`.
|
||||
* @{
|
||||
*/
|
||||
template<typename _Tp>
|
||||
@ -130,8 +130,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
* @param __p A non-null pointer to a shared_ptr object.
|
||||
* @param __r The value to store.
|
||||
*
|
||||
* The memory order shall not be @c memory_order_acquire or
|
||||
* @c memory_order_acq_rel.
|
||||
* The memory order shall not be `memory_order_acquire` or
|
||||
* `memory_order_acq_rel`.
|
||||
* @{
|
||||
*/
|
||||
template<typename _Tp>
|
||||
@ -167,8 +167,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
/**
|
||||
* @brief Atomic exchange for shared_ptr objects.
|
||||
* @param __p A non-null pointer to a shared_ptr object.
|
||||
* @param __r New value to store in @c *__p.
|
||||
* @return The original value of @c *__p
|
||||
* @param __r New value to store in `*__p`.
|
||||
* @return The original value of `*__p`
|
||||
* @{
|
||||
*/
|
||||
template<typename _Tp>
|
||||
@ -214,10 +214,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
* @param __p A non-null pointer to a shared_ptr object.
|
||||
* @param __v A non-null pointer to a shared_ptr object.
|
||||
* @param __w A non-null pointer to a shared_ptr object.
|
||||
* @return True if @c *__p was equivalent to @c *__v, false otherwise.
|
||||
* @return True if `*__p` was equivalent to `*__v`, false otherwise.
|
||||
*
|
||||
* The memory order for failure shall not be @c memory_order_release or
|
||||
* @c memory_order_acq_rel, or stronger than the memory order for success.
|
||||
* The memory order for failure shall not be `memory_order_release` or
|
||||
* `memory_order_acq_rel`.
|
||||
* @{
|
||||
*/
|
||||
template<typename _Tp>
|
||||
@ -327,11 +327,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
}
|
||||
/// @}
|
||||
|
||||
/// @} group pointer_abstractions
|
||||
|
||||
#if __cplusplus >= 202002L
|
||||
# define __cpp_lib_atomic_shared_ptr 201711L
|
||||
template<typename _Tp>
|
||||
class atomic;
|
||||
|
||||
/**
|
||||
* @addtogroup pointer_abstractions
|
||||
* @relates shared_ptr
|
||||
* @{
|
||||
*/
|
||||
|
||||
template<typename _Up>
|
||||
static constexpr bool __is_shared_ptr = false;
|
||||
template<typename _Up>
|
||||
@ -788,10 +796,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
private:
|
||||
_Sp_atomic<weak_ptr<_Tp>> _M_impl;
|
||||
};
|
||||
#endif // C++20
|
||||
|
||||
/// @} relates shared_ptr
|
||||
/// @} group pointer_abstractions
|
||||
#endif // C++20
|
||||
|
||||
_GLIBCXX_END_NAMESPACE_VERSION
|
||||
} // namespace
|
||||
|
||||
@ -181,11 +181,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
#endif // __cpp_lib_atomic_wait
|
||||
};
|
||||
|
||||
#if __cplusplus <= 201703L
|
||||
# define _GLIBCXX20_INIT(I)
|
||||
#else
|
||||
/// @cond undocumented
|
||||
#if __cpp_lib_atomic_value_initialization
|
||||
# define _GLIBCXX20_INIT(I) = I
|
||||
#else
|
||||
# define _GLIBCXX20_INIT(I)
|
||||
#endif
|
||||
/// @endcond
|
||||
|
||||
/**
|
||||
* @brief Generic atomic type, primary class template.
|
||||
@ -1241,11 +1243,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
|
||||
atomic_flag_clear(volatile atomic_flag* __a) noexcept
|
||||
{ atomic_flag_clear_explicit(__a, memory_order_seq_cst); }
|
||||
|
||||
|
||||
/// @cond undocumented
|
||||
template<typename _Tp>
|
||||
using __atomic_val_t = typename atomic<_Tp>::value_type;
|
||||
template<typename _Tp>
|
||||
using __atomic_diff_t = typename atomic<_Tp>::difference_type;
|
||||
/// @endcond
|
||||
|
||||
// [atomics.nonmembers] Non-member functions.
|
||||
// Function templates generally applicable to atomic types.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user