From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 51DD9395B42E for ; Fri, 13 May 2022 12:41:03 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 51DD9395B42E 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) From: Jonathan Wakely 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 Content-Type: text/plain Content-Transfer-Encoding: 8bit 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: libstdc++@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++ mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 13 May 2022 12:41:05 -0000 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: -- 2.34.1