1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtConcurrent module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40/*!
41 \page qtconcurrentrun.html
42 \title Concurrent Run
43 \ingroup thread
44
45 The QtConcurrent::run() function runs a function in a separate thread.
46 The return value of the function is made available through the QFuture API.
47
48 QtConcurrent::run() is an overloaded method. You can think of these overloads as slightly
49 different \e modes.
50 In \l {Concurrent Run (basic mode)} {basic mode}, the function passed to QtConcurrent::run()
51 is able to report merely a single computation result to its caller.
52 In \l {Concurrent Run With Promise} {run with promise mode}, the function passed to
53 QtConcurrent::run() can make use of the additional
54 QPromise API, which enables multiple result reporting, progress reporting,
55 suspending the computation when requested by the caller, or stopping
56 the computation on the caller's demand.
57
58 This function is a part of the Qt Concurrent framework.
59
60 \section1 Concurrent Run (basic mode)
61
62 The function passed to QtConcurrent::run() may report the result
63 through its return value.
64
65 \section2 Running a Function in a Separate Thread
66
67 To run a function in another thread, use QtConcurrent::run():
68
69 \snippet code/src_concurrent_qtconcurrentrun.cpp 0
70
71 This will run \c aFunction in a separate thread obtained from the default
72 QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
73 the status of the function.
74
75 To use a dedicated thread pool, you can pass the QThreadPool as
76 the first argument:
77
78 \snippet code/src_concurrent_qtconcurrentrun.cpp explicit-pool-0
79
80 \section2 Passing Arguments to the Function
81
82 Passing arguments to the function is done by adding them to the
83 QtConcurrent::run() call immediately after the function name. For example:
84
85 \snippet code/src_concurrent_qtconcurrentrun.cpp 1
86
87 A copy of each argument is made at the point where QtConcurrent::run() is
88 called, and these values are passed to the thread when it begins executing
89 the function. Changes made to the arguments after calling
90 QtConcurrent::run() are \e not visible to the thread.
91
92 Note that QtConcurrent::run does not support calling overloaded functions
93 directly. For example, the code below won't compile:
94
95//! [run-with-overload-calls]
96 \snippet code/src_concurrent_qtconcurrentrun.cpp 15
97
98 The easiest workaround is to call the overloaded function through lambda:
99
100 \snippet code/src_concurrent_qtconcurrentrun.cpp 16
101
102 Or you can tell the compiler which overload to choose by using a
103 \c static_cast:
104
105 \snippet code/src_concurrent_qtconcurrentrun.cpp 17
106
107 Or qOverload:
108
109 \snippet code/src_concurrent_qtconcurrentrun.cpp 18
110//! [run-with-overload-calls]
111
112 \section2 Returning Values from the Function
113
114 Any return value from the function is available via QFuture:
115
116 \snippet code/src_concurrent_qtconcurrentrun.cpp 2
117
118 As documented above, passing arguments is done like this:
119
120 \snippet code/src_concurrent_qtconcurrentrun.cpp 3
121
122 Note that the QFuture::result() function blocks and waits for the result
123 to become available. Use QFutureWatcher to get notification when the
124 function has finished execution and the result is available.
125
126 \section2 Additional API Features
127
128 \section3 Using Member Functions
129
130 QtConcurrent::run() also accepts pointers to member functions. The first
131 argument must be either a const reference or a pointer to an instance of
132 the class. Passing by const reference is useful when calling const member
133 functions; passing by pointer is useful for calling non-const member
134 functions that modify the instance.
135
136 For example, calling QByteArray::split() (a const member function) in a
137 separate thread is done like this:
138
139 \snippet code/src_concurrent_qtconcurrentrun.cpp 4
140
141 Calling a non-const member function is done like this:
142
143 \snippet code/src_concurrent_qtconcurrentrun.cpp 5
144
145 \section3 Using Lambda Functions
146
147 Calling a lambda function is done like this:
148
149 \snippet code/src_concurrent_qtconcurrentrun.cpp 6
150
151 Calling a function modifies an object passed by reference is done like this:
152
153 \snippet code/src_concurrent_qtconcurrentrun.cpp 7
154
155 Using callable object is done like this:
156
157 \snippet code/src_concurrent_qtconcurrentrun.cpp 8
158
159 \section1 Concurrent Run With Promise
160
161 The \e {Run With Promise} mode enables more control for the running
162 task compared to \e basic mode of QtConcurrent::run().
163 It allows progress reporting of the running task,
164 reporting multiple results, suspending the execution
165 if it was requested, or canceling the task on caller's
166 demand.
167
168 \section2 The mandatory QPromise argument
169
170 The function passed to QtConcurrent::run() in \e {Run With Promise} mode is expected
171 to have an additional argument of \c {QPromise<T> &} type, where
172 T is the type of the computation result (it should match the type T
173 of QFuture<T> returned by the QtConcurrent::runWithPromise()), like e.g.:
174
175 \snippet code/src_concurrent_qtconcurrentrun.cpp 9
176
177 The \c promise argument is instantiated inside the
178 QtConcurrent::run() function, and its reference
179 is passed to the invoked \c aFunction, so the user
180 doesn't need to instantiate it by himself, nor pass it explicitly
181 when calling QtConcurrent::runWithPromise().
182
183 The additional argument of QPromise type always needs to appear
184 as a first argument on function's arguments list, like:
185
186 \snippet code/src_concurrent_qtconcurrentrun.cpp 10
187
188 \section2 Reporting results
189
190 In contrast to \e basic mode of QtConcurrent::run(), the function passed to
191 QtConcurrent::run() in \e {Run With Promise} mode is expected to always return void type.
192 Result reporting is done through the additional argument of QPromise type.
193 It also enables multiple result reporting, like:
194
195 \snippet code/src_concurrent_qtconcurrentrun.cpp 11
196
197 \note There's no need to call QPromise::start() and QPromise::finish() to
198 indicate the beginning and the end of computation (like you would normally do when
199 using QPromise). QtConcurrent::run() will always call them before starting and
200 after finishing the execution.
201
202 \section2 Suspending and canceling the execution
203
204 The QPromise API also enables suspending and canceling the computation, if requested:
205
206 \snippet code/src_concurrent_qtconcurrentrun.cpp 12
207
208 The call to \c future.suspend() requests the running task to
209 hold its execution. After calling this method, the running task
210 will suspend after the next call to \c promise.suspendIfRequested()
211 in its iteration loop. In this case the running task will
212 block on a call to \c promise.suspendIfRequested(). The blocked
213 call will unblock after the \c future.resume() is called.
214 Note, that internally suspendIfRequested() uses wait condition
215 in order to unblock, so the running thread goes into an idle state
216 instead of wasting its resources when blocked in order to periodically
217 check if the resume request came from the caller's thread.
218
219 The call to \c future.cancel() from the last line causes that the next
220 call to \c promise.isCanceled() will return \c true and
221 \c aFunction will return immediately without any further result reporting.
222
223 \note There's no need to call QPromise::finish() to stop the computation
224 after the cancellation (like you would normally do when using QPromise).
225 QtConcurrent::run() will always call it after finishing the execution.
226
227 \section2 Progress reporting
228
229 It's also possible to report the progress of a task
230 independently of result reporting, like:
231
232 \snippet code/src_concurrent_qtconcurrentrun.cpp 13
233
234 The caller installs the \c QFutureWatcher for the \c QFuture
235 returned by QtConcurrent::run() in order to
236 connect to its \c progressValueChanged() signal and update
237 e.g. the graphical user interface accordingly.
238
239 \section2 Invoking functions with overloaded operator()()
240
241 By default, QtConcurrent::run() doesn't support functors with
242 overloaded operator()() in \e {Run With Promise} mode. In case of overloaded
243 functors the user needs to explicitly specify the result type
244 as a template parameter passed to QtConcurrent::run(), like:
245
246 \snippet code/src_concurrent_qtconcurrentrun.cpp 14
247*/
248
249/*!
250 \typedef Function
251 \internal
252
253 This typedef is a dummy required to make the \c Function
254 type name known so that clang doesn't reject functions
255 that use it.
256*/
257
258/*!
259 \fn QFuture<T> QtConcurrent::run(Function function, ...);
260
261 Equivalent to
262 \code
263 QtConcurrent::run(QThreadPool::globalInstance(), function, ...);
264 \endcode
265
266 Runs \a function in a separate thread. The thread is taken from the global
267 QThreadPool. Note that \a function may not run immediately; \a function
268 will only be run once a thread becomes available.
269
270//! [run-description]
271 In \l {Concurrent Run (basic mode)} {basic mode} T is the same type as the return value
272 of \a function. Non-void return values can be accessed via the QFuture::result() function.
273
274 In \l {Concurrent Run (basic mode)} {basic mode} the QFuture returned can only be used to
275 query for the running/finished status and the return value of the function. In particular,
276 canceling or pausing can be issued only if the computations behind the future
277 has not been started.
278
279 In \l {Concurrent Run With Promise} {run with promise mode}, the \a function is expected
280 to return void and must take an additional argument of \c {QPromise<T> &} type,
281 placed as a first argument in function's argument list. T is the result type
282 and it is the same for the returned \c QFuture<T>.
283
284 In \l {Concurrent Run With Promise} {run with promise mode}, similar to \e basic mode, the
285 QFuture returned can be used to query for the running/finished status and the value reported
286 by the function. In addition, it may be used for suspending or canceling the
287 running task, fetching multiple results from the called \a function or
288 monitoring progress reported by the \a function.
289
290 \sa {Concurrent Run (basic mode)}, {Concurrent Run With Promise}
291//! [run-description]
292*/
293
294/*!
295 \since 5.4
296 \fn QFuture<T> QtConcurrent::run(QThreadPool *pool, Function function, ...);
297
298 Runs \a function in a separate thread. The thread is taken from the
299 QThreadPool \a pool. Note that \a function may not run immediately; \a function
300 will only be run once a thread becomes available.
301
302 \include qtconcurrentrun.cpp run-description
303*/
304
305