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