Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_34_1/doc/html/thread/concepts.html @ 47

Last change on this file since 47 was 29, checked in by landauf, 17 years ago
updated boost from 1_33_1 to 1_34_1
File size: 107.2 KB

Line
1	<html>
2	<head>
3	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4	<title>Concepts</title>
5	<link rel="stylesheet" href="../boostbook.css" type="text/css">
6	<meta name="generator" content="DocBook XSL Stylesheets V1.68.1">
7	<link rel="start" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
8	<link rel="up" href="../thread.html" title="Chapter 15. Boost.Thread">
9	<link rel="prev" href="design.html" title="Design">
10	<link rel="next" href="rationale.html" title="Rationale">
11	</head>
12	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13	<table cellpadding="2" width="100%">
14	<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
15	<td align="center"><a href="../../../index.htm">Home</a></td>
16	<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
17	<td align="center"><a href="../../../people/people.htm">People</a></td>
18	<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
19	<td align="center"><a href="../../../more/index.htm">More</a></td>
20	</table>
21	<hr>
22	<div class="spirit-nav">
23	<a accesskey="p" href="design.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread.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>
24	</div>
25	<div class="section" lang="en">
26	<div class="titlepage"><div><div><h2 class="title" style="clear: both">
27	<a name="thread.concepts"></a>Concepts</h2></div></div></div>
28	<div class="toc"><dl>
29	<dt><span class="section"><a href="concepts.html#thread.concepts.mutexes">Mutexes</a></span></dt>
30	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-mutexes">Read/Write Mutexes</a></span></dt>
31	</dl></div>
32	<p><span class="bold"><strong>Boost.Thread</strong></span> currently supports two types of mutex concepts:
33	ordinary <a href="concepts.html#thread.concepts.mutexes" title="Mutexes">Mutexes</a>,
34	which allow only one thread at a time to access a resource, and
35	<a href="concepts.html#thread.concepts.read-write-mutexes" title="Read/Write Mutexes">Read/Write Mutexes</a>,
36	which allow only one thread at a time to access a resource when it is
37	being modified (the "Write" part of Read/Write), but allows multiple threads
38	to access a resource when it is only being referenced (the "Read" part of
39	Read/Write).</p>
40	<div class="note"><table border="0" summary="Note">
41	<tr>
42	<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
43	<th align="left">Note</th>
44	</tr>
45	<tr><td align="left" valign="top"> Unfortunately it turned out that the current implementation of Read/Write Mutex has
46	some serious problems. So it was decided not to put this implementation into
47	release grade code. Also discussions on the mailing list led to the
48	conclusion that the current concepts need to be rethought. In particular
49	the schedulings <a href="concepts.html#thread.concepts.read-write-scheduling-policies.inter-class" title="Inter-Class Scheduling Policies">
50	Inter-Class Scheduling Policies</a> are deemed unnecessary.
51	There seems to be common belief that a fair scheme suffices.
52	The following documentation has been retained however, to give
53	readers of this document the opportunity to study the original design.
54	</td></tr>
55	</table></div>
56	<div class="section" lang="en">
57	<div class="titlepage"><div><div><h3 class="title">
58	<a name="thread.concepts.mutexes"></a>Mutexes</h3></div></div></div>
59	<div class="toc"><dl>
60	<dt><span class="section"><a href="concepts.html#thread.concepts.locking-strategies">Locking Strategies</a></span></dt>
61	<dt><span class="section"><a href="concepts.html#thread.concepts.sheduling-policies">Scheduling Policies</a></span></dt>
62	<dt><span class="section"><a href="concepts.html#thread.concepts.mutex-concepts">Mutex Concepts</a></span></dt>
63	<dt><span class="section"><a href="concepts.html#thread.concepts.mutex-models">Mutex Models</a></span></dt>
64	<dt><span class="section"><a href="concepts.html#thread.concepts.lock-concepts">Lock Concepts</a></span></dt>
65	<dt><span class="section"><a href="concepts.html#thread.concepts.lock-models">Lock Models</a></span></dt>
66	</dl></div>
67	<div class="note"><table border="0" summary="Note">
68	<tr>
69	<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
70	<th align="left">Note</th>
71	</tr>
72	<tr><td align="left" valign="top">Certain changes to the mutexes and lock concepts are
73	currently under discussion. In particular, the combination of
74	the multiple lock concepts into a single lock concept
75	is likely, and the combination of the multiple mutex
76	concepts into a single mutex concept is also possible.</td></tr>
77	</table></div>
78	<p>A mutex (short for mutual-exclusion) object is used to serialize
79	access to a resource shared between multiple threads. The
80	<a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a> concept, with
81	<a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> and
82	<a href="concepts.html#thread.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> refinements,
83	formalize the requirements. A model that implements Mutex and its
84	refinements has two states: <span class="bold"><strong>locked</strong></span> and
85	<span class="bold"><strong>unlocked</strong></span>. Before using a shared resource, a
86	thread locks a <span class="bold"><strong>Boost.Thread</strong></span> mutex object
87	(an object whose type is a model of
88	<a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of it's
89	refinements), ensuring
90	<a href="../thread.html#thread.glossary.thread-safe">thread-safe</a> access to
91	the shared resource. When use of the shared resource is complete, the thread
92	unlocks the mutex object, allowing another thread to acquire the lock and
93	use the shared resource.</p>
94	<p>Traditional C thread APIs, like POSIX threads or the Windows thread
95	APIs, expose functions to lock and unlock a mutex object. This is dangerous
96	since it's easy to forget to unlock a locked mutex. When the flow of control
97	is complex, with multiple return points, the likelihood of forgetting to
98	unlock a mutex object becomes even greater. When exceptions are thrown,
99	it becomes nearly impossible to ensure that the mutex object is unlocked
100	properly when using these traditional API's. The result is
101	<a href="../thread.html#thread.glossary.deadlock">deadlock</a>.</p>
102	<p>Many C++ threading libraries use a pattern known as <span class="emphasis"><em>Scoped
103	Locking</em></span> [<span class="citation"><a href="../thread.html#thread.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] to free the programmer from
104	the need to explicitly lock and unlock mutex objects. With this pattern, a
105	<a href="concepts.html#thread.concepts.lock-concepts" title="Lock Concepts">Lock</a> concept is employed where
106	the lock object's constructor locks the associated mutex object and the
107	destructor automatically does the unlocking. The
108	<span class="bold"><strong>Boost.Thread</strong></span> library takes this pattern to
109	the extreme in that Lock concepts are the only way to lock and unlock a
110	mutex object: lock and unlock functions are not exposed by any
111	<span class="bold"><strong>Boost.Thread</strong></span> mutex objects. This helps to
112	ensure safe usage patterns, especially when code throws exceptions.</p>
113	<div class="section" lang="en">
114	<div class="titlepage"><div><div><h4 class="title">
115	<a name="thread.concepts.locking-strategies"></a>Locking Strategies</h4></div></div></div>
116	<div class="toc"><dl>
117	<dt><span class="section"><a href="concepts.html#thread.concepts.recursive-locking-strategy">Recursive Locking Strategy</a></span></dt>
118	<dt><span class="section"><a href="concepts.html#thread.concepts.checked-locking-strategy">Checked Locking Strategy</a></span></dt>
119	<dt><span class="section"><a href="concepts.html#thread.concepts.unchecked-locking-strategy">Unchecked Locking Strategy</a></span></dt>
120	<dt><span class="section"><a href="concepts.html#thread.concepts.unspecified-locking-strategy">Unspecified Locking Strategy</a></span></dt>
121	</dl></div>
122	<p>Every mutex object follows one of several locking strategies. These
123	strategies define the semantics for the locking operation when the calling
124	thread already owns a lock on the mutex object.</p>
125	<div class="section" lang="en">
126	<div class="titlepage"><div><div><h5 class="title">
127	<a name="thread.concepts.recursive-locking-strategy"></a>Recursive Locking Strategy</h5></div></div></div>
128	<p>With a recursive locking strategy, when a thread attempts to acquire
129	a lock on the mutex object for which it already owns a lock, the operation
130	is successful. Note the distinction between a thread, which may have
131	multiple locks outstanding on a recursive mutex object, and a lock object,
132	which even for a recursive mutex object cannot have any of its lock
133	functions called multiple times without first calling unlock.</p>
134	<p>Internally a lock count is maintained and the owning thread must
135	unlock the mutex object the same number of times that it locked it before
136	the mutex object's state returns to unlocked. Since mutex objects in
137	<span class="bold"><strong>Boost.Thread</strong></span> expose locking
138	functionality only through lock concepts, a thread will always unlock a
139	mutex object the same number of times that it locked it. This helps to
140	eliminate a whole set of errors typically found in traditional C style
141	thread APIs.</p>
142	<p>Classes <code class="computeroutput"><a href="../boost/recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code>,
143	<code class="computeroutput"><a href="../boost/recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code> and
144	<code class="computeroutput"><a href="../boost/recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code> use this locking
145	strategy.</p>
146	</div>
147	<div class="section" lang="en">
148	<div class="titlepage"><div><div><h5 class="title">
149	<a name="thread.concepts.checked-locking-strategy"></a>Checked Locking Strategy</h5></div></div></div>
150	<p>With a checked locking strategy, when a thread attempts to acquire a
151	lock on the mutex object for which the thread already owns a lock, the
152	operation will fail with some sort of error indication. Further, attempts
153	by a thread to unlock a mutex object that was not locked by the thread
154	will also return some sort of error indication. In
155	<span class="bold"><strong>Boost.Thread</strong></span>, an exception of type
156	<code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
157	would be thrown in these cases.</p>
158	<p><span class="bold"><strong>Boost.Thread</strong></span> does not currently
159	provide any mutex objects that use this strategy.</p>
160	</div>
161	<div class="section" lang="en">
162	<div class="titlepage"><div><div><h5 class="title">
163	<a name="thread.concepts.unchecked-locking-strategy"></a>Unchecked Locking Strategy</h5></div></div></div>
164	<p>With an unchecked locking strategy, when a thread attempts to acquire
165	a lock on a mutex object for which the thread already owns a lock the
166	operation will
167	<a href="../thread.html#thread.glossary.deadlock">deadlock</a>. In general
168	this locking strategy is less safe than a checked or recursive strategy,
169	but it's also a faster strategy and so is employed by many libraries.</p>
170	<p><span class="bold"><strong>Boost.Thread</strong></span> does not currently
171	provide any mutex objects that use this strategy.</p>
172	</div>
173	<div class="section" lang="en">
174	<div class="titlepage"><div><div><h5 class="title">
175	<a name="thread.concepts.unspecified-locking-strategy"></a>Unspecified Locking Strategy</h5></div></div></div>
176	<p>With an unspecified locking strategy, when a thread attempts to
177	acquire a lock on a mutex object for which the thread already owns a lock
178	the operation results in
179	<a href="../thread.html#thread.glossary.undefined-behavior">undefined behavior</a>.
180	</p>
181	<p>In general a mutex object with an unspecified locking strategy is
182	unsafe, and it requires programmer discipline to use the mutex object
183	properly. However, this strategy allows an implementation to be as fast as
184	possible with no restrictions on its implementation. This is especially
185	true for portable implementations that wrap the native threading support
186	of a platform. For this reason, the classes
187	<code class="computeroutput"><a href="../boost/mutex.html" title="Class mutex">boost::mutex</a></code>,
188	<code class="computeroutput"><a href="../boost/try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code> and
189	<code class="computeroutput"><a href="../boost/timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code> use this locking strategy
190	despite the lack of safety.</p>
191	</div>
192	</div>
193	<div class="section" lang="en">
194	<div class="titlepage"><div><div><h4 class="title">
195	<a name="thread.concepts.sheduling-policies"></a>Scheduling Policies</h4></div></div></div>
196	<div class="toc"><dl>
197	<dt><span class="section"><a href="concepts.html#thread.concepts.FIFO-scheduling-policy">FIFO Scheduling Policy</a></span></dt>
198	<dt><span class="section"><a href="concepts.html#thread.concepts.priority-driven-scheduling-policy">Priority Driven Policy</a></span></dt>
199	<dt><span class="section"><a href="concepts.html#thread.concepts.unspecified-scheduling-policy">Unspecified Policy</a></span></dt>
200	</dl></div>
201	<p>Every mutex object follows one of several scheduling policies. These
202	policies define the semantics when the mutex object is unlocked and there is
203	more than one thread waiting to acquire a lock. In other words, the policy
204	defines which waiting thread shall acquire the lock.</p>
205	<div class="section" lang="en">
206	<div class="titlepage"><div><div><h5 class="title">
207	<a name="thread.concepts.FIFO-scheduling-policy"></a>FIFO Scheduling Policy</h5></div></div></div>
208	<p>With a FIFO ("First In First Out") scheduling policy, threads waiting
209	for the lock will acquire it in a first-come-first-served order.
210	This can help prevent a high priority thread from starving lower priority
211	threads that are also waiting on the mutex object's lock.</p>
212	</div>
213	<div class="section" lang="en">
214	<div class="titlepage"><div><div><h5 class="title">
215	<a name="thread.concepts.priority-driven-scheduling-policy"></a>Priority Driven Policy</h5></div></div></div>
216	<p>With a Priority Driven scheduling policy, the thread with the
217	highest priority acquires the lock. Note that this means that low-priority
218	threads may never acquire the lock if the mutex object has high contention
219	and there is always at least one high-priority thread waiting. This is
220	known as thread starvation. When multiple threads of the same priority are
221	waiting on the mutex object's lock one of the other scheduling priorities
222	will determine which thread shall acquire the lock.</p>
223	</div>
224	<div class="section" lang="en">
225	<div class="titlepage"><div><div><h5 class="title">
226	<a name="thread.concepts.unspecified-scheduling-policy"></a>Unspecified Policy</h5></div></div></div>
227	<p>The mutex object does not specify a scheduling policy. In order to
228	ensure portability, all <span class="bold"><strong>Boost.Thread</strong></span>
229	mutex objects use an unspecified scheduling policy.</p>
230	</div>
231	</div>
232	<div class="section" lang="en">
233	<div class="titlepage"><div><div><h4 class="title">
234	<a name="thread.concepts.mutex-concepts"></a>Mutex Concepts</h4></div></div></div>
235	<div class="toc"><dl>
236	<dt><span class="section"><a href="concepts.html#thread.concepts.Mutex">Mutex Concept</a></span></dt>
237	<dt><span class="section"><a href="concepts.html#thread.concepts.TryMutex">TryMutex Concept</a></span></dt>
238	<dt><span class="section"><a href="concepts.html#thread.concepts.TimedMutex">TimedMutex Concept</a></span></dt>
239	</dl></div>
240	<div class="section" lang="en">
241	<div class="titlepage"><div><div><h5 class="title">
242	<a name="thread.concepts.Mutex"></a>Mutex Concept</h5></div></div></div>
243	<p>A Mutex object has two states: locked and unlocked. Mutex object
244	state can only be determined by a lock object meeting the
245	appropriate lock concept requirements
246	and constructed for the Mutex object.</p>
247	<p>A Mutex is
248	<a href="../../../libs/utility/utility.htm#Class%20noncopyable" target="_top">
249	NonCopyable</a>.</p>
250	<p>For a Mutex type <code class="computeroutput">M</code>
251	and an object <code class="computeroutput">m</code> of that type,
252	the following expressions must be well-formed
253	and have the indicated effects.</p>
254	<div class="table">
255	<a name="id1711496"></a><p class="title"><b>Table 15.1. Mutex Expressions</b></p>
256	<table class="table" summary="Mutex Expressions">
257	<colgroup>
258	<col>
259	<col>
260	</colgroup>
261	<thead><tr>
262	<th>Expression</th>
263	<th>Effects</th>
264	</tr></thead>
265	<tbody>
266	<tr>
267	<td>M m;</td>
268	<td>
269	<p>Constructs a mutex object m.</p>
270	<p>Postcondition: m is unlocked.</p>
271	</td>
272	</tr>
273	<tr>
274	<td>(&m)->~M();</td>
275	<td>Precondition: m is unlocked. Destroys a mutex object
276	m.</td>
277	</tr>
278	<tr>
279	<td>M::scoped_lock</td>
280	<td>A model of
281	<a href="concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
282	</td>
283	</tr>
284	</tbody>
285	</table>
286	</div>
287	</div>
288	<div class="section" lang="en">
289	<div class="titlepage"><div><div><h5 class="title">
290	<a name="thread.concepts.TryMutex"></a>TryMutex Concept</h5></div></div></div>
291	<p>A TryMutex is a refinement of
292	<a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a>.
293	For a TryMutex type <code class="computeroutput">M</code>
294	and an object <code class="computeroutput">m</code> of that type,
295	the following expressions must be well-formed
296	and have the indicated effects.</p>
297	<div class="table">
298	<a name="id1711605"></a><p class="title"><b>Table 15.2. TryMutex Expressions</b></p>
299	<table class="table" summary="TryMutex Expressions">
300	<colgroup>
301	<col>
302	<col>
303	</colgroup>
304	<thead><tr>
305	<th>Expression</th>
306	<th>Effects</th>
307	</tr></thead>
308	<tbody><tr>
309	<td>M::scoped_try_lock</td>
310	<td>A model of
311	<a href="concepts.html#thread.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>
312	</td>
313	</tr></tbody>
314	</table>
315	</div>
316	</div>
317	<div class="section" lang="en">
318	<div class="titlepage"><div><div><h5 class="title">
319	<a name="thread.concepts.TimedMutex"></a>TimedMutex Concept</h5></div></div></div>
320	<p>A TimedMutex is a refinement of
321	<a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryMutex</a>.
322	For a TimedMutex type <code class="computeroutput">M</code>
323	and an object <code class="computeroutput">m</code> of that type,
324	the following expressions must be well-formed
325	and have the indicated effects.</p>
326	<div class="table">
327	<a name="id1711688"></a><p class="title"><b>Table 15.3. TimedMutex Expressions</b></p>
328	<table class="table" summary="TimedMutex Expressions">
329	<colgroup>
330	<col>
331	<col>
332	</colgroup>
333	<thead><tr>
334	<th>Expression</th>
335	<th>Effects</th>
336	</tr></thead>
337	<tbody><tr>
338	<td>M::scoped_timed_lock</td>
339	<td>A model of
340	<a href="concepts.html#thread.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
341	</td>
342	</tr></tbody>
343	</table>
344	</div>
345	</div>
346	</div>
347	<div class="section" lang="en">
348	<div class="titlepage"><div><div><h4 class="title">
349	<a name="thread.concepts.mutex-models"></a>Mutex Models</h4></div></div></div>
350	<p><span class="bold"><strong>Boost.Thread</strong></span> currently supplies six models of
351	<a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a>
352	and its refinements.</p>
353	<div class="table">
354	<a name="id1711764"></a><p class="title"><b>Table 15.4. Mutex Models</b></p>
355	<table class="table" summary="Mutex Models">
356	<colgroup>
357	<col>
358	<col>
359	<col>
360	</colgroup>
361	<thead><tr>
362	<th>Concept</th>
363	<th>Refines</th>
364	<th>Models</th>
365	</tr></thead>
366	<tbody>
367	<tr>
368	<td><a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a></td>
369	<td> </td>
370	<td>
371	<p><code class="computeroutput"><a href="../boost/mutex.html" title="Class mutex">boost::mutex</a></code></p>
372	<p><code class="computeroutput"><a href="../boost/recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code></p>
373	</td>
374	</tr>
375	<tr>
376	<td><a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td>
377	<td><a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a></td>
378	<td>
379	<p><code class="computeroutput"><a href="../boost/try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code></p>
380	<p><code class="computeroutput"><a href="../boost/recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code></p>
381	</td>
382	</tr>
383	<tr>
384	<td><a href="concepts.html#thread.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a></td>
385	<td><a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td>
386	<td>
387	<p><code class="computeroutput"><a href="../boost/timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code></p>
388	<p><code class="computeroutput"><a href="../boost/recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code></p>
389	</td>
390	</tr>
391	</tbody>
392	</table>
393	</div>
394	</div>
395	<div class="section" lang="en">
396	<div class="titlepage"><div><div><h4 class="title">
397	<a name="thread.concepts.lock-concepts"></a>Lock Concepts</h4></div></div></div>
398	<div class="toc"><dl>
399	<dt><span class="section"><a href="concepts.html#thread.concepts.Lock">Lock Concept</a></span></dt>
400	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedLock">ScopedLock Concept</a></span></dt>
401	<dt><span class="section"><a href="concepts.html#thread.concepts.TryLock">TryLock Concept</a></span></dt>
402	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedTryLock">ScopedTryLock Concept</a></span></dt>
403	<dt><span class="section"><a href="concepts.html#thread.concepts.TimedLock">TimedLock Concept</a></span></dt>
404	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedTimedLock">ScopedTimedLock Concept</a></span></dt>
405	</dl></div>
406	<p>A lock object provides a safe means for locking and unlocking a mutex
407	object (an object whose type is a model of <a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of its refinements). In
408	other words they are an implementation of the <span class="emphasis"><em>Scoped
409	Locking</em></span> [<span class="citation"><a href="../thread.html#thread.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] pattern. The <a href="concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>,
410	<a href="concepts.html#thread.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>, and
411	<a href="concepts.html#thread.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
412	concepts formalize the requirements.</p>
413	<p>Lock objects are constructed with a reference to a mutex object and
414	typically acquire ownership of the mutex object by setting its state to
415	locked. They also ensure ownership is relinquished in the destructor. Lock
416	objects also expose functions to query the lock status and to manually lock
417	and unlock the mutex object.</p>
418	<p>Lock objects are meant to be short lived, expected to be used at block
419	scope only. The lock objects are not <a href="../thread.html#thread.glossary.thread-safe">thread-safe</a>. Lock objects must
420	maintain state to indicate whether or not they've been locked and this state
421	is not protected by any synchronization concepts. For this reason a lock
422	object should never be shared between multiple threads.</p>
423	<div class="section" lang="en">
424	<div class="titlepage"><div><div><h5 class="title">
425	<a name="thread.concepts.Lock"></a>Lock Concept</h5></div></div></div>
426	<p>For a Lock type <code class="computeroutput">L</code>
427	and an object <code class="computeroutput">lk</code>
428	and const object <code class="computeroutput">clk</code> of that type,
429	the following expressions must be well-formed
430	and have the indicated effects.</p>
431	<div class="table">
432	<a name="id1712048"></a><p class="title"><b>Table 15.5. Lock Expressions</b></p>
433	<table class="table" summary="Lock Expressions">
434	<colgroup>
435	<col>
436	<col>
437	</colgroup>
438	<thead><tr>
439	<th>Expression</th>
440	<th>Effects</th>
441	</tr></thead>
442	<tbody>
443	<tr>
444	<td><code class="computeroutput">(&lk)->~L();</code></td>
445	<td><code class="computeroutput">if (locked()) unlock();</code></td>
446	</tr>
447	<tr>
448	<td><code class="computeroutput">(&clk)->operator const void*()</code></td>
449	<td>Returns type void*, non-zero if the associated mutex
450	object has been locked by <code class="computeroutput">clk</code>, otherwise 0.</td>
451	</tr>
452	<tr>
453	<td><code class="computeroutput">clk.locked()</code></td>
454	<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->operator
455	const void*() != 0</code>
456	</td>
457	</tr>
458	<tr>
459	<td><code class="computeroutput">lk.lock()</code></td>
460	<td>
461	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
462	if <code class="computeroutput">locked()</code>.</p>
463
464	<p>If the associated mutex object is
465	already locked by some other thread, places the current thread in the
466	<a href="../thread.html#thread.glossary.thread-state">Blocked</a> state until
467	the associated mutex is unlocked, after which the current thread
468	is placed in the <a href="../thread.html#thread.glossary.thread-state">Ready</a> state,
469	eventually to be returned to the <a href="../thread.html#thread.glossary.thread-state">Running</a> state. If
470	the associated mutex object is already locked by the same thread
471	the behavior is dependent on the <a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
472	strategy</a> of the associated mutex object.</p>
473
474	<p>Postcondition: <code class="computeroutput">locked() == true</code></p>
475	</td>
476	</tr>
477	<tr>
478	<td><code class="computeroutput">lk.unlock()</code></td>
479	<td>
480	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
481	if <code class="computeroutput">!locked()</code>.</p>
482
483	<p>Unlocks the associated mutex.</p>
484
485	<p>Postcondition: <code class="computeroutput">!locked()</code></p>
486	</td>
487	</tr>
488	</tbody>
489	</table>
490	</div>
491	</div>
492	<div class="section" lang="en">
493	<div class="titlepage"><div><div><h5 class="title">
494	<a name="thread.concepts.ScopedLock"></a>ScopedLock Concept</h5></div></div></div>
495	<p>A ScopedLock is a refinement of <a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a>.
496	For a ScopedLock type <code class="computeroutput">L</code>
497	and an object <code class="computeroutput">lk</code> of that type,
498	and an object <code class="computeroutput">m</code> of a type meeting the
499	<a href="concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a> requirements,
500	and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
501	the following expressions must be well-formed
502	and have the indicated effects.</p>
503	<div class="table">
504	<a name="id1712329"></a><p class="title"><b>Table 15.6. ScopedLock Expressions</b></p>
505	<table class="table" summary="ScopedLock Expressions">
506	<colgroup>
507	<col>
508	<col>
509	</colgroup>
510	<thead><tr>
511	<th>Expression</th>
512	<th>Effects</th>
513	</tr></thead>
514	<tbody>
515	<tr>
516	<td><code class="computeroutput">L lk(m);</code></td>
517	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
518	object <code class="computeroutput">m</code> with it, then calls
519	<code class="computeroutput">lock()</code>
520	</td>
521	</tr>
522	<tr>
523	<td><code class="computeroutput">L lk(m,b);</code></td>
524	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
525	object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
526	<code class="computeroutput">lock()</code>
527	</td>
528	</tr>
529	</tbody>
530	</table>
531	</div>
532	</div>
533	<div class="section" lang="en">
534	<div class="titlepage"><div><div><h5 class="title">
535	<a name="thread.concepts.TryLock"></a>TryLock Concept</h5></div></div></div>
536	<p>A TryLock is a refinement of <a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a>.
537	For a TryLock type <code class="computeroutput">L</code>
538	and an object <code class="computeroutput">lk</code> of that type,
539	the following expressions must be well-formed
540	and have the indicated effects.</p>
541	<div class="table">
542	<a name="id1712459"></a><p class="title"><b>Table 15.7. TryLock Expressions</b></p>
543	<table class="table" summary="TryLock Expressions">
544	<colgroup>
545	<col>
546	<col>
547	</colgroup>
548	<thead><tr>
549	<th>Expression</th>
550	<th>Effects</th>
551	</tr></thead>
552	<tbody><tr>
553	<td><code class="computeroutput">lk.try_lock()</code></td>
554	<td>
555	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
556	if locked().</p>
557
558	<p>Makes a
559	non-blocking attempt to lock the associated mutex object,
560	returning <code class="computeroutput">true</code> if the lock attempt is successful,
561	otherwise <code class="computeroutput">false</code>. If the associated mutex object is
562	already locked by the same thread the behavior is dependent on the
563	<a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
564	strategy</a> of the associated mutex object.</p>
565	</td>
566	</tr></tbody>
567	</table>
568	</div>
569	</div>
570	<div class="section" lang="en">
571	<div class="titlepage"><div><div><h5 class="title">
572	<a name="thread.concepts.ScopedTryLock"></a>ScopedTryLock Concept</h5></div></div></div>
573	<p>A ScopedTryLock is a refinement of <a href="concepts.html#thread.concepts.TryLock" title="TryLock Concept">TryLock</a>.
574	For a ScopedTryLock type <code class="computeroutput">L</code>
575	and an object <code class="computeroutput">lk</code> of that type,
576	and an object <code class="computeroutput">m</code> of a type meeting the
577	<a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> requirements,
578	and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
579	the following expressions must be well-formed
580	and have the indicated effects.</p>
581	<div class="table">
582	<a name="id1712606"></a><p class="title"><b>Table 15.8. ScopedTryLock Expressions</b></p>
583	<table class="table" summary="ScopedTryLock Expressions">
584	<colgroup>
585	<col>
586	<col>
587	</colgroup>
588	<thead><tr>
589	<th>Expression</th>
590	<th>Effects</th>
591	</tr></thead>
592	<tbody>
593	<tr>
594	<td><code class="computeroutput">L lk(m);</code></td>
595	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
596	object <code class="computeroutput">m</code> with it, then calls
597	<code class="computeroutput">try_lock()</code>
598	</td>
599	</tr>
600	<tr>
601	<td><code class="computeroutput">L lk(m,b);</code></td>
602	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
603	object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
604	<code class="computeroutput">lock()</code>
605	</td>
606	</tr>
607	</tbody>
608	</table>
609	</div>
610	</div>
611	<div class="section" lang="en">
612	<div class="titlepage"><div><div><h5 class="title">
613	<a name="thread.concepts.TimedLock"></a>TimedLock Concept</h5></div></div></div>
614	<p>A TimedLock is a refinement of <a href="concepts.html#thread.concepts.TryLock" title="TryLock Concept">TryLock</a>.
615	For a TimedLock type <code class="computeroutput">L</code>
616	and an object <code class="computeroutput">lk</code> of that type,
617	and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../boost/xtime.html" title="Struct xtime">boost::xtime</a></code>,
618	the following expressions must be well-formed
619	and have the indicated effects.</p>
620	<div class="table">
621	<a name="id1730230"></a><p class="title"><b>Table 15.9. TimedLock Expressions</b></p>
622	<table class="table" summary="TimedLock Expressions">
623	<colgroup>
624	<col>
625	<col>
626	</colgroup>
627	<thead><tr>
628	<th>Expression</th>
629	<th>Effects</th>
630	</tr></thead>
631	<tbody><tr>
632	<td><code class="computeroutput">lk.timed_lock(t)</code></td>
633	<td>
634	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
635	if locked().</p>
636
637	<p>Makes a blocking attempt
638	to lock the associated mutex object, and returns <code class="computeroutput">true</code>
639	if successful within the specified time <code class="computeroutput">t</code>, otherwise
640	<code class="computeroutput">false</code>. If the associated mutex object is already
641	locked by the same thread the behavior is dependent on the <a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
642	strategy</a> of the associated mutex object.</p>
643	</td>
644	</tr></tbody>
645	</table>
646	</div>
647	</div>
648	<div class="section" lang="en">
649	<div class="titlepage"><div><div><h5 class="title">
650	<a name="thread.concepts.ScopedTimedLock"></a>ScopedTimedLock Concept</h5></div></div></div>
651	<p>A ScopedTimedLock is a refinement of <a href="concepts.html#thread.concepts.TimedLock" title="TimedLock Concept">TimedLock</a>.
652	For a ScopedTimedLock type <code class="computeroutput">L</code>
653	and an object <code class="computeroutput">lk</code> of that type,
654	and an object <code class="computeroutput">m</code> of a type meeting the
655	<a href="concepts.html#thread.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> requirements,
656	and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
657	and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../boost/xtime.html" title="Struct xtime">boost::xtime</a></code>,
658	the following expressions must be well-formed
659	and have the indicated effects.</p>
660	<div class="table">
661	<a name="id1730399"></a><p class="title"><b>Table 15.10. ScopedTimedLock Expressions</b></p>
662	<table class="table" summary="ScopedTimedLock Expressions">
663	<colgroup>
664	<col>
665	<col>
666	</colgroup>
667	<thead><tr>
668	<th>Expression</th>
669	<th>Effects</th>
670	</tr></thead>
671	<tbody>
672	<tr>
673	<td><code class="computeroutput">L lk(m,t);</code></td>
674	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
675	object <code class="computeroutput">m</code> with it, then calls
676	<code class="computeroutput">timed_lock(t)</code>
677	</td>
678	</tr>
679	<tr>
680	<td><code class="computeroutput">L lk(m,b);</code></td>
681	<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
682	object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
683	<code class="computeroutput">lock()</code>
684	</td>
685	</tr>
686	</tbody>
687	</table>
688	</div>
689	</div>
690	</div>
691	<div class="section" lang="en">
692	<div class="titlepage"><div><div><h4 class="title">
693	<a name="thread.concepts.lock-models"></a>Lock Models</h4></div></div></div>
694	<p><span class="bold"><strong>Boost.Thread</strong></span> currently supplies twelve models of
695	<a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a>
696	and its refinements.</p>
697	<div class="table">
698	<a name="id1730522"></a><p class="title"><b>Table 15.11. Lock Models</b></p>
699	<table class="table" summary="Lock Models">
700	<colgroup>
701	<col>
702	<col>
703	<col>
704	</colgroup>
705	<thead><tr>
706	<th>Concept</th>
707	<th>Refines</th>
708	<th>Models</th>
709	</tr></thead>
710	<tbody>
711	<tr>
712	<td><a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a></td>
713	<td> </td>
714	<td> </td>
715	</tr>
716	<tr>
717	<td><a href="concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a></td>
718	<td><a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a></td>
719	<td>
720	<p><code class="computeroutput">boost::mutex::scoped_lock</code></p>
721	<p><code class="computeroutput">boost::recursive_mutex::scoped_lock</code></p>
722
723	<p><code class="computeroutput">boost::try_mutex::scoped_lock</code></p>
724	<p><code class="computeroutput">boost::recursive_try_mutex::scoped_lock</code></p>
725
726	<p><code class="computeroutput">boost::timed_mutex::scoped_lock</code></p>
727	<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_lock</code></p>
728	</td>
729	</tr>
730	<tr>
731	<td><a href="concepts.html#thread.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
732	<td><a href="concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a></td>
733	<td> </td>
734	</tr>
735	<tr>
736	<td><a href="concepts.html#thread.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a></td>
737	<td><a href="concepts.html#thread.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
738	<td>
739	<p><code class="computeroutput">boost::try_mutex::scoped_try_lock</code></p>
740	<p><code class="computeroutput">boost::recursive_try_mutex::scoped_try_lock</code></p>
741
742	<p><code class="computeroutput">boost::timed_mutex::scoped_try_lock</code></p>
743	<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_try_lock</code></p>
744	</td>
745	</tr>
746	<tr>
747	<td><a href="concepts.html#thread.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td>
748	<td><a href="concepts.html#thread.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
749	<td> </td>
750	</tr>
751	<tr>
752	<td><a href="concepts.html#thread.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a></td>
753	<td><a href="concepts.html#thread.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td>
754	<td>
755	<p><code class="computeroutput">boost::timed_mutex::scoped_timed_lock</code></p>
756	<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_timed_lock</code></p>
757	</td>
758	</tr>
759	</tbody>
760	</table>
761	</div>
762	</div>
763	</div>
764	<div class="section" lang="en">
765	<div class="titlepage"><div><div><h3 class="title">
766	<a name="thread.concepts.read-write-mutexes"></a>Read/Write Mutexes</h3></div></div></div>
767	<div class="toc"><dl>
768	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies">Locking Strategies</a></span></dt>
769	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-scheduling-policies">Scheduling Policies</a></span></dt>
770	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-mutex-concepts">Mutex Concepts</a></span></dt>
771	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-mutex-models">Mutex Models</a></span></dt>
772	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-lock-concepts">Lock Concepts</a></span></dt>
773	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-lock-models">Lock Models</a></span></dt>
774	</dl></div>
775	<div class="note"><table border="0" summary="Note">
776	<tr>
777	<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
778	<th align="left">Note</th>
779	</tr>
780	<tr><td align="left" valign="top"> Unfortunately it turned out that the current implementation has
781	some serious problems. So it was decided not to put this implementation into
782	release grade code. Also discussions on the mailing list led to the
783	conclusion that the current concepts need to be rethought. In particular
784	the schedulings <a href="concepts.html#thread.concepts.read-write-scheduling-policies.inter-class" title="Inter-Class Scheduling Policies">
785	Inter-Class Scheduling Policies</a> are deemed unnecessary.
786	There seems to be common belief that a fair scheme suffices.
787	The following documentation has been retained however, to give
788	readers of this document the opportunity to study the original design.
789	</td></tr>
790	</table></div>
791	<p>A read/write mutex (short for reader/writer mutual-exclusion) object
792	is used to serialize access to a resource shared between multiple
793	threads, where multiple "readers" can share simultaneous access, but
794	"writers" require exclusive access. The
795	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> concept, with
796	<a href="concepts.html#thread.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a> and
797	<a href="concepts.html#thread.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept"> TimedReadWriteMutex</a>
798	refinements formalize the requirements. A model that implements
799	ReadWriteMutex and its refinements has three states:
800	<span class="bold"><strong>read-locked</strong></span>,
801	<span class="bold"><strong>write-locked</strong></span>, and
802	<span class="bold"><strong>unlocked</strong></span>.
803	Before reading from a shared resource, a thread
804	<span class="bold"><strong>read-locks</strong></span>
805	a <span class="bold"><strong>Boost.Thread</strong></span> read/write mutex object
806	(an object whose type is a model of
807	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>
808	or one of it's refinements), ensuring
809	<a href="../thread.html#thread.glossary.thread-safe">thread-safe</a>
810	access for reading from the shared resource. Before writing
811	to a shared resource, a thread
812	<span class="bold"><strong>write-locks</strong></span> a <span class="bold"><strong>Boost.Thread</strong></span>
813	read/write mutex object
814	(an object whose type is a model of
815	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>
816	or one of it's refinements), ensuring
817	<a href="../thread.html#thread.glossary.thread-safe">thread-safe</a>
818	access for altering the shared resource. When use of the shared
819	resource is complete, the thread unlocks the mutex object,
820	allowing another thread to acquire the lock and use the shared
821	resource.</p>
822	<p>Traditional C thread APIs that provide read/write mutex
823	primitives (like POSIX threads) expose functions to lock and unlock a
824	mutex object. This is dangerous since it's easy to forget to unlock a
825	locked mutex. When the flow of control is complex, with multiple
826	return points, the likelihood of forgetting to unlock a mutex object
827	becomes even greater. When exceptions are thrown, it becomes nearly
828	impossible to ensure that the mutex object is unlocked
829	properly when using these traditional API's. The result is
830	<a href="../thread.html#thread.glossary.deadlock">deadlock</a>.</p>
831	<p>Many C++ threading libraries use a pattern known as <span class="emphasis"><em>Scoped
832	Locking</em></span> [<span class="citation"><a href="../thread.html#thread.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] to free the
833	programmer from the need to explicitly lock and unlock
834	read/write mutex objects. With this pattern, a
835	<a href="concepts.html#thread.concepts.read-write-lock-concepts" title="Lock Concepts">Read/Write Lock</a>
836	concept is employed where the lock object's constructor locks
837	the associated read/write mutex object
838	and the destructor automatically does the unlocking. The
839	<span class="bold"><strong>Boost.Thread</strong></span> library takes this pattern to
840	the extreme in that
841	<a href="concepts.html#thread.concepts.read-write-lock-concepts" title="Lock Concepts">Read/Write Lock</a>
842	concepts are the only way to lock and unlock a read/write mutex
843	object: lock and unlock functions are not exposed by any
844	<span class="bold"><strong>Boost.Thread</strong></span> read/write mutex objects. This helps to
845	ensure safe usage patterns, especially when code throws exceptions.</p>
846	<div class="section" lang="en">
847	<div class="titlepage"><div><div><h4 class="title">
848	<a name="thread.concepts.read-write-locking-strategies"></a>Locking Strategies</h4></div></div></div>
849	<div class="toc"><dl>
850	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.recursive">Recursive Locking Strategy</a></span></dt>
851	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.checked">Checked Locking Strategy</a></span></dt>
852	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.unchecked">Unchecked Locking Strategy</a></span></dt>
853	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.unspecified">Unspecified Locking Strategy</a></span></dt>
854	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.thread-identification">Thread Identification</a></span></dt>
855	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.promotion">Lock Promotion</a></span></dt>
856	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-locking-strategies.demotion">Lock Demotion</a></span></dt>
857	</dl></div>
858	<p>Every read/write mutex object follows one of several locking
859	strategies. These strategies define the semantics for the locking
860	operation when the calling thread already owns a lock on the
861	read/write mutex object.</p>
862	<div class="section" lang="en">
863	<div class="titlepage"><div><div><h5 class="title">
864	<a name="thread.concepts.read-write-locking-strategies.recursive"></a>Recursive Locking Strategy</h5></div></div></div>
865	<p>With a recursive locking strategy, when a thread attempts
866	to acquire a lock on a read/write mutex object
867	for which it already owns a lock, the operation is successful,
868	except in the case where a thread holding a read-lock
869	attempts to obtain a write lock, in which case a
870	<code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code> exception will
871	be thrown. Note the distinction between a thread, which may have
872	multiple locks outstanding on a recursive read/write mutex object,
873	and a lock object, which even for a recursive read/write mutex
874	object cannot have any of its lock functions called multiple
875	times without first calling unlock.</p>
876	<div class="informaltable"><table class="table">
877	<colgroup>
878	<col>
879	<col>
880	<col>
881	</colgroup>
882	<thead><tr>
883	<th>Lock Type Held</th>
884	<th>Lock Type Requested</th>
885	<th>Action</th>
886	</tr></thead>
887	<tbody>
888	<tr>
889	<td>read-lock</td>
890	<td>read-lock</td>
891	<td>Grant the read-lock immediately</td>
892	</tr>
893	<tr>
894	<td>read-lock</td>
895	<td>write-lock</td>
896	<td>If this thread is the only holder of the read-lock,
897	grants the write lock immediately. Otherwise throws a
898	<code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code> exception.</td>
899	</tr>
900	<tr>
901	<td>write-locked</td>
902	<td>read-lock</td>
903	<td>Grants the (additional) read-lock immediately.</td>
904	</tr>
905	<tr>
906	<td>write-locked</td>
907	<td>write-lock</td>
908	<td> Grant the write-lock immediately</td>
909	</tr>
910	</tbody>
911	</table></div>
912	<p>Internally a lock count is maintained and the owning
913	thread must unlock the mutex object the same number of times
914	that it locked it before the mutex object's state returns
915	to unlocked. Since mutex objects in <span class="bold"><strong>Boost.Thread</strong></span> expose
916	locking functionality only through lock concepts, a thread
917	will always unlock a mutex object the same number of times
918	that it locked it. This helps to eliminate a whole set of
919	errors typically found in traditional C style thread APIs.
920	</p>
921	<p><span class="bold"><strong>Boost.Thread</strong></span> does not currently provide any read/write mutex objects
922	that use this strategy. A successful implementation of this locking strategy
923	may require
924	<a href="concepts.html#thread.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>.
925	</p>
926	</div>
927	<div class="section" lang="en">
928	<div class="titlepage"><div><div><h5 class="title">
929	<a name="thread.concepts.read-write-locking-strategies.checked"></a>Checked Locking Strategy</h5></div></div></div>
930	<p>With a checked locking strategy, when a thread attempts
931	to acquire a lock on the mutex object for which the thread
932	already owns a lock, the operation will fail with some sort of
933	error indication, except in the case of multiple read-lock
934	acquisition which is a normal operation for ANY ReadWriteMutex.
935	Further, attempts by a thread to unlock a mutex that was not
936	locked by the thread will also return some sort of error
937	indication. In <span class="bold"><strong>Boost.Thread</strong></span>, an exception of type
938	<code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code> would be thrown in
939	these cases.</p>
940	<div class="informaltable"><table class="table">
941	<colgroup>
942	<col>
943	<col>
944	<col>
945	</colgroup>
946	<thead><tr>
947	<th>Lock Type Held</th>
948	<th>Lock Type Requested</th>
949	<th>Action</th>
950	</tr></thead>
951	<tbody>
952	<tr>
953	<td>read-lock</td>
954	<td>read-lock</td>
955	<td>Grant the read-lock immediately</td>
956	</tr>
957	<tr>
958	<td>read-lock</td>
959	<td>write-lock</td>
960	<td>Throw <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
961	</td>
962	</tr>
963	<tr>
964	<td>write-locked</td>
965	<td>read-lock</td>
966	<td>Throw <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
967	</td>
968	</tr>
969	<tr>
970	<td>write-locked</td>
971	<td>write-lock</td>
972	<td> Throw <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
973	</td>
974	</tr>
975	</tbody>
976	</table></div>
977	<p><span class="bold"><strong>Boost.Thread</strong></span> does not currently provide any read/write mutex objects
978	that use this strategy. A successful implementation of this locking strategy
979	may require
980	<a href="concepts.html#thread.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>.
981	</p>
982	</div>
983	<div class="section" lang="en">
984	<div class="titlepage"><div><div><h5 class="title">
985	<a name="thread.concepts.read-write-locking-strategies.unchecked"></a>Unchecked Locking Strategy</h5></div></div></div>
986	<p>With an unchecked locking strategy, when a thread
987	attempts to acquire a lock on the read/write mutex object
988	for which the thread already owns a lock, the operation
989	will <a href="../thread.html#thread.glossary.deadlock">deadlock</a>.
990	In general this locking strategy is less safe than a checked
991	or recursive strategy, but it can be a faster strategy and so
992	is employed by many libraries.</p>
993	<div class="informaltable"><table class="table">
994	<colgroup>
995	<col>
996	<col>
997	<col>
998	</colgroup>
999	<thead><tr>
1000	<th>Lock Type Held</th>
1001	<th>Lock Type Requested</th>
1002	<th>Action</th>
1003	</tr></thead>
1004	<tbody>
1005	<tr>
1006	<td>read-lock</td>
1007	<td>read-lock</td>
1008	<td>Grant the read-lock immediately</td>
1009	</tr>
1010	<tr>
1011	<td>read-lock</td>
1012	<td>write-lock</td>
1013	<td><a href="../thread.html#thread.glossary.deadlock">Deadlock</a></td>
1014	</tr>
1015	<tr>
1016	<td>write-locked</td>
1017	<td>read-lock</td>
1018	<td><a href="../thread.html#thread.glossary.deadlock">Deadlock</a></td>
1019	</tr>
1020	<tr>
1021	<td>write-locked</td>
1022	<td>write-lock</td>
1023	<td><a href="../thread.html#thread.glossary.deadlock">Deadlock</a></td>
1024	</tr>
1025	</tbody>
1026	</table></div>
1027	<p><span class="bold"><strong>Boost.Thread</strong></span> does not currently provide any mutex
1028	objects that use this strategy. For ReadWriteMutexes on
1029	platforms that contain natively recursive synchronization
1030	primitives, implementing a guaranteed-deadlock can actually
1031	involve extra work, and would likely require
1032	<a href="concepts.html#thread.concepts.read-write-locking-strategies.thread-identification" title="Thread Identification">thread identification</a>.
1033	</p>
1034	</div>
1035	<div class="section" lang="en">
1036	<div class="titlepage"><div><div><h5 class="title">
1037	<a name="thread.concepts.read-write-locking-strategies.unspecified"></a>Unspecified Locking Strategy</h5></div></div></div>
1038	<p>With an unspecified locking strategy, when a thread
1039	attempts to acquire a lock on a read/write mutex object for
1040	which the thread already owns a lock, the operation results
1041	in <a href="../thread.html#thread.glossary.undefined-behavior">undefined behavior</a>.
1042	When a read/write mutex object has an unspecified locking
1043	strategy the programmer must assume that the read/write mutex
1044	object instead uses an unchecked strategy as the worse case,
1045	although some platforms may exhibit a mix of unchecked and
1046	recursive behavior.</p>
1047	<div class="informaltable"><table class="table">
1048	<colgroup>
1049	<col>
1050	<col>
1051	<col>
1052	</colgroup>
1053	<thead><tr>
1054	<th>Lock Type Held</th>
1055	<th>Lock Type Requested</th>
1056	<th>Action</th>
1057	</tr></thead>
1058	<tbody>
1059	<tr>
1060	<td>read-lock</td>
1061	<td>read-lock</td>
1062	<td>Grant the read-lock immediately</td>
1063	</tr>
1064	<tr>
1065	<td>read-lock</td>
1066	<td>write-lock</td>
1067	<td>
1068	<a href="../thread.html#thread.glossary.undefined-behavior">Undefined</a>, but generally <a href="../thread.html#thread.glossary.deadlock">deadlock</a>
1069	</td>
1070	</tr>
1071	<tr>
1072	<td>write-locked</td>
1073	<td>read-lock</td>
1074	<td>
1075	<a href="../thread.html#thread.glossary.undefined-behavior">Undefined</a>, but generally <a href="../thread.html#thread.glossary.deadlock">deadlock</a>
1076	</td>
1077	</tr>
1078	<tr>
1079	<td>write-locked</td>
1080	<td>write-lock</td>
1081	<td>
1082	<a href="../thread.html#thread.glossary.undefined-behavior">Undefined</a>, but generally <a href="../thread.html#thread.glossary.deadlock">deadlock</a>
1083	</td>
1084	</tr>
1085	</tbody>
1086	</table></div>
1087	<p>In general a read/write mutex object with an unspecified
1088	locking strategy is unsafe, and it requires programmer discipline
1089	to use the read/write mutex object properly. However, this strategy
1090	allows an implementation to be as fast as possible with no restrictions
1091	on its implementation. This is especially true for portable implementations
1092	that wrap the native threading support of a platform. For this reason, the
1093	classes
1094	<code class="computeroutput">read_write_mutex</code>,
1095	<code class="computeroutput">try_read_write_mutex</code>, and
1096	<code class="computeroutput">timed_read_write_mutex</code>
1097	use this locking strategy despite the lack of safety.</p>
1098	</div>
1099	<div class="section" lang="en">
1100	<div class="titlepage"><div><div><h5 class="title">
1101	<a name="thread.concepts.read-write-locking-strategies.thread-identification"></a>Thread Identification</h5></div></div></div>
1102	<p>ReadWriteMutexes can support specific Locking Strategies
1103	(recursive and checked) which help to detect and protect against
1104	self-deadlock. Self-deadlock can occur when a holder of a locked
1105	ReadWriteMutex attempts to obtain another lock. Given an
1106	implemention <span class="emphasis"><em>I</em></span> which is susceptible to
1107	self-deadlock but otherwise correct and efficient, a recursive or
1108	checked implementation <span class="emphasis"><em>Ir</em></span> or
1109	<span class="emphasis"><em>Ic</em></span> can use the same basic implementation,
1110	but make special checks against self-deadlock by tracking the
1111	identities of thread(s) currently holding locks. This approach
1112	makes deadlock detection othrogonal to the basic ReadWriteMutex
1113	implementaion.</p>
1114	<p>Alternatively, a different basic implementation for
1115	ReadWriteMutex concepts,
1116	<span class="emphasis"><em>I'</em></span> (I-Prime) may exist which uses recursive
1117	or checked versions of synchronization primitives to produce
1118	a recursive or checked ReadWriteMutex while still providing
1119	flexibility in terms of Scheduling Policies. </p>
1120	<p>Please refer to the <span class="bold"><strong>Boost.Thread</strong></span>
1121	<a href="concepts.html#thread.concepts.read-write-mutex-concepts" title="Mutex Concepts">read/write mutex concept</a>
1122	documentation for a discussion of locking strategies.
1123	The read/write mutex supports only the
1124	<a href="concepts.html#thread.concepts.read-write-locking-strategies.unspecified" title="Unspecified Locking Strategy">unspecified</a>
1125	locking strategy. ReadWriteMutexes are parameterized on a
1126	Mutex type which they use to control write-locking
1127	and access to internal state.</p>
1128	</div>
1129	<div class="section" lang="en">
1130	<div class="titlepage"><div><div><h5 class="title">
1131	<a name="thread.concepts.read-write-locking-strategies.promotion"></a>Lock Promotion</h5></div></div></div>
1132	<p>ReadWriteMutexes can support lock promotion, where a
1133	mutex which is in the read-locked state transitions to a
1134	write-locked state without releasing the lock. Lock
1135	promotion can be tricky to implement; for instance,
1136	extra care must be taken to ensure that only one thread holding a
1137	read-lock can block awaiting promotion at any given time. If
1138	more than one read-lock holder is allowed to enter a blocked
1139	state while waiting to be promoted, deadlock will result since
1140	both threads will be waiting for the other to release their read-lock.
1141	</p>
1142	<p>Currently, <span class="bold"><strong>Boost.Thread</strong></span> supports lock promotion
1143	through <code class="computeroutput">promote()</code>, <code class="computeroutput">try_promote()</code>,
1144	and <code class="computeroutput">timed_promote()</code> operations.</p>
1145	</div>
1146	<div class="section" lang="en">
1147	<div class="titlepage"><div><div><h5 class="title">
1148	<a name="thread.concepts.read-write-locking-strategies.demotion"></a>Lock Demotion</h5></div></div></div>
1149	<p>ReadWriteMutexes can support lock demotion, where a
1150	mutex which is in the write-locked state transitions to a
1151	read-locked state without releasing the lock.
1152	Since by definition only one thread at a time may hold
1153	a write-lock, the problem with deadlock that can occur
1154	during lock promotion is not a problem for lock
1155	demotion.</p>
1156	<p>Currently, <span class="bold"><strong>Boost.Thread</strong></span> supports lock demotion
1157	through <code class="computeroutput">demote()</code>, <code class="computeroutput">try_demote()</code>,
1158	and <code class="computeroutput">timed_demote()</code> operations.</p>
1159	</div>
1160	</div>
1161	<div class="section" lang="en">
1162	<div class="titlepage"><div><div><h4 class="title">
1163	<a name="thread.concepts.read-write-scheduling-policies"></a>Scheduling Policies</h4></div></div></div>
1164	<div class="toc"><dl>
1165	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-scheduling-policies.inter-class">Inter-Class Scheduling Policies</a></span></dt>
1166	<dt><span class="section"><a href="concepts.html#thread.concepts.read-write-scheduling-policies.intra-class">Intra-Class Scheduling Policies</a></span></dt>
1167	</dl></div>
1168	<p>Every read/write mutex object follows one of several scheduling
1169	policies. These policies define the semantics when the mutex object
1170	is unlocked and there is more than one thread waiting to acquire a
1171	lock. In other words, the policy defines which waiting thread shall
1172	acquire the lock. For a read/write mutex, it is particularly important
1173	to define the behavior when threads are requesting both read and
1174	write access simultaneously. This will be referred to as "inter-class
1175	scheduling" because it describes the scheduling between two
1176	classes of threads (those waiting for a read lock and those
1177	waiting for a write lock).</p>
1178	<p>For some types of inter-class scheduling, an "intra-class"
1179	scheduling policy can also be defined that will describe the order
1180	in which waiting threads of the same class (i.e., those
1181	waiting for the same type of lock) will acquire the thread.
1182	</p>
1183	<div class="section" lang="en">
1184	<div class="titlepage"><div><div><h5 class="title">
1185	<a name="thread.concepts.read-write-scheduling-policies.inter-class"></a>Inter-Class Scheduling Policies</h5></div></div></div>
1186	<div class="section" lang="en">
1187	<div class="titlepage"><div><div><h6 class="title">
1188	<a name="thread.concepts.read-write-scheduling-policies.reader-priority"></a>ReaderPriority</h6></div></div></div>
1189	<p>With ReaderPriority scheduling, any pending request for
1190	a read-lock will have priority over a pending request for a
1191	write-lock, irrespective of the current lock state of the
1192	read/write mutex, and irrespective of the relative order
1193	that the pending requests arrive.</p>
1194	<div class="informaltable"><table class="table">
1195	<colgroup>
1196	<col>
1197	<col>
1198	<col>
1199	</colgroup>
1200	<thead><tr>
1201	<th>Current mutex state</th>
1202	<th>Request Type</th>
1203	<th>Action</th>
1204	</tr></thead>
1205	<tbody>
1206	<tr>
1207	<td>unlocked</td>
1208	<td>read-lock</td>
1209	<td>Grant the read-lock immediately</td>
1210	</tr>
1211	<tr>
1212	<td>read-locked</td>
1213	<td>read-lock</td>
1214	<td>Grant the additional read-lock immediately.</td>
1215	</tr>
1216	<tr>
1217	<td>write-locked</td>
1218	<td>read-lock</td>
1219	<td>Wait to acquire the lock until the thread
1220	holding the write-lock releases its lock (or until
1221	the specified time, if any). A
1222	read-lock will be granted to all pending readers
1223	before any other thread can acquire a write-lock.
1224	<p>TODO: try-lock, timed-lock.</p>
1225	</td>
1226	</tr>
1227	<tr>
1228	<td>unlocked</td>
1229	<td>write-lock</td>
1230	<td>Grant the write-lock immediately, if and
1231	only if there are no pending read-lock requests.
1232	<p>TODO: try-lock, timed-lock.</p>
1233	</td>
1234	</tr>
1235	<tr>
1236	<td>read-locked</td>
1237	<td>write-lock</td>
1238	<td> Wait to acquire the lock until all
1239	threads holding read-locks release their locks
1240	<span class="bold"><strong>AND</strong></span> no requests
1241	for read-locks exist. If other write-lock
1242	requests exist, the lock is granted in accordance
1243	with the intra-class scheduling policy.
1244	<p>TODO: try-lock, timed-lock.</p>
1245	</td>
1246	</tr>
1247	<tr>
1248	<td>write-locked</td>
1249	<td>write-lock</td>
1250	<td>Wait to acquire the lock until the thread
1251	holding the write-lock releases its lock
1252	<span class="bold"><strong>AND</strong></span> no requests
1253	for read-locks exist. If other write-lock
1254	requests exist, the lock is granted in accordance
1255	with the intra-class scheduling policy.
1256	<p>TODO: try-lock, timed-lock.</p>
1257	</td>
1258	</tr>
1259	<tr>
1260	<td>read-locked</td>
1261	<td>promote</td>
1262	<td><p>TODO</p></td>
1263	</tr>
1264	<tr>
1265	<td>write-locked</td>
1266	<td>demote</td>
1267	<td><p>TODO</p></td>
1268	</tr>
1269	</tbody>
1270	</table></div>
1271	</div>
1272	<div class="section" lang="en">
1273	<div class="titlepage"><div><div><h6 class="title">
1274	<a name="thread.concepts.read-write-scheduling-policies.writer-priority"></a>WriterPriority</h6></div></div></div>
1275	<p>With WriterPriority scheduling, any pending request
1276	for a write-lock will have priority over a pending request
1277	for a read-lock, irrespective of the current lock state
1278	of the read/write mutex, and irrespective of the relative
1279	order that the pending requests arrive.</p>
1280	<div class="informaltable"><table class="table">
1281	<colgroup>
1282	<col>
1283	<col>
1284	<col>
1285	</colgroup>
1286	<thead><tr>
1287	<th>Current mutex state</th>
1288	<th>Request Type</th>
1289	<th>Action</th>
1290	</tr></thead>
1291	<tbody>
1292	<tr>
1293	<td>unlocked</td>
1294	<td>read-lock</td>
1295	<td>Grant the read-lock immediately.</td>
1296	</tr>
1297	<tr>
1298	<td>read-locked</td>
1299	<td>read-lock</td>
1300	<td>Grant the additional read-lock immediately,
1301	<span class="bold"><strong>IF</strong></span> no outstanding
1302	requests for a write-lock exist; otherwise TODO.
1303	<p>TODO: try-lock, timed-lock.</p>
1304	</td>
1305	</tr>
1306	<tr>
1307	<td>write-locked</td>
1308	<td>read-lock</td>
1309	<td> Wait to acquire the lock until the
1310	thread holding the write-lock
1311	releases its lock. The read lock will be granted
1312	once no other outstanding write-lock requests
1313	exist.
1314	<p>TODO: try-lock, timed-lock.</p>
1315	</td>
1316	</tr>
1317	<tr>
1318	<td>unlocked</td>
1319	<td>write-lock</td>
1320	<td>Grant the write-lock immediately.</td>
1321	</tr>
1322	<tr>
1323	<td>read-locked</td>
1324	<td>write-lock</td>
1325	<td>Wait to acquire the lock until all
1326	threads holding read-locks release their locks.
1327	If other write-lock requests exist, the lock
1328	is granted in accordance with the intra-class
1329	scheduling policy. This request will be granted
1330	before any new read-lock requests are granted.
1331	<p>TODO: try-lock, timed-lock.</p>
1332	</td>
1333	</tr>
1334	<tr>
1335	<td>write-locked</td>
1336	<td>write-lock</td>
1337	<td>Wait to acquire the lock until the thread
1338	holding the write-lock releases its lock. If
1339	other write-lock requests exist, the lock is
1340	granted in accordance with the intra-class
1341	scheduling policy. This request will be granted
1342	before any new read-lock requests are granted.
1343	<p>TODO: try-lock, timed-lock.</p>
1344	</td>
1345	</tr>
1346	<tr>
1347	<td>read-locked</td>
1348	<td>promote</td>
1349	<td><p>TODO</p></td>
1350	</tr>
1351	<tr>
1352	<td>write-locked</td>
1353	<td>demote</td>
1354	<td><p>TODO</p></td>
1355	</tr>
1356	</tbody>
1357	</table></div>
1358	</div>
1359	<div class="section" lang="en">
1360	<div class="titlepage"><div><div><h6 class="title">
1361	<a name="thread.concepts.read-write-scheduling-policies.alternating-many-reads"></a>AlternatingPriority/ManyReads</h6></div></div></div>
1362	<p>With AlternatingPriority/ManyReads scheduling, reader
1363	or writer starvation is avoided by alternatively granting read
1364	or write access when pending requests exist for both types of
1365	locks. Outstanding read-lock requests are treated as a group
1366	when it is the "readers' turn"</p>
1367	<div class="informaltable"><table class="table">
1368	<colgroup>
1369	<col>
1370	<col>
1371	<col>
1372	</colgroup>
1373	<thead><tr>
1374	<th>Current mutex state</th>
1375	<th>Request Type</th>
1376	<th>Action</th>
1377	</tr></thead>
1378	<tbody>
1379	<tr>
1380	<td>unlocked</td>
1381	<td>read-lock</td>
1382	<td>Grant the read-lock immediately.</td>
1383	</tr>
1384	<tr>
1385	<td>read-locked</td>
1386	<td>read-lock</td>
1387	<td>Grant the additional read-lock immediately,
1388	<span class="bold"><strong>IF</strong></span> no outstanding
1389	requests for a write-lock exist. If outstanding
1390	write-lock requests exist, this lock will not
1391	be granted until at least one of the
1392	write-locks is granted and released. If other
1393	read-lock requests exist, all read-locks will be
1394	granted as a group.
1395	<p>TODO: try-lock, timed-lock.</p>
1396	</td>
1397	</tr>
1398	<tr>
1399	<td>write-locked</td>
1400	<td>read-lock</td>
1401	<td> Wait to acquire the lock until the thread
1402	holding the write-lock releases its lock. If other
1403	outstanding write-lock requests exist, they will
1404	have to wait until all current read-lock requests
1405	are serviced.
1406	<p>TODO: try-lock, timed-lock.</p>
1407	</td>
1408	</tr>
1409	<tr>
1410	<td>unlocked</td>
1411	<td>write-lock</td>
1412	<td>Grant the write-lock immediately.</td>
1413	</tr>
1414	<tr>
1415	<td>read-locked</td>
1416	<td>write-lock</td>
1417	<td>
1418	<p>Wait to acquire the lock until all threads
1419	holding read-locks release their locks.</p>
1420
1421	<p>If other write-lock requests exist, this
1422	lock will be granted to one of them in accordance
1423	with the intra-class scheduling policy.</p>
1424
1425	<p>TODO: try-lock, timed-lock.</p>
1426	</td>
1427	</tr>
1428	<tr>
1429	<td>write-locked</td>
1430	<td>write-lock</td>
1431	<td>Wait to acquire the lock until the thread
1432	holding the write-lock releases its lock. If
1433	other outstanding read-lock requests exist, this
1434	lock will not be granted until all of the
1435	currently waiting read-locks are granted and
1436	released. If other write-lock requests exist,
1437	this lock will be granted in accordance with the
1438	intra-class scheduling policy.
1439	<p>TODO: try-lock, timed-lock.</p>
1440	</td>
1441	</tr>
1442	<tr>
1443	<td>read-locked</td>
1444	<td>promote</td>
1445	<td><p>TODO</p></td>
1446	</tr>
1447	<tr>
1448	<td>write-locked</td>
1449	<td>demote</td>
1450	<td><p>TODO</p></td>
1451	</tr>
1452	</tbody>
1453	</table></div>
1454	</div>
1455	<div class="section" lang="en">
1456	<div class="titlepage"><div><div><h6 class="title">
1457	<a name="thread.concepts.read-write-scheduling-policies.alternating-single-read"></a>AlternatingPriority/SingleRead</h6></div></div></div>
1458	<p>With AlternatingPriority/SingleRead scheduling, reader
1459	or writer starvation is avoided by alternatively granting read
1460	or write access when pending requests exist for both types of
1461	locks. Outstanding read-lock requests are services one at a
1462	time when it is the "readers' turn"</p>
1463	<div class="informaltable"><table class="table">
1464	<colgroup>
1465	<col>
1466	<col>
1467	<col>
1468	</colgroup>
1469	<thead><tr>
1470	<th>Current mutex state</th>
1471	<th>Request Type</th>
1472	<th>Action</th>
1473	</tr></thead>
1474	<tbody>
1475	<tr>
1476	<td>unlocked</td>
1477	<td>read-lock</td>
1478	<td>Grant the read-lock immediately.</td>
1479	</tr>
1480	<tr>
1481	<td>read-locked</td>
1482	<td>read-lock</td>
1483	<td>Grant the additional read-lock immediately,
1484	<span class="bold"><strong>IF</strong></span> no outstanding
1485	requests for a write-lock exist. If outstanding
1486	write-lock requests exist, this lock will not
1487	be granted until at least one of the write-locks
1488	is granted and released.
1489	<p>TODO: try-lock, timed-lock.</p>
1490	</td>
1491	</tr>
1492	<tr>
1493	<td>write-locked</td>
1494	<td>read-lock</td>
1495	<td>
1496	<p>Wait to acquire the lock until the thread
1497	holding the write-lock releases its lock.</p>
1498	<p>If other outstanding write-lock requests
1499	exist, exactly one read-lock request will be
1500	granted before the next write-lock is granted.
1501	</p>
1502	<p>TODO: try-lock, timed-lock.</p>
1503	</td>
1504	</tr>
1505	<tr>
1506	<td>unlocked</td>
1507	<td>write-lock</td>
1508	<td>Grant the write-lock immediately.</td>
1509	</tr>
1510	<tr>
1511	<td>read-locked</td>
1512	<td>write-lock</td>
1513	<td>
1514	<p>Wait to acquire the lock until all
1515	threads holding read-locks release their
1516	locks.</p>
1517
1518	<p>If other write-lock requests exist,
1519	this lock will be granted to one of them
1520	in accordance with the intra-class
1521	scheduling policy.</p>
1522	</td>
1523	</tr>
1524	<tr>
1525	<td>write-locked</td>
1526	<td>write-lock</td>
1527	<td>Wait to acquire the lock until the
1528	thread holding the write-lock releases its
1529	lock. If other outstanding read-lock requests
1530	exist, this lock can not be granted until
1531	exactly one read-lock request is granted and
1532	released. If other write-lock requests exist,
1533	this lock will be granted in accordance with
1534	the intra-class scheduling policy.
1535	<p>TODO: try-lock, timed-lock.</p>
1536	</td>
1537	</tr>
1538	<tr>
1539	<td>read-locked</td>
1540	<td>promote</td>
1541	<td><p>TODO</p></td>
1542	</tr>
1543	<tr>
1544	<td>write-locked</td>
1545	<td>demote</td>
1546	<td><p>TODO</p></td>
1547	</tr>
1548	</tbody>
1549	</table></div>
1550	</div>
1551	</div>
1552	<div class="section" lang="en">
1553	<div class="titlepage"><div><div><h5 class="title">
1554	<a name="thread.concepts.read-write-scheduling-policies.intra-class"></a>Intra-Class Scheduling Policies</h5></div></div></div>
1555	<p>Please refer to
1556	<a href="concepts.html#thread.concepts.sheduling-policies" title="Scheduling Policies">the section called “Scheduling Policies”</a>
1557	for a discussion of mutex scheduling policies, which are identical to
1558	read/write mutex intra-class scheduling policies.</p>
1559	<p>For threads waiting to obtain write-locks, the read/write mutex
1560	supports only the
1561	<a href="concepts.html#thread.concepts.unspecified-scheduling-policy" title="Unspecified Policy">Unspecified</a>
1562	intra-class scheduling policy. That is, given a set of threads
1563	waiting for write-locks, the order, relative to one another, in
1564	which they receive the write-lock is unspecified.</p>
1565	<p>For threads waiting to obtain read-locks, the read/write mutex
1566	supports only the
1567	<a href="concepts.html#thread.concepts.unspecified-scheduling-policy" title="Unspecified Policy">Unspecified</a>
1568	intra-class scheduling policy. That is, given a set of threads
1569	waiting for read-locks, the order, relative to one another, in
1570	which they receive the read-lock is unspecified.</p>
1571	</div>
1572	</div>
1573	<div class="section" lang="en">
1574	<div class="titlepage"><div><div><h4 class="title">
1575	<a name="thread.concepts.read-write-mutex-concepts"></a>Mutex Concepts</h4></div></div></div>
1576	<div class="toc"><dl>
1577	<dt><span class="section"><a href="concepts.html#thread.concepts.ReadWriteMutex">ReadWriteMutex Concept</a></span></dt>
1578	<dt><span class="section"><a href="concepts.html#thread.concepts.TryReadWriteMutex">TryReadWriteMutex Concept</a></span></dt>
1579	<dt><span class="section"><a href="concepts.html#thread.concepts.TimedReadWriteMutex">TimedReadWriteMutex Concept</a></span></dt>
1580	</dl></div>
1581	<div class="section" lang="en">
1582	<div class="titlepage"><div><div><h5 class="title">
1583	<a name="thread.concepts.ReadWriteMutex"></a>ReadWriteMutex Concept</h5></div></div></div>
1584	<p>A ReadWriteMutex object has three states: read-locked,
1585	write-locked, and unlocked. ReadWriteMutex object state can
1586	only be determined by a lock object meeting the appropriate lock concept
1587	requirements and constructed for the ReadWriteMutex object.</p>
1588	<p>A ReadWriteMutex is
1589	<a href="../../../libs/utility/utility.htm#Class%20noncopyable" target="_top">NonCopyable</a>.
1590	</p>
1591	<p>For a ReadWriteMutex type <code class="computeroutput">M</code>,
1592	and an object <code class="computeroutput">m</code> of that type,
1593	the following expressions must be well-formed
1594	and have the indicated effects.</p>
1595	<div class="table">
1596	<a name="id1732828"></a><p class="title"><b>Table 15.12. ReadWriteMutex Expressions</b></p>
1597	<table class="table" summary="ReadWriteMutex Expressions">
1598	<colgroup>
1599	<col>
1600	<col>
1601	</colgroup>
1602	<thead><tr>
1603	<th>Expression</th>
1604	<th>Effects</th>
1605	</tr></thead>
1606	<tbody>
1607	<tr>
1608	<td><code class="computeroutput">M m;</code></td>
1609	<td>Constructs a read/write mutex object <code class="computeroutput">m</code>.
1610	Post-condition: <code class="computeroutput">m</code> is unlocked.</td>
1611	</tr>
1612	<tr>
1613	<td><code class="computeroutput">(&m)->~M();</code></td>
1614	<td>Precondition: <code class="computeroutput">m</code> is unlocked.
1615	Destroys a read/write mutex object <code class="computeroutput">m</code>.
1616	</td>
1617	</tr>
1618	<tr>
1619	<td><code class="computeroutput">M::scoped_read_write_lock</code></td>
1620	<td>A type meeting the
1621	<a href="concepts.html#thread.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a>
1622	requirements. </td>
1623	</tr>
1624	<tr>
1625	<td><code class="computeroutput">M::scoped_read_lock</code></td>
1626	<td>A type meeting the
1627	<a href="concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
1628	requirements. </td>
1629	</tr>
1630	<tr>
1631	<td><code class="computeroutput">M::scoped_write_lock</code></td>
1632	<td>A type meeting the
1633	<a href="concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
1634	requirements. </td>
1635	</tr>
1636	</tbody>
1637	</table>
1638	</div>
1639	</div>
1640	<div class="section" lang="en">
1641	<div class="titlepage"><div><div><h5 class="title">
1642	<a name="thread.concepts.TryReadWriteMutex"></a>TryReadWriteMutex Concept</h5></div></div></div>
1643	<p>A TryReadWriteMutex is a refinement of
1644	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>.
1645	For a TryReadWriteMutex type <code class="computeroutput">M</code>
1646	and an object <code class="computeroutput">m</code> of that type,
1647	the following expressions must be well-formed
1648	and have the indicated effects.</p>
1649	<div class="table">
1650	<a name="id1733010"></a><p class="title"><b>Table 15.13. TryReadWriteMutex Expressions</b></p>
1651	<table class="table" summary="TryReadWriteMutex Expressions">
1652	<colgroup>
1653	<col>
1654	<col>
1655	</colgroup>
1656	<thead><tr>
1657	<th>Expression</th>
1658	<th>Effects</th>
1659	</tr></thead>
1660	<tbody>
1661	<tr>
1662	<td><code class="computeroutput">M::scoped_try_read_write_lock</code></td>
1663	<td>A type meeting the
1664	<a href="concepts.html#thread.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a>
1665	requirements.</td>
1666	</tr>
1667	<tr>
1668	<td><code class="computeroutput">M::scoped_try_read_lock</code></td>
1669	<td>A type meeting the
1670	<a href="concepts.html#thread.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>
1671	requirements.</td>
1672	</tr>
1673	<tr>
1674	<td><code class="computeroutput">M::scoped_try_write_lock</code></td>
1675	<td>A type meeting the
1676	<a href="concepts.html#thread.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>
1677	requirements.</td>
1678	</tr>
1679	</tbody>
1680	</table>
1681	</div>
1682	</div>
1683	<div class="section" lang="en">
1684	<div class="titlepage"><div><div><h5 class="title">
1685	<a name="thread.concepts.TimedReadWriteMutex"></a>TimedReadWriteMutex Concept</h5></div></div></div>
1686	<p>A TimedReadWriteMutex is a refinement of
1687	<a href="concepts.html#thread.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a>.
1688	For a TimedReadWriteMutex type <code class="computeroutput">M</code>
1689	and an object <code class="computeroutput">m</code> of that type
1690	the following expressions must be well-formed
1691	and have the indicated effects.</p>
1692	<div class="table">
1693	<a name="id1733143"></a><p class="title"><b>Table 15.14. TimedReadWriteMutex Expressions</b></p>
1694	<table class="table" summary="TimedReadWriteMutex Expressions">
1695	<colgroup>
1696	<col>
1697	<col>
1698	</colgroup>
1699	<thead><tr>
1700	<th>Expression</th>
1701	<th>Effects</th>
1702	</tr></thead>
1703	<tbody>
1704	<tr>
1705	<td><code class="computeroutput">M::scoped_timed_read_write_lock</code></td>
1706	<td>A type meeting the
1707	<a href="concepts.html#thread.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a>
1708	requirements.</td>
1709	</tr>
1710	<tr>
1711	<td><code class="computeroutput">M::scoped_timed_read_lock</code></td>
1712	<td>A type meeting the
1713	<a href="concepts.html#thread.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
1714	requirements.</td>
1715	</tr>
1716	<tr>
1717	<td><code class="computeroutput">M::scoped_timed_write_lock</code></td>
1718	<td>A type meeting the
1719	<a href="concepts.html#thread.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
1720	requirements.</td>
1721	</tr>
1722	</tbody>
1723	</table>
1724	</div>
1725	</div>
1726	</div>
1727	<div class="section" lang="en">
1728	<div class="titlepage"><div><div><h4 class="title">
1729	<a name="thread.concepts.read-write-mutex-models"></a>Mutex Models</h4></div></div></div>
1730	<p><span class="bold"><strong>Boost.Thread</strong></span> currently supplies three models of
1731	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>
1732	and its refinements.</p>
1733	<div class="table">
1734	<a name="id1733267"></a><p class="title"><b>Table 15.15. Mutex Models</b></p>
1735	<table class="table" summary="Mutex Models">
1736	<colgroup>
1737	<col>
1738	<col>
1739	<col>
1740	</colgroup>
1741	<thead><tr>
1742	<th>Concept</th>
1743	<th>Refines</th>
1744	<th>Models</th>
1745	</tr></thead>
1746	<tbody>
1747	<tr>
1748	<td><a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a></td>
1749	<td> </td>
1750	<td><code class="computeroutput"><a href="../boost/read_write_mutex.html" title="Class read_write_mutex">boost::read_write_mutex</a></code></td>
1751	</tr>
1752	<tr>
1753	<td><a href="concepts.html#thread.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a></td>
1754	<td><a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a></td>
1755	<td><code class="computeroutput"><a href="../boost/try_read_write_mutex.html" title="Class try_read_write_mutex">boost::try_read_write_mutex</a></code></td>
1756	</tr>
1757	<tr>
1758	<td><a href="concepts.html#thread.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept">TimedReadWriteMutex</a></td>
1759	<td><a href="concepts.html#thread.concepts.TryReadWriteMutex" title="TryReadWriteMutex Concept">TryReadWriteMutex</a></td>
1760	<td><code class="computeroutput"><a href="../boost/timed_read_write_mutex.html" title="Class timed_read_write_mutex">boost::timed_read_write_mutex</a></code></td>
1761	</tr>
1762	</tbody>
1763	</table>
1764	</div>
1765	</div>
1766	<div class="section" lang="en">
1767	<div class="titlepage"><div><div><h4 class="title">
1768	<a name="thread.concepts.read-write-lock-concepts"></a>Lock Concepts</h4></div></div></div>
1769	<div class="toc"><dl>
1770	<dt><span class="section"><a href="concepts.html#thread.concepts.ReadWriteLock">ReadWriteLock Concept</a></span></dt>
1771	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedReadWriteLock">ScopedReadWriteLock Concept</a></span></dt>
1772	<dt><span class="section"><a href="concepts.html#thread.concepts.TryReadWriteLock">TryReadWriteLock Expressions</a></span></dt>
1773	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedTryReadWriteLock">ScopedTryReadWriteLock Expressions</a></span></dt>
1774	<dt><span class="section"><a href="concepts.html#thread.concepts.TimedReadWriteLock">TimedReadWriteLock Concept</a></span></dt>
1775	<dt><span class="section"><a href="concepts.html#thread.concepts.ScopedTimedReadWriteLock">ScopedTimedReadWriteLock Concept</a></span></dt>
1776	</dl></div>
1777	<p>A read/write lock object provides a safe means for locking
1778	and unlocking a read/write mutex object (an object whose type is
1779	a model of
1780	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a>
1781	or one of its refinements). In other words they are an
1782	implementation of the <span class="emphasis"><em>Scoped Locking</em></span>
1783	[<span class="citation"><a href="../thread.html#thread.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] pattern. The
1784	<a href="concepts.html#thread.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a>,
1785	<a href="concepts.html#thread.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a>, and
1786	<a href="concepts.html#thread.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a>
1787	concepts formalize the requirements.</p>
1788	<p>Read/write lock objects are constructed with a reference to a
1789	read/write mutex object and typically acquire ownership of the
1790	read/write mutex object by setting its state to locked. They also
1791	ensure ownership is relinquished in the destructor. Lock objects
1792	also expose functions to query the lock status and to manually lock
1793	and unlock the read/write mutex object.</p>
1794	<p>Read/write lock objects are meant to be short lived, expected
1795	to be used at block scope only. The read/write lock objects are not
1796	<a href="../thread.html#thread.glossary.thread-safe">thread-safe</a>.
1797	Read/write lock objects must maintain state to indicate whether or
1798	not they've been locked and this state is not protected by any
1799	synchronization concepts. For this reason a read/write lock object
1800	should never be shared between multiple threads.</p>
1801	<div class="section" lang="en">
1802	<div class="titlepage"><div><div><h5 class="title">
1803	<a name="thread.concepts.ReadWriteLock"></a>ReadWriteLock Concept</h5></div></div></div>
1804	<p>For a read/write lock type <code class="computeroutput">L</code>
1805	and an object <code class="computeroutput">lk</code>
1806	and const object <code class="computeroutput">clk</code> of that type,
1807	the following expressions must be well-formed
1808	and have the indicated effects.</p>
1809	<div class="table">
1810	<a name="id1733520"></a><p class="title"><b>Table 15.16. ReadWriteLock Expressions</b></p>
1811	<table class="table" summary="ReadWriteLock Expressions">
1812	<colgroup>
1813	<col>
1814	<col>
1815	</colgroup>
1816	<thead><tr>
1817	<th>Expression</th>
1818	<th>Effects</th>
1819	</tr></thead>
1820	<tbody>
1821	<tr>
1822	<td><code class="computeroutput">(&lk)->~L();</code></td>
1823	<td><code class="computeroutput">if (locked()) unlock();</code></td>
1824	</tr>
1825	<tr>
1826	<td><code class="computeroutput">(&clk)->operator const void*()</code></td>
1827	<td>Returns type void*, non-zero if the associated read/write
1828	mutex object has been either read-locked or write-locked by
1829	<code class="computeroutput">clk</code>, otherwise 0.</td>
1830	</tr>
1831	<tr>
1832	<td><code class="computeroutput">clk.locked()</code></td>
1833	<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->operator
1834	const void*() != 0</code>
1835	</td>
1836	</tr>
1837	<tr>
1838	<td><code class="computeroutput">clk.state()</code></td>
1839	<td>Returns an enumeration constant of type <code class="computeroutput">read_write_lock_state</code>:
1840	<code class="computeroutput">read_write_lock_state::read_locked</code> if the associated read/write mutex object has been
1841	read-locked by <code class="computeroutput">clk</code>, <code class="computeroutput">read_write_lock_state::write_locked</code> if it
1842	has been write-locked by <code class="computeroutput">clk</code>, and <code class="computeroutput">read_write_lock_state::unlocked</code>
1843	if has not been locked by <code class="computeroutput">clk</code>.</td>
1844	</tr>
1845	<tr>
1846	<td><code class="computeroutput">clk.read_locked()</code></td>
1847	<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->state() == read_write_lock_state::read_locked</code>.</td>
1848	</tr>
1849	<tr>
1850	<td><code class="computeroutput">clk.write_locked()</code></td>
1851	<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&clk)->state() == read_write_lock_state::write_locked</code>.</td>
1852	</tr>
1853	<tr>
1854	<td><code class="computeroutput">lk.read_lock()</code></td>
1855	<td>
1856	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
1857	if <code class="computeroutput">locked()</code>.</p>
1858
1859	<p>If the associated read/write mutex
1860	object is already read-locked by some other
1861	thread, the effect depends on the
1862	<a href="concepts.html#thread.concepts.read-write-scheduling-policies.inter-class" title="Inter-Class Scheduling Policies">inter-class scheduling policy</a>
1863	of the associated read/write mutex:
1864	either immediately obtains an additional
1865	read-lock on the associated read/write
1866	mutex, or places the current thread in the
1867	<a href="../thread.html#thread.glossary.thread-state">Blocked</a>
1868	state until the associated read/write mutex
1869	is unlocked, after which the current thread
1870	is placed in the
1871	<a href="../thread.html#thread.glossary.thread-state">Ready</a>
1872	state, eventually to be returned to the
1873	<a href="../thread.html#thread.glossary.thread-state">Running</a>
1874	state.</p>
1875
1876	<p>If the associated read/write mutex
1877	object is already write-locked by some other
1878	thread, places the current thread in the
1879	<a href="../thread.html#thread.glossary.thread-state">Blocked</a>
1880	state until the associated read/write mutex
1881	is unlocked, after which the current thread
1882	is placed in the
1883	<a href="../thread.html#thread.glossary.thread-state">Ready</a>
1884	state, eventually to be returned to the
1885	<a href="../thread.html#thread.glossary.thread-state">Running</a>
1886	state.</p>
1887
1888	<p>If the associated read/write mutex
1889	object is already locked by the same thread
1890	the behavior is dependent on the
1891	<a href="concepts.html#thread.concepts.read-write-locking-strategies" title="Locking Strategies">locking strategy</a>
1892	of the associated read/write mutex object.
1893	</p>
1894
1895	<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::read_locked</code></p>
1896	</td>
1897	</tr>
1898	<tr>
1899	<td><code class="computeroutput">lk.write_lock()</code></td>
1900	<td>
1901	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
1902	if <code class="computeroutput">locked()</code>.</p>
1903
1904	<p>If the associated read/write mutex
1905	object is already locked by some other
1906	thread, places the current thread in the
1907	<a href="../thread.html#thread.glossary.thread-state">Blocked</a>
1908	state until the associated read/write mutex
1909	is unlocked, after which the current thread
1910	is placed in the
1911	<a href="../thread.html#thread.glossary.thread-state">Ready</a>
1912	state, eventually to be returned to the
1913	<a href="../thread.html#thread.glossary.thread-state">Running</a>
1914	state.</p>
1915
1916	<p>If the associated read/write mutex
1917	object is already locked by the same thread
1918	the behavior is dependent on the
1919	<a href="concepts.html#thread.concepts.read-write-locking-strategies" title="Locking Strategies">locking strategy</a>
1920	of the associated read/write mutex object.
1921	</p>
1922
1923	<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::write_locked</code></p>
1924	</td>
1925	</tr>
1926	<tr>
1927	<td><code class="computeroutput">lk.demote()</code></td>
1928	<td>
1929	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
1930	if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p>
1931
1932	<p>Converts the lock held on the associated read/write mutex
1933	object from a write-lock to a read-lock without releasing
1934	the lock.</p>
1935
1936	<p>Postcondition: <code class="computeroutput">state() == read_write_lock_state::read_locked</code></p>
1937	</td>
1938	</tr>
1939	<tr>
1940	<td><code class="computeroutput">lk.promote()</code></td>
1941	<td>
1942	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
1943	if <code class="computeroutput">state() != read_write_lock_state::read_locked</code>
1944	or if the lock cannot be promoted because another lock
1945	on the same mutex is already waiting to be promoted.</p>
1946
1947	<p>Makes a blocking attempt to convert the lock held on the associated
1948	read/write mutex object from a read-lock to a write-lock without releasing
1949	the lock.</p>
1950	</td>
1951	</tr>
1952	<tr>
1953	<td><code class="computeroutput">lk.unlock()</code></td>
1954	<td>
1955	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
1956	if <code class="computeroutput">!locked()</code>.</p>
1957
1958	<p>Unlocks the associated read/write mutex.</p>
1959
1960	<p>Postcondition: <code class="computeroutput">!locked()</code></p>
1961	</td>
1962	</tr>
1963	</tbody>
1964	</table>
1965	</div>
1966	</div>
1967	<div class="section" lang="en">
1968	<div class="titlepage"><div><div><h5 class="title">
1969	<a name="thread.concepts.ScopedReadWriteLock"></a>ScopedReadWriteLock Concept</h5></div></div></div>
1970	<p>A ScopedReadWriteLock is a refinement of
1971	<a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a>.
1972	For a ScopedReadWriteLock type <code class="computeroutput">L</code>
1973	and an object <code class="computeroutput">lk</code> of that type,
1974	and an object <code class="computeroutput">m</code> of a type meeting the
1975	<a href="concepts.html#thread.concepts.ReadWriteMutex" title="ReadWriteMutex Concept">ReadWriteMutex</a> requirements,
1976	and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>,
1977	the following expressions must be well-formed
1978	and have the indicated effects.</p>
1979	<div class="table">
1980	<a name="id1734142"></a><p class="title"><b>Table 15.17. ScopedReadWriteLock Expressions</b></p>
1981	<table class="table" summary="ScopedReadWriteLock Expressions">
1982	<colgroup>
1983	<col>
1984	<col>
1985	</colgroup>
1986	<thead><tr>
1987	<th>Expression</th>
1988	<th>Effects</th>
1989	</tr></thead>
1990	<tbody><tr>
1991	<td><code class="computeroutput">L lk(m,s);</code></td>
1992	<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex
1993	object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls
1994	<code class="computeroutput">read_lock()</code>; if <code class="computeroutput">s==read_write_lock_state::write_locked</code>,
1995	calls <code class="computeroutput">write_lock()</code>.</td>
1996	</tr></tbody>
1997	</table>
1998	</div>
1999	</div>
2000	<div class="section" lang="en">
2001	<div class="titlepage"><div><div><h5 class="title">
2002	<a name="thread.concepts.TryReadWriteLock"></a>TryReadWriteLock Expressions</h5></div></div></div>
2003	<p>A TryReadWriteLock is a refinement of
2004	<a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a>.
2005	For a TryReadWriteLock type <code class="computeroutput">L</code>
2006	and an object <code class="computeroutput">lk</code> of that type,
2007	the following expressions must be well-formed
2008	and have the indicated effects.</p>
2009	<div class="table">
2010	<a name="id1734257"></a><p class="title"><b>Table 15.18. TryReadWriteLock Expressions</b></p>
2011	<table class="table" summary="TryReadWriteLock Expressions">
2012	<colgroup>
2013	<col>
2014	<col>
2015	</colgroup>
2016	<thead><tr>
2017	<th>Expression</th>
2018	<th>Effects</th>
2019	</tr></thead>
2020	<tbody>
2021	<tr>
2022	<td><code class="computeroutput">lk.try_read_lock()</code></td>
2023	<td>
2024	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2025	if locked().</p>
2026
2027	<p>Makes a non-blocking attempt to read-lock the associated read/write
2028	mutex object, returning <code class="computeroutput">true</code> if the attempt is successful,
2029	otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is
2030	already locked by the same thread the behavior is dependent on the
2031	<a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
2032	strategy</a> of the associated read/write mutex object.</p>
2033	</td>
2034	</tr>
2035	<tr>
2036	<td><code class="computeroutput">lk.try_write_lock()</code></td>
2037	<td>
2038	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2039	if locked().</p>
2040
2041	<p>Makes a non-blocking attempt to write-lock the associated read/write
2042	mutex object, returning <code class="computeroutput">true</code> if the attempt is successful,
2043	otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is
2044	already locked by the same thread the behavior is dependent on the
2045	<a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
2046	strategy</a> of the associated read/write mutex object.</p>
2047	</td>
2048	</tr>
2049	<tr>
2050	<td><code class="computeroutput">lk.try_demote()</code></td>
2051	<td>
2052	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2053	if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p>
2054
2055	<p>Makes a non-blocking attempt to convert the lock held on the associated
2056	read/write mutex object from a write-lock to a read-lock without releasing
2057	the lock, returning <code class="computeroutput">true</code> if the attempt is successful,
2058	otherwise <code class="computeroutput">false</code>.</p>
2059	</td>
2060	</tr>
2061	<tr>
2062	<td><code class="computeroutput">lk.try_promote()</code></td>
2063	<td>
2064	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2065	if <code class="computeroutput">state() != read_write_lock_state::read_locked</code>.</p>
2066
2067	<p>Makes a non-blocking attempt to convert the lock held on the associated
2068	read/write mutex object from a read-lock to a write-lock without releasing
2069	the lock, returning <code class="computeroutput">true</code> if the attempt is successful,
2070	otherwise <code class="computeroutput">false</code>.</p>
2071	</td>
2072	</tr>
2073	</tbody>
2074	</table>
2075	</div>
2076	</div>
2077	<div class="section" lang="en">
2078	<div class="titlepage"><div><div><h5 class="title">
2079	<a name="thread.concepts.ScopedTryReadWriteLock"></a>ScopedTryReadWriteLock Expressions</h5></div></div></div>
2080	<p>A ScopedTryReadWriteLock is a refinement of
2081	<a href="concepts.html#thread.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a>.
2082	For a ScopedTryReadWriteLock type <code class="computeroutput">L</code>
2083	and an object <code class="computeroutput">lk</code> of that type,
2084	and an object <code class="computeroutput">m</code> of a type meeting the
2085	<a href="concepts.html#thread.concepts.TryMutex" title="TryMutex Concept">TryReadWriteMutex</a> requirements,
2086	and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>,
2087	and an object <code class="computeroutput">b</code> of type <code class="computeroutput">blocking_mode</code>,
2088	the following expressions must be well-formed
2089	and have the indicated effects.</p>
2090	<div class="table">
2091	<a name="id1734580"></a><p class="title"><b>Table 15.19. ScopedTryReadWriteLock Expressions</b></p>
2092	<table class="table" summary="ScopedTryReadWriteLock Expressions">
2093	<colgroup>
2094	<col>
2095	<col>
2096	</colgroup>
2097	<thead><tr>
2098	<th>Expression</th>
2099	<th>Effects</th>
2100	</tr></thead>
2101	<tbody><tr>
2102	<td><code class="computeroutput">L lk(m,s,b);</code></td>
2103	<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex
2104	object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls
2105	<code class="computeroutput">read_lock()</code> if <code class="computeroutput">b</code>, otherwise <code class="computeroutput">try_read_lock()</code>;
2106	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>,
2107	otherwise <code class="computeroutput">try_write_lock</code>.</td>
2108	</tr></tbody>
2109	</table>
2110	</div>
2111	</div>
2112	<div class="section" lang="en">
2113	<div class="titlepage"><div><div><h5 class="title">
2114	<a name="thread.concepts.TimedReadWriteLock"></a>TimedReadWriteLock Concept</h5></div></div></div>
2115	<p>A TimedReadWriteLock is a refinement of
2116	<a href="concepts.html#thread.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a>.
2117	For a TimedReadWriteLock type <code class="computeroutput">L</code>
2118	and an object <code class="computeroutput">lk</code> of that type,
2119	and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../boost/xtime.html" title="Struct xtime">boost::xtime</a></code>,
2120	the following expressions must be well-formed
2121	and have the indicated effects.</p>
2122	<div class="table">
2123	<a name="id1734736"></a><p class="title"><b>Table 15.20. TimedReadWriteLock Expressions</b></p>
2124	<table class="table" summary="TimedReadWriteLock Expressions">
2125	<colgroup>
2126	<col>
2127	<col>
2128	</colgroup>
2129	<thead><tr>
2130	<th>Expression</th>
2131	<th>Effects</th>
2132	</tr></thead>
2133	<tbody>
2134	<tr>
2135	<td><code class="computeroutput">lk.timed_read_lock(t)</code></td>
2136	<td>
2137	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2138	if locked().</p>
2139
2140	<p>Makes a blocking attempt to read-lock the associated read/write mutex object,
2141	and returns <code class="computeroutput">true</code> if successful within the specified time <code class="computeroutput">t</code>,
2142	otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is already
2143	locked by the same thread the behavior is dependent on the <a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
2144	strategy</a> of the associated read/write mutex object.</p>
2145	</td>
2146	</tr>
2147	<tr>
2148	<td><code class="computeroutput">lk.timed_write_lock(t)</code></td>
2149	<td>
2150	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2151	if locked().</p>
2152
2153	<p>Makes a blocking attempt to write-lock the associated read/write mutex object,
2154	and returns <code class="computeroutput">true</code> if successful within the specified time <code class="computeroutput">t</code>,
2155	otherwise <code class="computeroutput">false</code>. If the associated read/write mutex object is already
2156	locked by the same thread the behavior is dependent on the <a href="concepts.html#thread.concepts.locking-strategies" title="Locking Strategies">locking
2157	strategy</a> of the associated read/write mutex object.</p>
2158	</td>
2159	</tr>
2160	<tr>
2161	<td><code class="computeroutput">lk.timed_demote(t)</code></td>
2162	<td>
2163	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2164	if <code class="computeroutput">state() != read_write_lock_state::write_locked</code>.</p>
2165
2166	<p>Makes a blocking attempt to convert the lock held on the associated
2167	read/write mutex object from a write-lock to a read-lock without releasing
2168	the lock, returning <code class="computeroutput">true</code> if the attempt is successful
2169	in the specified time <code class="computeroutput">t</code>, otherwise <code class="computeroutput">false</code>.</p>
2170	</td>
2171	</tr>
2172	<tr>
2173	<td><code class="computeroutput">lk.timed_promote(t)</code></td>
2174	<td>
2175	<p>Throws <code class="computeroutput"><a href="../boost/lock_error.html" title="Class lock_error">boost::lock_error</a></code>
2176	if <code class="computeroutput">state() != read_write_lock_state::read_locked</code>.</p>
2177
2178	<p>Makes a blocking attempt to convert the lock held on the associated
2179	read/write mutex object from a read-lock to a write-lock without releasing
2180	the lock, returning <code class="computeroutput">true</code> if the attempt is successful
2181	in the specified time <code class="computeroutput">t</code>, otherwise <code class="computeroutput">false</code>.</p>
2182	</td>
2183	</tr>
2184	</tbody>
2185	</table>
2186	</div>
2187	</div>
2188	<div class="section" lang="en">
2189	<div class="titlepage"><div><div><h5 class="title">
2190	<a name="thread.concepts.ScopedTimedReadWriteLock"></a>ScopedTimedReadWriteLock Concept</h5></div></div></div>
2191	<p>A ScopedTimedReadWriteLock is a refinement of
2192	<a href="concepts.html#thread.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a>.
2193	For a ScopedTimedReadWriteLock type <code class="computeroutput">L</code>
2194	and an object <code class="computeroutput">lk</code> of that type,
2195	and an object <code class="computeroutput">m</code> of a type meeting the
2196	<a href="concepts.html#thread.concepts.TimedReadWriteMutex" title="TimedReadWriteMutex Concept">TimedReadWriteMutex</a> requirements,
2197	and an object <code class="computeroutput">s</code> of type <code class="computeroutput">read_write_lock_state</code>,
2198	and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../boost/xtime.html" title="Struct xtime">boost::xtime</a></code>,
2199	and an object <code class="computeroutput">b</code> of type <code class="computeroutput">blocking_mode</code>,
2200	the following expressions must be well-formed and have the
2201	indicated effects.</p>
2202	<div class="table">
2203	<a name="id1735097"></a><p class="title"><b>Table 15.21. ScopedTimedReadWriteLock Expressions</b></p>
2204	<table class="table" summary="ScopedTimedReadWriteLock Expressions">
2205	<colgroup>
2206	<col>
2207	<col>
2208	</colgroup>
2209	<thead><tr>
2210	<th>Expression</th>
2211	<th>Effects</th>
2212	</tr></thead>
2213	<tbody>
2214	<tr>
2215	<td><code class="computeroutput">L lk(m,s,b);</code></td>
2216	<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex
2217	object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls
2218	<code class="computeroutput">read_lock()</code> if <code class="computeroutput">b</code>, otherwise <code class="computeroutput">try_read_lock()</code>;
2219	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>,
2220	otherwise <code class="computeroutput">try_write_lock</code>.</td>
2221	</tr>
2222	<tr>
2223	<td><code class="computeroutput">L lk(m,s,t);</code></td>
2224	<td>Constructs an object <code class="computeroutput">lk</code> and associates read/write mutex
2225	object <code class="computeroutput">m</code> with it, then: if <code class="computeroutput">s == read_write_lock_state::read_locked</code>, calls
2226	<code class="computeroutput">timed_read_lock(t)</code>; if <code class="computeroutput">s==read_write_lock_state::write_locked</code>,
2227	calls <code class="computeroutput">timed_write_lock(t)</code>.</td>
2228	</tr>
2229	</tbody>
2230	</table>
2231	</div>
2232	</div>
2233	</div>
2234	<div class="section" lang="en">
2235	<div class="titlepage"><div><div><h4 class="title">
2236	<a name="thread.concepts.read-write-lock-models"></a>Lock Models</h4></div></div></div>
2237	<p><span class="bold"><strong>Boost.Thread</strong></span> currently supplies six models of
2238	<a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a>
2239	and its refinements.</p>
2240	<div class="table">
2241	<a name="id1735280"></a><p class="title"><b>Table 15.22. Lock Models</b></p>
2242	<table class="table" summary="Lock Models">
2243	<colgroup>
2244	<col>
2245	<col>
2246	<col>
2247	</colgroup>
2248	<thead><tr>
2249	<th>Concept</th>
2250	<th>Refines</th>
2251	<th>Models</th>
2252	</tr></thead>
2253	<tbody>
2254	<tr>
2255	<td><a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td>
2256	<td> </td>
2257	<td> </td>
2258	</tr>
2259	<tr>
2260	<td><a href="concepts.html#thread.concepts.ScopedReadWriteLock" title="ScopedReadWriteLock Concept">ScopedReadWriteLock</a></td>
2261	<td><a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td>
2262	<td>
2263	<p><code class="computeroutput">boost::read_write_mutex::scoped_read_write_lock</code></p>
2264	<p><code class="computeroutput">boost::try_read_write_mutex::scoped_read_write_lock</code></p>
2265	<p><code class="computeroutput">boost::timed_read_write_mutex::scoped_read_write_lock</code></p>
2266	</td>
2267	</tr>
2268	<tr>
2269	<td><a href="concepts.html#thread.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td>
2270	<td><a href="concepts.html#thread.concepts.ReadWriteLock" title="ReadWriteLock Concept">ReadWriteLock</a></td>
2271	<td> </td>
2272	</tr>
2273	<tr>
2274	<td><a href="concepts.html#thread.concepts.ScopedTryReadWriteLock" title="ScopedTryReadWriteLock Expressions">ScopedTryReadWriteLock</a></td>
2275	<td><a href="concepts.html#thread.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td>
2276	<td>
2277	<p><code class="computeroutput">boost::try_read_write_mutex::scoped_try_read_write_lock</code></p>
2278	<p><code class="computeroutput">boost::timed_read_write_mutex::scoped_try_read_write_lock</code></p>
2279	</td>
2280	</tr>
2281	<tr>
2282	<td><a href="concepts.html#thread.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a></td>
2283	<td><a href="concepts.html#thread.concepts.TryReadWriteLock" title="TryReadWriteLock Expressions">TryReadWriteLock</a></td>
2284	<td> </td>
2285	</tr>
2286	<tr>
2287	<td><a href="concepts.html#thread.concepts.ScopedTimedReadWriteLock" title="ScopedTimedReadWriteLock Concept">ScopedTimedReadWriteLock</a></td>
2288	<td><a href="concepts.html#thread.concepts.TimedReadWriteLock" title="TimedReadWriteLock Concept">TimedReadWriteLock</a></td>
2289	<td>
2290	<p><code class="computeroutput">boost::timed_read_write_mutex::scoped_timed_read_write_lock</code></p>
2291	</td>
2292	</tr>
2293	</tbody>
2294	</table>
2295	</div>
2296	</div>
2297	</div>
2298	</div>
2299	<table width="100%"><tr>
2300	<td align="left"><small><p>Last revised: January 02, 2007 at 21:44:39 GMT</p></small></td>
2301	<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
2302	</tr></table>
2303	<hr>
2304	<div class="spirit-nav">
2305	<a accesskey="p" href="design.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread.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>
2306	</div>
2307	</body>
2308	</html>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: