%!TEX root = std.tex

\rSec0[thread]{Concurrency support library}

\rSec1[thread.general]{General}

\pnum

The following subclauses describe components to create and manage

threads\iref{intro.multithread}, perform mutual exclusion, and communicate conditions

and values

between threads, as summarized in \tref{thread.summary}.

\begin{libsumtab}{Concurrency support library summary}{thread.summary}

\ref{thread.req} & Requirements & \\ \rowsep

\ref{thread.stoptoken}& Stop tokens & \tcode{<stop_token>} \\ \rowsep

\ref{thread.threads} & Threads & \tcode{<thread>} \\ \rowsep

\ref{atomics} & Atomic operations &

\tcode{<atomic>}, \tcode{<stdatomic.h>} \\ \rowsep

\ref{thread.mutex} & Mutual exclusion &

\tcode{<mutex>}, \tcode{<shared_mutex>} \\ \rowsep

\ref{thread.condition}& Condition variables & \tcode{<condition_variable>} \\ \rowsep

\ref{thread.sema} & Semaphores & \tcode{<semaphore>} \\ \rowsep

\ref{thread.coord} & Coordination types & \tcode{<latch>}, \tcode{<barrier>} \\ \rowsep

\ref{futures} & Futures & \tcode{<future>} \\ \rowsep

\ref{saferecl} & Safe reclamation & \tcode{<rcu>}, \tcode{<hazard_pointer>} \\

\end{libsumtab}

\rSec1[thread.req]{Requirements}

\rSec2[thread.req.paramname]{Template parameter names}

\pnum

Throughout this Clause, the names of template parameters are used to express type

requirements.

\tcode{Predicate} is a function object type\iref{function.objects}.

Let \tcode{pred} denote an lvalue of type \tcode{Predicate}.

Then the expression \tcode{pred()} shall be well-formed and

the type \tcode{decltype(pred())} shall model

\exposconcept{boolean-testable}\iref{concept.booleantestable}.

The return value of \tcode{pred()}, converted to \tcode{bool},

yields \tcode{true} if the corresponding test condition is satisfied, and

\tcode{false} otherwise.

If a template parameter is named \tcode{Clock},

the corresponding template argument shall be a type \tcode{C}

that meets the \oldconcept{Clock} requirements\iref{time.clock.req};

the program is ill-formed if \tcode{is_clock_v<C>} is \tcode{false}.

\rSec2[thread.req.exception]{Exceptions}

\pnum

Some functions described in this Clause are specified to throw exceptions of type

\tcode{system_error}\iref{syserr.syserr}. Such exceptions are thrown if

any of the function's error conditions is detected or

a call to

an operating system or other underlying API results in an error that prevents the

library function from

meeting its specifications. Failure to allocate storage is reported as described

in~\ref{res.on.exception.handling}.

\begin{example}

Consider a function in this Clause that is specified to throw exceptions of type

\tcode{system_error} and specifies error conditions that include

\tcode{operation_not_permitted} for a thread that does not have the privilege to

perform the operation. Assume that, during the execution of this function, an \tcode{errno}

of \tcode{EPERM} is reported by a POSIX API call used by the implementation. Since POSIX

specifies an \tcode{errno} of \tcode{EPERM} when ``the caller does not have the privilege

to perform the operation'', the implementation maps \tcode{EPERM} to an

\tcode{error_condition} of \tcode{operation_not_permitted}\iref{syserr} and an exception

of type \tcode{system_error} is thrown.

\end{example}

\pnum

The \tcode{error_code} reported by such an exception's \tcode{code()} member function

compares equal to one of the conditions specified in the function's error condition

element.

\rSec2[thread.req.native]{Native handles}

\pnum

Several classes described in this Clause have members \tcode{native_handle_type} and

\tcode{native_handle}. The presence of these members and their semantics is

\impldef{presence and meaning of \tcode{native_handle_type} and \tcode{native_handle}}.

\begin{note}

These members allow implementations to provide access

to implementation details. Their names are specified to facilitate portable compile-time

detection. Actual use of these members is inherently non-portable.

\end{note}

\rSec2[thread.req.timing]{Timing specifications}

\pnum

Several functions described in this Clause take an argument to specify a timeout. These

timeouts are specified as either a \tcode{duration} or a \tcode{time_point} type as

specified in~\ref{time}.

\pnum

Implementations necessarily have some delay in returning from a timeout. Any overhead in

interrupt response, function return, and scheduling induces a ``quality of implementation''

delay, expressed as duration $D_i$. Ideally, this delay would be zero. Further, any contention for

processor and memory resources induces a ``quality of management'' delay, expressed as duration

$D_m$. The delay durations may vary from timeout to timeout, but in all cases shorter is better.

\pnum

The functions whose names end in \tcode{_for} take an argument that

specifies a duration. These functions produce relative timeouts. Implementations

should use a steady clock to measure time for these functions.

\begin{footnote}

Implementations for which standard time units are meaningful will typically

have a steady clock within their hardware implementation.

\end{footnote}

Given a duration

argument $D_t$, the real-time duration of the timeout is $D_t + D_i + D_m$.

\pnum

The functions whose names end in \tcode{_until} take an argument that specifies a time

point. These functions produce absolute timeouts. Implementations should use the clock

specified in the time point to measure time for these functions. Given a clock time point

argument $C_t$, the clock time point of the return from timeout should be $C_t + D_i + D_m$

when the clock is not adjusted during the timeout. If the clock is adjusted to the time $C_a$

during the timeout, the behavior should be as follows:

\begin{itemize}

\item

If $C_a > C_t$, the waiting function should wake as soon as possible, i.e., $C_a + D_i + D_m$,

since the timeout is already satisfied.

This specification may result in the total

duration of the wait decreasing when measured against a steady clock.

\item

If $C_a \leq C_t$, the waiting function should not time out until \tcode{Clock::now()} returns a

time $C_n \geq C_t$, i.e., waking at $C_t + D_i + D_m$.

\begin{note}

When the clock is adjusted

backwards, this specification can result in the total duration of the wait increasing when

measured against a steady clock. When the clock is adjusted forwards, this specification can

result in the total duration of the wait decreasing when measured against a steady clock.

\end{note}

\end{itemize}

An implementation returns from such a timeout at any point from the time specified above to

the time it would return from a steady-clock relative timeout on the difference between $C_t$

and the time point of the call to the \tcode{_until} function.

\recommended

Implementations

should decrease the duration of the wait when the clock is adjusted forwards.

\pnum

\begin{note}

If the clock is not synchronized with a steady clock, e.g., a CPU time clock, these

timeouts can fail to provide useful functionality.

\end{note}

\pnum

The resolution of timing provided by an implementation depends on both operating system

and hardware. The finest resolution provided by an implementation is called the

\term{native resolution}.

\pnum

Implementation-provided clocks that are used for these functions meet the

\oldconcept{TrivialClock} requirements\iref{time.clock.req}.

\pnum

A function that takes an argument which specifies a timeout will throw if,

during its execution, a clock, time point, or time duration throws an exception.

Such exceptions are referred to as \term{timeout-related exceptions}.

\begin{note}

Instantiations of clock, time point and duration types supplied by

the implementation as specified in~\ref{time.clock} do not throw exceptions.

\end{note}

\rSec2[thread.req.lockable]{Requirements for \oldconcept{Lockable} types}

\rSec3[thread.req.lockable.general]{General}

\pnum

An \defn{execution agent} is an entity such as a thread that may perform work in parallel with

other execution agents.

\begin{note}

Implementations or users can introduce other kinds of

agents such as processes or thread-pool tasks.

\end{note}

The calling agent is determined by

context, e.g., the calling thread that contains the call, and so on.

\pnum

\begin{note}

Some lockable objects are ``agent oblivious'' in that they work for any

execution agent model because they do not determine or store the agent's ID (e.g., an

ordinary spin lock).

\end{note}

\pnum

The standard library templates \tcode{unique_lock}\iref{thread.lock.unique},

\tcode{shared_lock}\iref{thread.lock.shared},

\tcode{scoped_lock}\iref{thread.lock.scoped},

\tcode{lock_guard}\iref{thread.lock.guard}, \tcode{lock},

\tcode{try_lock}\iref{thread.lock.algorithm}, and

\tcode{condition_variable_any}\iref{thread.condition.condvarany} all operate on user-supplied

lockable objects. The \oldconcept{BasicLockable} requirements, the \oldconcept{Lockable} requirements,

the \oldconcept{TimedLockable} requirements,

the \oldconcept{SharedLockable} requirements, and

the \oldconcept{SharedTimedLock\-able} requirements

list the requirements imposed by these library types

in order to acquire or release ownership of a \tcode{lock} by a given execution agent.

\begin{note}

The nature of any lock ownership and any synchronization it entails are not part

of these requirements.

\end{note}

\pnum

A lock on an object \tcode{m} is said to be

\begin{itemize}

\item

a \defnadj{non-shared}{lock} if it is acquired by a call to

\tcode{lock},

\tcode{try_lock},

\tcode{try_lock_for}, or

\tcode{try_lock_until} on \tcode{m}, or

\item

a \defnadj{shared}{lock} if it is acquired by a call to

\tcode{lock_shared},

\tcode{try_lock_shared},

\tcode{try_lock_shared_for}, or

\tcode{try_lock_shared_until} on \tcode{m}.

\end{itemize}

\begin{note}

Only the method of lock acquisition is considered;

the nature of any lock ownership is not part of these definitions.

\end{note}

\rSec3[thread.req.lockable.basic]{\oldconcept{BasicLockable} requirements}

\pnum

A type \tcode{L} meets the \defnoldconcept{BasicLockable} requirements if the following expressions are

well-formed and have the specified semantics (\tcode{m} denotes a value of type \tcode{L}).

\begin{itemdecl}

m.lock()

\end{itemdecl}

\begin{itemdescr}

\pnum

\indextext{block (execution)}%

\effects

Blocks until a lock can be acquired for the current execution agent. If an exception

is thrown then a lock shall not have been acquired for the current execution agent.

\end{itemdescr}

\begin{itemdecl}

m.unlock()

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

The current execution agent holds a non-shared lock on \tcode{m}.

\pnum

\effects

Releases a non-shared lock on \tcode{m} held by the current execution agent.

\pnum

\throws

Nothing.

\end{itemdescr}

\rSec3[thread.req.lockable.req]{\oldconcept{Lockable} requirements}

\pnum

A type \tcode{L} meets the \defnoldconcept{Lockable} requirements if it meets the \oldconcept{BasicLockable}

requirements and the following expressions are well-formed and have the specified semantics

(\tcode{m} denotes a value of type \tcode{L}).

\begin{itemdecl}

m.try_lock()

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent without blocking. If an

exception is thrown then a lock shall not have been acquired for the current execution agent.

\pnum

\returntype \tcode{bool}.

\pnum

\returns

\tcode{true} if the lock was acquired, otherwise \tcode{false}.

\end{itemdescr}

\rSec3[thread.req.lockable.timed]{\oldconcept{TimedLockable} requirements}

\pnum

A type \tcode{L} meets the \defnoldconcept{TimedLockable} requirements if it meets the \oldconcept{Lockable}

requirements and the following expressions are well-formed and have the specified semantics

(\tcode{m} denotes a value of type \tcode{L}, \tcode{rel_time} denotes a value of a

specialization of \tcode{duration}\iref{time.duration}, and \tcode{abs_time} denotes a value

of a specialization of \tcode{time_point}\iref{time.point}).

\begin{itemdecl}

m.try_lock_for(rel_time)

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent within the relative

timeout\iref{thread.req.timing} specified by \tcode{rel_time}. The function will not return

within the timeout specified by \tcode{rel_time} unless it has obtained a lock on \tcode{m}

for the current execution agent. If an exception is thrown then a lock has not been

acquired for the current execution agent.

\pnum

\returntype \tcode{bool}.

\pnum

\returns

\tcode{true} if the lock was acquired, otherwise \tcode{false}.

\end{itemdescr}

\begin{itemdecl}

m.try_lock_until(abs_time)

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent before the absolute

timeout\iref{thread.req.timing} specified by \tcode{abs_time}. The function will not return

before the timeout specified by \tcode{abs_time} unless it has obtained a lock on \tcode{m} for

the current execution agent. If an exception is thrown then a lock has not been acquired

for the current execution agent.

\pnum

\returntype \tcode{bool}.

\pnum

\returns

\tcode{true} if the lock was acquired, otherwise \tcode{false}.

\end{itemdescr}

\rSec3[thread.req.lockable.shared]{\oldconcept{SharedLockable} requirements}

\pnum

A type \tcode{L} meets the \defnoldconcept{SharedLockable} requirements if

the following expressions are well-formed, have the specified semantics, and

the expression \tcode{m.try_lock_shared()} has type \tcode{bool}

(\tcode{m} denotes a value of type \tcode{L}):

\begin{itemdecl}

m.lock_shared()

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Blocks until a lock can be acquired for the current execution agent.

If an exception is thrown then a lock shall not have been acquired for

the current execution agent.

\end{itemdescr}

\begin{itemdecl}

m.try_lock_shared()

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent without blocking.

If an exception is thrown then a lock shall not have been acquired for

the current execution agent.

\pnum

\returns

\tcode{true} if the lock was acquired, \tcode{false} otherwise.

\end{itemdescr}

\begin{itemdecl}

m.unlock_shared()

\end{itemdecl}

\begin{itemdescr}

\pnum

\expects

The current execution agent holds a shared lock on \tcode{m}.

\pnum

\effects

Releases a shared lock on \tcode{m} held by the current execution agent.

\pnum

\throws

Nothing.

\end{itemdescr}

\rSec3[thread.req.lockable.shared.timed]{\oldconcept{SharedTimedLockable} requirements}

\pnum

A type \tcode{L} meets the \defnoldconcept{SharedTimedLockable} requirements if

it meets the \oldconcept{SharedLockable} requirements, and

the following expressions are well-formed, have type \tcode{bool}, and

have the specified semantics

(\tcode{m} denotes a value of type \tcode{L},

\tcode{rel_time} denotes a value of a specialization of \tcode{chrono::duration}, and

\tcode{abs_time} denotes a value of a specialization of \tcode{chrono::time_point}).

\begin{itemdecl}

m.try_lock_shared_for(rel_time)

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent within

the relative timeout\iref{thread.req.timing} specified by \tcode{rel_time}.

The function will not return within the timeout specified by \tcode{rel_time}

unless it has obtained a lock on \tcode{m} for the current execution agent.

If an exception is thrown then a lock has not been acquired for

the current execution agent.

\pnum

\returns

\tcode{true} if the lock was acquired, \tcode{false} otherwise.

\end{itemdescr}

\begin{itemdecl}

m.try_lock_shared_until(abs_time)

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Attempts to acquire a lock for the current execution agent before

the absolute timeout\iref{thread.req.timing} specified by \tcode{abs_time}.

The function will not return before the timeout specified by \tcode{abs_time}

unless it has obtained a lock on \tcode{m} for the current execution agent.

If an exception is thrown then a lock has not been acquired for

the current execution agent.

\pnum

\returns

\tcode{true} if the lock was acquired, \tcode{false} otherwise.

\end{itemdescr}

\rSec1[thread.stoptoken]{Stop tokens}

\rSec2[thread.stoptoken.intro]{Introduction}

\pnum

Subclause \ref{thread.stoptoken} describes components that can be used

to asynchronously request that an operation stops execution in a timely manner,

typically because the result is no longer required.

Such a request is called a \defn{stop request}.

\pnum

The concepts

\exposconcept{stoppable-source},

\libconcept{stoppable_token}, and

\exposconcept{stoppable-callback-for}

specify the required syntax and semantics of

shared access to a \defn{stop state}.

Any object modeling \exposconcept{stoppable-source},

\libconcept{stoppable_token}, or

\exposconcept{stoppable-callback-for}

that refers to the same stop state is

an \defn{associated}

\exposconcept{stoppable-source},

\libconcept{stoppable_token}, or

\exposconcept{stoppable-callback-for},

respectively.

\pnum

An object of a type that models \libconcept{stoppable_token}

can be passed to an operation that can either

\begin{itemize}

\item actively poll the token to check if there has been a stop request, or

\item register a callback that

will be called in the event that a stop request is made.

\end{itemize}

A stop request made via an object

whose type models \exposconcept{stoppable-source}

will be visible to

all associated \libconcept{stoppable_token} and

\exposconcept{stoppable-source} objects.

Once a stop request has been made it cannot be withdrawn

(a subsequent stop request has no effect).

\pnum

Callbacks registered via an object

whose type models \exposconcept{stoppable-callback-for}

are called when a stop request is first made

by any associated \exposconcept{stoppable-source} object.

\pnum

The types \tcode{stop_source} and \tcode{stop_token} and

the class template \tcode{stop_callback} implement

the semantics of shared ownership of a stop state.

The last remaining owner of the stop state automatically releases

the resources associated with the stop state.

\pnum

An object of type \tcode{inplace_stop_source}

is the sole owner of its stop state.

An object of type \tcode{inplace_stop_token} or

of a specialization of the class template \tcode{inplace_stop_callback}

does not participate in ownership of its associated stop state.

\begin{note}

They are for use when all uses of the associated token and callback objects

are known to nest within the lifetime of the \tcode{inplace_stop_source} object.

\end{note}

\rSec2[thread.stoptoken.syn]{Header \tcode{<stop_token>} synopsis}

\indexheader{stop_token}%

\begin{codeblock}

namespace std {

// \ref{stoptoken.concepts}, stop token concepts

template<class CallbackFn, class Token, class Initializer = CallbackFn>

concept @\exposconcept{stoppable-callback-for}@ = @\seebelow@; // \expos

template<class Token>

concept @\libconcept{stoppable_token}@ = @\seebelow@;

template<class Token>

concept @\libconcept{unstoppable_token}@ = @\seebelow@;

template<class Source>

concept @\exposconcept{stoppable-source}@ = @\seebelow@; // \expos

// \ref{stoptoken}, class \tcode{stop_token}

class stop_token;

// \ref{stopsource}, class \tcode{stop_source}

class stop_source;

// no-shared-stop-state indicator

struct @\libglobal{nostopstate_t}@ {

explicit nostopstate_t() = default;

};

inline constexpr nostopstate_t @\libglobal{nostopstate}@{};

// \ref{stopcallback}, class template \tcode{stop_callback}

template<class Callback>

class stop_callback;

// \ref{stoptoken.never}, class \tcode{never_stop_token}

class never_stop_token;

// \ref{stoptoken.inplace}, class \tcode{inplace_stop_token}

class inplace_stop_token;

// \ref{stopsource.inplace}, class \tcode{inplace_stop_source}

class inplace_stop_source;

// \ref{stopcallback.inplace}, class template \tcode{inplace_stop_callback}

template<class CallbackFn>

class inplace_stop_callback;

template<class T, class CallbackFn>

using @\libglobal{stop_callback_for_t}@ = T::template callback_type<CallbackFn>;

}

\end{codeblock}

\rSec2[stoptoken.concepts]{Stop token concepts}

\pnum

The exposition-only \exposconcept{stoppable-callback-for} concept

checks for a callback compatible with a given \tcode{Token} type.

\begin{codeblock}

template<class CallbackFn, class Token, class Initializer = CallbackFn>

concept @\defexposconcept{stoppable-callback-for}@ = // \expos

@\libconcept{invocable}@<CallbackFn> &&

@\libconcept{constructible_from}@<CallbackFn, Initializer> &&

requires { typename stop_callback_for_t<Token, CallbackFn>; } &&

@\libconcept{constructible_from}@<stop_callback_for_t<Token, CallbackFn>, const Token&, Initializer>;

\end{codeblock}

\pnum

Let \tcode{t} and \tcode{u} be distinct, valid objects of type \tcode{Token}

that reference the same logical stop state;

let \tcode{init} be an expression such that

\tcode{\libconcept{same_as}<decltype(init), Initializer>} is \tcode{true}; and

let \tcode{SCB} denote the type \tcode{stop_callback_for_t<Token, CallbackFn>}.

\pnum

The concept

\tcode{\exposconcept{stoppable-callback-for}<CallbackFn, Token, Initializer>}

is modeled only if:

\begin{itemize}

\item

The following concepts are modeled:

\begin{itemize}

\item \tcode{\libconcept{constructible_from}<SCB, Token, Initializer>}

\item \tcode{\libconcept{constructible_from}<SCB, Token\&, Initializer>}

\item \tcode{\libconcept{constructible_from}<SCB, const Token, Initializer>}

\end{itemize}

\item

An object of type \tcode{SCB} has

an associated callback function of type \tcode{CallbackFn}.

Let \tcode{scb} be an object of type \tcode{SCB} and

let \tcode{callback_fn} denote \tcode{scb}'s associated callback function.

Direct-non-list-initializing \tcode{scb} from

arguments \tcode{t} and \tcode{init}

shall execute a \defnadj{stoppable callback}{registration} as follows:

\begin{itemize}

\item

If \tcode{t.stop_possible()} is \tcode{true}:

\begin{itemize}

\item

\tcode{callback_fn} shall be direct-initialized with \tcode{init}.

\item

Construction of \tcode{scb} shall only throw exceptions

thrown by the initialization of \tcode{callback_fn} from \tcode{init}.

\item

The callback invocation \tcode{std::forward<CallbackFn>(callback_fn)()}

shall be registered with \tcode{t}'s associated stop state as follows:

\begin{itemize}

\item

If \tcode{t.stop_requested()} evaluates to \tcode{false}

at the time of registration,

the callback invocation is added to the stop state's list of callbacks

such that \tcode{std::forward<CallbackFn>(\newline callback_fn)()} is evaluated

if a stop request is made on the stop state.

\item

Otherwise, \tcode{std::forward<CallbackFn>(callback_fn)()}

shall be immediately evaluated

on the thread executing \tcode{scb}'s constructor, and

the callback invocation shall not be added to the list of callback invocations.

\end{itemize}

If the callback invocation was added to stop state's list of callbacks,

\tcode{scb} shall be associated with the stop state.

\end{itemize}

\begin{note}

If \tcode{t.stop_possible()} is \tcode{false},

there is no requirement

that the initialization of \tcode{scb}

causes the initialization of \tcode{callback_fn}.

\end{note}

\end{itemize}

\item

Destruction of \tcode{scb} shall execute

a \defnadj{stoppable}{callback deregistration} as follows (in order):

\begin{itemize}

\item

If the constructor of \tcode{scb} did not register

a callback invocation with \tcode{t}'s stop state,

then the stoppable callback deregistration shall have no effect

other than destroying \tcode{callback_fn} if it was constructed.

\item

Otherwise, the invocation of \tcode{callback_fn} shall be removed

from the associated stop state.

\item

If \tcode{callback_fn} is concurrently executing on another thread,

then the stoppable callback deregistration shall block\iref{defns.block}

until the invocation of \tcode{callback_fn} returns

such that the return from the invocation of \tcode{callback_fn}

strongly happens before\iref{intro.races}

the destruction of \tcode{callback_fn}.

\item

If \tcode{callback_fn} is executing on the current thread,

then the destructor shall not block

waiting for the return from the invocation of \tcode{callback_fn}.

\item

A stoppable callback deregistration shall not block

on the completion of the invocation of some other callback

registered with the same logical stop state.

\item

The stoppable callback deregistration shall destroy \tcode{callback_fn}.

\end{itemize}

\end{itemize}

\pnum

The \libconcept{stoppable_token} concept checks

for the basic interface of a stop token

that is copyable and allows polling to see if stop has been requested and

also whether a stop request is possible.

The \libconcept{unstoppable_token} concept checks

for a \libconcept{stoppable_token} type that does not allow stopping.

\begin{codeblock}

template<template<class> class>

struct @\exposid{check-type-alias-exists}@; // \expos

template<class Token>

concept @\deflibconcept{stoppable_token}@ =

requires (const Token tok) {

typename @\exposid{check-type-alias-exists}@<Token::template callback_type>;

{ tok.stop_requested() } noexcept -> @\libconcept{same_as}@<bool>;

{ tok.stop_possible() } noexcept -> @\libconcept{same_as}@<bool>;

{ Token(tok) } noexcept; // see implicit expression variations\iref{concepts.equality}

} &&

@\libconcept{copyable}@<Token> &&

@\libconcept{equality_comparable}@<Token>;

template<class Token>

concept @\deflibconcept{unstoppable_token}@ =

@\libconcept{stoppable_token}@<Token> &&

requires (const Token tok) {

requires bool_constant<(!tok.stop_possible())>::value;

};

\end{codeblock}

\pnum

An object whose type models \libconcept{stoppable_token}

has at most one associated logical stop state.

A \libconcept{stoppable_token} object with no associated stop state

is said to be \defn{disengaged}.

\pnum

Let \tcode{SP} be an evaluation of \tcode{t.stop_possible()}

that is \tcode{false}, and

let SR be an evaluation of \tcode{t.stop_requested()} that is \tcode{true}.

\pnum

The type \tcode{Token} models \libconcept{stoppable_token} only if:

\begin{itemize}

\item

Any evaluation of \tcode{u.stop_possible()} or \tcode{u.stop_requested()}

that happens after\iref{intro.races} \tcode{SP} is \tcode{false}.

\item

Any evaluation of \tcode{u.stop_possible()} or \tcode{u.stop_requested()}

that happens after \tcode{SR} is \tcode{true}.

\item

For any types \tcode{CallbackFn} and \tcode{Initializer} such that

\tcode{\exposconcept{stoppable-callback-for}<CallbackFn, To\-ken, Initializer>}

is satisfied,

\tcode{\exposconcept{stoppable-callback-for}<CallbackFn, Token, Initializer>}

is modeled.

\item

If \tcode{t} is disengaged,

evaluations of \tcode{t.stop_possible()} and \tcode{t.stop_requested()}

are \tcode{false}.

\item

If \tcode{t} and \tcode{u} reference the same stop state, or

if both \tcode{t} and \tcode{u} are disengaged,

\tcode{t == u} is \tcode{true}; otherwise, it is \tcode{false}.

\end{itemize}

\pnum

An object

whose type models the exposition-only \exposconcept{stoppable-source} concept

can be queried

whether stop has been requested (\tcode{stop_requested}) and

whether stop is possible (\tcode{stop_possible}).

It is a factory for associated stop tokens (\tcode{get_token}), and

a stop request can be made on it (\tcode{request_stop}).

It maintains a list of registered stop callback invocations

that it executes when a stop request is first made.

\begin{codeblock}

template<class Source>

concept @\defexposconcept{stoppable-source}@ = // \expos

requires (Source& src, const Source csrc) { // see implicit expression variations\iref{concepts.equality}

{ csrc.get_token() } -> stoppable_token;

{ csrc.stop_possible() } noexcept -> @\libconcept{same_as}@<bool>;

{ csrc.stop_requested() } noexcept -> @\libconcept{same_as}@<bool>;

{ src.request_stop() } -> @\libconcept{same_as}@<bool>;

};

\end{codeblock}

\pnum

An object whose type models \exposconcept{stoppable-source} has

at most one associated logical stop state.

If it has no associated stop state, it is said to be disengaged.

Let \tcode{s} be an object whose type models \exposconcept{stoppable-source} and

that is disengaged.

\tcode{s.stop_possible()} and \tcode{s.stop_requested()} shall be \tcode{false}.

\pnum

Let \tcode{t} be an object whose type models \exposconcept{stoppable-source}.

If \tcode{t} is disengaged,

\tcode{t.get_token()} shall return a disengaged stop token;

otherwise, it shall return

a stop token that is associated with the stop state of \tcode{t}.

\pnum

Calls to the member functions

\tcode{request_stop}, \tcode{stop_requested}, and \tcode{stop_possible} and

similarly named member functions

on associated \libconcept{stoppable_token} objects

do not introduce data races.

A call to \tcode{request_stop} that returns \tcode{true} synchronizes with

a call to \tcode{stop_requested} on

an associated

\libconcept{stoppable_token} or \exposconcept{stoppable-source} object

that returns \tcode{true}.

Registration of a callback synchronizes with the invocation of that callback.

\pnum

If the \exposconcept{stoppable-source} is disengaged,

\tcode{request_stop} shall have no effect and return \tcode{false}.

Otherwise, it shall execute a \defnadj{stop request}{operation}

on the associated stop state.

A stop request operation determines

whether the stop state has received a stop request, and

if not, makes a stop request.

The determination and making of the stop request shall happen atomically,

as-if by a read-modify-write operation\iref{intro.races}.

If the request was made,

the stop state's registered callback invocations shall be

synchronously executed.

If an invocation of a callback exits via an exception

then \tcode{terminate} shall be invoked\iref{except.terminate}.

\begin{note}

No constraint is placed on the order

in which the callback invocations are executed.

\end{note}

\tcode{request_stop} shall return \tcode{true} if a stop request was made, and

\tcode{false} otherwise.

After a call to \tcode{request_stop} either

a call to \tcode{stop_possible} shall return \tcode{false} or

a call to \tcode{stop_requested} shall return \tcode{true}.

\begin{note}

A stop request includes notifying

all condition variables of type \tcode{condition_variable_any}

temporarily registered during

an interruptible wait\iref{thread.condvarany.intwait}.

\end{note}

\rSec2[stoptoken]{Class \tcode{stop_token}}%

\indexlibraryglobal{stop_token}%

\rSec3[stoptoken.general]{General}

\pnum

\indexlibraryglobal{stop_token}%

The class \tcode{stop_token} models the concept \libconcept{stoppable_token}.

It shares ownership of its stop state, if any,

with its associated \tcode{stop_source} object\iref{stopsource} and

any \tcode{stop_token} objects to which it compares equal.

\begin{codeblock}

namespace std {

class stop_token {

public:

template<class CallbackFn>

using @\libmember{callback_type}{stop_token}@ = stop_callback<CallbackFn>;

stop_token() noexcept = default;

// \ref{stoptoken.mem}, member functions

void swap(stop_token&) noexcept;

bool stop_requested() const noexcept;

bool stop_possible() const noexcept;

bool operator==(const stop_token& rhs) noexcept = default;

private:

shared_ptr<@\unspec@> @\exposid{stop-state}@; // \expos

};

}

\end{codeblock}

\pnum

\exposid{stop-state} refers to the \tcode{stop_token}'s associated stop state.

A \tcode{stop_token} object is disengaged when \exposid{stop-state} is empty.

\rSec3[stoptoken.mem]{Member functions}

\indexlibrarymember{swap}{stop_token}%

\begin{itemdecl}

void swap(stop_token& rhs) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to:

\begin{codeblock}

@\exposid{stop-state}@.swap(rhs.@\exposid{stop-state}@);

\end{codeblock}

\end{itemdescr}

\indexlibrarymember{stop_requested}{stop_token}%

\begin{itemdecl}

bool stop_requested() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{true} if \exposid{stop-state} refers to a stop state

that has received a stop request;

otherwise, \tcode{false}.

\end{itemdescr}

\indexlibrarymember{stop_possible}{stop_token}%

\begin{itemdecl}

bool stop_possible() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{false} if

\begin{itemize}

\item \tcode{*this} is disengaged, or

\item a stop request was not made

and there are no associated \tcode{stop_source} objects;

\end{itemize}

otherwise, \tcode{true}.

\end{itemdescr}

\rSec2[stopsource]{Class \tcode{stop_source}}%

\indexlibraryglobal{stop_source}%

\rSec3[stopsource.general]{General}

\begin{codeblock}

namespace std {

class stop_source {

public:

// \ref{stopsource.cons}, constructors, copy, and assignment

stop_source();

explicit stop_source(nostopstate_t) noexcept {}

// \ref{stopsource.mem}, member functions

void swap(stop_source&) noexcept;

stop_token get_token() const noexcept;

bool stop_possible() const noexcept;

bool stop_requested() const noexcept;

bool request_stop() noexcept;

bool operator==(const stop_source& rhs) noexcept = default;

private:

shared_ptr<@\unspec@> @\exposid{stop-state}@; // \expos

};

}

\end{codeblock}

\pnum

\exposid{stop-state} refers to the \tcode{stop_source}'s associated stop state.

A \tcode{stop_source} object is disengaged when \exposid{stop-state} is empty.

\pnum

\tcode{stop_source} models

\exposconcept{stoppable-source},

\libconcept{copyable},

\libconcept{equality_comparable}, and

\libconcept{swappable}.

\rSec3[stopsource.cons]{Constructors, copy, and assignment}

\indexlibraryctor{stop_source}%

\begin{itemdecl}

stop_source();

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Initializes \exposid{stop-state} with a pointer to a new stop state.

\pnum

\ensures

\tcode{stop_possible()} is \tcode{true}

and \tcode{stop_requested()} is \tcode{false}.

\pnum

\throws

\tcode{bad_alloc} if memory cannot be allocated for the stop state.

\end{itemdescr}

\rSec3[stopsource.mem]{Member functions}

\indexlibrarymember{swap}{stop_source}%

\begin{itemdecl}

void swap(stop_source& rhs) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\effects

Equivalent to:

\begin{codeblock}

@\exposid{stop-state}@.swap(rhs.@\exposid{stop-state}@);

\end{codeblock}

\end{itemdescr}

\indexlibrarymember{get_token}{stop_source}%

\begin{itemdecl}

stop_token get_token() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum

\returns

\tcode{stop_token()} if \tcode{stop_possible()} is \tcode{false};

otherwise a new associated \tcode{stop_token} object;

i.e., its \exposid{stop-state} member is equal to

the \exposid{stop-state} member of \tcode{*this}.

\end{itemdescr}

\indexlibrarymember{stop_possible}{stop_source}%

\begin{itemdecl}

bool stop_possible() const noexcept;

\end{itemdecl}