Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/thread/doc/condition-ref.xml @ 12

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

added boost
File size: 8.1 KB
RevLine 
[12]1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
3  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd" [
4  <!ENTITY % threads.entities SYSTEM "entities.xml">
5  %threads.entities;
6]>
7<header name="boost/thread/condition.hpp"
8  last-revision="$Date: 2004/07/17 04:33:59 $">
9  <namespace name="boost">
10    <class name="condition">
11      <inherit access="private">
12        <type><classname>boost::noncopyable</classname></type>
13        <purpose>Exposition only</purpose>
14      </inherit>
15
16      <purpose>
17        <para>An object of class <classname>condition</classname> is a
18          synchronization primitive used to cause a thread to wait until a
19          particular shared-data condition (or time) is met.</para>
20      </purpose>
21
22      <description>
23        <para>A <classname>condition</classname> object is always used in
24          conjunction with a <link linkend="threads.concepts.mutexes">mutex</link>
25          object (an object whose type is a model of a <link
26            linkend="threads.concepts.Mutex">Mutex</link> or one of its
27          refinements). The mutex object must be locked prior to waiting on the
28          condition, which is verified by passing a lock object (an object whose
29          type is a model of <link linkend="threads.concepts.Lock">Lock</link> or
30          one of its refinements) to the <classname>condition</classname> object's
31          wait functions. Upon blocking on the <classname>condition</classname>
32          object, the thread unlocks the mutex object. When the thread returns
33          from a call to one of the <classname>condition</classname> object's wait
34          functions the mutex object is again locked. The tricky unlock/lock
35          sequence is performed automatically by the
36          <classname>condition</classname> object's wait functions.</para>
37        <para>The <classname>condition</classname> type is often used to
38          implement the Monitor Object and other important patterns (see
39          &cite.SchmidtStalRohnertBuschmann; and &cite.Hoare74;). Monitors are one
40          of the most important patterns for creating reliable multithreaded
41          programs.</para>
42        <para>See <xref linkend="threads.glossary"/> for definitions of <link
43            linkend="threads.glossary.thread-state">thread states</link>
44          blocked and ready. Note that "waiting" is a synonym for blocked.</para>
45      </description>
46
47      <constructor>
48        <effects><simpara>Constructs a <classname>condition</classname>
49            object.</simpara></effects>
50      </constructor>
51
52      <destructor>
53        <effects><simpara>Destroys <code>*this</code>.</simpara></effects>
54      </destructor>
55
56      <method-group name="notification">
57        <method name="notify_one">
58          <type>void</type>
59          <effects><simpara>If there is a thread waiting on <code>*this</code>,
60              change that thread's state to ready. Otherwise there is no
61              effect.</simpara></effects>
62          <notes><simpara>If more than one thread is waiting on <code>*this</code>,
63              it is unspecified which is made ready. After returning to a ready
64              state the notified thread must still acquire the mutex again (which
65              occurs within the call to one of the <classname>condition</classname>
66              object's wait functions.)</simpara></notes>
67        </method>
68
69        <method name="notify_all">
70          <type>void</type>
71          <effects><simpara>Change the state of all threads waiting on
72              <code>*this</code> to ready. If there are no waiting threads,
73              <code>notify_all()</code> has no effect.</simpara></effects>
74        </method>
75      </method-group>
76
77      <method-group name="waiting">
78        <method name="wait">
79          <template>
80            <template-type-parameter name="ScopedLock"/>
81          </template>
82
83          <type>void</type>
84
85          <parameter name="lock">
86            <paramtype>ScopedLock&amp;</paramtype>
87          </parameter>
88
89          <requires><simpara><code>ScopedLock</code> meets the <link
90                linkend="threads.concepts.ScopedLock">ScopedLock</link>
91              requirements.</simpara></requires>
92          <effects><simpara>Releases the lock on the <link
93                linkend="threads.concepts.mutexes">mutex object</link>
94              associated with <code>lock</code>, blocks the current thread of execution
95              until readied by a call to <code>this->notify_one()</code>
96              or<code> this->notify_all()</code>, and then reacquires the
97              lock.</simpara></effects>
98          <throws><simpara><classname>lock_error</classname> if
99              <code>!lock.locked()</code></simpara></throws>
100        </method>
101
102        <method name="wait">
103          <template>
104            <template-type-parameter name="ScopedLock"/>
105            <template-type-parameter name="Pred"/>
106          </template>
107
108          <type>void</type>
109
110          <parameter name="lock">
111            <paramtype>ScopedLock&amp;</paramtype>
112          </parameter>
113
114          <parameter name="pred">
115            <paramtype>Pred</paramtype>
116          </parameter>
117
118          <requires><simpara><code>ScopedLock</code> meets the <link
119                linkend="threads.concepts.ScopedLock">ScopedLock</link>
120              requirements and the return from <code>pred()</code> is
121              convertible to <code>bool</code>.</simpara></requires>
122          <effects><simpara>As if: <code>while (!pred())
123                wait(lock)</code></simpara></effects>
124          <throws><simpara><classname>lock_error</classname> if
125              <code>!lock.locked()</code></simpara></throws>
126        </method>
127
128        <method name="timed_wait">
129          <template>
130            <template-type-parameter name="ScopedLock"/>
131          </template>
132
133          <type>bool</type>
134
135          <parameter name="lock">
136            <paramtype>ScopedLock&amp;</paramtype>
137          </parameter>
138
139          <parameter name="xt">
140            <paramtype>const <classname>boost::xtime</classname>&amp;</paramtype>
141          </parameter>
142
143          <requires><simpara><code>ScopedLock</code> meets the <link
144                linkend="threads.concepts.ScopedLock">ScopedLock</link>
145              requirements.</simpara></requires>
146          <effects><simpara>Releases the lock on the <link
147                linkend="threads.concepts.mutexes">mutex object</link>
148              associated with <code>lock</code>, blocks the current thread of execution
149              until readied by a call to <code>this->notify_one()</code>
150              or<code> this->notify_all()</code>, or until time <code>xt</code> 
151              is reached, and then reacquires the lock.</simpara></effects>
152          <returns><simpara><code>false</code> if time <code>xt</code> is reached,
153              otherwise <code>true</code>.</simpara></returns>
154          <throws><simpara><classname>lock_error</classname> if
155              <code>!lock.locked()</code></simpara></throws>
156        </method>
157
158        <method name="timed_wait">
159          <template>
160            <template-type-parameter name="ScopedLock"/>
161            <template-type-parameter name="Pred"/>
162          </template>
163
164          <type>bool</type>
165
166          <parameter name="lock">
167            <paramtype>ScopedLock&amp;</paramtype>
168          </parameter>
169
170          <parameter name="pred">
171            <paramtype>Pred</paramtype>
172          </parameter>
173
174          <requires><simpara><code>ScopedLock</code> meets the <link
175                linkend="threads.concepts.ScopedLock">ScopedLock</link>
176              requirements and the return from <code>pred()</code> is
177              convertible to <code>bool</code>.</simpara></requires>
178          <effects><simpara>As if: <code>while (!pred()) { if (!timed_wait(lock,
179                xt)) return false; } return true;</code></simpara></effects>
180          <returns><simpara><code>false</code> if <code>xt</code> is reached,
181              otherwise <code>true</code>.</simpara></returns>
182          <throws><simpara><classname>lock_error</classname> if
183              <code>!lock.locked()</code></simpara></throws>
184        </method>
185      </method-group>
186    </class>
187  </namespace>
188</header>
Note: See TracBrowser for help on using the repository browser.