source: trunk/doc/html/qwaitcondition.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 8.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/tools/qwaitcondition_unix.cpp:57 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QWaitCondition Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QWaitCondition Class Reference</h1>
33
34<p>The QWaitCondition class allows waiting/waking for conditions between threads.
35<a href="#details">More...</a>
36<p>All the functions in this class are <a href="threads.html#threadsafe">thread-safe</a> when Qt is built with thread support.</p>
37<p><tt>#include &lt;<a href="qwaitcondition-h.html">qwaitcondition.h</a>&gt;</tt>
38<p><a href="qwaitcondition-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QWaitCondition"><b>QWaitCondition</b></a> ()</li>
42<li class=fn>virtual <a href="#~QWaitCondition"><b>~QWaitCondition</b></a> ()</li>
43<li class=fn>bool <a href="#wait"><b>wait</b></a> ( unsigned&nbsp;long&nbsp;time = ULONG_MAX )</li>
44<li class=fn>bool <a href="#wait-2"><b>wait</b></a> ( QMutex&nbsp;*&nbsp;mutex, unsigned&nbsp;long&nbsp;time = ULONG_MAX )</li>
45<li class=fn>void <a href="#wakeOne"><b>wakeOne</b></a> ()</li>
46<li class=fn>void <a href="#wakeAll"><b>wakeAll</b></a> ()</li>
47</ul>
48<hr><a name="details"></a><h2>Detailed Description</h2>
49
50
51
52The QWaitCondition class allows waiting/waking for conditions between threads.
53<p>
54
55<p> QWaitConditions allow a thread to tell other threads that some
56sort of condition has been met; one or many threads can block
57waiting for a QWaitCondition to set a condition with <a href="#wakeOne">wakeOne</a>() or
58<a href="#wakeAll">wakeAll</a>(). Use wakeOne() to wake one randomly selected event or
59wakeAll() to wake them all. For example, say we have three tasks
60that should be performed every time the user presses a key; each
61task could be split into a thread, each of which would have a
62run() body like this:
63<p> <pre>
64 QWaitCondition key_pressed;
65
66 for (;;) {
67 key_pressed.<a href="#wait">wait</a>(); // This is a QWaitCondition global variable
68 // Key was pressed, do something interesting
69 do_something();
70 }
71 </pre>
72
73<p> A fourth thread would read key presses and wake the other three
74threads up every time it receives one, like this:
75<p> <pre>
76 QWaitCondition key_pressed;
77
78 for (;;) {
79 getchar();
80 // Causes any thread in key_pressed.<a href="#wait">wait</a>() to return from
81 // that method and continue processing
82 key_pressed.<a href="#wakeAll">wakeAll</a>();
83 }
84 </pre>
85
86<p> Note that the order the three threads are woken up in is
87undefined, and that if some or all of the threads are still in
88do_something() when the key is pressed, they won't be woken up
89(since they're not waiting on the condition variable) and so the
90task will not be performed for that key press. This can be
91avoided by, for example, doing something like this:
92<p> <pre>
93 <a href="qmutex.html">QMutex</a> mymutex;
94 QWaitCondition key_pressed;
95 int mycount=0;
96
97 // Worker thread code
98 for (;;) {
99 key_pressed.<a href="#wait">wait</a>(); // This is a QWaitCondition global variable
100 mymutex.<a href="qmutex.html#lock">lock</a>();
101 mycount++;
102 mymutex.<a href="qmutex.html#unlock">unlock</a>();
103 do_something();
104 mymutex.<a href="qmutex.html#lock">lock</a>();
105 mycount--;
106 mymutex.<a href="qmutex.html#unlock">unlock</a>();
107 }
108
109 // Key reading thread code
110 for (;;) {
111 getchar();
112 mymutex.<a href="qmutex.html#lock">lock</a>();
113 // Sleep until there are no busy worker threads
114 while( mycount &gt; 0 ) {
115 mymutex.<a href="qmutex.html#unlock">unlock</a>();
116 sleep( 1 );
117 mymutex.<a href="qmutex.html#lock">lock</a>();
118 }
119 mymutex.<a href="qmutex.html#unlock">unlock</a>();
120 key_pressed.<a href="#wakeAll">wakeAll</a>();
121 }
122 </pre>
123
124<p> The mutexes are necessary because the results of two threads
125attempting to change the value of the same variable simultaneously
126are unpredictable.
127<p>See also <a href="environment.html">Environment Classes</a> and <a href="thread.html">Threading</a>.
128
129<hr><h2>Member Function Documentation</h2>
130<h3 class=fn><a name="QWaitCondition"></a>QWaitCondition::QWaitCondition ()
131</h3>
132Constructs a new event signalling, i.e. wait condition, object.
133
134<h3 class=fn><a name="~QWaitCondition"></a>QWaitCondition::~QWaitCondition ()<tt> [virtual]</tt>
135</h3>
136Deletes the event signalling, i.e. wait condition, object.
137
138<h3 class=fn>bool <a name="wait"></a>QWaitCondition::wait ( unsigned&nbsp;long&nbsp;time = ULONG_MAX )
139</h3>
140Wait on the thread event object. The thread calling this will
141block until either of these conditions is met:
142<ul>
143<li> Another thread signals it using <a href="#wakeOne">wakeOne</a>() or <a href="#wakeAll">wakeAll</a>(). This
144function will return TRUE in this case.
145<li> <em>time</em> milliseconds has elapsed. If <em>time</em> is ULONG_MAX (the
146default), then the wait will never timeout (the event must be
147signalled). This function will return FALSE if the wait timed
148out.
149</ul>
150<p> <p>See also <a href="#wakeOne">wakeOne</a>() and <a href="#wakeAll">wakeAll</a>().
151
152<h3 class=fn>bool <a name="wait-2"></a>QWaitCondition::wait ( <a href="qmutex.html">QMutex</a>&nbsp;*&nbsp;mutex, unsigned&nbsp;long&nbsp;time = ULONG_MAX )
153</h3>
154This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
155<p> Release the locked <em>mutex</em> and wait on the thread event object.
156The <em>mutex</em> must be initially locked by the calling thread. If <em>mutex</em> is not in a locked state, this function returns immediately.
157If <em>mutex</em> is a recursive mutex, this function returns
158immediately. The <em>mutex</em> will be unlocked, and the calling thread
159will block until either of these conditions is met:
160<ul>
161<li> Another thread signals it using <a href="#wakeOne">wakeOne</a>() or <a href="#wakeAll">wakeAll</a>(). This
162function will return TRUE in this case.
163<li> <em>time</em> milliseconds has elapsed. If <em>time</em> is ULONG_MAX (the
164default), then the wait will never timeout (the event must be
165signalled). This function will return FALSE if the wait timed
166out.
167</ul>
168<p> The mutex will be returned to the same locked state. This function
169is provided to allow the atomic transition from the locked state
170to the wait state.
171<p> <p>See also <a href="#wakeOne">wakeOne</a>() and <a href="#wakeAll">wakeAll</a>().
172
173<h3 class=fn>void <a name="wakeAll"></a>QWaitCondition::wakeAll ()
174</h3>
175This wakes all threads waiting on the QWaitCondition. The order in
176which the threads are woken up depends on the operating system's
177scheduling policies, and cannot be controlled or predicted.
178<p> <p>See also <a href="#wakeOne">wakeOne</a>().
179
180<h3 class=fn>void <a name="wakeOne"></a>QWaitCondition::wakeOne ()
181</h3>
182This wakes one thread waiting on the QWaitCondition. The thread
183that is woken up depends on the operating system's scheduling
184policies, and cannot be controlled or predicted.
185<p> <p>See also <a href="#wakeAll">wakeAll</a>().
186
187<!-- eof -->
188<hr><p>
189This file is part of the <a href="index.html">Qt toolkit</a>.
190Copyright &copy; 1995-2007
191<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
192<table width=100% cellspacing=0 border=0><tr>
193<td>Copyright &copy; 2007
194<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
195<td align=right><div align=right>Qt 3.3.8</div>
196</table></div></address></body>
197</html>
Note: See TracBrowser for help on using the repository browser.