<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<title>N2285=07-0145, A Multi-threading Library for Standard C++, Revision 2</title>
	<meta name="generator" content="BBEdit 8.6" />
<style type="text/css" title="text/css">
/* <![CDATA[ */
* { font-family: serif; }
*.code { font-size: 120%; font-family: monospace; font-weight: bolder; }
*.non-code { font-style: italic; font-family: monospace; }
p > span.non-code { font-size: 120%; }
*.link-target { font-weight: bolder; }
*.copyright { font-style: italic; }
h1 { text-align: center; }
div.group { border-bottom: double; padding-bottom: .5em; }
div.subgroup { border-bottom: thin solid; padding-bottom: .5em; }
div.block { border-bottom: thin solid; border-top: thin solid; }
div.menu { padding-top: .5em; padding-bottom: .5em; }
div.menu a { padding-right: .3em; }
div.menu a + a { padding-left: .45em; border-left: thin solid; line-height: 1.3em; }
table.heading { border-collapse: separate; float: right; padding-right: 1em; }
td.descr { padding: 0; text-align: right; font-style: italic; font-weight: bold; }
td.descr:after { content: ":"; }
td.emptydescr { padding: 0; }
td.value { padding: 0; padding-left: 1ex; }
pre { font-family: monospace; }
pre a.code { font-size: 100%; }
pre .decl { font-weight: bolder; font-size: 80%; }
span.reqmt { font-style: italic; }
span.reqmt:after { content: ":" }
/* ]]> */
</style>
</head>
<body>

<div class="group">
<h1>A Multi-threading Library for Standard C++, Revision 2</h1>

<table class="heading">
<tr>
  <td class="descr">Document number</td><td class="value">N2285=07-0145</td>
</tr>
<tr>
  <td class="descr">Date</td><td class="value">2007-05-07</td>
</tr>
<tr>
  <td class="descr">Project</td><td class="value">Programming Language C++</td>
</tr>
<tr>
  <td class="descr">Reference</td><td class="value">ISO/IEC IS 14882:2003(E)</td>
</tr>
<tr>
  <td class="descr">Reply to</td><td class="value">Pete Becker</td>
</tr>
<tr>
  <td class="emptydescr"></td><td class="value">Roundhouse Consulting, Ltd.</td>
</tr>
<tr>
  <td class="emptydescr"></td><td class="value">pete@versatilecoding.com</td>
</tr>
</table>
<p style="clear:both"></p>
</div>

<div class="group menu">
<h2><span id="Table-of-Contents" class="link-target">Table of Contents</span></h2>

<h3>General</h3>
<a href="#Introduction">Introduction</a>
<a href="#Open-Issues">Open Issues</a>

<h3>Threading</h3>
<a href="#Overview">Threading Overview</a>
<a href="#Memory-Visibility">Memory Visibility</a>
<a href="#Condition-Variables">Condition Variables</a>
<a href="#Mutexes">Mutexes</a>
<a href="#Once-Functions">Once Functions</a>
<a href="#Thread-specific-Storage">Thread-specific Storage</a>

<h3>Threading Specifics</h3>
<a href="#Thread-object">The <span class="code">thread</span> Object and the Thread</a>
<a href="#Cooperative-Thread-Cancellation">Cooperative Thread Cancellation</a>
<a href="#Mixing-C-and-Cpp">Mixing C and C++</a>

<h3>Details</h3>
<a href="#C-Interface">C Interface</a>
<a href="#Cpp-Interface">C++ Interface</a>
</div>

<div class="group">
<h2>General</h2>
<h3><span id="Introduction" class="link-target">Introduction</span></h3>

<p>This paper is a revision of N1907=05-0617, <cite>A Multithreading
Library for Standard C++, Revision 1</cite>. It incorporates the
recommendations made in N2184=07-0044, <cite>Thread Launching for
C++0x</cite>. Because of limited time, it undoubtedly does not accurately
reflect the contents of the latter paper.</p>

<p>This paper does not propose wording for the standard. It discusses
the proposed library threading model and documents C and C++
interfaces that support this model. There are ongoing discussions in
the Evolution Working Group of possible core language approaches to some
of the thread support features discussed here, so library support for
thread-specific storage and once functions might not be needed.
If the Library Working Group decides to adopt some or all of the model
proposed in this paper for the C++ standard, writing the appropriate
standards text will be straightforward.
</p>

<h3><span id="Open-Issues" class="link-target">Open Issues</span></h3>

<ul>
<li>Need to be able to unlock mutexes in C++ without exiting block scope
<ul>
<li>Suggested resolution: I may have misunderstood, but it looks like this is
already present. See <a href="#scoped_lock::unlock" class="code">scoped_lock::unlock</a>.</li>
</ul></li>
<li>May want to replace <span class="code">xtime</span> stuff with the new Date/Time stuff.</li>
<li>Mutex locks in the C++ interface provide an <span class="code">operator void*</span> to test
their state. Since we seem to be moving to <span class="code">operator
unspecified-boolean-type</span> for this sort of test, we should probably change
these operators accordingly.</li>
<li>The various functions that wait on condition variables are
<a href="#cancellation-point">cancellation points</a>,
but we may want to be more specific about whether cancellation occurs at the
beginning of the call, on wakeup, or both.</li>
<li>We can write the C interface so that thread handles can't be assigned,
and provide a function to copy a handle which also invalidates the source
of the assignment. This would provide single ownership, just as in C++.
I haven't done this because I think it's not a normal C coding style, but I'm
not dead set against it.</li>
<li>The C interface has one type for mutex variables, while the C++
interface has six. That's an artifact of the Dinkumware implementation. All
the C++ mutex types use the same underlying data structure and a set of
flags to indicate which flavor of mutex is being used. That underlying data
structure is the type used in the C interface. Another approach would be to
provide six distinct type names in C, but not require that they name distinct
types. I haven't thought through the implications of such a change.</li>
<li>The descriptions of the various <span class="code">c_handle</span> functions
and the corresponding C++ constructors don&rsquo;t describe the semantics
correctly. More generally, the interaction between C and C++ needs more work.</li>
</ul>
</div>

<div class="group">
<h2><span id="Threading" class="link-target">Threading</span></h2>

<h3><span id="Overview" class="link-target">Threading Overview</span></h3>

<p>A <span id="intro-thread" class="link-target">thread</span> is a separate flow of execution within an application.
On a multi-processor system threads can execute simultaneously on different processors.
On a single-processor system and on a multi-processor system with fewer available
processors than active threads two or more threads must share a processor.
The details of switching a processor from one thread to another are handled
by the operating system.</p>

<p>This library lets you create and control multiple threads
and synchronize the sharing of data between these threads. It consists of
compatible and complementary interfaces for programming in either C or C++.
The <a href="#C-Interface">C Interface</a> is very similar to the
thread support interface defined in the
the <a href="http://www.unix-systems.org/version3/ieee_std.html">Posix</a> Standard
(also known as <span id="pthreads" class="link-target">pthreads</span>), while the
<a href="#Cpp-Interface">C++ Interface</a> is very similar to the
<a href="http://www.boost.org/libs/thread/doc/index.html" class="code">boost.threads</a>
library for C++.</p>

<p>When a C or C++ program begins execution it runs in a single thread, executing
the <span class="code">main</span> function. The program can create additional threads as needed.
Each thread has its own copy of all <span class="code">auto</span> variables, so <span class="code">auto</span>
values in one thread are independent of <span class="code">auto</span> values in the other threads.
Data with static storage duration is accessible to all threads, so those values are shared.
However, changes to values in shared data often are not immediately visible in other threads.
A multi-threaded application uses condition variables, mutexes, and once functions
to coordinate the use of shared data by its threads, in order to ensure
that shared data is not made inconsistent by simultaneous changes from more than one thread,
that changes to shared data are visible to a thread when needed, and that a thread that
needs data that is being created by another thread can be notified when that data becomes
available.</p>

<h3><span id="Memory-Visibility" class="link-target">Memory Visibility</span></h3>

<p>Changes made by one thread to values in shared data often are not immediately
<span id="intro-visible" class="link-target">visible</span> in other threads.

For example, on a system with two separate processors and two threads running on the
two processors, if the two processors simply
share main memory an attempt by one processor to write data while the other processor
reads the same data could result in the second processor reading a data value that
has only been partially changed by the other processor. In order to avoid this inconsistency
one processor has to lock the other one out until it finishes. This locking is usually done through
the hardware and is known as a <span id="bus-lock" class="link-target">bus lock</span>. Bus locks are unavoidable, but they slow
the processors down. To minimize the effect of this slowdown, multi-processor systems
have separate cache memory for each processor. This cache memory holds a copy of some
of the data in main memory. When a processor writes data it writes to the cache.
Sometime later the changes made to the cache are written to main memory. Because of this delay, the
processors could each have a different value for a data item in their caches, and
those values could be different from the value in main memory.</p>

<p>There are three times at which changes made to memory by one thread are guaranteed
to be visible in another thread:</p>

<ul>
<li>when a thread is created, changes to memory made by the creating thread
prior to creating the new thread are visible to the new thread</li>

<li>when a thread locks a mutex, changes made by other threads prior to unlocking
the same mutex are visible to the locking thread</li>

<li>when a thread joins another thread, changes made by the joined thread prior to
exiting are visible to the joining thread</li>
</ul>

<p>In practice this means that:</p>

<ul>
<li>constant data that is initialized before a thread starts can be accessed in
the thread without further precautions</li>
<li>modifiable data should be accessed only from code controlled by
a mutex, both in threads that modify the data and in threads that use the
data</li>
</ul>

<p>Note, however, that locking a mutex to prevent modification of shared data while
it is being read also prevents other threads from locking the mutex in order to read the data.
Such critical sections should be kept as short as possible to avoid blocking other
threads any longer than necessary.</p>

<h3><span id="Condition-Variables" class="link-target">Condition Variables</span></h3>

<p>A <span id="intro-condition-variable" class="link-target">condition variable</span> is used
by a thread to wait until another thread notifies it that a condition has become
true. Code that waits for a condition variable must also use a
<a href="#intro-mutex">mutex</a>; before calling any of the functions that
wait for the condition variable
the calling thread must lock the mutex, and when the called
function returns the mutex will be locked. During the time that a
thread is blocked waiting for the condition to become true the mutex
is not locked.</p>

<p><span id="intro-spurious-wakeups" class="link-target">Spurious wakeups</span> occur
when threads waiting for condition variables become unblocked
without appropriate notifications. Code that waits for a condition to
become true should explicitly check that condition when returning from
a wait function to recognize such spurious wakeups.
This is usually done with a loop:</p>

<pre>while (condition is false)
    wait for condition variable;</pre>

<p>The condition variable functions use a mutex internally; when a thread returns
from a wait function any changes made to memory by threads that called a wait
function or a notify function before the return will be
<a href="#intro-visible">visible</a> to the caller.</p>

<h3><span id="Mutexes" class="link-target">Mutexes</span></h3>

<p>A <span id="intro-mutex" class="link-target">mutex</span> is used to insure that only one
thread executes a region of code, known as a critical section, at any one time.
On entry into the critical section the code locks the mutex; if no other thread
holds the mutex the lock operation succeeds and the calling thread holds the mutex.
On exit from the critical section the code unlocks the mutex. If another thread
holds the mutex when a thread tries to lock it the thread that tried to lock the mutex
blocks until the mutex is unlocked. When more than one thread is blocked waiting for
the mutex an unlock releases one of the blocked threads.</p>

<p>A mutex can be <span id="intro-recursive" class="link-target">recursive</span>
or <span id="intro-non-recursive" class="link-target">non-recursive</span>. When a thread that already holds
a recursive mutex attempts to lock it again the thread does not block. The
thread must unlock the mutex as many times as it locked it before any other
thread will be permitted to lock the mutex. When a thread that already holds
a non-recursive mutex attempts to lock it again the thread will block. Since
the thread cannot then unlock the mutex, the result is a deadlock. Non-recursive
mutexes are usually smaller and faster than recursive mutexes, so a properly written
program that uses non-recursive mutexes can be faster than one that uses
recursive mutexes.</p>

<p>A mutex supports <span id="intro-test-and-return" class="link-target">test and return</span>
if it provides a lock call that does not block if the mutex is already locked. Such a lock
call returns a value that indicates whether the mutex was locked as a result of the call.</p>

<p>A mutex supports <span id="intro-timeout" class="link-target">timeout</span>
if it provides a lock call that blocks until no later than a specified time
waiting for the mutex to be unlocked. Such a lock call returns a value that indicates
whether the mutex was locked as a result of the call.</p>

<h3><span id="Once-Functions" class="link-target">Once Functions</span></h3>

<p>A <span id="intro-once-function" class="link-target">once function</span> is a function that should only be
called once during a program's execution. Once functions are typically used to initialize
data that is shared between threads: the first thread that needs the data
initializes it by calling the once function, and later threads that need the data do not call
the once function. Each once function should have an associated
once flag, statically initialized to indicate that the function has not been called.
Code that needs to insure that the once function has been called calls
<a href="#call_once" class="code">call_once</a>, passing the flag and the address
of the once function. The code in <span class="code">call_once</span> atomically checks the
flag, and if the flag indicates that the function has not been called, calls the
once function and sets the flag to indicate that the function has been called.</p>

<p>The function <span class="code">call_once</span> uses a mutex internally; when it returns
any changes made to memory by the once function will be
<a href="#intro-visible">visible</a> to the caller.</p>

<h3><span id="Thread-specific-Storage" class="link-target">Thread-specific Storage</span></h3>

<p>Thread-specific storage is global data that can hold a distinct value for each
thread that uses it. This permits functions executing in a single thread to share
data without interfering with the data shared by the same functions when executing
in other threads.</p>
</div>

<div class="group">
<h2>Threading Specifics</h2>

<h3 id="Thread-object">The <span class="code">thread</span> Object and the Thread</h3>

<p>Every program begins execution in its main thread. A new thread can be started
from any thread by creating an object of type
<a href="#thread" class="code">thread</a>, passing a
callable object <span class="code">exec</span> to the <span class="code">thread</span>&rsquo;s constructor.
The new thread will begin execution by a call to <span class="code">exec()</span>. Various
operations that affect the state of the thread can be done through member functions
called on the <span class="code">thread</span> object.</p>

<p>A <span class="code">thread</span> object can be moved to another <span class="code">thread</span> object,
but it can&rsquo;t be copied. This means that there can never be more than one
<span class="code">thread</span> object that manages a particular thread.</p>

<p>A thread can be detached from its <span class="code">thread</span> object <span class="code">thr</span>
by calling <span class="code">thr.detach()</span>. After this call, <span class="code">thr</span> no longer
manages the thread that it used to manage (and, since <span class="code">thr</span> was the
only <span class="code">thread</span> object that managed the thread, there is now no
<span class="code">thread</span> object that manages the thread). When the thread terminates, it is
the responsibility of the underlying threading system to clean up any resources
allocated to the thread.</p>

<p>A thread can be <a href="#thread::join">joined</a> if it has not been detached
and it has not previously been joined. When a thread joins another thread, the
joining thread will block until the joined thread terminates.</p>

<h3><span id="Cooperative-Thread-Cancellation" class="link-target">Cooperative Thread Cancellation</span></h3>

<p>A thread can be <span class="link-target" id="cancelled">cancelled</span> by throwing an exception object
of type <a href="#thread_canceled" class="code">thread_canceled</a> or of a
type derived from <span class="code">thread_canceled</span>. A handler for this exception is
not required to rethrow it. Thus, cancellation can be canceled.</p>

<p>A program can request that a thread be <a href="#cancelled">cancelled</a>
by calling <a href="#thread::cancel" class="code">cancel()</a>
on the <span class="code">thread</span> object
that manages the target thread. Calling <span class="code">cancel()</span>
notifies the target thread that cancellation has been requested. It does
not force cancellation to occur.</p>

<p>A thread can check whether another thread has requested that it be
cancelled by calling <a href="#cancellation_requested"
class="code">cancellation_requested()</a>.</p>

<p>A thread can disable cancellation by creating an object of type
<a href="#disable_cancellation" class="code">disable_cancellation</a>.
When the object is destroyed, its destructor enables cancellation if
cancellation was enabled when the object was constructed.</p>

<p>A thread can temporarily restore its cancellation state by creating
an object of type
<a href="#restore_cancellation" class="code">restore_cancellation</a>. The object's
constructor takes an object of type
<a href="#disable_cancellation" class="code">disable_cancellation</a>, and sets
the thread's cancellation state to the state it was in at the time that the
argument was constructed. The destructor of the <span class="code">restore_cancellation</span>
object returns the thread's cancellation state to the state it was in when
that object was constructed.</p>

<p>When a thread calls a function that is a <span class="link-target"
id="cancellation-point">cancellation point</span>, if cancellation is not
disabled in that thread and a request for cancellation has been made to that
thread and that request has not been handled, the thread will be
<a href="#cancelled">cancelled</a>. The following functions are
cancellation points:</p>

<ul>
<li><a href="#cancellation_point" class="code">cancellation_point</a></li>
<li><a href="#sleep" class="code">sleep</a></li>
<li><a href="#thread::join" class="code">thread::join</a></li>
<li><a href="#thread::operator-call" class="code">thread::operator()</a></li>
<li><a href="#condition::wait" class="code">condition::wait</a></li>
<li><a href="#condition::timed_wait" class="code">condition::timed_wait</a></li>
</ul>

<p>The application's main thread starts in a non-cancellable state.
Consequently, no combination of <span class="code">disable_cancellation</span>
and <span class="code">restore_cancellation</span> objects can put it into a
cancellable state. Since it has no associated
<span class="code">thread</span> object, no other thread can request
cancellation of the main thread.</p>

<h3><span id="Mixing-C-and-Cpp" class="link-target">Mixing C and C++</span></h3>

<p>C++ condition variables, mutexes, thread-specific pointers,
and thread objects all have a member function
named <span class="code">c_handle</span> that returns an object of the corresponding
C type (<span class="code">cnd_t</span>,
<span class="code">mtx_t</span>,
<span class="code">tss_t</span>, and
<span class="code">thrd_t</span>).
Each of those C++ types also has a constructor
that takes an argument of the corresponding C type. [need to sort out move/copy
semantics for the four underlying types]
</p>

</div>

<div class="group">
<h2>Details</h2>

<h3><span id="C-Interface" class="link-target">C Interface</span></h3>

<div class="block menu">
<a href="#call_once" class="code">call_once</a>
<a href="#cnd_broadcast" class="code">cnd_broadcast</a>
<a href="#cnd_destroy" class="code">cnd_destroy</a>
<a href="#cnd_init" class="code">cnd_init</a>
<a href="#cnd_signal" class="code">cnd_signal</a>
<a href="#cnd_t" class="code">cnd_t</a>
<a href="#cnd_timedwait" class="code">cnd_timedwait</a>
<a href="#cnd_wait" class="code">cnd_wait</a>
<a href="#mtx_destroy" class="code">mtx_destroy</a>
<a href="#mtx_init" class="code">mtx_init</a>
<a href="#mtx_lock" class="code">mtx_lock</a>
<a href="#mtx_plain" class="code">mtx_plain</a>
<a href="#mtx_recursive" class="code">mtx_recursive</a>
<a href="#mtx_t" class="code">mtx_t</a>
<a href="#mtx_timed" class="code">mtx_timed</a>
<a href="#mtx_timedlock" class="code">mtx_timedlock</a>
<a href="#mtx_try" class="code">mtx_try</a>
<a href="#mtx_trylock" class="code">mtx_trylock</a>
<a href="#mtx_unlock" class="code">mtx_unlock</a>
<a href="#once_flag" class="code">once_flag</a>
<a href="#ONCE_FLAG_INIT" class="code">ONCE_FLAG_INIT</a>
<a href="#thrd_busy" class="code">thrd_busy</a>
<a href="#thrd_create" class="code">thrd_create</a>
<a href="#thrd_current" class="code">thrd_current</a>
<a href="#thrd_detach" class="code">thrd_detach</a>
<a href="#thrd_equal" class="code">thrd_equal</a>
<a href="#thrd_error" class="code">thrd_error</a>
<a href="#thrd_exit" class="code">thrd_exit</a>
<a href="#thrd_join" class="code">thrd_join</a>
<a href="#thrd_nomem" class="code">thrd_nomem</a>
<a href="#thrd_sleep" class="code">thrd_sleep</a>
<a href="#thrd_start_t" class="code">thrd_start_t</a>
<a href="#thrd_success" class="code">thrd_success</a>
<a href="#thrd_t" class="code">thrd_t</a>
<a href="#thrd_timedout" class="code">thrd_timedout</a>
<a href="#thrd_yield" class="code">thrd_yield</a>
<a href="#TIME_UTC" class="code">TIME_UTC</a>
<a href="#tss_create" class="code">tss_create</a>
<a href="#TSS_DTOR_ITERATIONS" class="code">TSS_DTOR_ITERATIONS</a>
<a href="#tss_delete" class="code">tss_delete</a>
<a href="#tss_dtor_t" class="code">tss_dtor_t</a>
<a href="#tss_get" class="code">tss_get</a>
<a href="#tss_set" class="code">tss_set</a>
<a href="#tss_t" class="code">tss_t</a>
<a href="#xtime" class="code">xtime</a>
<a href="#xtime_get" class="code">xtime_get</a>
</div>

<h4><span id="Return-Values" class="link-target">Return Values</span></h4>

<p>Most of the functions
<span id="return-value" class="link-target">return a value</span> of type <span class="code">int</span> that indicates whether
the function succeeded. The values are as follows:</p>

<ul>
<li><a href="#thrd_success" class="code">thrd_success</a>
-- the function succeeded</li>
<li><a href="#thrd_nomem" class="code">thrd_nomem</a>
-- the function was unable to allocate memory</li>
<li><a href="#thrd_timedout" class="code">thrd_timedout</a>
-- the time specified in a timed wait function was reached without
acquiring the requested resource</li>
<li><a href="#thrd_busy" class="code">thrd_busy</a>
-- a resource requested by a
<a href="#intro-test-and-return">test and return</a> function is already in use</li>
<li><a href="#thrd_error" class="code">thrd_error</a>
-- some other error occurred</li>
</ul>

<h4>Threads</h4>

<p>Use the functions and types with the prefix <span class="code">thrd_</span> to manage
<a href="#intro-thread">threads</a>. Each thread has an identifier of type
<a href="#thrd_t" class="code">thrd_t</a>, which is passed as an argument
to the functions that manage specific threads. Each thread begins execution in a
function of type <a href="#thrd_start_t" class="code">thrd_start_t</a>.
To create a new thread call the function
<a href="#thrd_create" class="code">thrd_create</a> with the address of the
thread identifier, the address of the thread function, and an argument to be passed
to the thread function. The thread ends when it returns from the thread function or when
it calls <a href="#thrd_exit" class="code">thrd_exit</a>. For convenience, a thread
can provide a <span id="result-code" class="link-target">result code</span>
of type <span class="code">int</span> when it ends, either by returning the
code from the thread function or by passing the code to <span class="code">thrd_exit</span>.
To block a thread until another thread ends call
<a href="#thrd_join" class="code">thrd_join</a>, passing the
identifier of the thread to wait for and, optionally, the address of a variable of
type <span class="code">int</span> where the result code will be stored. To properly clean up
resources allocated by the operating system, an application should call either
<span class="code">thrd_join</span> or <a href="#thrd_detach" class="code">thrd_detach</a>
once for each thread created by <span class="code">thrd_create</span>.</p>

<p>Two functions operate on the current thread; they do not take a thread identifier argument.
Use <a href="#thrd_sleep" class="code">thrd_sleep</a> to suspend
execution of the current thread until a particular time. Use
<a href="#thrd_yield" class="code">thrd_yield</a> to request that other
threads be allowed to run even if the current thread would ordinarily
continue to run.</p>

<p>Two functions operate on thread identifiers. Use
<a href="#thrd_equal" class="code">thrd_equal</a> to determine whether
two thread identifiers refer to the same thread.
Use <a href="#thrd_current" class="code">thrd_current</a> to get
a thread identifier that refers to the current thread.</p>

<h4>Condition Variables</h4>

<p>Use the functions and type with the prefix <span class="code">cnd_</span> to manage
<a href="#intro-condition-variable">condition variables</a>.
Each condition variable has an identifier of type
<a href="#cnd_t" class="code">cnd_t</a>, which is passed as an argument
to the functions that manage condition variables. Use
<a href="#cnd_init" class="code">cnd_init</a> to create a condition
variable and <a href="#cnd_destroy" class="code">cnd_destroy</a> to
release any resources associated with a condition variable when it is no longer needed.
To wait for a condition variable to be signalled call
<a href="#cnd_wait" class="code">cnd_wait</a> or
<a href="#cnd_timedwait" class="code">cnd_timedwait</a>.
To unblock threads waiting for a condition variable call
<a href="#cnd_signal" class="code">cnd_signal</a> or
<a href="#cnd_broadcast" class="code">cnd_broadcast</a>.</p>

<h4>Mutexes</h4>

<p>Use the functions and type with the prefix <span class="code">mtx_</span> to manage
<a href="#intro-mutex">mutexes</a>.
Each mutex has an identifier of type
<a href="#mtx_t" class="code">mtx_t</a>, which is passed as an argument
to the functions that manage mutexes. Use
<a href="#mtx_init" class="code">mtx_init</a> to create a mutex
and <a href="#mtx_destroy" class="code">mtx_destroy</a> to
release any resources associated with a mutex when it is no longer needed.
To lock a mutex call
<a href="#mtx_lock" class="code">mtx_lock</a>,
<a href="#mtx_timedlock" class="code">mtx_timedlock</a> or
<a href="#mtx_trylock" class="code">mtx_trylock</a>. To
unlock a mutex call
<a href="#mtx_unlock" class="code">mtx_unlock</a>.</p>

<h4>Once Functions</h4>

<p>Use a value of type <a href="#once_flag" class="code">once_flag</a>,
initialized to the value <a href="#ONCE_FLAG_INIT" class="code">ONCE_FLAG_INIT</a>,
to ensure that a function is called exactly once by passing
a function pointer and the address of the <span class="code">once_flag</span> object
to <a href="#call_once" class="code">call_once</a>.</p>

<h4>Thread-specific Storage</h4>

<p>Use the functions and types with the prefix <span class="code">tss_</span> to manage
<a href="#Thread-specific-Storage">thread-specific storage</a>.
Each thread-specific storage pointer has an identifier of type
<a href="#tss_t" class="code">tss_t</a>, which is passed as an argument
to the functions that manage thread-specific storage.
Call <a href="#tss_create" class="code">tss_create</a>
to create a thread-specific storage pointer and
<a href="#tss_delete" class="code">tss_delete</a> to release any
resources associated with a thread-specific storage pointer when it is no longer
needed. To get the value held by the pointer in the current thread call
<a href="#tss_get" class="code">tss_get</a>. To change the value
held by the pointer in the current thread call
<a href="#tss_set" class="code">tss_set</a>.</p>

<p>Each thread-specific storage pointer may have an associated
<span id="destructor" class="link-target">destructor</span>, specified in the call
to <span class="code">tss_create</span>. The destructor
will be called when a thread terminates and the value of the pointer
associated with that thread is not 0. The value of the pointer for that
thread is set to 0 before calling the destructor and the old value is
passed to the destructor. Since a destructor can store non-0 values in
thread-specific storage pointers, this process will be repeated until no pointers
for the terminating thread hold non-0 values or until a system-specific
maximum number of iterations
<a href="#TSS_DTOR_ITERATIONS" class="code">TSS_DTOR_ITERATIONS</a>
has been made.</p>

<pre>    /* ERROR REPORTING */
enum {
    <a href="#thrd_success" class="code">thrd_success</a> = .....,
    <a href="#thrd_nomem" class="code">thrd_nomem</a> = .....,
    <a href="#thrd_timedout" class="code">thrd_timedout</a> = .....,
    <a href="#thrd_busy" class="code">thrd_busy</a> = .....,
    <a href="#thrd_error" class="code">thrd_error</a> = .....
    };

    /* THREADS */
typedef <span class="non-code">o-type</span> <a href="#thrd_t" class="code">thrd_t</a>;
typedef int (*<a href="#thrd_start_t" class="code">thrd_start_t</a>)(void*);
int <a href="#thrd_create" class="code">thrd_create</a>(thrd_t *, thrd_start_t, void*);
int <a href="#thrd_detach" class="code">thrd_detach</a>(thrd_t);
void <a href="#thrd_exit" class="code">thrd_exit</a>(int);
int <a href="#thrd_join" class="code">thrd_join</a>(thrd_t, int*);
void <a href="#thrd_sleep" class="code">thrd_sleep</a>(const xtime*);
void <a href="#thrd_yield" class="code">thrd_yield</a>(void);
int <a href="#thrd_equal" class="code">thrd_equal</a>(thrd_t, thrd_t);
thrd_t <a href="#thrd_current" class="code">thrd_current</a>(void);

    /* MUTEXES */
typedef <span class="non-code">o-type</span> <a href="#mtx_t" class="code">mtx_t</a>;
enum {
    <a href="#mtx_plain" class="code">mtx_plain</a> = .....,
    <a href="#mtx_try" class="code">mtx_try</a> = .....,
    <a href="#mtx_timed" class="code">mtx_timed</a> = .....,
    <a href="#mtx_recursive" class="code">mtx_recursive</a> = .....
    };
int <a href="#mtx_init" class="code">mtx_init</a>(mtx_t*, int);
void <a href="#mtx_destroy" class="code">mtx_destroy</a>(mtx_t*);
int <a href="#mtx_lock" class="code">mtx_lock</a>(mtx_t*);
int <a href="#mtx_trylock" class="code">mtx_trylock</a>(mtx_t*);
int <a href="#mtx_timedlock" class="code">mtx_timedlock</a>(mtx_t*, const xtime*);
int <a href="#mtx_unlock" class="code">mtx_unlock</a>(mtx_t*);

    /* CONDITION VARIABLES */
typedef <span class="non-code">o_type</span> <a href="#cnd_t" class="code">cnd_t </a>;
int <a href="#cnd_init" class="code">cnd_init</a>(cnd_t*);
void <a href="#cnd_destroy" class="code">cnd_destroy</a>(cnd_t*);
int <a href="#cnd_wait" class="code">cnd_wait</a>(cnd_t*, mtx_t*);
int <a href="#cnd_timedwait" class="code">cnd_timedwait</a>(cnd_t*, mtx_t*, const xtime*);
int <a href="#cnd_signal" class="code">cnd_signal</a>(cnd_t*);
int <a href="#cnd_broadcast" class="code">cnd_broadcast</a>(cnd_t*);

    /* THREAD-SPECIFIC STORAGE */
typedef <span class="non-code">i-type</span> <a href="#tss_t" class="code">tss_t</a>;
typedef void (*<a href="#tss_dtor_t" class="code">tss_dtor_t</a>)(void*);
int <a href="#tss_create" class="code">tss_create</a>(tss_t*, tss_dtor_t);
int <a href="#tss_delete" class="code">tss_delete</a>(tss_t);
int <a href="#tss_set" class="code">tss_set</a>(tss_t, void*);
void *<a href="#tss_get" class="code">tss_get</a>(tss_t);
#define <a href="#TSS_DTOR_ITERATIONS" class="code">TSS_DTOR_ITERATIONS</a> <span class="non-code">&lt;integer constant expression&gt;</span>

    /* ONCE FUNCTIONS */
typedef <span class="non-code">o-type</span> <a href="#once_flag" class="code">once_flag</a>;
#define <a href="#ONCE_FLAG_INIT" class="code">ONCE_FLAG_INIT</a> <span class="non-code">&lt;object initializer&gt;</span>
void <a href="#call_once" class="code">call_once</a>(once_flag*, void (*)(void));

    /* TIME SUPPORT */
typedef <span class="non-code">o-type</span> <a href="#xtime" class="code">xtime</a>;
enum { <a href="#TIME_UTC" class="code">TIME_UTC</a> = <span class="non-code">&lt;integer constant expression&gt;</span> };
int <a href="#xtime_get" class="code">xtime_get</a>(xtime *, int);</pre>

<h3><span id="cnd_broadcast" class="code">cnd_broadcast</span></h3>

<pre>int <span class="decl">cnd_broadcast</span>(cnd_t *cond);</pre>

<p><span class="reqmt">Requires</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function unblocks all of the threads that are blocked on the
<a href="#intro-condition-variable">condition variable</a>
<span class="code">*cond</span> at the time of the call. If no threads are blocked
on the condition variable at the time of the call the function does nothing.</p>

<h3><span id="cnd_destroy" class="link-target code">cnd_destroy</span></h3>

<pre>void <span class="decl">cnd_destroy</span>(cnd_t *cond);</pre>

<p><span class="reqmt">Requires</span>
no threads are blocked waiting for <span class="code">*cond</span>.</p>

<p>The function releases any resources used by the
<a href="#intro-condition-variable">condition variable</a> <span class="code">*cond</span>.</p>

<h3><span id="cnd_init" class="link-target code">cnd_init</span></h3>

<pre>int <span class="decl">cnd_init</span>(cnd_t *cond);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function creates a
<a href="#intro-condition-variable">condition variable</a>.
If it succeeds
it sets <span class="code">*cond</span> to a value that uniquely identifies the
newly created condition variable.
A thread that calls <a href="#cnd_wait">cnd_wait</a> on a newly created condition variable
will block.</p>

<h3><span id="cnd_signal" class="link-target code">cnd_signal</span></h3>

<pre>int <span class="decl">cnd_signal</span>(cnd_t *cond);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function unblocks one of the threads that is blocked on the
<a href="#intro-condition-variable">condition variable</a>
<span class="code">*cond</span> at the time of the call. If no threads are blocked
on the condition variable at the time of the call the function does nothing.</p>

<h3><span id="cnd_t" class="link-target code">cnd_t</span></h3>

<pre>typedef <span class="non-code">o-type</span> <span class="decl">cnd_t</span>;</pre>

<p>The type is an object type <span class="non-code">o-type</span> that holds an identifier for a
<a href="#intro-condition-variable">condition variable</a>.</p>

<h3><span id="cnd_timedwait" class="link-target code">cnd_timedwait</span></h3>

<pre>int <span class="decl">cnd_timedwait</span>(cnd_t *cond, mtx_t *mtx, const xtime *xt);</pre>

<p><span class="reqmt">Requires</span>
the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
must be locked by the calling thread</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function atomically unlocks the <a href="#intro-mutex">mutex</a>
<span class="code">*mtx</span> and blocks until the
<a href="#intro-condition-variable">condition variable</a>
<span class="code">*cond</span> is signaled by a call to
<a href="#cnd_signal">cnd_signal</a> or to
<a href="#cnd_broadcast">cnd_broadcast</a>, or until after the time specified
by the <a href="#xtime">xtime</a> object <span class="code">*xt</span>.
When the calling thread becomes unblocked it locks <span class="code">*mtx</span>
before it returns.</p>

<h3><span id="cnd_wait" class="link-target code">cnd_wait</span></h3>

<pre>int <span class="decl">cnd_wait</span>(cnd_t *cond, mtx_t *mtx);</pre>

<p><span class="reqmt">Requires</span>
the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
must be locked by the calling thread</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function atomically unlocks the <a href="#intro-mutex">mutex</a>
<span class="code">*mtx</span> and blocks until the <a href="#intro-condition-variable">condition variable</a>
<span class="code">*cond</span> is signaled by a call to
<a href="#cnd_signal">cnd_signal</a> or to
<a href="#cnd_broadcast">cnd_broadcast</a>. When the calling thread becomes
unblocked it locks <span class="code">*mtx</span> before it returns.</p>

<h3><span id="mtx_destroy" class="link-target code">mtx_destroy</span></h3>

<pre>void <span class="decl">mtx_destroy</span>(mtx_t *mtx);</pre>

<p><span class="reqmt">Requires</span>
no threads are blocked waiting for <span class="code">*mtx</span>.</p>

<p>The function releases any resources used by the
<a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>.</p>

<h3><span id="mtx_init" class="link-target code">mtx_init</span></h3>

<pre>int <span class="decl">mtx_init</span>(mtx_t *mtx, int type);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function creates a <a href="#intro-mutex">mutex</a> object with
properties indicated by <span class="code">type</span>, which must have one of
the six values</p>

<ul>
<li><a href="#mtx_plain" class="code">mtx_plain</a> -- for a simple
<a href="#intro-non-recursive">non-recursive</a> mutex</li>
<li><a href="#mtx_timed" class="code">mtx_timed</a> -- for a
non-recursive mutex that supports <a href="#intro-timeout">timeout</a></li>
<li><a href="#mtx_try" class="code">mtx_try</a> -- for a
non-recursive mutex that supports <a href="#intro-test-and-return">test and return</a></li>
<li><span class="code">mtx_plain</span> | <a href="#mtx_recursive" class="code">mtx_recursive</a> -- for a simple
<a href="#intro-recursive">recursive</a> mutex</li>
<li><span class="code">mtx_timed | mtx_recursive</span> -- for a
recursive mutex that supports <a href="#intro-timeout">timeout</a></li>
<li><span class="code">mtx_try | mtx_recursive</span> -- for a
recursive mutex that supports <a href="#intro-test-and-return">test and return</a></li>
</ul>

<p>If it succeeds it sets <span class="code">*mtx</span> to a value that uniquely
identifies the newly created mutex.</p>

<h3><span id="mtx_lock" class="link-target code">mtx_lock</span></h3>

<pre>int <span class="decl">mtx_lock</span>(mtx_t *mtx);</pre>

<p><span class="reqmt">Requires</span>
if the <a href="#intro-mutex">mutex</a> is
<a href="#intro-non-recursive">non-recursive</a> it must not
be locked by the calling thread.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function blocks until it locks the
<a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>.</p>

<h3><span id="mtx_plain" class="link-target code">mtx_plain</span></h3>

<pre>enum { <span class="decl">mtx_plain</span> = ..... };</pre>

<p>The compile-time constant is passed to
<a href="#mtx_init">mtx_init</a> to create a
<a href="#intro-mutex">mutex</a> object that supports neither
<a href="#intro-timeout">timeout</a> nor
<a href="#intro-test-and-return">test and return</a>.</p>

<h3><span id="mtx_recursive" class="link-target code">mtx_recursive</span></h3>

<pre>enum { <span class="decl">mtx_recursive</span> = ..... };</pre>

<p>The compile-time constant is passed to
<a href="#mtx_init">mtx_init</a> to create a
<a href="#intro-mutex">mutex</a> object that supports
<a href="#intro-recursive">recursive</a> locking.</p>

<h3><span id="mtx_t" class="link-target code">mtx_t</span></h3>

<pre>typedef <span class="non-code">o-type</span> <span class="decl">mtx_t</span>;</pre>

<p>The type is an object type <span class="non-code">o-type</span> that holds an identifier for a
<a href="#intro-mutex">mutex</a>.</p>

<h3><span id="mtx_timed" class="link-target code">mtx_timed</span></h3>

<pre>enum { <span class="decl">mtx_timed</span> = ..... };</pre>

<p>The compile-time constant is passed to
<a href="#mtx_init">mtx_init</a> to create a
<a href="#intro-mutex">mutex</a> object that supports
<a href="#intro-timeout">timeout</a>.</p>

<h3><span id="mtx_timedlock" class="link-target code">mtx_timedlock</span></h3>

<pre>int <span class="decl">mtx_timedlock</span>(mtx_t *mtx, const xtime *xt);</pre>

<p><span class="reqmt">Requires</span>
the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
must be of type <a href="#mtx_timed">mtx_timed</a> or
of type <span class="code">mtx_timed | mtx_recursive</span>.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function blocks until it locks the
<a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
or until the time specified by the
<a href="#xtime">xtime</a> object <span class="code">*xt</span>.</p>

<h3><span id="mtx_try" class="link-target code">mtx_try</span></h3>

<pre>enum { <span class="decl">mtx_try</span> = ..... };</pre>

<p>The compile-time constant is passed to
<a href="#mtx_init">mtx_init</a> to create a
<a href="#intro-mutex">mutex</a> object that supports
<a href="#intro-test-and-return">test and return</a>.</p>

<h3><span id="mtx_trylock" class="link-target code">mtx_trylock</span></h3>

<pre>int <span class="decl">mtx_trylock</span>(mtx_t *mtx);</pre>

<p><span class="reqmt">Requires</span>
the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
must be of type <a href="#mtx_try">mtx_try</a>,
of type <span class="code">mtx_try | mtx_recursive</span>,
of type <a href="#mtx_timed">mtx_timed</a>,
or of type <span class="code">mtx_timed | mtx_recursive</span>.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function attempts to lock the
<a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>.
If the mutex is already locked the function returns without blocking.</p>

<h3><span id="mtx_unlock" class="link-target code">mtx_unlock</span></h3>

<pre>int <span class="decl">mtx_unlock</span>(mtx_t *mtx);</pre>

<p><span class="reqmt">Requires</span>
the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>
must be locked by the calling thread.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function unlocks the <a href="#intro-mutex">mutex</a> <span class="code">*mtx</span>.</p>

<h3><span id="thrd_busy" class="link-target code">thrd_busy</span></h3>

<pre>enum { <span class="decl">thrd_busy</span> = ..... };</pre>

<p>The compile-time constant is returned by a function to indicate
that the requested operation failed because
a resource requested by a <a href="#intro-test-and-return">test and return</a>
function is already in use.</p>

<h3><span id="thrd_create" class="link-target code">thrd_create</span></h3>

<pre>int <span class="decl">thrd_create</span>(thrd_t *thr, thrd_start_t func, void *arg);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function creates a new <a href="#intro-thread">thread</a>
executing <span class="code">func(arg)</span>.
If it succeeds it sets <span class="code">*thr</span> to a value that uniquely identifies the
newly created thread. The function does not return until the new thread has
begun execution.</p>

<h3><span id="thrd_current" class="link-target code">thrd_current</span></h3>

<pre>thrd_t <span class="decl">thrd_current</span>(void);</pre>

<p>The function returns a value that uniquely identifies
the <a href="#intro-thread">thread</a>
that called it.</p>

<h3><span id="thrd_detach" class="link-target code">thrd_detach</span></h3>

<pre>int <span class="decl">thrd_detach</span>(thrd_t thr);</pre>

<p><span class="reqmt">Requires</span>
the application must not have previously called
<span class="code">thrd_detach</span> or
<a href="#thrd_join">thrd_join</a> for the
<a href="#intro-thread">thread</a> identified by <span class="code">thr</span>.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function tells the operating system to dispose of any resources allocated to the
thread identified by <span class="code">thr</span> when that thread terminates.</p>

<h3><span id="thrd_equal" class="link-target code">thrd_equal</span></h3>

<pre>int <span class="decl">thrd_equal</span>(thrd_t thr0, thrd_t thr1);</pre>

<p>The function returns zero if <span class="code">thr0</span> and <span class="code">thr1</span> refer to
different threads. Otherwise it returns a non-zero value.</p>

<h3><span id="thrd_error" class="link-target code">thrd_error</span></h3>

<pre>enum { <span class="decl">thrd_error</span> = ..... };</pre>

<p>The compile-time constant is returned by a function to indicate
that the requested operation failed.</p>

<h3><span id="thrd_exit" class="link-target code">thrd_exit</span></h3>

<pre>void <span class="decl">thrd_exit</span>(int res);</pre>

<p>The function terminates execution of the calling
<a href="#intro-thread">thread</a> and sets its
<a href="#result-code">result code</a> to <span class="code">res</span>.</p>

<h3><span id="thrd_join" class="link-target code">thrd_join</span></h3>

<pre>int <span class="decl">thrd_join</span>(thrd_t thr, int *res);</pre>

<p><span class="reqmt">Requires</span>
the application must not have previously called
<span class="code">thrd_join</span> or
<a href="#thrd_detach">thrd_detach</a> for the
<a href="#intro-thread">thread</a> identified by <span class="code">thr</span>.</p>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function tells the operating system to dispose of any resources allocated to the
<span class="code">thread</span> identified by <span class="code">thr</span> when that thread terminates and
blocks until that thread has terminated. If <span class="code">res</span>
is not a null pointer it stores the thread's
<a href="#result-code">result code</a>
in <span class="code">*res</span>.</p>

<h3><span id="thrd_nomem" class="link-target code">thrd_nomem</span></h3>

<pre>enum { <span class="decl">thrd_nomem</span> = ..... };</pre>

<p>The compile-time constant is returned by a function to indicate
that the requested operation failed because
it was unable to allocate memory.</p>

<h3><span id="thrd_sleep" class="link-target code">thrd_sleep</span></h3>

<pre>void <span class="decl">thrd_sleep</span>(const xtime *xt);</pre>

<p>The function suspends execution of the calling
<a href="#intro-thread">thread</a>
until after the time specified by the
<a href="#xtime">xtime</a> object <span class="code">*xt</span>.</p>

<h3><span id="thrd_start_t" class="link-target code">thrd_start_t</span></h3>

<pre>typedef int (*<span class="decl">thrd_start_t</span>)(void*);</pre>

<p>The type is the function type that is passed to
<a href="#thrd_create">thrd_create</a> to create a new
<a href="#intro-thread">thread</a>.</p>

<h3><span id="thrd_success" class="link-target code">thrd_success</span></h3>

<pre>enum { <span class="decl">thrd_success</span> = ..... };</pre>

<p>The compile-time constant is returned by a function to indicate
that the requested operation succeeded.</p>

<h3><span id="thrd_t" class="link-target code">thrd_t</span></h3>

<pre>typedef <span class="non-code">o-type</span> <span class="decl">thrd_t</span>;</pre>

<p>The type is an object type <span class="non-code">o-type</span> that holds an identifier for a
<a href="#intro-thread">thread</a>.</p>

<h3><span id="thrd_timedout" class="link-target code">thrd_timedout</span></h3>

<pre>enum { <span class="decl">thrd_timedout</span> = ..... };</pre>

<p>The compile-time constant is returned by a timed wait function to indicate
that the time specified in the call was reached without acquiring the
requested resource.</p>

<h3><span id="thrd_yield" class="link-target code">thrd_yield</span></h3>

<pre>void <span class="decl">thrd_yield</span>(void);</pre>

<p>The function permits other threads to run even if the current thread would
ordinarily continue to run.</p>

<h3><span id="TIME_UTC" class="link-target code">TIME_UTC</span></h3>

<pre>enum { <span class="decl">TIME_UTC</span> = <span class="non-code">&lt;integer constant expression&gt;</span> };</pre>

<p>The compile-time constant is a non-zero value that designates Coordinated Universal
Time (UTC) as the time base for the values set by <a href="#xtime_get">xtime_get</a>.</p>

<h3><span id="tss_create" class="link-target code">tss_create</span></h3>

<pre>int <span class="decl">tss_create</span>(tss_t *key, tss_dtor_t dtor);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function creates a
<a href="#Thread-specific-Storage">thread-specific storage</a>
pointer with <a href="#destructor">destructor</a> <span class="code">dtor</span>,
which may be null. If it succeeds it sets <span class="code">*key</span> to a value that uniquely
identifies the newly created pointer.</p>

<h3><span id="TSS_DTOR_ITERATIONS" class="link-target code">TSS_DTOR_ITERATIONS</span></h3>

<pre>#define <span class="decl">TSS_DTOR_ITERATIONS</span> <span class="non-code">&lt;integer constant expression&gt;</span></pre>

<p>The macro yields the maximum number of times that
<a href="#destructor">destructors</a> will
be called when a thread terminates.</p>

<h3><span id="tss_dtor_t" class="link-target code">tss_dtor_t</span></h3>

<pre>typedef void (*<span class="decl">tss_dtor_t</span>)(void*);</pre>

<p>The type is the function type for a
<a href="#destructor">destructor</a> for a
<a href="#Thread-specific-Storage">thread-specific storage</a> pointer.</p>

<h3><span id="tss_delete" class="link-target code">tss_delete</span></h3>

<pre>void <span class="decl">tss_delete</span>(tss_t key);</pre>

<p>The function releases any resources used by the
<a href="#Thread-specific-Storage">thread-specific storage</a>
pointer <span class="code">key</span>.</p>

<h3><span id="tss_get" class="link-target code">tss_get</span></h3>

<pre>void *<span class="decl">tss_get</span>(tss_t key);</pre>

<p>The function returns the value for the current thread held in the
<a href="#Thread-specific-Storage">thread-specific storage</a>
pointer identified by <span class="code">key</span>.</p>

<h3><span id="tss_set" class="link-target code">tss_set</span></h3>

<pre>int <span class="decl">tss_set</span>(tss_t key, void *val);</pre>

<p><span class="reqmt">Returns</span> the usual <a href="#return-value">return value</a>.</p>

<p>The function sets the value for the current thread held in the
<a href="#Thread-specific-Storage">thread-specific storage</a>
pointer identified by <span class="code">key</span> to <span class="code">val</span>.</p>

<h3><span id="tss_t" class="link-target code">tss_t</span></h3>

<pre>typedef <span class="non-code">o-type</span> <span class="decl">tss_t</span>;</pre>

<p>The type is an object type <span class="non-code">o-type</span> that holds an identifier for a
<a href="#Thread-specific-Storage">thread-specific storage</a>
pointer.</p>

<h3><span id="xtime" class="link-target code">xtime</span></h3>

<pre>typedef struct {
    int sec;    /* seconds since 1 Jan. 1970 00:00:00 */
    int nsec;   /* nanoseconds since time specified by sec */
    } <span class="decl">xtime</span>;</pre>

<p>The struct <span class="code">xtime</span> contains members that describe times with
nanosecond resolution. The comment following each member desribes its meaning.</p>

<h3><span id="xtime_get" class="link-target code">xtime_get</span></h3>

<pre>int <span class="decl">xtime_get</span>(xtime *xt, int base);</pre>

<p>The function sets the <span class="code">xtime</span> object pointed to by
<span class="code">xt</span> to hold the current time based on the time base
<span class="code">base</span>. If successful it returns the non-zero value <span class="code">base</span>,
which must be <a href="#TIME_UTC">TIME_UTC</a>;
otherwise it returns 0.</p>

<h3><span id="Cpp-Interface" class="link-target">C++ Interface</span></h3>

<div class="block menu">
<a href="#call_once" class="code">call_once</a>
<a href="#cancellation_point" class="code">cancellation_point</a>
<a href="#cancellation_enabled" class="code">cancellation_enabled</a>
<a href="#cancellation_requested" class="code">cancellation_requested</a>
<a href="#condition" class="code">condition</a>
<a href="#disable_cancellation" class="code">disable_cancellation</a>
<a href="#restore_cancellation" class="code">restore_cancellation</a>
<a href="#get_id" class="code">get_id</a>
<a href="#lock_error" class="code">lock_error</a>
<a href="#mutex" class="code">mutex</a>
<a href="#once_flag" class="code">once_flag</a>
<a href="#ONCE_FLAG_INIT" class="code">ONCE_FLAG_INIT</a>
<a href="#once_init" class="code">once_init</a>
<a href="#operator-equal-equal-id" class="code">operator==</a>
<a href="#operator-not-equal-id" class="code">operator!=</a>
<a href="#recursive_mutex" class="code">recursive_mutex</a>
<a href="#recursive_timed_mutex" class="code">recursive_timed_mutex</a>
<a href="#recursive_try_mutex" class="code">recursive_try_mutex</a>
<a href="#sleep" class="code">sleep</a>
<a href="#thread" class="code">thread</a>
<a href="#thread::id" class="code">thread::id</a>
<a href="#thread_canceled" class="code">thread_canceled</a>
<a href="#thread_group" class="code">thread_group</a>
<a href="#thread_resource_error" class="code">thread_resource_error</a>
<a href="#thread_specific_ptr" class="code">thread_specific_ptr</a>
<a href="#timed_mutex" class="code">timed_mutex</a>
<a href="#try_mutex" class="code">try_mutex</a>
<a href="#yield" class="code">yield</a>
</div>

<pre>namespace std {

    /* ERROR REPORTING */
class <a href="#lock_error" class="code">lock_error</a>;
class <a href="#thread_resource_error" class="code">thread_resource_error</a>;

    /* THREADS */
class <a href="#thread" class="code">thread</a>;
class <a href="#thread_canceled" class="code">thread_canceled</a>;
class <a href="#thread_group" class="code">thread_group</a>;

    /* MUTEXES */
class <a href="#mutex" class="code">mutex</a>;
class <a href="#try_mutex" class="code">try_mutex</a>;
class <a href="#timed_mutex" class="code">timed_mutex</a>;

class <a href="#recursive_mutex" class="code">recursive_mutex</a>;
class <a href="#recursive_try_mutex" class="code">recursive_try_mutex</a>;
class <a href="#recursive_timed_mutex" class="code">recursive_timed_mutex</a>;

    /* CONDITION VARIABLES */
class <a href="#condition" class="code">condition</a>;

    /* THREAD-SPECIFIC STORAGE */
class <a href="#thread_specific_ptr" class="code">thread_specific_ptr</a>;

    /* ONCE FUNCTIONS */
typedef <span class="non-code">o-type</span> <a href="#once_flag" class="code">once_flag</a>;
#define <a href="#ONCE_FLAG_INIT" class="code">ONCE_FLAG_INIT</a> = .....
const once_flag <a href="#once_init" class="code">once_init</a> = .....;
void <a href="#call_once" class="code">call_once</a>(void (*func)(void), once_flag&amp; flag);    // C++ Only
void <a href="#call_once" class="code">call_once</a>(once_flag *flag, void (*func)(void));

    /* THREAD ID COMPARISONS */
bool <a href="#operator-equal-equal-id" class="code">operator==</a>(const thread::id&amp;, const thread::id&amp;);
bool <a href="#operator-not-equal-id" class="code">operator!=</a>(const thread::id&amp;, const thread::id&amp;);

    /* CURRENT THREAD OPERATIONS */
namespace this_thread {

thread::id <a href="#get_id" class="code">get_id</a>();
void <a href="#sleep" class="code">sleep</a>(const xtime&amp;);
void <a href="#yield" class="code">yield</a>();

class <a href="#disable_cancellation" class="code">disable_cancellation</a>;
class <a href="#restore_cancellation" class="code">restore_cancellation</a>;

void <a href="#cancellation_point" class="code">cancellation_point</a>();
bool <a href="#cancellation_enabled" class="code">cancellation_enabled</a>();
bool <a href="#cancellation_requested" class="code">cancellation_requested</a>();

}   // namespace this_thread

}   // namespace std

    /* C INTERFACE TYPES */
typedef <span class="non-code">unspecified</span> <a href="#cnd_t" class="code">cnd_t</a>;
typedef <span class="non-code">unspecified</span> <a href="#mtx_t" class="code">mtx_t</a>;
typedef <span class="non-code">unspecified</span> <a href="#thrd_t" class="code">thrd_t</a>;
typedef <span class="non-code">unspecified</span> <a href="#tss_t" class="code">tss_t</a>;

</pre>

<h3><span id="call_once" class="link-target code">call_once</span></h3>

<pre>void <span class="decl">call_once</span>(void (*func)(void), once_flag&amp; flag);    // C++ Only
void <span class="decl">call_once</span>(once_flag *pflag, void (*func)(void));</pre>

<p>The functions use <span class="code">flag</span> and <span class="code">*pflag</span> to ensure that
<span class="code">func</span> is called exactly once.</p>

<h3><span id="cancellation_enabled" class="link-target code">cancellation_enabled</span></h3>

<pre>bool <span class="decl">cancellation_enabled</span>();</pre>

<p>The function returns true if cancellation is enabled in the calling thread,
otherwise false.</p>

<h3><span id="cancellation_point" class="link-target code">cancellation_point</span></h3>

<pre>void <span class="decl">cancellation_point</span>();</pre>

<p>If cancellation is enabled in the calling thread and there is an
unhandled cancellation request to the calling thread, the function
handles the cancellation request by throwing an object of type
<span class="code">thread_canceled</span>, otherwise it does nothing.</p>

<h3><span id="cancellation_requested" class="link-target code">cancellation_requested</span></h3>

<pre>bool <span class="decl">cancellation_requested</span>();</pre>

<p>The function returns true if there is an unhandled cancellation request to the
calling thread, otherwise false.</p>

<h3><span id="condition" class="link-target code">condition</span></h3>

<div class="block menu">
<a href="#condition::c_handle" class="code">c_handle</a>
<a href="#condition::condition" class="code">condition</a>
<a href="#condition::~condition" class="code">~condition</a>
<a href="#condition::native_handle" class="code">native_handle</a>
<a href="#condition::native_condition_handle" class="code">native_condition_handle</a>
<a href="#condition::notify_all" class="code">notify_all</a>
<a href="#condition::notify_one" class="code">notify_one</a>
<a href="#condition::timed_wait" class="code">timed_wait</a>
<a href="#condition::wait" class="code">wait</a>
</div>

<pre>class <span class="decl">condition</span>
    {
public:
    <a href="#condition::condition" class="code">condition</a>();
    <a href="#condition::condition" class="code">condition</a>(cnd_t);
    <a href="#condition::~condition" class="code">~condition</a>();

    template &lt;class Lock&gt;
        void <a href="#condition::wait" class="code">wait</a>(Lock&amp; lock);
    template &lt;class Lock, class Pred&gt;
        void <a href="#condition::wait" class="code">wait</a>(Lock&amp; lock, Pred pred);

    template &lt;class Lock&gt;
        bool <a href="#condition::timed_wait" class="code">timed_wait</a>(Lock&amp; lock, const xtime&amp; xt);
    template &lt;class Lock, class Pred&gt;
        bool <a href="#condition::timed_wait" class="code">timed_wait</a>(Lock&amp; lock, const xtime&amp; xt, Pred pred);

    void <a href="#condition::notify_one" class="code">notify_one</a>();
    void <a href="#condition::notify_all" class="code">notify_all</a>();

    typedef <span class="non-code">unspecified</span> <a href="#condition::native_condition_handle" class="code">native_condition_handle</a>;
    native_condition_handle <a href="#condition::native_handle" class="code">native_handle</a>() const;
    cnd_t <a href="#condition::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:

    // not implemented
    condition(const condition&amp;);
    condition&amp; operator=(const condition&amp;);</span>
    };</pre>

<p>The class describes an object that manages a
<a href="#intro-condition-variable">condition variable</a>.
Use <a href="#condition::wait">wait</a> or
<a href="#condition::timed_wait">timed_wait</a>
to wait for a condition to become true. Use
<a href="#condition::notify_one">notify_one</a>
to notify one waiting thread that the condition has become true and
<a href="#condition::notify_all">notify_all</a>
to notify all waiting threads that the condition has become true.
Objects of class <span class="code">condition</span> cannot be copied.</p>

<h4><span id="condition::c_handle" class="link-target code">condition::c_handle</span></h4>

<pre>cnd_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#cnd_t" class="code">cnd_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this condition variable.</p>

<h4><span id="condition::condition" class="link-target code">condition::condition</span></h4>

<pre><span class="decl">condition</span>();
<span class="decl">condition</span>(cnd_t cnd);</pre>

<p>The first constructor constructs a <span class="code">condition</span> object;
a thread that calls <span class="code">wait</span> on a newly
constructed <span class="code">condition</span> object will block.
The second constructor constructs a <span class="code">condition</span> object
with the same state as <span class="code">cnd</span>.</p>

<h4><span id="condition::destructor" class="link-target code">condition::~condition</span></h4>

<pre><span class="decl">~condition</span>();</pre>

<p><span class="reqmt">Requires</span>
no threads are blocked waiting for the condition object.</p>

<p>The destructor releases any resources used by the <span class="code">condition</span> object.</p>

<h4><span id="condition::native_handle" class="link-target code">condition::native_handle</span></h4>

<pre>native_condition_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the condition variable managed by this object.</p>

<h4><span id="condition::native_condition_handle" class="link-target code">condition::native_condition_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_condition_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the thread managed by this object.</p>

<h4><span id="condition::notify_one" class="link-target code">condition::notify_one</span></h4>

<pre>void <span class="decl">notify_one</span>();</pre>

<p>The member function unblocks one of the threads that is blocked on the
<span class="code">condition</span> object at the time of the call. If no threads are blocked
on the object at the time of the call the function does nothing.</p>

<h4><span id="condition::notify_all" class="link-target code">condition::notify_all</span></h4>

<pre>void <span class="decl">notify_all</span>();</pre>

<p>The member function unblocks all of the threads that are blocked on the
<span class="code">condition</span> object at the time of the call. If no threads are blocked
on the object at the time of the call the function does nothing.</p>

<h4><span id="condition::timed_wait" class="link-target code">condition::timed_wait</span></h4>

<pre>template &lt;class Lock&gt;
    bool <span class="decl">timed_wait</span>(Lock&amp; lock, const xtime&amp; xt);
template &lt;class Lock, class Pred&gt;
    bool <span class="decl">timed_wait</span>(Lock&amp; lock, const xtime&amp; xt, Pred pred);</pre>

<p><span class="reqmt">Throws</span> an object of class
<a href="#lock_error" class="code">lock_error</a> if
the <a href="#lock-object">lock object</a> <span class="code">lock</span>
is not locked.</p>

<p>The first member function atomically unlocks <span class="code">lock</span> and blocks
until the <span class="code">condition</span> object is signaled by a call to
<a href="#condition::notify_one">notify_one</a> or to
<a href="#condition::notify_all">notify_all</a>, or until after the time specified
by the <a href="#xtime">xtime</a> object <span class="code">xt</span>.
When the calling thread becomes unblocked it locks the lock object <span class="code">lock</span>
before it returns. The function returns <span class="code">false</span> if it returned because the time
<span class="code">xt</span> had passed, otherwise it returns <span class="code">true</span>.</p>

<p>The second member function atomically unlocks <span class="code">lock</span> and blocks
until the <span class="code">condition</span> object is signaled by a call to
<span class="code">notify_one</span> or to <span class="code">notify_all</span> and the predicate
<span class="code">pred()</span> returns true
(that is, the function incorporates the loop that is needed to avoid
<a href="#intro-spurious-wakeups">spurious wakeups</a>),
or until after the time specified
by the <a href="#xtime">xtime</a> object <span class="code">xt</span>.
When the calling thread becomes unblocked it locks the lock object <span class="code">lock</span>
before it returns. The function returns <span class="code">false</span> if it returned because the time
<span class="code">xt</span> had passed, otherwise it returns <span class="code">true</span>.</p>

<h4><span id="condition::wait" class="link-target code">condition::wait</span></h4>

<pre>template &lt;class Lock&gt;
    void <span class="decl">wait</span>(Lock&amp; lock);
template &lt;class Lock, class Pred&gt;
    void <span class="decl">wait</span>(Lock&amp; lock, Pred pred);</pre>

<p><span class="reqmt">Throws</span> an object of class
<a href="#lock_error" class="code">lock_error</a> if
the <a href="#lock-object">lock object</a> <span class="code">lock</span>
is not locked.</p>

<p>The first member function atomically unlocks <span class="code">lock</span> and blocks
until the <span class="code">condition</span> object is signaled by a call to
<a href="#condition::notify_one">notify_one</a> or to
<a href="#condition::notify_all">notify_all</a>. When the calling thread becomes
unblocked it locks the lock object <span class="code">lock</span> before it returns.</p>

<p>The second member function atomically unlocks <span class="code">lock</span> and blocks
until the <span class="code">condition</span> object is signaled by a call to
<span class="code">notify_one</span> or to <span class="code">notify_all</span> and the predicate
<span class="code">pred()</span> returns true
(that is, the function incorporates the loop that is needed to avoid
<a href="#intro-spurious-wakeups">spurious wakeups</a>).
When the calling thread becomes
unblocked it locks the lock object <span class="code">lock</span> before it returns.</p>

<h3><span id="disable_cancellation" class="link-target code">disable_cancellation</span></h3>

<pre>class <span class="decl">disable_cancellation</span>
    {
public:

    <a href="#disable_cancellation::disable_cancellation" class="code">disable_cancellation</a>();
    <a href="#disable_cancellation::destructor" class="code">~disable_cancellation</a>();

<span class="non-code">    // exposition only
private:
    // not implemented
    disable_cancellation(const disable_cancellation&amp;);
    disable_cancellation&amp; operator= (const disable_cancellation&amp;);</span>
    };</pre>

<p>The class describes an object that can be created to disable cancellation
throughout its lifetime.</p>

<h4><span id="disable_cancellation::disable_cancellation" class="link-target code">disable_cancellation::disable_cancellation</span></h4>

<pre><span class="decl">disable_cancellation</span>();</pre>

<p>The constructor disables cancellation in the calling thread.</p>

<h4><span id="disable_cancellation::destructor" class="link-target code">disable_cancellation::~disable_cancellation</span></h4>

<pre><span class="decl">~disable_cancellation</span>();</pre>

<p>The destructor enables cancellation in the calling thread only if cancellation was
enabled in the calling thread when this <span class="code">disable_cancellation</span> object was created.</p>

<h3><span id="restore_cancellation" class="link-target code">restore_cancellation</span></h3>

<pre>class <span class="decl">restore_cancellation</span>
    {
public:

    <a href="#restore_cancellation::restore_cancellation" class="code">restore_cancellation</a>(disable_cancellation&amp;);
    <a href="#restore_cancellation::destructor" class="code">~restore_cancellation</a>();

<span class="non-code">    // exposition only
private:
    // not implemented
    restore_cancellation(const restore_cancellation&amp; rc);
    restore_cancellation&amp; operator= (const restore_cancellation&amp;);</span>
    };</pre>

<p>The class describes an object that can be created to restore cancellation, throughout
its lifetime, to the state prior to creation of <span class="code">rc</span>.</p>

<h4><span id="restore_cancellation::restore_cancellation" class="link-target code">restore_cancellation::restore_cancellation</span></h4>

<pre><span class="decl">restore_cancellation</span>(disable_cancellation&amp; d);</pre>

<p>The constructor enables cancellation in the calling thread only if
the desctructor of the <span class="code">disable_cancellation</span> object
<span class="code">d</span> would enable cancellation in the calling thread.</p>

<h4><span id="restore_cancellation::destructor" class="link-target code">restore_cancellation::~restore_cancellation</span></h4>

<pre><span class="decl">~restore_cancellation</span>();</pre>

<p>The destructor disables cancellation in the calling thread only if cancellation was
disabled in the calling thread when this <span class="code">restore_cancellation</span> object was created.</p>

<h3><span id="get_id" class="link-target code">get_id</span></h3>

<pre>thread::id <span class="decl">get_id</span>();</pre>

<p>The function returns an object that uniquely identifies the calling thread.</p>

<h3><span id="lock_error" class="link-target code">lock_error</span></h3>

<pre>class <span class="decl">lock_error</span>
    : public std::runtime_error
    {
public:
    lock_error();
    };</pre>

<p>The class describes an exception thrown to indicate that an attempted
operation involving a lock failed because the lock was not in a required state.</p>

<h3><span id="once_flag" class="link-target code">once_flag</span></h3>

<pre>typedef <span class="non-code">o-type</span> <span class="decl">once_flag</span>;</pre>

<p>The type describes a data object for use as the first argument to
<a href="#call_once" class="code">call_once</a>.</p>

<h3><span id="ONCE_FLAG_INIT" class="link-target code">ONCE_FLAG_INIT</span></h3>

<pre>#define <span class="decl">ONCE_FLAG_INIT</span> <span class="non-code">&lt;object initializer&gt;</span></pre>

<p>The macro yields a value that can be used to initialize an object of
type <a href="#once_flag">once_flag</a>.</p>

<h3><span id="once_init" class="link-target code">once_init</span></h3>

<pre>const once_flag <span class="decl">once_init</span> = .....;</pre>

<p>The object provides an initial value for objects of type <span class="code">once_flag</span>.</p>

<h3><span id="mutex" class="link-target code">mutex</span></h3>

<div class="block menu">
<a href="#mutex::c_handle" class="code">c_handle</a>
<a href="#mutex::mutex" class="code">mutex</a>
<a href="#mutex::~mutex" class="code">~mutex</a>
<a href="#mutex::native_handle" class="code">native_handle</a>
<a href="#mutex::native_mutex_handle" class="code">native_mutex_handle</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
</div>

<pre>class <span class="decl">mutex</span>
    {
public:
    <a href="#mutex::mutex" class="code">mutex</a>();
    <a href="#mutex::mutex" class="code">mutex</a>(mtx_t);
    <a href="#mutex::~mutex" class="code">~mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#mutex::native_mutex_handle" class="code">native_mutex_handle</a>;
    native_thread_handle <a href="#mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    mutex(const mutex&amp;);
    mutex&amp; operator= (const mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#scoped_lock">scoped lock</a>
to provide a non-recursive <a href="#intro-mutex">mutex</a>.
Objects of class <span class="code">mutex</span> cannot be copied.</p>

<h4><span id="mutex::c_handle" class="link-target code">mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>();</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="mutex::mutex" class="link-target code">mutex::mutex</span></h4>

<pre><span class="decl">mutex</span>();
<span class="decl">mutex</span>(mtx_t mtx);</pre>

<p>The first constructor constructs a <span class="code">mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="mutex::destructor" class="link-target code">mutex::~mutex</span></h4>

<pre><span class="decl">~mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h4><span id="mutex::native_handle" class="link-target code">mutex::native_handle</span></h4>

<pre>native_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="mutex::native_mutex_handle" class="link-target code">mutex::native_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined
set of system functions for operations on the thread managed by this object.</p>

<h3><span id="recursive_mutex" class="link-target code">recursive_mutex</span></h3>

<div class="block menu">
<a href="#recursive_mutex::c_handle" class="code">c_handle</a>
<a href="#recursive_mutex::native_handle" class="code">native_handle</a>
<a href="#recursive_mutex::native_recursive_mutex_handle" class="code">native_recursive_mutex_handle</a>
<a href="#recursive_mutex::recursive_mutex" class="code">recursive_mutex</a>
<a href="#recursive_mutex::~recursive_mutex" class="code">~recursive_mutex</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
</div>

<pre>class <span class="decl">recursive_mutex</span>
    {
public:
    <a href="#recursive_mutex::recursive_mutex" class="code">recursive_mutex</a>();
    <a href="#recursive_mutex::recursive_mutex" class="code">recursive_mutex</a>(mtx_t);
    <a href="#recursive_mutex::~recursive_mutex" class="code">~recursive_mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#recursive_mutex::native_recursive_mutex_handle" class="code">native_recursive_mutex_handle</a>;
    native_recursive_mutex_handle <a href="#recursive_mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#recursive_mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    recursive_mutex(const recursive_mutex&amp;);
    recursive_mutex&amp; operator= (const recursive_mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#lock-object">lock object</a>
to provide a recursive <a href="#intro-mutex">mutex</a>
object. Objects of class <span class="code">recursive_mutex</span> cannot be copied.</p>

<h4><span id="recursive_mutex::c_handle" class="link-target code">recursive_mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="recursive_mutex::native_handle" class="link-target code">recursive_mutex::native_handle</span></h4>

<pre>native_recursive_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="recursive_mutex::native_recursive_mutex_handle" class="link-target code">recursive_mutex::native_recursive_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_recursive_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the thread managed by this object.</p>

<h4><span id="recursive_mutex::recursive_mutex" class="link-target code">recursive_mutex::recursive_mutex</span></h4>

<pre><span class="decl">recursive_mutex</span>();
<span class="decl">recursive_mutex</span>(mtx_t mtx);</pre>

<p>The first constructor constructs a <span class="code">recursive_mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">recursive_mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="recursive_mutex::destructor" class="link-target code">recursive_mutex::~recursive_mutex</span></h4>

<pre><span class="decl">~recursive_mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h3><span id="recursive_timed_mutex" class="link-target code">recursive_timed_mutex</span></h3>

<div class="block menu">
<a href="#recursive_timed_mutex::c_handle" class="code">c_handle</a>
<a href="#recursive_timed_mutex::native_handle" class="code">native_handle</a>
<a href="#recursive_timed_mutex::native_recursive_timed_mutex_handle" class="code">native_recursive_timed_mutex_handle</a>
<a href="#recursive_timed_mutex::recursive_timed_mutex" class="code">recursive_timed_mutex</a>
<a href="#recursive_timed_mutex::~recursive_timed_mutex" class="code">~recursive_timed_mutex</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
<a href="#scoped_timed_lock" class="code">scoped_timed_lock</a>
<a href="#scoped_try_lock" class="code">scoped_try_lock</a>
</div>

<pre>class <span class="decl">recursive_timed_mutex</span>
    {
public:
    <a href="#recursive_timed_mutex::recursive_timed_mutex" class="code">recursive_timed_mutex</a>();
    <a href="#recursive_timed_mutex::recursive_timed_mutex" class="code">recursive_timed_mutex</a>(mtx_t);
    <a href="#recursive_timed_mutex::~recursive_timed_mutex" class="code">~recursive_timed_mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;
    typedef SL1 <a href="#scoped_try_lock" class="code">scoped_try_lock</a>;
    typedef SL2 <a href="#scoped_timed_lock" class="code">scoped_timed_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#recursive_timed_mutex::native_recursive_timed_mutex_handle" class="code">native_recursive_timed_mutex_handle</a>;
    native_thread_handle <a href="#recursive_timed_mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#recursive_timed_mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    recursive_timed_mutex(const recursive_timed_mutex&amp;);
    recursive_timed_mutex&amp; operator= (const recursive_timed_mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#scoped_lock">scoped lock</a>,
a <a href="#scoped_try_lock">scoped try lock</a>
or a <a href="#scoped_timed_lock">scoped timed lock</a>
to provide a recursive <a href="#intro-mutex">mutex</a>
object that supports <a href="#intro-test-and-return">test and return</a>
and <a href="#intro-timeout">timeout</a>.
Objects of class <span class="code">recursive_timed_mutex</span> cannot be copied.</p>

<h4><span id="recursive_timed_mutex::c_handle" class="link-target code">recursive_timed_mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="recursive_timed_mutex::native_handle" class="link-target code">recursive_timed_mutex::native_handle</span></h4>

<pre>native_recursive_timed_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="recursive_timed_mutex::native_recursive_timed_mutex_handle" class="link-target code">recursive_timed_mutex::native_recursive_timed_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_recursive_timed_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the mutex managed by this object.</p>

<h4><span id="recursive_timed_mutex::recursive_timed_mutex" class="link-target code">recursive_timed_mutex::recursive_timed_mutex</span></h4>

<pre><span class="decl">recursive_timed_mutex</span>(mtx_t mtx);
<span class="decl">recursive_timed_mutex</span>();</pre>

<p>The first constructor constructs a <span class="code">recursive_timed_mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">recursive_timed_mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="recursive_timed_mutex::destructor" class="link-target code">recursive_timed_mutex::~recursive_timed_mutex</span></h4>

<pre><span class="decl">~recursive_timed_mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h3><span id="recursive_try_mutex" class="link-target code">recursive_try_mutex</span></h3>

<div class="block menu">
<a href="#recursive_try_mutex::c_handle" class="code">c_handle</a>
<a href="#recursive_try_mutex::native_handle" class="code">native_handle</a>
<a href="#recursive_try_mutex::native_recursive_try_mutex_handle" class="code">native_recursive_try_mutex_handle</a>
<a href="#recursive_try_mutex::recursive_try_mutex" class="code">recursive_try_mutex</a>
<a href="#recursive_try_mutex::~recursive_try_mutex" class="code">~recursive_try_mutex</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
<a href="#scoped_try_lock" class="code">scoped_try_lock</a>
</div>

<pre>class <span class="decl">recursive_try_mutex</span>
    {
public:
    <a href="#recursive_try_mutex::recursive_try_mutex" class="code">recursive_try_mutex</a>();
    <a href="#recursive_try_mutex::recursive_try_mutex" class="code">recursive_try_mutex</a>(mtx_t);
    <a href="#recursive_try_mutex::~recursive_try_mutex" class="code">~recursive_try_mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;
    typedef SL1 <a href="#scoped_try_lock" class="code">scoped_try_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#recursive_try_mutex::native_recursive_try_mutex_handle" class="code">native_recursive_try_mutex_handle</a>;
    native_thread_handle <a href="#recursive_try_mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#recursive_try_mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    recursive_try_mutex(const recursive_try_mutex&amp;);
    recursive_try_mutex&amp; operator= (const recursive_try_mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#scoped_lock">scoped lock</a>
or a <a href="#scoped_try_lock">scoped_try_lock</a>
to provide a recursive <a href="#intro-mutex">mutex</a>
object that supports <a href="#intro-test-and-return">test and return</a>.
Objects of class <span class="code">recursive_try_mutex</span> cannot be copied.</p>

<h4><span id="recursive_try_mutex::c_handle" class="link-target code">recursive_try_mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="recursive_try_mutex::native_handle" class="link-target code">recursive_try_mutex::native_handle</span></h4>

<pre>native_recursive_try_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="recursive_try_mutex::native_recursive_try_mutex_handle" class="link-target code">recursive_try_mutex::native_recursive_try_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_recursive_try_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the mutex managed by this object.</p>

<h4><span id="recursive_try_mutex::recursive_try_mutex" class="link-target code">recursive_try_mutex::recursive_try_mutex</span></h4>

<pre><span class="decl">recursive_try_mutex</span>();
<span class="decl">recursive_try_mutex</span>(mtx_t mtx);</pre>

<p>The first constructor constructs a <span class="code">recursive_try_mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">recursive_try_mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="recursive_try_mutex::destructor" class="link-target code">recursive_try_mutex::~recursive_try_mutex</span></h4>

<pre><span class="decl">~recursive_try_mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h3><span id="scoped_lock" class="link-target code">scoped_lock</span></h3>

<div class="block menu">
<a href="#scoped_lock::lock" class="code">lock</a>
<a href="#scoped_lock::locked" class="code">locked</a>
<a href="#scoped_lock::mutex_type" class="code">mutex_type</a>
<a href="#scoped_lock::operator-const-void-star" class="code">operator const void *</a>
<a href="#scoped_lock::scoped_lock" class="code">scoped_lock</a>
<a href="#scoped_lock::~scoped_lock" class="code">~scoped_lock</a>
<a href="#scoped_lock::unlock" class="code">unlock</a>
</div>

<p>Every mutual exclusion class <span class="code">mtx</span> defines a nested
type <span class="code">mtx::scoped_lock</span> that can be used to create a
<a href="#lock-object">lock object</a> for an object of the type <span class="code">mtx</span>.</p>

<p>A <span id="lock-object" class="link-target">lock object</span> is an object whose constructor
locks an associated mutex object and whose destructor
unlocks the mutex object. Thus, unlocking is
guaranteed in the presence of exceptions.
Lock objects cannot be copied.</p>

<pre>class <span class="decl">mtx::scoped_lock</span>
    {
public:
    typedef mtx <a href="#scoped_lock::mutex_type">mutex_type</a>;

    <a href="#scoped_lock::scoped_lock">scoped_lock</a>(mtx&amp; m);
    <a href="#scoped_lock::scoped_lock">scoped_lock</a>(mtx&amp; m, bool lck);
    <a href="#scoped_lock::~scoped_lock">~scoped_lock</a>();

    <a href="#scoped_lock::operator-const-void-star">operator const void *</a>() const;
    bool <a href="#scoped_lock::locked">locked</a>() const;

    void <a href="#scoped_lock::lock">lock</a>();
    void <a href="#scoped_lock::unlock">unlock</a>();

<span class="non-code">    // exposition only
private:
    mtx&amp; <span class="decl">mm</span>;
    bool <span class="decl">is_locked</span>;

    // not implemented
    scoped_lock::scoped_lock(const scoped_lock&amp;);
    scoped_lock&amp; scoped_lock::operator= (const scoped_lock&amp;);</span>
    };</pre>

<h4><span id="scoped_lock::lock" class="link-target code">scoped_lock::lock</span></h4>

<pre>void <span class="decl">lock</span>();</pre>

<p>The member function locks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">true</span>.</p>

<h4><span id="scoped_lock::locked" class="link-target code">scoped_lock::locked</span></h4>

<pre>bool <span class="decl">locked</span>() const;</pre>

<p>The member function returns the stored value <span class="code">is_locked</span>.</p>

<h4><span id="scoped_lock::mutex_type" class="link-target code">scoped_lock::mutex_type</span></h4>

<pre>typedef mtx <span class="decl">mutex_type</span>;</pre>

<p>The nested type is a synonym for the containing type <span class="code">mtx</span>.</p>

<h4><span id="scoped_lock::operator-const-void-star" class="link-target code">scoped_lock::operator const void *</span></h4>

<pre><span class="decl">operator const void *</span>() const;</pre>

<p>The member function returns 0 if the stored value <span class="code">is_locked</span> is <span class="code">false</span>,
otherwise a non-0 pointer value.</p>

<h4><span id="scoped_lock::scoped_lock" class="link-target code">scoped_lock::scoped_lock</span></h4>

<pre><span class="decl">scoped_lock</span>(mtx&amp; m);
<span class="decl">scoped_lock</span>(mtx&amp; m, bool lck);</pre>

<p>The first constructor constructs a <span class="code">scoped_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span> and then calls <span class="code">lock</span>.</p>

<p>The second constructor constructs a <span class="code">scoped_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span>. If <span class="code">lck</span> is <span class="code">true</span>
the constructor calls <span class="code">lock</span>. Otherwise the
stored value <span class="code">is_locked</span> is set to <span class="code">false</span>.</p>

<h4><span id="scoped_lock::destructor" class="link-target code">scoped_lock::~scoped_lock</span></h4>

<pre><span class="decl">~scoped_lock</span>();</pre>

<p>The destructor calls <span class="code">unlock</span> if the stored value <span class="code">is_locked</span>
is <span class="code">true</span>. Otherwise the destructor does nothing.</p>

<h4><span id="scoped_lock::unlock" class="link-target code">scoped_lock::unlock</span></h4>

<pre>void <span class="decl">unlock</span>();</pre>

<p>The member function unlocks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">false</span>.
Note that if <span class="code">mm</span> is a <a href="#intro-recursive">recursive</a>
mutex unlocking <span class="code">mm</span> doesn't necessarily put <span class="code">mm</span> into
the unlocked state.</p>

<h3><span id="scoped_timed_lock" class="link-target code">scoped_timed_lock</span></h3>

<div class="block menu">
<a href="#scoped_timed_lock::lock" class="code">lock</a>
<a href="#scoped_timed_lock::locked" class="code">locked</a>
<a href="#scoped_timed_lock::mutex_type" class="code">mutex_type</a>
<a href="#scoped_timed_lock::operator-const-void-star" class="code">operator const void *</a>
<a href="#scoped_timed_lock::scoped_timed_lock" class="code">scoped_timed_lock</a>
<a href="#scoped_timed_lock::~scoped_timed_lock" class="code">~scoped_timed_lock</a>
<a href="#scoped_timed_lock::timed_lock" class="code">timed_lock</a>
<a href="#scoped_timed_lock::unlock" class="code">unlock</a>
</div>

<p>A mutual exclusion class <span class="code">mtx</span> that supports
<a href="#intro-timeout">timeout</a>
defines a nested type <span class="code">mtx::scoped_timed_lock</span>
that can be used to create a
<a href="#lock-object">lock object</a> for an object of the type <span class="code">mtx</span>.</p>

<pre>class <span class="decl">mtx::scoped_timed_lock</span>
    {
public:
    typedef mtx <a href="#scoped_timed_lock::mutex_type">mutex_type</a>;

    <a href="#scoped_timed_lock::scoped_timed_lock">scoped_timed_lock</a>(mtx&amp; m, const xtime&amp; xt);
    <a href="#scoped_timed_lock::scoped_timed_lock">scoped_timed_lock</a>(mtx&amp; m, bool lck);
    <a href="#scoped_timed_lock::~scoped_timed_lock">~scoped_timed_lock</a>();

    <a href="#scoped_timed_lock::operator-const-void-star">operator const void *</a>() const;
    bool <a href="#scoped_timed_lock::locked">locked</a>() const;

    void <a href="#scoped_timed_lock::lock">lock</a>();
    bool <a href="#scoped_timed_lock::timed_lock">timed_lock</a>(const xtime&amp; xt);
    void <a href="#scoped_timed_lock::unlock">unlock</a>();

<span class="non-code">    // exposition only
private:
    mtx&amp; <span class="decl">mm</span>;
    bool <span class="decl">is_locked</span>;

    // not implemented
    scoped_timed_lock::scoped_timed_lock(const scoped_timed_lock&amp;);
    scoped_timed_lock&amp; scoped_timed_lock::operator= (const scoped_timed_lock&amp;);</span>
    };</pre>

<h4><span id="scoped_timed_lock::lock" class="link-target code">scoped_timed_lock::lock</span></h4>

<pre>void <span class="decl">lock</span>();</pre>

<p>The member function locks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">true</span>.</p>

<h4><span id="scoped_timed_lock::locked" class="link-target code">scoped_timed_lock::locked</span></h4>

<pre>bool <span class="decl">locked</span>() const;</pre>

<p>The member function returns the stored value <span class="code">is_locked</span>.</p>

<h4><span id="scoped_timed_lock::mutex_type" class="link-target code">scoped_timed_lock::mutex_type</span></h4>

<pre>typedef mtx <span class="decl">mutex_type</span>;</pre>

<p>The nested type is a synonym for the containing type <span class="code">mtx</span>.</p>

<h4><span id="scoped_timed_lock::operator-const-void-star" class="link-target code">scoped_timed_lock::operator const void *</span></h4>

<pre><span class="decl">operator const void *</span>() const;</pre>

<p>The member function returns 0 if the stored value <span class="code">is_locked</span> is <span class="code">false</span>,
otherwise a non-0 pointer value.</p>

<h4><span id="scoped_timed_lock::scoped_timed_lock" class="link-target code">scoped_timed_lock::scoped_timed_lock</span></h4>

<pre><span class="decl">scoped_timed_lock</span>(mtx&amp; m, const xtime&amp; xt);
<span class="decl">scoped_timed_lock</span>(mtx&amp; m, bool lck);</pre>

<p>The first constructor constructs a <span class="code">scoped_timed_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span>, then calls <span class="code">timed_lock(xt)</span>.</p>

<p>The second constructor constructs a <span class="code">scoped_timed_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span>. If <span class="code">lck</span> is <span class="code">true</span>
the constructor calls <span class="code">lock</span>. Otherwise the
stored value <span class="code">is_locked</span> is set to <span class="code">false</span>.</p>

<h4><span id="scoped_timed_lock::destructor" class="link-target code">scoped_timed_lock::~scoped_timed_lock</span></h4>

<pre><span class="decl">~scoped_timed_lock</span>();</pre>

<p>The destructor calls <span class="code">unlock</span> if the stored value <span class="code">is_locked</span>
is <span class="code">true</span>. Otherwise the destructor does nothing.</p>

<h4><span id="scoped_timed_lock::timed_lock" class="link-target code">scoped_timed_lock::timed_lock</span></h4>

<pre>bool <span class="decl">timed_lock</span>(const xtime&amp; xt);</pre>

<p>The member function attempts to lock the stored mutual exclusion object <span class="code">mm</span>,
using its <a href="#intro-timeout">timeout</a> mechanism to avoid blocking beyond the time
specified by the <a href="#xtime">xtime</a> object <span class="code">xt</span>,
sets the stored value <span class="code">is_locked</span> to <span class="code">true</span> if the lock
attempt was successful or <span class="code">false</span> if it was not usccessful,
and returns the stored value <span class="code">is_locked</span>.</p>

<h4><span id="scoped_timed_lock::unlock" class="link-target code">scoped_timed_lock::unlock</span></h4>

<pre>void <span class="decl">unlock</span>();</pre>

<p>The member function unlocks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">false</span>. Note that if
<span class="code">mm</span> is a <a href="#intro-recursive">recursive</a> mutex unlocking
<span class="code">mm</span> doesn't necessarily put <span class="code">mm</span> into the unlocked state.</p>

<h3><span id="scoped_try_lock" class="link-target code">scoped_try_lock</span></h3>

<div class="block menu">
<a href="#scoped_try_lock::lock" class="code">lock</a>
<a href="#scoped_try_lock::locked" class="code">locked</a>
<a href="#scoped_try_lock::mutex_type" class="code">mutex_type</a>
<a href="#scoped_try_lock::operator-const-void-star" class="code">operator const void *</a>
<a href="#scoped_try_lock::scoped_try_lock" class="code">scoped_try_lock</a>
<a href="#scoped_try_lock::~scoped_try_lock" class="code">~scoped_try_lock</a>
<a href="#scoped_try_lock::try_lock" class="code">try_lock</a>
<a href="#scoped_try_lock::unlock" class="code">unlock</a>
</div>

<p>A mutual exclusion class <span class="code">mtx</span> that supports
<a href="#intro-test-and-return">test and return</a>
defines a nested type <span class="code">mtx::scoped_try_lock</span>
that can be used to create a
<a href="#lock-object">lock object</a> for an object of the type <span class="code">mtx</span>.</p>

<pre>class <span class="decl">mtx::scoped_try_lock</span>
    {
public:
    typedef mtx <a href="#scoped_try_lock::mutex_type">mutex_type</a>;

    <a href="#scoped_try_lock::scoped_try_lock">scoped_try_lock</a>(mtx&amp; m);
    <a href="#scoped_try_lock::scoped_try_lock">scoped_try_lock</a>(mtx&amp; m, bool lck);
    <a href="#scoped_try_lock::~scoped_try_lock">~scoped_try_lock</a>();

    <a href="#scoped_try_lock::operator-const-void-star">operator const void *</a>() const;
    bool <a href="#scoped_try_lock::locked">locked</a>() const;

    void <a href="#scoped_try_lock::lock">lock</a>();
    bool <a href="#scoped_try_lock::try_lock">try_lock</a>();
    void <a href="#scoped_try_lock::unlock">unlock</a>();

<span class="non-code">    // exposition only
private:
    mtx&amp; <span class="decl">mm</span>;
    bool <span class="decl">is_locked</span>;

    // not implemented
    scoped_try_lock::scoped_try_lock(const scoped_try_lock&amp;);
    scoped_try_lock&amp; scoped_try_lock::operator= (const scoped_try_lock&amp;);</span>
    };</pre>

<h4><span id="scoped_try_lock::lock" class="link-target code">scoped_try_lock::lock</span></h4>

<pre>void <span class="decl">lock</span>();</pre>

<p>The member function locks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">true</span>.</p>

<h4><span id="scoped_try_lock::locked" class="link-target code">scoped_try_lock::locked</span></h4>

<pre>bool <span class="decl">locked</span>() const;</pre>

<p>The member function returns the stored value <span class="code">is_locked</span>.</p>

<h4><span id="scoped_try_lock::mutex_type" class="link-target code">scoped_try_lock::mutex_type</span></h4>

<pre>typedef mtx <span class="decl">mutex_type</span>;</pre>

<p>The nested type is a synonym for the containing type <span class="code">mtx</span>.</p>

<h4><span id="scoped_try_lock::operator-const-void-star" class="link-target code">scoped_try_lock::operator const void *</span></h4>

<pre><span class="decl">operator const void *</span>() const;</pre>

<p>The member function returns 0 if the stored value <span class="code">is_locked</span> is <span class="code">false</span>,
otherwise a non-0 pointer value.</p>

<h4><span id="scoped_try_lock::scoped_try_lock" class="link-target code">scoped_try_lock::scoped_try_lock</span></h4>

<pre><span class="decl">scoped_try_lock</span>(mtx&amp; m);
<span class="decl">scoped_try_lock</span>(mtx&amp; m, bool lck);</pre>

<p>The first constructor constructs a <span class="code">scoped_try_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span>, then calls <span class="code">try_lock</span>.</p>

<p>The second constructor constructs a <span class="code">scoped_try_lock</span> object with stored
value <span class="code">mm</span> set to <span class="code">m</span>. If <span class="code">lck</span> is <span class="code">true</span>
the constructor calls <span class="code">lock</span>. Otherwise the
stored value <span class="code">is_locked</span> is set to <span class="code">false</span>.</p>

<h4><span id="scoped_try_lock::destructor" class="link-target code">scoped_try_lock::~scoped_try_lock</span></h4>

<pre><span class="decl">~scoped_try_lock</span>();</pre>

<p>The destructor calls <span class="code">unlock</span> if the stored value <span class="code">is_locked</span>
is <span class="code">true</span>. Otherwise the destructor does nothing.</p>

<h4><span id="scoped_try_lock::try_lock" class="link-target code">scoped_try_lock::try_lock</span></h4>

<pre>bool <span class="decl">try_lock</span>();</pre>

<p>The member function attempts to lock the stored mutual exclusion object <span class="code">mm</span>,
using its <a href="#intro-test-and-return">test and return</a> mechanism,
sets the stored value <span class="code">is_locked</span> to <span class="code">true</span> if
the lock attempt was successful or <span class="code">false</span> if it was not
successful, and returns the stored value <span class="code">is_locked</span>.</p>

<h4><span id="scoped_try_lock::unlock" class="link-target code">scoped_try_lock::unlock</span></h4>

<pre>void <span class="decl">unlock</span>();</pre>

<p>The member function unlocks the stored mutual exclusion object <span class="code">mm</span>
and sets the stored value <span class="code">is_locked</span> to <span class="code">false</span>. Note that if
<span class="code">mm</span> is a <a href="#intro-recursive">recursive</a> mutex unlocking
<span class="code">mm</span> doesn't necessarily put <span class="code">mm</span> into the unlocked state.</p>

<h3><span id="sleep" class="link-target code">sleep</span></h3>

<pre>void <span class="decl">sleep</span>(const xtime&amp; xt);</pre>

<p>The function blocks the calling thread
at least until the time specified by the <a href="#xtime">xtime</a>
object <span class="code">xt</span>.</p>

<h3><span id="thread" class="link-target code">thread</span></h3>

<div class="block menu">
<a href="#thread::c_handle" class="code">c_handle</a>
<a href="#thread::cancel" class="code">cancel</a>
<a href="#thread::cancellation_requested" class="code">cancellation_requested</a>
<a href="#thread::detach" class="code">detach</a>
<a href="#thread::get_id" class="code">get_id</a>
<a href="#thread::hardware_concurrency" class="code">hardware_concurrency</a>
<a href="#thread::id" class="code">thread::id</a>
<a href="#thread::join" class="code">join</a>
<a href="#thread::joinable" class="code">joinable</a>
<a href="#thread::native_handle" class="code">native_handle</a>
<a href="#thread::native_thread_handle" class="code">native_thread_handle</a>
<a href="#thread::operator-call" class="code">operator()</a>
<a href="#thread::operator-equal" class="code">operator=</a>
<a href="#operator-not-equal-id" class="code">operator!=</a>
<a href="#operator-equal-equal-id" class="code">operator==</a>
<a href="#thread::swap" class="code">swap</a>
<a href="#thread::thread" class="code">thread</a>
<a href="#thread::dtor" class="code">~thread</a>
</div>

<pre>class <span class="decl">thread</span>
    {
public:
    <a href="#thread::thread" class="code">thread</a>();
    template &lt;class Func&gt;
        explicit <a href="#thread::thread" class="code">thread</a>(Func func);
    <a href="#thread::thread" class="code">thread</a>(thread&amp;&amp;);
    <a href="#thread::thread" class="code">thread</a>(thrd_t);
    <a href="#thread::dtor" class="code">~thread</a>();
    thread&amp; <a href="#thread::operator-equal" class="code">operator=</a>(thread&amp;&amp;);

    void <a href="#thread::swap" class="code">swap</a>(thread&amp;);

    void <a href="#thread::detach" class="code">detach</a>();
    void <a href="#thread::join" class="code">join</a>();
    void <a href="#thread::operator-call" class="code">operator()</a>();
    bool <a href="#thread::joinable" class="code">joinable</a>() const;

    void <a href="#thread::cancel" class="code">cancel</a>();
    bool <a href="#thread::cancellation_requested" class="code">cancellation_requested</a>() const;

    class <a href="#thread::id" class="code">id</a>
        {
    public:
        <a href="#thread::id::id" class="code">id</a>() throw();
        };

    id <a href="#thread::get_id" class="code">get_id</a>() const;

    typedef <span class="non-code">unspecified</span> <a href="#thread::native_thread_handle" class="code">native_thread_handle</a>;
    native_thread_handle <a href="#thread::native_handle" class="code">native_handle</a>() const;
    thrd_t <a href="#thread::c_handle" class="code">c_handle</a>() const;

    static unsigned <a href="#thread::hardware_concurrency" class="code">hardware_concurrency</a>();

<span class="non-code">    // exposition only
private:

    // not implemented
    thread(const thread&amp;);
    thread&amp; operator= (const thread&amp;);</span>
    };</pre>

<p>The class <span class="code">thread</span> describes an object for observing the state of a thread
(<a href="#thread::join">join</a>) and managing the state of the current
Objects of class <span class="code">thread</span> cannot be copied.</p>

<p>A <span class="code">thread</span> object is <span id="joinable" class="link-target">joinable</span>
if the application has not made a call to <a
href="#thread::join">thread::join</a> for that object, has not made a
call to <a href="#thread::detach">thread::detach</a> for that object,
and has not made a call to
<a href="#thread_group::join_all">thread_group::join_all</a> for a
<span class="code">thread_group</span> object observing that thread object.</p>

<h4><span id="thread::c_handle" class="link-target code">thread::c_handle</span></h4>

<pre>thrd_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#thrd_t" class="code">thrd_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this thread object.</p>

<h4><span id="thread::cancel" class="link-target code">thread::cancel</span></h4>

<pre>void <span class="decl">cancel</span>();</pre>

<p>The member function makes a cancellation request for the thread controlled by this
<span class="code">thread</span> object.</p>

<h4><span id="thread::cancellation_requested" class="link-target code">thread::cancellation_requested</span></h4>

<pre>bool <span class="decl">cancellation_requested</span>() const;</pre>

<p>The member function returns true if there is an unhandled cancellation request
for the thread controlled by this <span class="code">thread</span> object.</p>

<h4><span id="thread::detach" class="link-target code">thread::detach</span></h4>

<pre>void <span class="decl">detach</span>();</pre>

<p>The member function detaches the <span class="code">thread</span> object
from the thread that it manages. After the call, the <span class="code">thread</span>
does not manage any object.</p>

<h4><span id="thread::get_id" class="link-target code">thread::get_id</span></h4>

<pre>thread::id <span class="decl">get_id</span>();</pre>

<p>The member function returns an object that uniquely identifies the thread
managed by this <span class="code">thread</span> object if that thread has not been
detached; otherwise it returns <span class="code">id()</span>.</p>

<h4><span id="thread::hardware_concurrency" class="link-target code">thread::hardware_concurrency</span></h4>

<pre>unsigned <span class="decl">thread::hardware_concurrency</span>() throw();</pre>

<p>The static member function returns a measure of the number of threads which
could possibly execute concurrently. On platforms where this value cannot be
computed or is not well defined the function should return 1.</p>

<h4><span id="thread::join" class="link-target code">thread::join</span><br />
<span id="thread::operator-call" class="link-target">thread::operator()</span></h4>

<pre>void <span class="decl">join</span>();
void <span class="decl">operator()</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must be <a href="#joinable">joinable</a>.</p>

<p>The member functions mark this <span class="code">thread</span> object
as non-joinable then block until the thread observed by this
<span class="code">thread</span> object terminates.</p>

<h4><span id="thread::joinable" class="link-target code">thread::joinable</span></h4>

<pre>bool <span class="decl">joinable</span>() const;</pre>

<p>The member function returns true only if this <span class="code">thread</span>
object is <a href="#joinable">joinable</a>.</p>

<h4><span id="thread::native_handle" class="link-target code">native_handle</span></h4>

<pre>native_thread_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the thread managed by this object.</p>

<h4><span id="thread::native_thread_handle" class="link-target code">native_thread_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_thread_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the thread managed by this object.</p>

<h4><span id="thread::operator-equal" class="link-target code">thread::operator=</span></h4>

<pre>thread&amp; <span class="decl">operator=</span> (thread&amp;&amp; other);</pre>

<p>The member operator copies the state of <span class="code">other</span>
into <span class="code">*this</span> and leaves
<span class="code">other</span> in a default-constructed state.</p>

<h4><span id="thread::swap" class="link-target code">thread::swap</span></h4>

<pre>void <span class="decl">swap</span>(thread&amp; other);</pre>

<p>Swaps the state of <span class="code">*this</span> and
<span class="code">other</span>.</p>

<h4><span id="thread::thread" class="link-target code">thread::thread</span></h4>

<pre><span class="decl">thread</span>();
template&lt;class Func&gt;
    explicit <span class="decl">thread</span>(Func func);
<span class="decl">thread</span>(thread&amp;&amp; other);
<span class="decl">thread</span>(thrd_t thr);</pre>

<p>The first constructor constructs a
<span class="code">thread</span> object that does not observes any thread.</p>

<p>The second constructor constructs a <a href="#joinable">joinable</a>
<span class="code">thread</span> object that observes a new thread
executing <span class="code">func()</span>, where <span class="code">func</span>
is the name of a function that takes no arguments and returns void, or
the name of an object of a class that provides an <span class="code">operator()</span>
that takes no arguments and returns void. The constructor does not return
until the new thread has begun execution.</p>

<p>The third constructor constructs a <span class="code">thread</span> object
in the same state as <span class="code">other</span> and leaves
<span class="code">other</span> in a default-constructed state.</p>

<p>The fourth constructor constructs a <span class="code">thread</span> object
that manages the thread managed by <span class="code">thrd</span>. After the
call, <span class="code">thrd</span> does not manage any thread.</p>

<h4><span id="thread::dtor" class="link-target code">thread::~thread</span></h4>

<pre><span class="decl">~thread</span>();</pre>

<p>If the <span class="code">thread</span> object manages a thread and that thread is
<a href="#joinable">joinable</a>, the destructor calls
<a href="#thread::cancel" class="code">cancel()</a>
and then calls <a href="#thread::detach" class="code">detach()</a>. Otherwise,
it does nothing.</p>

<h4><span id="thread::id" class="link-target code">thread::id::id</span></h4>

<pre><span class="decl">id</span>() throw();</pre>

<p>The constructor constructs an object of type <span class="code">id</span>.</p>

<h4><span id="operator-equal-equal-id" class="link-target code">operator==</span></h4>

<pre>bool <span class="decl">operator==</span>(const thread::id&amp; left, const thread&amp; right);</pre>

<p>The function returns true only if <span class="code">left</span> and <span class="code">right</span> were
both constructed with the default constructor or if <span class="code">left</span> and
<span class="code">right</span> refer to the same thread.</p>

<h4><span id="operator-not-equal-id" class="link-target code">operator!=</span></h4>

<pre>bool <span class="decl">operator!=</span>(const thread::id&amp; left, const thread&amp; right);</pre>

<p>The function returns <span class="code">!(left == right)</span>.</p>

<h3><span id="thread_canceled" class="link-target code">thread_canceled</span></h3>

<div class="block menu">
<a href="#thread_canceled::thread_canceled" class="code">thread_canceled</a>
<a href="#thread_canceled::what" class="code">what</a>
</div>

<pre>class <span class="decl">thread_canceled</span>
    {
public:
    <a href="#thread_canceled::thread_canceled" class="code">thread_canceled</a>() throw();
    virtual <a href="#thread_canceled::destructor" class="code">~thread_canceled</a>() throw();
    virtual const char *<a href="#thread_canceled::what" class="code">what</a>() const throw();
    };</pre>

<p>The class describes an exception thrown to indicate that the thread in which it
was thrown is being cancelled.</p>

<h4><span id="thread_canceled::thread_canceled" class="link-target code">thread_canceled::thread_canceled</span></h4>

<pre><span class="decl">thread_canceled</span>();</pre>

<p>The constructor constructs an object of type <span class="code">thread_canceled</span>.</p>

<h4><span id="thread_canceled::destructor" class="link-target code">thread_canceled::~thread_canceled</span></h4>

<pre><span class="decl">~thread_canceled</span>();</pre>

<p>The destructor destroys an object of type <span class="code">thread_canceled</span>.</p>

<h4><span id="thread_canceled::what" class="link-target code">thread_canceled::what</span></h4>

<pre>const char *<span class="decl">what</span>() const throw();</pre>

<p>The member function returns an implementation-defined NTBS.</p>

<p>The message may be a null-terminated miltibyte string, suitable for
conversion and display as a <span class="code">wstring</span>. The return value
remains valid until the object from which it is obtained is destroyed or
a non-const member function of the object is called.</p>

<h3><span id="thread_group" class="link-target code">thread_group</span></h3>

<div class="block menu">
<a href="#thread_group::add_thread" class="code">add_thread</a>
<a href="#thread_group::create_thread" class="code">create_thread</a>
<a href="#thread_group::join_all" class="code">join_all</a>
<a href="#thread_group::remove_thread" class="code">remove_thread</a>
<a href="#thread_group::thread_group" class="code">thread_group</a>
<a href="#thread_group::~thread_group" class="code">~thread_group</a>
</div>

<pre>class <span class="decl">thread_group</span>
    {
public:
    <a href="#thread_group::thread_group" class="code">thread_group</a>();
    <a href="#thread_group::~thread_group" class="code">~thread_group</a>();

    template &lt;class Func&gt;
        thread *<a href="#thread_group::create_thread" class="code">create_thread</a>(Func func);

    void <a href="#thread_group::add_thread" class="code">add_thread</a>(thread *thrd);
    void <a href="#thread_group::remove_thread" class="code">remove_thread</a>(thread *thrd);
    void <a href="#thread_group::join_all" class="code">join_all</a>();

<span class="non-code">    // exposition only
private:

    // not implemented
    thread_group(const thread_group&amp;);
    thread_group&amp; operator= (const thread_group&amp;);</span>
    };</pre>

<p>The class describes an object for observing the states of multiple objects
of class <span class="code">thread</span> (<a href="#thread_group::join_all">join_all</a>)
without having to observe each of the threads individually. Objects of class
<span class="code">thread</span> to be observed by a <span class="code">thread_group</span> object must
be created with <span class="code">new</span>; they will be destroyed by the
<span class="code">thread_group</span> object's destructor.
Objects of class <span class="code">thread_group</span> cannot be copied.</p>

<h4><span id="thread_group::add_thread" class="link-target code">thread_group::add_thread</span></h4>

<pre>void <span class="decl">add_thread</span>(thread *thrd);</pre>

<p><span class="reqmt">Requires</span>
<span class="code">*thrd</span> must be <a href="#joinable">joinable</a>.</p>

<p>The member function adds <span class="code">*thrd</span> to the group of <span class="code">thread</span>
objects observed by the <span class="code">thread_group</span> object. Calling <span class="code">add_thread</span>
with a <span class="code">thread</span> object that is already in the group does nothing.</p>

<h4><span id="thread_group::create_thread" class="link-target code">thread_group::create_thread</span></h4>

<pre>template &lt;class Func&gt;
    thread *<span class="decl">create_thread</span>(Func func);</pre>

<p>The member function calls <span class="code">thread *res = new thread(func)</span>, and if
the call succeeds calls <span class="code">add_thread(res)</span>. It returns <span class="code">res</span>.</p>

<h4><span id="thread_group::join_all" class="link-target code">thread_group::join_all</span></h4>

<pre>void <span class="decl">join_all</span>();</pre>

<p>The member function effectively calls
<span class="code">thr.join()</span> for each <span class="code">thread</span> object <span class="code">thr</span>
in the group of <span class="code">thread</span> objects observed by the <span class="code">thread_group</span>
object.</p>

<h4><span id="thread_group::remove_thread" class="link-target code">thread_group::remove_thread</span></h4>

<pre>void <span class="decl">remove_thread</span>(thread *thrd);</pre>

<p>The member function removes <span class="code">*thrd</span> from the group of <span class="code">thread</span>
objects observed by the <span class="code">thread_group</span> object. If <span class="code">*thrd</span>
is not in the group the function does nothing.</p>

<h4><span id="thread_group::thread_group" class="link-target code">thread_group::thread_group</span></h4>

<pre><span class="decl">thread_group</span>();</pre>

<p>The constructor constructs a <span class="code">thread_group</span> object with an empty
group of <span class="code">thread</span> objects.</p>

<h4><span id="thread_group::destructor" class="link-target code">thread_group::~thread_group</span></h4>

<pre><span class="decl">~thread_group</span>();</pre>

<p>The destructor effectively executes <span class="code">delete thrd</span> for every <span class="code">thread</span>
object <span class="code">*thrd</span> in the group.</p>

<h3><span id="thread_resource_error" class="link-target code">thread_resource_error</span></h3>

<pre>class <span class="decl">thread_resource_error</span>
    : public std::runtime_error
    {
public:
    thread_resource_error();
    };</pre>

<p>The class describes an exception thrown to indicate that an attempted
operation failed because a required resource other than memory was not available.</p>

<h3><span id="thread_specific_ptr" class="link-target code">thread_specific_ptr</span></h3>

<div class="block menu">
<a href="#thread_specific_ptr::c_handle" class="code">c_handle</a>
<a href="#thread_specific_ptr::get" class="code">get</a>
<a href="#thread_specific_ptr::native_handle" class="code">native_handle</a>
<a href="#thread_specific_ptr::native_tss_handle" class="code">native_tss_handle</a>
<a href="#thread_specific_ptr::operator-arrow" class="code">operator-&gt;</a>
<a href="#thread_specific_ptr::operator*" class="code">operator*</a>
<a href="#thread_specific_ptr::release" class="code">release</a>
<a href="#thread_specific_ptr::reset" class="code">reset</a>
<a href="#thread_specific_ptr::thread_specific_ptr" class="code">thread_specific_ptr</a>
<a href="#thread_specific_ptr::~thread_specific_ptr" class="code">~thread_specific_ptr</a>
</div>

<pre>template &lt;class T&gt;
class <span class="decl">thread_specific_ptr</span>
    {
public:
    <a href="#thread_specific_ptr::thread_specific_ptr" class="code">thread_specific_ptr</a>();
    <a href="#thread_specific_ptr::thread_specific_ptr" class="code">thread_specific_ptr</a>(tss_t);
    <a href="#thread_specific_ptr::~thread_specific_ptr" class="code">~thread_specific_ptr</a>();

    T *<a href="#thread_specific_ptr::get" class="code">get</a>() const;
    T *<a href="#thread_specific_ptr::operator-arrow" class="code">operator-&gt;</a>() const;
    T&amp; <a href="#thread_specific_ptr::operator*" class="code">operator*</a>() const;
    T *<a href="#thread_specific_ptr::release" class="code">release</a>();
    void <a href="#thread_specific_ptr::reset" class="code">reset</a>(T *ptr = 0);

    typedef <span class="non-code">unspecified</span> <a href="#thread_specific_ptr::native_tss_handle" class="code">native_tss_handle</a>;
    native_tss_handle <a href="#thread_specific_ptr::native_handle" class="code">native_handle</a>() const;
    tss_t <a href="#thread_specific_ptr::c_handle" class="code">c_handle</a>() const;

    // exposition only
private:
    T *<span class="decl">data</span>;

    // not implemented
    thread_specific_ptr::thread_specific_ptr(const thread_specific_ptr&amp;);
    thread_specific_ptr&lt;T&gt;&amp; thread_specific_ptr::operator= (const thread_specific_ptr&lt;T&gt;&amp;);
    };</pre>

<p>The template class describes an object that controls
<a href="#Thread-specific-Storage">thread-specific storage</a> for a
data object of type <span class="code">T</span> or of a type derived from <span class="code">T</span>.
The template holds a pointer <span class="code">data</span> of type <span class="code">T*</span>;
the stored value <span class="code">data</span> can be different in different threads,
so threads can use different data objects,
accessed through the same <span class="code">thread_specific_ptr</span> object.
Objects of class <span class="code">thread_specific_ptr&lt;T&gt;</span> cannot be copied.</p>

<h4><span id="thread_specific_ptr::c_handle" class="link-target code">thread_specific_ptr::c_handle</span></h4>

<pre>tss_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#tss_t" class="code">tss_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this thread-specific storage object.</p>

<h4><span id="thread_specific_ptr::get" class="link-target code">thread_specific_ptr::get</span></h4>

<pre>T *<span class="decl">get</span>() const;</pre>

<p>The member function returns the thread-specific stored value <span class="code">data</span>.</p>

<h4><span id="thread_specific_ptr::native_handle" class="link-target code">thread_specific_ptr::native_handle</span></h4>

<pre>native_tss_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the thread-specific storage managed by this object.</p>

<h4><span id="thread_specific_ptr::native_tss_handle" class="link-target code">thread_specific_ptr::native_tss_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_tss_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the thread-specific storage managed by this object.</p>

<h4><span id="thread_specific_ptr::operator-arrow" class="link-target code">thread_specific_ptr::operator-&gt;</span></h4>

<pre>T *<span class="decl">operator-&gt;</span>() const;</pre>

<p><span class="reqmt">Requires</span>
<span class="code">get() != 0</span>.</p>

<p>The member function returns the thread-specific stored value <span class="code">data</span>.</p>

<h4><span id="thread_specific_ptr::operator-star" class="link-target code">thread_specific_ptr::operator*</span></h4>

<pre>T&amp; <span class="decl">operator*</span>() const;</pre>

<p><span class="reqmt">Requires</span>
<span class="code">get() != 0</span>.</p>

<p>The member function returns <span class="code">*get()</span>.</p>

<h4><span id="thread_specific_ptr::release" class="link-target code">thread_specific_ptr::release</span></h4>

<pre>T *<span class="decl">release</span>();</pre>

<p>The member function sets the thread-specific stored value <span class="code">data</span> to 0
and returns the previous value of the stored value <span class="code">data</span>.</p>

<h4><span id="thread_specific_ptr::reset" class="link-target code">thread_specific_ptr::reset</span></h4>

<pre>void <span class="decl">reset</span>(T *ptr = 0);</pre>

<p>The member function does nothing if the thread-specific stored value <span class="code">data</span>
equals <span class="code">ptr</span>; otherwise it
deletes the thread-specific stored value <span class="code">data</span> and
sets the thread-specific stored value <span class="code">data</span> to <span class="code">ptr</span>.</p>

<h4><span id="thread_specific_ptr::thread_specific_ptr" class="link-target code">thread_specific_ptr::thread_specific_ptr</span></h4>

<pre><span class="decl">thread_specific_ptr</span>();
<span class="decl">thread_specific_ptr</span>(tss_t tss);</pre>

<p>The first constructor constructs a <span class="code">thread_specific_ptr&lt;T&gt;</span>
object with initial stored value <span class="code">data</span> equal to
0 for all threads. The second constructor constructs a
<span class="code">thread_specific_ptr&lt;T&gt;</span> that points to the same
thread-specific storage as <span class="code">tss</span>.</p>

<h4><span id="thread_specific_ptr::destructor" class="link-target code">thread_specific_ptr::~thread_specific_ptr</span></h4>

<pre><span class="decl">~thread_specific_ptr</span>();</pre>

<p>The destructor frees resources used by the object. It does not delete thread-specific
data pointers.</p>

<h3><span id="timed_mutex" class="link-target code">timed_mutex</span></h3>

<div class="block menu">
<a href="#timed_mutex::c_handle" class="code">c_handle</a>
<a href="#timed_mutex::native_handle" class="code">native_handle</a>
<a href="#timed_mutex::native_timed_mutex_handle" class="code">native_timed_mutex_handle</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
<a href="#scoped_timed_lock" class="code">scoped_timed_lock</a>
<a href="#scoped_try_lock" class="code">scoped_try_lock</a>
<a href="#timed_mutex::timed_mutex" class="code">timed_mutex</a>
<a href="#timed_mutex::~timed_mutex" class="code">~timed_mutex</a>
</div>

<pre>class <span class="decl">timed_mutex</span>
    {
public:
    <a href="#timed_mutex::timed_mutex" class="code">timed_mutex</a>();
    <a href="#timed_mutex::timed_mutex" class="code">timed_mutex</a>(mtx_t);
    <a href="#timed_mutex::~timed_mutex" class="code">~timed_mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;
    typedef SL1 <a href="#scoped_try_lock" class="code">scoped_try_lock</a>;
    typedef SL2 <a href="#scoped_timed_lock" class="code">scoped_timed_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#timed_mutex::native_timed_mutex_handle" class="code">native_timed_mutex_handle</a>;
    native_thread_handle <a href="#timed_mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#timed_mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    timed_mutex(const timed_mutex&amp;);
    timed_mutex&amp; operator= (const timed_mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#scoped_lock">scoped lock</a>,
a <a href="#scoped_try_lock">scoped try lock</a>
or a <a href="#scoped_timed_lock">scoped timed lock</a>
to provide a non-recursive <a href="#intro-mutex">mutex</a>
that supports <a href="#intro-test-and-return">test and return</a>
and <a href="#intro-timeout">timeout</a>.
Objects of class <span class="code">timed_mutex</span> cannot be copied.</p>

<h4><span id="timed_mutex::c_handle" class="link-target code">timed_mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="timed_mutex::native_handle" class="link-target code">timed_mutex::native_handle</span></h4>

<pre>native_timed_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="timed_mutex::native_timed_mutex_handle" class="link-target code">timed_mutex::native_timed_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_timed_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the mutex managed by this object.</p>

<h4><span id="timed_mutex::timed_mutex" class="link-target code">timed_mutex::timed_mutex</span></h4>

<pre><span class="decl">timed_mutex</span>();
<span class="decl">timed_mutex</span>(mtx_t mtx);</pre>

<p>The first constructor constructs a <span class="code">timed_mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">timed_mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="timed_mutex::destructor" class="link-target code">timed_mutex::~timed_mutex</span></h4>

<pre><span class="decl">~timed_mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h3><span id="try_mutex" class="link-target code">try_mutex</span></h3>

<div class="block menu">
<a href="#try_mutex::c_handle" class="code">c_handle</a>
<a href="#try_mutex::native_handle" class="code">native_handle</a>
<a href="#try_mutex::native_try_mutex_handle" class="code">native_try_mutex_handle</a>
<a href="#scoped_lock" class="code">scoped_lock</a>
<a href="#scoped_try_lock" class="code">scoped_try_lock</a>
<a href="#try_mutex::try_mutex" class="code">try_mutex</a>
<a href="#try_mutex::~try_mutex" class="code">~try_mutex</a>
</div>

<pre>class <span class="decl">try_mutex</span>
    {
public:
    <a href="#try_mutex::try_mutex" class="code">try_mutex</a>();
    <a href="#try_mutex::try_mutex" class="code">try_mutex</a>(mtx_t);
    <a href="#try_mutex::~try_mutex" class="code">~try_mutex</a>();
    typedef SL0 <a href="#scoped_lock" class="code">scoped_lock</a>;
    typedef SL1 <a href="#scoped_try_lock" class="code">scoped_try_lock</a>;

    typedef <span class="non-code">unspecified</span> <a href="#try_mutex::native_try_mutex_handle" class="code">native_try_mutex_handle</a>;
    native_thread_handle <a href="#try_mutex::native_handle" class="code">native_handle</a>() const;
    mtx_t <a href="#try_mutex::c_handle" class="code">c_handle</a>() const;

<span class="non-code">    // exposition only
private:
    // not implemented
    try_mutex(const try_mutex&amp;);
    try_mutex&amp; operator= (const try_mutex&amp;);</span>
    };</pre>

<p>The class describes an object that
can be used with a <a href="#scoped_lock">scoped lock</a>
or a <a href="#scoped_try_lock">scoped try lock</a>
to provide a non-recursive <a href="#intro-mutex">mutex</a>
that supports <a href="#intro-test-and-return">test and return</a>.
Objects of class <span class="code">try_mutex</span> cannot be copied.</p>

<h4><span id="try_mutex::c_handle" class="link-target code">try_mutex::c_handle</span></h4>

<pre>mtx_t <span class="decl">c_handle</span>() const;</pre>

<p>The member function returns an object of type
<a href="#mtx_t" class="code">mtx_t</a> that can be passed to functions in the
<a href="#C-Interface">C interface</a> for operations on this mutex.</p>

<h4><span id="try_mutex::native_handle" class="link-target code">try_mutex::native_handle</span></h4>

<pre>native_try_mutex_handle <span class="decl">native_handle</span>() const;</pre>

<p>The member function returns an object that can be passed to an implementation-defined
set of system functions for operations on the mutex managed by this object.</p>

<h4><span id="try_mutex::native_try_mutex_handle" class="link-target code">try_mutex::native_try_mutex_handle</span></h4>

<pre>typedef <span class="non-code">unspecified</span> <span class="decl">native_try_mutex_handle</span>;</pre>

<p>The typedef names a type for objects that can be passed to an implementation-defined set of
system functions for operations on the mutex managed by this object.</p>

<h4><span id="try_mutex::try_mutex" class="link-target code">try_mutex::try_mutex</span></h4>

<pre><span class="decl">try_mutex</span>();
<span class="decl">try_mutex</span>(mtx_t mtx);</pre>

<p>The first constructor constructs a <span class="code">try_mutex</span>
in the unlocked state. The second constructor constructs a
<span class="code">try_mutex</span> in the same state as
<span class="code">mtx</span>.</p>

<h4><span id="try_mutex::destructor" class="link-target code">try_mutex::~try_mutex</span></h4>

<pre><span class="decl">~try_mutex</span>();</pre>

<p><span class="reqmt">Requires</span>
the object must not be locked.</p>

<p>The destructor releases any resources used by the object.</p>

<h3><span id="yield" class="link-target code">yield</span></h3>

<pre>void <span class="decl">yield</span>();</pre>

<p>The function requests the runtime system to put the
calling thread at the back of the execution queue for threads
with the same priority as the calling thread.</p>
</div>

<div class="copyright">
<p>Copyright &#169; 2007 by Roundhouse Consulting, Ltd. Permission is granted
to use this document for standardization purposes.</p>

<p>This document is derived
in part from <cite>A Multi-threading Library for Standard C++, Revision 1,
Copyright &#169; 2002-2005 by Dinkumware, Ltd.</cite></p>

<p>That document is, in turn, derived in part from a document bearing
the following restrictions:</p>

<p>&#169; Copyright William E. Kempf 2001</p>

<p>Permission to use, copy, modify, distribute and sell this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice appear in all copies and that both that copyright notice
and this permission notice appear in supporting documentation.
William E. Kempf makes no representations about the suitability of this software
for any purpose. It is provided "as is" without express or implied warranty.</p>
</div>

</body>
</html>
