Qt Concurrent

The Qt Concurrent module provides high-level APIs that make it possible to write multi-threaded programs without using low-level threading primitives such as mutexes, read-write locks, wait conditions, or semaphores. Programs written with Qt Concurrent automatically adjust the number of threads used according to the number of processor cores available. This means that applications written today will continue to scale when deployed on multi-core systems in the future.

Qt Concurrent includes functional programming style APIs for parallel list processing, including a MapReduce and FilterReduce implementation for shared-memory (non-distributed) systems, and classes for managing asynchronous computations in GUI applications:

• Concurrent Map and Map-Reduce
  • QtConcurrent::map() applies a function to every item in a container, modifying the items in-place.
  • QtConcurrent::mapped() is like map(), except that it returns a new container with the modifications.
  • QtConcurrent::mappedReduced() is like mapped(), except that the modified results are reduced or folded into a single result.
• Concurrent Filter and Filter-Reduce
  • QtConcurrent::filter() removes all items from a container based on the result of a filter function.
  • QtConcurrent::filtered() is like filter(), except that it returns a new container with the filtered results.
  • QtConcurrent::filteredReduced() is like filtered(), except that the filtered results are reduced or folded into a single result.
• Concurrent Run
  • QtConcurrent::run() runs a function in another thread.
• Concurrent Task
  • QtConcurrent::task() creates an instance of QtConcurrent::QTaskBuilder. This object can be used for adjusting parameters and for kicking off a task in a separate thread.
• QFuture represents the result of an asynchronous computation.
• QFutureIterator allows iterating through results available via QFuture.
• QFutureWatcher allows monitoring a QFuture using signals-and-slots.
• QFutureSynchronizer is a convenience class that automatically synchronizes several QFutures.
• QPromise provides a way to report progress and results of the asynchronous computation to QFuture. Allows suspending or canceling the task when requested by QFuture.

Qt Concurrent supports several STL-compatible container and iterator types, but works best with Qt containers that have random-access iterators, such as QList. The map and filter functions accept both containers and begin/end iterators.

STL Iterator support overview:

Iterator Type	Example classes	Support status
Input Iterator		Not Supported
Output Iterator		Not Supported
Forward Iterator	std::slist	Supported
Bidirectional Iterator	std::list	Supported
Random Access Iterator	QList, std::vector	Supported and Recommended

Random access iterators can be faster in cases where Qt Concurrent is iterating over a large number of lightweight items, since they allow skipping to any point in the container. In addition, using random access iterators allows Qt Concurrent to provide progress information through QFuture::progressValue() and QFutureWatcher::progressValueChanged().

The non in-place modifying functions such as mapped() and filtered() makes a copy of the container when called. If you are using STL containers this copy operation might take some time, in this case we recommend specifying the begin and end iterators for the container instead.

Using the Module

Using a Qt module requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

Building with CMake

Use the find_package() command to locate the needed module components in the Qt6 package:

find_package(Qt6 COMPONENTS Concurrent REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Concurrent)

See also the Build with CMake overview.

Building with qmake

To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

QT += concurrent

Module Evolution

Changes to Qt Concurrent lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.

Licenses

The Qt Concurrent module is available under commercial licenses from The Qt Company. In addition, it is available under free software licenses: The GNU Lesser General Public License, version 3, or the GNU General Public License, version 2. See Qt Licensing for further details.