← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/corelib/thread/qwaitcondition.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/thread/qwaitcondition.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 
4
** All rights reserved.
 
5
** Contact: Nokia Corporation (qt-info@nokia.com)
 
6
**
 
7
** This file is part of the documentation of the Qt Toolkit.
 
8
**
 
9
** $QT_BEGIN_LICENSE:LGPL$
 
10
** No Commercial Usage
 
11
** This file contains pre-release code and may not be distributed.
 
12
** You may use this file in accordance with the terms and conditions
 
13
** contained in the Technology Preview License Agreement accompanying
 
14
** this package.
 
15
**
 
16
** GNU Lesser General Public License Usage
 
17
** Alternatively, this file may be used under the terms of the GNU Lesser
 
18
** General Public License version 2.1 as published by the Free Software
 
19
** Foundation and appearing in the file LICENSE.LGPL included in the
 
20
** packaging of this file.  Please review the following information to
 
21
** ensure the GNU Lesser General Public License version 2.1 requirements
 
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
23
**
 
24
** In addition, as a special exception, Nokia gives you certain additional
 
25
** rights.  These rights are described in the Nokia Qt LGPL Exception
 
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
27
**
 
28
** If you have questions regarding the use of this file, please contact
 
29
** Nokia at qt-info@nokia.com.
 
30
**
 
31
**
 
32
**
 
33
**
 
34
**
 
35
**
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
/*!
 
43
    \class QWaitCondition
 
44
    \brief The QWaitCondition class provides a condition variable for
 
45
    synchronizing threads.
 
46
 
 
47
    \threadsafe
 
48
 
 
49
    \ingroup thread
 
50
 
 
51
    QWaitCondition allows a thread to tell other threads that some
 
52
    sort of condition has been met. One or many threads can block
 
53
    waiting for a QWaitCondition to set a condition with wakeOne() or
 
54
    wakeAll(). Use wakeOne() to wake one randomly selected condition or
 
55
    wakeAll() to wake them all.
 
56
 
 
57
    For example, let's suppose that we have three tasks that should
 
58
    be performed whenever the user presses a key. Each task could be
 
59
    split into a thread, each of which would have a
 
60
    \l{QThread::run()}{run()} body like this:
 
61
 
 
62
    \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0
 
63
 
 
64
    Here, the \c keyPressed variable is a global variable of type
 
65
    QWaitCondition.
 
66
 
 
67
    A fourth thread would read key presses and wake the other three
 
68
    threads up every time it receives one, like this:
 
69
 
 
70
    \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1
 
71
 
 
72
    The order in which the three threads are woken up is undefined.
 
73
    Also, if some of the threads are still in \c do_something() when
 
74
    the key is pressed, they won't be woken up (since they're not
 
75
    waiting on the condition variable) and so the task will not be
 
76
    performed for that key press. This issue can be solved using a
 
77
    counter and a QMutex to guard it. For example, here's the new
 
78
    code for the worker threads:
 
79
 
 
80
    \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2
 
81
 
 
82
    Here's the code for the fourth thread:
 
83
 
 
84
    \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3
 
85
 
 
86
    The mutex is necessary because the results of two threads
 
87
    attempting to change the value of the same variable
 
88
    simultaneously are unpredictable.
 
89
 
 
90
    Wait conditions are a powerful thread synchronization primitive.
 
91
    The \l{threads/waitconditions}{Wait Conditions} example shows how
 
92
    to use QWaitCondition as an alternative to QSemaphore for
 
93
    controlling access to a circular buffer shared by a producer
 
94
    thread and a consumer thread.
 
95
 
 
96
    \sa QMutex, QSemaphore, QThread, {Wait Conditions Example}
 
97
*/
 
98
 
 
99
/*!
 
100
    \fn QWaitCondition::QWaitCondition()
 
101
 
 
102
    Constructs a new wait condition object.
 
103
*/
 
104
 
 
105
/*!
 
106
    \fn QWaitCondition::~QWaitCondition()
 
107
 
 
108
    Destroys the wait condition object.
 
109
*/
 
110
 
 
111
/*!
 
112
    \fn void QWaitCondition::wakeOne()
 
113
 
 
114
    Wakes one thread waiting on the wait condition. The thread that
 
115
    is woken up depends on the operating system's scheduling
 
116
    policies, and cannot be controlled or predicted.
 
117
 
 
118
    If you want to wake up a specific thread, the solution is
 
119
    typically to use different wait conditions and have different
 
120
    threads wait on different conditions.
 
121
 
 
122
    \sa wakeAll()
 
123
*/
 
124
 
 
125
/*!
 
126
    \fn void QWaitCondition::wakeAll()
 
127
 
 
128
    Wakes all threads waiting on the wait condition. The order in
 
129
    which the threads are woken up depends on the operating system's
 
130
    scheduling policies and cannot be controlled or predicted.
 
131
 
 
132
    \sa wakeOne()
 
133
*/
 
134
 
 
135
/*!
 
136
    \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time)
 
137
 
 
138
    Releases the locked \a mutex and waits on the wait condition.  The
 
139
    \a mutex must be initially locked by the calling thread. If \a
 
140
    mutex is not in a locked state, this function returns
 
141
    immediately. If \a mutex is a recursive mutex, this function
 
142
    returns immediately. The \a mutex will be unlocked, and the
 
143
    calling thread will block until either of these conditions is met:
 
144
 
 
145
    \list
 
146
    \o Another thread signals it using wakeOne() or wakeAll(). This
 
147
       function will return true in this case.
 
148
    \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX
 
149
       (the default), then the wait will never timeout (the event
 
150
       must be signalled). This function will return false if the
 
151
       wait timed out.
 
152
    \endlist
 
153
 
 
154
    The mutex will be returned to the same locked state. This
 
155
    function is provided to allow the atomic transition from the
 
156
    locked state to the wait state.
 
157
 
 
158
    \sa wakeOne(), wakeAll()
 
159
*/
 
160
 
 
161
/*!
 
162
    \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time)
 
163
    \since 4.4
 
164
 
 
165
    Releases the locked \a readWriteLock and waits on the wait
 
166
    condition.  The \a readWriteLock must be initially locked by the
 
167
    calling thread. If \a readWriteLock is not in a locked state, this
 
168
    function returns immediately. The \a readWriteLock must not be
 
169
    locked recursively, otherwise this function will not release the
 
170
    lock properly. The \a readWriteLock will be unlocked, and the
 
171
    calling thread will block until either of these conditions is met:
 
172
 
 
173
    \list
 
174
    \o Another thread signals it using wakeOne() or wakeAll(). This
 
175
       function will return true in this case.
 
176
    \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX
 
177
       (the default), then the wait will never timeout (the event
 
178
       must be signalled). This function will return false if the
 
179
       wait timed out.
 
180
    \endlist
 
181
 
 
182
    The \a readWriteLock will be returned to the same locked
 
183
    state. This function is provided to allow the atomic transition
 
184
    from the locked state to the wait state.
 
185
 
 
186
    \sa wakeOne(), wakeAll()
 
187
*/