Semaphores Example

Files:

Description

The Semaphores example shows how to use QSemaphore 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 screen.

Semaphores make it possible to have a higher level of concurrency than mutexes. If accesses to the buffer were 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 different parts of the buffer at the same time.

The example comprises two classes: Producer and Consumer. Both inherit from QThread. The circular buffer used for communicating between these two classes and the semaphores that protect it are global variables.

An alternative to using QSemaphore to solve the producer-consumer problem is to use QWaitCondition and QMutex. This is what the Wait Conditions example does.

Global Variables

Let's start by reviewing the circular buffer and the associated semaphores:

    // The total number of bytes that will be produced and consumed
    static const int DataSize = 100000;

    // The size of the buffer that is used to deliver data from the producer to the consumer
    static const int BufferSize = 1700;

    // The buffer that is used to deliver data from the producer to the consumer
    static char buffer[BufferSize];

    // The two semaphores that are used to synchronize the access between producer and consumer to the shared buffer
    static QSemaphore freeBytes(BufferSize);
    static QSemaphore usedBytes;

DataSize is the amout of data that the producer will generate. To keep the example as simple as possible, we make it a constant. BufferSize is the size of the circular buffer. It is less than 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 semaphores. The freeBytes semaphore controls the "free" area of the buffer (the area that the producer hasn't filled with data yet or that the consumer has already read). The usedBytes semaphore controls the "used" area of the buffer (the area that the producer has filled but that the consumer hasn't read yet).

Together, the semaphores ensure that the producer is never more than BufferSize bytes ahead of the consumer, and that the consumer never reads data that the producer hasn't generated yet.

The freeBytes semaphore is initialized with BufferSize, because initially the entire buffer is empty. The usedBytes semaphore is initialized to 0 (the default value if none is specified).

Producer Class

Let's review the code for the Producer class:

    /**
     * The Producer fills the shared buffer with data in a separated worker thread.
     */
    class Producer : public QThread
    {
    public:
        void run()
        {
            // This code is executed in the worker thread

            // Initialize the random number generator
            qsrand(QTime(0, 0, 0).secsTo(QTime::currentTime()));

            for (int i = 0; i < DataSize; ++i) {
                // Decrement the 'counter' of free bytes. This will block this thread if no free bytes are available
                freeBytes.acquire();

                // Write a random character to the buffer
                buffer[i % BufferSize] = "ACGT"[(int) qrand() % 4];

                // Increament the 'counter' of used bytes. This will unblock the Consumer if it was waiting for reading new data
                usedBytes.release();
            }
        }
    };

The producer generates DataSize bytes of data. Before it writes a byte to the circular buffer, it must acquire a "free" byte using the freeBytes semaphore. The QSemaphore::acquire() call might block if the consumer hasn't kept up the pace with the producer.

At the end, the producer releases a byte using the usedBytes semaphore. The "free" byte has successfully been transformed into a "used" byte, ready to be read by the consumer.

Consumer Class

Let's now turn to the Consumer class:

    /**
     * The Consumer reads the data from the shared buffer in a separated worker thread and
     * publishes the read data to the UI.
     */
    class Consumer : public QThread
    {
        Q_OBJECT

    public:
        void run()
        {
            // This code is executed in the worker thread

            for (int i = 0; i < DataSize; ++i) {
                // Decrement the 'counter' of used bytes. This will block this thread if no used bytes are available
                usedBytes.acquire();

                // Read out one byte from the shared buffer
                const QString text(buffer[i % BufferSize]);

                // Increment the 'counter' of free bytes. This will unblock the Producer if it was waiting for writing new data
                freeBytes.release();

                // Publish the result to the UI
                emit stringConsumed(text);
            }

            // Tell the UI that we have transferred all data
            emit stringConsumed("\n\nFinished");
        }

    Q_SIGNALS:
        void stringConsumed(const QString &text);
    };

The code is very similar to the producer, except that this time we acquire a "used" byte and release a "free" byte, instead of the opposite.

The main() Function

    /**
     * This sample application shows how to solve the producer-consumer problem (http://en.wikipedia.org/wiki/Producer-consumer_problem)
     * with semaphores under Qt.
     */
    Q_DECL_EXPORT int main(int argc, char **argv)
    {
        Application app(argc, argv);

        // Create the producer and consumer objects
        Producer producer;
        Consumer consumer;

        // Create the TextBuffer object
        TextBuffer textBuffer;

        // Append the new data to the TextBuffer whenever the Consumer has consumed some data
        QObject::connect(&consumer, SIGNAL(stringConsumed(const QString&)),
                         &textBuffer, SLOT(appendText(const QString&)), Qt::BlockingQueuedConnection);

        // Load the UI description from main.qml
        QmlDocument *qml = QmlDocument::create("asset:///main.qml");

        // Make the TextBuffer object available to the UI as context property
        qml->setContextProperty("_textBuffer", &textBuffer);

        // Create the application scene
        AbstractPane *appPage = qml->createRootObject<AbstractPane>();
        Application::instance()->setScene(appPage);

        // Start the producer and consumer thread
        producer.start();
        consumer.start();

        return Application::exec();
    }

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 usedBytes semaphore to be released (its initial available() count is 0). Once the producer has put one byte in the buffer, freeBytes.available() is BufferSize - 1 and usedBytes.available() is 1. At that point, two things can happen: Either the consumer thread takes over and reads that byte, or the consumer 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. Acquiring and releasing a QSemaphore 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.

To visualize the result, the data the Consumer processes is also appended to a TextBuffer, which is exported to QML and displayed there.

Contents