* [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2 Jonathan Wakely
` (9 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/mofunc_impl.h: Fix doxygen command.
---
libstdc++-v3/include/bits/mofunc_impl.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libstdc++-v3/include/bits/mofunc_impl.h b/libstdc++-v3/include/bits/mofunc_impl.h
index 6cc9711a42b..405c4054642 100644
--- a/libstdc++-v3/include/bits/mofunc_impl.h
+++ b/libstdc++-v3/include/bits/mofunc_impl.h
@@ -48,7 +48,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @brief Polymorphic function wrapper.
* @ingroup functors
* @since C++23
- * @headername functional
+ * @headerfile functional
*
* The `std::move_only_function` class template is a call wrapper similar
* to * `std::function`, but does not require the stored target function
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
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 ` Jonathan Wakely
2022-05-14 15:36 ` François Dumont
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
` (8 subsequent siblings)
10 siblings, 1 reply; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
Unlike the rest of the series, this isn't suitable for backporting
because it changes the ABI for the gnu-versioned-namespace build. That's
fine for GCC 13, but not OK to change within a release branch, e.g.
between 12.1 and 12.2. If we want to backport it, the macro should do
the same thing whether or not _GLIBCXX_INLINE_VERSION is set.
-- >8 --
Use macros to open and close the inline namespace _V2 that is used for
ABI versioning of individual components such as chrono::system_clock.
This allows the namespace to be hidden in the docs generated by Doxygen,
so that we document std::foo instead of std::_V2::foo.
This also makes it easy to remove that namespace entirely for the
gnu-versioned-namespace build, where everything is already versioned as
std::__8 and there are no backwards compatibility guarantees.
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Expand new macros to
nothing.
* include/bits/c++config (_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE)
(_GLIBCXX_END_INLINE_ABI_NAMESPACE): Define new macros.
* include/bits/algorithmfwd.h (_V2::__rotate): Use new macros
for the namespace.
* include/bits/chrono.h (chrono::_V2::system_clock): Likewise.
* include/bits/stl_algo.h (_V2::__rotate): Likewise.
* include/std/condition_variable (_V2::condition_variable_any):
Likewise.
* include/std/system_error (_V2::error_category): Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 2 ++
libstdc++-v3/include/bits/algorithmfwd.h | 15 ++++++++-------
libstdc++-v3/include/bits/c++config | 11 +++++++++--
libstdc++-v3/include/bits/chrono.h | 4 ++--
libstdc++-v3/include/bits/stl_algo.h | 5 ++---
libstdc++-v3/include/std/condition_variable | 4 ++--
libstdc++-v3/include/std/system_error | 5 +++--
7 files changed, 28 insertions(+), 18 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index b9babc3993e..2dbed727013 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2347,6 +2347,8 @@ PREDEFINED = __cplusplus=202002L \
"_GLIBCXX_END_NAMESPACE_CONTAINER= " \
"_GLIBCXX_END_NAMESPACE_CXX11= " \
"_GLIBCXX_END_NAMESPACE_LDBL= " \
+ "-D_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)= " \
+ "-D_GLIBCXX_END_INLINE_ABI_NAMESPACE(X)= " \
"_GLIBCXX_TEMPLATE_ARGS=... " \
"_GLIBCXX_DEPRECATED= " \
"_GLIBCXX_DEPRECATED_SUGGEST(E)= " \
diff --git a/libstdc++-v3/include/bits/algorithmfwd.h b/libstdc++-v3/include/bits/algorithmfwd.h
index 5271a90b501..aacc34e09e8 100644
--- a/libstdc++-v3/include/bits/algorithmfwd.h
+++ b/libstdc++-v3/include/bits/algorithmfwd.h
@@ -601,13 +601,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_OIter
reverse_copy(_BIter, _BIter, _OIter);
- inline namespace _V2
- {
- template<typename _FIter>
- _GLIBCXX20_CONSTEXPR
- _FIter
- rotate(_FIter, _FIter, _FIter);
- }
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
+
+ template<typename _FIter>
+ _GLIBCXX20_CONSTEXPR
+ _FIter
+ rotate(_FIter, _FIter, _FIter);
+
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
template<typename _FIter, typename _OIter>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config
index 2798b9786dc..150b0bc5834 100644
--- a/libstdc++-v3/include/bits/c++config
+++ b/libstdc++-v3/include/bits/c++config
@@ -345,13 +345,16 @@ namespace __gnu_cxx
# define _GLIBCXX_DEFAULT_ABI_TAG
#endif
-// Defined if inline namespaces are used for versioning.
+// Non-zero if inline namespaces are used for versioning the entire library.
#define _GLIBCXX_INLINE_VERSION
-// Inline namespace for symbol versioning.
#if _GLIBCXX_INLINE_VERSION
+// Inline namespace for symbol versioning of (nearly) everything in std.
# define _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace __8 {
# define _GLIBCXX_END_NAMESPACE_VERSION }
+// Unused when everything in std is versioned anyway.
+# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)
+# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X)
namespace std
{
@@ -376,8 +379,12 @@ _GLIBCXX_END_NAMESPACE_VERSION
}
#else
+// Unused.
# define _GLIBCXX_BEGIN_NAMESPACE_VERSION
# define _GLIBCXX_END_NAMESPACE_VERSION
+// Used to version individual components, e.g. std::_V2::error_category.
+# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X) inline namespace X {
+# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X) } // inline namespace X
#endif
// Inline namespaces for special modes: debug, parallel.
diff --git a/libstdc++-v3/include/bits/chrono.h b/libstdc++-v3/include/bits/chrono.h
index 421898516ae..745f9a81357 100644
--- a/libstdc++-v3/include/bits/chrono.h
+++ b/libstdc++-v3/include/bits/chrono.h
@@ -1099,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// compatibility definitions for previous versions. At some
// point, when these clocks settle down, the inlined namespaces
// can be removed. XXX GLIBCXX_ABI Deprecated
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/**
* @brief System clock.
@@ -1171,7 +1171,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
using high_resolution_clock = system_clock;
- } // end inline namespace _V2
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
#if __cplusplus >= 202002L
/// @addtogroup chrono
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index 1f07b9e6589..6619ff7bf1d 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -1190,8 +1190,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __m;
}
- inline namespace _V2
- {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/// This is a helper function for the rotate algorithm.
template<typename _ForwardIterator>
@@ -1398,7 +1397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
std::__iterator_category(__first));
}
- } // namespace _V2
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/**
* @brief Copy a sequence, rotating its elements.
diff --git a/libstdc++-v3/include/std/condition_variable b/libstdc++-v3/include/std/condition_variable
index 2a23e65bbd3..06c4ff9ebdd 100644
--- a/libstdc++-v3/include/std/condition_variable
+++ b/libstdc++-v3/include/std/condition_variable
@@ -234,7 +234,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
void (*_M_cb)(void*);
};
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/// condition_variable_any
// Like above, but mutex is not required to have try_lock.
@@ -439,7 +439,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
- } // end inline namespace
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/// @} group condition_variables
_GLIBCXX_END_NAMESPACE_VERSION
diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index 45a1d283556..dcef94e16e2 100644
--- a/libstdc++-v3/include/std/system_error
+++ b/libstdc++-v3/include/std/system_error
@@ -77,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif // C++17
/// @}
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/** @addtogroup diagnostics
* @{
@@ -168,7 +168,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_GLIBCXX_CONST const error_category& system_category() noexcept;
/// @}
- } // end inline namespace
+
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
/** @addtogroup diagnostics
* @{
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
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:13 ` Jonathan Wakely
0 siblings, 2 replies; 18+ messages in thread
From: François Dumont @ 2022-05-14 15:36 UTC (permalink / raw)
To: libstdc++
[-- Attachment #1: Type: text/plain, Size: 12441 bytes --]
Versioned namespace does not compile after this patch. With this patch
it compiles but does not link because of:
/usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
../src/c++11/.libs/libc++11convenience.a(chrono.o): in function
`std::__8::chrono::system_clock::now()':
chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0): multiple
definition of `std::__8::chrono::system_clock::now()'; /usr/bin/ld:
DWARF error: can't find .debug_ranges section.
.libs/compatibility-chrono.o:compatibility-chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0):
first defined here
/usr/bin/ld:
../src/c++11/.libs/libc++11convenience.a(chrono.o):(.rodata._ZNSt3__86chrono12system_clock9is_steadyE+0x0):
multiple definition of `std::__8::chrono::system_clock::is_steady';
.libs/compatibility-chrono.o:(.rodata._ZNSt3__86chrono12system_clock9is_steadyE+0x0):
first defined here
/usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
../src/c++11/.libs/libc++11convenience.a(system_error.o): in function
`std::__8::error_category::default_error_condition(int) const':
system_error.cc:(.text._ZNKSt3__814error_category23default_error_conditionEi+0x0):
multiple definition of
`std::__8::error_category::default_error_condition(int) const';
/usr/bin/ld: DWARF error: can't find .debug_ranges section.
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category23default_error_conditionEi+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::error_category::equivalent(int,
std::__8::error_condition const&) const':
system_error.cc:(.text._ZNKSt3__814error_category10equivalentEiRKNS_15error_conditionE+0x0):
multiple definition of `std::__8::error_category::equivalent(int,
std::__8::error_condition const&) const';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category10equivalentEiRKNS_15error_conditionE+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::error_category::equivalent(std::__8::error_code
const&, int) const':
system_error.cc:(.text._ZNKSt3__814error_category10equivalentERKNS_10error_codeEi+0x0):
multiple definition of
`std::__8::error_category::equivalent(std::__8::error_code const&, int)
const';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category10equivalentERKNS_10error_codeEi+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::error_category::~error_category()':
system_error.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0): multiple
definition of `std::__8::error_category::~error_category()';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::error_category::~error_category()':
system_error.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0): multiple
definition of `std::__8::error_category::~error_category()';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::error_category::~error_category()':
system_error.cc:(.text._ZNSt3__814error_categoryD0Ev+0x0): multiple
definition of `std::__8::error_category::~error_category()';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD0Ev+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::system_category()':
system_error.cc:(.text._ZNSt3__815system_categoryEv+0x0): multiple
definition of `std::__8::system_category()';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__815system_categoryEv+0x0):
first defined here
/usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
in function `std::__8::generic_category()':
system_error.cc:(.text._ZNSt3__816generic_categoryEv+0x0): multiple
definition of `std::__8::generic_category()';
.libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__816generic_categoryEv+0x0):
first defined here
On 13/05/22 14:40, Jonathan Wakely via Libstdc++ wrote:
> Tested powerpc64le-linux, pushed to trunk.
>
> Unlike the rest of the series, this isn't suitable for backporting
> because it changes the ABI for the gnu-versioned-namespace build. That's
> fine for GCC 13, but not OK to change within a release branch, e.g.
> between 12.1 and 12.2. If we want to backport it, the macro should do
> the same thing whether or not _GLIBCXX_INLINE_VERSION is set.
>
> -- >8 --
>
> Use macros to open and close the inline namespace _V2 that is used for
> ABI versioning of individual components such as chrono::system_clock.
>
> This allows the namespace to be hidden in the docs generated by Doxygen,
> so that we document std::foo instead of std::_V2::foo.
>
> This also makes it easy to remove that namespace entirely for the
> gnu-versioned-namespace build, where everything is already versioned as
> std::__8 and there are no backwards compatibility guarantees.
>
> libstdc++-v3/ChangeLog:
>
> * doc/doxygen/user.cfg.in (PREDEFINED): Expand new macros to
> nothing.
> * include/bits/c++config (_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE)
> (_GLIBCXX_END_INLINE_ABI_NAMESPACE): Define new macros.
> * include/bits/algorithmfwd.h (_V2::__rotate): Use new macros
> for the namespace.
> * include/bits/chrono.h (chrono::_V2::system_clock): Likewise.
> * include/bits/stl_algo.h (_V2::__rotate): Likewise.
> * include/std/condition_variable (_V2::condition_variable_any):
> Likewise.
> * include/std/system_error (_V2::error_category): Likewise.
> ---
> libstdc++-v3/doc/doxygen/user.cfg.in | 2 ++
> libstdc++-v3/include/bits/algorithmfwd.h | 15 ++++++++-------
> libstdc++-v3/include/bits/c++config | 11 +++++++++--
> libstdc++-v3/include/bits/chrono.h | 4 ++--
> libstdc++-v3/include/bits/stl_algo.h | 5 ++---
> libstdc++-v3/include/std/condition_variable | 4 ++--
> libstdc++-v3/include/std/system_error | 5 +++--
> 7 files changed, 28 insertions(+), 18 deletions(-)
>
> diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
> index b9babc3993e..2dbed727013 100644
> --- a/libstdc++-v3/doc/doxygen/user.cfg.in
> +++ b/libstdc++-v3/doc/doxygen/user.cfg.in
> @@ -2347,6 +2347,8 @@ PREDEFINED = __cplusplus=202002L \
> "_GLIBCXX_END_NAMESPACE_CONTAINER= " \
> "_GLIBCXX_END_NAMESPACE_CXX11= " \
> "_GLIBCXX_END_NAMESPACE_LDBL= " \
> + "-D_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)= " \
> + "-D_GLIBCXX_END_INLINE_ABI_NAMESPACE(X)= " \
> "_GLIBCXX_TEMPLATE_ARGS=... " \
> "_GLIBCXX_DEPRECATED= " \
> "_GLIBCXX_DEPRECATED_SUGGEST(E)= " \
> diff --git a/libstdc++-v3/include/bits/algorithmfwd.h b/libstdc++-v3/include/bits/algorithmfwd.h
> index 5271a90b501..aacc34e09e8 100644
> --- a/libstdc++-v3/include/bits/algorithmfwd.h
> +++ b/libstdc++-v3/include/bits/algorithmfwd.h
> @@ -601,13 +601,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> _OIter
> reverse_copy(_BIter, _BIter, _OIter);
>
> - inline namespace _V2
> - {
> - template<typename _FIter>
> - _GLIBCXX20_CONSTEXPR
> - _FIter
> - rotate(_FIter, _FIter, _FIter);
> - }
> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
> +
> + template<typename _FIter>
> + _GLIBCXX20_CONSTEXPR
> + _FIter
> + rotate(_FIter, _FIter, _FIter);
> +
> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>
> template<typename _FIter, typename _OIter>
> _GLIBCXX20_CONSTEXPR
> diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config
> index 2798b9786dc..150b0bc5834 100644
> --- a/libstdc++-v3/include/bits/c++config
> +++ b/libstdc++-v3/include/bits/c++config
> @@ -345,13 +345,16 @@ namespace __gnu_cxx
> # define _GLIBCXX_DEFAULT_ABI_TAG
> #endif
>
> -// Defined if inline namespaces are used for versioning.
> +// Non-zero if inline namespaces are used for versioning the entire library.
> #define _GLIBCXX_INLINE_VERSION
>
> -// Inline namespace for symbol versioning.
> #if _GLIBCXX_INLINE_VERSION
> +// Inline namespace for symbol versioning of (nearly) everything in std.
> # define _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace __8 {
> # define _GLIBCXX_END_NAMESPACE_VERSION }
> +// Unused when everything in std is versioned anyway.
> +# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)
> +# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X)
>
> namespace std
> {
> @@ -376,8 +379,12 @@ _GLIBCXX_END_NAMESPACE_VERSION
> }
>
> #else
> +// Unused.
> # define _GLIBCXX_BEGIN_NAMESPACE_VERSION
> # define _GLIBCXX_END_NAMESPACE_VERSION
> +// Used to version individual components, e.g. std::_V2::error_category.
> +# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X) inline namespace X {
> +# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X) } // inline namespace X
> #endif
>
> // Inline namespaces for special modes: debug, parallel.
> diff --git a/libstdc++-v3/include/bits/chrono.h b/libstdc++-v3/include/bits/chrono.h
> index 421898516ae..745f9a81357 100644
> --- a/libstdc++-v3/include/bits/chrono.h
> +++ b/libstdc++-v3/include/bits/chrono.h
> @@ -1099,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> // compatibility definitions for previous versions. At some
> // point, when these clocks settle down, the inlined namespaces
> // can be removed. XXX GLIBCXX_ABI Deprecated
> - inline namespace _V2 {
> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>
> /**
> * @brief System clock.
> @@ -1171,7 +1171,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> */
> using high_resolution_clock = system_clock;
>
> - } // end inline namespace _V2
> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>
> #if __cplusplus >= 202002L
> /// @addtogroup chrono
> diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
> index 1f07b9e6589..6619ff7bf1d 100644
> --- a/libstdc++-v3/include/bits/stl_algo.h
> +++ b/libstdc++-v3/include/bits/stl_algo.h
> @@ -1190,8 +1190,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> return __m;
> }
>
> - inline namespace _V2
> - {
> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>
> /// This is a helper function for the rotate algorithm.
> template<typename _ForwardIterator>
> @@ -1398,7 +1397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> std::__iterator_category(__first));
> }
>
> - } // namespace _V2
> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>
> /**
> * @brief Copy a sequence, rotating its elements.
> diff --git a/libstdc++-v3/include/std/condition_variable b/libstdc++-v3/include/std/condition_variable
> index 2a23e65bbd3..06c4ff9ebdd 100644
> --- a/libstdc++-v3/include/std/condition_variable
> +++ b/libstdc++-v3/include/std/condition_variable
> @@ -234,7 +234,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> void (*_M_cb)(void*);
> };
>
> - inline namespace _V2 {
> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>
> /// condition_variable_any
> // Like above, but mutex is not required to have try_lock.
> @@ -439,7 +439,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> #endif
> };
>
> - } // end inline namespace
> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>
> /// @} group condition_variables
> _GLIBCXX_END_NAMESPACE_VERSION
> diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
> index 45a1d283556..dcef94e16e2 100644
> --- a/libstdc++-v3/include/std/system_error
> +++ b/libstdc++-v3/include/std/system_error
> @@ -77,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> #endif // C++17
> /// @}
>
> - inline namespace _V2 {
> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>
> /** @addtogroup diagnostics
> * @{
> @@ -168,7 +168,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> _GLIBCXX_CONST const error_category& system_category() noexcept;
>
> /// @}
> - } // end inline namespace
> +
> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>
> /** @addtogroup diagnostics
> * @{
[-- Attachment #2: fix_version_namespace_build.patch --]
[-- Type: text/x-patch, Size: 1475 bytes --]
diff --git a/libstdc++-v3/src/c++11/chrono.cc b/libstdc++-v3/src/c++11/chrono.cc
index 6825b5bc4bf..9963b67f65a 100644
--- a/libstdc++-v3/src/c++11/chrono.cc
+++ b/libstdc++-v3/src/c++11/chrono.cc
@@ -44,7 +44,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace chrono
{
// XXX GLIBCXX_ABI Deprecated
- inline namespace _V2 {
+ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
constexpr bool system_clock::is_steady;
@@ -94,7 +94,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
}
- } // end inline namespace _V2
+ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) // end inline namespace _V2
} // namespace chrono
_GLIBCXX_END_NAMESPACE_VERSION
diff --git a/libstdc++-v3/src/c++11/system_error.cc b/libstdc++-v3/src/c++11/system_error.cc
index 7b1a5a20637..9839165fd79 100644
--- a/libstdc++-v3/src/c++11/system_error.cc
+++ b/libstdc++-v3/src/c++11/system_error.cc
@@ -526,11 +526,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
error_category::~error_category() = default;
+ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
const error_category&
- _V2::system_category() noexcept { return system_category_instance.obj; }
+ system_category() noexcept { return system_category_instance.obj; }
const error_category&
- _V2::generic_category() noexcept { return generic_category_instance.obj; }
+ generic_category() noexcept { return generic_category_instance.obj; }
+ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
system_error::~system_error() = default;
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
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 16:13 ` Jonathan Wakely
1 sibling, 1 reply; 18+ messages in thread
From: François Dumont @ 2022-05-16 4:27 UTC (permalink / raw)
To: libstdc++
[-- Attachment #1: Type: text/plain, Size: 13482 bytes --]
Based on what you told me recently maybe this patch is better. It does
not change the link errors.
On 14/05/22 17:36, François Dumont wrote:
> Versioned namespace does not compile after this patch. With this patch
> it compiles but does not link because of:
>
> /usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
> ../src/c++11/.libs/libc++11convenience.a(chrono.o): in function
> `std::__8::chrono::system_clock::now()':
> chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0): multiple
> definition of `std::__8::chrono::system_clock::now()'; /usr/bin/ld:
> DWARF error: can't find .debug_ranges section.
> .libs/compatibility-chrono.o:compatibility-chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0):
> first defined here
> /usr/bin/ld:
> ../src/c++11/.libs/libc++11convenience.a(chrono.o):(.rodata._ZNSt3__86chrono12system_clock9is_steadyE+0x0):
> multiple definition of `std::__8::chrono::system_clock::is_steady';
> .libs/compatibility-chrono.o:(.rodata._ZNSt3__86chrono12system_clock9is_steadyE+0x0):
> first defined here
> /usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
> ../src/c++11/.libs/libc++11convenience.a(system_error.o): in function
> `std::__8::error_category::default_error_condition(int) const':
> system_error.cc:(.text._ZNKSt3__814error_category23default_error_conditionEi+0x0):
> multiple definition of
> `std::__8::error_category::default_error_condition(int) const';
> /usr/bin/ld: DWARF error: can't find .debug_ranges section.
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category23default_error_conditionEi+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::error_category::equivalent(int,
> std::__8::error_condition const&) const':
> system_error.cc:(.text._ZNKSt3__814error_category10equivalentEiRKNS_15error_conditionE+0x0):
> multiple definition of `std::__8::error_category::equivalent(int,
> std::__8::error_condition const&) const';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category10equivalentEiRKNS_15error_conditionE+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::error_category::equivalent(std::__8::error_code
> const&, int) const':
> system_error.cc:(.text._ZNKSt3__814error_category10equivalentERKNS_10error_codeEi+0x0):
> multiple definition of
> `std::__8::error_category::equivalent(std::__8::error_code const&,
> int) const';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNKSt3__814error_category10equivalentERKNS_10error_codeEi+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::error_category::~error_category()':
> system_error.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0): multiple
> definition of `std::__8::error_category::~error_category()';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::error_category::~error_category()':
> system_error.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0): multiple
> definition of `std::__8::error_category::~error_category()';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD2Ev+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::error_category::~error_category()':
> system_error.cc:(.text._ZNSt3__814error_categoryD0Ev+0x0): multiple
> definition of `std::__8::error_category::~error_category()';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__814error_categoryD0Ev+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::system_category()':
> system_error.cc:(.text._ZNSt3__815system_categoryEv+0x0): multiple
> definition of `std::__8::system_category()';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__815system_categoryEv+0x0):
> first defined here
> /usr/bin/ld: ../src/c++11/.libs/libc++11convenience.a(system_error.o):
> in function `std::__8::generic_category()':
> system_error.cc:(.text._ZNSt3__816generic_categoryEv+0x0): multiple
> definition of `std::__8::generic_category()';
> .libs/compatibility-c++0x.o:compatibility-c++0x.cc:(.text._ZNSt3__816generic_categoryEv+0x0):
> first defined here
>
>
> On 13/05/22 14:40, Jonathan Wakely via Libstdc++ wrote:
>> Tested powerpc64le-linux, pushed to trunk.
>>
>> Unlike the rest of the series, this isn't suitable for backporting
>> because it changes the ABI for the gnu-versioned-namespace build. That's
>> fine for GCC 13, but not OK to change within a release branch, e.g.
>> between 12.1 and 12.2. If we want to backport it, the macro should do
>> the same thing whether or not _GLIBCXX_INLINE_VERSION is set.
>>
>> -- >8 --
>>
>> Use macros to open and close the inline namespace _V2 that is used for
>> ABI versioning of individual components such as chrono::system_clock.
>>
>> This allows the namespace to be hidden in the docs generated by Doxygen,
>> so that we document std::foo instead of std::_V2::foo.
>>
>> This also makes it easy to remove that namespace entirely for the
>> gnu-versioned-namespace build, where everything is already versioned as
>> std::__8 and there are no backwards compatibility guarantees.
>>
>> libstdc++-v3/ChangeLog:
>>
>> * doc/doxygen/user.cfg.in (PREDEFINED): Expand new macros to
>> nothing.
>> * include/bits/c++config (_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE)
>> (_GLIBCXX_END_INLINE_ABI_NAMESPACE): Define new macros.
>> * include/bits/algorithmfwd.h (_V2::__rotate): Use new macros
>> for the namespace.
>> * include/bits/chrono.h (chrono::_V2::system_clock): Likewise.
>> * include/bits/stl_algo.h (_V2::__rotate): Likewise.
>> * include/std/condition_variable (_V2::condition_variable_any):
>> Likewise.
>> * include/std/system_error (_V2::error_category): Likewise.
>> ---
>> libstdc++-v3/doc/doxygen/user.cfg.in | 2 ++
>> libstdc++-v3/include/bits/algorithmfwd.h | 15 ++++++++-------
>> libstdc++-v3/include/bits/c++config | 11 +++++++++--
>> libstdc++-v3/include/bits/chrono.h | 4 ++--
>> libstdc++-v3/include/bits/stl_algo.h | 5 ++---
>> libstdc++-v3/include/std/condition_variable | 4 ++--
>> libstdc++-v3/include/std/system_error | 5 +++--
>> 7 files changed, 28 insertions(+), 18 deletions(-)
>>
>> diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in
>> b/libstdc++-v3/doc/doxygen/user.cfg.in
>> index b9babc3993e..2dbed727013 100644
>> --- a/libstdc++-v3/doc/doxygen/user.cfg.in
>> +++ b/libstdc++-v3/doc/doxygen/user.cfg.in
>> @@ -2347,6 +2347,8 @@ PREDEFINED = __cplusplus=202002L \
>> "_GLIBCXX_END_NAMESPACE_CONTAINER= " \
>> "_GLIBCXX_END_NAMESPACE_CXX11= " \
>> "_GLIBCXX_END_NAMESPACE_LDBL= " \
>> + "-D_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)= " \
>> + "-D_GLIBCXX_END_INLINE_ABI_NAMESPACE(X)= " \
>> "_GLIBCXX_TEMPLATE_ARGS=... " \
>> "_GLIBCXX_DEPRECATED= " \
>> "_GLIBCXX_DEPRECATED_SUGGEST(E)= " \
>> diff --git a/libstdc++-v3/include/bits/algorithmfwd.h
>> b/libstdc++-v3/include/bits/algorithmfwd.h
>> index 5271a90b501..aacc34e09e8 100644
>> --- a/libstdc++-v3/include/bits/algorithmfwd.h
>> +++ b/libstdc++-v3/include/bits/algorithmfwd.h
>> @@ -601,13 +601,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> _OIter
>> reverse_copy(_BIter, _BIter, _OIter);
>> - inline namespace _V2
>> - {
>> - template<typename _FIter>
>> - _GLIBCXX20_CONSTEXPR
>> - _FIter
>> - rotate(_FIter, _FIter, _FIter);
>> - }
>> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>> +
>> + template<typename _FIter>
>> + _GLIBCXX20_CONSTEXPR
>> + _FIter
>> + rotate(_FIter, _FIter, _FIter);
>> +
>> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>> template<typename _FIter, typename _OIter>
>> _GLIBCXX20_CONSTEXPR
>> diff --git a/libstdc++-v3/include/bits/c++config
>> b/libstdc++-v3/include/bits/c++config
>> index 2798b9786dc..150b0bc5834 100644
>> --- a/libstdc++-v3/include/bits/c++config
>> +++ b/libstdc++-v3/include/bits/c++config
>> @@ -345,13 +345,16 @@ namespace __gnu_cxx
>> # define _GLIBCXX_DEFAULT_ABI_TAG
>> #endif
>> -// Defined if inline namespaces are used for versioning.
>> +// Non-zero if inline namespaces are used for versioning the entire
>> library.
>> #define _GLIBCXX_INLINE_VERSION
>> -// Inline namespace for symbol versioning.
>> #if _GLIBCXX_INLINE_VERSION
>> +// Inline namespace for symbol versioning of (nearly) everything in
>> std.
>> # define _GLIBCXX_BEGIN_NAMESPACE_VERSION namespace __8 {
>> # define _GLIBCXX_END_NAMESPACE_VERSION }
>> +// Unused when everything in std is versioned anyway.
>> +# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X)
>> +# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X)
>> namespace std
>> {
>> @@ -376,8 +379,12 @@ _GLIBCXX_END_NAMESPACE_VERSION
>> }
>> #else
>> +// Unused.
>> # define _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> # define _GLIBCXX_END_NAMESPACE_VERSION
>> +// Used to version individual components, e.g.
>> std::_V2::error_category.
>> +# define _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(X) inline namespace X {
>> +# define _GLIBCXX_END_INLINE_ABI_NAMESPACE(X) } // inline namespace X
>> #endif
>> // Inline namespaces for special modes: debug, parallel.
>> diff --git a/libstdc++-v3/include/bits/chrono.h
>> b/libstdc++-v3/include/bits/chrono.h
>> index 421898516ae..745f9a81357 100644
>> --- a/libstdc++-v3/include/bits/chrono.h
>> +++ b/libstdc++-v3/include/bits/chrono.h
>> @@ -1099,7 +1099,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> // compatibility definitions for previous versions. At some
>> // point, when these clocks settle down, the inlined namespaces
>> // can be removed. XXX GLIBCXX_ABI Deprecated
>> - inline namespace _V2 {
>> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>> /**
>> * @brief System clock.
>> @@ -1171,7 +1171,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> */
>> using high_resolution_clock = system_clock;
>> - } // end inline namespace _V2
>> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>> #if __cplusplus >= 202002L
>> /// @addtogroup chrono
>> diff --git a/libstdc++-v3/include/bits/stl_algo.h
>> b/libstdc++-v3/include/bits/stl_algo.h
>> index 1f07b9e6589..6619ff7bf1d 100644
>> --- a/libstdc++-v3/include/bits/stl_algo.h
>> +++ b/libstdc++-v3/include/bits/stl_algo.h
>> @@ -1190,8 +1190,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> return __m;
>> }
>> - inline namespace _V2
>> - {
>> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>> /// This is a helper function for the rotate algorithm.
>> template<typename _ForwardIterator>
>> @@ -1398,7 +1397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> std::__iterator_category(__first));
>> }
>> - } // namespace _V2
>> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>> /**
>> * @brief Copy a sequence, rotating its elements.
>> diff --git a/libstdc++-v3/include/std/condition_variable
>> b/libstdc++-v3/include/std/condition_variable
>> index 2a23e65bbd3..06c4ff9ebdd 100644
>> --- a/libstdc++-v3/include/std/condition_variable
>> +++ b/libstdc++-v3/include/std/condition_variable
>> @@ -234,7 +234,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> void (*_M_cb)(void*);
>> };
>> - inline namespace _V2 {
>> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>> /// condition_variable_any
>> // Like above, but mutex is not required to have try_lock.
>> @@ -439,7 +439,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> #endif
>> };
>> - } // end inline namespace
>> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>> /// @} group condition_variables
>> _GLIBCXX_END_NAMESPACE_VERSION
>> diff --git a/libstdc++-v3/include/std/system_error
>> b/libstdc++-v3/include/std/system_error
>> index 45a1d283556..dcef94e16e2 100644
>> --- a/libstdc++-v3/include/std/system_error
>> +++ b/libstdc++-v3/include/std/system_error
>> @@ -77,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> #endif // C++17
>> /// @}
>> - inline namespace _V2 {
>> +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
>> /** @addtogroup diagnostics
>> * @{
>> @@ -168,7 +168,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
>> _GLIBCXX_CONST const error_category& system_category() noexcept;
>> /// @}
>> - } // end inline namespace
>> +
>> +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
>> /** @addtogroup diagnostics
>> * @{
>
[-- Attachment #2: fix_version_namespace_build2.patch --]
[-- Type: text/x-patch, Size: 1780 bytes --]
diff --git a/libstdc++-v3/src/c++11/chrono.cc b/libstdc++-v3/src/c++11/chrono.cc
index 6825b5bc4bf..e52211d9aab 100644
--- a/libstdc++-v3/src/c++11/chrono.cc
+++ b/libstdc++-v3/src/c++11/chrono.cc
@@ -39,13 +39,8 @@
namespace std _GLIBCXX_VISIBILITY(default)
{
-_GLIBCXX_BEGIN_NAMESPACE_VERSION
-
namespace chrono
{
- // XXX GLIBCXX_ABI Deprecated
- inline namespace _V2 {
-
constexpr bool system_clock::is_steady;
system_clock::time_point
@@ -93,9 +88,5 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return time_point(system_clock::now().time_since_epoch());
#endif
}
-
- } // end inline namespace _V2
} // namespace chrono
-
-_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/src/c++11/system_error.cc b/libstdc++-v3/src/c++11/system_error.cc
index 7b1a5a20637..cc2c491cdbb 100644
--- a/libstdc++-v3/src/c++11/system_error.cc
+++ b/libstdc++-v3/src/c++11/system_error.cc
@@ -516,8 +516,6 @@ namespace
namespace std _GLIBCXX_VISIBILITY(default)
{
-_GLIBCXX_BEGIN_NAMESPACE_VERSION
-
void
__throw_system_error(int __i __attribute__((unused)))
{
@@ -527,10 +525,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
error_category::~error_category() = default;
const error_category&
- _V2::system_category() noexcept { return system_category_instance.obj; }
+ system_category() noexcept { return system_category_instance.obj; }
const error_category&
- _V2::generic_category() noexcept { return generic_category_instance.obj; }
+ generic_category() noexcept { return generic_category_instance.obj; }
system_error::~system_error() = default;
@@ -560,6 +558,4 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return {msg.c_str(), msg.length()};
}
#endif
-
-_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
2022-05-16 4:27 ` François Dumont
@ 2022-05-16 16:19 ` Jonathan Wakely
2022-05-16 17:04 ` François Dumont
0 siblings, 1 reply; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-16 16:19 UTC (permalink / raw)
To: François Dumont; +Cc: libstdc++
On Mon, 16 May 2022 at 05:28, François Dumont via Libstdc++
<libstdc++@gcc.gnu.org> wrote:
>
> Based on what you told me recently maybe this patch is better. It does
> not change the link errors.
We need to be a little careful about just removing those macros.
For definitions that use qualified names, the macros are not needed.
For example:
namespace std { inline namespace __8 {
struct foo {
void bar(); // #1
};
} }
namespace std {
void foo::bar() { } // #2
}
The definition at #2 works correctly, because name lookup for 'foo'
finds std::__8::foo, so it's a definition of the member declared at
#1.
But if we have a definition using an unqualified name, that doesn't
work the same. For example:
namespace std { inline namespace __8 {
void func(); // #3
} }
namespace std {
void func() { } // #4
}
The definition at #4 doesn't need to do any name lookup, so it just
defines (and declares) a new function directly in namespace std. This
means we have std::__8::func declared at #3 and std::func declared at
#4, and so trying to call std::func() would be ambiguous.
So we don't need to _add_ the macros to files where the symbols are
already being defined correctly (which is why your recent patch was
not needed). And we can remove them from _some_ source files. But if
we remove all source files, some of those removals would be wrong.
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
2022-05-16 16:19 ` Jonathan Wakely
@ 2022-05-16 17:04 ` François Dumont
0 siblings, 0 replies; 18+ messages in thread
From: François Dumont @ 2022-05-16 17:04 UTC (permalink / raw)
To: Jonathan Wakely; +Cc: libstdc++
On 16/05/22 18:19, Jonathan Wakely wrote:
> On Mon, 16 May 2022 at 05:28, François Dumont via Libstdc++
> <libstdc++@gcc.gnu.org> wrote:
>> Based on what you told me recently maybe this patch is better. It does
>> not change the link errors.
> We need to be a little careful about just removing those macros.
>
> For definitions that use qualified names, the macros are not needed.
> For example:
>
> namespace std { inline namespace __8 {
> struct foo {
> void bar(); // #1
> };
> } }
>
> namespace std {
> void foo::bar() { } // #2
> }
>
> The definition at #2 works correctly, because name lookup for 'foo'
> finds std::__8::foo, so it's a definition of the member declared at
> #1.
>
> But if we have a definition using an unqualified name, that doesn't
> work the same. For example:
>
> namespace std { inline namespace __8 {
> void func(); // #3
> } }
>
> namespace std {
> void func() { } // #4
> }
>
> The definition at #4 doesn't need to do any name lookup, so it just
> defines (and declares) a new function directly in namespace std. This
> means we have std::__8::func declared at #3 and std::func declared at
> #4, and so trying to call std::func() would be ambiguous.
>
> So we don't need to _add_ the macros to files where the symbols are
> already being defined correctly (which is why your recent patch was
> not needed). And we can remove them from _some_ source files. But if
> we remove all source files, some of those removals would be wrong.
>
And thanks for this explanation too, I wasn't considering all use cases
indeed.
So no rush to do any cleanup, good.
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
2022-05-14 15:36 ` François Dumont
2022-05-16 4:27 ` François Dumont
@ 2022-05-16 16:13 ` Jonathan Wakely
2022-05-16 16:59 ` François Dumont
1 sibling, 1 reply; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-16 16:13 UTC (permalink / raw)
To: François Dumont; +Cc: libstdc++
[-- Attachment #1: Type: text/plain, Size: 1158 bytes --]
On Sat, 14 May 2022 at 16:36, François Dumont via Libstdc++
<libstdc++@gcc.gnu.org> wrote:
>
> Versioned namespace does not compile after this patch. With this patch
> it compiles but does not link because of:
>
> /usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
> ../src/c++11/.libs/libc++11convenience.a(chrono.o): in function
> `std::__8::chrono::system_clock::now()':
> chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0): multiple
> definition of `std::__8::chrono::system_clock::now()'; /usr/bin/ld:
> DWARF error: can't find .debug_ranges section.
> .libs/compatibility-chrono.o:compatibility-chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0):
> first defined here
Oops, I knew I'd forgotten to check something!
I think the attached patch would be better. This stops defining the
C++0x compat symbols for the versioned namespace. Those symbols only
exist for backwards compatibility with ancient versions of
libstdc++.so.6 (from GCC 4.6 and similar vintages). We don't need
those symbols in libstdc++.so.8 at all.
This fixes the versioned namespace build, I'm running the tests now.
[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 6160 bytes --]
commit db4b611a49421fb5619aefbdf892d62d6eee6e47
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Mon May 16 16:54:52 2022 +0100
libstdc++: Stop defining C++0x compat symbols for versioned namespace
The src/c++11/compatibility*-c++0x.cc files define symbols that need to
be exported for ancient versions of libstdc++.so.6 due to changes
between C++0x and the final C++11 standard. Those symbols are not needed
in the libstdc++.so.8 library, and we can skip building them entirely.
This also fixes the build failure I introduced last week when making the
versioned namespace config not use the _V2 namespace for compat symbols.
libstdc++-v3/ChangeLog:
* src/Makefile.am [ENABLE_SYMVERS_GNU_NAMESPACE] (cxx11_sources):
Do not build the compatibility*-c++0x.cc objects.
* src/Makefile.in: Regenerate.
* src/c++11/compatibility-c++0x.cc [_GLIBCXX_INLINE_VERSION]:
Refuse to build for the versioned namespace.
* src/c++11/compatibility-chrono.cc: Likewise.
* src/c++11/compatibility-condvar.cc: Likewise.
* src/c++11/compatibility-thread-c++0x.cc: Likewise.
* src/c++11/chrono.cc (system_clock, steady_clock):
Use macros to define in inline namespace _V2, matching the
declarations in <system_error>.
* src/c++11/system_error.cc (system_category, generic_category):
Likewise.
diff --git a/libstdc++-v3/src/Makefile.am b/libstdc++-v3/src/Makefile.am
index 9c3f4aca655..b83c222d51d 100644
--- a/libstdc++-v3/src/Makefile.am
+++ b/libstdc++-v3/src/Makefile.am
@@ -96,6 +96,16 @@ else
ldbl_alt128_compat_sources =
endif
+if ENABLE_SYMVERS_GNU_NAMESPACE
+cxx0x_compat_sources =
+else
+cxx0x_compat_sources = \
+ compatibility-atomic-c++0x.cc \
+ compatibility-c++0x.cc \
+ compatibility-chrono.cc \
+ compatibility-condvar.cc \
+ compatibility-thread-c++0x.cc
+endif
parallel_compat_sources = \
compatibility-parallel_list.cc compatibility-parallel_list-2.cc
@@ -108,11 +118,7 @@ cxx98_sources = \
${ldbl_compat_sources}
cxx11_sources = \
- compatibility-c++0x.cc \
- compatibility-atomic-c++0x.cc \
- compatibility-thread-c++0x.cc \
- compatibility-chrono.cc \
- compatibility-condvar.cc \
+ ${cxx0x_compat_sources} \
${ldbl_alt128_compat_sources}
libstdc___la_SOURCES = $(cxx98_sources) $(cxx11_sources)
diff --git a/libstdc++-v3/src/c++11/chrono.cc b/libstdc++-v3/src/c++11/chrono.cc
index 6825b5bc4bf..5539d8cbedd 100644
--- a/libstdc++-v3/src/c++11/chrono.cc
+++ b/libstdc++-v3/src/c++11/chrono.cc
@@ -43,8 +43,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace chrono
{
- // XXX GLIBCXX_ABI Deprecated
- inline namespace _V2 {
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
constexpr bool system_clock::is_steady;
@@ -94,7 +93,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
}
- } // end inline namespace _V2
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
} // namespace chrono
_GLIBCXX_END_NAMESPACE_VERSION
diff --git a/libstdc++-v3/src/c++11/compatibility-c++0x.cc b/libstdc++-v3/src/c++11/compatibility-c++0x.cc
index d48f5bd1e28..768dd666d00 100644
--- a/libstdc++-v3/src/c++11/compatibility-c++0x.cc
+++ b/libstdc++-v3/src/c++11/compatibility-c++0x.cc
@@ -40,6 +40,10 @@
# error "compatibility-c++0x.cc must be compiled with -std=gnu++0x"
#endif
+#if _GLIBCXX_INLINE_VERSION
+# error "compatibility-thread-c++0x.cc is not needed for gnu-versioned-namespace"
+#endif
+
#ifdef _GLIBCXX_SHARED
namespace std _GLIBCXX_VISIBILITY(default)
diff --git a/libstdc++-v3/src/c++11/compatibility-chrono.cc b/libstdc++-v3/src/c++11/compatibility-chrono.cc
index 38b96e811fb..6beb8b39a25 100644
--- a/libstdc++-v3/src/c++11/compatibility-chrono.cc
+++ b/libstdc++-v3/src/c++11/compatibility-chrono.cc
@@ -24,6 +24,10 @@
#include <bits/c++config.h>
+#if _GLIBCXX_INLINE_VERSION
+# error "compatibility-thread-c++0x.cc is not needed for gnu-versioned-namespace"
+#endif
+
#ifdef _GLIBCXX_USE_C99_STDINT_TR1
#ifdef _GLIBCXX_USE_GETTIMEOFDAY
diff --git a/libstdc++-v3/src/c++11/compatibility-condvar.cc b/libstdc++-v3/src/c++11/compatibility-condvar.cc
index ea3e11efeda..e3a8b8403ca 100644
--- a/libstdc++-v3/src/c++11/compatibility-condvar.cc
+++ b/libstdc++-v3/src/c++11/compatibility-condvar.cc
@@ -28,6 +28,10 @@
# error "compatibility-condvar-c++0x.cc must be compiled with -std=gnu++11"
#endif
+#if _GLIBCXX_INLINE_VERSION
+# error "compatibility-thread-c++0x.cc is not needed for gnu-versioned-namespace"
+#endif
+
#if defined(_GLIBCXX_HAS_GTHREADS) && defined(_GLIBCXX_USE_C99_STDINT_TR1)
#define condition_variable_any condition_variable_anyXX
diff --git a/libstdc++-v3/src/c++11/compatibility-thread-c++0x.cc b/libstdc++-v3/src/c++11/compatibility-thread-c++0x.cc
index dbacda2bc44..d920f9f0345 100644
--- a/libstdc++-v3/src/c++11/compatibility-thread-c++0x.cc
+++ b/libstdc++-v3/src/c++11/compatibility-thread-c++0x.cc
@@ -35,6 +35,10 @@
# error "compatibility-thread-c++0x.cc must be compiled with -std=gnu++0x"
#endif
+#if _GLIBCXX_INLINE_VERSION
+# error "compatibility-thread-c++0x.cc is not needed for gnu-versioned-namespace"
+#endif
+
#define _GLIBCXX_ASM_SYMVER(cur, old, version) \
asm (".symver " #cur "," #old "@@@" #version);
diff --git a/libstdc++-v3/src/c++11/system_error.cc b/libstdc++-v3/src/c++11/system_error.cc
index 7b1a5a20637..8c13642408d 100644
--- a/libstdc++-v3/src/c++11/system_error.cc
+++ b/libstdc++-v3/src/c++11/system_error.cc
@@ -526,11 +526,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
error_category::~error_category() = default;
- const error_category&
- _V2::system_category() noexcept { return system_category_instance.obj; }
+_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
const error_category&
- _V2::generic_category() noexcept { return generic_category_instance.obj; }
+ system_category() noexcept { return system_category_instance.obj; }
+
+ const error_category&
+ generic_category() noexcept { return generic_category_instance.obj; }
+
+_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
system_error::~system_error() = default;
^ permalink raw reply [flat|nested] 18+ messages in thread* Re: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2
2022-05-16 16:13 ` Jonathan Wakely
@ 2022-05-16 16:59 ` François Dumont
0 siblings, 0 replies; 18+ messages in thread
From: François Dumont @ 2022-05-16 16:59 UTC (permalink / raw)
To: Jonathan Wakely; +Cc: libstdc++
Great, thanks for explaining what compatibility files are for.
I can't wait to see the impact of this patch on the abi tests.
Especially for my patch to use cxx11 abi std::string for the version
namespace mode.
François
On 16/05/22 18:13, Jonathan Wakely wrote:
> On Sat, 14 May 2022 at 16:36, François Dumont via Libstdc++
> <libstdc++@gcc.gnu.org> wrote:
>> Versioned namespace does not compile after this patch. With this patch
>> it compiles but does not link because of:
>>
>> /usr/bin/ld: /usr/bin/ld: DWARF error: can't find .debug_ranges section.
>> ../src/c++11/.libs/libc++11convenience.a(chrono.o): in function
>> `std::__8::chrono::system_clock::now()':
>> chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0): multiple
>> definition of `std::__8::chrono::system_clock::now()'; /usr/bin/ld:
>> DWARF error: can't find .debug_ranges section.
>> .libs/compatibility-chrono.o:compatibility-chrono.cc:(.text._ZNSt3__86chrono12system_clock3nowEv+0x0):
>> first defined here
> Oops, I knew I'd forgotten to check something!
>
> I think the attached patch would be better. This stops defining the
> C++0x compat symbols for the versioned namespace. Those symbols only
> exist for backwards compatibility with ancient versions of
> libstdc++.so.6 (from GCC 4.6 and similar vintages). We don't need
> those symbols in libstdc++.so.8 at all.
>
> This fixes the versioned namespace build, I'm running the tests now.
^ permalink raw reply [flat|nested] 18+ messages in thread
* [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits
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-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
` (7 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/ptr_traits.h: Add some doxygen comments.
---
libstdc++-v3/include/bits/ptr_traits.h | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/libstdc++-v3/include/bits/ptr_traits.h b/libstdc++-v3/include/bits/ptr_traits.h
index 047efa5cf28..8360c3b6557 100644
--- a/libstdc++-v3/include/bits/ptr_traits.h
+++ b/libstdc++-v3/include/bits/ptr_traits.h
@@ -47,6 +47,8 @@ namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
+ /// @cond undocumented
+
class __undefined;
// For a specialization `SomeTemplate<T, Types...>` the member `type` is T,
@@ -91,6 +93,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using __ptr_traits_elem_t = typename __ptr_traits_elem<_Ptr>::type;
#endif
+ /// @endcond
+
// Define pointer_traits<P>::pointer_to.
template<typename _Ptr, typename _Elt, bool = is_void<_Elt>::value>
struct __ptr_traits_ptr_to
@@ -187,6 +191,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Uniform interface to all pointer-like types
+ * @headerfile memory
* @ingroup pointer_abstractions
* @since C++11
*/
@@ -203,6 +208,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Partial specialization for built-in pointers.
+ * @headerfile memory
* @ingroup pointer_abstractions
* @since C++11
*/
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 05/12] libstdc++: Improve doxygen docs for <system_error>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (2 preceding siblings ...)
2022-05-13 12:40 ` [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 06/12] libstdc++: Improve doxygen docs for <atomic> Jonathan Wakely
` (6 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/std/system_error: Improve doxygen comments.
---
libstdc++-v3/include/std/system_error | 136 ++++++++++++++++++++------
1 file changed, 107 insertions(+), 29 deletions(-)
diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index dcef94e16e2..95508da73dd 100644
--- a/libstdc++-v3/include/std/system_error
+++ b/libstdc++-v3/include/std/system_error
@@ -85,13 +85,20 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
/** Abstract base class for types defining a category of error codes.
*
- * An error category defines a context that give meaning to the integer
+ * An error category defines a context that gives meaning to the integer
* stored in an `error_code` or `error_condition` object. For example,
* the standard `errno` constants such a `EINVAL` and `ENOMEM` are
* associated with the "generic" category and other OS-specific error
* numbers are associated with the "system" category, but a user-defined
* category might give different meanings to the same numerical values.
*
+ * A user-defined category can override the `equivalent` member functions
+ * to define correspondence between errors in different categories.
+ * For example, a category for errors from disk I/O could consider some
+ * of its error numbers equivalent to ENOSPC and ENOENT in the generic
+ * category.
+ *
+ * @headerfile system_error
* @since C++11
*/
class error_category
@@ -104,6 +111,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
error_category(const error_category&) = delete;
error_category& operator=(const error_category&) = delete;
+ /// A string that identifies the error category.
virtual const char*
name() const noexcept = 0;
@@ -118,6 +126,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
_M_message(int) const;
public:
+ /// A description of the error condition corresponding to the number.
_GLIBCXX_DEFAULT_ABI_TAG
virtual string
message(int) const = 0;
@@ -131,31 +140,36 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2)
#endif
public:
+ /// Return an error_condition corresponding to `i` in this category.
virtual error_condition
default_error_condition(int __i) const noexcept;
+ /// Test whether `cond` corresponds to `i` for this category.
virtual bool
equivalent(int __i, const error_condition& __cond) const noexcept;
+ /// Test whether `code` corresponds to `i` for this category.
virtual bool
equivalent(const error_code& __code, int __i) const noexcept;
+ /// An error_category only compares equal to itself.
bool
operator==(const error_category& __other) const noexcept
{ return this == &__other; }
+ /// Ordered comparison that defines a total order for error categories.
#if __cpp_lib_three_way_comparison
strong_ordering
operator<=>(const error_category& __rhs) const noexcept
{ return std::compare_three_way()(this, &__rhs); }
#else
- bool
- operator!=(const error_category& __other) const noexcept
- { return this != &__other; }
-
bool
operator<(const error_category& __other) const noexcept
{ return less<const error_category*>()(this, &__other); }
+
+ bool
+ operator!=(const error_category& __other) const noexcept
+ { return this != &__other; }
#endif
};
@@ -191,8 +205,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* library might be represented by an HTTP response status code (e.g. 404)
* and a custom category defined by the library.
*
+ * @headerfile system_error
* @since C++11
- * @ingroup diagnostics
*/
class error_code
{
@@ -226,20 +240,25 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
operator=(_ErrorCodeEnum __e) noexcept
{ return *this = make_error_code(__e); }
+ /// The error value.
int
value() const noexcept { return _M_value; }
+ /// The error category that this error belongs to.
const error_category&
category() const noexcept { return *_M_cat; }
+ /// An `error_condition` for this error's category and value.
error_condition
default_error_condition() const noexcept;
+ /// The category's description of the value.
_GLIBCXX_DEFAULT_ABI_TAG
string
message() const
{ return category().message(value()); }
+ /// Test whether `value()` is non-zero.
explicit operator bool() const noexcept
{ return _M_value != 0; }
@@ -249,14 +268,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
const error_category* _M_cat;
};
- // 19.4.2.6 non-member functions
-
- /// @relates error_code @{
+ // C++11 19.5.2.5 non-member functions
+ /** Create an `error_code` representing a standard `errc` condition.
+ *
+ * The `std::errc` constants correspond to `errno` macros and so use the
+ * generic category.
+ *
+ * @relates error_code
+ * @since C++11
+ */
inline error_code
make_error_code(errc __e) noexcept
{ return error_code(static_cast<int>(__e), generic_category()); }
+ /** Ordered comparison for std::error_code.
+ *
+ * This defines a total order by comparing the categories, and then
+ * if they are equal comparing the values.
+ *
+ * @relates error_code
+ * @since C++11
+ */
#if __cpp_lib_three_way_comparison
inline strong_ordering
operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept
@@ -275,13 +308,16 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
}
#endif
+ /** Write a std::error_code to an ostream.
+ *
+ * @relates error_code
+ * @since C++11
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e)
{ return (__os << __e.category().name() << ':' << __e.value()); }
- /// @}
-
error_condition make_error_condition(errc) noexcept;
/** Class error_condition
@@ -293,14 +329,17 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* An `error_condition` represents something that the program can test for,
* and subsequently take appropriate action.
*
+ * @headerfile system_error
* @since C++11
*/
class error_condition
{
public:
+ /// Initialize with a zero (no error) value and the generic category.
error_condition() noexcept
: _M_value(0), _M_cat(&generic_category()) { }
+ /// Initialize with the specified value and category.
error_condition(int __v, const error_category& __cat) noexcept
: _M_value(__v), _M_cat(&__cat) { }
@@ -309,6 +348,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
error_condition(_ErrorConditionEnum __e) noexcept
{ *this = make_error_condition(__e); }
+ /// Set the value and category.
void
assign(int __v, const error_category& __cat) noexcept
{
@@ -323,22 +363,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
operator=(_ErrorConditionEnum __e) noexcept
{ return *this = make_error_condition(__e); }
+ /// Reset the value and category to the default-constructed state.
void
clear() noexcept
{ assign(0, generic_category()); }
- // 19.4.3.4 observers
+ // C++11 19.5.3.4 observers
+
+ /// The error value.
int
value() const noexcept { return _M_value; }
+ /// The error category that this error belongs to.
const error_category&
category() const noexcept { return *_M_cat; }
+ /// The category's description of the value.
_GLIBCXX_DEFAULT_ABI_TAG
string
message() const
{ return category().message(value()); }
+ /// Test whether `value()` is non-zero.
explicit operator bool() const noexcept
{ return _M_value != 0; }
@@ -348,42 +394,75 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
const error_category* _M_cat;
};
- // 19.4.3.6 non-member functions
+ // C++11 19.5.3.5 non-member functions
- /// Create an `error_condition` representing a standard `errc` condition.
- /// @relates error_condition
+ /** Create an `error_condition` representing a standard `errc` condition.
+ *
+ * The `std::errc` constants correspond to `errno` macros and so use the
+ * generic category.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline error_condition
make_error_condition(errc __e) noexcept
{ return error_condition(static_cast<int>(__e), generic_category()); }
- // 19.4.4 Comparison operators
+ // C++11 19.5.4 Comparison operators
- /// @relates error_code
+ /** Equality comparison for std::error_code.
+ *
+ * Returns true only if they have the same category and the same value.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_code& __lhs, const error_code& __rhs) noexcept
- { return (__lhs.category() == __rhs.category()
- && __lhs.value() == __rhs.value()); }
+ {
+ return __lhs.category() == __rhs.category()
+ && __lhs.value() == __rhs.value();
+ }
- /// @relates error_code
+ /** Equality comparison for std::error_code and std::error_condition.
+ *
+ * Uses each category's `equivalent` member function to check whether
+ * the values correspond to an equivalent error in that category.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
{
- return (__lhs.category().equivalent(__lhs.value(), __rhs)
- || __rhs.category().equivalent(__lhs, __rhs.value()));
+ return __lhs.category().equivalent(__lhs.value(), __rhs)
+ || __rhs.category().equivalent(__lhs, __rhs.value());
}
- /// @relates error_condition
+ /** Equality comparison for std::error_condition.
+ *
+ * Returns true only if they have the same category and the same value.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
inline bool
operator==(const error_condition& __lhs,
const error_condition& __rhs) noexcept
{
- return (__lhs.category() == __rhs.category()
- && __lhs.value() == __rhs.value());
+ return __lhs.category() == __rhs.category()
+ && __lhs.value() == __rhs.value();
}
+ /** Ordered comparison for std::error_condition.
+ *
+ * This defines a total order by comparing the categories, and then
+ * if they are equal comparing the values.
+ *
+ * @relates error_condition
+ * @since C++11
+ */
#if __cpp_lib_three_way_comparison
- /// Define an ordering for error_condition objects.
- /// @relates error_condition
inline strong_ordering
operator<=>(const error_condition& __lhs,
const error_condition& __rhs) noexcept
@@ -393,8 +472,6 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
return __lhs.value() <=> __rhs.value();
}
#else
- /// Define an ordering for error_condition objects.
- /// @relates error_condition
inline bool
operator<(const error_condition& __lhs,
const error_condition& __rhs) noexcept
@@ -441,6 +518,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* Typically used to report errors from the operating system and other
* low-level APIs.
*
+ * @headerfile system_error
* @since C++11
* @ingroup exceptions
*/
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 06/12] libstdc++: Improve doxygen docs for <atomic>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (3 preceding siblings ...)
2022-05-13 12:40 ` [committed 05/12] libstdc++: Improve doxygen docs for <system_error> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
` (5 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
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
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 07/12] libstdc++: Improve doxygen docs for <regex>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (4 preceding siblings ...)
2022-05-13 12:40 ` [committed 06/12] libstdc++: Improve doxygen docs for <atomic> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
` (4 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
Add @headerfile and @since tags. Improve grouping of non-member
functions via @relates tags.
Mark the std::pair base class of std::sub_match as undocumented, so that
the docs don't show all the related non-member functions are part of the
sub_match API. Use a new macro to re-add the data members for Doxygen
only.
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define macro
_GLIBCXX_DOXYGEN_ONLY to expand its argument.
* include/bits/c++config (_GLIBCXX_DOXYGEN_ONLY): Define.
* include/bits/regex.h: Improve doxygen docs.
* include/bits/regex_constants.h: Likewise.
* include/bits/regex_error.h: Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/bits/c++config | 3 ++
libstdc++-v3/include/bits/regex.h | 60 ++++++++++++++++++---
libstdc++-v3/include/bits/regex_constants.h | 5 +-
libstdc++-v3/include/bits/regex_error.h | 7 ++-
5 files changed, 66 insertions(+), 10 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 2dbed727013..02ce290d3ad 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2404,6 +2404,7 @@ PREDEFINED = __cplusplus=202002L \
_GLIBCXX_HAVE_BUILTIN_IS_AGGREGATE \
_GLIBCXX_HAVE_IS_CONSTANT_EVALUATED \
_GLIBCXX_HAVE_BUILTIN_LAUNDER \
+ "_GLIBCXX_DOXYGEN_ONLY(X)=X " \
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/libstdc++-v3/include/bits/c++config b/libstdc++-v3/include/bits/c++config
index 150b0bc5834..191880fb99d 100644
--- a/libstdc++-v3/include/bits/c++config
+++ b/libstdc++-v3/include/bits/c++config
@@ -823,6 +823,9 @@ namespace std
#undef _GLIBCXX_HAS_BUILTIN
+// Mark code that should be ignored by the compiler, but seen by Doxygen.
+#define _GLIBCXX_DOXYGEN_ONLY(X)
+
// PSTL configuration
#if __cplusplus >= 201703L
diff --git a/libstdc++-v3/include/bits/regex.h b/libstdc++-v3/include/bits/regex.h
index 46c168010bf..24298e35e2c 100644
--- a/libstdc++-v3/include/bits/regex.h
+++ b/libstdc++-v3/include/bits/regex.h
@@ -84,6 +84,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* The class %regex is parameterized around a set of related types and
* functions used to complete the definition of its semantics. This class
* satisfies the requirements of such a traits class.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _Ch_type>
class regex_traits
@@ -388,11 +391,24 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
// [7.8] Class basic_regex
/**
- * Objects of specializations of this class represent regular expressions
- * constructed from sequences of character type @p _Ch_type.
+ * @brief A regular expression
*
- * Storage for the regular expression is allocated and deallocated as
- * necessary by the member functions of this class.
+ * Specializations of this class template represent regular expressions
+ * constructed from sequences of character type `_Ch_type`.
+ * Use the `std::regex` typedef for `std::basic_regex<char>`.
+ *
+ * A character sequence passed to the constructor will be parsed according
+ * to the chosen grammar, and used to create a state machine representing
+ * the regular expression. The regex object can then be passed to algorithms
+ * such as `std::regex_match` to match sequences of characters.
+ *
+ * The `syntax_option_type` flag passed to the constructor selects from
+ * one of the supported regular expression grammars. The default is
+ * `ECMAScript` and the others are `basic`, `extended`, `awk`, `grep`, and
+ * `egrep`, which are variations on POSIX regular expressions.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _Ch_type, typename _Rx_traits = regex_traits<_Ch_type>>
class basic_regex
@@ -885,14 +901,22 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* An object of this class is essentially a pair of iterators marking a
* matched subexpression within a regular expression pattern match. Such
* objects can be converted to and compared with std::basic_string objects
- * of a similar base character type as the pattern matched by the regular
+ * of the same character type as the pattern matched by the regular
* expression.
*
+ * A `sub_match<Iter>` has a public base class of type `pair<Iter, Iter>`,
+ * so inherits pair's data members named `first` and `second`.
* The iterators that make up the pair are the usual half-open interval
* referencing the actual original pattern matched.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _BiIter>
- class sub_match : public std::pair<_BiIter, _BiIter>
+ class sub_match
+ /// @cond undocumented
+ : public std::pair<_BiIter, _BiIter>
+ /// @endcond
{
typedef iterator_traits<_BiIter> __iter_traits;
@@ -902,6 +926,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
typedef _BiIter iterator;
typedef basic_string<value_type> string_type;
+ _GLIBCXX_DOXYGEN_ONLY(iterator first; iterator second;)
+
bool matched;
constexpr sub_match() noexcept : matched() { }
@@ -1699,6 +1725,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* of characters [first, second) which formed that match. Otherwise matched
* is false, and members first and second point to the end of the sequence
* that was searched.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _Bi_iter,
typename _Alloc = allocator<sub_match<_Bi_iter> > >
@@ -2125,6 +2154,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* @brief Compares two match_results for equality.
* @returns true if the two objects refer to the same match,
* false otherwise.
+ *
+ * @relates match_results
*/
template<typename _Bi_iter, typename _Alloc>
inline bool
@@ -2150,6 +2181,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* @brief Compares two match_results for inequality.
* @returns true if the two objects do not refer to the same match,
* false otherwise.
+ *
+ * @relates match_results
*/
template<typename _Bi_iter, class _Alloc>
inline bool
@@ -2165,6 +2198,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* @param __rhs A match result.
*
* The contents of the two match_results objects are swapped.
+ *
+ * @relates match_results
*/
template<typename _Bi_iter, typename _Alloc>
inline void
@@ -2177,8 +2212,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
// [28.11.2] Function template regex_match
/**
* @name Matching, Searching, and Replacing
+ *
+ * @{
*/
- ///@{
/**
* @brief Determines if there is a match between the regular expression @p e
@@ -2486,6 +2522,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
// std [28.11.4] Function template regex_replace
+ /// @cond undocumented
template<typename _Out_iter, typename _Bi_iter,
typename _Rx_traits, typename _Ch_type>
_Out_iter
@@ -2493,6 +2530,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
const basic_regex<_Ch_type, _Rx_traits>& __e,
const _Ch_type* __fmt, size_t __len,
regex_constants::match_flag_type __flags);
+ /// @endcond
/**
* @brief Search for a regular expression within a range for multiple times,
@@ -2654,7 +2692,7 @@ _GLIBCXX_END_NAMESPACE_CXX11
return __result;
}
- ///@}
+ /// @}
_GLIBCXX_BEGIN_NAMESPACE_CXX11
@@ -2662,6 +2700,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
/**
* An iterator adaptor that will provide repeated calls of regex_search over
* a range until no more matches remain.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _Bi_iter,
typename _Ch_type = typename iterator_traits<_Bi_iter>::value_type,
@@ -2779,6 +2820,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
* The purpose of this iterator is to enumerate all, or all specified,
* matches of a regular expression within a text range. The dereferenced
* value of an iterator of this class is a std::sub_match object.
+ *
+ * @headerfile regex
+ * @since C++11
*/
template<typename _Bi_iter,
typename _Ch_type = typename iterator_traits<_Bi_iter>::value_type,
diff --git a/libstdc++-v3/include/bits/regex_constants.h b/libstdc++-v3/include/bits/regex_constants.h
index 35a8956b447..c7e1d857b1f 100644
--- a/libstdc++-v3/include/bits/regex_constants.h
+++ b/libstdc++-v3/include/bits/regex_constants.h
@@ -1,4 +1,4 @@
-// class template regex -*- C++ -*-
+// Namespace std::regex_constants -*- C++ -*-
// Copyright (C) 2010-2022 Free Software Foundation, Inc.
//
@@ -38,6 +38,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @defgroup regex Regular Expressions
*
* A facility for performing regular expression pattern matching.
+ *
+ * @since C++11
+ *
* @{
*/
diff --git a/libstdc++-v3/include/bits/regex_error.h b/libstdc++-v3/include/bits/regex_error.h
index 77d4925921b..74a1428c2c7 100644
--- a/libstdc++-v3/include/bits/regex_error.h
+++ b/libstdc++-v3/include/bits/regex_error.h
@@ -1,4 +1,4 @@
-// class template regex -*- C++ -*-
+// Errors for std::regex -*- C++ -*-
// Copyright (C) 2010-2022 Free Software Foundation, Inc.
//
@@ -130,6 +130,9 @@ namespace regex_constants
* @ingroup exceptions
*
* The regular expression library throws objects of this class on error.
+ *
+ * @headerfile regex
+ * @since C++11
*/
class regex_error : public std::runtime_error
{
@@ -158,6 +161,7 @@ namespace regex_constants
{ return _M_code; }
private:
+ /// @cond undocumented
regex_error(error_type __ecode, const char* __what)
: std::runtime_error(__what), _M_code(__ecode)
{ }
@@ -167,6 +171,7 @@ namespace regex_constants
__throw_regex_error(error_type __ecode __attribute__((__unused__)),
const char* __what __attribute__((__unused__)))
{ _GLIBCXX_THROW_OR_ABORT(regex_error(__ecode, __what)); }
+ /// @endcond
};
/// @cond undocumented
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 08/12] libstdc++: Improve doxygen docs for std::allocator
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (5 preceding siblings ...)
2022-05-13 12:40 ` [committed 07/12] libstdc++: Improve doxygen docs for <regex> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
` (3 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define __allocator_base
so that Doxygen shows the right base-class for std::allocator.
* include/bits/alloc_traits.h: Improve doxygen docs.
* include/bits/allocator.h: Likewise.
* include/bits/new_allocator.h: Likewise.
* include/ext/new_allocator.h: Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/bits/alloc_traits.h | 5 +++++
libstdc++-v3/include/bits/allocator.h | 15 ++++++++++++++-
libstdc++-v3/include/bits/new_allocator.h | 19 +++++++++++++------
libstdc++-v3/include/ext/new_allocator.h | 12 +++++++++---
5 files changed, 42 insertions(+), 10 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 02ce290d3ad..cfda7ab13c4 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2405,6 +2405,7 @@ PREDEFINED = __cplusplus=202002L \
_GLIBCXX_HAVE_IS_CONSTANT_EVALUATED \
_GLIBCXX_HAVE_BUILTIN_LAUNDER \
"_GLIBCXX_DOXYGEN_ONLY(X)=X " \
+ __allocator_base=std::__new_allocator \
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/libstdc++-v3/include/bits/alloc_traits.h b/libstdc++-v3/include/bits/alloc_traits.h
index a4d06d3fc7a..f9ca37fd7d6 100644
--- a/libstdc++-v3/include/bits/alloc_traits.h
+++ b/libstdc++-v3/include/bits/alloc_traits.h
@@ -661,6 +661,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return __rhs; }
};
+ /// @cond undocumented
#if __cplusplus < 201703L
template<typename _Alloc>
inline void
@@ -818,8 +819,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__a.deallocate(__a.allocate(1u), 1u);
};
#endif
+ /// @endcond
#endif // C++11
+ /// @cond undocumented
+
/**
* Destroy a range of objects using the supplied allocator. For
* non-default allocators we do not optimize away invocation of
@@ -849,6 +853,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{
_Destroy(__first, __last);
}
+ /// @endcond
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/allocator.h b/libstdc++-v3/include/bits/allocator.h
index f7770165273..ee1121b080a 100644
--- a/libstdc++-v3/include/bits/allocator.h
+++ b/libstdc++-v3/include/bits/allocator.h
@@ -67,7 +67,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// explicit specialization, with the historical ABI properties, but with
// the same members that are present in the primary template.
- /// allocator<void> specialization.
+ /** std::allocator<void> specialization.
+ *
+ * @headerfile memory
+ */
template<>
class allocator<void>
{
@@ -119,6 +122,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* for further details.
*
* @tparam _Tp Type of allocated object.
+ *
+ * @headerfile memory
*/
template<typename _Tp>
class allocator : public __allocator_base<_Tp>
@@ -209,6 +214,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// Inherit everything else.
};
+ /** Equality comparison for std::allocator objects
+ *
+ * @return true, for all std::allocator objects.
+ * @relates std::allocator
+ */
template<typename _T1, typename _T2>
inline _GLIBCXX20_CONSTEXPR bool
operator==(const allocator<_T1>&, const allocator<_T2>&)
@@ -223,6 +233,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return false; }
#endif
+ /// @cond undocumented
+
// Invalid allocator<cv T> partial specializations.
// allocator_traits::rebind_alloc can be used to form a valid allocator type.
template<typename _Tp>
@@ -325,6 +337,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
};
#endif
+ /// @endcond
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/new_allocator.h b/libstdc++-v3/include/bits/new_allocator.h
index 20ef20fe118..1a5bc51b956 100644
--- a/libstdc++-v3/include/bits/new_allocator.h
+++ b/libstdc++-v3/include/bits/new_allocator.h
@@ -43,14 +43,21 @@ namespace std _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
- * @brief An allocator that uses global new, as per C++03 [20.4.1].
- * @ingroup allocators
+ * @brief An allocator that uses global `new`, as per C++03 [20.4.1].
+ * @ingroup allocators
*
- * This is precisely the allocator defined in the C++ Standard.
- * - all allocation calls operator new
- * - all deallocation calls operator delete
+ * This is precisely the allocator defined in the C++ Standard.
+ * - all allocation calls `operator new`
+ * - all deallocation calls `operator delete`
*
- * @tparam _Tp Type of allocated object.
+ * This is the default base-class implementation of `std::allocator`,
+ * and is also the base-class of the `__gnu_cxx::new_allocator` extension.
+ * You should use either `std::allocator` or `__gnu_cxx::new_allocator`
+ * instead of using this directly.
+ *
+ * @tparam _Tp Type of allocated object.
+ *
+ * @headerfile memory
*/
template<typename _Tp>
class __new_allocator
diff --git a/libstdc++-v3/include/ext/new_allocator.h b/libstdc++-v3/include/ext/new_allocator.h
index b8f5fcccccc..96e6523977a 100644
--- a/libstdc++-v3/include/ext/new_allocator.h
+++ b/libstdc++-v3/include/ext/new_allocator.h
@@ -36,14 +36,20 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default)
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
- * @brief An allocator that uses global new, as per C++03 [20.4.1].
+ * @brief An allocator that uses global `new`, as per C++03 [20.4.1].
* @ingroup allocators
*
* This is precisely the allocator defined in the C++ Standard.
- * - all allocation calls operator new
- * - all deallocation calls operator delete
+ * - all allocation calls `operator new`
+ * - all deallocation calls `operator delete`
+ *
+ * This is a non-standard extension that can be used to guarantee
+ * allocation from `new` even if the library has been configured to
+ * use a different implementation for `std::allocator`.
*
* @tparam _Tp Type of allocated object.
+ *
+ * @headerfile ext/new_allocator.h
*/
template<typename _Tp>
class new_allocator : public std::__new_allocator<_Tp>
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (6 preceding siblings ...)
2022-05-13 12:40 ` [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
` (2 subsequent siblings)
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/ostream_insert.h: Mark helper functions as
undocumented by Doxygen.
* include/bits/stl_algo.h: Use markdown for formatting and mark
helper functions as undocumented.
* include/bits/stl_numeric.h: Likewise.
* include/bits/stl_pair.h (pair): Add @headerfile.
---
libstdc++-v3/include/bits/ostream_insert.h | 4 +
libstdc++-v3/include/bits/stl_algo.h | 198 +++++++++++----------
libstdc++-v3/include/bits/stl_numeric.h | 10 +-
libstdc++-v3/include/bits/stl_pair.h | 4 +
4 files changed, 112 insertions(+), 104 deletions(-)
diff --git a/libstdc++-v3/include/bits/ostream_insert.h b/libstdc++-v3/include/bits/ostream_insert.h
index 9442ea130d3..f236353b2a6 100644
--- a/libstdc++-v3/include/bits/ostream_insert.h
+++ b/libstdc++-v3/include/bits/ostream_insert.h
@@ -40,6 +40,8 @@ namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
+ /// @cond undocumented
+
template<typename _CharT, typename _Traits>
inline void
__ostream_write(basic_ostream<_CharT, _Traits>& __out,
@@ -124,6 +126,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
#endif
+ /// @endcond
+
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace std
diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h
index 6619ff7bf1d..1d8ed4e5fa8 100644
--- a/libstdc++-v3/include/bits/stl_algo.h
+++ b/libstdc++-v3/include/bits/stl_algo.h
@@ -1617,6 +1617,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
__gnu_cxx::__ops::__pred_iter(__pred));
}
+ /// @cond undocumented
+
/// This is a helper function for the sort routines.
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -1671,6 +1673,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
return __result_real_last;
}
+ /// @endcond
+
/**
* @brief Copy the smallest elements of a sequence.
* @ingroup sorting_algorithms
@@ -1680,14 +1684,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* @param __result_last Another random-access iterator.
* @return An iterator indicating the end of the resulting sequence.
*
- * Copies and sorts the smallest N values from the range @p [__first,__last)
- * to the range beginning at @p __result_first, where the number of
- * elements to be copied, @p N, is the smaller of @p (__last-__first) and
- * @p (__result_last-__result_first).
- * After the sort if @e i and @e j are iterators in the range
- * @p [__result_first,__result_first+N) such that i precedes j then
- * *j<*i is false.
- * The value returned is @p __result_first+N.
+ * Copies and sorts the smallest `N` values from the range
+ * `[__first, __last)` to the range beginning at `__result_first`, where
+ * the number of elements to be copied, `N`, is the smaller of
+ * `(__last - __first)` and `(__result_last - __result_first)`.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__result_first,__result_first + N)` such that `i` precedes `j` then
+ * `*j < *i` is false.
+ * The value returned is `__result_first + N`.
*/
template<typename _InputIterator, typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -1730,14 +1734,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
* @param __comp A comparison functor.
* @return An iterator indicating the end of the resulting sequence.
*
- * Copies and sorts the smallest N values from the range @p [__first,__last)
- * to the range beginning at @p result_first, where the number of
- * elements to be copied, @p N, is the smaller of @p (__last-__first) and
- * @p (__result_last-__result_first).
- * After the sort if @e i and @e j are iterators in the range
- * @p [__result_first,__result_first+N) such that i precedes j then
- * @p __comp(*j,*i) is false.
- * The value returned is @p __result_first+N.
+ * Copies and sorts the smallest `N` values from the range
+ * `[__first, __last)` to the range beginning at `result_first`, where
+ * the number of elements to be copied, `N`, is the smaller of
+ * `(__last - __first)` and `(__result_last - __result_first)`.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__result_first, __result_first + N)` such that `i` precedes `j` then
+ * `__comp(*j, *i)` is false.
+ * The value returned is `__result_first + N`.
*/
template<typename _InputIterator, typename _RandomAccessIterator,
typename _Compare>
@@ -1774,6 +1778,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
__gnu_cxx::__ops::__iter_comp_iter(__comp));
}
+ /// @cond undocumented
+
/// This is a helper function for the sort routine.
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -1967,21 +1973,22 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2)
std::__insertion_sort(__first, __last, __comp);
}
+ /// @endcond
+
// nth_element
// lower_bound moved to stl_algobase.h
/**
- * @brief Finds the first position in which @p __val could be inserted
+ * @brief Finds the first position in which `__val` could be inserted
* without changing the ordering.
* @ingroup binary_search_algorithms
- * @param __first An iterator.
- * @param __last Another iterator.
+ * @param __first An iterator to the start of a sorted range.
+ * @param __last A past-the-end iterator for the sorted range.
* @param __val The search term.
* @param __comp A functor to use for comparisons.
- * @return An iterator pointing to the first element <em>not less
- * than</em> @p __val, or end() if every element is less
- * than @p __val.
+ * @return An iterator pointing to the first element _not less than_
+ * `__val`, or `end()` if every element is less than `__val`.
* @ingroup binary_search_algorithms
*
* The comparison function should have the same effects on ordering as
@@ -4313,8 +4320,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __new_value The replacement value.
* @return replace() returns no value.
*
- * For each iterator @c i in the range @p [__first,__last) if @c *i ==
- * @p __old_value then the assignment @c *i = @p __new_value is performed.
+ * For each iterator `i` in the range `[__first,__last)` if
+ * `*i == __old_value` then the assignment `*i = __new_value` is performed.
*/
template<typename _ForwardIterator, typename _Tp>
_GLIBCXX20_CONSTEXPR
@@ -4346,8 +4353,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __new_value The replacement value.
* @return replace_if() returns no value.
*
- * For each iterator @c i in the range @p [__first,__last) if @p __pred(*i)
- * is true then the assignment @c *i = @p __new_value is performed.
+ * For each iterator `i` in the range `[__first,__last)` if `__pred(*i)`
+ * is true then the assignment `*i = __new_value` is performed.
*/
template<typename _ForwardIterator, typename _Predicate, typename _Tp>
_GLIBCXX20_CONSTEXPR
@@ -4375,12 +4382,11 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @ingroup mutating_algorithms
* @param __first A forward iterator.
* @param __last A forward iterator.
- * @param __gen A function object taking no arguments and returning
- * std::iterator_traits<_ForwardIterator>::value_type
+ * @param __gen A function object callable with no arguments.
* @return generate() returns no value.
*
- * Performs the assignment @c *i = @p __gen() for each @c i in the range
- * @p [__first,__last).
+ * Performs the assignment `*i = __gen()` for each `i` in the range
+ * `[__first, __last)`.
*/
template<typename _ForwardIterator, typename _Generator>
_GLIBCXX20_CONSTEXPR
@@ -4404,14 +4410,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @ingroup mutating_algorithms
* @param __first A forward iterator.
* @param __n The length of the sequence.
- * @param __gen A function object taking no arguments and returning
- * std::iterator_traits<_ForwardIterator>::value_type
- * @return The end of the sequence, @p __first+__n
+ * @param __gen A function object callable with no arguments.
+ * @return The end of the sequence, i.e., `__first + __n`
*
- * Performs the assignment @c *i = @p __gen() for each @c i in the range
- * @p [__first,__first+__n).
+ * Performs the assignment `*i = __gen()` for each `i` in the range
+ * `[__first, __first + __n)`.
*
- * If @p __n is negative, the function does nothing and returns @p __first.
+ * If `__n` is negative, the function does nothing and returns `__first`.
*/
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 865. More algorithms that throw away information
@@ -4441,19 +4446,16 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __result An output iterator.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) to the range
- * beginning at @p __result, except that only the first element is copied
+ * Copies each element in the range `[__first, __last)` to the range
+ * beginning at `__result`, except that only the first element is copied
* from groups of consecutive elements that compare equal.
- * unique_copy() is stable, so the relative order of elements that are
+ * `unique_copy()` is stable, so the relative order of elements that are
* copied is unchanged.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 241. Does unique_copy() require CopyConstructible and Assignable?
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 538. 241 again: Does unique_copy() require CopyConstructible and
- * Assignable?
- */
+ */
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 241. Does unique_copy() require CopyConstructible and Assignable?
+ // DR 538. 241 again: Does unique_copy() require CopyConstructible and
+ // Assignable?
template<typename _InputIterator, typename _OutputIterator>
_GLIBCXX20_CONSTEXPR
inline _OutputIterator
@@ -4485,16 +4487,15 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __binary_pred A binary predicate.
* @return An iterator designating the end of the resulting sequence.
*
- * Copies each element in the range @p [__first,__last) to the range
- * beginning at @p __result, except that only the first element is copied
- * from groups of consecutive elements for which @p __binary_pred returns
+ * Copies each element in the range `[__first, __last)` to the range
+ * beginning at `__result`, except that only the first element is copied
+ * from groups of consecutive elements for which `__binary_pred` returns
* true.
- * unique_copy() is stable, so the relative order of elements that are
+ * `unique_copy()` is stable, so the relative order of elements that are
* copied is unchanged.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 241. Does unique_copy() require CopyConstructible and Assignable?
- */
+ */
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 241. Does unique_copy() require CopyConstructible and Assignable?
template<typename _InputIterator, typename _OutputIterator,
typename _BinaryPredicate>
_GLIBCXX20_CONSTEXPR
@@ -4526,7 +4527,7 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last A forward iterator.
* @return Nothing.
*
- * Reorder the elements in the range @p [__first,__last) using a random
+ * Reorder the elements in the range `[__first, __last)` using a random
* distribution, so that every possible ordering of the sequence is
* equally likely.
*
@@ -4565,10 +4566,10 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __rand The RNG functor or function.
* @return Nothing.
*
- * Reorders the elements in the range @p [__first,__last) using @p __rand to
- * provide a random distribution. Calling @p __rand(N) for a positive
- * integer @p N should return a randomly chosen integer from the
- * range [0,N).
+ * Reorders the elements in the range `[__first, __last)` using `__rand`
+ * to provide a random distribution. Calling `__rand(N)` for a positive
+ * integer `N` should return a randomly chosen integer from the
+ * range `[0, N)`.
*
* @deprecated
* Since C++14 `std::random_shuffle` is not part of the C++ standard.
@@ -4607,13 +4608,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __first A forward iterator.
* @param __last A forward iterator.
* @param __pred A predicate functor.
- * @return An iterator @p middle such that @p __pred(i) is true for each
- * iterator @p i in the range @p [__first,middle) and false for each @p i
- * in the range @p [middle,__last).
+ * @return An iterator `middle` such that `__pred(i)` is true for each
+ * iterator `i` in the range `[__first, middle)` and false for each `i`
+ * in the range `[middle, __last)`.
*
- * @p __pred must not modify its operand. @p partition() does not preserve
+ * `__pred` must not modify its operand. `partition()` does not preserve
* the relative ordering of elements in each group, use
- * @p stable_partition() if this is needed.
+ * `stable_partition()` if this is needed.
*/
template<typename _ForwardIterator, typename _Predicate>
_GLIBCXX20_CONSTEXPR
@@ -4641,13 +4642,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Sorts the smallest @p (__middle-__first) elements in the range
- * @p [first,last) and moves them to the range @p [__first,__middle). The
- * order of the remaining elements in the range @p [__middle,__last) is
- * undefined.
- * After the sort if @e i and @e j are iterators in the range
- * @p [__first,__middle) such that i precedes j and @e k is an iterator in
- * the range @p [__middle,__last) then *j<*i and *k<*i are both false.
+ * Sorts the smallest `(__middle - __first)` elements in the range
+ * `[first, last)` and moves them to the range `[__first, __middle)`. The
+ * order of the remaining elements in the range `[__middle, __last)` is
+ * unspecified.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator
+ * in the range `[__middle, __last)` then `*j < *i` and `*k < *i` are
+ * both false.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4679,14 +4681,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the smallest @p (__middle-__first) elements in the range
- * @p [__first,__last) and moves them to the range @p [__first,__middle). The
- * order of the remaining elements in the range @p [__middle,__last) is
- * undefined.
- * After the sort if @e i and @e j are iterators in the range
- * @p [__first,__middle) such that i precedes j and @e k is an iterator in
- * the range @p [__middle,__last) then @p *__comp(j,*i) and @p __comp(*k,*i)
- * are both false.
+ * Sorts the smallest `(__middle - __first)` elements in the range
+ * `[__first, __last)` and moves them to the range `[__first, __middle)`.
+ * The order of the remaining elements in the range `[__middle, __last)` is
+ * unspecified.
+ * After the sort if `i` and `j` are iterators in the range
+ * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator
+ * in the range `[__middle, __last)` then `*__comp(j, *i)` and
+ * `__comp(*k, *i)` are both false.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -4718,12 +4720,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Rearranges the elements in the range @p [__first,__last) so that @p *__nth
+ * Rearranges the elements in the range `[__first, __last)` so that `*__nth`
* is the same element that would have been in that position had the
- * whole sequence been sorted. The elements either side of @p *__nth are
- * not completely sorted, but for any iterator @e i in the range
- * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it
- * holds that *j < *i is false.
+ * whole sequence been sorted. The elements either side of `*__nth` are
+ * not completely sorted, but for any iterator `i` in the range
+ * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)` it
+ * holds that `*j < *i` is false.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4758,12 +4760,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Rearranges the elements in the range @p [__first,__last) so that @p *__nth
+ * Rearranges the elements in the range `[__first, __last)` so that `*__nth`
* is the same element that would have been in that position had the
- * whole sequence been sorted. The elements either side of @p *__nth are
- * not completely sorted, but for any iterator @e i in the range
- * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it
- * holds that @p __comp(*j,*i) is false.
+ * whole sequence been sorted. The elements either side of `*__nth` are
+ * not completely sorted, but for any iterator `i` in the range
+ * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)`
+ * it holds that `__comp(*j, *i)` is false.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
@@ -4796,12 +4798,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last Another iterator.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that for each iterator @e i in the range @p [__first,__last-1),
- * *(i+1)<*i is false.
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that for each iterator `i` in the range `[__first, __last - 1)`,
+ * `*(i+1) < *i` is false.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator>
_GLIBCXX20_CONSTEXPR
@@ -4827,12 +4829,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __comp A comparison functor.
* @return Nothing.
*
- * Sorts the elements in the range @p [__first,__last) in ascending order,
- * such that @p __comp(*(i+1),*i) is false for every iterator @e i in the
- * range @p [__first,__last-1).
+ * Sorts the elements in the range `[__first, __last)` in ascending order,
+ * such that `__comp(*(i+1), *i)` is false for every iterator `i` in the
+ * range `[__first, __last - 1)`.
*
* The relative ordering of equivalent elements is not preserved, use
- * @p stable_sort() if this is needed.
+ * `stable_sort()` if this is needed.
*/
template<typename _RandomAccessIterator, typename _Compare>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/stl_numeric.h b/libstdc++-v3/include/bits/stl_numeric.h
index ea017d41e76..f71236cab5d 100644
--- a/libstdc++-v3/include/bits/stl_numeric.h
+++ b/libstdc++-v3/include/bits/stl_numeric.h
@@ -328,10 +328,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __last End of input range.
* @param __result Output sums.
* @return Iterator pointing just beyond the values written to result.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 539. partial_sum and adjacent_difference should mention requirements
*/
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 539. partial_sum and adjacent_difference should mention requirements
template<typename _InputIterator, typename _OutputIterator>
_GLIBCXX20_CONSTEXPR
_OutputIterator
@@ -371,10 +370,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO
* @param __result Output sum.
* @param __binary_op Function object.
* @return Iterator pointing just beyond the values written to result.
- *
- * _GLIBCXX_RESOLVE_LIB_DEFECTS
- * DR 539. partial_sum and adjacent_difference should mention requirements
*/
+ // _GLIBCXX_RESOLVE_LIB_DEFECTS
+ // DR 539. partial_sum and adjacent_difference should mention requirements
template<typename _InputIterator, typename _OutputIterator,
typename _BinaryOperation>
_GLIBCXX20_CONSTEXPR
diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h
index 0eb78345ca4..831e770d54b 100644
--- a/libstdc++-v3/include/bits/stl_pair.h
+++ b/libstdc++-v3/include/bits/stl_pair.h
@@ -180,6 +180,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @tparam _T2 Type of second object.
*
* <https://gcc.gnu.org/onlinedocs/libstdc++/manual/utilities.html>
+ *
+ * @headerfile utility
*/
template<typename _T1, typename _T2>
struct pair
@@ -757,9 +759,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if __cplusplus >= 201103L
// Various functions which give std::pair a tuple-like interface.
+ /// @cond undocumented
template<typename _T1, typename _T2>
struct __is_tuple_like_impl<pair<_T1, _T2>> : true_type
{ };
+ /// @endcond
/// Partial specialization for std::pair
template<class _Tp1, class _Tp2>
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (7 preceding siblings ...)
2022-05-13 12:40 ` [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Jonathan Wakely
@ 2022-05-13 12:40 ` 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
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* include/bits/std_thread.h (thread, thread::id): Improve
doxygen docs.
* include/std/future: Likewise.
* include/std/thread (jthread): Likewise.
---
libstdc++-v3/include/bits/std_thread.h | 33 ++++++++++++++++++++++----
libstdc++-v3/include/std/future | 29 ++++++++++++++++++----
libstdc++-v3/include/std/thread | 21 +++++++++++++++-
3 files changed, 73 insertions(+), 10 deletions(-)
diff --git a/libstdc++-v3/include/bits/std_thread.h b/libstdc++-v3/include/bits/std_thread.h
index dd625de3bc3..f67bc114591 100644
--- a/libstdc++-v3/include/bits/std_thread.h
+++ b/libstdc++-v3/include/bits/std_thread.h
@@ -57,7 +57,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @{
*/
- /// thread
+ /** A std::thread represents a new thread of execution.
+ *
+ * The default constructor creates an object that does not own a thread.
+ * The `thread(F&&, Args&&...)` constructor invokes a callable in a new
+ * thread, and owns that new thread. A `std::thread` that owns a thread
+ * is *joinable*. Joining a thread waits for it to finish executing,
+ * which happens when the callable running in that thread returns.
+ *
+ * A `std::thread` cannot be copied, but can be moved. Moving a joinable
+ * object transfers ownership of its thread to another object.
+ *
+ * A joinable `std::thread` must be explicitly joined (or detached) before
+ * it is destroyed or assigned to. Attempting to destroy a joinable thread
+ * will terminate the whole process.
+ *
+ * @headerfile thread
+ * @since C++11
+ */
class thread
{
public:
@@ -76,7 +93,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
using native_handle_type = int;
#endif
- /// thread::id
+ /** A std::thread::id is a unique identifier for a thread.
+ *
+ * @headerfile thread
+ * @since C++11
+ */
class id
{
native_handle_type _M_thread;
@@ -261,8 +282,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
public:
+ /// @cond undocumented
template<typename... _Tp>
using _Call_wrapper = _Invoker<tuple<typename decay<_Tp>::type...>>;
+ /// @endcond
#endif // _GLIBCXX_HAS_GTHREADS
};
@@ -272,10 +295,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
inline unsigned int thread::hardware_concurrency() noexcept { return 0; }
#endif
+ /// @relates std::thread
inline void
swap(thread& __x, thread& __y) noexcept
{ __x.swap(__y); }
+ /// @relates std::thread::id
inline bool
operator==(thread::id __x, thread::id __y) noexcept
{
@@ -301,7 +326,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
namespace this_thread
{
- /// this_thread::get_id
+ /// The unique identifier of the current thread.
inline thread::id
get_id() noexcept
{
@@ -314,7 +339,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
}
- /// this_thread::yield
+ /// Allow the implementation to schedule a different thread.
inline void
yield() noexcept
{
diff --git a/libstdc++-v3/include/std/future b/libstdc++-v3/include/std/future
index a9268cade91..3d5d793a08e 100644
--- a/libstdc++-v3/include/std/future
+++ b/libstdc++-v3/include/std/future
@@ -58,7 +58,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @defgroup futures Futures
* @ingroup concurrency
*
- * Classes for futures support.
+ * Futures and promises provide support for retrieving the result from
+ * an asynchronous function, e.g. one that is running in another thread.
+ * A `std::future` represents an asynchronous result that will become
+ * ready at some later time. A consumer can wait on a future until the
+ * result is ready to be accessed.
+ *
+ * @since C++11
* @{
*/
@@ -71,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
broken_promise
};
- /// Specialization.
+ /// Specialization that allows `future_errc` to convert to `error_code`.
template<>
struct is_error_code_enum<future_errc> : public true_type { };
@@ -79,12 +85,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
const error_category&
future_category() noexcept;
- /// Overload for make_error_code.
+ /// Overload of make_error_code for `future_errc`.
inline error_code
make_error_code(future_errc __errc) noexcept
{ return error_code(static_cast<int>(__errc), future_category()); }
- /// Overload for make_error_condition.
+ /// Overload of make_error_condition for `future_errc`.
inline error_condition
make_error_condition(future_errc __errc) noexcept
{ return error_condition(static_cast<int>(__errc), future_category()); }
@@ -92,6 +98,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief Exception type thrown by futures.
* @ingroup exceptions
+ * @since C++11
*/
class future_error : public logic_error
{
@@ -178,11 +185,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
deferred
};
+ /// @cond undocumented
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// 2021. Further incorrect usages of result_of
template<typename _Fn, typename... _Args>
using __async_result_of = typename __invoke_result<
typename decay<_Fn>::type, typename decay<_Args>::type...>::type;
+ /// @endcond
template<typename _Fn, typename... _Args>
future<__async_result_of<_Fn, _Args...>>
@@ -194,6 +203,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#if defined(_GLIBCXX_HAS_GTHREADS)
+ /// @cond undocumented
+
/// Base class and enclosing scope.
struct __future_base
{
@@ -655,8 +666,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
void _M_destroy() { delete this; }
};
+ /// @endcond
+
#ifndef _GLIBCXX_ASYNC_ABI_COMPAT
+ /// @cond undocumented
// Allow _Setter objects to be stored locally in std::function
template<typename _Res, typename _Arg>
struct __is_location_invariant
@@ -668,6 +682,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct __is_location_invariant
<__future_base::_Task_setter<_Res_ptr, _Fn, _Res>>
: true_type { };
+ /// @endcond
/// Common implementation for future and shared_future.
template<typename _Res>
@@ -1376,6 +1391,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
};
+ /// @cond undocumented
template<typename _Ptr_type, typename _Fn, typename _Res>
struct __future_base::_Task_setter
{
@@ -1512,6 +1528,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return __create_task_state<_Res(_Args...)>(std::move(_M_impl._M_fn),
static_cast<_Alloc&>(_M_impl));
}
+ /// @endcond
/// packaged_task
template<typename _Res, typename... _ArgTypes>
@@ -1648,6 +1665,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
: public true_type { };
#endif
+ /// @cond undocumented
+
// Shared state created by std::async().
// Holds a deferred function and storage for its result.
template<typename _BoundFn, typename _Res>
@@ -1761,7 +1780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
_Ptr_type _M_result;
_BoundFn _M_fn;
};
-
+ /// @endcond
/// async
template<typename _Fn, typename... _Args>
diff --git a/libstdc++-v3/include/std/thread b/libstdc++-v3/include/std/thread
index 92b24268ffe..82f191afe2d 100644
--- a/libstdc++-v3/include/std/thread
+++ b/libstdc++-v3/include/std/thread
@@ -50,6 +50,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @defgroup threads Threads
* @ingroup concurrency
+ * @since C++11
*
* Classes for thread support.
* @{
@@ -57,6 +58,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// std::thread is defined in <bits/std_thread.h>
+ /// @relates std::thread::id @{
+
#if __cpp_lib_three_way_comparison
inline strong_ordering
operator<=>(thread::id __x, thread::id __y) noexcept
@@ -96,9 +99,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
else
return __out << __id._M_thread;
}
+ /// @}
#ifdef __cpp_lib_jthread
+ /// @cond undocumented
#ifndef __STRICT_ANSI__
template<typename _Callable, typename... _Args>
constexpr bool __pmf_expects_stop_token = false;
@@ -108,8 +113,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
= __and_<is_member_function_pointer<remove_reference_t<_Callable>>,
is_invocable<_Callable, _Obj, stop_token, _Args...>>::value;
#endif
+ /// @endcond
- /// A thread that can be requested to stop and automatically joined.
+ /** A thread with cancellation and automatic joining.
+ *
+ * Unlike `std::thread`, destroying a joinable `std::jthread` will not
+ * terminate the process. Instead, it will try to request its thread to
+ * stop, then will join it.
+ *
+ * A `std::jthread` has a `std::stop_source` member which will be passed
+ * as the first argument to the callable that runs in the new thread
+ * (as long as the callable will accept that argument). That can then
+ * be used to send a stop request that the new thread can test for.
+ *
+ * @headerfile thread
+ * @since C++20
+ */
class jthread
{
public:
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 11/12] libstdc++: Improve doxygen docs for some of <memory>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (8 preceding siblings ...)
2022-05-13 12:40 ` [committed 10/12] libstdc++: Improve doxygen docs for <thread> and <future> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
2022-05-13 12:40 ` [committed 12/12] libstdc++: Improve doxygen docs for <mutex> Jonathan Wakely
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define
_GLIBCXX23_CONSTEXPR macro.
* include/backward/auto_ptr.h (auto_ptr): Use @deprecated.
* include/bits/unique_ptr.h (default_delete): Use @since and
@headerfile.
* include/std/scoped_allocator: Remove @ingroup from @file
block.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/backward/auto_ptr.h | 4 ++++
libstdc++-v3/include/bits/unique_ptr.h | 13 ++++++++++---
libstdc++-v3/include/std/scoped_allocator | 1 -
4 files changed, 15 insertions(+), 4 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index cfda7ab13c4..4d21968cc57 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2388,6 +2388,7 @@ PREDEFINED = __cplusplus=202002L \
_GLIBCXX14_CONSTEXPR=constexpr \
_GLIBCXX17_CONSTEXPR=constexpr \
_GLIBCXX20_CONSTEXPR=constexpr \
+ _GLIBCXX23_CONSTEXPR=constexpr \
"_GLIBCXX11_DEPRECATED= " \
"_GLIBCXX11_DEPRECATED_SUGGEST(E)= " \
"_GLIBCXX17_DEPRECATED= " \
diff --git a/libstdc++-v3/include/backward/auto_ptr.h b/libstdc++-v3/include/backward/auto_ptr.h
index 8725504d4c9..184ab403466 100644
--- a/libstdc++-v3/include/backward/auto_ptr.h
+++ b/libstdc++-v3/include/backward/auto_ptr.h
@@ -84,6 +84,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* _GLIBCXX_RESOLVE_LIB_DEFECTS
* 127. auto_ptr<> conversion issues
* These resolutions have all been incorporated.
+ *
+ * @headerfile memory
+ * @deprecated Deprecated in C++11, no longer in the standard since C++17.
+ * Use `unique_ptr` instead.
*/
template<typename _Tp>
class auto_ptr
diff --git a/libstdc++-v3/include/bits/unique_ptr.h b/libstdc++-v3/include/bits/unique_ptr.h
index ad60fada59b..e1ad7721a59 100644
--- a/libstdc++-v3/include/bits/unique_ptr.h
+++ b/libstdc++-v3/include/bits/unique_ptr.h
@@ -65,8 +65,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#pragma GCC diagnostic pop
#endif
- /// Primary template of default_delete, used by unique_ptr for single objects
- /// @since C++11
+ /** Primary template of default_delete, used by unique_ptr for single objects
+ *
+ * @headerfile memory
+ * @since C++11
+ */
template<typename _Tp>
struct default_delete
{
@@ -99,7 +102,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
// _GLIBCXX_RESOLVE_LIB_DEFECTS
// DR 740 - omit specialization for array objects with a compile time length
- /// Specialization of default_delete for arrays, used by `unique_ptr<T[]>`
+ /** Specialization of default_delete for arrays, used by `unique_ptr<T[]>`
+ *
+ * @headerfile memory
+ * @since C++11
+ */
template<typename _Tp>
struct default_delete<_Tp[]>
{
diff --git a/libstdc++-v3/include/std/scoped_allocator b/libstdc++-v3/include/std/scoped_allocator
index f2e3ed9f783..c62b04874e2 100644
--- a/libstdc++-v3/include/std/scoped_allocator
+++ b/libstdc++-v3/include/std/scoped_allocator
@@ -24,7 +24,6 @@
/** @file include/scoped_allocator
* This is a Standard C++ Library header.
- * @ingroup allocators
*/
#ifndef _SCOPED_ALLOCATOR
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread* [committed 12/12] libstdc++: Improve doxygen docs for <mutex>
2022-05-13 12:40 [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Jonathan Wakely
` (9 preceding siblings ...)
2022-05-13 12:40 ` [committed 11/12] libstdc++: Improve doxygen docs for some of <memory> Jonathan Wakely
@ 2022-05-13 12:40 ` Jonathan Wakely
10 siblings, 0 replies; 18+ messages in thread
From: Jonathan Wakely @ 2022-05-13 12:40 UTC (permalink / raw)
To: libstdc++, gcc-patches
Tested powerpc64le-linux, pushed to trunk.
-- >8 --
libstdc++-v3/ChangeLog:
* doc/doxygen/user.cfg.in (PREDEFINED): Define
_GTHREAD_USE_MUTEX_TIMEDLOCK macro.
* include/bits/std_mutex.h (mutex, lock_guard): Use @since and
@headerfile.
* include/bits/unique_lock.h (unique_lock): Likewise.
* include/std/mutex (recursive_mutex, timed_mutex)
(recursive_timed_mutex, scoped_lock): Likewise.
---
libstdc++-v3/doc/doxygen/user.cfg.in | 1 +
libstdc++-v3/include/bits/std_mutex.h | 21 +++++++++++++-
libstdc++-v3/include/bits/unique_lock.h | 2 ++
libstdc++-v3/include/std/mutex | 38 +++++++++++++++++++++++--
4 files changed, 58 insertions(+), 4 deletions(-)
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 4d21968cc57..c034b864928 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2325,6 +2325,7 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = __cplusplus=202002L \
__GTHREADS \
_GLIBCXX_HAS_GTHREADS \
+ _GTHREAD_USE_MUTEX_TIMEDLOCK \
_GLIBCXX_HAVE_TLS \
_GLIBCXX_INCLUDE_AS_CXX11 \
"_GLIBCXX_PURE= " \
diff --git a/libstdc++-v3/include/bits/std_mutex.h b/libstdc++-v3/include/bits/std_mutex.h
index d3a1d5eaec9..b22e0e12793 100644
--- a/libstdc++-v3/include/bits/std_mutex.h
+++ b/libstdc++-v3/include/bits/std_mutex.h
@@ -53,6 +53,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
#ifdef _GLIBCXX_HAS_GTHREADS
+ /// @cond undocumented
+
// Common base class for std::mutex and std::timed_mutex
class __mutex_base
{
@@ -78,8 +80,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__mutex_base(const __mutex_base&) = delete;
__mutex_base& operator=(const __mutex_base&) = delete;
};
+ /// @endcond
- /// The standard mutex type.
+ /** The standard mutex type.
+ *
+ * A simple, non-recursive, non-timed mutex.
+ *
+ * Do not call `lock()` and `unlock()` directly, use a scoped lock type
+ * such as `std::unique_lock`, `std::lock_guard`, or (since C++17)
+ * `std::scoped_lock`.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class mutex : private __mutex_base
{
public:
@@ -123,6 +136,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return &_M_mutex; }
};
+ /// @cond undocumented
+
// Implementation details for std::condition_variable
class __condvar
{
@@ -192,6 +207,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
__gthread_cond_t _M_cond;
#endif
};
+ /// @endcond
#endif // _GLIBCXX_HAS_GTHREADS
@@ -218,6 +234,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* A lock_guard controls mutex ownership within a scope, releasing
* ownership in the destructor.
+ *
+ * @headerfile mutex
+ * @since C++11
*/
template<typename _Mutex>
class lock_guard
diff --git a/libstdc++-v3/include/bits/unique_lock.h b/libstdc++-v3/include/bits/unique_lock.h
index 1f1aa15c463..9ed7ba25766 100644
--- a/libstdc++-v3/include/bits/unique_lock.h
+++ b/libstdc++-v3/include/bits/unique_lock.h
@@ -51,7 +51,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* to another unique_lock by move construction or move assignment. If a
* mutex lock is owned when the destructor runs ownership will be released.
*
+ * @headerfile mutex
* @ingroup mutexes
+ * @since C++11
*/
template<typename _Mutex>
class unique_lock
diff --git a/libstdc++-v3/include/std/mutex b/libstdc++-v3/include/std/mutex
index f500818d9c9..b9590bbf276 100644
--- a/libstdc++-v3/include/std/mutex
+++ b/libstdc++-v3/include/std/mutex
@@ -62,6 +62,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
#ifdef _GLIBCXX_HAS_GTHREADS
+ /// @cond undocumented
// Common base class for std::recursive_mutex and std::recursive_timed_mutex
class __recursive_mutex_base
@@ -89,8 +90,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ __gthread_recursive_mutex_destroy(&_M_mutex); }
#endif
};
+ /// @endcond
- /// The standard recursive mutex type.
+ /** The standard recursive mutex type.
+ *
+ * A recursive mutex can be locked more than once by the same thread.
+ * Other threads cannot lock the mutex until the owning thread unlocks it
+ * as many times as it was locked.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class recursive_mutex : private __recursive_mutex_base
{
public:
@@ -132,6 +142,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
};
#if _GTHREAD_USE_MUTEX_TIMEDLOCK
+ /// @cond undocumented
+
template<typename _Derived>
class __timed_mutex_impl
{
@@ -207,8 +219,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return false;
}
};
+ /// @endcond
- /// The standard timed mutex type.
+ /** The standard timed mutex type.
+ *
+ * A non-recursive mutex that supports a timeout when trying to acquire the
+ * lock.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class timed_mutex
: private __mutex_base, public __timed_mutex_impl<timed_mutex>
{
@@ -273,7 +293,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
- /// recursive_timed_mutex
+ /** The standard recursive timed mutex type.
+ *
+ * A recursive mutex that supports a timeout when trying to acquire the
+ * lock. A recursive mutex can be locked more than once by the same thread.
+ * Other threads cannot lock the mutex until the owning thread unlocks it
+ * as many times as it was locked.
+ *
+ * @headerfile mutex
+ * @since C++11
+ */
class recursive_timed_mutex
: private __recursive_mutex_base,
public __timed_mutex_impl<recursive_timed_mutex>
@@ -687,6 +716,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*
* A scoped_lock controls mutex ownership within a scope, releasing
* ownership in the destructor.
+ *
+ * @headerfile mutex
+ * @since C++17
*/
template<typename... _MutexTypes>
class scoped_lock
--
2.34.1
^ permalink raw reply [flat|nested] 18+ messages in thread