Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example threads/waitconditions
++ \examplecategory {Data Processing & I/O}
++ \title Producer and Consumer using Wait Conditions
++ \ingroup qtconcurrent-mtexamples
++ \ingroup corelib_examples
++
++ \brief The Producer and Consumer using Wait Conditions example shows
++ how to use QWaitCondition and QMutex to control access to a circular
++ buffer shared by a producer thread and a consumer thread.
++
++ The producer writes data to the buffer until it reaches the end
++ of the buffer, at which point it restarts from the beginning,
++ overwriting existing data. The consumer thread reads the data as
++ it is produced and writes it to standard error.
++
++ Wait conditions make it possible to have a higher level of
++ concurrency than what is possible with mutexes alone. If accesses
++ to the buffer were simply guarded by a QMutex, the consumer
++ thread couldn't access the buffer at the same time as the
++ producer thread. Yet, there is no harm in having both threads
++ working on \e{different parts} of the buffer at the same time.
++
++ The example comprises two classes: \c Producer and \c Consumer.
++ Both inherit from QThread. The circular buffer used for
++ communicating between these two classes and the synchronization
++ tools that protect it are global variables.
++
++ An alternative to using QWaitCondition and QMutex to solve the
++ producer-consumer problem is to use QSemaphore. This is what the
++ \l{Producer and Consumer using Semaphores} example does.
++
++ \section1 Global Variables
++
++ Let's start by reviewing the circular buffer and the associated
++ synchronization tools:
++
++ \snippet threads/waitconditions/waitconditions.cpp 0
++
++ \c DataSize is the amount of data that the producer will generate.
++ To keep the example as simple as possible, we make it a constant.
++ \c BufferSize is the size of the circular buffer. It is less than
++ \c DataSize, meaning that at some point the producer will reach
++ the end of the buffer and restart from the beginning.
++
++ To synchronize the producer and the consumer, we need two wait
++ conditions and one mutex. The \c bufferNotEmpty condition is
++ signalled when the producer has generated some data, telling the
++ consumer that it can start reading it. The \c bufferNotFull
++ condition is signalled when the consumer has read some data,
++ telling the producer that it can generate more. The \c numUsedBytes
++ is the number of bytes in the buffer that contain data.
++
++ Together, the wait conditions, the mutex, and the \c numUsedBytes
++ counter ensure that the producer is never more than \c BufferSize
++ bytes ahead of the consumer, and that the consumer never reads
++ data that the producer hasn't generated yet.
++
++ \section1 Producer Class
++
++ Let's review the code for the \c Producer class:
++
++ \snippet threads/waitconditions/waitconditions.cpp 1
++ \snippet threads/waitconditions/waitconditions.cpp 2
++
++ The producer generates \c DataSize bytes of data. Before it
++ writes a byte to the circular buffer, it must first check whether
++ the buffer is full (i.e., \c numUsedBytes equals \c BufferSize).
++ If the buffer is full, the thread waits on the \c bufferNotFull
++ condition.
++
++ At the end, the producer increments \c numUsedBytes and signalls
++ that the condition \c bufferNotEmpty is true, since \c
++ numUsedBytes is necessarily greater than 0.
++
++ We guard all accesses to the \c numUsedBytes variable with a
++ mutex. In addition, the QWaitCondition::wait() function accepts a
++ mutex as its argument. This mutex is unlocked before the thread
++ is put to sleep and locked when the thread wakes up. Furthermore,
++ the transition from the locked state to the wait state is atomic,
++ to prevent race conditions from occurring.
++
++ \section1 Consumer Class
++
++ Let's turn to the \c Consumer class:
++
++ \snippet threads/waitconditions/waitconditions.cpp 3
++ \snippet threads/waitconditions/waitconditions.cpp 4
++
++ The code is very similar to the producer. Before we read the
++ byte, we check whether the buffer is empty (\c numUsedBytes is 0)
++ instead of whether it's full and wait on the \c bufferNotEmpty
++ condition if it's empty. After we've read the byte, we decrement
++ \c numUsedBytes (instead of incrementing it), and we signal the
++ \c bufferNotFull condition (instead of the \c bufferNotEmpty
++ condition).
++
++ \section1 The main() Function
++
++ In \c main(), we create the two threads and call QThread::wait()
++ to ensure that both threads get time to finish before we exit:
++
++ \snippet threads/waitconditions/waitconditions.cpp 5
++ \snippet threads/waitconditions/waitconditions.cpp 6
++
++ So what happens when we run the program? Initially, the producer
++ thread is the only one that can do anything; the consumer is
++ blocked waiting for the \c bufferNotEmpty condition to be
++ signalled (\c numUsedBytes is 0). Once the producer has put one
++ byte in the buffer, \c numUsedBytes is strictly greater than 0, and the
++ \c bufferNotEmpty condition is signalled. At that point, two
++ things can happen: Either the consumer thread takes over and
++ reads that byte, or the producer gets to produce a second byte.
++
++ The producer-consumer model presented in this example makes it
++ possible to write highly concurrent multithreaded applications.
++ On a multiprocessor machine, the program is potentially up to
++ twice as fast as the equivalent mutex-based program, since the
++ two threads can be active at the same time on different parts of
++ the buffer.
++
++ Be aware though that these benefits aren't always realized.
++ Locking and unlocking a QMutex has a cost. In practice, it would
++ probably be worthwhile to divide the buffer into chunks and to
++ operate on chunks instead of individual bytes. The buffer size is
++ also a parameter that must be selected carefully, based on
++ experimentation.
++ */