\rSec0[thread]{Thread support library}

\rSec1[thread.general]{General}

The following subclauses describe components to create and manage

threads~(\ref{intro.multithread}), perform mutual exclusion, and communicate conditions

and values

between threads, as summarized in Table~\ref{tab:thread.lib.summary}.

\begin{libsumtab}{Thread support library summary}{tab:thread.lib.summary}

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

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

\ref{thread.mutex} & Mutual exclusion & \tcode{<mutex>} \\

& & \tcode{<shared_mutex>} \\ \rowsep

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

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

\end{libsumtab}

\rSec1[thread.req]{Requirements}

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

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

requirements.

If a template parameter is named \tcode{Predicate}, \tcode{operator()} applied to

the template argument shall return a value that is convertible to \tcode{bool}.

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

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

\tcode{system_error}~(\ref{syserr.syserr}). Such exceptions shall be 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 shall be 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}~(\ref{syserr}) and an exception

of type \tcode{system_error} is thrown.

\end{example}

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

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

element.

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

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}

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}.

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.

The member 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.\footnote{All

implementations for which standard time units are meaningful must necessarily

have a steady clock within their hardware implementation.} Given a duration

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

The member 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}

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. \begin{note} This specification may result in the total

duration of the wait decreasing when measured against a steady clock. \end{note}

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

time $C_n >= C_t$, i.e. waking at $C_t + D_i + D_m$. \begin{note} When the clock is adjusted

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

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

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

\end{note}

\end{itemize}

An implementation shall return 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. \begin{note} Implementations

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

\end{note}

\begin{note} If the clock is not synchronized with a steady clock, e.g., a CPU time clock, these

timeouts might not provide useful functionality. \end{note}

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}.

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

\tcode{TrivialClock} requirements (\ref{time.clock.req}).

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 \tcode{Lockable} types}

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

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 may 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.

\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}

The standard library templates \tcode{unique_lock}~(\ref{thread.lock.unique}),

\tcode{shared_lock}~(\ref{thread.lock.shared}),

\tcode{scoped_lock}~(\ref{thread.lock.scoped}),

\tcode{lock_guard}~(\ref{thread.lock.guard}), \tcode{lock},

\tcode{try_lock}~(\ref{thread.lock.algorithm}), and

\tcode{condition_variable_any}~(\ref{thread.condition.condvarany}) all operate on user-supplied

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

and the \tcode{TimedLockable} 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 may entail are not part

of these requirements. \end{note}

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

A type \tcode{L} meets the \tcode{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}

\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}

\requires The current execution agent shall hold a lock on \tcode{m}.

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

\throws Nothing.

\end{itemdescr}

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

A type \tcode{L} meets the \tcode{Lockable} requirements if it meets the \tcode{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}

\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.

\returntype \tcode{bool}.

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

\end{itemdescr}

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

A type \tcode{L} meets the \tcode{TimedLockable} requirements if it meets the \tcode{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 an

instantiation of \tcode{duration}~(\ref{time.duration}), and \tcode{abs_time} denotes a value

of an instantiation of \tcode{time_point}~(\ref{time.point})).

\begin{itemdecl}

m.try_lock_for(rel_time)

\end{itemdecl}

\begin{itemdescr}

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

timeout~(\ref{thread.req.timing}) specified by \tcode{rel_time}. The function shall 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 shall not have been

acquired for the current execution agent.

\returntype \tcode{bool}.

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

\end{itemdescr}

\begin{itemdecl}

m.try_lock_until(abs_time)

\end{itemdecl}

\begin{itemdescr}

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

timeout~(\ref{thread.req.timing}) specified by \tcode{abs_time}. The function shall 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 shall not have been acquired

for the current execution agent.

\returntype \tcode{bool}.

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

\end{itemdescr}

\rSec2[thread.decaycopy]{\tcode{decay_copy}}

In several places in this Clause the operation

\indextext{DECAY_COPY@\tcode{\placeholder{DECAY_COPY}}}%

\indexlibrary{DECAY_COPY@\tcode{\placeholder{DECAY_COPY}}}%

{\tcode{\placeholdernc{DECAY_COPY}(x)}} is used. All

such uses mean call the function \tcode{decay_copy(x)} and use the

result, where \tcode{decay_copy} is defined as follows:

\begin{codeblock}

template <class T> decay_t<T> decay_copy(T&& v)

{ return std::forward<T>(v); }

\end{codeblock}

\rSec1[thread.threads]{Threads}

\ref{thread.threads} describes components that can be used to create and manage threads.

\begin{note} These threads are intended to map one-to-one with operating system threads.

\end{note}

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

\indextext{\idxhdr{thread}}%

\indexlibrary{\idxhdr{thread}}%

\begin{codeblock}

namespace std {

class thread;

void swap(thread& x, thread& y) noexcept;

namespace this_thread {

thread::id get_id() noexcept;

void yield() noexcept;

template <class Clock, class Duration>

void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);

template <class Rep, class Period>

void sleep_for(const chrono::duration<Rep, Period>& rel_time);

}

}

\end{codeblock}

\rSec2[thread.thread.class]{Class \tcode{thread}}

The class \tcode{thread} provides a mechanism to create a new thread of execution, to join with

a thread (i.e., wait for a thread to complete), and to perform other operations that manage and

query the state of a thread. A \tcode{thread} object uniquely represents a particular thread of

execution. That representation may be transferred to other \tcode{thread} objects in such a way

that no two \tcode{thread} objects simultaneously represent the same thread of execution. A

thread of execution is \term{detached} when no \tcode{thread} object represents that thread.

Objects of class \tcode{thread} can be in a state that does not represent a thread of

execution. \begin{note} A \tcode{thread} object does not represent a thread of execution after

default construction, after being moved from, or after a successful call to \tcode{detach} or

\tcode{join}. \end{note}

\indexlibrary{\idxcode{thread}}%

\begin{codeblock}

namespace std {

class thread {

public:

// types:

class id;

using native_handle_type = @\impdef@; // See~\ref{thread.req.native}

// construct/copy/destroy:

thread() noexcept;

template <class F, class... Args> explicit thread(F&& f, Args&&... args);

~thread();

thread(const thread&) = delete;

thread(thread&&) noexcept;

thread& operator=(const thread&) = delete;

thread& operator=(thread&&) noexcept;

// members:

void swap(thread&) noexcept;

bool joinable() const noexcept;

void join();

void detach();

id get_id() const noexcept;

native_handle_type native_handle(); // See~\ref{thread.req.native}

// static members:

static unsigned hardware_concurrency() noexcept;

};

}

\end{codeblock}

\rSec3[thread.thread.id]{Class \tcode{thread::id}}

\indexlibrary{\idxcode{thread::id}}%

\indexlibrary{\idxcode{thread}!\idxcode{id}}%

\begin{codeblock}

namespace std {

class thread::id {

public:

id() noexcept;

};

bool operator==(thread::id x, thread::id y) noexcept;

bool operator!=(thread::id x, thread::id y) noexcept;

bool operator<(thread::id x, thread::id y) noexcept;

bool operator<=(thread::id x, thread::id y) noexcept;

bool operator>(thread::id x, thread::id y) noexcept;

bool operator>=(thread::id x, thread::id y) noexcept;

template<class charT, class traits>

basic_ostream<charT, traits>&

operator<< (basic_ostream<charT, traits>& out, thread::id id);

// Hash support

template <class T> struct hash;

template <> struct hash<thread::id>;

}

\end{codeblock}

\pnum An object of type \tcode{thread::id} provides a unique identifier for

each thread of execution and a single distinct value for all \tcode{thread}

objects that do not represent a thread of

execution~(\ref{thread.thread.class}). Each thread of execution has an

associated \tcode{thread::id} object that is not equal to the

\tcode{thread::id} object of any other thread of execution and that is not

equal to the \tcode{thread::id} object of any \tcode{thread} object that

does not represent threads of execution.

\tcode{thread::id} shall be a trivially copyable class (Clause~\ref{class}).

The library may reuse the value of a \tcode{thread::id} of a terminated thread that can no longer be joined.

\begin{note} Relational operators allow \tcode{thread::id} objects to be used as

keys in associative containers. \end{note}

\indexlibrary{\idxcode{thread::id}!constructor}%

\begin{itemdecl}

id() noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\effects Constructs an object of type \tcode{id}.

\pnum\postconditions The constructed object does not represent a thread of execution.

\end{itemdescr}

\indexlibrarymember{operator==}{thread::id}%

\begin{itemdecl}

bool operator==(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\returns \tcode{true} only if \tcode{x} and \tcode{y} represent the same

thread of execution or neither \tcode{x} nor \tcode{y} represents a thread of

execution.

\end{itemdescr}

\indexlibrarymember{operator"!=}{thread::id}%

\begin{itemdecl}

bool operator!=(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\returns \tcode{!(x == y)}

\end{itemdescr}

\indexlibrarymember{operator<}{thread::id}%

\begin{itemdecl}

bool operator<(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns A value such that \tcode{operator<} is a total ordering as described in~\ref{alg.sorting}.

\end{itemdescr}

\indexlibrarymember{operator<=}{thread::id}%

\begin{itemdecl}

bool operator<=(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns \tcode{!(y < x)}.

\end{itemdescr}

\indexlibrarymember{operator>}{thread::id}%

\begin{itemdecl}

bool operator>(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\returns \tcode{y < x}.

\end{itemdescr}

\indexlibrarymember{operator>=}{thread::id}%

\begin{itemdecl}

bool operator>=(thread::id x, thread::id y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\returns \tcode{!(x < y)}.

\end{itemdescr}

\indexlibrarymember{operator<<}{thread::id}%

\begin{itemdecl}

template<class charT, class traits>

basic_ostream<charT, traits>&

operator<< (basic_ostream<charT, traits>& out, thread::id id);

\end{itemdecl}

\begin{itemdescr}

\pnum\effects Inserts an unspecified text representation of \tcode{id} into

\tcode{out}. For two objects of type \tcode{thread::id} \tcode{x} and \tcode{y},

if \tcode{x == y} the \tcode{thread::id} objects shall have the same text

representation and if \tcode{x != y} the \tcode{thread::id} objects shall have

distinct text representations.

\pnum\returns \tcode{out}.

\end{itemdescr}

\indexlibrary{\idxcode{hash}!\idxcode{thread::id}}%

\begin{itemdecl}

template <> struct hash<thread::id>;

\end{itemdecl}

\begin{itemdescr}

\pnum The specialization is enabled~(\ref{unord.hash}).

\end{itemdescr}

\rSec3[thread.thread.constr]{\tcode{thread} constructors}

\indexlibrary{\idxcode{thread}!constructor}%

\begin{itemdecl}

thread() noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\effects Constructs a \tcode{thread} object that does not represent a thread of execution.

\pnum\postconditions \tcode{get_id() == id()}.

\end{itemdescr}

\indexlibrary{\idxcode{thread}!constructor}%

\begin{itemdecl}

template <class F, class... Args> explicit thread(F&& f, Args&&... args);

\end{itemdecl}

\begin{itemdescr}

\requires\ \tcode{F} and each \tcode{Ti} in \tcode{Args} shall satisfy the

\tcode{MoveConstructible} requirements.

\tcode{%

\placeholdernc{INVOKE}(\brk{}%

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<F>(f)),

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<Args>(\brk{}args))...)}~(\ref{func.require}) shall be

a va\-lid expression.

This constructor shall not participate in overload resolution if \tcode{decay_t<F>}

is the same type as \tcode{std::thread}.

\effects\ Constructs an object of type \tcode{thread}. The new thread of execution executes

\tcode{%

\placeholdernc{INVOKE}(\brk{}%

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<F>(f)),

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<Args>(\brk{}args))...)} with the calls to

\tcode{\placeholder{DECAY_COPY}} being evaluated in the constructing thread. Any return value from this invocation

is ignored. \begin{note} This implies that any exceptions not thrown from the invocation of the copy

of \tcode{f} will be thrown in the constructing thread, not the new thread. \end{note} If the

invocation of

\tcode{%

\placeholdernc{INVOKE}(\brk{}%

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<F>(f)),

\placeholdernc{DECAY_COPY}(\brk{}%

std::forward<Args>(args))...)}

termi\-nates with an uncaught exception, \tcode{terminate} shall be called.

\pnum\sync The completion of the invocation of the constructor

synchronizes with the beginning of the invocation of the copy of \tcode{f}.

\pnum\postconditions \tcode{get_id() != id()}. \tcode{*this} represents the newly started thread.

\pnum\throws \tcode{system_error} if unable to start the new thread.

\begin{itemize}

\item \tcode{resource_unavailable_try_again} --- the system lacked the necessary

resources to create another thread, or the system-imposed limit on the number of

threads in a process would be exceeded.

\end{itemize}

\end{itemdescr}

\indexlibrary{\idxcode{thread}!constructor}%

\begin{itemdecl}

thread(thread&& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

\effects Constructs an object of type \tcode{thread} from \tcode{x}, and sets

\tcode{x} to a default constructed state.

\postconditions \tcode{x.get_id() == id()} and \tcode{get_id()} returns the

value of \tcode{x.get_id()} prior to the start of construction.

\end{itemdescr}

\rSec3[thread.thread.destr]{\tcode{thread} destructor}

\indexlibrary{\idxcode{thread}!destructor}%

\begin{itemdecl}

~thread();

\end{itemdecl}

\begin{itemdescr}

If \tcode{joinable()}, calls \tcode{terminate()}. Otherwise, has no effects.

\begin{note} Either implicitly detaching or joining a \tcode{joinable()} thread in its

destructor could result in difficult to debug correctness (for detach) or performance

(for join) bugs encountered only when an exception is thrown. Thus the programmer must

ensure that the destructor is never executed while the thread is still joinable.

\end{note}

\end{itemdescr}

\rSec3[thread.thread.assign]{\tcode{thread} assignment}

\indexlibrarymember{operator=}{thread}%

\begin{itemdecl}

thread& operator=(thread&& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

\effects If \tcode{joinable()}, calls \tcode{terminate()}. Otherwise, assigns the

state of \tcode{x} to \tcode{*this} and sets \tcode{x} to a default constructed state.

\postconditions \tcode{x.get_id() == id()} and \tcode{get_id()} returns the value of

\tcode{x.get_id()} prior to the assignment.

\returns \tcode{*this}.

\end{itemdescr}

\rSec3[thread.thread.member]{\tcode{thread} members}

\indexlibrarymember{swap}{thread}%

\begin{itemdecl}

void swap(thread& x) noexcept;

\end{itemdecl}

\begin{itemdescr}

\effects Swaps the state of \tcode{*this} and \tcode{x}.

\end{itemdescr}

\indexlibrarymember{joinable}{thread}%

\begin{itemdecl}

bool joinable() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns \tcode{get_id() != id()}.

\end{itemdescr}

\indexlibrarymember{join}{thread}%

\begin{itemdecl}

void join();

\end{itemdecl}

\begin{itemdescr}

\effects\ Blocks until the thread represented by \tcode{*this} has completed.

\sync The completion of the thread represented by \tcode{*this} synchronizes with~(\ref{intro.multithread})

the corresponding successful

\tcode{join()} return. \begin{note} Operations on

\tcode{*this} are not synchronized. \end{note}

\postconditions The thread represented by \tcode{*this} has completed. \tcode{get_id() == id()}.

\throws \tcode{system_error} when

an exception is required~(\ref{thread.req.exception}).

\begin{itemize}

\item \tcode{resource_deadlock_would_occur} --- if deadlock is detected or

\tcode{get_id() == this_thread::\brk{}get_id()}.

\item \tcode{no_such_process} --- if the thread is not valid.

\item \tcode{invalid_argument} --- if the thread is not joinable.

\end{itemize}

\end{itemdescr}

\indexlibrarymember{detach}{thread}%

\begin{itemdecl}

void detach();

\end{itemdecl}

\begin{itemdescr}

\effects The thread represented by \tcode{*this} continues execution without the calling thread

blocking. When \tcode{detach()} returns, \tcode{*this} no longer represents the possibly continuing

thread of execution. When the thread previously represented by \tcode{*this} ends execution, the

implementation shall release any owned resources.

\pnum\postconditions \tcode{get_id() == id()}.

\pnum\throws \tcode{system_error} when

an exception is required~(\ref{thread.req.exception}).

\pnum \errors

\begin{itemize}

\item \tcode{no_such_process} --- if the thread is not valid.

\item \tcode{invalid_argument} --- if the thread is not joinable.

\end{itemize}

\end{itemdescr}

\indexlibrarymember{get_id}{thread}%

\begin{itemdecl}

id get_id() const noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns A default constructed \tcode{id} object if \tcode{*this} does not represent a thread,

otherwise \tcode{this_thread::get_id()} for the thread of execution represented by

\tcode{*this}.

\end{itemdescr}

\rSec3[thread.thread.static]{\tcode{thread} static members}

\indexlibrarymember{hardware_concurrency}{thread}%

\begin{itemdecl}

unsigned hardware_concurrency() noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns The number of hardware thread contexts. \begin{note} This value should

only be considered to be a hint. \end{note} If this value is not computable or

well defined an implementation should return 0.

\end{itemdescr}

\rSec3[thread.thread.algorithm]{\tcode{thread} specialized algorithms}

\indexlibrarymember{swap}{thread}%

\begin{itemdecl}

void swap(thread& x, thread& y) noexcept;

\end{itemdecl}

\begin{itemdescr}

\pnum\effects As if by \tcode{x.swap(y)}.

\end{itemdescr}

\rSec2[thread.thread.this]{Namespace \tcode{this_thread}}

\begin{codeblock}

namespace std::this_thread {

thread::id get_id() noexcept;

void yield() noexcept;

template <class Clock, class Duration>

void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);

template <class Rep, class Period>

void sleep_for(const chrono::duration<Rep, Period>& rel_time);

}

\end{codeblock}

\indexlibrarymember{get_id}{this_thread}%

\begin{itemdecl}

thread::id this_thread::get_id() noexcept;

\end{itemdecl}

\begin{itemdescr}

\returns An object of type \tcode{thread::id} that uniquely identifies the current thread of

execution. No other thread of execution shall have this id and this thread of execution shall

always have this id. The object returned shall not compare equal to a default constructed

\tcode{thread::id}.

\end{itemdescr}

\indexlibrarymember{yield}{this_thread}%

\begin{itemdecl}

void this_thread::yield() noexcept;

\end{itemdecl}

\begin{itemdescr}

\effects Offers the implementation the opportunity to reschedule.

\sync None.

\end{itemdescr}

\indexlibrarymember{sleep_until}{this_thread}%

\begin{itemdecl}

template <class Clock, class Duration>

void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);

\end{itemdecl}

\begin{itemdescr}

\effects Blocks the calling thread for the absolute timeout~(\ref{thread.req.timing}) specified

by \tcode{abs_time}.

\sync None.

\throws Timeout-related exceptions~(\ref{thread.req.timing}).

\end{itemdescr}

\indexlibrarymember{sleep_for}{this_thread}%

\begin{itemdecl}

template <class Rep, class Period>

void sleep_for(const chrono::duration<Rep, Period>& rel_time);

\end{itemdecl}

\begin{itemdescr}

\effects Blocks the calling thread for the relative timeout~(\ref{thread.req.timing}) specified

by \tcode{rel_time}.

\sync None.

\throws Timeout-related exceptions~(\ref{thread.req.timing}).

\end{itemdescr}

\rSec1[thread.mutex]{Mutual exclusion}

This section provides mechanisms for mutual exclusion: mutexes, locks, and call

once. These mechanisms ease the production of race-free

programs~(\ref{intro.multithread}).

\rSec2[mutex.syn]{Header \tcode{<mutex>} synopsis}

\indextext{\idxhdr{mutex}}%

\indexlibrary{\idxhdr{mutex}}%

\begin{codeblock}

namespace std {

class mutex;

class recursive_mutex;

class timed_mutex;

class recursive_timed_mutex;

struct defer_lock_t { explicit defer_lock_t() = default; };

struct try_to_lock_t { explicit try_to_lock_t() = default; };

struct adopt_lock_t { explicit adopt_lock_t() = default; };

inline constexpr defer_lock_t defer_lock { };

inline constexpr try_to_lock_t try_to_lock { };

inline constexpr adopt_lock_t adopt_lock { };

template <class Mutex> class lock_guard;

template <class... MutexTypes> class scoped_lock;

template <class Mutex> class unique_lock;

template <class Mutex>

void swap(unique_lock<Mutex>& x, unique_lock<Mutex>& y) noexcept;

template <class L1, class L2, class... L3> int try_lock(L1&, L2&, L3&...);

template <class L1, class L2, class... L3> void lock(L1&, L2&, L3&...);

struct once_flag;

template<class Callable, class... Args>

void call_once(once_flag& flag, Callable&& func, Args&&... args);

}

\end{codeblock}

\rSec2[shared_mutex.syn]{Header \tcode{<shared_mutex>} synopsis}

\indextext{\idxhdr{shared_mutex}}%

\indexlibrary{\idxhdr{shared_mutex}}%

\begin{codeblock}

namespace std {

class shared_mutex;

class shared_timed_mutex;

template <class Mutex> class shared_lock;

template <class Mutex>

void swap(shared_lock<Mutex>& x, shared_lock<Mutex>& y) noexcept;

}

\end{codeblock}

\rSec2[thread.mutex.requirements]{Mutex requirements}

\rSec3[thread.mutex.requirements.general]{In general}

A mutex object facilitates protection against data races and allows safe synchronization of

data between execution agents~(\ref{thread.req.lockable}).

An execution agent \term{owns} a mutex from the time it successfully calls one of the

lock functions until it calls unlock. Mutexes can be either recursive or non-recursive, and can

grant simultaneous ownership to one or many execution agents. Both

recursive and non-recursive mutexes are supplied.

\rSec3[thread.mutex.requirements.mutex]{Mutex types}

The \defn{mutex types} are the standard library types \tcode{mutex},

\tcode{recursive_mutex}, \tcode{timed_mutex}, \tcode{recursive_timed_mutex},

\tcode{shared_mutex}, and \tcode{shared_timed_mutex}.

They shall meet the requirements set out in this section. In this description, \tcode{m}

denotes an object of a mutex type.

The mutex types shall meet the \tcode{Lockable} requirements~(\ref{thread.req.lockable.req}).

The mutex types shall be \tcode{DefaultConstructible} and \tcode{Destructible}. If

initialization of an object of a mutex type fails, an exception of type

\tcode{system_error} shall be thrown. The mutex types shall not be copyable or movable.

The error conditions for error codes, if any, reported by member functions of the mutex types

shall be:

\begin{itemize}

\item \tcode{resource_unavailable_try_again} --- if any native handle type manipulated is not available.

\item \tcode{operation_not_permitted} --- if the thread does not have the

privilege to perform the operation.

\item \tcode{invalid_argument} --- if any native handle type manipulated as part of mutex

construction is incorrect.

\end{itemize}

The implementation shall provide lock and unlock operations, as described below.

For purposes of determining the existence of a data race, these behave as

atomic operations~(\ref{intro.multithread}). The lock and unlock operations on

a single mutex shall appear to occur in a single total order. \begin{note} This

can be viewed as the modification order~(\ref{intro.multithread}) of the

mutex. \end{note}

\begin{note} Construction and

destruction of an object of a mutex type need not be thread-safe; other

synchronization should be used to ensure that mutex objects are initialized

and visible to other threads. \end{note}

The expression \tcode{m.lock()} shall be well-formed and have the following semantics:

\begin{itemdescr}

\requires If \tcode{m} is of type \tcode{mutex}, \tcode{timed_mutex},

\tcode{shared_mutex}, or \tcode{shared_timed_mutex}, the calling

thread does not own the mutex.

\effects Blocks the calling thread until ownership of the mutex can be obtained for the calling thread.

\postconditions The calling thread owns the mutex.

\returntype \tcode{void}.

\sync Prior \tcode{unlock()} operations on the same object shall

\term{synchronize with}~(\ref{intro.multithread}) this operation.

\throws \tcode{system_error} when

an exception is required~(\ref{thread.req.exception}).

\pnum \errors

\begin{itemize}

\item \tcode{operation_not_permitted} --- if the thread does not have the

privilege to perform the operation.

\item \tcode{resource_deadlock_would_occur} --- if the implementation detects

that a deadlock would occur.

\end{itemize}

\end{itemdescr}

The expression \tcode{m.try_lock()} shall be well-formed and have the following semantics:

\begin{itemdescr}

\requires If \tcode{m} is of type \tcode{mutex}, \tcode{timed_mutex},

\tcode{shared_mutex}, or \tcode{shared_timed_mutex}, the calling

thread does not own the mutex.

\effects Attempts to obtain ownership of the mutex for the calling thread without

blocking. If ownership is not obtained, there is no effect and \tcode{try_lock()}

immediately returns. An implementation may fail to obtain the lock even if it is not

held by any other thread. \begin{note} This spurious failure is normally uncommon, but

allows interesting implementations based on a simple

compare and exchange

(Clause~\ref{atomics}). \end{note}

An implementation should ensure that \tcode{try_lock()} does not consistently return \tcode{false}

in the absence of contending mutex acquisitions.

\returntype \tcode{bool}.

\returns \tcode{true} if ownership of the mutex was obtained for the calling

thread, otherwise \tcode{false}.

\sync If \tcode{try_lock()} returns \tcode{true}, prior \tcode{unlock()} operations

on the same object \term{synchronize with}~(\ref{intro.multithread}) this operation.

\begin{note} Since \tcode{lock()} does not synchronize with a failed subsequent

\tcode{try_lock()}, the visibility rules are weak enough that little would be

known about the state after a failure, even in the absence of spurious failures. \end{note}

\throws Nothing.

\end{itemdescr}