libstdc++-v3/include/std/thread

   1 // <thread> -*- C++ -*-
   2
   3 // Copyright (C) 2008-2024 Free Software Foundation, Inc.
   4 //
   5 // This file is part of the GNU ISO C++ Library.  This library is free
   6 // software; you can redistribute it and/or modify it under the
   7 // terms of the GNU General Public License as published by the
   8 // Free Software Foundation; either version 3, or (at your option)
   9 // any later version.
  10
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // Under Section 7 of GPL version 3, you are granted additional
  17 // permissions described in the GCC Runtime Library Exception, version
  18 // 3.1, as published by the Free Software Foundation.
  19
  20 // You should have received a copy of the GNU General Public License and
  21 // a copy of the GCC Runtime Library Exception along with this program;
  22 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  23 // <http://www.gnu.org/licenses/>.
  24
  25 /** @file include/thread
  26  *  This is a Standard C++ Library header.
  27  */
  28
  29 #ifndef _GLIBCXX_THREAD
  30 #define _GLIBCXX_THREAD 1
  31
  32 #pragma GCC system_header
  33
  34 #include <bits/requires_hosted.h> // concurrency
  35
  36 #if __cplusplus < 201103L
  37 # include <bits/c++0x_warning.h>
  38 #else
  39
  40 #if __cplusplus > 201703L
  41 # include <compare>     // std::strong_ordering
  42 # include <stop_token>  // std::stop_source, std::stop_token, std::nostopstate
  43 #endif
  44
  45 #if __cplusplus > 202002L
  46 # include <format>
  47 #endif
  48
  49 #include <bits/std_thread.h> // std::thread, get_id, yield
  50 #include <bits/this_thread_sleep.h> // std::this_thread::sleep_for, sleep_until
  51
  52 #define __glibcxx_want_jthread
  53 #define __glibcxx_want_formatters
  54 #include <bits/version.h>
  55
  56 namespace std _GLIBCXX_VISIBILITY(default)
  57 {
  58 _GLIBCXX_BEGIN_NAMESPACE_VERSION
  59
  60   /**
  61    * @defgroup threads Threads
  62    * @ingroup concurrency
  63    * @since C++11
  64    *
  65    * Classes for thread support.
  66    * @{
  67    */
  68
  69   // std::thread is defined in <bits/std_thread.h>
  70
  71   /// @relates std::thread::id @{
  72
  73 #if __cpp_lib_three_way_comparison
  74   inline strong_ordering
  75   operator<=>(thread::id __x, thread::id __y) noexcept
  76   { return __x._M_thread <=> __y._M_thread; }
  77 #else
  78   inline bool
  79   operator!=(thread::id __x, thread::id __y) noexcept
  80   { return !(__x == __y); }
  81
  82   inline bool
  83   operator<(thread::id __x, thread::id __y) noexcept
  84   {
  85     // Pthreads doesn't define any way to do this, so we just have to
  86     // assume native_handle_type is LessThanComparable.
  87     return __x._M_thread < __y._M_thread;
  88   }
  89
  90   inline bool
  91   operator<=(thread::id __x, thread::id __y) noexcept
  92   { return !(__y < __x); }
  93
  94   inline bool
  95   operator>(thread::id __x, thread::id __y) noexcept
  96   { return __y < __x; }
  97
  98   inline bool
  99   operator>=(thread::id __x, thread::id __y) noexcept
 100   { return !(__x < __y); }
 101 #endif // __cpp_lib_three_way_comparison
 102
 103   template<class _CharT, class _Traits>
 104     inline basic_ostream<_CharT, _Traits>&
 105     operator<<(basic_ostream<_CharT, _Traits>& __out, thread::id __id)
 106     {
 107       if (__id == thread::id())
 108         return __out << "thread::id of a non-executing thread";
 109       else
 110         return __out << __id._M_thread;
 111     }
 112   /// @}
 113
 114 #ifdef __cpp_lib_jthread // C++ >= 20
 115
 116   /// @cond undocumented
 117 #ifndef __STRICT_ANSI__
 118     template<typename _Callable, typename... _Args>
 119       constexpr bool __pmf_expects_stop_token = false;
 120
 121     template<typename _Callable, typename _Obj, typename... _Args>
 122       constexpr bool __pmf_expects_stop_token<_Callable, _Obj, _Args...>
 123         = __and_<is_member_function_pointer<remove_reference_t<_Callable>>,
 124                  is_invocable<_Callable, _Obj, stop_token, _Args...>>::value;
 125 #endif
 126     /// @endcond
 127
 128   /** A thread with cancellation and automatic joining.
 129    *
 130    * Unlike `std::thread`, destroying a joinable `std::jthread` will not
 131    * terminate the process. Instead, it will try to request its thread to
 132    * stop, then will join it.
 133    *
 134    * A `std::jthread` has a `std::stop_source` member which will be passed
 135    * as the first argument to the callable that runs in the new thread
 136    * (as long as the callable will accept that argument). That can then
 137    * be used to send a stop request that the new thread can test for.
 138    *
 139    * @headerfile thread
 140    * @since C++20
 141    */
 142   class jthread
 143   {
 144   public:
 145     using id = thread::id;
 146     using native_handle_type = thread::native_handle_type;
 147
 148     jthread() noexcept
 149     : _M_stop_source{nostopstate}
 150     { }
 151
 152     template<typename _Callable, typename... _Args,
 153              typename = enable_if_t<!is_same_v<remove_cvref_t<_Callable>,
 154                                                jthread>>>
 155       explicit
 156       jthread(_Callable&& __f, _Args&&... __args)
 157       : _M_thread{_S_create(_M_stop_source, std::forward<_Callable>(__f),
 158                             std::forward<_Args>(__args)...)}
 159       { }
 160
 161     jthread(const jthread&) = delete;
 162     jthread(jthread&&) noexcept = default;
 163
 164     ~jthread()
 165     {
 166       if (joinable())
 167         {
 168           request_stop();
 169           join();
 170         }
 171     }
 172
 173     jthread&
 174     operator=(const jthread&) = delete;
 175
 176     jthread&
 177     operator=(jthread&& __other) noexcept
 178     {
 179       std::jthread(std::move(__other)).swap(*this);
 180       return *this;
 181     }
 182
 183     void
 184     swap(jthread& __other) noexcept
 185     {
 186       std::swap(_M_stop_source, __other._M_stop_source);
 187       std::swap(_M_thread, __other._M_thread);
 188     }
 189
 190     [[nodiscard]] bool
 191     joinable() const noexcept
 192     {
 193       return _M_thread.joinable();
 194     }
 195
 196     void
 197     join()
 198     {
 199       _M_thread.join();
 200     }
 201
 202     void
 203     detach()
 204     {
 205       _M_thread.detach();
 206     }
 207
 208     [[nodiscard]] id
 209     get_id() const noexcept
 210     {
 211       return _M_thread.get_id();
 212     }
 213
 214     [[nodiscard]] native_handle_type
 215     native_handle()
 216     {
 217       return _M_thread.native_handle();
 218     }
 219
 220     [[nodiscard]] static unsigned
 221     hardware_concurrency() noexcept
 222     {
 223       return thread::hardware_concurrency();
 224     }
 225
 226     [[nodiscard]] stop_source
 227     get_stop_source() noexcept
 228     {
 229       return _M_stop_source;
 230     }
 231
 232     [[nodiscard]] stop_token
 233     get_stop_token() const noexcept
 234     {
 235       return _M_stop_source.get_token();
 236     }
 237
 238     bool request_stop() noexcept
 239     {
 240       return _M_stop_source.request_stop();
 241     }
 242
 243     friend void swap(jthread& __lhs, jthread& __rhs) noexcept
 244     {
 245       __lhs.swap(__rhs);
 246     }
 247
 248   private:
 249     template<typename _Callable, typename... _Args>
 250       static thread
 251       _S_create(stop_source& __ssrc, _Callable&& __f, _Args&&... __args)
 252       {
 253 #ifndef __STRICT_ANSI__
 254         if constexpr (__pmf_expects_stop_token<_Callable, _Args...>)
 255           return _S_create_pmf(__ssrc, __f, std::forward<_Args>(__args)...);
 256         else
 257 #endif
 258         if constexpr(is_invocable_v<decay_t<_Callable>, stop_token,
 259                                     decay_t<_Args>...>)
 260           return thread{std::forward<_Callable>(__f), __ssrc.get_token(),
 261                         std::forward<_Args>(__args)...};
 262         else
 263           {
 264             static_assert(is_invocable_v<decay_t<_Callable>,
 265                                          decay_t<_Args>...>,
 266                           "std::jthread arguments must be invocable after"
 267                           " conversion to rvalues");
 268             return thread{std::forward<_Callable>(__f),
 269                           std::forward<_Args>(__args)...};
 270           }
 271       }
 272
 273 #ifndef __STRICT_ANSI__
 274     template<typename _Callable, typename _Obj, typename... _Args>
 275       static thread
 276       _S_create_pmf(stop_source& __ssrc, _Callable __f, _Obj&& __obj,
 277                     _Args&&... __args)
 278       {
 279         return thread{__f, std::forward<_Obj>(__obj), __ssrc.get_token(),
 280                       std::forward<_Args>(__args)...};
 281       }
 282 #endif
 283
 284     stop_source _M_stop_source;
 285     thread _M_thread;
 286   };
 287 #endif // __cpp_lib_jthread
 288
 289 #ifdef __cpp_lib_formatters // C++ >= 23
 290
 291   template<typename _CharT>
 292     class formatter<thread::id, _CharT>
 293     {
 294     public:
 295       constexpr typename basic_format_parse_context<_CharT>::iterator
 296       parse(basic_format_parse_context<_CharT>& __pc)
 297       {
 298         __format::_Spec<_CharT> __spec{};
 299         const auto __last = __pc.end();
 300         auto __first = __pc.begin();
 301
 302         auto __finalize = [this, &__spec] {
 303           _M_spec = __spec;
 304         };
 305
 306         auto __finished = [&] {
 307           if (__first == __last || *__first == '}')
 308             {
 309               __finalize();
 310               return true;
 311             }
 312           return false;
 313         };
 314
 315         if (__finished())
 316           return __first;
 317
 318         __first = __spec._M_parse_fill_and_align(__first, __last);
 319         if (__finished())
 320           return __first;
 321
 322         __first = __spec._M_parse_width(__first, __last, __pc);
 323         if (__finished())
 324           return __first;
 325
 326         __throw_format_error("format error: invalid format-spec for "
 327                              "std::thread::id");
 328       }
 329
 330       template<typename _Out>
 331         typename basic_format_context<_Out, _CharT>::iterator
 332         format(thread::id __id, basic_format_context<_Out, _CharT>& __fc) const
 333         {
 334           std::basic_ostringstream<_CharT> __os;
 335           __os << __id;
 336           auto __str = __os.view();
 337           return __format::__write_padded_as_spec(__str, __str.size(),
 338                                                   __fc, _M_spec,
 339                                                   __format::_Align_right);
 340         }
 341
 342     private:
 343       __format::_Spec<_CharT> _M_spec;
 344     };
 345 #endif // __cpp_lib_formatters
 346
 347   /// @} group threads
 348
 349 _GLIBCXX_END_NAMESPACE_VERSION
 350 } // namespace
 351 #endif // C++11
 352 #endif // _GLIBCXX_THREAD