1QWaitCondition(3qt) QWaitCondition(3qt)
2
6 QWaitCondition - Allows waiting/waking for conditions between threads
7
9 All the functions in this class are thread-safe when Qt is built with
10 thread support.</p>
11 #include <qwaitcondition.h>
13 Public Members
15 QWaitCondition ()
16 virtual ~QWaitCondition ()
17 bool wait ( unsigned long time = ULONG_MAX )
18 bool wait ( QMutex * mutex, unsigned long time = ULONG_MAX )
19 void wakeOne ()
20 void wakeAll ()
21
23 The QWaitCondition class allows waiting/waking for conditions between
24 threads.
25 QWaitConditions allow a thread to tell other threads that some sort of
27 condition has been met; one or many threads can block waiting for a
28 QWaitCondition to set a condition with wakeOne() or wakeAll(). Use
29 wakeOne() to wake one randomly selected event or wakeAll() to wake them
30 all. For example, say we have three tasks that should be performed
31 every time the user presses a key; each task could be split into a
32 thread, each of which would have a run() body like this:
33 QWaitCondition key_pressed;
35 for (;;) {
36 key_pressed.wait(); // This is a QWaitCondition global variable
37 // Key was pressed, do something interesting
38 do_something();
39 }
40 A fourth thread would read key presses and wake the other three threads
42 up every time it receives one, like this:
43 QWaitCondition key_pressed;
45 for (;;) {
46 getchar();
47 // Causes any thread in key_pressed.wait() to return from
48 // that method and continue processing
49 key_pressed.wakeAll();
50 }
51 Note that the order the three threads are woken up in is undefined, and
53 that if some or all of the threads are still in do_something() when the
54 key is pressed, they won't be woken up (since they're not waiting on
55 the condition variable) and so the task will not be performed for that
56 key press. This can be avoided by, for example, doing something like
57 this:
58 QMutex mymutex;
60 QWaitCondition key_pressed;
61 int mycount=0;
62 // Worker thread code
63 for (;;) {
64 key_pressed.wait(); // This is a QWaitCondition global variable
65 mymutex.lock();
66 mycount++;
67 mymutex.unlock();
68 do_something();
69 mymutex.lock();
70 mycount--;
71 mymutex.unlock();
72 }
73 // Key reading thread code
74 for (;;) {
75 getchar();
76 mymutex.lock();
77 // Sleep until there are no busy worker threads
78 while( mycount > 0 ) {
79 mymutex.unlock();
80 sleep( 1 );
81 mymutex.lock();
82 }
83 mymutex.unlock();
84 key_pressed.wakeAll();
85 }
86 The mutexes are necessary because the results of two threads attempting
88 to change the value of the same variable simultaneously are
89 unpredictable.
90 See also Environment Classes and Threading.
92
95 Constructs a new event signalling, i.e. wait condition, object.
96
98 Deletes the event signalling, i.e. wait condition, object.
99
101 Wait on the thread event object. The thread calling this will block
102 until either of these conditions is met:
103 Another thread signals it using wakeOne() or wakeAll(). This function
105 will return TRUE in this case.
106 time milliseconds has elapsed. If time is ULONG_MAX (the default), then
108 the wait will never timeout (the event must be signalled). This
109 function will return FALSE if the wait timed out.
110 See also wakeOne() and wakeAll().
112
114 This is an overloaded member function, provided for convenience. It
115 behaves essentially like the above function.
116 Release the locked mutex and wait on the thread event object. The mutex
118 must be initially locked by the calling thread. If mutex is not in a
119 locked state, this function returns immediately. If mutex is a
120 recursive mutex, this function returns immediately. The mutex will be
121 unlocked, and the calling thread will block until either of these
122 conditions is met:
123 Another thread signals it using wakeOne() or wakeAll(). This function
125 will return TRUE in this case.
126 time milliseconds has elapsed. If time is ULONG_MAX (the default), then
128 the wait will never timeout (the event must be signalled). This
129 function will return FALSE if the wait timed out.
130 The mutex will be returned to the same locked state. This function is
132 provided to allow the atomic transition from the locked state to the
133 wait state.
134 See also wakeOne() and wakeAll().
136
138 This wakes all threads waiting on the QWaitCondition. The order in
139 which the threads are woken up depends on the operating system's
140 scheduling policies, and cannot be controlled or predicted.
141 See also wakeOne().
143
145 This wakes one thread waiting on the QWaitCondition. The thread that is
146 woken up depends on the operating system's scheduling policies, and
147 cannot be controlled or predicted.
148 See also wakeAll().
150
153 http://doc.trolltech.com/qwaitcondition.html
154 http://www.trolltech.com/faq/tech.html
155
157 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
158 license file included in the distribution for a complete license
159 statement.
160
162 Generated automatically from the source code.
163
165 If you find a bug in Qt, please report it as described in
166 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
167 help you. Thank you.
168 The definitive Qt documentation is provided in HTML format; it is
170 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
171 web browser. This man page is provided as a convenience for those users
172 who prefer man pages, although this format is not officially supported
173 by Trolltech.
174 If you find errors in this manual page, please report them to qt-
176 bugs@trolltech.com. Please include the name of the manual page
177 (qwaitcondition.3qt) and the Qt version (3.3.8).
178Trolltech AS 2 February 2007 QWaitCondition(3qt)