Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qwaitcondition.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \class QWaitCondition
6 \inmodule QtCore
7 \brief The QWaitCondition class provides a condition variable for
8 synchronizing threads.
9
10 \threadsafe
11
12 \ingroup thread
13
14 QWaitCondition allows a thread to tell other threads that some
15 sort of condition has been met. One or many threads can block
16 waiting for a QWaitCondition to set a condition with wakeOne() or
17 wakeAll(). Use wakeOne() to wake one randomly selected thread or
18 wakeAll() to wake them all.
19
20 For example, let's suppose that we have three tasks that should
21 be performed whenever the user presses a key. Each task could be
22 split into a thread, each of which would have a
23 \l{QThread::run()}{run()} body like this:
24
25 \snippet code/src_corelib_thread_qwaitcondition_unix.cpp 0
26
27 Here, the \c keyPressed variable is a global variable of type
28 QWaitCondition.
29
30 A fourth thread would read key presses and wake the other three
31 threads up every time it receives one, like this:
32
33 \snippet code/src_corelib_thread_qwaitcondition_unix.cpp 1
34
35 The order in which the three threads are woken up is undefined.
36 Also, if some of the threads are still in \c do_something() when
37 the key is pressed, they won't be woken up (since they're not
38 waiting on the condition variable) and so the task will not be
39 performed for that key press. This issue can be solved using a
40 counter and a QMutex to guard it. For example, here's the new
41 code for the worker threads:
42
43 \snippet code/src_corelib_thread_qwaitcondition_unix.cpp 2
44
45 Here's the code for the fourth thread:
46
47 \snippet code/src_corelib_thread_qwaitcondition_unix.cpp 3
48
49 The mutex is necessary because the results of two threads
50 attempting to change the value of the same variable
51 simultaneously are unpredictable.
52
53 Wait conditions are a powerful thread synchronization primitive.
54 The \l{Producer and Consumer using Wait Conditions} example
55 shows how to use QWaitCondition as an alternative to QSemaphore
56 for controlling access to a circular buffer shared by a producer
57 thread and a consumer thread.
58
59 \sa QMutex, QSemaphore, QThread, {Producer and Consumer using Wait Conditions}
60*/
61
62/*!
63 \fn QWaitCondition::QWaitCondition()
64
65 Constructs a new wait condition object.
66*/
67
68/*!
69 \fn QWaitCondition::~QWaitCondition()
70
71 Destroys the wait condition object.
72*/
73
74/*!
75 \fn void QWaitCondition::wakeOne()
76
77 Wakes one thread waiting on the wait condition. The thread that
78 is woken up depends on the operating system's scheduling
79 policies, and cannot be controlled or predicted.
80
81 If you want to wake up a specific thread, the solution is
82 typically to use different wait conditions and have different
83 threads wait on different conditions.
84
85 \sa wakeAll()
86*/
87
88/*!
89 \fn void QWaitCondition::wakeAll()
90
91 Wakes all threads waiting on the wait condition. The order in
92 which the threads are woken up depends on the operating system's
93 scheduling policies and cannot be controlled or predicted.
94
95 \sa wakeOne()
96*/
97
98/*!
99 \fn bool QWaitCondition::wait(QMutex *lockedMutex, unsigned long time)
100 \overload
101
102 Releases the \a lockedMutex and waits on the wait condition for \a time
103 milliseconds.
104*/
105/*!
106 \fn bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, unsigned long time)
107 \overload
108
109 Releases the \a lockedReadWriteLock and waits on the wait condition for \a
110 time milliseconds.
111*/
112
113/*!
114 \fn bool QWaitCondition::wait(QMutex *lockedMutex, QDeadlineTimer deadline)
115 \since 5.12
116
117 Releases the \a lockedMutex and waits on the wait condition. The
118 \a lockedMutex must be initially locked by the calling thread. If \a
119 lockedMutex is not in a locked state, the behavior is undefined. If
120 \a lockedMutex is a recursive mutex, this function
121 returns immediately. The \a lockedMutex will be unlocked, and the
122 calling thread will block until either of these conditions is met:
123
124 \list
125 \li Another thread signals it using wakeOne() or wakeAll(). This
126 function will return true in this case.
127 \li the deadline given by \a deadline is reached. If \a deadline is
128 \c QDeadlineTimer::Forever (the default), then the wait will never
129 timeout (the event must be signalled). This function will return
130 false if the wait timed out.
131 \endlist
132
133 The \a lockedMutex will be returned to the same locked state. This
134 function is provided to allow the atomic transition from the
135 locked state to the wait state.
136
137 \sa wakeOne(), wakeAll()
138*/
139
140/*!
141 \fn bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, QDeadlineTimer deadline)
142 \since 5.12
143
144 Releases the \a lockedReadWriteLock and waits on the wait
145 condition. The \a lockedReadWriteLock must be initially locked by the
146 calling thread. If \a lockedReadWriteLock is not in a locked state, this
147 function returns immediately. The \a lockedReadWriteLock must not be
148 locked recursively, otherwise this function will not release the
149 lock properly. The \a lockedReadWriteLock will be unlocked, and the
150 calling thread will block until either of these conditions is met:
151
152 \list
153 \li Another thread signals it using wakeOne() or wakeAll(). This
154 function will return true in this case.
155 \li the deadline given by \a deadline is reached. If \a deadline is
156 \c QDeadlineTimer::Forever (the default), then the wait will never
157 timeout (the event must be signalled). This function will return
158 false if the wait timed out.
159 \endlist
160
161 The \a lockedReadWriteLock will be returned to the same locked
162 state. This function is provided to allow the atomic transition
163 from the locked state to the wait state.
164
165 \sa wakeOne(), wakeAll()
166*/
167
168
169/*! \fn void QWaitCondition::notify_one()
170 \since 5.8
171
172 This function is provided for STL compatibility. It is equivalent
173 to wakeOne().
174*/
175
176/*! \fn void QWaitCondition::notify_all()
177 \since 5.8
178
179 This function is provided for STL compatibility. It is equivalent
180 to wakeAll().
181*/