--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/corelib/thread/qwaitcondition.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,187 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class QWaitCondition
+ \brief The QWaitCondition class provides a condition variable for
+ synchronizing threads.
+
+ \threadsafe
+
+ \ingroup thread
+
+ QWaitCondition allows a thread to tell other threads that some
+ sort of condition has been met. One or many threads can block
+ waiting for a QWaitCondition to set a condition with wakeOne() or
+ wakeAll(). Use wakeOne() to wake one randomly selected condition or
+ wakeAll() to wake them all.
+
+ For example, let's suppose that we have three tasks that should
+ be performed whenever the user presses a key. Each task could be
+ split into a thread, each of which would have a
+ \l{QThread::run()}{run()} body like this:
+
+ \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0
+
+ Here, the \c keyPressed variable is a global variable of type
+ QWaitCondition.
+
+ A fourth thread would read key presses and wake the other three
+ threads up every time it receives one, like this:
+
+ \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1
+
+ The order in which the three threads are woken up is undefined.
+ Also, if some of the threads are still in \c do_something() when
+ the key is pressed, they won't be woken up (since they're not
+ waiting on the condition variable) and so the task will not be
+ performed for that key press. This issue can be solved using a
+ counter and a QMutex to guard it. For example, here's the new
+ code for the worker threads:
+
+ \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2
+
+ Here's the code for the fourth thread:
+
+ \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3
+
+ The mutex is necessary because the results of two threads
+ attempting to change the value of the same variable
+ simultaneously are unpredictable.
+
+ Wait conditions are a powerful thread synchronization primitive.
+ The \l{threads/waitconditions}{Wait Conditions} example shows how
+ to use QWaitCondition as an alternative to QSemaphore for
+ controlling access to a circular buffer shared by a producer
+ thread and a consumer thread.
+
+ \sa QMutex, QSemaphore, QThread, {Wait Conditions Example}
+*/
+
+/*!
+ \fn QWaitCondition::QWaitCondition()
+
+ Constructs a new wait condition object.
+*/
+
+/*!
+ \fn QWaitCondition::~QWaitCondition()
+
+ Destroys the wait condition object.
+*/
+
+/*!
+ \fn void QWaitCondition::wakeOne()
+
+ Wakes one thread waiting on the wait condition. The thread that
+ is woken up depends on the operating system's scheduling
+ policies, and cannot be controlled or predicted.
+
+ If you want to wake up a specific thread, the solution is
+ typically to use different wait conditions and have different
+ threads wait on different conditions.
+
+ \sa wakeAll()
+*/
+
+/*!
+ \fn void QWaitCondition::wakeAll()
+
+ Wakes all threads waiting on the wait condition. The order in
+ which the threads are woken up depends on the operating system's
+ scheduling policies and cannot be controlled or predicted.
+
+ \sa wakeOne()
+*/
+
+/*!
+ \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time)
+
+ Releases the locked \a mutex and waits on the wait condition. The
+ \a mutex must be initially locked by the calling thread. If \a
+ mutex is not in a locked state, this function returns
+ immediately. If \a mutex is a recursive mutex, this function
+ returns immediately. The \a mutex will be unlocked, and the
+ calling thread will block until either of these conditions is met:
+
+ \list
+ \o Another thread signals it using wakeOne() or wakeAll(). This
+ function will return true in this case.
+ \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX
+ (the default), then the wait will never timeout (the event
+ must be signalled). This function will return false if the
+ wait timed out.
+ \endlist
+
+ The mutex will be returned to the same locked state. This
+ function is provided to allow the atomic transition from the
+ locked state to the wait state.
+
+ \sa wakeOne(), wakeAll()
+*/
+
+/*!
+ \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time)
+ \since 4.4
+
+ Releases the locked \a readWriteLock and waits on the wait
+ condition. The \a readWriteLock must be initially locked by the
+ calling thread. If \a readWriteLock is not in a locked state, this
+ function returns immediately. The \a readWriteLock must not be
+ locked recursively, otherwise this function will not release the
+ lock properly. The \a readWriteLock will be unlocked, and the
+ calling thread will block until either of these conditions is met:
+
+ \list
+ \o Another thread signals it using wakeOne() or wakeAll(). This
+ function will return true in this case.
+ \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX
+ (the default), then the wait will never timeout (the event
+ must be signalled). This function will return false if the
+ wait timed out.
+ \endlist
+
+ The \a readWriteLock will be returned to the same locked
+ state. This function is provided to allow the atomic transition
+ from the locked state to the wait state.
+
+ \sa wakeOne(), wakeAll()
+*/