libstdc++
stop_token
Go to the documentation of this file.
1 // <stop_token> -*- C++ -*-
2 
3 // Copyright (C) 2019-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/stop_token
26  * This is a Standard C++ Library header.
27  */
28 
29 #ifndef _GLIBCXX_STOP_TOKEN
30 #define _GLIBCXX_STOP_TOKEN
31 
32 #include <bits/requires_hosted.h> // concurrency
33 
34 #define __glibcxx_want_jthread
35 #include <bits/version.h>
36 
37 #if __cplusplus > 201703L
38 
39 #include <atomic>
40 #include <bits/std_thread.h>
41 
42 #include <semaphore>
43 
44 namespace std _GLIBCXX_VISIBILITY(default)
45 {
46 _GLIBCXX_BEGIN_NAMESPACE_VERSION
47 
48  /// Tag type indicating a stop_source should have no shared-stop-state.
49  struct nostopstate_t { explicit nostopstate_t() = default; };
50  inline constexpr nostopstate_t nostopstate{};
51 
52  class stop_source;
53 
54  /// Allow testing whether a stop request has been made on a `stop_source`.
55  class stop_token
56  {
57  public:
58  stop_token() noexcept = default;
59 
60  stop_token(const stop_token&) noexcept = default;
61  stop_token(stop_token&&) noexcept = default;
62 
63  ~stop_token() = default;
64 
65  stop_token&
66  operator=(const stop_token&) noexcept = default;
67 
68  stop_token&
69  operator=(stop_token&&) noexcept = default;
70 
71  [[nodiscard]]
72  bool
73  stop_possible() const noexcept
74  {
75  return static_cast<bool>(_M_state) && _M_state->_M_stop_possible();
76  }
77 
78  [[nodiscard]]
79  bool
80  stop_requested() const noexcept
81  {
82  return static_cast<bool>(_M_state) && _M_state->_M_stop_requested();
83  }
84 
85  void
86  swap(stop_token& __rhs) noexcept
87  { _M_state.swap(__rhs._M_state); }
88 
89  [[nodiscard]]
90  friend bool
91  operator==(const stop_token& __a, const stop_token& __b)
92  { return __a._M_state == __b._M_state; }
93 
94  friend void
95  swap(stop_token& __lhs, stop_token& __rhs) noexcept
96  { __lhs.swap(__rhs); }
97 
98  private:
99  friend class stop_source;
100  template<typename _Callback>
101  friend class stop_callback;
102 
103  static void
104  _S_yield() noexcept
105  {
106 #if defined __i386__ || defined __x86_64__
107  __builtin_ia32_pause();
108 #endif
109  this_thread::yield();
110  }
111 
112 #ifndef __glibcxx_semaphore
113  struct binary_semaphore
114  {
115  explicit binary_semaphore(int __d) : _M_counter(__d > 0) { }
116 
117  void release() { _M_counter.fetch_add(1, memory_order::release); }
118 
119  void acquire()
120  {
121  int __old = 1;
122  while (!_M_counter.compare_exchange_weak(__old, 0,
123  memory_order::acquire,
124  memory_order::relaxed))
125  {
126  __old = 1;
127  _S_yield();
128  }
129  }
130 
131  atomic<int> _M_counter;
132  };
133 #endif
134 
135  struct _Stop_cb
136  {
137  using __cb_type = void(_Stop_cb*) noexcept;
138  __cb_type* _M_callback;
139  _Stop_cb* _M_prev = nullptr;
140  _Stop_cb* _M_next = nullptr;
141  bool* _M_destroyed = nullptr;
142  binary_semaphore _M_done{0};
143 
144  [[__gnu__::__nonnull__]]
145  explicit
146  _Stop_cb(__cb_type* __cb)
147  : _M_callback(__cb)
148  { }
149 
150  void _M_run() noexcept { _M_callback(this); }
151  };
152 
153  struct _Stop_state_t
154  {
155  using value_type = uint32_t;
156  static constexpr value_type _S_stop_requested_bit = 1;
157  static constexpr value_type _S_locked_bit = 2;
158  static constexpr value_type _S_ssrc_counter_inc = 4;
159 
160  std::atomic<value_type> _M_owners{1};
161  std::atomic<value_type> _M_value{_S_ssrc_counter_inc};
162  _Stop_cb* _M_head = nullptr;
163  std::thread::id _M_requester;
164 
165  _Stop_state_t() = default;
166 
167  bool
168  _M_stop_possible() noexcept
169  {
170  // true if a stop request has already been made or there are still
171  // stop_source objects that would allow one to be made.
172  return _M_value.load(memory_order::acquire) & ~_S_locked_bit;
173  }
174 
175  bool
176  _M_stop_requested() noexcept
177  {
178  return _M_value.load(memory_order::acquire) & _S_stop_requested_bit;
179  }
180 
181  void
182  _M_add_owner() noexcept
183  {
184  _M_owners.fetch_add(1, memory_order::relaxed);
185  }
186 
187  void
188  _M_release_ownership() noexcept
189  {
190  if (_M_owners.fetch_sub(1, memory_order::acq_rel) == 1)
191  delete this;
192  }
193 
194  void
195  _M_add_ssrc() noexcept
196  {
197  _M_value.fetch_add(_S_ssrc_counter_inc, memory_order::relaxed);
198  }
199 
200  void
201  _M_sub_ssrc() noexcept
202  {
203  _M_value.fetch_sub(_S_ssrc_counter_inc, memory_order::release);
204  }
205 
206  // Obtain lock.
207  void
208  _M_lock() noexcept
209  {
210  // Can use relaxed loads to get the current value.
211  // The successful call to _M_try_lock is an acquire operation.
212  auto __old = _M_value.load(memory_order::relaxed);
213  while (!_M_try_lock(__old, memory_order::relaxed))
214  { }
215  }
216 
217  // Precondition: calling thread holds the lock.
218  void
219  _M_unlock() noexcept
220  {
221  _M_value.fetch_sub(_S_locked_bit, memory_order::release);
222  }
223 
224  bool
225  _M_request_stop() noexcept
226  {
227  // obtain lock and set stop_requested bit
228  auto __old = _M_value.load(memory_order::acquire);
229  do
230  {
231  if (__old & _S_stop_requested_bit) // stop request already made
232  return false;
233  }
234  while (!_M_try_lock_and_stop(__old));
235 
236  _M_requester = this_thread::get_id();
237 
238  while (_M_head)
239  {
240  bool __last_cb;
241  _Stop_cb* __cb = _M_head;
242  _M_head = _M_head->_M_next;
243  if (_M_head)
244  {
245  _M_head->_M_prev = nullptr;
246  __last_cb = false;
247  }
248  else
249  __last_cb = true;
250 
251  // Allow other callbacks to be unregistered while __cb runs.
252  _M_unlock();
253 
254  bool __destroyed = false;
255  __cb->_M_destroyed = &__destroyed;
256 
257  // run callback
258  __cb->_M_run();
259 
260  if (!__destroyed)
261  {
262  __cb->_M_destroyed = nullptr;
263 
264  // synchronize with destructor of stop_callback that owns *__cb
265  if (!__gnu_cxx::__is_single_threaded())
266  __cb->_M_done.release();
267  }
268 
269  // Avoid relocking if we already know there are no more callbacks.
270  if (__last_cb)
271  return true;
272 
273  _M_lock();
274  }
275 
276  _M_unlock();
277  return true;
278  }
279 
280  [[__gnu__::__nonnull__]]
281  bool
282  _M_register_callback(_Stop_cb* __cb) noexcept
283  {
284  auto __old = _M_value.load(memory_order::acquire);
285  do
286  {
287  if (__old & _S_stop_requested_bit) // stop request already made
288  {
289  __cb->_M_run(); // run synchronously
290  return false;
291  }
292 
293  if (__old < _S_ssrc_counter_inc) // no stop_source owns *this
294  // No need to register callback if no stop request can be made.
295  // Returning false also means the stop_callback does not share
296  // ownership of this state, but that's not observable.
297  return false;
298  }
299  while (!_M_try_lock(__old));
300 
301  __cb->_M_next = _M_head;
302  if (_M_head)
303  {
304  _M_head->_M_prev = __cb;
305  }
306  _M_head = __cb;
307  _M_unlock();
308  return true;
309  }
310 
311  // Called by ~stop_callback just before destroying *__cb.
312  [[__gnu__::__nonnull__]]
313  void
314  _M_remove_callback(_Stop_cb* __cb)
315  {
316  _M_lock();
317 
318  if (__cb == _M_head)
319  {
320  _M_head = _M_head->_M_next;
321  if (_M_head)
322  _M_head->_M_prev = nullptr;
323  _M_unlock();
324  return;
325  }
326  else if (__cb->_M_prev)
327  {
328  __cb->_M_prev->_M_next = __cb->_M_next;
329  if (__cb->_M_next)
330  __cb->_M_next->_M_prev = __cb->_M_prev;
331  _M_unlock();
332  return;
333  }
334 
335  _M_unlock();
336 
337  // Callback is not in the list, so must have been removed by a call to
338  // _M_request_stop.
339 
340  // Despite appearances there is no data race on _M_requester. The only
341  // write to it happens before the callback is removed from the list,
342  // and removing it from the list happens before this read.
343  if (!(_M_requester == this_thread::get_id()))
344  {
345  // Synchronize with completion of callback.
346  __cb->_M_done.acquire();
347  // Safe for ~stop_callback to destroy *__cb now.
348  return;
349  }
350 
351  if (__cb->_M_destroyed)
352  *__cb->_M_destroyed = true;
353  }
354 
355  // Try to obtain the lock.
356  // Returns true if the lock is acquired (with memory order acquire).
357  // Otherwise, sets __curval = _M_value.load(__failure) and returns false.
358  // Might fail spuriously, so must be called in a loop.
359  bool
360  _M_try_lock(value_type& __curval,
361  memory_order __failure = memory_order::acquire) noexcept
362  {
363  return _M_do_try_lock(__curval, 0, memory_order::acquire, __failure);
364  }
365 
366  // Try to obtain the lock to make a stop request.
367  // Returns true if the lock is acquired and the _S_stop_requested_bit is
368  // set (with memory order acq_rel so that other threads see the request).
369  // Otherwise, sets __curval = _M_value.load(memory_order::acquire) and
370  // returns false.
371  // Might fail spuriously, so must be called in a loop.
372  bool
373  _M_try_lock_and_stop(value_type& __curval) noexcept
374  {
375  return _M_do_try_lock(__curval, _S_stop_requested_bit,
376  memory_order::acq_rel, memory_order::acquire);
377  }
378 
379  bool
380  _M_do_try_lock(value_type& __curval, value_type __newbits,
381  memory_order __success, memory_order __failure) noexcept
382  {
383  if (__curval & _S_locked_bit)
384  {
385  _S_yield();
386  __curval = _M_value.load(__failure);
387  return false;
388  }
389  __newbits |= _S_locked_bit;
390  return _M_value.compare_exchange_weak(__curval, __curval | __newbits,
391  __success, __failure);
392  }
393  };
394 
395  struct _Stop_state_ref
396  {
397  _Stop_state_ref() = default;
398 
399  [[__gnu__::__access__(__none__, 2)]]
400  explicit
401  _Stop_state_ref(const stop_source&)
402  : _M_ptr(new _Stop_state_t())
403  { }
404 
405  _Stop_state_ref(const _Stop_state_ref& __other) noexcept
406  : _M_ptr(__other._M_ptr)
407  {
408  if (_M_ptr)
409  _M_ptr->_M_add_owner();
410  }
411 
412  _Stop_state_ref(_Stop_state_ref&& __other) noexcept
413  : _M_ptr(__other._M_ptr)
414  {
415  __other._M_ptr = nullptr;
416  }
417 
418  _Stop_state_ref&
419  operator=(const _Stop_state_ref& __other) noexcept
420  {
421  if (auto __ptr = __other._M_ptr; __ptr != _M_ptr)
422  {
423  if (__ptr)
424  __ptr->_M_add_owner();
425  if (_M_ptr)
426  _M_ptr->_M_release_ownership();
427  _M_ptr = __ptr;
428  }
429  return *this;
430  }
431 
432  _Stop_state_ref&
433  operator=(_Stop_state_ref&& __other) noexcept
434  {
435  _Stop_state_ref(std::move(__other)).swap(*this);
436  return *this;
437  }
438 
439  ~_Stop_state_ref()
440  {
441  if (_M_ptr)
442  _M_ptr->_M_release_ownership();
443  }
444 
445  void
446  swap(_Stop_state_ref& __other) noexcept
447  { std::swap(_M_ptr, __other._M_ptr); }
448 
449  explicit operator bool() const noexcept { return _M_ptr != nullptr; }
450 
451  _Stop_state_t* operator->() const noexcept { return _M_ptr; }
452 
453 #if __cpp_impl_three_way_comparison >= 201907L
454  friend bool
455  operator==(const _Stop_state_ref&, const _Stop_state_ref&) = default;
456 #else
457  friend bool
458  operator==(const _Stop_state_ref& __lhs, const _Stop_state_ref& __rhs)
459  noexcept
460  { return __lhs._M_ptr == __rhs._M_ptr; }
461 
462  friend bool
463  operator!=(const _Stop_state_ref& __lhs, const _Stop_state_ref& __rhs)
464  noexcept
465  { return __lhs._M_ptr != __rhs._M_ptr; }
466 #endif
467 
468  private:
469  _Stop_state_t* _M_ptr = nullptr;
470  };
471 
472  _Stop_state_ref _M_state;
473 
474  explicit
475  stop_token(const _Stop_state_ref& __state) noexcept
476  : _M_state{__state}
477  { }
478  };
479 
480  /// A type that allows a stop request to be made.
481  class stop_source
482  {
483  public:
484  stop_source() : _M_state(*this)
485  { }
486 
487  explicit stop_source(std::nostopstate_t) noexcept
488  { }
489 
490  stop_source(const stop_source& __other) noexcept
491  : _M_state(__other._M_state)
492  {
493  if (_M_state)
494  _M_state->_M_add_ssrc();
495  }
496 
497  stop_source(stop_source&&) noexcept = default;
498 
499  stop_source&
500  operator=(const stop_source& __other) noexcept
501  {
502  if (_M_state != __other._M_state)
503  {
504  stop_source __sink(std::move(*this));
505  _M_state = __other._M_state;
506  if (_M_state)
507  _M_state->_M_add_ssrc();
508  }
509  return *this;
510  }
511 
512  stop_source&
513  operator=(stop_source&&) noexcept = default;
514 
515  ~stop_source()
516  {
517  if (_M_state)
518  _M_state->_M_sub_ssrc();
519  }
520 
521  [[nodiscard]]
522  bool
523  stop_possible() const noexcept
524  {
525  return static_cast<bool>(_M_state);
526  }
527 
528  [[nodiscard]]
529  bool
530  stop_requested() const noexcept
531  {
532  return static_cast<bool>(_M_state) && _M_state->_M_stop_requested();
533  }
534 
535  bool
536  request_stop() const noexcept
537  {
538  if (stop_possible())
539  return _M_state->_M_request_stop();
540  return false;
541  }
542 
543  [[nodiscard]]
544  stop_token
545  get_token() const noexcept
546  {
547  return stop_token{_M_state};
548  }
549 
550  void
551  swap(stop_source& __other) noexcept
552  {
553  _M_state.swap(__other._M_state);
554  }
555 
556  [[nodiscard]]
557  friend bool
558  operator==(const stop_source& __a, const stop_source& __b) noexcept
559  {
560  return __a._M_state == __b._M_state;
561  }
562 
563  friend void
564  swap(stop_source& __lhs, stop_source& __rhs) noexcept
565  {
566  __lhs.swap(__rhs);
567  }
568 
569  private:
570  stop_token::_Stop_state_ref _M_state;
571  };
572 
573  /// A wrapper for callbacks to be run when a stop request is made.
574  template<typename _Callback>
575  class [[nodiscard]] stop_callback
576  {
577  static_assert(is_nothrow_destructible_v<_Callback>);
578  static_assert(is_invocable_v<_Callback>);
579 
580  public:
581  using callback_type = _Callback;
582 
583  template<typename _Cb,
584  enable_if_t<is_constructible_v<_Callback, _Cb>, int> = 0>
585  explicit
586  stop_callback(const stop_token& __token, _Cb&& __cb)
587  noexcept(is_nothrow_constructible_v<_Callback, _Cb>)
588  : _M_cb(std::forward<_Cb>(__cb))
589  {
590  if (auto __state = __token._M_state)
591  {
592  if (__state->_M_register_callback(&_M_cb))
593  _M_state.swap(__state);
594  }
595  }
596 
597  template<typename _Cb,
598  enable_if_t<is_constructible_v<_Callback, _Cb>, int> = 0>
599  explicit
600  stop_callback(stop_token&& __token, _Cb&& __cb)
601  noexcept(is_nothrow_constructible_v<_Callback, _Cb>)
602  : _M_cb(std::forward<_Cb>(__cb))
603  {
604  if (auto& __state = __token._M_state)
605  {
606  if (__state->_M_register_callback(&_M_cb))
607  _M_state.swap(__state);
608  }
609  }
610 
611  ~stop_callback()
612  {
613  if (_M_state)
614  {
615  _M_state->_M_remove_callback(&_M_cb);
616  }
617  }
618 
619  stop_callback(const stop_callback&) = delete;
620  stop_callback& operator=(const stop_callback&) = delete;
621  stop_callback(stop_callback&&) = delete;
622  stop_callback& operator=(stop_callback&&) = delete;
623 
624  private:
625  struct _Cb_impl : stop_token::_Stop_cb
626  {
627  template<typename _Cb>
628  explicit
629  _Cb_impl(_Cb&& __cb)
630  : _Stop_cb(&_S_execute),
631  _M_cb(std::forward<_Cb>(__cb))
632  { }
633 
634  _Callback _M_cb;
635 
636  [[__gnu__::__nonnull__]]
637  static void
638  _S_execute(_Stop_cb* __that) noexcept
639  {
640  _Callback& __cb = static_cast<_Cb_impl*>(__that)->_M_cb;
641  std::forward<_Callback>(__cb)();
642  }
643  };
644 
645  _Cb_impl _M_cb;
646  stop_token::_Stop_state_ref _M_state;
647  };
648 
649  template<typename _Callback>
650  stop_callback(stop_token, _Callback) -> stop_callback<_Callback>;
651 
652 _GLIBCXX_END_NAMESPACE_VERSION
653 } // namespace
654 #endif // __cplusplus > 201703L
655 #endif // _GLIBCXX_STOP_TOKEN