diff options
Diffstat (limited to 'doc/html/threads/concepts.html')
| -rw-r--r-- | doc/html/threads/concepts.html | 2241 |
1 files changed, 2241 insertions, 0 deletions
diff --git a/doc/html/threads/concepts.html b/doc/html/threads/concepts.html new file mode 100644 index 0000000000..329409c17f --- /dev/null +++ b/doc/html/threads/concepts.html @@ -0,0 +1,2241 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Concepts</title> +<link rel="stylesheet" href="../boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.68.1"> +<link rel="start" href="../index.html" title="The Boost C++ Libraries"> +<link rel="up" href="../threads.html" title="Chapter 12. Boost.Threads"> +<link rel="prev" href="design.html" title="Design"> +<link rel="next" href="rationale.html" title="Rationale"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table cellpadding="2" width="100%"> +<td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td> +<td align="center"><a href="../../../index.htm">Home</a></td> +<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> +<td align="center"><a href="../../../people/people.htm">People</a></td> +<td align="center"><a href="../../../more/faq.htm">FAQ</a></td> +<td align="center"><a href="../../../more/index.htm">More</a></td> +</table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="design.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../threads.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h3 class="title"> +<a name="threads.concepts"></a>Concepts</h3></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.mutexes">Mutexes</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-mutexes">Read/Write Mutexes</a></span></dt> +</dl></div> +<p> currently supports two types of mutex concepts: + ordinary <a href="concepts.html#threads.concepts.mutexes" title="Mutexes">Mutexes</a>, + which allow only one thread at a time to access a resource, and + <a href="concepts.html#threads.concepts.read-write-mutexes" title="Read/Write Mutexes">Read/Write Mutexes</a>, + which allow only one thread at a time to access a resource when it is + being modified (the "Write" part of Read/Write), but allows multiple threads + to access a resource when it is only being referenced (the "Read" part of + Read/Write).</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="threads.concepts.mutexes"></a>Mutexes</h4></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.locking-strategies">Locking Strategies</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.sheduling-policies">Scheduling Policies</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.mutex-concepts">Mutex Concepts</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.mutex-models">Mutex Models</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.lock-concepts">Lock Concepts</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.lock-models">Lock Models</a></span></dt> +</dl></div> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Certain changes to the mutexes and lock concepts are + currently under discussion. In particular, the combination of + the multiple lock concepts into a single lock concept + is likely, and the combination of the multiple mutex + concepts into a single mutex concept is also possible.</div> +<p>A mutex (short for mutual-exclusion) object is used to serialize + access to a resource shared between multiple threads. The + <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> concept, with + <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> and + <a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> refinements, + formalize the requirements. A model that implements Mutex and its + refinements has two states: <span class="bold"><strong>locked</strong></span> and + <span class="bold"><strong>unlocked</strong></span>. Before using a shared resource, a + thread locks a mutex object + (an object whose type is a model of + <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of it's + refinements), ensuring + <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a> access to + the shared resource. When use of the shared resource is complete, the thread + unlocks the mutex object, allowing another thread to acquire the lock and + use the shared resource.</p> +<p>Traditional C thread APIs, like POSIX threads or the Windows thread + APIs, expose functions to lock and unlock a mutex object. This is dangerous + since it's easy to forget to unlock a locked mutex. When the flow of control + is complex, with multiple return points, the likelihood of forgetting to + unlock a mutex object becomes even greater. When exceptions are thrown, + it becomes nearly impossible to ensure that the mutex object is unlocked + properly when using these traditional API's. The result is + <a href="../threads.html#threads.glossary.deadlock">deadlock</a>.</p> +<p>Many C++ threading libraries use a pattern known as <span class="emphasis"><em>Scoped + Locking</em></span> to free the programmer from + the need to explicitly lock and unlock mutex objects. With this pattern, a + <a href="concepts.html#threads.concepts.lock-concepts" title="Lock Concepts">Lock</a> concept is employed where + the lock object's constructor locks the associated mutex object and the + destructor automatically does the unlocking. The + library takes this pattern to + the extreme in that Lock concepts are the only way to lock and unlock a + mutex object: lock and unlock functions are not exposed by any + mutex objects. This helps to + ensure safe usage patterns, especially when code throws exceptions.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.locking-strategies"></a>Locking Strategies</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.recursive-locking-strategy">Recursive Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.checked-locking-strategy">Checked Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.unchecked-locking-strategy">Unchecked Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.unspecified-locking-strategy">Unspecified Locking Strategy</a></span></dt> +</dl></div> +<p>Every mutex object follows one of several locking strategies. These + strategies define the semantics for the locking operation when the calling + thread already owns a lock on the mutex object.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.recursive-locking-strategy"></a>Recursive Locking Strategy</h6></div></div></div> +<p>With a recursive locking strategy, when a thread attempts to acquire + a lock on the mutex object for which it already owns a lock, the operation + is successful. Note the distinction between a thread, which may have + multiple locks outstanding on a recursive mutex object, and a lock object, + which even for a recursive mutex object cannot have any of its lock + functions called multiple times without first calling unlock.</p> +<p>Internally a lock count is maintained and the owning thread must + unlock the mutex object the same number of times that it locked it before + the mutex object's state returns to unlocked. Since mutex objects in + expose locking + functionality only through lock concepts, a thread will always unlock a + mutex object the same number of times that it locked it. This helps to + eliminate a whole set of errors typically found in traditional C style + thread APIs.</p> +<p>Classes <code class="computeroutput"><a href="../recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code>, + <code class="computeroutput"><a href="../recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code> and + <code class="computeroutput"><a href="../recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code> use this locking + strategy.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.checked-locking-strategy"></a>Checked Locking Strategy</h6></div></div></div> +<p>With a checked locking strategy, when a thread attempts to acquire a + lock on the mutex object for which the thread already owns a lock, the + operation will fail with some sort of error indication. Further, attempts + by a thread to unlock a mutex object that was not locked by the thread + will also return some sort of error indication. In + , an exception of type + <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + would be thrown in these cases.</p> +<p> does not currently + provide any mutex objects that use this strategy.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.unchecked-locking-strategy"></a>Unchecked Locking Strategy</h6></div></div></div> +<p>With an unchecked locking strategy, when a thread attempts to acquire + a lock on a mutex object for which the thread already owns a lock the + operation will + <a href="../threads.html#threads.glossary.deadlock">deadlock</a>. In general + this locking strategy is less safe than a checked or recursive strategy, + but it's also a faster strategy and so is employed by many libraries.</p> +<p> does not currently + provide any mutex objects that use this strategy.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.unspecified-locking-strategy"></a>Unspecified Locking Strategy</h6></div></div></div> +<p>With an unspecified locking strategy, when a thread attempts to + acquire a lock on a mutex object for which the thread already owns a lock + the operation results in + <a href="../threads.html#threads.glossary.undefined-behavior">undefined behavior</a>. + </p> +<p>In general a mutex object with an unspecified locking strategy is + unsafe, and it requires programmer discipline to use the mutex object + properly. However, this strategy allows an implementation to be as fast as + possible with no restrictions on its implementation. This is especially + true for portable implementations that wrap the native threading support + of a platform. For this reason, the classes + <code class="computeroutput"><a href="../mutex.html" title="Class mutex">boost::mutex</a></code>, + <code class="computeroutput"><a href="../try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code> and + <code class="computeroutput"><a href="../timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code> use this locking strategy + despite the lack of safety.</p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.sheduling-policies"></a>Scheduling Policies</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.FIFO-scheduling-policy">FIFO Scheduling Policy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.priority-driven-scheduling-policy">Priority Driven Policy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.unspecified-scheduling-policy">Unspecified Policy</a></span></dt> +</dl></div> +<p>Every mutex object follows one of several scheduling policies. These + policies define the semantics when the mutex object is unlocked and there is + more than one thread waiting to acquire a lock. In other words, the policy + defines which waiting thread shall acquire the lock.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.FIFO-scheduling-policy"></a>FIFO Scheduling Policy</h6></div></div></div> +<p>With a FIFO ("First In First Out") scheduling policy, threads waiting + for the lock will acquire it in a first-come-first-served order. + This can help prevent a high priority thread from starving lower priority + threads that are also waiting on the mutex object's lock.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.priority-driven-scheduling-policy"></a>Priority Driven Policy</h6></div></div></div> +<p>With a Priority Driven scheduling policy, the thread with the + highest priority acquires the lock. Note that this means that low-priority + threads may never acquire the lock if the mutex object has high contention + and there is always at least one high-priority thread waiting. This is + known as thread starvation. When multiple threads of the same priority are + waiting on the mutex object's lock one of the other scheduling priorities + will determine which thread shall acquire the lock.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.unspecified-scheduling-policy"></a>Unspecified Policy</h6></div></div></div> +<p>The mutex object does not specify a scheduling policy. In order to + ensure portability, all + mutex objects use an unspecified scheduling policy.</p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.mutex-concepts"></a>Mutex Concepts</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.Mutex">Mutex Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TryMutex">TryMutex Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TimedMutex">TimedMutex Concept</a></span></dt> +</dl></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.Mutex"></a>Mutex Concept</h6></div></div></div> +<p>A Mutex object has two states: locked and unlocked. Mutex object + state can only be determined by a lock object meeting the + appropriate lock concept requirements + and constructed for the Mutex object.</p> +<p>A Mutex is + <a href="../../../libs/utility/utility.htm#Class%20noncopyable" target="_top"> + NonCopyable</a>.</p> +<p>For a Mutex type <code class="computeroutput">M</code> + and an object <code class="computeroutput">m</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1358355"></a><p class="title"><b>Table 12.1. Mutex Expressions</b></p> +<table class="table" summary="Mutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td>M m;</td> +<td> +<p>Constructs a mutex object m.</p> +<p>Postcondition: m is unlocked.</p> +</td> +</tr> +<tr> +<td>(&m)->~M();</td> +<td>Precondition: m is unlocked. Destroys a mutex object + m.</td> +</tr> +<tr> +<td>M::scoped_lock</td> +<td>A model of + <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TryMutex"></a>TryMutex Concept</h6></div></div></div> +<p>A TryMutex is a refinement of + <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a>. + For a TryMutex type <code class="computeroutput">M</code> + and an object <code class="computeroutput">m</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1358432"></a><p class="title"><b>Table 12.2. TryMutex Expressions</b></p> +<table class="table" summary="TryMutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td>M::scoped_try_lock</td> +<td>A model of + <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a> +</td> +</tr></tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TimedMutex"></a>TimedMutex Concept</h6></div></div></div> +<p>A TimedMutex is a refinement of + <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a>. + For a TimedMutex type <code class="computeroutput">M</code> + and an object <code class="computeroutput">m</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1358492"></a><p class="title"><b>Table 12.3. TimedMutex Expressions</b></p> +<table class="table" summary="TimedMutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td>M::scoped_timed_lock</td> +<td>A model of + <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a> +</td> +</tr></tbody> +</table> +</div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.mutex-models"></a>Mutex Models</h5></div></div></div> +<p> currently supplies six models of + <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> + and its refinements.</p> +<div class="table"> +<a name="id1358540"></a><p class="title"><b>Table 12.4. Mutex Models</b></p> +<table class="table" summary="Mutex Models"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Concept</th> +<th>Refines</th> +<th>Models</th> +</tr></thead> +<tbody> +<tr> +<td><a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a></td> +<td> </td> +<td> +<p><code class="computeroutput"><a href="../mutex.html" title="Class mutex">boost::mutex</a></code></p> +<p><code class="computeroutput"><a href="../recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td> +<td><a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a></td> +<td> +<p><code class="computeroutput"><a href="../try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code></p> +<p><code class="computeroutput"><a href="../recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a></td> +<td><a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td> +<td> +<p><code class="computeroutput"><a href="../timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code></p> +<p><code class="computeroutput"><a href="../recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code></p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.lock-concepts"></a>Lock Concepts</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.Lock">Lock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedLock">ScopedLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TryLock">TryLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTryLock">ScopedTryLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TimedLock">TimedLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTimedLock">ScopedTimedLock Concept</a></span></dt> +</dl></div> +<p>A lock object provides a safe means for locking and unlocking a mutex + object (an object whose type is a model of <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of its refinements). In + other words they are an implementation of the <span class="emphasis"><em>Scoped + Locking</em></span> pattern. The <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>, + <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>, and + <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a> + concepts formalize the requirements.</p> +<p>Lock objects are constructed with a reference to a mutex object and + typically acquire ownership of the mutex object by setting its state to + locked. They also ensure ownership is relinquished in the destructor. Lock + objects also expose functions to query the lock status and to manually lock + and unlock the mutex object.</p> +<p>Lock objects are meant to be short lived, expected to be used at block + scope only. The lock objects are not <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a>. Lock objects 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 a lock + object should never be shared between multiple threads.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.Lock"></a>Lock Concept</h6></div></div></div> +<p>For a Lock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> + and const object <code class="computeroutput">clk</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1358762"></a><p class="title"><b>Table 12.5. Lock Expressions</b></p> +<table class="table" summary="Lock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">(&lk)->~L();</code></td> +<td><code class="computeroutput">if (locked()) unlock();</code></td> +</tr> +<tr> +<td><code class="computeroutput">(&clk)->operator const void*()</code></td> +<td>Returns type void*, non-zero if the associated mutex + object has been locked by <code class="computeroutput">clk</code>, otherwise 0.</td> +</tr> +<tr> +<td><code class="computeroutput">clk.locked()</code></td> +<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->operator + const void*() != 0</code> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">locked()</code>.</p> +<p>If the associated mutex object is + already locked by some other thread, places the current thread in the + <a href="../threads.html#threads.glossary.thread-state">Blocked</a> state until + the associated mutex is unlocked, after which the current thread + is placed in the <a href="../threads.html#threads.glossary.thread-state">Ready</a> state, + eventually to be returned to the <a href="../threads.html#threads.glossary.thread-state">Running</a> state. If + the associated mutex object is already locked by the same thread + the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated mutex object.</p> +<p>Postcondition: <code class="computeroutput">locked() == true</code></p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.unlock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">!locked()</code>.</p> +<p>Unlocks the associated mutex.</p> +<p>Postcondition: <code class="computeroutput">!locked()</code></p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedLock"></a>ScopedLock Concept</h6></div></div></div> +<p>A ScopedLock is a refinement of <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a>. + For a ScopedLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> requirements, + and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1358999"></a><p class="title"><b>Table 12.6. ScopedLock Expressions</b></p> +<table class="table" summary="ScopedLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">L lk(m);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then calls + <code class="computeroutput">lock()</code> +</td> +</tr> +<tr> +<td><code class="computeroutput">L lk(m,b);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls + <code class="computeroutput">lock()</code> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TryLock"></a>TryLock Concept</h6></div></div></div> +<p>A TryLock is a refinement of <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a>. + For a TryLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1359102"></a><p class="title"><b>Table 12.7. TryLock Expressions</b></p> +<table class="table" summary="TryLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td><code class="computeroutput">lk.try_lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a + non-blocking attempt to lock the associated mutex object, + returning <code class="computeroutput">true</code> if the lock attempt is successful, + otherwise <code class="computeroutput">false</code>. If the associated mutex object is + already locked by the same thread the behavior is dependent on the + <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated mutex object.</p> +</td> +</tr></tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedTryLock"></a>ScopedTryLock Concept</h6></div></div></div> +<p>A ScopedTryLock is a refinement of <a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a>. + For a ScopedTryLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> requirements, + and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1359223"></a><p class="title"><b>Table 12.8. ScopedTryLock Expressions</b></p> +<table class="table" summary="ScopedTryLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">L lk(m);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then calls + <code class="computeroutput">try_lock()</code> +</td> +</tr> +<tr> +<td><code class="computeroutput">L lk(m,b);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls + <code class="computeroutput">lock()</code> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TimedLock"></a>TimedLock Concept</h6></div></div></div> +<p>A TimedLock is a refinement of <a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a>. + For a TimedLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1359344"></a><p class="title"><b>Table 12.9. TimedLock Expressions</b></p> +<table class="table" summary="TimedLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td><code class="computeroutput">lk.timed_lock(t)</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a blocking attempt + to lock the associated mutex object, and returns <code class="computeroutput">true</code> + if successful within the specified time <code class="computeroutput">t</code>, otherwise + <code class="computeroutput">false</code>. If the associated mutex object is already + locked by the same thread the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated mutex object.</p> +</td> +</tr></tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedTimedLock"></a>ScopedTimedLock Concept</h6></div></div></div> +<p>A ScopedTimedLock is a refinement of <a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a>. + For a ScopedTimedLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> requirements, + and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>, + and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1359488"></a><p class="title"><b>Table 12.10. ScopedTimedLock Expressions</b></p> +<table class="table" summary="ScopedTimedLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">L lk(m,t);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then calls + <code class="computeroutput">timed_lock(t)</code> +</td> +</tr> +<tr> +<td><code class="computeroutput">L lk(m,b);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex + object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls + <code class="computeroutput">lock()</code> +</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.lock-models"></a>Lock Models</h5></div></div></div> +<p> currently supplies twelve models of + <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a> + and its refinements.</p> +<div class="table"> +<a name="id1359578"></a><p class="title"><b>Table 12.11. Lock Models</b></p> +<table class="table" summary="Lock Models"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Concept</th> +<th>Refines</th> +<th>Models</th> +</tr></thead> +<tbody> +<tr> +<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td> +<td> </td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a></td> +<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td> +<td> +<p><code class="computeroutput">boost::mutex::scoped_lock</code></p> +<p><code class="computeroutput">boost::recursive_mutex::scoped_lock</code></p> +<p><code class="computeroutput">boost::try_mutex::scoped_lock</code></p> +<p><code class="computeroutput">boost::recursive_try_mutex::scoped_lock</code></p> +<p><code class="computeroutput">boost::timed_mutex::scoped_lock</code></p> +<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_lock</code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td> +<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a></td> +<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td> +<td> +<p><code class="computeroutput">boost::try_mutex::scoped_try_lock</code></p> +<p><code class="computeroutput">boost::recursive_try_mutex::scoped_try_lock</code></p> +<p><code class="computeroutput">boost::timed_mutex::scoped_try_lock</code></p> +<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_try_lock</code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td> +<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a></td> +<td><a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td> +<td> +<p><code class="computeroutput">boost::timed_mutex::scoped_timed_lock</code></p> +<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_timed_lock</code></p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="threads.concepts.read-write-mutexes"></a>Read/Write Mutexes</h4></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies">Locking Strategies</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-scheduling-policies">Scheduling Policies</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-mutex-concepts">Mutex Concepts</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-mutex-models">Mutex Models</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-lock-concepts">Lock Concepts</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-lock-models">Lock Models</a></span></dt> +</dl></div> +<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +<h3 class="title">Note</h3>Since the read/write mutex and related classes are new, + both interface and implementation are liable to change + in future releases of . + The lock concepts and lock promotion and demotion in particular + are still under discussion and very likely to change.</div> +<p>A read/write mutex (short for reader/writer mutual-exclusion) object + is used to serialize access to a resource shared between multiple + threads, where multiple "readers" can share simultaneous access, but + "writers" require exclusive access. The + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> concept, with + <a href="concepts.html#threads.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a> and + <a href="concepts.html#threads.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept"> TimedReadWriteMutex</a> + refinements formalize the requirements. A model that implements + ReadWriteMutex and its refinements has three states: + <span class="bold"><strong>read-locked</strong></span>, + <span class="bold"><strong>write-locked</strong></span>, and + <span class="bold"><strong>unlocked</strong></span>. + Before reading from a shared resource, a thread + <span class="bold"><strong>read-locks</strong></span> + a read/write mutex object + (an object whose type is a model of + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> + or one of it's refinements), ensuring + <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a> + access for reading from the shared resource. Before writing + to a shared resource, a thread + <span class="bold"><strong>write-locks</strong></span> a + read/write mutex object + (an object whose type is a model of + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> + or one of it's refinements), ensuring + <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a> + access for altering the shared resource. When use of the shared + resource is complete, the thread unlocks the mutex object, + allowing another thread to acquire the lock and use the shared + resource.</p> +<p>Traditional C thread APIs that provide read/write mutex + primitives (like POSIX threads) expose functions to lock and unlock a + mutex object. This is dangerous since it's easy to forget to unlock a + locked mutex. When the flow of control is complex, with multiple + return points, the likelihood of forgetting to unlock a mutex object + becomes even greater. When exceptions are thrown, it becomes nearly + impossible to ensure that the mutex object is unlocked + properly when using these traditional API's. The result is + <a href="../threads.html#threads.glossary.deadlock">deadlock</a>.</p> +<p>Many C++ threading libraries use a pattern known as <span class="emphasis"><em>Scoped + Locking</em></span> to free the + programmer from the need to explicitly lock and unlock + read/write mutex objects. With this pattern, a + <a href="concepts.html#threads.concepts.read-write-lock-concepts" title="Lock Concepts">Read/Write Lock</a> + concept is employed where the lock object's constructor locks + the associated read/write mutex object + and the destructor automatically does the unlocking. The + library takes this pattern to + the extreme in that + <a href="concepts.html#threads.concepts.read-write-lock-concepts" title="Lock Concepts">Read/Write Lock</a> + concepts are the only way to lock and unlock a read/write mutex + object: lock and unlock functions are not exposed by any + read/write mutex objects. This helps to + ensure safe usage patterns, especially when code throws exceptions.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-locking-strategies"></a>Locking Strategies</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.recursive">Recursive Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.checked">Checked Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.unchecked">Unchecked Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.unspecified">Unspecified Locking Strategy</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.thread-identification">Thread Identification</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.promotion">Lock Promotion</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-locking-strategies.demotion">Lock Demotion</a></span></dt> +</dl></div> +<p>Every read/write mutex object follows one of several locking + strategies. These strategies define the semantics for the locking + operation when the calling thread already owns a lock on the + read/write mutex object.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.recursive"></a>Recursive Locking Strategy</h6></div></div></div> +<p>With a recursive locking strategy, when a thread attempts + to acquire a lock on a read/write mutex object + for which it already owns a lock, the operation is successful, + except in the case where a thread holding a read-lock + attempts to obtain a write lock, in which case a + <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> exception will + be thrown. Note the distinction between a thread, which may have + multiple locks outstanding on a recursive read/write mutex object, + and a lock object, which even for a recursive read/write mutex + object cannot have any of its lock functions called multiple + times without first calling unlock.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Lock Type Held</th> +<th>Lock Type Requested</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>read-lock</td> +<td>read-lock</td> +<td>Grant the read-lock immediately</td> +</tr> +<tr> +<td>read-lock</td> +<td>write-lock</td> +<td>If this thread is the only holder of the read-lock, + grants the write lock immediately. Otherwise throws a + <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> exception.</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td>Grants the (additional) read-lock immediately.</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td> Grant the write-lock immediately</td> +</tr> +</tbody> +</table></div> +<p>Internally a lock count is maintained and the owning + thread must unlock the mutex object the same number of times + that it locked it before the mutex object's state returns + to unlocked. Since mutex objects in expose + locking functionality only through lock concepts, a thread + will always unlock a mutex object the same number of times + that it locked it. This helps to eliminate a whole set of + errors typically found in traditional C style thread APIs. + </p> +<p> does not currently provide any read/write mutex objects + that use this strategy. A successful implementation of this locking strategy + may require + <a href="concepts.html#threads.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.checked"></a>Checked Locking Strategy</h6></div></div></div> +<p>With a checked locking strategy, when a thread attempts + to acquire a lock on the mutex object for which the thread + already owns a lock, the operation will fail with some sort of + error indication, except in the case of multiple read-lock + acquisition which is a normal operation for ANY ReadWriteMutex. + Further, attempts by a thread to unlock a mutex that was not + locked by the thread will also return some sort of error + indication. In , an exception of type + <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> would be thrown in + these cases.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Lock Type Held</th> +<th>Lock Type Requested</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>read-lock</td> +<td>read-lock</td> +<td>Grant the read-lock immediately</td> +</tr> +<tr> +<td>read-lock</td> +<td>write-lock</td> +<td>Throw <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td>Throw <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td> Throw <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> +</td> +</tr> +</tbody> +</table></div> +<p> does not currently provide any read/write mutex objects + that use this strategy. A successful implementation of this locking strategy + may require + <a href="concepts.html#threads.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.unchecked"></a>Unchecked Locking Strategy</h6></div></div></div> +<p>With an unchecked locking strategy, when a thread + attempts to acquire a lock on the read/write mutex object + for which the thread already owns a lock, the operation + will <a href="../threads.html#threads.glossary.deadlock">deadlock</a>. + In general this locking strategy is less safe than a checked + or recursive strategy, but it can be a faster strategy and so + is employed by many libraries.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Lock Type Held</th> +<th>Lock Type Requested</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>read-lock</td> +<td>read-lock</td> +<td>Grant the read-lock immediately</td> +</tr> +<tr> +<td>read-lock</td> +<td>write-lock</td> +<td><a href="../threads.html#threads.glossary.deadlock">Deadlock</a></td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td><a href="../threads.html#threads.glossary.deadlock">Deadlock</a></td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td><a href="../threads.html#threads.glossary.deadlock">Deadlock</a></td> +</tr> +</tbody> +</table></div> +<p> does not currently provide any mutex + objects that use this strategy. For ReadWriteMutexes on + platforms that contain natively recursive synchronization + primitives, implementing a guaranteed-deadlock can actually + involve extra work, and would likely require + <a href="concepts.html#threads.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>. + </p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.unspecified"></a>Unspecified Locking Strategy</h6></div></div></div> +<p>With an unspecified locking strategy, when a thread + attempts to acquire a lock on a read/write mutex object for + which the thread already owns a lock, the operation results + in <a href="../threads.html#threads.glossary.undefined-behavior">undefined behavior</a>. + When a read/write mutex object has an unspecified locking + strategy the programmer must assume that the read/write mutex + object instead uses an unchecked strategy as the worse case, + although some platforms may exhibit a mix of unchecked and + recursive behavior.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Lock Type Held</th> +<th>Lock Type Requested</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>read-lock</td> +<td>read-lock</td> +<td>Grant the read-lock immediately</td> +</tr> +<tr> +<td>read-lock</td> +<td>write-lock</td> +<td> +<a href="../threads.html#threads.glossary.undefined-behavior">Undefined</a>, but generally <a href="../threads.html#threads.glossary.deadlock">deadlock</a> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td> +<a href="../threads.html#threads.glossary.undefined-behavior">Undefined</a>, but generally <a href="../threads.html#threads.glossary.deadlock">deadlock</a> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td> +<a href="../threads.html#threads.glossary.undefined-behavior">Undefined</a>, but generally <a href="../threads.html#threads.glossary.deadlock">deadlock</a> +</td> +</tr> +</tbody> +</table></div> +<p>In general a read/write mutex object with an unspecified + locking strategy is unsafe, and it requires programmer discipline + to use the read/write mutex object properly. However, this strategy + allows an implementation to be as fast as possible with no restrictions + on its implementation. This is especially true for portable implementations + that wrap the native threading support of a platform. For this reason, the + classes + <code class="computeroutput">read_write_mutex</code>, + <code class="computeroutput">try_read_write_mutex</code>, and + <code class="computeroutput">timed_read_write_mutex</code> + use this locking strategy despite the lack of safety.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.thread-identification"></a>Thread Identification</h6></div></div></div> +<p>ReadWriteMutexes can support specific Locking Strategies + (recursive and checked) which help to detect and protect against + self-deadlock. Self-deadlock can occur when a holder of a locked + ReadWriteMutex attempts to obtain another lock. Given an + implemention <span class="emphasis"><em>I</em></span> which is susceptible to + self-deadlock but otherwise correct and efficient, a recursive or + checked implementation <span class="emphasis"><em>Ir</em></span> or + <span class="emphasis"><em>Ic</em></span> can use the same basic implementation, + but make special checks against self-deadlock by tracking the + identities of thread(s) currently holding locks. This approach + makes deadlock detection othrogonal to the basic ReadWriteMutex + implementaion.</p> +<p>Alternatively, a different basic implementation for + ReadWriteMutex concepts, + <span class="emphasis"><em>I'</em></span> (I-Prime) may exist which uses recursive + or checked versions of synchronization primitives to produce + a recursive or checked ReadWriteMutex while still providing + flexibility in terms of Scheduling Policies. </p> +<p>Please refer to the <a href="concepts.html#threads.concepts.read-write-mutex-concepts" title="Mutex Concepts">read/write mutex concept</a> + documentation for a discussion of locking strategies. + The read/write mutex supports only the + <a href="concepts.html#threads.concepts.read-write-locking-strategies.unspecified" title="Unspecified Locking Strategy">unspecified</a> + locking strategy. ReadWriteMutexes are parameterized on a + Mutex type which they use to control write-locking + and access to internal state.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.promotion"></a>Lock Promotion</h6></div></div></div> +<p>ReadWriteMutexes can support lock promotion, where a + mutex which is in the read-locked state transitions to a + write-locked state without releasing the lock. Lock + promotion can be tricky to implement; for instance, + extra care must be taken to ensure that only one thread holding a + read-lock can block awaiting promotion at any given time. If + more than one read-lock holder is allowed to enter a blocked + state while waiting to be promoted, deadlock will result since + both threads will be waiting for the other to release their read-lock. + </p> +<p>Currently, supports lock promotion + through <code class="computeroutput">promote()</code>, <code class="computeroutput">try_promote()</code>, + and <code class="computeroutput">timed_promote()</code> operations.</p> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-locking-strategies.demotion"></a>Lock Demotion</h6></div></div></div> +<p>ReadWriteMutexes can support lock demotion, where a + mutex which is in the write-locked state transitions to a + read-locked state without releasing the lock. + Since by definition only one thread at a time may hold + a write-lock, the problem with deadlock that can occur + during lock promotion is not a problem for lock + demotion.</p> +<p>Currently, supports lock demotion + through <code class="computeroutput">demote()</code>, <code class="computeroutput">try_demote()</code>, + and <code class="computeroutput">timed_demote()</code> operations.</p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-scheduling-policies"></a>Scheduling Policies</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-scheduling-policies.inter-class">Inter-Class Scheduling Policies</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.read-write-scheduling-policies.intra-class">Intra-Class Scheduling Policies</a></span></dt> +</dl></div> +<p>Every read/write mutex object follows one of several scheduling + policies. These policies define the semantics when the mutex object + is unlocked and there is more than one thread waiting to acquire a + lock. In other words, the policy defines which waiting thread shall + acquire the lock. For a read/write mutex, it is particularly important + to define the behavior when threads are requesting both read and + write access simultaneously. This will be referred to as "inter-class + scheduling" because it describes the scheduling between two + classes of threads (those waiting for a read lock and those + waiting for a write lock).</p> +<p>For some types of inter-class scheduling, an "intra-class" + scheduling policy can also be defined that will describe the order + in which waiting threads of the same class (i.e., those + waiting for the same type of lock) will acquire the thread. + </p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.inter-class"></a>Inter-Class Scheduling Policies</h6></div></div></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.reader-priority"></a>ReaderPriority</h6></div></div></div> +<p>With ReaderPriority scheduling, any pending request for + a read-lock will have priority over a pending request for a + write-lock, irrespective of the current lock state of the + read/write mutex, and irrespective of the relative order + that the pending requests arrive.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Current mutex state</th> +<th>Request Type</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>unlocked</td> +<td>read-lock</td> +<td>Grant the read-lock immediately</td> +</tr> +<tr> +<td>read-locked</td> +<td>read-lock</td> +<td>Grant the additional read-lock immediately.</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td>Wait to acquire the lock until the thread + holding the write-lock releases its lock (or until + the specified time, if any). A + read-lock will be granted to all pending readers + before any other thread can acquire a write-lock. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>unlocked</td> +<td>write-lock</td> +<td>Grant the write-lock immediately, if and + only if there are no pending read-lock requests. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>read-locked</td> +<td>write-lock</td> +<td> Wait to acquire the lock until all + threads holding read-locks release their locks + <span class="bold"><strong>AND</strong></span> no requests + for read-locks exist. If other write-lock + requests exist, the lock is granted in accordance + with the intra-class scheduling policy. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td>Wait to acquire the lock until the thread + holding the write-lock releases its lock + <span class="bold"><strong>AND</strong></span> no requests + for read-locks exist. If other write-lock + requests exist, the lock is granted in accordance + with the intra-class scheduling policy. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>read-locked</td> +<td>promote</td> +<td><p>TODO</p></td> +</tr> +<tr> +<td>write-locked</td> +<td>demote</td> +<td><p>TODO</p></td> +</tr> +</tbody> +</table></div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.writer-priority"></a>WriterPriority</h6></div></div></div> +<p>With WriterPriority scheduling, any pending request + for a write-lock will have priority over a pending request + for a read-lock, irrespective of the current lock state + of the read/write mutex, and irrespective of the relative + order that the pending requests arrive.</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Current mutex state</th> +<th>Request Type</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>unlocked</td> +<td>read-lock</td> +<td>Grant the read-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>read-lock</td> +<td>Grant the additional read-lock immediately, + <span class="bold"><strong>IF</strong></span> no outstanding + requests for a write-lock exist; otherwise TODO. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td> Wait to acquire the lock until the + thread holding the write-lock + releases its lock. The read lock will be granted + once no other outstanding write-lock requests + exist. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>unlocked</td> +<td>write-lock</td> +<td>Grant the write-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>write-lock</td> +<td>Wait to acquire the lock until all + threads holding read-locks release their locks. + If other write-lock requests exist, the lock + is granted in accordance with the intra-class + scheduling policy. This request will be granted + before any new read-lock requests are granted. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td>Wait to acquire the lock until the thread + holding the write-lock releases its lock. If + other write-lock requests exist, the lock is + granted in accordance with the intra-class + scheduling policy. This request will be granted + before any new read-lock requests are granted. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>read-locked</td> +<td>promote</td> +<td><p>TODO</p></td> +</tr> +<tr> +<td>write-locked</td> +<td>demote</td> +<td><p>TODO</p></td> +</tr> +</tbody> +</table></div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.alternating-many-reads"></a>AlternatingPriority/ManyReads</h6></div></div></div> +<p>With AlternatingPriority/ManyReads scheduling, reader + or writer starvation is avoided by alternatively granting read + or write access when pending requests exist for both types of + locks. Outstanding read-lock requests are treated as a group + when it is the "readers' turn"</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Current mutex state</th> +<th>Request Type</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>unlocked</td> +<td>read-lock</td> +<td>Grant the read-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>read-lock</td> +<td>Grant the additional read-lock immediately, + <span class="bold"><strong>IF</strong></span> no outstanding + requests for a write-lock exist. If outstanding + write-lock requests exist, this lock will not + be granted until at least one of the + write-locks is granted and released. If other + read-lock requests exist, all read-locks will be + granted as a group. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td> Wait to acquire the lock until the thread + holding the write-lock releases its lock. If other + outstanding write-lock requests exist, they will + have to wait until all current read-lock requests + are serviced. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>unlocked</td> +<td>write-lock</td> +<td>Grant the write-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>write-lock</td> +<td> +<p>Wait to acquire the lock until all threads + holding read-locks release their locks.</p> +<p>If other write-lock requests exist, this + lock will be granted to one of them in accordance + with the intra-class scheduling policy.</p> +<p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td>Wait to acquire the lock until the thread + holding the write-lock releases its lock. If + other outstanding read-lock requests exist, this + lock will not be granted until all of the + currently waiting read-locks are granted and + released. If other write-lock requests exist, + this lock will be granted in accordance with the + intra-class scheduling policy. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>read-locked</td> +<td>promote</td> +<td><p>TODO</p></td> +</tr> +<tr> +<td>write-locked</td> +<td>demote</td> +<td><p>TODO</p></td> +</tr> +</tbody> +</table></div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.alternating-single-read"></a>AlternatingPriority/SingleRead</h6></div></div></div> +<p>With AlternatingPriority/SingleRead scheduling, reader + or writer starvation is avoided by alternatively granting read + or write access when pending requests exist for both types of + locks. Outstanding read-lock requests are services one at a + time when it is the "readers' turn"</p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Current mutex state</th> +<th>Request Type</th> +<th>Action</th> +</tr></thead> +<tbody> +<tr> +<td>unlocked</td> +<td>read-lock</td> +<td>Grant the read-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>read-lock</td> +<td>Grant the additional read-lock immediately, + <span class="bold"><strong>IF</strong></span> no outstanding + requests for a write-lock exist. If outstanding + write-lock requests exist, this lock will not + be granted until at least one of the write-locks + is granted and released. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>read-lock</td> +<td> +<p>Wait to acquire the lock until the thread + holding the write-lock releases its lock.</p> +<p>If other outstanding write-lock requests + exist, exactly one read-lock request will be + granted before the next write-lock is granted. + </p> +<p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>unlocked</td> +<td>write-lock</td> +<td>Grant the write-lock immediately.</td> +</tr> +<tr> +<td>read-locked</td> +<td>write-lock</td> +<td> +<p>Wait to acquire the lock until all + threads holding read-locks release their + locks.</p> +<p>If other write-lock requests exist, + this lock will be granted to one of them + in accordance with the intra-class + scheduling policy.</p> +</td> +</tr> +<tr> +<td>write-locked</td> +<td>write-lock</td> +<td>Wait to acquire the lock until the + thread holding the write-lock releases its + lock. If other outstanding read-lock requests + exist, this lock can not be granted until + exactly one read-lock request is granted and + released. If other write-lock requests exist, + this lock will be granted in accordance with + the intra-class scheduling policy. + <p>TODO: try-lock, timed-lock.</p> +</td> +</tr> +<tr> +<td>read-locked</td> +<td>promote</td> +<td><p>TODO</p></td> +</tr> +<tr> +<td>write-locked</td> +<td>demote</td> +<td><p>TODO</p></td> +</tr> +</tbody> +</table></div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.read-write-scheduling-policies.intra-class"></a>Intra-Class Scheduling Policies</h6></div></div></div> +<p>Please refer to + <a href="concepts.html#threads.concepts.sheduling-policies" title="Scheduling Policies">the section called “Scheduling Policies”</a> + for a discussion of mutex scheduling policies, which are identical to + read/write mutex intra-class scheduling policies.</p> +<p>For threads waiting to obtain write-locks, the read/write mutex + supports only the + <a href="concepts.html#threads.concepts.unspecified-scheduling-policy" title="Unspecified Policy">Unspecified</a> + intra-class scheduling policy. That is, given a set of threads + waiting for write-locks, the order, relative to one another, in + which they receive the write-lock is unspecified.</p> +<p>For threads waiting to obtain read-locks, the read/write mutex + supports only the + <a href="concepts.html#threads.concepts.unspecified-scheduling-policy" title="Unspecified Policy">Unspecified</a> + intra-class scheduling policy. That is, given a set of threads + waiting for read-locks, the order, relative to one another, in + which they receive the read-lock is unspecified.</p> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-mutex-concepts"></a>Mutex Concepts</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.ReadWriteMutex">ReadWriteMutex Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TryReadWriteMutex">TryReadWriteMutex Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TimedReadWriteMutex">TimedReadWriteMutex Concept</a></span></dt> +</dl></div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ReadWriteMutex"></a>ReadWriteMutex Concept</h6></div></div></div> +<p>A ReadWriteMutex object has three states: read-locked, + write-locked, and unlocked. ReadWriteMutex object state can + only be determined by a lock object meeting the appropriate lock concept + requirements and constructed for the ReadWriteMutex object.</p> +<p>A ReadWriteMutex is + <a href="../../../libs/utility/utility.htm#Class%20noncopyable" target="_top">NonCopyable</a>. + </p> +<p>For a ReadWriteMutex type <code class="computeroutput">M</code>, + and an object <code class="computeroutput">m</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1361243"></a><p class="title"><b>Table 12.12. ReadWriteMutex Expressions</b></p> +<table class="table" summary="ReadWriteMutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">M m;</code></td> +<td>Constructs a read/write mutex object <code class="computeroutput">m</code>. + Post-condition: <code class="computeroutput">m</code> is unlocked.</td> +</tr> +<tr> +<td><code class="computeroutput">(&m)->~M();</code></td> +<td>Precondition: <code class="computeroutput">m</code> is unlocked. + Destroys a read/write mutex object <code class="computeroutput">m</code>. + </td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_read_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a> + requirements. </td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_read_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a> + requirements. </td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a> + requirements. </td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TryReadWriteMutex"></a>TryReadWriteMutex Concept</h6></div></div></div> +<p>A TryReadWriteMutex is a refinement of + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>. + For a TryReadWriteMutex type <code class="computeroutput">M</code> + and an object <code class="computeroutput">m</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1361388"></a><p class="title"><b>Table 12.13. TryReadWriteMutex Expressions</b></p> +<table class="table" summary="TryReadWriteMutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">M::scoped_try_read_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a> + requirements.</td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_try_read_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a> + requirements.</td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_try_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a> + requirements.</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TimedReadWriteMutex"></a>TimedReadWriteMutex Concept</h6></div></div></div> +<p>A TimedReadWriteMutex is a refinement of + <a href="concepts.html#threads.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a>. + For a TimedReadWriteMutex type <code class="computeroutput">M</code> + and an object <code class="computeroutput">m</code> of that type + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1361491"></a><p class="title"><b>Table 12.14. TimedReadWriteMutex Expressions</b></p> +<table class="table" summary="TimedReadWriteMutex Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">M::scoped_timed_read_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a> + requirements.</td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_timed_read_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a> + requirements.</td> +</tr> +<tr> +<td><code class="computeroutput">M::scoped_timed_write_lock</code></td> +<td>A type meeting the + <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a> + requirements.</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-mutex-models"></a>Mutex Models</h5></div></div></div> +<p> currently supplies three models of + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> + and its refinements.</p> +<div class="table"> +<a name="id1361580"></a><p class="title"><b>Table 12.15. Mutex Models</b></p> +<table class="table" summary="Mutex Models"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Concept</th> +<th>Refines</th> +<th>Models</th> +</tr></thead> +<tbody> +<tr> +<td><a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a></td> +<td> </td> +<td><code class="computeroutput"><a href="../read_write_mutex.html" title="Class read_write_mutex">boost::read_write_mutex</a></code></td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a></td> +<td><a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a></td> +<td><code class="computeroutput"><a href="../try_read_write_mutex.html" title="Class try_read_write_mutex">boost::try_read_write_mutex</a></code></td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept">TimedReadWriteMutex</a></td> +<td><a href="concepts.html#threads.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a></td> +<td><code class="computeroutput"><a href="../timed_read_write_mutex.html" title="Class timed_read_write_mutex">boost::timed_read_write_mutex</a></code></td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-lock-concepts"></a>Lock Concepts</h5></div></div></div> +<div class="toc"><dl> +<dt><span class="section"><a href="concepts.html#threads.concepts.ReadWriteLock">ReadWriteLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedReadWriteLock">ScopedReadWriteLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TryReadWriteLock">TryReadWriteLock Expressions</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTryReadWriteLock">ScopedTryReadWriteLock Expressions</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.TimedReadWriteLock">TimedReadWriteLock Concept</a></span></dt> +<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTimedReadWriteLock">ScopedTimedReadWriteLock Concept</a></span></dt> +</dl></div> +<p>A read/write lock object provides a safe means for locking + and unlocking a read/write mutex object (an object whose type is + a model of + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> + or one of its refinements). In other words they are an + implementation of the <span class="emphasis"><em>Scoped Locking</em></span> pattern. The + <a href="concepts.html#threads.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a>, + <a href="concepts.html#threads.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a>, and + <a href="concepts.html#threads.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a> + concepts formalize the requirements.</p> +<p>Read/write lock objects are constructed with a reference to a + read/write mutex object and typically acquire ownership of the + read/write mutex object by setting its state to locked. They also + ensure ownership is relinquished in the destructor. Lock objects + also expose functions to query the lock status and to manually lock + and unlock the read/write mutex object.</p> +<p>Read/write lock objects are meant to be short lived, expected + to be used at block scope only. The read/write lock objects are not + <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a>. + Read/write lock objects 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 a read/write lock object + should never be shared between multiple threads.</p> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ReadWriteLock"></a>ReadWriteLock Concept</h6></div></div></div> +<p>For a read/write lock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> + and const object <code class="computeroutput">clk</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1361782"></a><p class="title"><b>Table 12.16. ReadWriteLock Expressions</b></p> +<table class="table" summary="ReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">(&lk)->~L();</code></td> +<td><code class="computeroutput">if (locked()) unlock();</code></td> +</tr> +<tr> +<td><code class="computeroutput">(&clk)->operator const void*()</code></td> +<td>Returns type void*, non-zero if the associated read/write + mutex object has been either read-locked or write-locked by + <code class="computeroutput">clk</code>, otherwise 0.</td> +</tr> +<tr> +<td><code class="computeroutput">clk.locked()</code></td> +<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->operator + const void*() != 0</code> +</td> +</tr> +<tr> +<td><code class="computeroutput">clk.state()</code></td> +<td>Returns an enumeration constant of type <code class="computeroutput">read_write_lock_state</code>: + <code class="computeroutput">read_write_lock_state::read_locked</code> if the associated read/write mutex object has been + read-locked by <code class="computeroutput">clk</code>, <code class="computeroutput">read_write_lock_state::write_locked</code> if it + has been write-locked by <code class="computeroutput">clk</code>, and <code class="computeroutput">read_write_lock_state::unlocked</code> + if has not been locked by <code class="computeroutput">clk</code>.</td> +</tr> +<tr> +<td><code class="computeroutput">clk.read_locked()</code></td> +<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->state() == read_write_lock_state::read_locked</code>.</td> +</tr> +<tr> +<td><code class="computeroutput">clk.write_locked()</code></td> +<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->state() == read_write_lock_state::write_locked</code>.</td> +</tr> +<tr> +<td><code class="computeroutput">lk.read_lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">locked()</code>.</p> +<p>If the associated read/write mutex + object is already read-locked by some other + thread, the effect depends on the + <a href="concepts.html#threads.concepts.read-write-scheduling-policies.inter-class" title="Inter-Class Scheduling Policies">inter-class scheduling policy</a> + of the associated read/write mutex: + either immediately obtains an additional + read-lock on the associated read/write + mutex, or places the current thread in the + <a href="../threads.html#threads.glossary.thread-state">Blocked</a> + state until the associated read/write mutex + is unlocked, after which the current thread + is placed in the + <a href="../threads.html#threads.glossary.thread-state">Ready</a> + state, eventually to be returned to the + <a href="../threads.html#threads.glossary.thread-state">Running</a> + state.</p> +<p>If the associated read/write mutex + object is already write-locked by some other + thread, places the current thread in the + <a href="../threads.html#threads.glossary.thread-state">Blocked</a> + state until the associated read/write mutex + is unlocked, after which the current thread + is placed in the + <a href="../threads.html#threads.glossary.thread-state">Ready</a> + state, eventually to be returned to the + <a href="../threads.html#threads.glossary.thread-state">Running</a> + state.</p> +<p>If the associated read/write mutex + object is already locked by the same thread + the behavior is dependent on the + <a href="concepts.html#threads.concepts.read-write-locking-strategies" title="Locking Strategies">locking strategy</a> + of the associated read/write mutex object. + </p> +<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::read_locked</code></p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.write_lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">locked()</code>.</p> +<p>If the associated read/write mutex + object is already locked by some other + thread, places the current thread in the + <a href="../threads.html#threads.glossary.thread-state">Blocked</a> + state until the associated read/write mutex + is unlocked, after which the current thread + is placed in the + <a href="../threads.html#threads.glossary.thread-state">Ready</a> + state, eventually to be returned to the + <a href="../threads.html#threads.glossary.thread-state">Running</a> + state.</p> +<p>If the associated read/write mutex + object is already locked by the same thread + the behavior is dependent on the + <a href="concepts.html#threads.concepts.read-write-locking-strategies" title="Locking Strategies">locking strategy</a> + of the associated read/write mutex object. + </p> +<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::write_locked</code></p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.demote()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p> +<p>Converts the lock held on the associated read/write mutex + object from a write-lock to a read-lock without releasing + the lock.</p> +<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::read_locked</code></p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.promote()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::read_locked</code> + or if the lock cannot be promoted because another lock + on the same mutex is already waiting to be promoted.</p> +<p>Makes a blocking attempt to convert the lock held on the associated + read/write mutex object from a read-lock to a write-lock without releasing + the lock.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.unlock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">!locked()</code>.</p> +<p>Unlocks the associated read/write mutex.</p> +<p>Postcondition: <code class="computeroutput">!locked()</code></p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedReadWriteLock"></a>ScopedReadWriteLock Concept</h6></div></div></div> +<p>A ScopedReadWriteLock is a refinement of + <a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a>. + For a ScopedReadWriteLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> requirements, + and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1362317"></a><p class="title"><b>Table 12.17. ScopedReadWriteLock Expressions</b></p> +<table class="table" summary="ScopedReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td><code class="computeroutput">L lk(m,s);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex + object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls + <code class="computeroutput">read_lock()</code>; if <code class="computeroutput">s==read_write_lock_state::write_locked</code>, + calls <code class="computeroutput">write_lock()</code>.</td> +</tr></tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TryReadWriteLock"></a>TryReadWriteLock Expressions</h6></div></div></div> +<p>A TryReadWriteLock is a refinement of + <a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a>. + For a TryReadWriteLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1362411"></a><p class="title"><b>Table 12.18. TryReadWriteLock Expressions</b></p> +<table class="table" summary="TryReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">lk.try_read_lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a non-blocking attempt to read-lock the associated read/write + mutex object, returning <code class="computeroutput">true</code> if the attempt is successful, + otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is + already locked by the same thread the behavior is dependent on the + <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated read/write mutex object.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.try_write_lock()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a non-blocking attempt to write-lock the associated read/write + mutex object, returning <code class="computeroutput">true</code> if the attempt is successful, + otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is + already locked by the same thread the behavior is dependent on the + <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated read/write mutex object.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.try_demote()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p> +<p>Makes a non-blocking attempt to convert the lock held on the associated + read/write mutex object from a write-lock to a read-lock without releasing + the lock, returning <code class="computeroutput">true</code> if the attempt is successful, + otherwise <code class="computeroutput">false</code>.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.try_promote()</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::read_locked</code>.</p> +<p>Makes a non-blocking attempt to convert the lock held on the associated + read/write mutex object from a read-lock to a write-lock without releasing + the lock, returning <code class="computeroutput">true</code> if the attempt is successful, + otherwise <code class="computeroutput">false</code>.</p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedTryReadWriteLock"></a>ScopedTryReadWriteLock Expressions</h6></div></div></div> +<p>A ScopedTryReadWriteLock is a refinement of + <a href="concepts.html#threads.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a>. + For a ScopedTryReadWriteLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryReadWriteMutex</a> requirements, + and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>, + and an object <code class="computeroutput">b</code> of type <code class="computeroutput">blocking_mode</code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1362685"></a><p class="title"><b>Table 12.19. ScopedTryReadWriteLock Expressions</b></p> +<table class="table" summary="ScopedTryReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody><tr> +<td><code class="computeroutput">L lk(m,s,b);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex + object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls + <code class="computeroutput">read_lock()</code> if <code class="computeroutput">b</code>, otherwise <code class="computeroutput">try_read_lock()</code>; + if <code class="computeroutput">s==read_write_lock_state::write_locked</code>, calls <code class="computeroutput">write_lock()</code> if <code class="computeroutput">b</code>, + otherwise <code class="computeroutput">try_write_lock</code>.</td> +</tr></tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.TimedReadWriteLock"></a>TimedReadWriteLock Concept</h6></div></div></div> +<p>A TimedReadWriteLock is a refinement of + <a href="concepts.html#threads.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a>. + For a TimedReadWriteLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>, + the following expressions must be well-formed + and have the indicated effects.</p> +<div class="table"> +<a name="id1362819"></a><p class="title"><b>Table 12.20. TimedReadWriteLock Expressions</b></p> +<table class="table" summary="TimedReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">lk.timed_read_lock(t)</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a blocking attempt to read-lock the associated read/write mutex object, + and returns <code class="computeroutput">true</code> if successful within the specified time <code class="computeroutput">t</code>, + otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is already + locked by the same thread the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated read/write mutex object.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.timed_write_lock(t)</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if locked().</p> +<p>Makes a blocking attempt to write-lock the associated read/write mutex object, + and returns <code class="computeroutput">true</code> if successful within the specified time <code class="computeroutput">t</code>, + otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is already + locked by the same thread the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking + strategy</a> of the associated read/write mutex object.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.timed_demote(t)</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p> +<p>Makes a blocking attempt to convert the lock held on the associated + read/write mutex object from a write-lock to a read-lock without releasing + the lock, returning <code class="computeroutput">true</code> if the attempt is successful + in the specified time <code class="computeroutput">t</code>, otherwise <code class="computeroutput">false</code>.</p> +</td> +</tr> +<tr> +<td><code class="computeroutput">lk.timed_promote(t)</code></td> +<td> +<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> + if <code class="computeroutput">state() != read_write_lock_state::read_locked</code>.</p> +<p>Makes a blocking attempt to convert the lock held on the associated + read/write mutex object from a read-lock to a write-lock without releasing + the lock, returning <code class="computeroutput">true</code> if the attempt is successful + in the specified time <code class="computeroutput">t</code>, otherwise <code class="computeroutput">false</code>.</p> +</td> +</tr> +</tbody> +</table> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h6 class="title"> +<a name="threads.concepts.ScopedTimedReadWriteLock"></a>ScopedTimedReadWriteLock Concept</h6></div></div></div> +<p>A ScopedTimedReadWriteLock is a refinement of + <a href="concepts.html#threads.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a>. + For a ScopedTimedReadWriteLock type <code class="computeroutput">L</code> + and an object <code class="computeroutput">lk</code> of that type, + and an object <code class="computeroutput">m</code> of a type meeting the + <a href="concepts.html#threads.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept">TimedReadWriteMutex</a> requirements, + and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>, + and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>, + and an object <code class="computeroutput">b</code> of type <code class="computeroutput">blocking_mode</code>, + the following expressions must be well-formed and have the + indicated effects.</p> +<div class="table"> +<a name="id1363131"></a><p class="title"><b>Table 12.21. ScopedTimedReadWriteLock Expressions</b></p> +<table class="table" summary="ScopedTimedReadWriteLock Expressions"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th>Expression</th> +<th>Effects</th> +</tr></thead> +<tbody> +<tr> +<td><code class="computeroutput">L lk(m,s,b);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex + object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls + <code class="computeroutput">read_lock()</code> if <code class="computeroutput">b</code>, otherwise <code class="computeroutput">try_read_lock()</code>; + if <code class="computeroutput">s==read_write_lock_state::write_locked</code>, calls <code class="computeroutput">write_lock()</code> if <code class="computeroutput">b</code>, + otherwise <code class="computeroutput">try_write_lock</code>.</td> +</tr> +<tr> +<td><code class="computeroutput">L lk(m,s,t);</code></td> +<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex + object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls + <code class="computeroutput">timed_read_lock(t)</code>; if <code class="computeroutput">s==read_write_lock_state::write_locked</code>, + calls <code class="computeroutput">timed_write_lock(t)</code>.</td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="section" lang="en"> +<div class="titlepage"><div><div><h5 class="title"> +<a name="threads.concepts.read-write-lock-models"></a>Lock Models</h5></div></div></div> +<p> currently supplies six models of + <a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a> + and its refinements.</p> +<div class="table"> +<a name="id1555521"></a><p class="title"><b>Table 12.22. Lock Models</b></p> +<table class="table" summary="Lock Models"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead><tr> +<th>Concept</th> +<th>Refines</th> +<th>Models</th> +</tr></thead> +<tbody> +<tr> +<td><a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td> +<td> </td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a></td> +<td><a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td> +<td> +<p><code class="computeroutput">boost::read_write_mutex::scoped_read_write_lock</code></p> +<p><code class="computeroutput">boost::try_read_write_mutex::scoped_read_write_lock</code></p> +<p><code class="computeroutput">boost::timed_read_write_mutex::scoped_read_write_lock</code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td> +<td><a href="concepts.html#threads.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a></td> +<td><a href="concepts.html#threads.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td> +<td> +<p><code class="computeroutput">boost::try_read_write_mutex::scoped_try_read_write_lock</code></p> +<p><code class="computeroutput">boost::timed_read_write_mutex::scoped_try_read_write_lock</code></p> +</td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a></td> +<td><a href="concepts.html#threads.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td> +<td> </td> +</tr> +<tr> +<td><a href="concepts.html#threads.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a></td> +<td><a href="concepts.html#threads.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a></td> +<td><p><code class="computeroutput">boost::timed_read_write_mutex::scoped_timed_read_write_lock</code></p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +</div> +<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> +<td align="left"><small><p>Last revised: November 28, 2004 at 04:29:36 GMT</p></small></td> +<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td> +</tr></table> +<hr> +<div class="spirit-nav"> +<a accesskey="p" href="design.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../threads.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a> +</div> +</body> +</html> |