mirror of
https://github.com/boostorg/thread.git
synced 2026-01-30 20:32:10 +00:00
196 lines
6.2 KiB
HTML
196 lines
6.2 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, basic_lock</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
|
|
|
|
<table 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">basic_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 <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/boost/boost/libs/thread/doc/Attic/lock_concept.html">lock
|
|
concept</a> type. The <a href="mutex.html">mutex</a>, <a href="mutex.html">try_mutex</a>,
|
|
<a href="mutex.html">timed_mutex</a>, <a href="recursive_mutex.html">recursive_mutex</a>,
|
|
<a href="recursive_mutex.html">recursive_try_mutex</a> and <a href="recursive_mutex.html">recursive_timed_mutex</a>
|
|
classes all use this template to define their <tt>lock</tt> types. Instances of class <code>basic_lock</code>
|
|
meet the <a href="lock_concept.html#requirements">Lock requirements</a>.</p>
|
|
|
|
<p>Like all the <b>Boost.Threads</b> <a href="lock_concept.html">lock models</a>,
|
|
<tt>basic_lock</tt> objects are meant to be short lived. Objects of class <tt>basic_lock</tt>
|
|
are not <a href="thread_formal_definition.html#thread-safe">thread-safe</a>, and
|
|
so should not be shared between threads.</p>
|
|
|
|
<p>Class basic_lock 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 commonly not
|
|
explicitly called, but allow for complex overlapping locks of multiple
|
|
<a href="mutex_concept.html">Mutex concepts</a>.</p>
|
|
|
|
<p>The type <code>M</code> used to instantiate class <code>basic_lock</code>
|
|
must meet the <a href="mutex_concept.html#requirements">Mutex requirements</a>.</p>
|
|
|
|
<h2><a name="Header">Header</a></h2>
|
|
|
|
<pre>
|
|
#include <a href="../../../boost/thread/xlock.hpp"><boost/thread/xlock.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 {
|
|
|
|
template <typename M>
|
|
class basic_lock : private <a href="../../utility/utility.htm#Class noncopyable">boost::noncopyable</a>
|
|
{
|
|
public:
|
|
typedef M mutex_type;
|
|
|
|
explicit basic_lock(M& mx, bool lock_it=true);
|
|
~basic_lock();
|
|
|
|
void lock();
|
|
void unlock();
|
|
|
|
operator const void*() const;
|
|
};
|
|
|
|
} // namespace boost
|
|
</pre>
|
|
|
|
<h2><a name="Members">Members</a></h2>
|
|
|
|
<hr>
|
|
|
|
<h3>Constructor</h3>
|
|
|
|
<pre>
|
|
explicit basic_lock(M& mx, bool lock_it=true);
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> Associates mutex <code>mx</code> with <code>*this</code>.
|
|
If <tt>lock_it</tt> is <tt>true,</tt> then calls <tt>lock()</tt>.</p>
|
|
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
|
|
<pre>
|
|
~basic_lock();
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> If locked calls <tt>unlock()</tt>, then destroys <code>*this</code>.</p>
|
|
|
|
<hr>
|
|
|
|
<h3>lock</h3>
|
|
|
|
<pre>
|
|
void lock();
|
|
</pre>
|
|
|
|
<p><b>Requires:</b> this->operator const void*() == 0 (not locked).</p>
|
|
|
|
<p><b>Effects:</b> Attempts to lock the associated mutex. If the associated mutex
|
|
is already locked by the currently running thread the effects depend on the locking
|
|
strategy of the associated mutex, as shown in the following table:</p>
|
|
|
|
<table border="1" cellpadding="5">
|
|
<tr>
|
|
<td><i><a href="mutex_concept.html#LockingStrategies">Locking Strategy</a><br>
|
|
of associated mutex</i></td>
|
|
<td><i>Effect if associated mutex is already locked</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td>Recursive</td>
|
|
<td>As if an additional lock were added to the mutex.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Checked</td>
|
|
<td>Throws <a href="lock_error.html">lock_error</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Unspecified</td>
|
|
<td>Undefined behavior [<a href="bibliography.html#ISO">ISO</a> 1.3.12] (but
|
|
typically, <a href="thread_formal_definition.html#Deadlock">deadlock</a>.)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><b>Throws:</b> <a href="lock_error.html">lock_error</a> if the lock object is
|
|
already locked or if the associated mutex uses the Checked
|
|
<a href="mutex_concept.html#LockingStrategies">Locking Strategy</a> and has
|
|
already been locked by the currently running thread.
|
|
|
|
<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 the associated
|
|
mutex is not already locked.</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>
|
|
|
|
<h2><a name="Example">Example</a> Usage</h2>
|
|
|
|
<p>See the example given in the documentation for the <a href="mutex.html">mutex</a> class.</p>
|
|
|
|
<hr>
|
|
|
|
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->19 July, 2001<!--webbot bot="Timestamp" endspan i-checksum="21079" -->
|
|
</p>
|
|
|
|
<p><i>Copyright <a href="mailto:williamkempf@hotmail.com">William E. Kempf</a>
|
|
2001 all rights reserved.</i></p>
|
|
|
|
</body>
|
|
</html>
|