Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtconcurrent-index.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page qtconcurrent-index.html
6 \title Qt Concurrent
7
8 \brief The Qt Concurrent module contains functionality to support concurrent execution of program code.
9
10
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.
19
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
24 applications:
25
26 \list
27 \li \l {Concurrent Map and Map-Reduce}
28 \list
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
33 modifications.
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.
37 \endlist
38
39 \li \l {Concurrent Filter and Filter-Reduce}
40 \list
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
45 results.
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.
49 \endlist
50
51 \li \l {Concurrent Run}
52 \list
53 \li \l {QtConcurrent::run}{QtConcurrent::run()} runs a function in
54 another thread.
55 \endlist
56
57 \li \l {Concurrent Task}
58 \list
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.
62 \endlist
63
64 \li QFuture represents the result of an asynchronous computation.
65
66 \li QFutureIterator allows iterating through results available via QFuture.
67
68 \li QFutureWatcher allows monitoring a QFuture using signals-and-slots.
69
70 \li QFutureSynchronizer is a convenience class that automatically
71 synchronizes several QFutures.
72
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.
76
77 \endlist
78
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
82 iterators.
83
84 STL Iterator support overview:
85
86 \table
87 \header
88 \li Iterator Type
89 \li Example classes
90 \li Support status
91 \row
92 \li Input Iterator
93 \li
94 \li Not Supported
95 \row
96 \li Output Iterator
97 \li
98 \li Not Supported
99 \row
100 \li Forward Iterator
101 \li std::forward_list
102 \li Supported
103 \row
104 \li Bidirectional Iterator
105 \li std::list
106 \li Supported
107 \row
108 \li Random Access Iterator
109 \li QList, std::vector
110 \li Supported and Recommended
111 \endtable
112
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().
118
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.
123
124
125 \include module-use.qdocinc using qt module
126 \snippet snippets/CMakeLists.txt cmake_use
127
128 See also the \l {Build with CMake} overview.
129
130 \include module-use.qdocinc building with qmake
131 \snippet snippets/snippets.pro qmake_use
132
133 \section1 Examples
134
135 \list
136 \li \l {Qt Concurrent Examples}
137 \endlist
138
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.
142
143 \section1 Licenses
144
145 The Qt Concurrent module is available under commercial licenses from
146 \l{The Qt Company}.
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.
151*/