From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id E2AE0395A052; Fri, 13 May 2022 12:35:23 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E2AE0395A052 MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r13-431] libstdc++: Improve doxygen docs for and X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: e61492549b95dff635395f69034b5fefa00e339a X-Git-Newrev: c29c2a0604719684ca3d65c7c10912c11afb8357 Message-Id: <20220513123523.E2AE0395A052@sourceware.org> Date: Fri, 13 May 2022 12:35:23 +0000 (GMT) X-BeenThere: libstdc++-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 13 May 2022 12:35:24 -0000 https://gcc.gnu.org/g:c29c2a0604719684ca3d65c7c10912c11afb8357 commit r13-431-gc29c2a0604719684ca3d65c7c10912c11afb8357 Author: Jonathan Wakely Date: Thu May 12 22:26:34 2022 +0100 libstdc++: Improve doxygen docs for and libstdc++-v3/ChangeLog: * include/bits/std_thread.h (thread, thread::id): Improve doxygen docs. * include/std/future: Likewise. * include/std/thread (jthread): Likewise. Diff: --- 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: