New in Qt 5.10: QThread::create

10.01.2018 Giuseppe D'Angelo 17 comments

If you are using Qt and you need to run some code in a separate thread, chances are that you are using QThread for the job. QThread is a very old class in Qt, making its first appearance in Qt 2.2, released on the 22nd of September 2000. Its responsibility is to start a new thread, and let you execute code in that thread.

There are two main ways of running code in a separate thread using QThread:

1. subclassing QThread and overriding run();
2. creating a “worker object” (some QObject subclass) and connecting it to QThread signals.

Please refer to my Qt World Summit 2017 presentation (video) for more details about how to use these two functions. There are also lots of other documentation and blog posts available on the internet, discussing the pros and the cons of the two approaches.

Enter QThread::create()

In Qt 5.10 I have added another way to run some code in a new thread. Inspired by C++11’s std::thread, I have introduced QThread::create, a factory function that creates a new QThread which will run a user-provided callable:

QThread *thread = QThread::create([]{ runSlowCode(); });
thread->start();

The advantage of this approach is that it avoids creating a new QThread subclass manually for the sole purpose to override its run() member function and run some code.

Unlike std::thread, however, the newly-created thread is not automatically launched; the user is expected to start it with an explicit call to start(). This allows users to do some extra work before starting the thread, for instance, connect to its signals, set the name of the thread, or change its priority, as demonstrated by this snippet:

QThread *thread = QThread::create(myFunction);

thread->setObjectName("WorkerThread"); // name to appear in ps, task manager, etc.
connect(thread, &QThread::started, gui, &Gui::threadHasStarted);

thread->start();

The user acquires ownership of the newly-created QThread object.

With a C++17 capable compiler it is also possible to pass extra arguments to QThread::create(): these arguments will be then passed to the function in the new thread, using the same semantics as std::thread‘s constructor. For instance:

QThread *thread = QThread::create(myFunction, arg1, arg2);
// extra setup...
thread->start(); // calls myFunction in another thread, passing arg1 and arg2

That’s it! I hope this will be useful to you. However, the API of QThread::create() is only half of the story. If you want to know more about what this apparently little patch meant for Qt, keep reading.

Implementation notes

In afterthought, the implementation of QThread::create is very simple. However, when doing the necessary research, I found a small oddity with the C++ Standard Library that deserves some attention.

The most important constraint I imposed on myself when writing QThread::create was to be as compatible as possible with std::thread‘s constructor semantics. If one reads the relevant section in the Standard (f.i. here), one can see that the actual semantics of the invocation are quite complex. The extra arguments to the function undergo a transformation (specified as DECAY_COPY), they’re stored “somewhere”, and finally the functor is invoked using the INVOKE function. Both DECAY_COPY and INVOKE are not actual Standard Library functions, but pseudo-functions formally defined elsewhere in the C++ Standard.

An oddity that I found during my research is that the C++11 Standard does not provide these building blocks to end-users (and by that I also include developers of other C++ libraries, like Qt). A way to use INVOKE for user code got added in C++17 with the std::invoke function; however, there is simply nothing ready-made that applies the DECAY_COPY transformation, and stores the callable and its decayed/copied arguments, and possibly even invokes the function with the right semantics.

The only workaround that I have found was to use a higher-level thread primitive provided by the Standard Library: std::async. std::async has the same invocation semantics as std::thread‘s constructor; it returns a std::future that we can use to examine the result.

We can force std::async to not spawn an additional thread and to run the callable only when asked to do so, by specifying the std::launch::deferred launch policy. std::launch::deferred allows a sort of lazy evaluation: the callable is invoked only when one tries to access the result (via the returned std::future object):

auto future = std::async(std::launch::deferred, function, arg1, arg2);

// some time later, possibly in another thread:
future.get(); // calls the function with the arguments

This is exactly how QThread::create() is implemented: it calls std::async on the user-provided function and its arguments, and stores the returned std::future in an instance of an internal QThread subclass. This subclass overrides run(), which in turn simply calls get() on the future (see here and here). This machinery isn’t zero-overhead, as the combination of std::async and std::future does way more than what we need, but it at least shifts the burden of the implementation from Qt onto the Standard Library.

The extra plumbing needed is the aforementioned std::invoke, which however is only available in C++17. Under a C++17 compiler, QThread::create() takes a callable and its arguments, whereas under a pre-C++17 compiler, QThread::create() only supports a callable (and no further arguments). In practice this isn’t a big limitation, because one can always use a lambda to wrap the callable and its arguments, and then pass the lambda as the only argument.

Qt and the Standard Library ABI

The addition of QThread::create() to Qt was also possible because of a major policy change in Qt.

A little bit of history: up to and including version 4, Qt did not require the presence of a Standard Library implementation on the system (the configure script had a -no-stl option). From version 5.0 Qt started to require a working Standard Library implementation: the configure switch was dropped, and Qt code dealing with Standard Library types was compiled unconditionally. Qt itself started using Standard Library types (notably, containers) in its own implementation, mostly where such types provided more features or performance when compared to Qt’s own versions.

However, Qt has never exposed Standard Library types from its public ABI: all functions taking or returning Standard Library types had to be inline (example). The main reason for doing so was to make the same build of Qt compatible across different Standard Library implementations (e.g. libc++ and stdlibc++, or two ABI-incompatible builds of the same implementation).

After lots of debate, this has finally changed in Qt 5.10: Qt is now allowed to expose Standard Library types from its public ABI. Users wishing to mix-and-match Standard Library implementations need to recompile Qt. (In other words, we’ve made this Someone Else’s Problem).

What does this have to do with QThread::create()? As I explained before, the current implementation uses std::async under the hood. The std::future returned by std::async is then passed to an exported, out-of-line Qt function, which constructs and returns the result — the QThread instance that runs the user-supplied function. (The reason for doing such a thing is because QThread is an exported polymorphic class. A subclass defined entirely inline would generate copies of its vtable / type_info in all the translation units using it, and this may cause problems.) Therefore, now std::future is part of Qt’s own ABI; and I’m very glad I didn’t have to re-implement it!