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 and Run With Promise
43 \ingroup thread
44
45 The QtConcurrent::run() and QtConcurrent::runWithPromise()
46 functions run a function in a separate thread.
47 The return value of the function is made available through the QFuture API.
48 The function passed to QtConcurrent::run() is able to report merely
49 a single computation result to its caller, while the function passed to
50 QtConcurrent::runWithPromise() can make use of the additional
51 QPromise API, which enables multiple result reporting, progress reporting,
52 suspending the computation when requested by the caller, or stopping
53 the computation on the caller's demand.
54
55 These functions are part of the Qt Concurrent framework.
56
57 \section1 Concurrent Run
58
59 The function passed to QtConcurrent::run() may report the result
60 through its return value.
61
62 \section2 Running a Function in a Separate Thread
63
64 To run a function in another thread, use QtConcurrent::run():
65
66 \snippet code/src_concurrent_qtconcurrentrun.cpp 0
67
68 This will run \e aFunction in a separate thread obtained from the default
69 QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
70 the status of the function.
71
72 To use a dedicated thread pool, you can pass the QThreadPool as
73 the first argument:
74
75 \snippet code/src_concurrent_qtconcurrentrun.cpp explicit-pool-0
76
77 \section2 Passing Arguments to the Function
78
79 Passing arguments to the function is done by adding them to the
80 QtConcurrent::run() call immediately after the function name. For example:
81
82 \snippet code/src_concurrent_qtconcurrentrun.cpp 1
83
84 A copy of each argument is made at the point where QtConcurrent::run() is
85 called, and these values are passed to the thread when it begins executing
86 the function. Changes made to the arguments after calling
87 QtConcurrent::run() are \e not visible to the thread.
88
89 \section2 Returning Values from the Function
90
91 Any return value from the function is available via QFuture:
92
93 \snippet code/src_concurrent_qtconcurrentrun.cpp 2
94
95 As documented above, passing arguments is done like this:
96
97 \snippet code/src_concurrent_qtconcurrentrun.cpp 3
98
99 Note that the QFuture::result() function blocks and waits for the result
100 to become available. Use QFutureWatcher to get notification when the
101 function has finished execution and the result is available.
102
103 \section2 Additional API Features
104
105 \section3 Using Member Functions
106
107 QtConcurrent::run() also accepts pointers to member functions. The first
108 argument must be either a const reference or a pointer to an instance of
109 the class. Passing by const reference is useful when calling const member
110 functions; passing by pointer is useful for calling non-const member
111 functions that modify the instance.
112
113 For example, calling QByteArray::split() (a const member function) in a
114 separate thread is done like this:
115
116 \snippet code/src_concurrent_qtconcurrentrun.cpp 4
117
118 Calling a non-const member function is done like this:
119
120 \snippet code/src_concurrent_qtconcurrentrun.cpp 5
121
122 \section3 Using Lambda Functions
123
124 Calling a lambda function is done like this:
125
126 \snippet code/src_concurrent_qtconcurrentrun.cpp 6
127
128 Calling a function modifies an object passed by reference is done like this:
129
130 \snippet code/src_concurrent_qtconcurrentrun.cpp 7
131
132 Using callable object is done like this:
133
134 \snippet code/src_concurrent_qtconcurrentrun.cpp 8
135
136 \section1 Concurrent Run With Promise
137
138 The QtConcurrent::runWithPromise() enables more control
139 for the running task comparing to QtConcurrent::run().
140 It allows progress reporting of the running task,
141 reporting multiple results, suspending the execution
142 if it was requested, or canceling the task on caller's
143 demand.
144
145 \section2 The mandatory QPromise argument
146
147 The function passed to QtConcurrent::runWithPromise() is expected
148 to have an additional argument of \e {QPromise<T> &} type, where
149 T is the type of the computation result (it should match the type T
150 of QFuture<T> returned by the QtConcurrent::runWithPromise()), like e.g.:
151
152 \snippet code/src_concurrent_qtconcurrentrun.cpp 9
153
154 The \e promise argument is instantiated inside the
155 QtConcurrent::runWithPromise() function, and its reference
156 is passed to the invoked \e aFunction, so the user
157 doesn't need to instantiate it by himself, nor pass it explicitly
158 when calling QtConcurrent::runWithPromise().
159
160 The additional argument of QPromise type always needs to appear
161 as a first argument on function's arguments list, like:
162
163 \snippet code/src_concurrent_qtconcurrentrun.cpp 10
164
165 \section2 Reporting results
166
167 In contrast to QtConcurrent::run(), the function passed to
168 QtConcurrent::runWithPromise() is expected to always return void type.
169 Result reporting is done through the additional argument of QPromise type.
170 It also enables multiple result reporting, like:
171
172 \snippet code/src_concurrent_qtconcurrentrun.cpp 11
173
174 \section2 Suspending and canceling the execution
175
176 The QPromise API also enables suspending and canceling the computation, if requested:
177
178 \snippet code/src_concurrent_qtconcurrentrun.cpp 12
179
180 The call to \e future.suspend() requests the running task to
181 hold its execution. After calling this method, the running task
182 will suspend after the next call to \e promise.suspendIfRequested()
183 in its iteration loop. In this case the running task will
184 block on a call to \e promise.suspendIfRequested(). The blocked
185 call will unblock after the \e future.resume() is called.
186 Note, that internally suspendIfRequested() uses wait condition
187 in order to unblock, so the running thread goes into an idle state
188 instead of wasting its resources when blocked in order to periodically
189 check if the resume request came from the caller's thread.
190
191 The call to \e future.cancel() from the last line causes that the next
192 call to \e promise.isCanceled() will return \c true and
193 \e aFunction will return immediately without any further result reporting.
194
195 \section2 Progress reporting
196
197 It's also possible to report the progress of a task
198 independently of result reporting, like:
199
200 \snippet code/src_concurrent_qtconcurrentrun.cpp 13
201
202 The caller installs the \e QFutureWatcher for the \e QFuture
203 returned by QtConcurrent::runWithPromise() in order to
204 connect to its \e progressValueChanged() signal and update
205 e.g. the graphical user interface accordingly.
206
207 \section2 Invoking functions with overloaded operator()()
208
209 By default, QtConcurrent::runWithPromise() doesn't support functors with
210 overloaded operator()(). In case of overloaded functors the user
211 needs to explicitly specify the result type
212 as a template parameter passed to runWithPromise, like:
213
214 \snippet code/src_concurrent_qtconcurrentrun.cpp 14
215*/
216
217/*!
218 \typedef Function
219 \internal
220
221 This typedef is a dummy required to make the \c Function
222 type name known so that clang doesn't reject functions
223 that use it.
224*/
225
226/*!
227 \fn QFuture<T> QtConcurrent::run(Function function, ...);
228
229 Equivalent to
230 \code
231 QtConcurrent::run(QThreadPool::globalInstance(), function, ...);
232 \endcode
233
234 Runs \a function in a separate thread. The thread is taken from the global
235 QThreadPool. Note that \a function may not run immediately; \a function
236 will only be run once a thread becomes available.
237
238 T is the same type as the return value of \a function. Non-void return
239 values can be accessed via the QFuture::result() function.
240
241 \note The QFuture returned can only be used to query for the
242 running/finished status and the return value of the function. In particular,
243 canceling or pausing can be issued only if the computations behind the future
244 has not been started.
245
246 \sa {Concurrent Run}
247*/
248
249/*!
250 \since 5.4
251 \fn QFuture<T> QtConcurrent::run(QThreadPool *pool, Function function, ...);
252
253 Runs \a function in a separate thread. The thread is taken from the
254 QThreadPool \a pool. Note that \a function may not run immediately; \a function
255 will only be run once a thread becomes available.
256
257 T is the same type as the return value of \a function. Non-void return
258 values can be accessed via the QFuture::result() function.
259
260 \note The QFuture returned can only be used to query for the
261 running/finished status and the return value of the function. In particular,
262 canceling or pausing can be issued only if the computations behind the future
263 has not been started.
264
265 \sa {Concurrent Run}
266*/
267
268/*!
269 \since 6.0
270 \fn QFuture<T> QtConcurrent::runWithPromise(Function function, ...);
271
272 Equivalent to
273 \code
274 QtConcurrent::runWithPromise(QThreadPool::globalInstance(), function, ...);
275 \endcode
276
277 Runs \a function in a separate thread. The thread is taken from the global
278 QThreadPool. Note that \a function may not run immediately; \a function
279 will only be run once a thread becomes available.
280
281 The \a function is expected to return void
282 and must take an additional argument of \e {QPromise<T> &} type,
283 placed as a first argument in function's argument list. T is the result type
284 and it is the same for the returned \e QFuture<T>.
285
286 Similar to QtConcurrent::run(), the QFuture returned can be used to query for the
287 running/finished status and the value reported by the function. In addition,
288 it may be used for suspending or canceling the running task, fetching
289 multiple results from the called /a function or monitoring progress
290 reported by the \a function.
291
292 \sa {Concurrent Run With Promise}
293*/
294
295/*!
296 \since 6.0
297 \fn QFuture<T> QtConcurrent::runWithPromise(QThreadPool *pool, Function function, ...);
298
299 Runs \a function in a separate thread. The thread is taken from the
300 QThreadPool \a pool. Note that \a function may not run immediately; \a function
301 will only be run once a thread becomes available.
302
303 The \a function is expected to return void
304 and must take an additional argument of \e {QPromise<T> &} type,
305 placed as a first argument in function's argument list. T is the result type
306 and it is the same for the returned \e QFuture<T>.
307
308 Similar to QtConcurrent::run(), the QFuture returned can be used to query for the
309 running/finished status and the value reported by the function. In addition,
310 it may be used for suspending or canceling the running task, fetching
311 multiple results from the called /a function or monitoring progress
312 reported by the \a function.
313
314 \sa {Concurrent Run With Promise}
315*/
316