1 // <stop_token> -*- C++ -*-
3 // Copyright (C) 2019-2020 Free Software Foundation, Inc.
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)
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.
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.
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/>.
25 /** @file include/stop_token
26 * This is a Standard C++ Library header.
29 #ifndef _GLIBCXX_STOP_TOKEN
30 #define _GLIBCXX_STOP_TOKEN
32 #if __cplusplus > 201703L
36 #ifdef _GLIBCXX_HAS_GTHREADS
37 # define __cpp_lib_jthread 201907L
38 # include <bits/gthr.h>
39 # if __has_include(<semaphore>)
44 namespace std _GLIBCXX_VISIBILITY(default)
46 _GLIBCXX_BEGIN_NAMESPACE_VERSION
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{};
54 /// Allow testing whether a stop request has been made on a `stop_source`.
58 stop_token() noexcept = default;
60 stop_token(const stop_token&) noexcept = default;
61 stop_token(stop_token&&) noexcept = default;
63 ~stop_token() = default;
66 operator=(const stop_token&) noexcept = default;
69 operator=(stop_token&&) noexcept = default;
73 stop_possible() const noexcept
75 return static_cast<bool>(_M_state) && _M_state->_M_stop_possible();
80 stop_requested() const noexcept
82 return static_cast<bool>(_M_state) && _M_state->_M_stop_requested();
86 swap(stop_token& __rhs) noexcept
87 { _M_state.swap(__rhs._M_state); }
91 operator==(const stop_token& __a, const stop_token& __b)
92 { return __a._M_state == __b._M_state; }
95 swap(stop_token& __lhs, stop_token& __rhs) noexcept
96 { __lhs.swap(__rhs); }
99 friend class stop_source;
100 template<typename _Callback>
101 friend class stop_callback;
106 #if defined __i386__ || defined __x86_64__
107 __builtin_ia32_pause();
108 #elif defined _GLIBCXX_USE_SCHED_YIELD
113 #ifndef __cpp_lib_semaphore
114 // TODO: replace this with a real implementation of std::binary_semaphore
115 struct binary_semaphore
117 explicit binary_semaphore(int __d) : _M_counter(__d > 0) { }
119 void release() { _M_counter.fetch_add(1, memory_order::release); }
124 while (!_M_counter.compare_exchange_weak(__old, 0,
125 memory_order::acquire,
126 memory_order::relaxed))
133 atomic<int> _M_counter;
139 using __cb_type = void(_Stop_cb*) noexcept;
140 __cb_type* _M_callback;
141 _Stop_cb* _M_prev = nullptr;
142 _Stop_cb* _M_next = nullptr;
143 bool* _M_destroyed = nullptr;
144 binary_semaphore _M_done{0};
146 [[__gnu__::__nonnull__]]
148 _Stop_cb(__cb_type* __cb)
152 void _M_run() noexcept { _M_callback(this); }
157 using value_type = uint32_t;
158 static constexpr value_type _S_stop_requested_bit = 1;
159 static constexpr value_type _S_locked_bit = 2;
160 static constexpr value_type _S_ssrc_counter_inc = 4;
162 std::atomic<value_type> _M_owners{1};
163 std::atomic<value_type> _M_value{_S_ssrc_counter_inc};
164 _Stop_cb* _M_head = nullptr;
165 #if _GLIBCXX_HAS_GTHREADS
166 __gthread_t _M_requester;
169 _Stop_state_t() = default;
172 _M_stop_possible() noexcept
174 // true if a stop request has already been made or there are still
175 // stop_source objects that would allow one to be made.
176 return _M_value.load(memory_order::acquire) & ~_S_locked_bit;
180 _M_stop_requested() noexcept
182 return _M_value.load(memory_order::acquire) & _S_stop_requested_bit;
186 _M_add_owner() noexcept
188 _M_owners.fetch_add(1, memory_order::relaxed);
192 _M_release_ownership() noexcept
194 if (_M_owners.fetch_sub(1, memory_order::release) == 1)
199 _M_add_ssrc() noexcept
201 _M_value.fetch_add(_S_ssrc_counter_inc, memory_order::relaxed);
205 _M_sub_ssrc() noexcept
207 _M_value.fetch_sub(_S_ssrc_counter_inc, memory_order::release);
214 // Can use relaxed loads to get the current value.
215 // The successful call to _M_try_lock is an acquire operation.
216 auto __old = _M_value.load(memory_order::relaxed);
217 while (!_M_try_lock(__old, memory_order::relaxed))
221 // Precondition: calling thread holds the lock.
225 _M_value.fetch_sub(_S_locked_bit, memory_order::release);
229 _M_request_stop() noexcept
231 // obtain lock and set stop_requested bit
232 auto __old = _M_value.load(memory_order::acquire);
235 if (__old & _S_stop_requested_bit) // stop request already made
238 while (!_M_try_lock_and_stop(__old));
240 #if _GLIBCXX_HAS_GTHREADS
241 _M_requester = __gthread_self();
247 _Stop_cb* __cb = _M_head;
248 _M_head = _M_head->_M_next;
251 _M_head->_M_prev = nullptr;
257 // Allow other callbacks to be unregistered while __cb runs.
260 bool __destroyed = false;
261 __cb->_M_destroyed = &__destroyed;
268 __cb->_M_destroyed = nullptr;
269 #if _GLIBCXX_HAS_GTHREADS
270 // synchronize with destructor of stop_callback that owns *__cb
271 __cb->_M_done.release();
275 // Avoid relocking if we already know there are no more callbacks.
286 [[__gnu__::__nonnull__]]
288 _M_register_callback(_Stop_cb* __cb) noexcept
290 auto __old = _M_value.load(memory_order::acquire);
293 if (__old & _S_stop_requested_bit) // stop request already made
295 __cb->_M_run(); // run synchronously
299 if (__old < _S_ssrc_counter_inc) // no stop_source owns *this
300 // No need to register callback if no stop request can be made.
301 // Returning false also means the stop_callback does not share
302 // ownership of this state, but that's not observable.
305 while (!_M_try_lock(__old));
307 __cb->_M_next = _M_head;
310 _M_head->_M_prev = __cb;
317 // Called by ~stop_callback just before destroying *__cb.
318 [[__gnu__::__nonnull__]]
320 _M_remove_callback(_Stop_cb* __cb)
326 _M_head = _M_head->_M_next;
328 _M_head->_M_prev = nullptr;
332 else if (__cb->_M_prev)
334 __cb->_M_prev->_M_next = __cb->_M_next;
336 __cb->_M_next->_M_prev = __cb->_M_prev;
343 // Callback is not in the list, so must have been removed by a call to
346 #if _GLIBCXX_HAS_GTHREADS
347 // Despite appearances there is no data race on _M_requester. The only
348 // write to it happens before the callback is removed from the list,
349 // and removing it from the list happens before this read.
350 if (!__gthread_equal(_M_requester, __gthread_self()))
352 // Synchronize with completion of callback.
353 __cb->_M_done.acquire();
354 // Safe for ~stop_callback to destroy *__cb now.
358 if (__cb->_M_destroyed)
359 *__cb->_M_destroyed = true;
362 // Try to obtain the lock.
363 // Returns true if the lock is acquired (with memory order acquire).
364 // Otherwise, sets __curval = _M_value.load(__failure) and returns false.
365 // Might fail spuriously, so must be called in a loop.
367 _M_try_lock(value_type& __curval,
368 memory_order __failure = memory_order::acquire) noexcept
370 return _M_do_try_lock(__curval, 0, memory_order::acquire, __failure);
373 // Try to obtain the lock to make a stop request.
374 // Returns true if the lock is acquired and the _S_stop_requested_bit is
375 // set (with memory order acq_rel so that other threads see the request).
376 // Otherwise, sets __curval = _M_value.load(memory_order::acquire) and
378 // Might fail spuriously, so must be called in a loop.
380 _M_try_lock_and_stop(value_type& __curval) noexcept
382 return _M_do_try_lock(__curval, _S_stop_requested_bit,
383 memory_order::acq_rel, memory_order::acquire);
387 _M_do_try_lock(value_type& __curval, value_type __newbits,
388 memory_order __success, memory_order __failure) noexcept
390 if (__curval & _S_locked_bit)
393 __curval = _M_value.load(__failure);
396 __newbits |= _S_locked_bit;
397 return _M_value.compare_exchange_weak(__curval, __curval | __newbits,
398 __success, __failure);
402 struct _Stop_state_ref
404 _Stop_state_ref() = default;
407 _Stop_state_ref(const stop_source&)
408 : _M_ptr(new _Stop_state_t())
411 _Stop_state_ref(const _Stop_state_ref& __other) noexcept
412 : _M_ptr(__other._M_ptr)
415 _M_ptr->_M_add_owner();
418 _Stop_state_ref(_Stop_state_ref&& __other) noexcept
419 : _M_ptr(__other._M_ptr)
421 __other._M_ptr = nullptr;
425 operator=(const _Stop_state_ref& __other) noexcept
427 if (auto __ptr = __other._M_ptr; __ptr != _M_ptr)
430 __ptr->_M_add_owner();
432 _M_ptr->_M_release_ownership();
439 operator=(_Stop_state_ref&& __other) noexcept
441 _Stop_state_ref(std::move(__other)).swap(*this);
448 _M_ptr->_M_release_ownership();
452 swap(_Stop_state_ref& __other) noexcept
453 { std::swap(_M_ptr, __other._M_ptr); }
455 explicit operator bool() const noexcept { return _M_ptr != nullptr; }
457 _Stop_state_t* operator->() const noexcept { return _M_ptr; }
459 #if __cpp_impl_three_way_comparison >= 201907L
461 operator==(const _Stop_state_ref&, const _Stop_state_ref&) = default;
464 operator==(const _Stop_state_ref& __lhs, const _Stop_state_ref& __rhs)
466 { return __lhs._M_ptr == __rhs._M_ptr; }
469 operator!=(const _Stop_state_ref& __lhs, const _Stop_state_ref& __rhs)
471 { return __lhs._M_ptr != __rhs._M_ptr; }
475 _Stop_state_t* _M_ptr = nullptr;
478 _Stop_state_ref _M_state;
481 stop_token(const _Stop_state_ref& __state) noexcept
486 /// A type that allows a stop request to be made.
490 stop_source() : _M_state(*this)
493 explicit stop_source(std::nostopstate_t) noexcept
496 stop_source(const stop_source& __other) noexcept
497 : _M_state(__other._M_state)
500 _M_state->_M_add_ssrc();
503 stop_source(stop_source&&) noexcept = default;
506 operator=(const stop_source& __other) noexcept
508 if (_M_state != __other._M_state)
510 stop_source __sink(std::move(*this));
511 _M_state = __other._M_state;
513 _M_state->_M_add_ssrc();
519 operator=(stop_source&&) noexcept = default;
524 _M_state->_M_sub_ssrc();
529 stop_possible() const noexcept
531 return static_cast<bool>(_M_state);
536 stop_requested() const noexcept
538 return static_cast<bool>(_M_state) && _M_state->_M_stop_requested();
542 request_stop() const noexcept
545 return _M_state->_M_request_stop();
551 get_token() const noexcept
553 return stop_token{_M_state};
557 swap(stop_source& __other) noexcept
559 _M_state.swap(__other._M_state);
564 operator==(const stop_source& __a, const stop_source& __b) noexcept
566 return __a._M_state == __b._M_state;
570 swap(stop_source& __lhs, stop_source& __rhs) noexcept
576 stop_token::_Stop_state_ref _M_state;
579 /// A wrapper for callbacks to be run when a stop request is made.
580 template<typename _Callback>
581 class [[nodiscard]] stop_callback
583 static_assert(is_nothrow_destructible_v<_Callback>);
584 static_assert(is_invocable_v<_Callback>);
587 using callback_type = _Callback;
589 template<typename _Cb,
590 enable_if_t<is_constructible_v<_Callback, _Cb>, int> = 0>
592 stop_callback(const stop_token& __token, _Cb&& __cb)
593 noexcept(is_nothrow_constructible_v<_Callback, _Cb>)
594 : _M_cb(std::forward<_Cb>(__cb))
596 if (auto __state = __token._M_state)
598 if (__state->_M_register_callback(&_M_cb))
599 _M_state.swap(__state);
603 template<typename _Cb,
604 enable_if_t<is_constructible_v<_Callback, _Cb>, int> = 0>
606 stop_callback(stop_token&& __token, _Cb&& __cb)
607 noexcept(is_nothrow_constructible_v<_Callback, _Cb>)
608 : _M_cb(std::forward<_Cb>(__cb))
610 if (auto& __state = __token._M_state)
612 if (__state->_M_register_callback(&_M_cb))
613 _M_state.swap(__state);
621 _M_state->_M_remove_callback(&_M_cb);
625 stop_callback(const stop_callback&) = delete;
626 stop_callback& operator=(const stop_callback&) = delete;
627 stop_callback(stop_callback&&) = delete;
628 stop_callback& operator=(stop_callback&&) = delete;
631 struct _Cb_impl : stop_token::_Stop_cb
633 template<typename _Cb>
636 : _Stop_cb(&_S_execute),
637 _M_cb(std::forward<_Cb>(__cb))
642 [[__gnu__::__nonnull__]]
644 _S_execute(_Stop_cb* __that) noexcept
646 _Callback& __cb = static_cast<_Cb_impl*>(__that)->_M_cb;
647 std::forward<_Callback>(__cb)();
652 stop_token::_Stop_state_ref _M_state;
655 template<typename _Callback>
656 stop_callback(stop_token, _Callback) -> stop_callback<_Callback>;
658 _GLIBCXX_END_NAMESPACE_VERSION
660 #endif // __cplusplus > 201703L
661 #endif // _GLIBCXX_STOP_TOKEN