Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/doc/html/boost/condition.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: 15.8 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>Class condition</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/reference.html#header.boost.thread.condition.hpp" title="Header &lt;boost/thread/condition.hpp&gt;">
9<link rel="prev" href="barrier.html" title="Class barrier">
10<link rel="next" href="lock_error.html" title="Class lock_error">
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="barrier.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.condition.hpp"><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="lock_error.html"><img src="../images/next.png" alt="Next"></a>
24</div>
25<div class="refentry" lang="en">
26<a name="boost.condition"></a><div class="titlepage"></div>
27<div class="refnamediv">
28<h2><span class="refentrytitle">Class condition</span></h2>
29<p>boost::condition &#8212; <p>An object of class <a href="condition.html" title="Class condition">condition</a> is a
30          synchronization primitive used to cause a thread to wait until a
31          particular shared-data condition (or time) is met.</p></p>
32</div>
33<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2>
34<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis">
35<span class="bold"><strong>class</strong></span> condition : <span class="bold"><strong>private</strong></span> boost::noncopyable   <span class="emphasis"><em>// Exposition only</em></span>
36{
37<span class="bold"><strong>public</strong></span>:
38  <span class="emphasis"><em>// <a href="condition.html#boost.conditionconstruct-copy-destruct">construct/copy/destruct</a></em></span>
39  <a href="condition.html#id976835-bb">condition</a>();
40  <a href="condition.html#id976848-bb">~condition</a>();
41
42  <span class="emphasis"><em>// <a href="condition.html#id976860-bb">notification</a></em></span>
43  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="condition.html#id976864-bb">notify_one</a>();
44  <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="condition.html#id661647-bb">notify_all</a>();
45
46  <span class="emphasis"><em>// <a href="condition.html#id686445-bb">waiting</a></em></span>
47  <span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock&gt; <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="condition.html#id686450-bb">wait</a>(ScopedLock&amp;);
48  <span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock, <span class="bold"><strong>typename</strong></span> Pred&gt; <span class="type"><span class="bold"><strong>void</strong></span></span> <a href="condition.html#id762497-bb">wait</a>(ScopedLock&amp;, Pred);
49  <span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock&gt; 
50    <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="condition.html#id1289365-bb">timed_wait</a>(ScopedLock&amp;, <span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">boost::xtime</a>&amp;);
51  <span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock, <span class="bold"><strong>typename</strong></span> Pred&gt; 
52    <span class="type"><span class="bold"><strong>bool</strong></span></span> <a href="condition.html#id1292607-bb">timed_wait</a>(ScopedLock&amp;, <span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">boost::xtime</a>&amp;, Pred);
53};</pre></div>
54<div class="refsect1" lang="en">
55<a name="id1737157"></a><h2>Description</h2>
56<p>A <a href="condition.html" title="Class condition">condition</a> object is always used in
57          conjunction with a <a href="../thread/concepts.html#thread.concepts.mutexes" title="Mutexes">mutex</a>
58          object (an object whose type is a model of a <a href="../thread/concepts.html#thread.concepts.Mutex" title="Mutex Concept">Mutex</a> or one of its
59          refinements). The mutex object must be locked prior to waiting on the
60          condition, which is verified by passing a lock object (an object whose
61          type is a model of <a href="../thread/concepts.html#thread.concepts.Lock" title="Lock Concept">Lock</a> or
62          one of its refinements) to the <a href="condition.html" title="Class condition">condition</a> object's
63          wait functions. Upon blocking on the <a href="condition.html" title="Class condition">condition</a>
64          object, the thread unlocks the mutex object. When the thread returns
65          from a call to one of the <a href="condition.html" title="Class condition">condition</a> object's wait
66          functions the mutex object is again locked. The tricky unlock/lock
67          sequence is performed automatically by the
68          <a href="condition.html" title="Class condition">condition</a> object's wait functions.</p>
69<p>The <a href="condition.html" title="Class condition">condition</a> type is often used to
70          implement the Monitor Object and other important patterns (see
71          [<span class="citation"><a href="../thread.html#thread.bib.SchmidtStalRohnertBuschmann">SchmidtStalRohnertBuschmann</a></span>] and [<span class="citation"><a href="../thread.html#thread.bib.Hoare74">Hoare74</a></span>]). Monitors are one
72          of the most important patterns for creating reliable multithreaded
73          programs.</p>
74<p>See <a href="../thread.html#thread.glossary" title="Glossary">Glossary</a> for definitions of <a href="../thread.html#thread.glossary.thread-state">thread states</a>
75          blocked and ready. Note that "waiting" is a synonym for blocked.</p>
76<div class="refsect2" lang="en">
77<a name="id1737290"></a><h3>
78<a name="boost.conditionconstruct-copy-destruct"></a><code class="computeroutput">condition</code> construct/copy/destruct</h3>
79<div class="orderedlist"><ol type="1">
80<li>
81<pre class="literallayout"><a name="id976835-bb"></a>condition();</pre>
82<div class="variablelist"><table border="0">
83<col align="left" valign="top">
84<tbody><tr>
85<td>
86<span class="term">Effects:</span></td>
87<td>Constructs a <a href="condition.html" title="Class condition">condition</a>
88            object.</td>
89</tr></tbody>
90</table></div>
91</li>
92<li>
93<pre class="literallayout"><a name="id976848-bb"></a>~condition();</pre>
94<div class="variablelist"><table border="0">
95<col align="left" valign="top">
96<tbody><tr>
97<td>
98<span class="term">Effects:</span></td>
99<td>Destroys <code class="computeroutput">*this</code>.</td>
100</tr></tbody>
101</table></div>
102</li>
103</ol></div>
104</div>
105<div class="refsect2" lang="en">
106<a name="id1737374"></a><h3>
107<a name="id976860-bb"></a><code class="computeroutput">condition</code> notification</h3>
108<div class="orderedlist"><ol type="1">
109<li>
110<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id976864-bb"></a>notify_one();</pre>
111<div class="variablelist"><table border="0">
112<col align="left" valign="top">
113<tbody>
114<tr>
115<td>
116<span class="term">Effects:</span></td>
117<td>If there is a thread waiting on <code class="computeroutput">*this</code>,
118              change that thread's state to ready. Otherwise there is no
119              effect.</td>
120</tr>
121<tr>
122<td>
123<span class="term">Notes:</span></td>
124<td>If more than one thread is waiting on <code class="computeroutput">*this</code>,
125              it is unspecified which is made ready. After returning to a ready
126              state the notified thread must still acquire the mutex again (which
127              occurs within the call to one of the <a href="condition.html" title="Class condition">condition</a>
128              object's wait functions.)</td>
129</tr>
130</tbody>
131</table></div>
132</li>
133<li>
134<pre class="literallayout"><span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id661647-bb"></a>notify_all();</pre>
135<div class="variablelist"><table border="0">
136<col align="left" valign="top">
137<tbody><tr>
138<td>
139<span class="term">Effects:</span></td>
140<td>Change the state of all threads waiting on
141              <code class="computeroutput">*this</code> to ready. If there are no waiting threads,
142              <code class="computeroutput">notify_all()</code> has no effect.</td>
143</tr></tbody>
144</table></div>
145</li>
146</ol></div>
147</div>
148<div class="refsect2" lang="en">
149<a name="id1737501"></a><h3>
150<a name="id686445-bb"></a><code class="computeroutput">condition</code> waiting</h3>
151<div class="orderedlist"><ol type="1">
152<li>
153<pre class="literallayout"><span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock&gt; <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id686450-bb"></a>wait(ScopedLock&amp; lock);</pre>
154<div class="variablelist"><table border="0">
155<col align="left" valign="top">
156<tbody>
157<tr>
158<td>
159<span class="term">Requires:</span></td>
160<td>
161<code class="computeroutput">ScopedLock</code> meets the <a href="../thread/concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
162              requirements.</td>
163</tr>
164<tr>
165<td>
166<span class="term">Effects:</span></td>
167<td>Releases the lock on the <a href="../thread/concepts.html#thread.concepts.mutexes" title="Mutexes">mutex object</a>
168              associated with <code class="computeroutput">lock</code>, blocks the current thread of execution
169              until readied by a call to <code class="computeroutput">this-&gt;notify_one()</code>
170              or<code class="computeroutput"> this-&gt;notify_all()</code>, and then reacquires the
171              lock.</td>
172</tr>
173<tr>
174<td>
175<span class="term">Throws:</span></td>
176<td>
177<a href="lock_error.html" title="Class lock_error">lock_error</a> if
178              <code class="computeroutput">!lock.locked()</code>
179</td>
180</tr>
181</tbody>
182</table></div>
183</li>
184<li>
185<pre class="literallayout"><span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock, <span class="bold"><strong>typename</strong></span> Pred&gt; 
186  <span class="type"><span class="bold"><strong>void</strong></span></span> <a name="id762497-bb"></a>wait(ScopedLock&amp; lock, Pred pred);</pre>
187<div class="variablelist"><table border="0">
188<col align="left" valign="top">
189<tbody>
190<tr>
191<td>
192<span class="term">Requires:</span></td>
193<td>
194<code class="computeroutput">ScopedLock</code> meets the <a href="../thread/concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
195              requirements and the return from <code class="computeroutput">pred()</code> is
196              convertible to <code class="computeroutput">bool</code>.</td>
197</tr>
198<tr>
199<td>
200<span class="term">Effects:</span></td>
201<td>As if: <code class="computeroutput">while (!pred())
202                wait(lock)</code>
203</td>
204</tr>
205<tr>
206<td>
207<span class="term">Throws:</span></td>
208<td>
209<a href="lock_error.html" title="Class lock_error">lock_error</a> if
210              <code class="computeroutput">!lock.locked()</code>
211</td>
212</tr>
213</tbody>
214</table></div>
215</li>
216<li>
217<pre class="literallayout"><span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock&gt; 
218  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1289365-bb"></a>timed_wait(ScopedLock&amp; lock, <span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">boost::xtime</a>&amp; xt);</pre>
219<div class="variablelist"><table border="0">
220<col align="left" valign="top">
221<tbody>
222<tr>
223<td>
224<span class="term">Requires:</span></td>
225<td>
226<code class="computeroutput">ScopedLock</code> meets the <a href="../thread/concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
227              requirements.</td>
228</tr>
229<tr>
230<td>
231<span class="term">Effects:</span></td>
232<td>Releases the lock on the <a href="../thread/concepts.html#thread.concepts.mutexes" title="Mutexes">mutex object</a>
233              associated with <code class="computeroutput">lock</code>, blocks the current thread of execution
234              until readied by a call to <code class="computeroutput">this-&gt;notify_one()</code>
235              or<code class="computeroutput"> this-&gt;notify_all()</code>, or until time <code class="computeroutput">xt</code> 
236              is reached, and then reacquires the lock.</td>
237</tr>
238<tr>
239<td>
240<span class="term">Returns:</span></td>
241<td>
242<code class="computeroutput">false</code> if time <code class="computeroutput">xt</code> is reached,
243              otherwise <code class="computeroutput">true</code>.</td>
244</tr>
245<tr>
246<td>
247<span class="term">Throws:</span></td>
248<td>
249<a href="lock_error.html" title="Class lock_error">lock_error</a> if
250              <code class="computeroutput">!lock.locked()</code>
251</td>
252</tr>
253</tbody>
254</table></div>
255</li>
256<li>
257<pre class="literallayout"><span class="bold"><strong>template</strong></span>&lt;<span class="bold"><strong>typename</strong></span> ScopedLock, <span class="bold"><strong>typename</strong></span> Pred&gt; 
258  <span class="type"><span class="bold"><strong>bool</strong></span></span> <a name="id1292607-bb"></a>timed_wait(ScopedLock&amp; lock, <span class="bold"><strong>const</strong></span> <a href="xtime.html" title="Struct xtime">boost::xtime</a>&amp; xt, Pred pred);</pre>
259<div class="variablelist"><table border="0">
260<col align="left" valign="top">
261<tbody>
262<tr>
263<td>
264<span class="term">Requires:</span></td>
265<td>
266<code class="computeroutput">ScopedLock</code> meets the <a href="../thread/concepts.html#thread.concepts.ScopedLock" title="ScopedLock Concept">ScopedLock</a>
267              requirements and the return from <code class="computeroutput">pred()</code> is
268              convertible to <code class="computeroutput">bool</code>.</td>
269</tr>
270<tr>
271<td>
272<span class="term">Effects:</span></td>
273<td>As if: <code class="computeroutput">while (!pred()) { if (!timed_wait(lock,
274                xt)) return false; } return true;</code>
275</td>
276</tr>
277<tr>
278<td>
279<span class="term">Returns:</span></td>
280<td>
281<code class="computeroutput">false</code> if <code class="computeroutput">xt</code> is reached,
282              otherwise <code class="computeroutput">true</code>.</td>
283</tr>
284<tr>
285<td>
286<span class="term">Throws:</span></td>
287<td>
288<a href="lock_error.html" title="Class lock_error">lock_error</a> if
289              <code class="computeroutput">!lock.locked()</code>
290</td>
291</tr>
292</tbody>
293</table></div>
294</li>
295</ol></div>
296</div>
297</div>
298</div>
299<table width="100%"><tr>
300<td align="left"></td>
301<td align="right"><small>Copyright © 2001-2003 William E. Kempf</small></td>
302</tr></table>
303<hr>
304<div class="spirit-nav">
305<a accesskey="p" href="barrier.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../thread/reference.html#header.boost.thread.condition.hpp"><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="lock_error.html"><img src="../images/next.png" alt="Next"></a>
306</div>
307</body>
308</html>
Note: See TracBrowser for help on using the repository browser.