1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qtconcurrent-index.html
8 \brief The Qt Concurrent module contains functionality to support concurrent execution of program code.
11 The Qt Concurrent module provides high-level APIs that make it
12 possible to write multi-threaded programs without using low-level
13 threading primitives such as mutexes, read-write locks, wait
14 conditions, or semaphores. Programs written with Qt Concurrent
15 automatically adjust the number of threads used according to the
16 number of processor cores available. This means that applications
17 written today will continue to scale when deployed on multi-core
18 systems in the future.
20 Qt Concurrent includes functional programming style APIs for
21 parallel list processing, including a MapReduce and FilterReduce
22 implementation for shared-memory (non-distributed) systems, and
23 classes for managing asynchronous computations in GUI
27 \li \l {Concurrent Map and Map-Reduce}
29 \li \l {QtConcurrent::map}{QtConcurrent::map()} applies a function
30 to every item in a container, modifying the items in-place.
31 \li \l {QtConcurrent::mapped}{QtConcurrent::mapped()} is like
32 map(), except that it returns a new container with the
34 \li \l {QtConcurrent::mappedReduced}{QtConcurrent::mappedReduced()}
35 is like mapped(), except that the modified results are reduced
36 or folded into a single result.
39 \li \l {Concurrent Filter and Filter-Reduce}
41 \li \l {QtConcurrent::filter}{QtConcurrent::filter()} removes all items
42 from a container based on the result of a filter function.
43 \li \l {QtConcurrent::filtered}{QtConcurrent::filtered()} is like
44 filter(), except that it returns a new container with the filtered
46 \li \l {QtConcurrent::filteredReduced}{QtConcurrent::filteredReduced()}
47 is like filtered(), except that the filtered results are reduced or
48 folded into a single result.
51 \li \l {Concurrent Run}
53 \li \l {QtConcurrent::run}{QtConcurrent::run()} runs a function in
57 \li \l {Concurrent Task}
59 \li \l {QtConcurrent::task}{QtConcurrent::task()} creates an instance
60 of QtConcurrent::QTaskBuilder. This object can be used for adjusting
61 parameters and for kicking off a task in a separate thread.
64 \li QFuture represents the result of an asynchronous computation.
66 \li QFutureIterator allows iterating through results available via QFuture.
68 \li QFutureWatcher allows monitoring a QFuture using signals-and-slots.
70 \li QFutureSynchronizer is a convenience class that automatically
71 synchronizes several QFutures.
73 \li QPromise provides a way to report progress and results of the
74 asynchronous computation to QFuture. Allows suspending or canceling the task
75 when requested by QFuture.
79 Qt Concurrent supports several STL-compatible container and iterator types,
80 but works best with Qt containers that have random-access iterators, such as
81 QList. The map and filter functions accept both containers and begin/end
84 STL Iterator support overview:
104 \li Bidirectional Iterator
108 \li Random Access Iterator
109 \li QList, std::vector
110 \li Supported and Recommended
113 Random access iterators can be faster in cases where Qt Concurrent is
114 iterating over a large number of lightweight items, since they allow
115 skipping to any point in the container. In addition, using random access
116 iterators allows Qt Concurrent to provide progress information through
117 QFuture::progressValue() and QFutureWatcher::progressValueChanged().
119 The non in-place modifying functions such as mapped() and filtered() makes a
120 copy of the container when called. If you are using STL containers this copy
121 operation might take some time, in this case we recommend specifying the
122 begin and end iterators for the container instead.
125 \include module-use.qdocinc using qt module
126 \snippet snippets/CMakeLists.txt cmake_use
128 See also the \l {Build with CMake} overview.
130 \include module-use.qdocinc building with qmake
131 \snippet snippets/snippets.pro qmake_use
136 \li \l {Qt Concurrent Examples}
139 \section1 Module Evolution
140 \l{Changes to Qt Concurrent} lists important changes in the module API
141 and functionality that were done for the Qt 6 series of Qt.
145 The Qt Concurrent module is available under commercial licenses from
147 In addition, it is available under free software licenses:
148 The \l{GNU Lesser General Public License, version 3}, or
149 the \l{GNU General Public License, version 2}.
150 See \l{Qt Licensing} for further details.