mirror of
https://github.com/boostorg/thread.git
synced 2026-01-29 20:12:10 +00:00
306 lines
10 KiB
HTML
306 lines
10 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, scoped_try_lock</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">scoped_try_lock</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
<a href="#Header">Header</a><br>
|
|
<a href="#Synopsis">Synopsis</a><br>
|
|
<a href="#Members">Members</a><br>
|
|
<a href="#Example">Example</a></p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<p>This class template defines a generic lock type which meets the <a
|
|
href="lock_concept.html#ScopedTryLock">ScopedTryLock</a> requirements.
|
|
The <a href="mutex.html">try_mutex</a>, <a href="mutex.html">
|
|
timed_mutex</a>, <a href="recursive_mutex.html">recursive_try_mutex</a>
|
|
and <a href="recursive_mutex.html">recursive_timed_mutex</a> classes
|
|
use this template to define their <code>scoped_try_lock</code>
|
|
types.</p>
|
|
|
|
<p>Like all the <b>Boost.Threads</b> <a href="lock_concept.html">lock
|
|
models</a>, <code>scoped_try_lock</code> objects are meant to be
|
|
short-lived. Objects of the class are not <a href=
|
|
"definitions.html#thread-safe">thread-safe</a>, and so should not be
|
|
shared between threads.</p>
|
|
|
|
<p>Class <code>scoped_try_lock</code> follows the "resource
|
|
acquisition is initialization" idiom <a href=
|
|
"bibliography.html#Stroustrup-00">[Stroustrup 00 14.4.1]</a> and is a
|
|
realization of the "Scoped Locking Pattern" <a href=
|
|
"bibliography.html#Schmidt-00">[Schmidt-00]</a>. Thus the usage is to
|
|
let the constructor do the locking, and then let the destructor do the
|
|
unlocking automatically at the end of the enclosing scope. The lock()
|
|
and unlock() members are usually not explicitly called, but are
|
|
provided to allow for complex overlapping locks of multiple
|
|
mutexes.</p>
|
|
|
|
<p>Although this class is an implementation detail, it is publicly
|
|
documented here because of its importance.</p>
|
|
|
|
<p>The type used to instantiate the class must meet the <a href=
|
|
"mutex_concept.html#TryMutex">TryMutex</a> requirements.</p>
|
|
|
|
<h2><a name="Header">Header</a></h2>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/detail/lock.hpp"><boost/thread/detail/lock.hpp></a>
|
|
<i>This header is usually not included directly by programmers
|
|
because it is supplied by <a href=
|
|
"../../../boost/thread/mutex.hpp"><boost/thread/mutex.hpp></a> or
|
|
<a href=
|
|
"../../../boost/thread/recursive_mutex.hpp"><boost/thread/recursive_mutex.hpp></a></i>
|
|
</pre>
|
|
|
|
<h2><a name="Synopsis">Synopsis</a></h2>
|
|
<pre>
|
|
namespace boost { namespace detail { namespace thread {
|
|
template <typename TryMutex>
|
|
class scoped_try_lock : private <a href=
|
|
"../../utility/utility.htm#Class noncopyable">boost::noncopyable</a> // Exposition only.
|
|
// Class scoped_try_lock meets the <a href=
|
|
"overview.html#NonCopyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
typedef TryMutex mutex_type;
|
|
|
|
explicit scoped_try_lock(TryMutex& mx);
|
|
scoped_try_lock(TryMutex& mx, bool initially_locked);
|
|
~scoped_try_lock();
|
|
|
|
void lock();
|
|
bool try_lock();
|
|
void unlock();
|
|
|
|
operator const void*() const;
|
|
};
|
|
} // namespace thread
|
|
} // namespace detail
|
|
} // namespace boost
|
|
</pre>
|
|
|
|
<h2><a name="Members">Members</a></h2>
|
|
<hr>
|
|
|
|
<h3>Constructors</h3>
|
|
<pre>
|
|
explicit scoped_try_lock(TryMutex& mx);
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> Associates mutex <code>mx</code> with <code>
|
|
*this</code>. Calls <code>try_lock()</code>.</p>
|
|
<hr>
|
|
<pre>
|
|
scoped_try_lock(TryMutex& mx, bool initially_locked);
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> Associates mutex <code>mx</code> with <code>
|
|
*this</code>. If <code>initially_locked</code> is <code>true,</code>
|
|
calls <code>lock()</code>.</p>
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
<pre>
|
|
~scoped_try_lock();
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> If <code>locked()</code>, calls <code>
|
|
unlock()</code>. Destroys <code>*this</code>.</p>
|
|
<hr>
|
|
|
|
<h3>lock</h3>
|
|
<pre>
|
|
void lock();
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> If the associated mutex is already locked by another
|
|
lock in the current thread, the effects depend on the locking strategy
|
|
of the associated mutex, as shown in the following table:</p>
|
|
|
|
<table summary="lock effects" border="1" cellpadding="5" height="147">
|
|
<tr>
|
|
<td height="34"><i><a href=
|
|
"mutex_concept.html#LockingStrategies">Locking Strategy</a><br>
|
|
of associated mutex</i></td>
|
|
|
|
<td height="34"><i>Effect if associated mutex is already locked
|
|
by the current thread</i></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Recursive</td>
|
|
|
|
<td height="19">As if an additional lock were added to the
|
|
mutex.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Checked</td>
|
|
|
|
<td height="19">Throws <a href="lock_error.html">
|
|
lock_error</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Unchecked</td>
|
|
|
|
<td height="19">Undefined behavior [<a href=
|
|
"bibliography.html#ISO">ISO</a> 1.3.12] (but typically, <a
|
|
href="definitions.html#Deadlock">deadlock</a>.)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If the associated mutex is already locked by some other thread,
|
|
places the current thread in the <a href="definitions.html#State">
|
|
Blocked</a> state until the associated mutex is unlocked, after which
|
|
the current thread is placed in the <a href="definitions.html#State">
|
|
Ready</a> state, eventually to be returned to the <a href=
|
|
"definitions.html#State">Running</a> state. Places the associated mutex
|
|
in the locked state.</p>
|
|
|
|
<p><b>Throws:</b> <a href="lock_error.html">lock_error</a> if <code>
|
|
locked()</code> or as indicated in <b>Effects</b>.</p>
|
|
<hr>
|
|
|
|
<h3>try_lock</h3>
|
|
<pre>
|
|
bool try_lock();
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> If the associated mutex is already locked by another
|
|
lock in the current thread, the effects depend on the locking strategy
|
|
of the associated mutex, as shown in the following table:</p>
|
|
|
|
<table summary="try_lock effects" border="1" cellpadding="5" height=
|
|
"147">
|
|
<tr>
|
|
<td height="34"><i><a href=
|
|
"mutex_concept.html#LockingStrategies">Locking Strategy</a><br>
|
|
of associated mutex</i></td>
|
|
|
|
<td height="34"><i>Effect if associated mutex is already locked
|
|
by the current thread</i></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Recursive</td>
|
|
|
|
<td height="19">As if an additional lock were added to the
|
|
mutex.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Checked</td>
|
|
|
|
<td height="19">Throws <a href="lock_error.html">
|
|
lock_error</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td height="19">Unspecified</td>
|
|
|
|
<td height="19">Undefined behavior [<a href=
|
|
"bibliography.html#ISO">ISO</a> 1.3.12] (but typically, <a
|
|
href="definitions.html#Deadlock">deadlock</a>.)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If the associated mutex is not already locked by some other thread,
|
|
locks the associated mutex and returns true, else returns false.</p>
|
|
|
|
<p><b>Returns:</b> See effects.</p>
|
|
|
|
<p><b>Throws:</b> <a href="lock_error.html">lock_error</a> if <code>
|
|
locked()</code> or as indicated in <b>Effects</b>.</p>
|
|
<hr>
|
|
|
|
<h3>unlock</h3>
|
|
<pre>
|
|
void unlock();
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> Unlocks the associated mutex.</p>
|
|
|
|
<p><b>Throws:</b> <a href="lock_error.html">lock_error</a> if <code>
|
|
!locked()</code>.</p>
|
|
<hr>
|
|
|
|
<h3>const void* Conversion</h3>
|
|
<pre>
|
|
operator const void*() const;
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> If the associated mutex is currently locked, a value
|
|
convertible to <code>true</code>, else a value convertible to <code>
|
|
false</code>.</p>
|
|
|
|
<p><b>Rationale:</b> A <code>const void*</code> conversion is
|
|
considered safer than a conversion to <code>bool</code>.</p>
|
|
<hr>
|
|
|
|
<h3>locked</h3>
|
|
<pre>
|
|
bool locked() const;
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> <code>this->operator const void*() !=
|
|
0</code>.</p>
|
|
<hr>
|
|
|
|
<h2><a name="Example">Example</a> Usage</h2>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/mutex.hpp"><boost/thread/mutex.hpp></a>
|
|
#include <iostream>
|
|
|
|
int main(int, char*[])
|
|
{
|
|
boost::mutex mutex;
|
|
boost::mutex::try_lock lock(mutex);
|
|
if (lock)
|
|
std::cout << "locked" << std::endl;
|
|
else
|
|
std::cout << "unlocked" << std::endl;
|
|
return 0;
|
|
}
|
|
</pre>
|
|
|
|
<p>The output is:</p>
|
|
<pre>
|
|
locked
|
|
</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>
|
|
|