From: Jonathan Wakely <jwakely@redhat.com>
To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org
Subject: [committed 06/12] libstdc++: Improve doxygen docs for <atomic>
Date: Fri, 13 May 2022 13:40:44 +0100 [thread overview]
Message-ID: <20220513124050.4028450-6-jwakely@redhat.com> (raw)
In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com>
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
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.
---
libstdc++-v3/include/bits/atomic_base.h | 41 ++++++++++++++-----
libstdc++-v3/include/bits/shared_ptr_atomic.h | 32 +++++++++------
libstdc++-v3/include/std/atomic | 11 +++--
3 files changed, 57 insertions(+), 27 deletions(-)
diff --git a/libstdc++-v3/include/bits/atomic_base.h b/libstdc++-v3/include/bits/atomic_base.h
index 5cf217dbf28..d29e4434177 100644
--- a/libstdc++-v3/include/bits/atomic_base.h
+++ b/libstdc++-v3/include/bits/atomic_base.h
@@ -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
diff --git a/libstdc++-v3/include/bits/shared_ptr_atomic.h b/libstdc++-v3/include/bits/shared_ptr_atomic.h
index ff86432f0b4..d4bd712fc7d 100644
--- a/libstdc++-v3/include/bits/shared_ptr_atomic.h
+++ b/libstdc++-v3/include/bits/shared_ptr_atomic.h
@@ -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
diff --git a/libstdc++-v3/include/std/atomic b/libstdc++-v3/include/std/atomic
index d819b6bf41e..1c6acfa36d0 100644
--- a/libstdc++-v3/include/std/atomic
+++ b/libstdc++-v3/include/std/atomic
@@ -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.
--
2.34.1
next prev parent reply other threads:[~2022-05-13 12:41 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
2022-05-13 12:40 ` [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command Jonathan Wakely
2022-05-13 12:40 ` [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2 Jonathan Wakely
2022-05-14 15:36 ` François Dumont
2022-05-16 4:27 ` François Dumont
2022-05-16 16:19 ` Jonathan Wakely
2022-05-16 17:04 ` François Dumont
2022-05-16 16:13 ` Jonathan Wakely
2022-05-16 16:59 ` François Dumont
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
2022-05-13 12:40 ` Jonathan Wakely [this message]
2022-05-13 12:40 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
2022-05-13 12:40 ` [committed 11/12] libstdc++: Improve doxygen docs for some of <memory> Jonathan Wakely
2022-05-13 12:40 ` [committed 12/12] libstdc++: Improve doxygen docs for <mutex> Jonathan Wakely
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220513124050.4028450-6-jwakely@redhat.com \
--to=jwakely@redhat.com \
--cc=gcc-patches@gcc.gnu.org \
--cc=libstdc++@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).