1QWaitCondition(3qt)                                        QWaitCondition(3qt)
2
3
4

NAME

6       QWaitCondition - Allows waiting/waking for conditions between threads
7

SYNOPSIS

9       All the functions in this class are thread-safe when Qt is built with
10       thread support.</p>
11
12       #include <qwaitcondition.h>
13
14   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

DESCRIPTION

23       The QWaitCondition class allows waiting/waking for conditions between
24       threads.
25
26       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
34           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
41       A fourth thread would read key presses and wake the other three threads
42       up every time it receives one, like this:
43
44           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
52       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
59           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
87       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
91       See also Environment Classes and Threading.
92

MEMBER FUNCTION DOCUMENTATION

QWaitCondition::QWaitCondition ()

95       Constructs a new event signalling, i.e. wait condition, object.
96

QWaitCondition::~QWaitCondition () [virtual]

98       Deletes the event signalling, i.e. wait condition, object.
99

bool QWaitCondition::wait ( unsigned long time = ULONG_MAX )

101       Wait on the thread event object. The thread calling this will block
102       until either of these conditions is met:
103
104       Another thread signals it using wakeOne() or wakeAll(). This function
105       will return TRUE in this case.
106
107       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
111       See also wakeOne() and wakeAll().
112

bool QWaitCondition::wait ( QMutex * mutex, unsigned long time = ULONG_MAX )

114       This is an overloaded member function, provided for convenience. It
115       behaves essentially like the above function.
116
117       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
124       Another thread signals it using wakeOne() or wakeAll(). This function
125       will return TRUE in this case.
126
127       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
131       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
135       See also wakeOne() and wakeAll().
136

void QWaitCondition::wakeAll ()

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
142       See also wakeOne().
143

void QWaitCondition::wakeOne ()

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
149       See also wakeAll().
150
151

SEE ALSO

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

AUTHOR

162       Generated automatically from the source code.
163

BUGS

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
169       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
175       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).
178
179
180
181Trolltech AS                    2 February 2007            QWaitCondition(3qt)
Impressum