summaryrefslogtreecommitdiffstats
path: root/libstdc++-v3
diff options
context:
space:
mode:
authorJonathan Wakely <jwakely@redhat.com>2022-05-12 22:26:34 +0100
committerJonathan Wakely <jwakely@redhat.com>2022-05-13 13:32:23 +0100
commitc29c2a0604719684ca3d65c7c10912c11afb8357 (patch)
treeb294a8398339c8db302f487b53078876d712fb40 /libstdc++-v3
parentlibstdc++: Improve doxygen docs for algorithms and more (diff)
downloadgcc-c29c2a0604719684ca3d65c7c10912c11afb8357.tar.gz
gcc-c29c2a0604719684ca3d65c7c10912c11afb8357.tar.bz2
gcc-c29c2a0604719684ca3d65c7c10912c11afb8357.tar.xz
libstdc++: Improve doxygen docs for <thread> and <future>
libstdc++-v3/ChangeLog: * include/bits/std_thread.h (thread, thread::id): Improve doxygen docs. * include/std/future: Likewise. * include/std/thread (jthread): Likewise.
Diffstat (limited to 'libstdc++-v3')
-rw-r--r--libstdc++-v3/include/bits/std_thread.h33
-rw-r--r--libstdc++-v3/include/std/future29
-rw-r--r--libstdc++-v3/include/std/thread21
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
57 * @{ 57 * @{
58 */ 58 */
59 59
60 /// thread 60 /** A std::thread represents a new thread of execution.
61 *
62 * The default constructor creates an object that does not own a thread.
63 * The `thread(F&&, Args&&...)` constructor invokes a callable in a new
64 * thread, and owns that new thread. A `std::thread` that owns a thread
65 * is *joinable*. Joining a thread waits for it to finish executing,
66 * which happens when the callable running in that thread returns.
67 *
68 * A `std::thread` cannot be copied, but can be moved. Moving a joinable
69 * object transfers ownership of its thread to another object.
70 *
71 * A joinable `std::thread` must be explicitly joined (or detached) before
72 * it is destroyed or assigned to. Attempting to destroy a joinable thread
73 * will terminate the whole process.
74 *
75 * @headerfile thread
76 * @since C++11
77 */
61 class thread 78 class thread
62 { 79 {
63 public: 80 public:
@@ -76,7 +93,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
76 using native_handle_type = int; 93 using native_handle_type = int;
77#endif 94#endif
78 95
79 /// thread::id 96 /** A std::thread::id is a unique identifier for a thread.
97 *
98 * @headerfile thread
99 * @since C++11
100 */
80 class id 101 class id
81 { 102 {
82 native_handle_type _M_thread; 103 native_handle_type _M_thread;
@@ -261,8 +282,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
261 }; 282 };
262 283
263 public: 284 public:
285 /// @cond undocumented
264 template<typename... _Tp> 286 template<typename... _Tp>
265 using _Call_wrapper = _Invoker<tuple<typename decay<_Tp>::type...>>; 287 using _Call_wrapper = _Invoker<tuple<typename decay<_Tp>::type...>>;
288 /// @endcond
266#endif // _GLIBCXX_HAS_GTHREADS 289#endif // _GLIBCXX_HAS_GTHREADS
267 }; 290 };
268 291
@@ -272,10 +295,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
272 inline unsigned int thread::hardware_concurrency() noexcept { return 0; } 295 inline unsigned int thread::hardware_concurrency() noexcept { return 0; }
273#endif 296#endif
274 297
298 /// @relates std::thread
275 inline void 299 inline void
276 swap(thread& __x, thread& __y) noexcept 300 swap(thread& __x, thread& __y) noexcept
277 { __x.swap(__y); } 301 { __x.swap(__y); }
278 302
303 /// @relates std::thread::id
279 inline bool 304 inline bool
280 operator==(thread::id __x, thread::id __y) noexcept 305 operator==(thread::id __x, thread::id __y) noexcept
281 { 306 {
@@ -301,7 +326,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
301 326
302 namespace this_thread 327 namespace this_thread
303 { 328 {
304 /// this_thread::get_id 329 /// The unique identifier of the current thread.
305 inline thread::id 330 inline thread::id
306 get_id() noexcept 331 get_id() noexcept
307 { 332 {
@@ -314,7 +339,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
314#endif 339#endif
315 } 340 }
316 341
317 /// this_thread::yield 342 /// Allow the implementation to schedule a different thread.
318 inline void 343 inline void
319 yield() noexcept 344 yield() noexcept
320 { 345 {
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
58 * @defgroup futures Futures 58 * @defgroup futures Futures
59 * @ingroup concurrency 59 * @ingroup concurrency
60 * 60 *
61 * Classes for futures support. 61 * Futures and promises provide support for retrieving the result from
62 * an asynchronous function, e.g. one that is running in another thread.
63 * A `std::future` represents an asynchronous result that will become
64 * ready at some later time. A consumer can wait on a future until the
65 * result is ready to be accessed.
66 *
67 * @since C++11
62 * @{ 68 * @{
63 */ 69 */
64 70
@@ -71,7 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
71 broken_promise 77 broken_promise
72 }; 78 };
73 79
74 /// Specialization. 80 /// Specialization that allows `future_errc` to convert to `error_code`.
75 template<> 81 template<>
76 struct is_error_code_enum<future_errc> : public true_type { }; 82 struct is_error_code_enum<future_errc> : public true_type { };
77 83
@@ -79,12 +85,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
79 const error_category& 85 const error_category&
80 future_category() noexcept; 86 future_category() noexcept;
81 87
82 /// Overload for make_error_code. 88 /// Overload of make_error_code for `future_errc`.
83 inline error_code 89 inline error_code
84 make_error_code(future_errc __errc) noexcept 90 make_error_code(future_errc __errc) noexcept
85 { return error_code(static_cast<int>(__errc), future_category()); } 91 { return error_code(static_cast<int>(__errc), future_category()); }
86 92
87 /// Overload for make_error_condition. 93 /// Overload of make_error_condition for `future_errc`.
88 inline error_condition 94 inline error_condition
89 make_error_condition(future_errc __errc) noexcept 95 make_error_condition(future_errc __errc) noexcept
90 { return error_condition(static_cast<int>(__errc), future_category()); } 96 { return error_condition(static_cast<int>(__errc), future_category()); }
@@ -92,6 +98,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
92 /** 98 /**
93 * @brief Exception type thrown by futures. 99 * @brief Exception type thrown by futures.
94 * @ingroup exceptions 100 * @ingroup exceptions
101 * @since C++11
95 */ 102 */
96 class future_error : public logic_error 103 class future_error : public logic_error
97 { 104 {
@@ -178,11 +185,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
178 deferred 185 deferred
179 }; 186 };
180 187
188 /// @cond undocumented
181 // _GLIBCXX_RESOLVE_LIB_DEFECTS 189 // _GLIBCXX_RESOLVE_LIB_DEFECTS
182 // 2021. Further incorrect usages of result_of 190 // 2021. Further incorrect usages of result_of
183 template<typename _Fn, typename... _Args> 191 template<typename _Fn, typename... _Args>
184 using __async_result_of = typename __invoke_result< 192 using __async_result_of = typename __invoke_result<
185 typename decay<_Fn>::type, typename decay<_Args>::type...>::type; 193 typename decay<_Fn>::type, typename decay<_Args>::type...>::type;
194 /// @endcond
186 195
187 template<typename _Fn, typename... _Args> 196 template<typename _Fn, typename... _Args>
188 future<__async_result_of<_Fn, _Args...>> 197 future<__async_result_of<_Fn, _Args...>>
@@ -194,6 +203,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
194 203
195#if defined(_GLIBCXX_HAS_GTHREADS) 204#if defined(_GLIBCXX_HAS_GTHREADS)
196 205
206 /// @cond undocumented
207
197 /// Base class and enclosing scope. 208 /// Base class and enclosing scope.
198 struct __future_base 209 struct __future_base
199 { 210 {
@@ -655,8 +666,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
655 void _M_destroy() { delete this; } 666 void _M_destroy() { delete this; }
656 }; 667 };
657 668
669 /// @endcond
670
658#ifndef _GLIBCXX_ASYNC_ABI_COMPAT 671#ifndef _GLIBCXX_ASYNC_ABI_COMPAT
659 672
673 /// @cond undocumented
660 // Allow _Setter objects to be stored locally in std::function 674 // Allow _Setter objects to be stored locally in std::function
661 template<typename _Res, typename _Arg> 675 template<typename _Res, typename _Arg>
662 struct __is_location_invariant 676 struct __is_location_invariant
@@ -668,6 +682,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
668 struct __is_location_invariant 682 struct __is_location_invariant
669 <__future_base::_Task_setter<_Res_ptr, _Fn, _Res>> 683 <__future_base::_Task_setter<_Res_ptr, _Fn, _Res>>
670 : true_type { }; 684 : true_type { };
685 /// @endcond
671 686
672 /// Common implementation for future and shared_future. 687 /// Common implementation for future and shared_future.
673 template<typename _Res> 688 template<typename _Res>
@@ -1376,6 +1391,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
1376 } 1391 }
1377 }; 1392 };
1378 1393
1394 /// @cond undocumented
1379 template<typename _Ptr_type, typename _Fn, typename _Res> 1395 template<typename _Ptr_type, typename _Fn, typename _Res>
1380 struct __future_base::_Task_setter 1396 struct __future_base::_Task_setter
1381 { 1397 {
@@ -1512,6 +1528,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
1512 return __create_task_state<_Res(_Args...)>(std::move(_M_impl._M_fn), 1528 return __create_task_state<_Res(_Args...)>(std::move(_M_impl._M_fn),
1513 static_cast<_Alloc&>(_M_impl)); 1529 static_cast<_Alloc&>(_M_impl));
1514 } 1530 }
1531 /// @endcond
1515 1532
1516 /// packaged_task 1533 /// packaged_task
1517 template<typename _Res, typename... _ArgTypes> 1534 template<typename _Res, typename... _ArgTypes>
@@ -1648,6 +1665,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
1648 : public true_type { }; 1665 : public true_type { };
1649#endif 1666#endif
1650 1667
1668 /// @cond undocumented
1669
1651 // Shared state created by std::async(). 1670 // Shared state created by std::async().
1652 // Holds a deferred function and storage for its result. 1671 // Holds a deferred function and storage for its result.
1653 template<typename _BoundFn, typename _Res> 1672 template<typename _BoundFn, typename _Res>
@@ -1761,7 +1780,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
1761 _Ptr_type _M_result; 1780 _Ptr_type _M_result;
1762 _BoundFn _M_fn; 1781 _BoundFn _M_fn;
1763 }; 1782 };
1764 1783 /// @endcond
1765 1784
1766 /// async 1785 /// async
1767 template<typename _Fn, typename... _Args> 1786 template<typename _Fn, typename... _Args>
diff --git a/libstdc++-v3/include/std/thread b/libstdc++-v3/include/std/thread
index 92b24268ffe..82f191afe2d 100644
--- a/libstdc++-v3/include/std/thread
+++ b/libstdc++-v3/include/std/thread
@@ -50,6 +50,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
50 /** 50 /**
51 * @defgroup threads Threads 51 * @defgroup threads Threads
52 * @ingroup concurrency 52 * @ingroup concurrency
53 * @since C++11
53 * 54 *
54 * Classes for thread support. 55 * Classes for thread support.
55 * @{ 56 * @{
@@ -57,6 +58,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
57 58
58 // std::thread is defined in <bits/std_thread.h> 59 // std::thread is defined in <bits/std_thread.h>
59 60
61 /// @relates std::thread::id @{
62
60#if __cpp_lib_three_way_comparison 63#if __cpp_lib_three_way_comparison
61 inline strong_ordering 64 inline strong_ordering
62 operator<=>(thread::id __x, thread::id __y) noexcept 65 operator<=>(thread::id __x, thread::id __y) noexcept
@@ -96,9 +99,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
96 else 99 else
97 return __out << __id._M_thread; 100 return __out << __id._M_thread;
98 } 101 }
102 /// @}
99 103
100#ifdef __cpp_lib_jthread 104#ifdef __cpp_lib_jthread
101 105
106 /// @cond undocumented
102#ifndef __STRICT_ANSI__ 107#ifndef __STRICT_ANSI__
103 template<typename _Callable, typename... _Args> 108 template<typename _Callable, typename... _Args>
104 constexpr bool __pmf_expects_stop_token = false; 109 constexpr bool __pmf_expects_stop_token = false;
@@ -108,8 +113,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
108 = __and_<is_member_function_pointer<remove_reference_t<_Callable>>, 113 = __and_<is_member_function_pointer<remove_reference_t<_Callable>>,
109 is_invocable<_Callable, _Obj, stop_token, _Args...>>::value; 114 is_invocable<_Callable, _Obj, stop_token, _Args...>>::value;
110#endif 115#endif
116 /// @endcond
111 117
112 /// A thread that can be requested to stop and automatically joined. 118 /** A thread with cancellation and automatic joining.
119 *
120 * Unlike `std::thread`, destroying a joinable `std::jthread` will not
121 * terminate the process. Instead, it will try to request its thread to
122 * stop, then will join it.
123 *
124 * A `std::jthread` has a `std::stop_source` member which will be passed
125 * as the first argument to the callable that runs in the new thread
126 * (as long as the callable will accept that argument). That can then
127 * be used to send a stop request that the new thread can test for.
128 *
129 * @headerfile thread
130 * @since C++20
131 */
113 class jthread 132 class jthread
114 { 133 {
115 public: 134 public: