mirror of
https://github.com/boostorg/thread.git
synced 2026-01-23 06:02:14 +00:00
Boost.Threads documentation updates.
[SVN r13439]
This commit is contained in:
William E. Kempf
409
doc/mutex.html
409
doc/mutex.html
@@ -1,159 +1,129 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content=
|
||||
"text/html; charset=iso-8859-1">
|
||||
<meta name="keywords" content="threads, BTL, thread library, C++">
|
||||
<link rel="stylesheet" type="text/css" href="styles.css">
|
||||
|
||||
<title>Boost.Threads, mutex</title>
|
||||
</head>
|
||||
|
||||
<body bgcolor="#ffffff" link="#0000ff" vlink="#800080">
|
||||
<table summary="header" border="0" cellpadding="7" cellspacing="0"
|
||||
width="100%">
|
||||
<tr>
|
||||
<td valign="top" width="300">
|
||||
<h3><img alt="C++ Boost" src="../../../c++boost.gif" width=
|
||||
"277" height="86"></h3>
|
||||
</td>
|
||||
|
||||
<td valign="top">
|
||||
<h1 align="center">Boost.Threads</h1>
|
||||
|
||||
<h2 align="center">mutex<br>
|
||||
try_mutex<br>
|
||||
timed_mutex</h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
|
||||
<p><a href="#Introduction">Introduction</a><br>
|
||||
<a href="#Header">Header</a><br>
|
||||
<a href="#mutex Synopsis">Class mutex Synopsis</a><br>
|
||||
<a href="#mutex Members">Class mutex Members</a><br>
|
||||
<a href="#try_mutex Synopsis">Class try_mutex Synopsis</a><br>
|
||||
<a href="#try_mutex Members">Class try_mutex Members</a><br>
|
||||
<a href="#timed_mutex Synopsis">Class timed_mutex Synopsis</a><br>
|
||||
<a href="#timed_mutex Members">Class timed_mutex Members</a><br>
|
||||
<a href="#Example">Example</a></p>
|
||||
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
|
||||
<p>The <tt><a href="#mutex Synopsis">mutex</a></tt>, <tt><a href=
|
||||
"#try_mutex Synopsis">try_mutex</a></tt> and <tt><a href=
|
||||
"#timed_mutex Synopsis">timed_mutex</a></tt> classes define full
|
||||
featured models of the <a href="mutex_concept.html#Mutex">Mutex</a>, <a
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
||||
<title>Boost.Threads - Header <boost/thread/mutex.hpp></title>
|
||||
</head>
|
||||
<body link="#0000ff" vlink="#800080">
|
||||
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
||||
"header">
|
||||
<tr>
|
||||
<td valign="top" width="300">
|
||||
<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3>
|
||||
</td>
|
||||
<td valign="top">
|
||||
<h1 align="center">Boost.Threads</h1>
|
||||
<h2 align="center">Header <<a href="../../../boost/thread/mutex.hpp">boost/thread/mutex.hpp</a>></h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
<h2>Contents</h2>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#introduction">Introduction</a></dt>
|
||||
<dt><a href="#classes">Classes</a></dt>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-mutex">Class <code>mutex</code></a></dt>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-mutex-synopsis">Class <code>mutex</code> synopsis</a></dt>
|
||||
<dt><a href="#class-mutex-ctors">Class <code>mutex</code> constructors and
|
||||
destructor</a></dt>
|
||||
</dl>
|
||||
</dl>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-try_mutex">Class <code>try_mutex</code></a></dt>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-try_mutex-synopsis">Class <code>try_mutex</code> synopsis</a></dt>
|
||||
<dt><a href="#class-try_mutex-ctors">Class <code>try_mutex</code> constructors
|
||||
and destructor</a></dt>
|
||||
</dl>
|
||||
</dl>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-timed_mutex">Class <code>timed_mutex</code></a></dt>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#class-timed_mutex-synopsis">Class <code>timed_mutex</code>
|
||||
synopsis</a></dt>
|
||||
<dt><a href="#class-timed_mutex-ctors">Class <code>timed_mutex</code> constructors
|
||||
and destructor</a></dt>
|
||||
</dl>
|
||||
</dl>
|
||||
<dt><a href="#examples">Example(s)</a></dt>
|
||||
</dl>
|
||||
<hr>
|
||||
<h2><a name="introduction"></a>Introduction</h2>
|
||||
<p>The <code><a href="#mutex Synopsis">mutex</a></code>, <code><a href=
|
||||
"#try_mutex Synopsis">try_mutex</a></code> and <code><a href=
|
||||
"#timed_mutex Synopsis">timed_mutex</a></code> classes define full featured
|
||||
models of the <a href="mutex_concept.html#Mutex">Mutex</a>, <a
|
||||
href="mutex_concept.html#TryMutex">TryMutex</a>, and <a href=
|
||||
"mutex_concept.html#TimedMutex">TimedMutex</a> concepts. These types
|
||||
should be used to non-recursively synchronize access to shared
|
||||
resources. For recursive locking mechanics, see <a href=
|
||||
"mutex_concept.html#TimedMutex">TimedMutex</a> concepts. These types should
|
||||
be used to non-recursively synchronize access to shared resources. For recursive
|
||||
locking mechanics, see <a href=
|
||||
"recursive_mutex.html">recursive mutexes</a>.</p>
|
||||
|
||||
<p>Each class supplies one or more typedefs for lock types which model
|
||||
matching lock concepts. For the best possible performance you should
|
||||
use the mutex class that supports the minimum set of lock types that
|
||||
you need.</p>
|
||||
|
||||
<table summary="lock types" border="1" cellpadding="5">
|
||||
<tr>
|
||||
<td><b>Mutex Class</b></td>
|
||||
|
||||
<td><b>Lock name</b></td>
|
||||
|
||||
<td><b>Implementation defined Lock Type</b></td>
|
||||
|
||||
<td><b>Lock Concept</b></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><a href="#mutex Synopsis"><code>
|
||||
mutex</code></a></td>
|
||||
|
||||
<td valign="middle"><code>scoped_lock</code></td>
|
||||
|
||||
<td valign="middle"><code><a href="scoped_lock.html">
|
||||
boost::</a></code><a href=
|
||||
<p>Each class supplies one or more typedefs for lock types which model matching
|
||||
lock concepts. For the best possible performance you should use the mutex class
|
||||
that supports the minimum set of lock types that you need.</p>
|
||||
<table summary="lock types" border="1" cellpadding="5">
|
||||
<tr>
|
||||
<td><b>Mutex Class</b></td>
|
||||
<td><b>Lock name</b></td>
|
||||
<td><b>Implementation defined Lock Type</b></td>
|
||||
<td><b>Lock Concept</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><a href="#mutex Synopsis"><code> mutex</code></a></td>
|
||||
<td valign="middle"><code>scoped_lock</code></td>
|
||||
<td valign="middle"><code><a href="scoped_lock.html"> boost::</a></code><a href=
|
||||
"scoped_lock.html"><code>detail::thread::scoped_lock<mutex></code></a></td>
|
||||
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock">
|
||||
ScopedLock</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><tt><a href="#try_mutex Synopsis">
|
||||
try_mutex</a></tt> </td>
|
||||
|
||||
<td valign="middle"><code>scoped_lock<br>
|
||||
scoped_try_lock</code></td>
|
||||
|
||||
<td valign="middle"><code><a href="scoped_lock.html">
|
||||
boost::</a></code><a href=
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock"> ScopedLock</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code><a href="#try_mutex Synopsis"> try_mutex</a></code>
|
||||
</td>
|
||||
<td valign="middle"><code>scoped_lock<br>
|
||||
scoped_try_lock</code></td>
|
||||
<td valign="middle"><code><a href="scoped_lock.html"> boost::</a></code><a href=
|
||||
"scoped_lock.html"><code>detail::thread::scoped_lock<try_mutex><br>
|
||||
|
||||
</code></a> <code><a href="scoped_try_lock.html">
|
||||
boost::detail::thread::scoped_try_lock<try_mutex></a></code></td>
|
||||
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock">
|
||||
ScopedLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTryLock">
|
||||
ScopedTryLock</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td valign="top"><code><a href="#timed_mutex Synopsis">
|
||||
timed_mutex</a></code> </td>
|
||||
|
||||
<td valign="middle"><code>scoped_lock<br>
|
||||
scoped_try_lock<br>
|
||||
scoped_timed_lock</code></td>
|
||||
|
||||
<td valign="middle"><code><a href="scoped_lock.html">
|
||||
boost::</a></code><a href=
|
||||
</code></a> <code><a href="scoped_try_lock.html"> boost::detail::thread::scoped_try_lock<try_mutex></a></code></td>
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock"> ScopedLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTryLock"> ScopedTryLock</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top"><code><a href="#timed_mutex Synopsis"> timed_mutex</a></code>
|
||||
</td>
|
||||
<td valign="middle"><code>scoped_lock<br>
|
||||
scoped_try_lock<br>
|
||||
scoped_timed_lock</code></td>
|
||||
<td valign="middle"><code><a href="scoped_lock.html"> boost::</a></code><a href=
|
||||
"scoped_lock.html"><code>detail::thread::scoped_lock<timed_mutex></code></a><br>
|
||||
|
||||
<code><a href="scoped_try_lock.html">boost::</a></code><a
|
||||
<code><a href="scoped_try_lock.html">boost::</a></code><a
|
||||
href=
|
||||
"scoped_try_lock.html"><code>detail::thread::scoped_try_lock<timed_mutex></code></a><br>
|
||||
|
||||
<code><a href="scoped_timed_lock.html">boost::</a></code><a
|
||||
<code><a href="scoped_timed_lock.html">boost::</a></code><a
|
||||
href=
|
||||
"scoped_timed_lock.html"><code>detail::thread::scoped_timed_lock<timed_mutex></code></a></td>
|
||||
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock">
|
||||
ScopedLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTryLock">
|
||||
ScopedTryLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTimedLock">
|
||||
ScopedTimedLock</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>The <tt>mutex</tt>, <tt>try_mutex</tt> and <tt>timed_mutex</tt>
|
||||
classes use an <tt>Unspecified</tt> <a href=
|
||||
"mutex_concept.html#LockingStrategies">locking strategy</a>, so
|
||||
attempts to recursively lock them or attempts to unlock them by threads
|
||||
that don't own a lock on them result in <b>undefined behavior</b>.
|
||||
This strategy allows implementations to be as efficient as possible on
|
||||
any given platform. It is, however, recommended that implementations
|
||||
include debugging support to detect misuse when <tt>NDEBUG</tt> is not
|
||||
defined.</p>
|
||||
|
||||
<p>Like all the <b>Boost.Threads</b> <a href="mutex_concept.html">mutex
|
||||
models</a>, the <tt>mutex</tt>, <tt>try_mutex</tt> and <tt>
|
||||
timed_mutex</tt> leave the <a href=
|
||||
"mutex_concept.html#SchedulingPolicies">scheduling policy</a> as <tt>
|
||||
Unspecified</tt>. Programmers should assume that threads waiting for a
|
||||
lock on objects of these types acquire the lock in a random order, even
|
||||
though the specific behavior for a given platform may be different.</p>
|
||||
|
||||
<h2><a name="Header">Header</a></h2>
|
||||
<pre>
|
||||
#include <a href=
|
||||
"../../../boost/thread/mutex.hpp"><boost/thread/mutex.hpp></a>
|
||||
</pre>
|
||||
|
||||
<h2>Class <a name="mutex Synopsis">mutex Synopsis</a></h2>
|
||||
<td valign="middle"><a href="lock_concept.html#ScopedLock"> ScopedLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTryLock"> ScopedTryLock</a><br>
|
||||
<a href="lock_concept.html#ScopedTimedLock"> ScopedTimedLock</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>The <code>mutex</code>, <code>try_mutex</code> and <code>timed_mutex</code>
|
||||
classes use an <code>Unspecified</code> <a href="mutex_concept.html#LockingStrategies">locking
|
||||
strategy</a>, so attempts to recursively lock them or attempts to unlock them
|
||||
by threads that don't own a lock on them result in <b>undefined behavior</b>.
|
||||
This strategy allows implementations to be as efficient as possible on any given
|
||||
platform. It is, however, recommended that implementations include debugging
|
||||
support to detect misuse when <code>NDEBUG</code> is not defined.</p>
|
||||
<p>Like all the <b>Boost.Threads</b> <a href="mutex_concept.html">mutex models</a>,
|
||||
the <code>mutex</code>, <code>try_mutex</code> and <code> timed_mutex</code>
|
||||
leave the <a href="mutex_concept.html#SchedulingPolicies">scheduling policy</a>
|
||||
as <code> Unspecified</code>. Programmers should assume that threads waiting
|
||||
for a lock on objects of these types acquire the lock in a random order, even
|
||||
though the specific behavior for a given platform may be different.</p>
|
||||
<h2><a name="classes"></a>Classes</h2>
|
||||
<h3><a name="class-mutex"></a>Class <code>mutex</code></h3>
|
||||
<p>{{class overview text}}</p>
|
||||
<h4><a name="class-mutex-synopsis"></a>Class <code>mutex</code> synopsis</h4>
|
||||
<pre>
|
||||
namespace boost
|
||||
{
|
||||
@@ -169,40 +139,32 @@ namespace boost
|
||||
mutex();
|
||||
~mutex();
|
||||
};
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h2>Class <a name="mutex Members">mutex Members</a></h2>
|
||||
<hr>
|
||||
|
||||
<h3>Constructor</h3>
|
||||
<h4><a name="class-mutex-ctors"></a>Class <code>mutex</code> constructors and
|
||||
destructor</h4>
|
||||
<pre>
|
||||
mutex();
|
||||
mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
||||
state.</p>
|
||||
<hr>
|
||||
|
||||
<h3>Destructor</h3>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Postconditions:</b> <code>*this</code> is in an unlocked state.</dt>
|
||||
</dl>
|
||||
<pre>
|
||||
~mutex();
|
||||
~mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Requires:</b> <code>*this</code> is in the unlocked state.</p>
|
||||
|
||||
<p><b>Effects:</b> Destroys <code>*this</code>.</p>
|
||||
|
||||
<p><b>Dangers:</b> Destruction of a locked mutex is a serious
|
||||
programming error resulting in undefined behavior such as a program
|
||||
crash.</p>
|
||||
<hr>
|
||||
|
||||
<h2>Class <a name="try_mutex Synopsis">try_mutex Synopsis</a></h2>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> <code>*this</code> is in an unlocked sate.</dt>
|
||||
<dt><b>Danger:</b> Destruction of a locked mutex is a serious programming error
|
||||
resulting in undefined behavior such as a program crash.</dt>
|
||||
</dl>
|
||||
<h3><a name="class-try_mutex"></a>Class <code>try_mutex</code></h3>
|
||||
<p>{{class overview text}}</p>
|
||||
<h4><a name="class-try_mutex-synopsis"></a>Class <code>try_mutex</code> synopsis</h4>
|
||||
<pre>
|
||||
namespace boost
|
||||
{
|
||||
class try_mutex : private boost::noncopyable // Exposition only.
|
||||
class try_mutex : private <a href=
|
||||
"../../utility/utility.htm">boost::noncopyable</a> // Exposition only.
|
||||
// Class try_mutex meets the <a href=
|
||||
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
||||
{
|
||||
@@ -215,40 +177,32 @@ namespace boost
|
||||
try_mutex();
|
||||
~try_mutex();
|
||||
};
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h2>Class <a name="try_mutex Members">try_mutex Members</a></h2>
|
||||
<hr>
|
||||
|
||||
<h3>Constructor</h3>
|
||||
<h4><a name="class-try_mutex-ctors"></a>Class <code>try_mutex</code> constructors
|
||||
and destructor</h4>
|
||||
<pre>
|
||||
try_mutex();
|
||||
try_mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
||||
state.</p>
|
||||
<hr>
|
||||
|
||||
<h3>Destructor</h3>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Postconditions:</b> <code>*this</code> is in an unlocked state.</dt>
|
||||
</dl>
|
||||
<pre>
|
||||
~try_mutex();
|
||||
~try_mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Requires:</b> <code>*this</code> is in the unlocked state.</p>
|
||||
|
||||
<p><b>Effects:</b> Destroys <code>*this</code>.</p>
|
||||
|
||||
<p><b>Dangers:</b> Destruction of a locked mutex is a serious
|
||||
programming error resulting in undefined behavior such as a program
|
||||
crash.</p>
|
||||
<hr>
|
||||
|
||||
<h2>Class <a name="timed_mutex Synopsis">timed_mutex Synopsis</a></h2>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> <code>*this</code> is in an unlocked sate.</dt>
|
||||
<dt><b>Danger:</b> Destruction of a locked mutex is a serious programming error
|
||||
resulting in undefined behavior such as a program crash.</dt>
|
||||
</dl>
|
||||
<h3><a name="class-timed_mutex"></a>Class <code>timed_mutex</code></h3>
|
||||
<p>{{class overview text}}</p>
|
||||
<h4><a name="class-timed_mutex-synopsis"></a>Class <code>timed_mutex</code> synopsis</h4>
|
||||
<pre>
|
||||
namespace boost
|
||||
{
|
||||
class timed_mutex : private boost::noncopyable // Exposition only.
|
||||
class timed_mutex : private <a href=
|
||||
"../../utility/utility.htm">boost::noncopyable</a> // Exposition only.
|
||||
// Class timed_mutex meets the <a href=
|
||||
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
||||
{
|
||||
@@ -263,36 +217,25 @@ namespace boost
|
||||
timed_mutex();
|
||||
~timed_mutex();
|
||||
};
|
||||
}
|
||||
};
|
||||
</pre>
|
||||
|
||||
<h2>Class <a name="timed_mutex Members">timed_mutex Members</a></h2>
|
||||
<hr>
|
||||
|
||||
<h3>Constructor</h3>
|
||||
<h4><a name="class-timed_mutex-ctors"></a>Class <code>timed_mutex</code> constructors
|
||||
and destructor</h4>
|
||||
<pre>
|
||||
timed_mutex();
|
||||
timed_mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
||||
state.</p>
|
||||
<hr>
|
||||
|
||||
<h3>Destructor</h3>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Postconditions:</b> <code>*this</code> is in an unlocked state.</dt>
|
||||
</dl>
|
||||
<pre>
|
||||
~timed_mutex();
|
||||
~timed_mutex();
|
||||
</pre>
|
||||
|
||||
<p><b>Requires:</b> <code>*this</code> is in the unlocked state.</p>
|
||||
|
||||
<p><b>Effects:</b> Destroys <code>*this</code>.</p>
|
||||
|
||||
<p><b>Dangers:</b> Destruction of a locked mutex is a serious
|
||||
programming error resulting in undefined behavior such as a program
|
||||
crash.</p>
|
||||
<hr>
|
||||
|
||||
<h2><a name="Example">Example</a> Usage</h2>
|
||||
<dl class="function-semantics">
|
||||
<dt><b>Requires:</b> <code>*this</code> is in an unlocked sate.</dt>
|
||||
<dt><b>Danger:</b> Destruction of a locked mutex is a serious programming error
|
||||
resulting in undefined behavior such as a program crash.</dt>
|
||||
</dl>
|
||||
<h2><a name="examples"></a>Example(s)</h2>
|
||||
<pre>
|
||||
#include <a href=
|
||||
"../../../boost/thread/mutex.hpp"><boost/thread/mutex.hpp></a>
|
||||
@@ -339,21 +282,19 @@ int main(int, char*[])
|
||||
return 0;
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>The output is:</p>
|
||||
<p>The output is:</p>
|
||||
<pre>
|
||||
count == 1
|
||||
count == 2
|
||||
count == 3
|
||||
count == 4
|
||||
</pre>
|
||||
<hr>
|
||||
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->05 November, 2001<!--webbot bot="Timestamp" endspan i-checksum="39359" --></p>
|
||||
|
||||
<p><i>© Copyright <a href="mailto:williamkempf@hotmail.com">
|
||||
William E. Kempf</a> 2001 all rights reserved.</i></p>
|
||||
</body>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
||||
05 November, 2001
|
||||
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
||||
</p>
|
||||
<p><i>© Copyright <a href="mailto:wekempf@cox.net">William E. Kempf</a> 2002. All Rights
|
||||
Reserved.</i></p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user