doc/src/examples/waitconditions.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example threads/waitconditions
  30     \title Wait Conditions Example
  31
  32     \brief The Wait Conditions example shows how to use QWaitCondition and
  33     QMutex to control access to a circular buffer shared by a
  34     producer thread and a consumer thread.
  35
  36     The producer writes data to the buffer until it reaches the end
  37     of the buffer, at which point it restarts from the beginning,
  38     overwriting existing data. The consumer thread reads the data as
  39     it is produced and writes it to standard error.
  40
  41     Wait conditions make it possible to have a higher level of
  42     concurrency than what is possible with mutexes alone. If accesses
  43     to the buffer were simply guarded by a QMutex, the consumer
  44     thread couldn't access the buffer at the same time as the
  45     producer thread. Yet, there is no harm in having both threads
  46     working on \e{different parts} of the buffer at the same time.
  47
  48     The example comprises two classes: \c Producer and \c Consumer.
  49     Both inherit from QThread. The circular buffer used for
  50     communicating between these two classes and the synchronization
  51     tools that protect it are global variables.
  52
  53     An alternative to using QWaitCondition and QMutex to solve the
  54     producer-consumer problem is to use QSemaphore. This is what the
  55     \l{threads/semaphores}{Semaphores} example does.
  56
  57     \section1 Global Variables
  58
  59     Let's start by reviewing the circular buffer and the associated
  60     synchronization tools:
  61
  62     \snippet examples/threads/waitconditions/waitconditions.cpp 0
  63
  64     \c DataSize is the amount of data that the producer will generate.
  65     To keep the example as simple as possible, we make it a constant.
  66     \c BufferSize is the size of the circular buffer. It is less than
  67     \c DataSize, meaning that at some point the producer will reach
  68     the end of the buffer and restart from the beginning.
  69
  70     To synchronize the producer and the consumer, we need two wait
  71     conditions and one mutex. The \c bufferNotEmpty condition is
  72     signalled when the producer has generated some data, telling the
  73     consumer that it can start reading it. The \c bufferNotFull
  74     condition is signalled when the consumer has read some data,
  75     telling the producer that it can generate more. The \c numUsedBytes
  76     is the number of bytes in the buffer that contain data.
  77
  78     Together, the wait conditions, the mutex, and the \c numUsedBytes
  79     counter ensure that the producer is never more than \c BufferSize
  80     bytes ahead of the consumer, and that the consumer never reads
  81     data that the producer hasn't generated yet.
  82
  83     \section1 Producer Class
  84
  85     Let's review the code for the \c Producer class:
  86
  87     \snippet examples/threads/waitconditions/waitconditions.cpp 1
  88     \snippet examples/threads/waitconditions/waitconditions.cpp 2
  89
  90     The producer generates \c DataSize bytes of data. Before it
  91     writes a byte to the circular buffer, it must first check whether
  92     the buffer is full (i.e., \c numUsedBytes equals \c BufferSize).
  93     If the buffer is full, the thread waits on the \c bufferNotFull
  94     condition.
  95
  96     At the end, the producer increments \c numUsedBytes and signalls
  97     that the condition \c bufferNotEmpty is true, since \c
  98     numUsedBytes is necessarily greater than 0.
  99
 100     We guard all accesses to the \c numUsedBytes variable with a
 101     mutex. In addition, the QWaitCondition::wait() function accepts a
 102     mutex as its argument. This mutex is unlocked before the thread
 103     is put to sleep and locked when the thread wakes up. Furthermore,
 104     the transition from the locked state to the wait state is atomic,
 105     to prevent race conditions from occurring.
 106
 107     \section1 Consumer Class
 108
 109     Let's turn to the \c Consumer class:
 110
 111     \snippet examples/threads/waitconditions/waitconditions.cpp 3
 112     \snippet examples/threads/waitconditions/waitconditions.cpp 4
 113
 114     The code is very similar to the producer. Before we read the
 115     byte, we check whether the buffer is empty (\c numUsedBytes is 0)
 116     instead of whether it's full and wait on the \c bufferNotEmpty
 117     condition if it's empty. After we've read the byte, we decrement
 118     \c numUsedBytes (instead of incrementing it), and we signal the
 119     \c bufferNotFull condition (instead of the \c bufferNotEmpty
 120     condition).
 121
 122     \section1 The main() Function
 123
 124     In \c main(), we create the two threads and call QThread::wait()
 125     to ensure that both threads get time to finish before we exit:
 126
 127     \snippet examples/threads/waitconditions/waitconditions.cpp 5
 128     \snippet examples/threads/waitconditions/waitconditions.cpp 6
 129
 130     So what happens when we run the program? Initially, the producer
 131     thread is the only one that can do anything; the consumer is
 132     blocked waiting for the \c bufferNotEmpty condition to be
 133     signalled (\c numUsedBytes is 0). Once the producer has put one
 134     byte in the buffer, \c numUsedBytes is \c BufferSize - 1 and the
 135     \c bufferNotEmpty condition is signalled. At that point, two
 136     things can happen: Either the consumer thread takes over and
 137     reads that byte, or the consumer gets to produce a second byte.
 138
 139     The producer-consumer model presented in this example makes it
 140     possible to write highly concurrent multithreaded applications.
 141     On a multiprocessor machine, the program is potentially up to
 142     twice as fast as the equivalent mutex-based program, since the
 143     two threads can be active at the same time on different parts of
 144     the buffer.
 145
 146     Be aware though that these benefits aren't always realized.
 147     Locking and unlocking a QMutex has a cost. In practice, it would
 148     probably be worthwhile to divide the buffer into chunks and to
 149     operate on chunks instead of individual bytes. The buffer size is
 150     also a parameter that must be selected carefully, based on
 151     experimentation.
 152 */