mirror of
https://github.com/boostorg/thread.git
synced 2026-01-22 05:42:37 +00:00
369 lines
12 KiB
HTML
369 lines
12 KiB
HTML
<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, recursive_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 src="../../../c++boost.gif" alt="C++ Boost" width=
|
|
"277" height="86"></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Threads</h1>
|
|
|
|
<h2 align="center">recursive_mutex<br>
|
|
recursive_try_mutex<br>
|
|
recursive_timed_mutex</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
<a href="#Header">Header</a><br>
|
|
<a href="#recursive_mutex Synopsis">Class recursive_mutex
|
|
Synopsis</a><br>
|
|
<a href="#recursive_mutex Members">Class recursive_mutex
|
|
Members</a><br>
|
|
<a href="#recursive_try_mutex Synopsis">Class recursive_try_mutex
|
|
Synopsis</a><br>
|
|
<a href="#recursive_try_mutex Members">Class recursive_try_mutex
|
|
Members</a><br>
|
|
<a href="#recursive_timed_mutex Synopsis">Class recursive_timed_mutex
|
|
Synopsis</a><br>
|
|
<a href="#recursive_timed_mutex Members">Class recursive_timed_mutex
|
|
Members</a><br>
|
|
<a href="#Example">Example</a></p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>The <code>recursive_mutex</code>, <code>recursive_try_mutex</code>
|
|
and <code>recursive_timed_mutex</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 with recursive
|
|
locking semantics. These types should be used to synchronize access to
|
|
shared resources when recursive locking by a single thread is likely to
|
|
occur. A good example for this is when a class supplies "internal
|
|
synchronization" to ensure <a href="definitions.html#Thread-safe">
|
|
thread-safety</a> and a function of the class may have to call other
|
|
functions of the class which also attempt to lock the mutex. For
|
|
recursive locking mechanics, see <a href="mutex.html">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="#recursive_mutex Synopsis"><code>
|
|
recursive_mutex</code></a></td>
|
|
|
|
<td valign="middle"><code>scoped_lock</code></td>
|
|
|
|
<td valign="middle"><a href="scoped_lock.html"><code>
|
|
detail::thread::scoped_lock<recursive_mutex></code></a></td>
|
|
|
|
<td valign="middle"><a href="lock_concept.html#ScopedLock">
|
|
ScopedLock</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><code><a href="#recursive_try_mutex Synopsis">
|
|
recursive_try_mutex</a></code></td>
|
|
|
|
<td valign="middle"><code>scoped_lock<br>
|
|
scoped_try_lock</code></td>
|
|
|
|
<td valign="middle"><a href="scoped_lock.html"><code>
|
|
detail::thread::scoped_lock<recursive_try_mutex><br>
|
|
</code></a> <code><a href="scoped_try_lock.html">
|
|
detail::thread::scoped_try_lock<recursive_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=
|
|
"#recursive_timed_mutex Synopsis">
|
|
recursive_timed_mutex</a></code> </td>
|
|
|
|
<td valign="middle"><code>scoped_lock<br>
|
|
scoped_try_lock<br>
|
|
scoped_timed_lock</code></td>
|
|
|
|
<td valign="middle"><a href="scoped_lock.html"><code>
|
|
detail::thread::scoped_lock<recursive_timed_mutex></code></a><br>
|
|
|
|
<a href="scoped_try_lock.html"><code>
|
|
detail::thread::scoped_try_lock<recursive_timed_mutex></code></a><br>
|
|
|
|
<a href="scoped_timed_lock.html"><code>
|
|
detail::thread::scoped_timed_lock<recursive_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 <code>recursive_mutex</code>, <code>recursive_try_mutex</code>
|
|
and <code>recursive_timed_mutex</code> employ a <code>Recursive</code>
|
|
<a href="mutex_concept.html#LockingStrategies">locking strategy</a>, so
|
|
attempts to recursively lock them succeed and an internal "lock
|
|
count" is maintained. Attempts to unlock them by a thread that
|
|
does not own a lock on them will result in a <a href="lock_error.html">
|
|
lock_error</a> exception being thrown.</p>
|
|
|
|
<p>The <code>recursive_mutex</code>, <code>recursive_try_mutex</code>
|
|
and <code>recursive_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="Header">Header</a></h2>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/recursive_mutex.hpp"><boost/thread/recursive_mutex.hpp></a>
|
|
</pre>
|
|
|
|
<h2>Class <a name="recursive_mutex Synopsis">recursive_mutex
|
|
Synopsis</a></h2>
|
|
<hr>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
class recursive_mutex : private <a href=
|
|
"../../utility/utility.htm">boost::noncopyable</a> // Exposition only.
|
|
// Class recursive_mutex meets the <a href=
|
|
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_lock;
|
|
|
|
recursive_mutex();
|
|
~recursive_mutex();
|
|
};
|
|
}
|
|
</pre>
|
|
|
|
<h2>Class <a name="recursive_mutex Members">recursive_mutex
|
|
Members</a></h2>
|
|
<hr>
|
|
|
|
<h3>Constructor</h3>
|
|
<pre>
|
|
recursive_mutex();
|
|
</pre>
|
|
|
|
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
|
state.</p>
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
<pre>
|
|
~recursive_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="recursive_try_mutex Synopsis">recursive_try_mutex
|
|
Synopsis</a></h2>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
class recursive_try_mutex : private boost::noncopyable // Exposition only.
|
|
// Class recursive_try_mutex meets the <a href=
|
|
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_lock;
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_try_lock;
|
|
|
|
recursive_try_mutex();
|
|
~recursive_try_mutex();
|
|
};
|
|
}
|
|
</pre>
|
|
|
|
<h2>Class <a name="recursive_try_mutex Members">recursive_try_mutex
|
|
Members</a></h2>
|
|
<hr>
|
|
|
|
<h3>Constructor</h3>
|
|
<pre>
|
|
recursive_try_mutex();
|
|
</pre>
|
|
|
|
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
|
state.</p>
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
<pre>
|
|
~recursive_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="recursive_timed_mutex Synopsis">
|
|
recursive_timed_mutex Synopsis</a></h2>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
class recursive_timed_mutex : private boost::noncopyable // Exposition only.
|
|
// Class recursive_timed_mutex meets the <a href=
|
|
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_lock;
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_try_lock;
|
|
typedef <i>[implementation defined; see <a href=
|
|
"#Introduction">Introduction</a>]</i> scoped_timed_lock;
|
|
|
|
recursive_timed_mutex();
|
|
~recursive_timed_mutex();
|
|
};
|
|
}
|
|
</pre>
|
|
|
|
<h2>Class <a name="recursive_timed_mutex Members">recursive_timed_mutex
|
|
Members</a></h2>
|
|
<hr>
|
|
|
|
<h3>Constructor</h3>
|
|
<pre>
|
|
recursive_timed_mutex();
|
|
</pre>
|
|
|
|
<p><b>Postconditions:</b> <code>*this</code> is in the unlocked
|
|
state.</p>
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
<pre>
|
|
~recursive_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>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/recursive_mutex.hpp"><boost/thread/recursive_mutex.hpp></a>
|
|
#include <a href=
|
|
"../../../boost/thread/thread.hpp"><boost/thread/thread.hpp></a>
|
|
#include <iostream>
|
|
|
|
class counter
|
|
{
|
|
public:
|
|
counter() : count(0) { }
|
|
|
|
int add(int val) {
|
|
boost::recursive_mutex::scoped_lock scoped_lock(mutex);
|
|
count += val;
|
|
return count;
|
|
}
|
|
int increment() {
|
|
boost::recursive_mutex::scoped_lock scoped_lock(mutex);
|
|
return add(1);
|
|
}
|
|
|
|
private:
|
|
boost::recursive_mutex mutex;
|
|
int count;
|
|
};
|
|
|
|
counter c;
|
|
|
|
void change_count(void*)
|
|
{
|
|
std::cout << "count == " << c.increment() << std::endl;
|
|
}
|
|
|
|
int main(int, char*[])
|
|
{
|
|
const int num_threads=4;
|
|
|
|
boost::thread_group threads;
|
|
for (int i=0; i < num_threads; ++i)
|
|
threads.create_thread(&change_count, 0);
|
|
|
|
threads.join_all();
|
|
|
|
return 0;
|
|
}
|
|
</pre>
|
|
|
|
<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>
|
|
</html>
|
|
|