HelW olorld! - Concurrent programming using the ThreadWeaver framework

Concurrent programming means creating applications that perform multiple operations at the same time. A common problem is that the user sees the application pause. A typical requirement is that an operation which may take an arbitrary amount of time because it is, for example, performing disk I/O, is scheduled for execution but immediately taken of the main thread of the application (the one that starts main()). To illustrate how this problem would be solved and to jump right into using ThreadWeaver, let’s simulate this problem by printing Hello World!¹ as the asynchronous payload:

#include <QtCore>
#include <ThreadWeaver/ThreadWeaver>

int main(int argc, char** argv)
{
    QCoreApplication app(argc, argv);
    using namespace ThreadWeaver;
    stream() << make_job( []() { qDebug() << "Hello World!"; } );
}

This short but complete program written in C++11 outputs the common greeting to the command line.² It does so, however, from a worker thread managed by the global ThreadWeaver queue. The header file ThreadWeaver/ThreadWeaver included in line 2 contains the essential declarations needed to use the most common ThreadWeaver operations. The components used in this examples are the global queue, a job and a queueing mechanism. The global queue is a singleton instance of the ThreadWeaver thread pool that is instantiated when it it first accessed after the application starts. A job represents “something” that should be executed asynchroneously. In this case, the thing to execute is a C++ lambda function that prints the welcome message. The queueing mechanism used here is a queue stream, an API inspired by the iostream family of classes. ThreadWeaver builds on top of Qt, and similar to most Qt applications requires a QCoreApplication (or one of it’s descendents) to exist throughout the lifetime of the application. Up to line 7, the program looks like any other Qt application.

To have the job lambda function called by one of the worker threads, a job is created that wraps it using the make_job(). It is then handed to the queue stream. The queue stream will submit the jobs for execution when the queuing command is completed, that is at the closing semicolon. Once the job is queued, one of the worker threads will automatically pick it up from the queue and execute it. ThreadWeaver::Job is the unit of execution handled by ThreadWeaver queues. Jobs are simple runnable types that perform one task, defined in their run() method. Some jobs wrap a lambda function as in this example or decorate other jobs. However implementing custom, reusable job classes is only a matter of writing a class that inherits ThreadWeaver::Job and re-implementing it’s run method. The job that was created by make_job() in this example wraps the specified lambda function, and executes it when it is itself executed by a worker thread.

The program does not specify where the job should be executed, and not even when exactly. In a scenario where there would be many jobs waiting in the queue, execution of the new job would not be immediate. Which worker thread will be assigned the job is also undefined. The programmer gives up a bit of control over the details of execution, and in turns benefits from the automatic distribution of jobs amongst the available processors by the worker threads in the queue. Every program that links the ThreadWeaver library has access to a global queue for the execution of jobs. If no queue is specified when enqueueing a job, the global one will be used by default. Workers threads are allocated when needed by the queue. If the global pool is never accessed by an application, it will never be instantiated.

An application performing tasks in background threads should never exit while any of these operations is still in progress. In the case of ThreadWeaver, this means all jobs in the queue need to be either completed or dequeued and all worker threads idle before the application may exit. The global pool is in fact a QObject child of the QCoreApplication object instantiated in line 7. It will be deleted by the destructor of QCoreApplication. When it is destroyed, it will wait until all queued up jobs have completed. The program will thus wait in line 8 until the job has finished printing “Hello World!” and will then exit. The job was enqueued as a shared pointer, so memory management is taken care of. While this example was very much simplified, the described functionality already has many practical applications. For example, the many operations real-life applications need to perform at startup, like loading translations, icon resources et cetera, can be removed from the criticial path this way. In this case the operations usually need to be performed in a certain order and then handed over to the main thread. Solutions for that are built into ThreadWeaver as well.