From patchwork Fri May 13 12:40:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53928 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6CB76395B427 for ; Fri, 13 May 2022 12:43:27 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6CB76395B427 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652445807; bh=rxCCX24t4fYfprT3jKxzupOzWy7AfZ7JNYapC4nNZIA=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=K659baKdNiVVv/G48g6plOgfHhMKXkyTL3B3mzCMOp6q+giiybrr7eUkFe8+DuXOL ZSPqYpNsshTeozEyzIoTxQ1CNZVGGk95xKNLx8GX/Cg56uAtiyDUnziJMDptPK2vaz ZwYtrOJ2zlnmTGOtYndT/dajFnVEdRTWpcXLOcoY= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 71EFA395B07D for ; Fri, 13 May 2022 12:40:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 71EFA395B07D Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-390-klBLfVq3P7qm-janS3Qnww-1; Fri, 13 May 2022 08:40:51 -0400 X-MC-Unique: klBLfVq3P7qm-janS3Qnww-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 90FF9294EDE5; Fri, 13 May 2022 12:40:51 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 56BBF2166B4E; Fri, 13 May 2022 12:40:51 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 01/12] libstdc++: Disable Doxygen GROUP_NESTED_COMPOUNDS config option Date: Fri, 13 May 2022 13:40:39 +0100 Message-Id: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.9 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" Tested powerpc64le-linux, pushed to trunk. -- >8 -- Before Doxygen version 1.9.2 this option is broken (see https://github.com/doxygen/doxygen/issues/8638 for more details) and classes are not added to the correct groups by @ingroup and @addtogroup. Also remove the obsolete CLASS_DIAGRAMS option that causes a warning. libstdc++-v3/ChangeLog: * doc/doxygen/user.cfg.in (GROUP_NESTED_COMPOUNDS): Set to NO. (CLASS_DIAGRAMS): Remove obsolete option. --- libstdc++-v3/doc/doxygen/user.cfg.in | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index 85955f88390..b9babc3993e 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -388,7 +388,7 @@ DISTRIBUTE_GROUP_DOC = YES # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. -GROUP_NESTED_COMPOUNDS = YES +GROUP_NESTED_COMPOUNDS = NO # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that @@ -2472,15 +2472,6 @@ EXTERNAL_PAGES = YES # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. From patchwork Fri May 13 12:40:40 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53931 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D43963839C40 for ; Fri, 13 May 2022 12:48:26 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D43963839C40 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446106; bh=pLxfe63UIQKplty+o/VLrWMv3hVCT1O0MJb/I2Zd+C0=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=C2kdz3vthYlibQ8NWShLYWRS064KQwUjcgefKn5dXR3Ol429PM+piTRI9CC/AzgpM 4hUgdqeMJ3Xi013B4GjZ8e6TZrDB9jFQ0Anucy7AoCbqHDia8zdmQZusADUyj0eUam cgJmPgIc3zQwo0RiUZYx0wlcRw/OrzdDjB/CYun8= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 6EDDE395B40A for ; Fri, 13 May 2022 12:40:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 6EDDE395B40A Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-450-vGkv_9QYMnuCza7EmgyLAg-1; Fri, 13 May 2022 08:40:52 -0400 X-MC-Unique: vGkv_9QYMnuCza7EmgyLAg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6CCEA1C05AFB; Fri, 13 May 2022 12:40:52 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 365B1C15D4F; Fri, 13 May 2022 12:40:52 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 02/12] libstdc++: Fix typo in doxygen @headerfile command Date: Fri, 13 May 2022 13:40:40 +0100 Message-Id: <20220513124050.4028450-2-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 From patchwork Fri May 13 12:40:41 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53929 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0F579395B41C for ; Fri, 13 May 2022 12:45:29 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0F579395B41C DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652445929; bh=yzpEMI7CUaLtJSKQntPbIRDkUmtLXE/Lz8HFQDn7jv8=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=AyI0xRA+oa3oofCnvINiEAT626qRe3kQogyZ+bitevvXToRkFc0KyEOrfiigjH0fA /GwTDd3eCtr/sFEjRMlB3QfalJoXh6bTdDge/Xe3NJ3C2oCboBLjNAjcrMH2Y2F5bg Bop6cTVTlpejTmZxqcAYVbFfz70NPYrArlBAnCqE= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id D7D71395B40E for ; Fri, 13 May 2022 12:40:54 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D7D71395B40E Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-558-LtePX16vOTS_VW4EYgMdxg-1; Fri, 13 May 2022 08:40:53 -0400 X-MC-Unique: LtePX16vOTS_VW4EYgMdxg-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4C34A1C05AF4; Fri, 13 May 2022 12:40:53 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 124742166B4E; Fri, 13 May 2022 12:40:52 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 03/12] libstdc++: Add macros for the inline namespace std::_V2 Date: Fri, 13 May 2022 13:40:41 +0100 Message-Id: <20220513124050.4028450-3-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.7 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_NUMSUBJECT, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 - _GLIBCXX20_CONSTEXPR - _FIter - rotate(_FIter, _FIter, _FIter); - } +_GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2) + + template + _GLIBCXX20_CONSTEXPR + _FIter + rotate(_FIter, _FIter, _FIter); + +_GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) template _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 @@ -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 * @{ From patchwork Fri May 13 12:40:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53930 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 352CD395B828 for ; Fri, 13 May 2022 12:47:30 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 352CD395B828 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446050; bh=rwNr42QZinIM/BBuz+Jj074HiKbFEiIOTHr4EWlns9A=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=iVqiH5kvvGXXPVH2PntbDvsYgSlH4ErOLzI5jaPUDqaSxRO0BFG0T5Vi5M48hw1na yv7wDuLI27fRoX88yewOZSVfQ06owDryqNmkMbUkYBSveDWtpMLv4K9LDJH9Mmmx1a o5mYzbofCJWpQDLhkulYqWwQBaky8gwK12zGTnGM= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 98594395B419 for ; Fri, 13 May 2022 12:40:57 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 98594395B419 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-562-SbzN3u9sObKrycoZSzbHNA-1; Fri, 13 May 2022 08:40:54 -0400 X-MC-Unique: SbzN3u9sObKrycoZSzbHNA-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 2B4EE294EDE5; Fri, 13 May 2022 12:40:54 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id E69B54085314; Fri, 13 May 2022 12:40:53 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 04/12] libstdc++: Improve doxygen docs for std::pointer_traits Date: Fri, 13 May 2022 13:40:42 +0100 Message-Id: <20220513124050.4028450-4-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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` 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

::pointer_to. template::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 */ From patchwork Fri May 13 12:40:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53934 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 7F27C395BC12 for ; Fri, 13 May 2022 12:51:57 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7F27C395BC12 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446317; bh=F++HGcVSW4I+gJh5z7bF9DYihCjujI+2hFPJXg/5xak=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=Kp7HAfMHawXaiDMXFC4nnJZB4ydW/aDR5vDTL9r/fcj+I6/okoocBd56wgnu6Sd7J nhrbsay8NUHTTya2VKTwzmW8qCrQB5Oiyyg+Egbn5rQYei6TXM+WmecH4rDTZ4ImC8 R+IpKtR1D+nrtczyXKM2WCAhQh1Of09dsC7e+9fg= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id D80CF395B416 for ; Fri, 13 May 2022 12:40:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D80CF395B416 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-578-woJLAXYxM-SlX8Gbtlsccg-1; Fri, 13 May 2022 08:40:55 -0400 X-MC-Unique: woJLAXYxM-SlX8Gbtlsccg-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 1C42985A5BE; Fri, 13 May 2022 12:40:55 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id BDA261121330; Fri, 13 May 2022 12:40:54 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 05/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:43 +0100 Message-Id: <20220513124050.4028450-5-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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()(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(__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 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(__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 */ From patchwork Fri May 13 12:40:44 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53936 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6B43B395BC51 for ; Fri, 13 May 2022 12:55:02 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6B43B395BC51 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446502; bh=aw3iUmblrmEOs/y7NcDVJvlWQvZ1BzVf/dO2kGlmjfI=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=kjG4zzLyU4CdaO/pFXjGXg8NPbJKvJmGdIHZ23uZYfLdwUt9teLaTqI+kqSWDsSlc wLCSQlbYxng19JUQQrDabFxVcewEKto7hECF0MCI02B6L8oLfBEpAEJ5qlsC9Ls3Ct NMuA4XKNxn4SEt3oo0Qw6c/HgogKz79XNTwYZ94A= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 14FAC395A00D for ; Fri, 13 May 2022 12:41:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 14FAC395A00D Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-255-STvvTCpUPMOTvDqOv-ybuQ-1; Fri, 13 May 2022 08:40:56 -0400 X-MC-Unique: STvvTCpUPMOTvDqOv-ybuQ-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EA5EE18A6585; Fri, 13 May 2022 12:40:55 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id AF7381121330; Fri, 13 May 2022 12:40:55 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 06/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:44 +0100 Message-Id: <20220513124050.4028450-6-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 + 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 - 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 @@ -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. 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 @@ -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 @@ -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 @@ -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 @@ -327,11 +327,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } /// @} + /// @} group pointer_abstractions + #if __cplusplus >= 202002L # define __cpp_lib_atomic_shared_ptr 201711L template class atomic; + /** + * @addtogroup pointer_abstractions + * @relates shared_ptr + * @{ + */ + template static constexpr bool __is_shared_ptr = false; template @@ -788,10 +796,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION private: _Sp_atomic> _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 using __atomic_val_t = typename atomic<_Tp>::value_type; template using __atomic_diff_t = typename atomic<_Tp>::difference_type; + /// @endcond // [atomics.nonmembers] Non-member functions. // Function templates generally applicable to atomic types. From patchwork Fri May 13 12:40:45 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53932 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id BEDA0395BC29 for ; Fri, 13 May 2022 12:49:55 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BEDA0395BC29 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446195; bh=pSCmjYvTMEeHzFhBC5i0ZDGeECfZFFzk1MOqenvOm+s=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=jDFwsMPq3khCBiXmLzvt4/y08rrYi9CH4NNS2vsdnvJu1fBNUFz+ZecdYa7Dr8R2m u4hnXND/3cySJzbTr8hhPZNml8UQw+WObFjqx27ueVzAEJPY8NYvWcHYvZl9CH0gp6 Lvy0hQpD5Q43U/SZsRjVyqU4L/l6vpWTLTvT/Gsk= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id C0EAC395B41E for ; Fri, 13 May 2022 12:40:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org C0EAC395B41E Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-365-gdWd4dU1NFaRSSneBUyqcg-1; Fri, 13 May 2022 08:40:57 -0400 X-MC-Unique: gdWd4dU1NFaRSSneBUyqcg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id EAE5E382ECD8; Fri, 13 May 2022 12:40:56 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id B024940CF8FA; Fri, 13 May 2022 12:40:56 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 07/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:45 +0100 Message-Id: <20220513124050.4028450-7-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 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`. + * + * 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> 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` has a public base class of type `pair`, + * 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 - 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 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 > > @@ -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 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 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 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 _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::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::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 From patchwork Fri May 13 12:40:46 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53933 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6BB05395B429 for ; Fri, 13 May 2022 12:51:00 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 6BB05395B429 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446260; bh=UOFhqPV0w7Zb0Un3rItlt1awVzpci0PJqBIngkAFPvk=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=i3jQB47fU6F+quLIOfZlJSkcFPaKtcsMpeR3uyS3cQ0hWb9vaYekEmFsakc1snuG/ uYE5yblMreOOTXNKPvB61WchZbDuCPNiQrnVckmwZXnIqOk0LEo/Spr8SLiotsVXtG iQ1VZZWz35X+ZVXfxSnmPFcINeeoJ7Sb5yogFecQ= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 7807D395B423 for ; Fri, 13 May 2022 12:40:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 7807D395B423 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-442-MXP_FyMsNlilsDBg8oVI9A-1; Fri, 13 May 2022 08:40:58 -0400 X-MC-Unique: MXP_FyMsNlilsDBg8oVI9A-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id C1B7E1C05AF5; Fri, 13 May 2022 12:40:57 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 88A5E2026D6A; Fri, 13 May 2022 12:40:57 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Date: Fri, 13 May 2022 13:40:46 +0100 Message-Id: <20220513124050.4028450-8-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 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 specialization. + /** std::allocator specialization. + * + * @headerfile memory + */ template<> class allocator { @@ -119,6 +122,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * for further details. * * @tparam _Tp Type of allocated object. + * + * @headerfile memory */ template 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 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 partial specializations. // allocator_traits::rebind_alloc can be used to form a valid allocator type. template @@ -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 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 class new_allocator : public std::__new_allocator<_Tp> From patchwork Fri May 13 12:40:47 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53938 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id AF5C1395C006 for ; Fri, 13 May 2022 12:58:47 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org AF5C1395C006 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446727; bh=95nkM62cXd/P4LLJRlNNXzJyZGEX/PZukwhLiEqEqnk=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=iEQdqBcSMCBwTiZFbMTa0+aNMDtrVABw/YO0xNzIZ40o30qApWqfabUlr2zc35xQ3 zd3Qskn5+fZ8EJrTZEpRc09usFUChqJpcOrCUWHeFh3Pf7puN/jt7CmDaIaKUzUB+e kWnuxVd6/UK9ANJ3TRbnPgAp/bbwor0MDXLKLtwQ= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id DD1BB395B41B for ; Fri, 13 May 2022 12:41:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org DD1BB395B41B Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-498-tmpRwK9wOM-OmSOaf8cdgw-1; Fri, 13 May 2022 08:40:59 -0400 X-MC-Unique: tmpRwK9wOM-OmSOaf8cdgw-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id BC9BE85A5A8; Fri, 13 May 2022 12:40:58 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 63DC014E0B40; Fri, 13 May 2022 12:40:58 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Date: Fri, 13 May 2022 13:40:47 +0100 Message-Id: <20220513124050.4028450-9-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 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 _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 _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 @@ -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 _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 not less - * than @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 _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 _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 _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 _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 _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 _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 _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 _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 _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 _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 _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 _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 _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 _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. * * + * + * @headerfile utility */ template 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 struct __is_tuple_like_impl> : true_type { }; + /// @endcond /// Partial specialization for std::pair template From patchwork Fri May 13 12:40:48 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53935 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 75CC3395B40B for ; Fri, 13 May 2022 12:54:05 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 75CC3395B40B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446445; bh=6Sdm1+NhKBbqoxyvlJA+GR8iAi76C0vCBP8qKDv2e8Y=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=LZnQUDwLGlVgg129ubTcmXg0x1WlEYPriHI+PHR2GtVwKjYbWR7LRxkj8Je0ZvGAB 1dYTFe7O9p3rFhuW5ggrZ/syE7VY91MtXW5hZLlfXwHeQS5tnjSt4cN3jltYs1ZDja ZkxFcb1CDLUUmtxMjn8sTLpUHK6oUMS4ATclkHNo= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 71482395B42E for ; Fri, 13 May 2022 12:41:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 71482395B42E Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-331-bYKtesN2P9u3i3F9dxV31A-1; Fri, 13 May 2022 08:40:59 -0400 X-MC-Unique: bYKtesN2P9u3i3F9dxV31A-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9E13F80A0AD; Fri, 13 May 2022 12:40:59 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 65D1CC28106; Fri, 13 May 2022 12:40:59 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 10/12] libstdc++: Improve doxygen docs for and Date: Fri, 13 May 2022 13:40:48 +0100 Message-Id: <20220513124050.4028450-10-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 using _Call_wrapper = _Invoker::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 : 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(__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(__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 using __async_result_of = typename __invoke_result< typename decay<_Fn>::type, typename decay<_Args>::type...>::type; + /// @endcond template 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 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 @@ -1376,6 +1391,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; + /// @cond undocumented template 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 @@ -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 @@ -1761,7 +1780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION _Ptr_type _M_result; _BoundFn _M_fn; }; - + /// @endcond /// async template 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 + /// @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 constexpr bool __pmf_expects_stop_token = false; @@ -108,8 +113,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION = __and_>, 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: From patchwork Fri May 13 12:40:49 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53937 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 9219B395BC63 for ; Fri, 13 May 2022 12:55:59 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9219B395BC63 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446559; bh=+pvjoETK/hfcdfdkwuIK6p5MMGiuzv+SSJEjebkQFJU=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=BIMj/pzdL/v7qoBsRBWa5QctAWMv1KLT0awqlJ+RnViUF2P7FqIwn+Vo3bi3NvnWo kB7X+kBZEa7Ap+YoVgCgFckIKgbRx1mO1xe3//bsLgH8ZpsApwGto+euzjQ0CkQLgN nVZC72g19R9EUePAjl3v1OBu8k2vSOikIKuK0P/s= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 29A10395B41F for ; Fri, 13 May 2022 12:41:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 29A10395B41F Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-148-1D_j0oq4NemNfzd8-uq_Cg-1; Fri, 13 May 2022 08:41:00 -0400 X-MC-Unique: 1D_j0oq4NemNfzd8-uq_Cg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 78E0A100FB88; Fri, 13 May 2022 12:41:00 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 42195400E884; Fri, 13 May 2022 12:41:00 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 11/12] libstdc++: Improve doxygen docs for some of Date: Fri, 13 May 2022 13:40:49 +0100 Message-Id: <20220513124050.4028450-11-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 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 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` + /** Specialization of default_delete for arrays, used by `unique_ptr` + * + * @headerfile memory + * @since C++11 + */ template 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 From patchwork Fri May 13 12:40:50 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53939 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E253F395BC78 for ; Fri, 13 May 2022 13:00:31 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E253F395BC78 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446831; bh=nwphmdkWZEh5u9ux2HwI4l1028U9GYqVpBnwnHzImls=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=F9dMnNqOv+4BFuClb8qEKkj8dZxaebjVY3pkPsJoP6dgfGt35cdiTnI27pVfoptJR wnYpPHlbuAHc0oVYFOyQ+eOZUwHvK9AdlYMuJDFk0vB2po0QHpvl4AjHYzSy8cQ70n RuzPnsf7HlwQcc6eEN5V0/Fcfure5NFjgvyGr72E= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 99BDF395B43B for ; Fri, 13 May 2022 12:41:08 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 99BDF395B43B Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-103-JBZL_QbPPI-lsufV6zGNuQ-1; Fri, 13 May 2022 08:41:01 -0400 X-MC-Unique: JBZL_QbPPI-lsufV6zGNuQ-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 57B671C05AF4; Fri, 13 May 2022 12:41:01 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1DC6C2026D6A; Fri, 13 May 2022 12:41:01 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 12/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:50 +0100 Message-Id: <20220513124050.4028450-12-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.0 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "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 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 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 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 { @@ -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 @@ -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 class scoped_lock