summaryrefslogtreecommitdiffstats
path: root/src/concurrent/doc/src/qtconcurrent-index.qdoc
blob: e4abb433cdf7b356cf05ea62b071d43c341fa573 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtconcurrent-index.html
    \title Qt Concurrent

    \brief The Qt Concurrent module contains functionality to support concurrent execution of program code.

    \include module-use.qdocinc using qt module
    \snippet snippets/CMakeLists.txt cmake_use

    See also the \l[QtDoc]{Building with CMake} overview.

    \include module-use.qdocinc building with qmake
    \snippet snippets/snippets.pro qmake_use

    \section1 Getting Started

    The QtConcurrent namespace 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 QtConcurrent
    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.

    QtConcurrent 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:

    \list
    \li \l {Concurrent Map and Map-Reduce}
        \list
            \li \l {QtConcurrent::map}{QtConcurrent::map()} applies a function
                to every item in a container, modifying the items in-place.
            \li \l {QtConcurrent::mapped}{QtConcurrent::mapped()} is like
                map(), except that it returns a new container with the
                modifications.
            \li \l {QtConcurrent::mappedReduced}{QtConcurrent::mappedReduced()}
                is like mapped(), except that the modified results are reduced
                or folded into a single result.
        \endlist

    \li \l {Concurrent Filter and Filter-Reduce}
    \list
        \li \l {QtConcurrent::filter}{QtConcurrent::filter()} removes all items
            from a container based on the result of a filter function.
        \li \l {QtConcurrent::filtered}{QtConcurrent::filtered()} is like
            filter(), except that it returns a new container with the filtered
            results.
        \li \l {QtConcurrent::filteredReduced}{QtConcurrent::filteredReduced()}
            is like filtered(), except that the filtered results are reduced or
            folded into a single result.
    \endlist

    \li \l {Concurrent Run and Run With Promise}
    \list
        \li \l {QtConcurrent::run}{QtConcurrent::run()} runs a function in
            another thread.
        \li \l {QtConcurrent::runWithPromise}{QtConcurrent::runWithPromise()}
            is like run(), except that the function to run accepts additional
            argument of QPromise type that enables more control over the function
            execution, like suspending or canceling the execution when requested,
            progress reporting or reporting multiple results.
    \endlist

    \li \l {Concurrent Task}
    \list
        \li \l {QtConcurrent::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.
    \endlist

    \li QFuture represents the result of an asynchronous computation.

    \li QFutureIterator allows iterating through results available via QFuture.

    \li QFutureWatcher allows monitoring a QFuture using signals-and-slots.

    \li QFutureSynchronizer is a convenience class that automatically
    synchronizes several QFutures.

    \li 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.

    \endlist

    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:

    \table
    \header
        \li Iterator Type
        \li Example classes
        \li Support status
    \row
        \li Input Iterator
        \li
        \li Not Supported
    \row
        \li Output Iterator
        \li
        \li Not Supported
    \row
        \li Forward Iterator
        \li std::slist
        \li Supported
    \row
        \li Bidirectional Iterator
        \li std::list
        \li Supported
    \row
        \li Random Access Iterator
        \li QList, std::vector
        \li Supported and Recommended
    \endtable

    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 trough 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.

    \section1 Module Evolution
    \l{Porting to Qt 6 - Qt Concurrent} lists important changes in the module API
    and functionality that were done for the Qt 6 series of Qt.

    \section1 Licenses

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