mirror of
https://github.com/boostorg/thread.git
synced 2026-01-26 19:12:11 +00:00
248 lines
12 KiB
HTML
248 lines
12 KiB
HTML
<html>
|
|
<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 - RWLock Concepts</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">RWLock Concepts</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<dl class="index">
|
|
<dt><a href="#introduction">Introduction</a></dt>
|
|
<dt><a href="#requirements">Concept Requirements</a></dt>
|
|
<dl class="index">
|
|
<dt><a href="#lock-state-enumeration">Lock State Enumeration</a></dt>
|
|
<dt><a href="#RWLock-concept">RWLock Concept</a></dt>
|
|
<dt><a href="#ScopedRWLock-concept">ScopedRWLock Concept</a></dt>
|
|
<dt><a href="#ScopedTryRWLock-concept">ScopedTryRWLock Concept</a></dt>
|
|
<dt><a href="#ScopedTimedRWLock-concept">ScopedTimedRWLock Concept</a></dt>
|
|
</dl>
|
|
<dt><a href="#models">Models</a></h2>
|
|
<dt><a href="#footnotes">Footnotes</a></dt>
|
|
</dl>
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
<p>The lock concepts provide exception safe means for locking and unlocking a
|
|
<a href="rw_mutex_concept.html"> rw_mutex model</a>. In other words they are
|
|
an implementation of the <i>Scoped Locking</i> <a href="bibliography.html#Schmidt 00">[Schmidt
|
|
00]</a> pattern. The <a href="#ScopedRWLock">ScopedRWLock</a> concept, with
|
|
<a href="#ScopedTryRWLock"> ScopedTryRWLock</a> and <a href="#ScopedTimedRWLock">ScopedTimedRWLock</a>
|
|
refinements, formalize the requirements.</p>
|
|
<p>Lock models are constructed with a reference to a <a href="mutex_concept.html">mutex
|
|
model</a> and typically acquire ownership of the <a href="mutex_concept.html">mutex
|
|
model</a> by setting its state to locked. They also ensure ownership is relinquished
|
|
in the destructor. Lock models also expose functions to query the lock status
|
|
and to manually lock and unlock the <a href="mutex_concept.html">mutex model</a>.</p>
|
|
<p>Instances of lock models are meant to be short lived, expected to be used at
|
|
block scope only. The lock models are not <a href="definitions.html#Thread-safe">thread-safe</a>.
|
|
Lock models must maintain state to indicate whether or not they've been locked
|
|
and this state is not protected by any synchronization concepts. For this reason
|
|
an instance of a lock model should never be shared between multiple threads.</p>
|
|
<h2><a name="requirements"></a>Concept Requirements</h2>
|
|
<p>[For documentation purposes, portions of the concept requirements are repeated
|
|
in the documentation for specific lock classes. Those copies need to be kept
|
|
in sync with the requirements here.]</p>
|
|
<h3><a name="lock-state-enumeration"></a>Lock State Enumeration</h3>
|
|
<p>An enumerated value that can be one of three possible values - {NO_LOCK, SHARED_LOCK,
|
|
or EXCL_LOCK). Each class modeling the Lock Concept will maintain this
|
|
state as its view of the lock-state of the controlled rw_mutex.</p>
|
|
<h3><a name="RWLock-concept"></a>RWLock Concept</h3>
|
|
<p>For a <a href="#ScopedRWLock">ScopedRWLock</a>, <a href="#ScopedTryRWLock">ScopedTryRWLock</a>,
|
|
or <a href="#ScopedTimedRWLock">ScopedTimedRWLock</a> type <code>L</code> and
|
|
an object <code>lk</code> and const object <code>clk</code> of that type, the
|
|
following expressions must be well-formed and have the indicated effects.</p>
|
|
<p>The Lock concept is used as a base for the <a href="#ScopedRWLock">ScopedRWLock</a>,
|
|
<a href="#ScopedTryRWLock">ScopedTryRWLock</a>, and <a href="#ScopedTimedRWLock">ScopedTimedRWLock</a>
|
|
refinements. The associated rw_mutex type is as specified for each of those
|
|
refinements respectively.</p>
|
|
<table summary="Lock expressions" border="1" cellpadding="5">
|
|
<tr>
|
|
<td><b>Expression</b></td>
|
|
<td><b>Effects</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>(&lk)->~L();</code></td>
|
|
<td><code>if (locked()) unlock();</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>(&clk)->operator const void*()</code></td>
|
|
<td>Returns type void*, non-zero if if the associated rw_mutex has been locked
|
|
by <code> clk</code>, otherwise 0.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>clk.locked()</code></td>
|
|
<td>Returns a <code>bool</code>, <code>(&clk)->operator const void*()
|
|
!= 0</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>clk.lockstate()</code></td>
|
|
<td><code>Returns an enumeration of the lock state, NO_LOCK, EXCL_LOCK
|
|
or SHARED_LOCK</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>lk.wrlock()</code></td>
|
|
<td>Throws lock_error if locked(). If the associated rw_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 rw_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.<br>
|
|
Postcondition: locked() and lockstate() == EXCL_LOCK</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>lk.rdlock()</code></td>
|
|
<td>Throws lock_error if locked(). If the associated rw_mutex cannot
|
|
immediately grant the shared lock, places the current thread in the <a href="definitions.html#State">
|
|
Blocked</a> state until the associated rw_ mutex can grant a shared lock,
|
|
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. <br>
|
|
Postcondition: locked() and lockstate() == SHARED_LOCK</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><code>lk.unlock()</code></td>
|
|
<td>If !locked(), throws lock_error, otherwise unlocks the associated rw_mutex.<br>
|
|
Postcondition: !locked()</td>
|
|
</tr>
|
|
</table>
|
|
<h3><a name="ScopedRWLock-concept"></a>ScopedRWLock Concept</h3>
|
|
<p>A ScopedRWLock must meet the <a href="#Lock">RWLock</a> requirements. For a
|
|
ScopedRWLock type <code>L</code> and an object <code>lk</code> of that type,
|
|
and an object <code>m</code> of a type meeting the <a href="mutex_concept.html#Mutex">
|
|
RWMutex</a> requirements, and an object <code>s</code> of type <code>lock_state</code>,
|
|
the following expressions must be well-formed and have the indicated effects.</p>
|
|
<table summary="ScopedRWLock expressions" border="1" cellpadding="5" width="732">
|
|
<tr>
|
|
<td width="91"><b>Expression</b></td>
|
|
<td width="609"><b>Effects</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="91"><code>L lk(m);</code></td>
|
|
<td width="609">Constructs an object <code>lk</code>, and associates rw_mutex
|
|
<code>m</code> with it, then calls <code>lock()</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="91"><code>L lk(m,s);</code></td>
|
|
<td width="609">Constructs an object <code>lk</code>, and associates rw_mutex
|
|
<code>m</code> with it, then if <code>s==SHARED_LOCK</code>, calls <code>sharedlock()
|
|
or if s==EXCL_LOCK then calls lock()</code></td>
|
|
</tr>
|
|
</table>
|
|
<h3><a name="ScopedTryRWLock-concept"></a>ScopedTryRWLock Concept</h3>
|
|
<p>A ScopedTryRWLock must meet the <a href="#Lock">RWLock</a> requirements. For
|
|
a ScopedTryRWLock type <code>L</code> and an object <code>lk</code> of that
|
|
type, and an object <code>m</code> of a type meeting the <a href="mutex_concept.html#TryMutex">
|
|
TryRWMutex</a> requirements, and an object <code>s</code> of type <code>lock_state</code>,
|
|
the following expressions must be well-formed and have the indicated effects.</p>
|
|
<table summary="ScopedTryRWLock expressions" border="1" cellpadding="5">
|
|
<tr>
|
|
<td width="157"><b>Expression</b></td>
|
|
<td><b>Effects</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="157"><code>L lk(m);</code></td>
|
|
<td>Constructs an object <code>lk</code>, and associates rw_mutex <code>m</code>
|
|
with it, then calls <code>try_lock()</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="157"><code>L lk(m,s);</code></td>
|
|
<td>Constructs an object <code>lk</code>, and associates rw_mutex <code>m</code>
|
|
with it, then if <code>s==SHARED_LOCK</code>, calls <code>sharedlock() or
|
|
if s==EXCL_LOCK then calls lock()</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="157"><code>lk.try_wrlock()</code></td>
|
|
<td>If locked(), throws <code>lock_error</code>. Makes a non-blocking attempt
|
|
to exclusive-lock the associated rw_mutex, returning <code>true</code> if
|
|
the lock attempt is successful, otherwise <code>false</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="157"><code>lk.try_rdlock()</code></td>
|
|
<td>If locked(), throws <code>lock_error</code>. Makes a non-blocking attempt
|
|
to shared-lock the associated rw_mutex, returning <code>true</code> if the
|
|
lock attempt is successful, otherwise <code>false</code>.</td>
|
|
</tr>
|
|
</table>
|
|
<h3><a name="ScopedTimedRWLock-concept"></a>ScopedTimedRWLock Concept</h3>
|
|
<p>A ScopedTimedRWLock must meet the <a href="#Lock">RWLock</a> requirements.
|
|
For a ScopedTimedRWLock type <code>L</code> and an object <code>lk</code> of
|
|
that type, and an object <code>m</code> of a type meeting the <a href="mutex_concept.html#TimedMutex">
|
|
TimedRWMutex</a> requirements, and an object <code>s</code> of type <code>lock_state</code>,
|
|
and an object <code>t</code> of type <code><a href="xtime.html">xtime</a></code>,
|
|
the following expressions must be well-formed and have the indicated effects.</p>
|
|
<table summary="ScopedTimedRWLock expressions" border="1" cellpadding="5">
|
|
<tr>
|
|
<td width="164"><b>Expression</b></td>
|
|
<td><b>Effects</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="164"><code>L lk(m,t);</code></td>
|
|
<td>Constructs an object <code>lk</code>, and associates rw_mutex <code>m</code>
|
|
with it, then calls <code>timed_lock(t)</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="164"><code>L lk(m,s);</code></td>
|
|
<td>Constructs an object <code>lk</code>, and associates rw_ mutex <code>m</code>
|
|
with it, then if <code>s==SHARED_LOCK</code>, calls <code>sharedlock() or
|
|
if s==EXCL_LOCK then calls lock()</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="164"><code>lk.timed_wrlock(t)</code></td>
|
|
<td>If locked(), throws lock_error. Makes a blocking attempt to exclusive-lock
|
|
the associated rw_mutex, and returns <code>true</code> if successful within
|
|
the specified time <code>t</code>, otherwise <code>false</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top" width="164"><code>lk.timed_rdlock(t)</code></td>
|
|
<td>If locked(), throws lock_error. Makes a blocking attempt to shared-lock
|
|
the associated rw_mutex, and returns <code>true</code> if successful within
|
|
the specified time <code>t</code>, otherwise <code>false</code>.</td>
|
|
</tr>
|
|
</table>
|
|
<h2><a name="models"></a>Models</h2>
|
|
<p><b>Boost.Threads</b> currently supplies three classes which model lock concepts.</p>
|
|
<p>These classes are normally accessed via typedefs of the same name supplied
|
|
by a <a href="mutex_concept.html"> mutex model</a>.</p>
|
|
<table summary="Lock concept classes" border="1" cellpadding="5">
|
|
<tr>
|
|
<td><b>Concept</b></td>
|
|
<td><b>Refines</b></td>
|
|
<td><b>Classes Modeling the Concept</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ScopedRWLock">ScopedRWLock</a></td>
|
|
<td> </td>
|
|
<td><a href="scoped_rw_lock.html">scoped_rw_lock</a></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ScopedTryRWLock">ScopedTryRWLock</a></td>
|
|
<td><a href="#ScopedRWLock">ScopedRWLock</a></td>
|
|
<td><a href="scoped_try_rw_lock.html">scoped_try_rw_lock</a> </td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#ScopedTimedRWLock">ScopedTimedRWLock</a></td>
|
|
<td><a href="#ScopedRWLock">ScopedRWLock</a></td>
|
|
<td><a href="scoped_timed_rw_lock.html">scoped_timed_rw_lock</a></td>
|
|
</tr>
|
|
</table>
|
|
<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:{{address}}">{{author}}</a> 2002. All Rights
|
|
Reserved.</i></p>
|
|
</body>
|
|
</html>
|