src/corelib/thread/qwaitcondition.qdoc

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