Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/doc/html/threads/concepts.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 18 years ago

added boost
File size: 36.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.69.1">
7<link rel="start" href="../index.html" title="The Boost C++ Libraries">
8<link rel="up" href="../threads.html" title="Chapter 12. Boost.Threads">
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.png (6897 bytes)" 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="../threads.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="section" lang="en">
26<div class="titlepage"><div><div><h3 class="title">
27<a name="threads.concepts"></a>Concepts</h3></div></div></div>
28<div class="toc"><dl><dt><span class="section"><a href="concepts.html#threads.concepts.mutexes">Mutexes</a></span></dt></dl></div>
29<div class="section" lang="en">
30<div class="titlepage"><div><div><h4 class="title">
31<a name="threads.concepts.mutexes"></a>Mutexes</h4></div></div></div>
32<div class="toc"><dl>
33<dt><span class="section"><a href="concepts.html#threads.concepts.locking-strategies">Locking Strategies</a></span></dt>
34<dt><span class="section"><a href="concepts.html#threads.concepts.sheduling-policies">Scheduling Policies</a></span></dt>
35<dt><span class="section"><a href="concepts.html#threads.concepts.mutex-concepts">Mutex Concepts</a></span></dt>
36<dt><span class="section"><a href="concepts.html#threads.concepts.mutex-models">Mutex Models</a></span></dt>
37<dt><span class="section"><a href="concepts.html#threads.concepts.lock-concepts">Lock Concepts</a></span></dt>
38<dt><span class="section"><a href="concepts.html#threads.concepts.lock-models">Lock Models</a></span></dt>
39</dl></div>
40<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
41<h3 class="title">Note</h3>Certain changes to the mutexes and lock concepts are
42                currently under discussion. In particular, the combination of
43                the multiple lock concepts into a single lock concept
44                is likely, and the combination of the multiple mutex
45                concepts into a single mutex concept is also possible.</div>
46<p>A mutex (short for mutual-exclusion) object is used to serialize
47                access to a resource shared between multiple threads. The
48                <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> concept, with
49                <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> and
50                <a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> refinements,
51                formalize the requirements. A model that implements Mutex and its
52                refinements has two states: <span class="bold"><strong>locked</strong></span> and
53                <span class="bold"><strong>unlocked</strong></span>. Before using a shared resource, a
54                thread locks a <span class="bold"><strong>Boost.Threads</strong></span> mutex object
55                (an object whose type is a model of
56                <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of it's
57                refinements), ensuring
58                <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a> access to
59                the shared resource. When use of the shared resource is complete, the thread
60                unlocks the mutex object, allowing another thread to acquire the lock and
61                use the shared resource.</p>
62<p>Traditional C thread APIs, like POSIX threads or the Windows thread
63                APIs, expose functions to lock and unlock a mutex object. This is dangerous
64                since it's easy to forget to unlock a locked mutex. When the flow of control
65                is complex, with multiple return points, the likelihood of forgetting to
66                unlock a mutex object becomes even greater. When exceptions are thrown,
67                it becomes nearly impossible to ensure that the mutex object is unlocked
68                properly when using these traditional API's. The result is
69                <a href="../threads.html#threads.glossary.deadlock">deadlock</a>.</p>
70<p>Many C++ threading libraries use a pattern known as <span class="emphasis"><em>Scoped
71                Locking</em></span>[<span class="citation"><a href="../threads.html#threads.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] to free the programmer from
72                the need to explicitly lock and unlock mutex objects. With this pattern, a
73                <a href="concepts.html#threads.concepts.lock-concepts" title="Lock Concepts">Lock</a> concept is employed where
74                the lock object's constructor locks the associated mutex object and the
75                destructor automatically does the unlocking. The
76                <span class="bold"><strong>Boost.Threads</strong></span> library takes this pattern to
77                the extreme in that Lock concepts are the only way to lock and unlock a
78                mutex object: lock and unlock functions are not exposed by any
79                <span class="bold"><strong>Boost.Threads</strong></span> mutex objects. This helps to
80                ensure safe usage patterns, especially when code throws exceptions.</p>
81<div class="section" lang="en">
82<div class="titlepage"><div><div><h5 class="title">
83<a name="threads.concepts.locking-strategies"></a>Locking Strategies</h5></div></div></div>
84<div class="toc"><dl>
85<dt><span class="section"><a href="concepts.html#threads.concepts.recursive-locking-strategy">Recursive Locking Strategy</a></span></dt>
86<dt><span class="section"><a href="concepts.html#threads.concepts.checked-locking-strategy">Checked Locking Strategy</a></span></dt>
87<dt><span class="section"><a href="concepts.html#threads.concepts.unchecked-locking-strategy">Unchecked Locking Strategy</a></span></dt>
88<dt><span class="section"><a href="concepts.html#threads.concepts.unspecified-locking-strategy">Unspecified Locking Strategy</a></span></dt>
89</dl></div>
90<p>Every mutex object follows one of several locking strategies. These
91                        strategies define the semantics for the locking operation when the calling
92                        thread already owns a lock on the mutex object.</p>
93<div class="section" lang="en">
94<div class="titlepage"><div><div><h6 class="title">
95<a name="threads.concepts.recursive-locking-strategy"></a>Recursive Locking Strategy</h6></div></div></div>
96<p>With a recursive locking strategy, when a thread attempts to acquire
97                                a lock on the mutex object for which it already owns a lock, the operation
98                                is successful. Note the distinction between a thread, which may have
99                                multiple locks outstanding on a recursive mutex object, and a lock object,
100                                which even for a recursive mutex object cannot have any of its lock
101                                functions called multiple times without first calling unlock.</p>
102<p>Internally a lock count is maintained and the owning thread must
103                                unlock the mutex object the same number of times that it locked it before
104                                the mutex object's state returns to unlocked. Since mutex objects in
105                                <span class="bold"><strong>Boost.Threads</strong></span> expose locking
106                                functionality only through lock concepts, a thread will always unlock a
107                                mutex object the same number of times that it locked it. This helps to
108                                eliminate a whole set of errors typically found in traditional C style
109                                thread APIs.</p>
110<p>Classes <code class="computeroutput"><a href="../recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code>,
111                                <code class="computeroutput"><a href="../recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code> and
112                                <code class="computeroutput"><a href="../recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code> use this locking
113                                strategy.</p>
114</div>
115<div class="section" lang="en">
116<div class="titlepage"><div><div><h6 class="title">
117<a name="threads.concepts.checked-locking-strategy"></a>Checked Locking Strategy</h6></div></div></div>
118<p>With a checked locking strategy, when a thread attempts to acquire a
119                                lock on the mutex object for which the thread already owns a lock, the
120                                operation will fail with some sort of error indication. Further, attempts
121                                by a thread to unlock a mutex object that was not locked by the thread
122                                will also return some sort of error indication. In
123                                <span class="bold"><strong>Boost.Threads</strong></span>, an exception of type
124                                <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code> 
125                                would be thrown in these cases.</p>
126<p><span class="bold"><strong>Boost.Threads</strong></span> does not currently
127                                provide any mutex objects that use this strategy.</p>
128</div>
129<div class="section" lang="en">
130<div class="titlepage"><div><div><h6 class="title">
131<a name="threads.concepts.unchecked-locking-strategy"></a>Unchecked Locking Strategy</h6></div></div></div>
132<p>With an unchecked locking strategy, when a thread attempts to acquire
133                                a lock on a mutex object for which the thread already owns a lock the
134                                operation will
135                                <a href="../threads.html#threads.glossary.deadlock">deadlock</a>. In general
136                                this locking strategy is less safe than a checked or recursive strategy,
137                                but it's also a faster strategy and so is employed by many libraries.</p>
138<p><span class="bold"><strong>Boost.Threads</strong></span> does not currently
139                                provide any mutex objects that use this strategy.</p>
140</div>
141<div class="section" lang="en">
142<div class="titlepage"><div><div><h6 class="title">
143<a name="threads.concepts.unspecified-locking-strategy"></a>Unspecified Locking Strategy</h6></div></div></div>
144<p>With an unspecified locking strategy, when a thread attempts to
145                                acquire a lock on a mutex object for which the thread already owns a lock
146                                the operation results in
147                                <a href="../threads.html#threads.glossary.undefined-behavior">undefined behavior</a>.
148                                </p>
149<p>In general a mutex object with an unspecified locking strategy is
150                                unsafe, and it requires programmer discipline to use the mutex object
151                                properly. However, this strategy allows an implementation to be as fast as
152                                possible with no restrictions on its implementation. This is especially
153                                true for portable implementations that wrap the native threading support
154                                of a platform. For this reason, the classes
155                                <code class="computeroutput"><a href="../mutex.html" title="Class mutex">boost::mutex</a></code>,
156                                <code class="computeroutput"><a href="../try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code> and
157                                <code class="computeroutput"><a href="../timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code> use this locking strategy
158                                despite the lack of safety.</p>
159</div>
160</div>
161<div class="section" lang="en">
162<div class="titlepage"><div><div><h5 class="title">
163<a name="threads.concepts.sheduling-policies"></a>Scheduling Policies</h5></div></div></div>
164<div class="toc"><dl>
165<dt><span class="section"><a href="concepts.html#threads.concepts.FIFO-scheduling-policy">FIFO Scheduling Policy</a></span></dt>
166<dt><span class="section"><a href="concepts.html#threads.concepts.priority-driven-scheduling-policy">Priority Driven Policy</a></span></dt>
167<dt><span class="section"><a href="concepts.html#threads.concepts.unspecified-scheduling-policy">Unspecified Policy</a></span></dt>
168</dl></div>
169<p>Every mutex object follows one of several scheduling policies. These
170                        policies define the semantics when the mutex object is unlocked and there is
171                        more than one thread waiting to acquire a lock. In other words, the policy
172                        defines which waiting thread shall acquire the lock.</p>
173<div class="section" lang="en">
174<div class="titlepage"><div><div><h6 class="title">
175<a name="threads.concepts.FIFO-scheduling-policy"></a>FIFO Scheduling Policy</h6></div></div></div>
176<p>With a FIFO ("First In First Out") scheduling policy, threads waiting
177                                for the lock will acquire it in a first-come-first-served order.
178                                This can help prevent a high priority thread from starving lower priority
179                                threads that are also waiting on the mutex object's lock.</p>
180</div>
181<div class="section" lang="en">
182<div class="titlepage"><div><div><h6 class="title">
183<a name="threads.concepts.priority-driven-scheduling-policy"></a>Priority Driven Policy</h6></div></div></div>
184<p>With a Priority Driven scheduling policy, the thread with the
185                                highest priority acquires the lock. Note that this means that low-priority
186                                threads may never acquire the lock if the mutex object has high contention
187                                and there is always at least one high-priority thread waiting. This is
188                                known as thread starvation. When multiple threads of the same priority are
189                                waiting on the mutex object's lock one of the other scheduling priorities
190                                will determine which thread shall acquire the lock.</p>
191</div>
192<div class="section" lang="en">
193<div class="titlepage"><div><div><h6 class="title">
194<a name="threads.concepts.unspecified-scheduling-policy"></a>Unspecified Policy</h6></div></div></div>
195<p>The mutex object does not specify a scheduling policy. In order to
196                                ensure portability, all <span class="bold"><strong>Boost.Threads</strong></span>
197                                mutex objects use an unspecified scheduling policy.</p>
198</div>
199</div>
200<div class="section" lang="en">
201<div class="titlepage"><div><div><h5 class="title">
202<a name="threads.concepts.mutex-concepts"></a>Mutex Concepts</h5></div></div></div>
203<div class="toc"><dl>
204<dt><span class="section"><a href="concepts.html#threads.concepts.Mutex">Mutex Concept</a></span></dt>
205<dt><span class="section"><a href="concepts.html#threads.concepts.TryMutex">TryMutex Concept</a></span></dt>
206<dt><span class="section"><a href="concepts.html#threads.concepts.TimedMutex">TimedMutex Concept</a></span></dt>
207</dl></div>
208<div class="section" lang="en">
209<div class="titlepage"><div><div><h6 class="title">
210<a name="threads.concepts.Mutex"></a>Mutex Concept</h6></div></div></div>
211<p>A Mutex object has two states: locked and unlocked. Mutex object
212                                state can only be determined by a lock object meeting the
213                                appropriate lock concept requirements
214                                and constructed for the Mutex object.</p>
215<p>A Mutex is
216                                <a href="../../../libs/utility/utility.htm#Class%20noncopyable" target="_top">
217                                NonCopyable</a>.</p>
218<p>For a Mutex type <code class="computeroutput">M</code>
219                                and an object <code class="computeroutput">m</code> of that type,
220                                the following expressions must be well-formed
221                                and have the indicated effects.</p>
222<div class="table">
223<a name="id2776317"></a><p class="title"><b>Table 12.1. Mutex Expressions</b></p>
224<table class="table" summary="Mutex Expressions">
225<colgroup>
226<col>
227<col>
228</colgroup>
229<thead><tr>
230<th>Expression</th>
231<th>Effects</th>
232</tr></thead>
233<tbody>
234<tr>
235<td>M m;</td>
236<td>
237<p>Constructs a mutex object m.</p>
238<p>Postcondition: m is unlocked.</p>
239</td>
240</tr>
241<tr>
242<td>(&amp;m)-&gt;~M();</td>
243<td>Precondition: m is unlocked. Destroys a mutex object
244                                                                m.</td>
245</tr>
246<tr>
247<td>M::scoped_lock</td>
248<td>A model of
249                                                                <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
250</td>
251</tr>
252</tbody>
253</table>
254</div>
255</div>
256<div class="section" lang="en">
257<div class="titlepage"><div><div><h6 class="title">
258<a name="threads.concepts.TryMutex"></a>TryMutex Concept</h6></div></div></div>
259<p>A TryMutex is a refinement of
260                                <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a>.
261                                For a TryMutex type <code class="computeroutput">M</code>
262                                and an object <code class="computeroutput">m</code> of that type,
263                                the following expressions must be well-formed
264                                and have the indicated effects.</p>
265<div class="table">
266<a name="id2776393"></a><p class="title"><b>Table 12.2. TryMutex Expressions</b></p>
267<table class="table" summary="TryMutex Expressions">
268<colgroup>
269<col>
270<col>
271</colgroup>
272<thead><tr>
273<th>Expression</th>
274<th>Effects</th>
275</tr></thead>
276<tbody><tr>
277<td>M::scoped_try_lock</td>
278<td>A model of
279                                                                <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>
280</td>
281</tr></tbody>
282</table>
283</div>
284</div>
285<div class="section" lang="en">
286<div class="titlepage"><div><div><h6 class="title">
287<a name="threads.concepts.TimedMutex"></a>TimedMutex Concept</h6></div></div></div>
288<p>A TimedMutex is a refinement of
289                                <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a>.
290                                For a TimedMutex type <code class="computeroutput">M</code>
291                                and an object <code class="computeroutput">m</code> of that type,
292                                the following expressions must be well-formed
293                                and have the indicated effects.</p>
294<div class="table">
295<a name="id2776453"></a><p class="title"><b>Table 12.3. TimedMutex Expressions</b></p>
296<table class="table" summary="TimedMutex Expressions">
297<colgroup>
298<col>
299<col>
300</colgroup>
301<thead><tr>
302<th>Expression</th>
303<th>Effects</th>
304</tr></thead>
305<tbody><tr>
306<td>M::scoped_timed_lock</td>
307<td>A model of
308                                                                <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
309</td>
310</tr></tbody>
311</table>
312</div>
313</div>
314</div>
315<div class="section" lang="en">
316<div class="titlepage"><div><div><h5 class="title">
317<a name="threads.concepts.mutex-models"></a>Mutex Models</h5></div></div></div>
318<p><span class="bold"><strong>Boost.Threads</strong></span> currently supplies six models of
319                        <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a>
320                        and its refinements.</p>
321<div class="table">
322<a name="id2776506"></a><p class="title"><b>Table 12.4. Mutex Models</b></p>
323<table class="table" summary="Mutex Models">
324<colgroup>
325<col>
326<col>
327<col>
328</colgroup>
329<thead><tr>
330<th>Concept</th>
331<th>Refines</th>
332<th>Models</th>
333</tr></thead>
334<tbody>
335<tr>
336<td><a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a></td>
337<td> </td>
338<td>
339<p><code class="computeroutput"><a href="../mutex.html" title="Class mutex">boost::mutex</a></code></p>
340<p><code class="computeroutput"><a href="../recursive_mutex.html" title="Class recursive_mutex">boost::recursive_mutex</a></code></p>
341</td>
342</tr>
343<tr>
344<td><a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td>
345<td><a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a></td>
346<td>
347<p><code class="computeroutput"><a href="../try_mutex.html" title="Class try_mutex">boost::try_mutex</a></code></p>
348<p><code class="computeroutput"><a href="../recursive_try_mutex.html" title="Class recursive_try_mutex">boost::recursive_try_mutex</a></code></p>
349</td>
350</tr>
351<tr>
352<td><a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a></td>
353<td><a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a></td>
354<td>
355<p><code class="computeroutput"><a href="../timed_mutex.html" title="Class timed_mutex">boost::timed_mutex</a></code></p>
356<p><code class="computeroutput"><a href="../recursive_timed_mutex.html" title="Class recursive_timed_mutex">boost::recursive_timed_mutex</a></code></p>
357</td>
358</tr>
359</tbody>
360</table>
361</div>
362</div>
363<div class="section" lang="en">
364<div class="titlepage"><div><div><h5 class="title">
365<a name="threads.concepts.lock-concepts"></a>Lock Concepts</h5></div></div></div>
366<div class="toc"><dl>
367<dt><span class="section"><a href="concepts.html#threads.concepts.Lock">Lock Concept</a></span></dt>
368<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedLock">ScopedLock Concept</a></span></dt>
369<dt><span class="section"><a href="concepts.html#threads.concepts.TryLock">TryLock Concept</a></span></dt>
370<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTryLock">ScopedTryLock Concept</a></span></dt>
371<dt><span class="section"><a href="concepts.html#threads.concepts.TimedLock">TimedLock Concept</a></span></dt>
372<dt><span class="section"><a href="concepts.html#threads.concepts.ScopedTimedLock">ScopedTimedLock Concept</a></span></dt>
373</dl></div>
374<p>A lock object provides a safe means for locking and unlocking a mutex
375                        object (an object whose type is a model of <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of its refinements). In
376                        other words they are an implementation of the <span class="emphasis"><em>Scoped
377                        Locking</em></span>[<span class="citation"><a href="../threads.html#threads.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] pattern. The <a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>,
378                        <a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a>, and
379                        <a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a>
380                        concepts formalize the requirements.</p>
381<p>Lock objects are constructed with a reference to a mutex object and
382                        typically acquire ownership of the mutex object by setting its state to
383                        locked. They also ensure ownership is relinquished in the destructor. Lock
384                        objects also expose functions to query the lock status and to manually lock
385                        and unlock the mutex object.</p>
386<p>Lock objects are meant to be short lived, expected to be used at block
387                        scope only. The lock objects are not <a href="../threads.html#threads.glossary.thread-safe">thread-safe</a>. Lock objects must
388                        maintain state to indicate whether or not they've been locked and this state
389                        is not protected by any synchronization concepts. For this reason a lock
390                        object should never be shared between multiple threads.</p>
391<div class="section" lang="en">
392<div class="titlepage"><div><div><h6 class="title">
393<a name="threads.concepts.Lock"></a>Lock Concept</h6></div></div></div>
394<p>For a Lock type <code class="computeroutput">L</code> 
395                                and an object <code class="computeroutput">lk</code> 
396                                and const object <code class="computeroutput">clk</code> of that type,
397                                the following expressions must be well-formed
398                                and have the indicated effects.</p>
399<div class="table">
400<a name="id2776742"></a><p class="title"><b>Table 12.5. Lock Expressions</b></p>
401<table class="table" summary="Lock Expressions">
402<colgroup>
403<col>
404<col>
405</colgroup>
406<thead><tr>
407<th>Expression</th>
408<th>Effects</th>
409</tr></thead>
410<tbody>
411<tr>
412<td><code class="computeroutput">(&amp;lk)-&gt;~L();</code></td>
413<td><code class="computeroutput">if (locked()) unlock();</code></td>
414</tr>
415<tr>
416<td><code class="computeroutput">(&amp;clk)-&gt;operator const void*()</code></td>
417<td>Returns type void*, non-zero if the associated mutex
418                                                                object has been locked by <code class="computeroutput">clk</code>, otherwise 0.</td>
419</tr>
420<tr>
421<td><code class="computeroutput">clk.locked()</code></td>
422<td>Returns a <code class="computeroutput">bool</code>, <code class="computeroutput">(&amp;clk)-&gt;operator
423                                                                const void*() != 0</code>
424</td>
425</tr>
426<tr>
427<td><code class="computeroutput">lk.lock()</code></td>
428<td>
429<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code>
430                                                                        if <code class="computeroutput">locked()</code>.</p>
431<p>If the associated mutex object is
432                                                                        already locked by some other thread, places the current thread in the
433                                                                        <a href="../threads.html#threads.glossary.thread-state">Blocked</a> state until
434                                                                        the associated mutex is unlocked, after which the current thread
435                                                                        is placed in the <a href="../threads.html#threads.glossary.thread-state">Ready</a> state,
436                                                                        eventually to be returned to the <a href="../threads.html#threads.glossary.thread-state">Running</a> state. If
437                                                                        the associated mutex object is already locked by the same thread
438                                                                        the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking
439                                                                        strategy</a> of the associated mutex object.</p>
440<p>Postcondition: <code class="computeroutput">locked() == true</code></p>
441</td>
442</tr>
443<tr>
444<td><code class="computeroutput">lk.unlock()</code></td>
445<td>
446<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code>
447                                                                        if <code class="computeroutput">!locked()</code>.</p>
448<p>Unlocks the associated mutex.</p>
449<p>Postcondition: <code class="computeroutput">!locked()</code></p>
450</td>
451</tr>
452</tbody>
453</table>
454</div>
455</div>
456<div class="section" lang="en">
457<div class="titlepage"><div><div><h6 class="title">
458<a name="threads.concepts.ScopedLock"></a>ScopedLock Concept</h6></div></div></div>
459<p>A ScopedLock is a refinement of <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a>.
460                                For a ScopedLock type <code class="computeroutput">L</code> 
461                                and an object <code class="computeroutput">lk</code> of that type,
462                                and an object <code class="computeroutput">m</code> of a type meeting the
463                                <a href="concepts.html#threads.concepts.Mutex" title="Mutex Concept">Mutex</a> requirements,
464                                and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
465                                the following expressions must be well-formed
466                                and have the indicated effects.</p>
467<div class="table">
468<a name="id2776979"></a><p class="title"><b>Table 12.6. ScopedLock Expressions</b></p>
469<table class="table" summary="ScopedLock Expressions">
470<colgroup>
471<col>
472<col>
473</colgroup>
474<thead><tr>
475<th>Expression</th>
476<th>Effects</th>
477</tr></thead>
478<tbody>
479<tr>
480<td><code class="computeroutput">L lk(m);</code></td>
481<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
482                                                                object <code class="computeroutput">m</code> with it, then calls
483                                                                <code class="computeroutput">lock()</code>
484</td>
485</tr>
486<tr>
487<td><code class="computeroutput">L lk(m,b);</code></td>
488<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
489                                                                object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
490                                                                <code class="computeroutput">lock()</code>
491</td>
492</tr>
493</tbody>
494</table>
495</div>
496</div>
497<div class="section" lang="en">
498<div class="titlepage"><div><div><h6 class="title">
499<a name="threads.concepts.TryLock"></a>TryLock Concept</h6></div></div></div>
500<p>A TryLock is a refinement of <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a>.
501                                For a TryLock type <code class="computeroutput">L</code> 
502                                and an object <code class="computeroutput">lk</code> of that type,
503                                the following expressions must be well-formed
504                                and have the indicated effects.</p>
505<div class="table">
506<a name="id2777084"></a><p class="title"><b>Table 12.7. TryLock Expressions</b></p>
507<table class="table" summary="TryLock Expressions">
508<colgroup>
509<col>
510<col>
511</colgroup>
512<thead><tr>
513<th>Expression</th>
514<th>Effects</th>
515</tr></thead>
516<tbody><tr>
517<td><code class="computeroutput">lk.try_lock()</code></td>
518<td>
519<p>Throws  <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code>
520                                                                        if locked().</p>
521<p>Makes a
522                                                                        non-blocking attempt to lock the associated mutex object,
523                                                                        returning <code class="computeroutput">true</code> if the lock attempt is successful,
524                                                                        otherwise <code class="computeroutput">false</code>. If the associated mutex object is
525                                                                        already locked by the same thread the behavior is dependent on the
526                                                                        <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking
527                                                                        strategy</a> of the associated mutex object.</p>
528</td>
529</tr></tbody>
530</table>
531</div>
532</div>
533<div class="section" lang="en">
534<div class="titlepage"><div><div><h6 class="title">
535<a name="threads.concepts.ScopedTryLock"></a>ScopedTryLock Concept</h6></div></div></div>
536<p>A ScopedTryLock is a refinement of <a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a>.
537                                For a ScopedTryLock type <code class="computeroutput">L</code> 
538                                and an object <code class="computeroutput">lk</code> of that type,
539                                and an object <code class="computeroutput">m</code> of a type meeting the
540                                <a href="concepts.html#threads.concepts.TryMutex" title="TryMutex Concept">TryMutex</a> requirements,
541                                and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
542                                the following expressions must be well-formed
543                                and have the indicated effects.</p>
544<div class="table">
545<a name="id2777206"></a><p class="title"><b>Table 12.8. ScopedTryLock Expressions</b></p>
546<table class="table" summary="ScopedTryLock Expressions">
547<colgroup>
548<col>
549<col>
550</colgroup>
551<thead><tr>
552<th>Expression</th>
553<th>Effects</th>
554</tr></thead>
555<tbody>
556<tr>
557<td><code class="computeroutput">L lk(m);</code></td>
558<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
559                                                                object <code class="computeroutput">m</code> with it, then calls
560                                                                <code class="computeroutput">try_lock()</code>
561</td>
562</tr>
563<tr>
564<td><code class="computeroutput">L lk(m,b);</code></td>
565<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
566                                                                object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
567                                                                <code class="computeroutput">lock()</code>
568</td>
569</tr>
570</tbody>
571</table>
572</div>
573</div>
574<div class="section" lang="en">
575<div class="titlepage"><div><div><h6 class="title">
576<a name="threads.concepts.TimedLock"></a>TimedLock Concept</h6></div></div></div>
577<p>A TimedLock is a refinement of <a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a>.
578                                For a TimedLock type <code class="computeroutput">L</code> 
579                                and an object <code class="computeroutput">lk</code> of that type,
580                                and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>,
581                                the following expressions must be well-formed
582                                and have the indicated effects.</p>
583<div class="table">
584<a name="id2777328"></a><p class="title"><b>Table 12.9. TimedLock Expressions</b></p>
585<table class="table" summary="TimedLock Expressions">
586<colgroup>
587<col>
588<col>
589</colgroup>
590<thead><tr>
591<th>Expression</th>
592<th>Effects</th>
593</tr></thead>
594<tbody><tr>
595<td><code class="computeroutput">lk.timed_lock(t)</code></td>
596<td>
597<p>Throws <code class="computeroutput"><a href="../lock_error.html" title="Class lock_error">boost::lock_error</a></code>
598                                                                        if locked().</p>
599<p>Makes a blocking attempt
600                                                                        to lock the associated mutex object, and returns <code class="computeroutput">true</code>
601                                                                        if successful within the specified time <code class="computeroutput">t</code>, otherwise
602                                                                        <code class="computeroutput">false</code>. If the associated mutex object is already
603                                                                        locked by the same thread the behavior is dependent on the <a href="concepts.html#threads.concepts.locking-strategies" title="Locking Strategies">locking
604                                                                        strategy</a> of the associated mutex object.</p>
605</td>
606</tr></tbody>
607</table>
608</div>
609</div>
610<div class="section" lang="en">
611<div class="titlepage"><div><div><h6 class="title">
612<a name="threads.concepts.ScopedTimedLock"></a>ScopedTimedLock Concept</h6></div></div></div>
613<p>A ScopedTimedLock is a refinement of <a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a>.
614                                For a ScopedTimedLock type <code class="computeroutput">L</code> 
615                                and an object <code class="computeroutput">lk</code> of that type,
616                                and an object <code class="computeroutput">m</code> of a type meeting the
617                                <a href="concepts.html#threads.concepts.TimedMutex" title="TimedMutex Concept">TimedMutex</a> requirements,
618                                and an object <code class="computeroutput">b</code> of type <code class="computeroutput">bool</code>,
619                                and an object <code class="computeroutput">t</code> of type <code class="computeroutput"><a href="../xtime.html" title="Struct xtime">boost::xtime</a></code>,
620                                the following expressions must be well-formed
621                                and have the indicated effects.</p>
622<div class="table">
623<a name="id2777472"></a><p class="title"><b>Table 12.10. ScopedTimedLock Expressions</b></p>
624<table class="table" summary="ScopedTimedLock Expressions">
625<colgroup>
626<col>
627<col>
628</colgroup>
629<thead><tr>
630<th>Expression</th>
631<th>Effects</th>
632</tr></thead>
633<tbody>
634<tr>
635<td><code class="computeroutput">L lk(m,t);</code></td>
636<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
637                                                                object <code class="computeroutput">m</code> with it, then calls
638                                                                <code class="computeroutput">timed_lock(t)</code>
639</td>
640</tr>
641<tr>
642<td><code class="computeroutput">L lk(m,b);</code></td>
643<td>Constructs an object <code class="computeroutput">lk</code>, and associates mutex
644                                                                object <code class="computeroutput">m</code> with it, then if <code class="computeroutput">b</code>, calls
645                                                                <code class="computeroutput">lock()</code>
646</td>
647</tr>
648</tbody>
649</table>
650</div>
651</div>
652</div>
653<div class="section" lang="en">
654<div class="titlepage"><div><div><h5 class="title">
655<a name="threads.concepts.lock-models"></a>Lock Models</h5></div></div></div>
656<p><span class="bold"><strong>Boost.Threads</strong></span> currently supplies twelve models of
657                        <a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a>
658                        and its refinements.</p>
659<div class="table">
660<a name="id2777570"></a><p class="title"><b>Table 12.11. Lock Models</b></p>
661<table class="table" summary="Lock Models">
662<colgroup>
663<col>
664<col>
665<col>
666</colgroup>
667<thead><tr>
668<th>Concept</th>
669<th>Refines</th>
670<th>Models</th>
671</tr></thead>
672<tbody>
673<tr>
674<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td>
675<td> </td>
676<td> </td>
677</tr>
678<tr>
679<td><a href="concepts.html#threads.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a></td>
680<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td>
681<td>
682<p><code class="computeroutput">boost::mutex::scoped_lock</code></p>
683<p><code class="computeroutput">boost::recursive_mutex::scoped_lock</code></p>
684<p><code class="computeroutput">boost::try_mutex::scoped_lock</code></p>
685<p><code class="computeroutput">boost::recursive_try_mutex::scoped_lock</code></p>
686<p><code class="computeroutput">boost::timed_mutex::scoped_lock</code></p>
687<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_lock</code></p>
688</td>
689</tr>
690<tr>
691<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
692<td><a href="concepts.html#threads.concepts.Lock" title="Lock Concept">Lock</a></td>
693<td> </td>
694</tr>
695<tr>
696<td><a href="concepts.html#threads.concepts.ScopedTryLock" title="ScopedTryLock Concept">ScopedTryLock</a></td>
697<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
698<td>
699<p><code class="computeroutput">boost::try_mutex::scoped_try_lock</code></p>
700<p><code class="computeroutput">boost::recursive_try_mutex::scoped_try_lock</code></p>
701<p><code class="computeroutput">boost::timed_mutex::scoped_try_lock</code></p>
702<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_try_lock</code></p>
703</td>
704</tr>
705<tr>
706<td><a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td>
707<td><a href="concepts.html#threads.concepts.TryLock" title="TryLock Concept">TryLock</a></td>
708<td> </td>
709</tr>
710<tr>
711<td><a href="concepts.html#threads.concepts.ScopedTimedLock" title="ScopedTimedLock Concept">ScopedTimedLock</a></td>
712<td><a href="concepts.html#threads.concepts.TimedLock" title="TimedLock Concept">TimedLock</a></td>
713<td>
714<p><code class="computeroutput">boost::timed_mutex::scoped_timed_lock</code></p>
715<p><code class="computeroutput">boost::recursive_timed_mutex::scoped_timed_lock</code></p>
716</td>
717</tr>
718</tbody>
719</table>
720</div>
721</div>
722</div>
723</div>
724<table width="100%"><tr>
725<td align="left"><small><p>Last revised: October 16, 2005 at 14:37:34 GMT</p></small></td>
726<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
727</tr></table>
728<hr>
729<div class="spirit-nav">
730<a accesskey="p" href="design.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../threads.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rationale.html"><img src="../images/next.png" alt="Next"></a>
731</div>
732</body>
733</html>
Note: See TracBrowser for help on using the repository browser.