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
qfuture.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*! \class QFuture
5 \inmodule QtCore
6 \threadsafe
7 \brief The QFuture class represents the result of an asynchronous computation.
8 \since 4.4
9
10 \ingroup thread
11
12 QFuture is a template class where the template parameter \a T specifies
13 the type of results that the asynchronous computation produces.
14
15 QFuture allows threads to be synchronized against one or more results
16 which will be ready at a later point in time. The result can be of any type
17 that has default, copy and possibly move constructors. If
18 a result is not available at the time of calling the result(), resultAt(),
19 results() and takeResult() functions, QFuture will wait until the result
20 becomes available. You can use the isResultReadyAt() function to determine
21 if a result is ready or not. For QFuture objects that report more than one
22 result, the resultCount() function returns the number of continuous results.
23 This means that it is always safe to iterate through the results from 0 to
24 resultCount(). takeResult() invalidates a future, and any subsequent attempt
25 to access result or results from the future leads to undefined behavior.
26 isValid() tells you if results can be accessed.
27
28 QFuture provides a \l{Java-style iterators}{Java-style iterator}
29 (QFutureIterator) and an \l{STL-style iterators}{STL-style iterator}
30 (QFuture::const_iterator). Using these iterators is another way to access
31 results in the future.
32
33 If the result of one asynchronous computation needs to be passed
34 to another, QFuture provides a convenient way of chaining multiple sequential
35 computations using then(). onCanceled() can be used for adding a handler to
36 be called if the QFuture is canceled. Additionally, onFailed() can be used
37 to handle any failures that occurred in the chain. Note that QFuture relies
38 on exceptions for the error handling. If using exceptions is not an option,
39 you can still indicate the error state of QFuture, by making the error type
40 part of the QFuture type. For example, you can use std::variant, std::any or
41 similar for keeping the result or failure or make your custom type.
42
43 The example below demonstrates how the error handling can be done without
44 using exceptions. Let's say we want to send a network request to obtain a large
45 file from a network location. Then we want to write it to the file system and
46 return its location in case of a success. Both of these operations may fail
47 with different errors. So, we use \c std::variant to keep the result
48 or error:
49
50 \snippet code/src_corelib_thread_qfuture.cpp 3
51
52 And we combine the two operations using then():
53
54 \snippet code/src_corelib_thread_qfuture.cpp 4
55
56 It's possible to chain multiple continuations and handlers in any order.
57 For example:
58
59 \snippet code/src_corelib_thread_qfuture.cpp 15
60
61 Depending on the state of \c testFuture (canceled, has exception or has a
62 result), the next onCanceled(), onFailed() or then() will be called. So
63 if \c testFuture is successfully fulfilled, \c {Block 1} will be called. If
64 it succeeds as well, the next then() (\c {Block 4}) is called. If \c testFuture
65 gets canceled or fails with an exception, either \c {Block 2} or \c {Block 3}
66 will be called respectively. The next then() will be called afterwards, and the
67 story repeats.
68
69 \note If \c {Block 2} is invoked and throws an exception, the following
70 onFailed() (\c {Block 3}) will handle it. If the order of onFailed() and
71 onCanceled() were reversed, the exception state would propagate to the
72 next continuations and eventually would be caught in \c {Block 5}.
73
74 In the next example the first onCanceled() (\c {Block 2}) is removed:
75
76 \snippet code/src_corelib_thread_qfuture.cpp 16
77
78 If \c testFuture gets canceled, its state is propagated to the next then(),
79 which will be also canceled. So in this case \c {Block 6} will be called.
80
81 The future can have only one continuation. Consider the following example:
82
83 \snippet code/src_corelib_thread_qfuture.cpp 31
84
85 In this case \c f1 and \c f2 are effectively the same QFuture object, as
86 they share the same internal state. As a result, calling
87 \l {QFuture::}{then} on \c f2 will overwrite the continuation specified for
88 \c {f1}. So, only \c {"second"} will be printed when this code is executed.
89
90 QFuture also offers ways to interact with a running computation. For
91 instance, the computation can be canceled with the cancel() function. To
92 suspend or resume the computation, use the setSuspended() function or one of
93 the suspend(), resume(), or toggleSuspended() convenience functions. Be aware
94 that not all running asynchronous computations can be canceled or suspended.
95 For example, the future returned by QtConcurrent::run() cannot be canceled;
96 but the future returned by QtConcurrent::mappedReduced() can.
97
98 Progress information is provided by the progressValue(),
99 progressMinimum(), progressMaximum(), and progressText() functions. The
100 waitForFinished() function causes the calling thread to block and wait for
101 the computation to finish, ensuring that all results are available.
102
103 The state of the computation represented by a QFuture can be queried using
104 the isCanceled(), isStarted(), isFinished(), isRunning(), isSuspending()
105 or isSuspended() functions.
106
107 QFuture<void> is specialized to not contain any of the result fetching
108 functions. Any QFuture<T> can be assigned or copied into a QFuture<void>
109 as well. This is useful if only status or progress information is needed
110 - not the actual result data.
111
112 To interact with running tasks using signals and slots, use QFutureWatcher.
113
114 You can also use QtFuture::connect() to connect signals to a QFuture object
115 which will be resolved when a signal is emitted. This allows working with
116 signals like with QFuture objects. For example, if you combine it with then(),
117 you can attach multiple continuations to a signal, which are invoked in the
118 same thread or a new thread.
119
120 The QtFuture::whenAll() and QtFuture::whenAny() functions can be used to
121 combine several futures and track when the last or first of them completes.
122
123 A ready QFuture object with a value or a QFuture object holding exception can
124 be created using convenience functions QtFuture::makeReadyVoidFuture(),
125 QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(), and
126 QtFuture::makeExceptionalFuture().
127
128 \note Some APIs (see \l {QFuture::then()} or various QtConcurrent method
129 overloads) allow scheduling the computation to a specific thread pool.
130 However, QFuture implements a work-stealing algorithm to prevent deadlocks
131 and optimize thread usage. As a result, computations can be executed
132 directly in the thread which requests the QFuture's result.
133
134 \note To start a computation and store results in a QFuture, use QPromise or
135 one of the APIs in the \l {Qt Concurrent} framework.
136
137 \sa QPromise, QtFuture::connect(), QtFuture::makeReadyVoidFuture(),
138 QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(),
139 QtFuture::makeExceptionalFuture(), QFutureWatcher, {Qt Concurrent}
140*/
141
142/*! \fn template <typename T> QFuture<T>::QFuture()
143
144 Constructs an empty, canceled future.
145*/
146
147/*! \fn template <typename T> QFuture<T>::QFuture(const QFuture<T> &other)
148
149 Constructs a copy of \a other.
150
151 \sa operator=()
152*/
153
154/*! \fn template <typename T> QFuture<T>::QFuture(QFutureInterface<T> *resultHolder)
155 \internal
156*/
157
158/*! \fn template <typename T> QFuture<T>::~QFuture()
159
160 Destroys the future.
161
162 Note that this neither waits nor cancels the asynchronous computation. Use
163 waitForFinished() or QFutureSynchronizer when you need to ensure that the
164 computation is completed before the future is destroyed.
165*/
166
167/*! \fn template <typename T> QFuture<T> &QFuture<T>::operator=(const QFuture<T> &other)
168
169 Assigns \a other to this future and returns a reference to this future.
170*/
171
172/*! \fn template <typename T> void QFuture<T>::cancel()
173
174 Cancels the asynchronous computation represented by this future. Note that
175 the cancellation is asynchronous. Use waitForFinished() after calling
176 cancel() when you need synchronous cancellation.
177
178 Results currently available may still be accessed on a canceled future,
179 but new results will \e not become available after calling this function.
180 Any QFutureWatcher object that is watching this future will not deliver
181 progress and result ready signals on a canceled future.
182
183 Be aware that not all running asynchronous computations can be canceled.
184 For example, the future returned by QtConcurrent::run() cannot be canceled;
185 but the future returned by QtConcurrent::mappedReduced() can.
186
187 \sa cancelChain()
188*/
189
190/*! \fn template <typename T> bool QFuture<T>::isCanceled() const
191
192 Returns \c true if the asynchronous computation has been canceled with the
193 cancel() function; otherwise returns \c false.
194
195 Be aware that the computation may still be running even though this
196 function returns \c true. See cancel() for more details.
197*/
198
199/*!
200 \fn template <typename T> void QFuture<T>::cancelChain()
201 \since 6.10
202
203 Cancels the entire continuation chain. All already-finished futures are
204 unchanged and their results are still available. Every pending continuation
205 is canceled, and its \l {onCanceled()} handler is called, if it exists in
206 the continuation chain.
207
208 \snippet code/src_corelib_thread_qfuture.cpp 38
209
210 In the example, if the chain is canceled before the \c {Then 2} continuation
211 is executed, both \c {OnCanceled 1} and \c {OnCanceled 2} cancellation
212 handlers will be invoked.
213
214 If the chain is canceled after \c {Then 2}, but before \c {Then 4}, then
215 only \c {OnCanceled 2} will be invoked.
216
217 \note When called on an already finished future, this method has no effect.
218 It's recommended to use it on the QFuture object that represents the entire
219 continuation chain, like it's shown in the example above.
220
221 If any of the continuations in the chain executes an asynchronous
222 computation and returns a QFuture representing it, the \c cancelChain() call
223 will not be propagated into such nested computation once it is started.
224 The reason for that is that the future will be available in the continuation
225 chain only when the outer future is fulfilled, but the cancellation might
226 happen when both an outer and a nested futures are still waiting for their
227 computations to be finished. In such cases, the nested future needs to be
228 captured and canceled explicitly.
229
230 \snippet code/src_corelib_thread_qfuture.cpp 39
231
232 In this example, if \c runNestedComputation() is already in progress,
233 it can only be canceled by calling \c {nested.cancel()}.
234
235 \sa cancel()
236*/
237
238#if QT_DEPRECATED_SINCE(6, 0)
239/*! \fn template <typename T> void QFuture<T>::setPaused(bool paused)
240
241 \deprecated [6.0] Use setSuspended() instead.
242
243 If \a paused is true, this function pauses the asynchronous computation
244 represented by the future. If the computation is already paused, this
245 function does nothing. Any QFutureWatcher object that is watching this
246 future will stop delivering progress and result ready signals while the
247 future is paused. Signal delivery will continue once the future is
248 resumed.
249
250 If \a paused is false, this function resumes the asynchronous computation.
251 If the computation was not previously paused, this function does nothing.
252
253 Be aware that not all computations can be paused. For example, the future
254 returned by QtConcurrent::run() cannot be paused; but the future returned
255 by QtConcurrent::mappedReduced() can.
256
257 \sa suspend(), resume(), toggleSuspended()
258*/
259
260/*! \fn template <typename T> bool QFuture<T>::isPaused() const
261
262 \deprecated [6.0] Use isSuspending() or isSuspended() instead.
263
264 Returns \c true if the asynchronous computation has been paused with the
265 pause() function; otherwise returns \c false.
266
267 Be aware that the computation may still be running even though this
268 function returns \c true. See setPaused() for more details. To check
269 if pause actually took effect, use isSuspended() instead.
270
271 \sa toggleSuspended(), isSuspended()
272*/
273
274/*! \fn template <typename T> void QFuture<T>::pause()
275
276 \deprecated [6.0] Use suspend() instead.
277
278 Pauses the asynchronous computation represented by this future. This is a
279 convenience method that simply calls setPaused(true).
280
281 \sa resume()
282*/
283
284/*! \fn template <typename T> void QFuture<T>::togglePaused()
285
286 \deprecated [6.0] Use toggleSuspended() instead.
287
288 Toggles the paused state of the asynchronous computation. In other words,
289 if the computation is currently paused, calling this function resumes it;
290 if the computation is running, it is paused. This is a convenience method
291 for calling setPaused(!isPaused()).
292
293 \sa setSuspended(), suspend(), resume()
294*/
295#endif // QT_DEPRECATED_SINCE(6, 0)
296
297/*! \fn template <typename T> void QFuture<T>::setSuspended(bool suspend)
298
299 \since 6.0
300
301 If \a suspend is true, this function suspends the asynchronous computation
302 represented by the future(). If the computation is already suspended, this
303 function does nothing. QFutureWatcher will not immediately stop delivering
304 progress and result ready signals when the future is suspended. At the moment
305 of suspending there may still be computations that are in progress and cannot
306 be stopped. Signals for such computations will still be delivered.
307
308 If \a suspend is false, this function resumes the asynchronous computation.
309 If the computation was not previously suspended, this function does nothing.
310
311 Be aware that not all computations can be suspended. For example, the
312 QFuture returned by QtConcurrent::run() cannot be suspended; but the QFuture
313 returned by QtConcurrent::mappedReduced() can.
314
315 \sa suspend(), resume(), toggleSuspended()
316*/
317
318/*! \fn template <typename T> bool QFuture<T>::isSuspending() const
319
320 \since 6.0
321
322 Returns \c true if the asynchronous computation has been suspended with the
323 suspend() function, but the work is not yet suspended, and computation is still
324 running. Returns \c false otherwise.
325
326 To check if suspension is actually in effect, use isSuspended() instead.
327
328 \sa setSuspended(), toggleSuspended(), isSuspended()
329*/
330
331/*! \fn template <typename T> bool QFuture<T>::isSuspended() const
332
333 \since 6.0
334
335 Returns \c true if a suspension of the asynchronous computation has been
336 requested, and it is in effect, meaning that no more results or progress
337 changes are expected.
338
339 \sa setSuspended(), toggleSuspended(), isSuspending()
340*/
341
342/*! \fn template <typename T> void QFuture<T>::suspend()
343
344 \since 6.0
345
346 Suspends the asynchronous computation represented by this future. This is a
347 convenience method that simply calls setSuspended(true).
348
349 \sa resume()
350*/
351
352/*! \fn template <typename T> void QFuture<T>::resume()
353
354 Resumes the asynchronous computation represented by the future(). This is
355 a convenience method that simply calls setSuspended(false).
356
357 \sa suspend()
358*/
359
360/*! \fn template <typename T> void QFuture<T>::toggleSuspended()
361
362 \since 6.0
363
364 Toggles the suspended state of the asynchronous computation. In other words,
365 if the computation is currently suspending or suspended, calling this
366 function resumes it; if the computation is running, it is suspended. This is a
367 convenience method for calling setSuspended(!(isSuspending() || isSuspended())).
368
369 \sa setSuspended(), suspend(), resume()
370*/
371
372/*! \fn template <typename T> bool QFuture<T>::isStarted() const
373
374 Returns \c true if the asynchronous computation represented by this future
375 has been started; otherwise returns \c false.
376*/
377
378/*! \fn template <typename T> bool QFuture<T>::isFinished() const
379
380 Returns \c true if the asynchronous computation represented by this future
381 has finished; otherwise returns \c false.
382*/
383
384/*! \fn template <typename T> bool QFuture<T>::isRunning() const
385
386 Returns \c true if the asynchronous computation represented by this future is
387 currently running; otherwise returns \c false.
388*/
389
390/*! \fn template <typename T> int QFuture<T>::resultCount() const
391
392 Returns the number of continuous results available in this future. The real
393 number of results stored might be different from this value, due to gaps
394 in the result set. It is always safe to iterate through the results from 0
395 to resultCount().
396 \sa result(), resultAt(), results(), takeResult()
397*/
398
399/*! \fn template <typename T> int QFuture<T>::progressValue() const
400
401 Returns the current progress value, which is between the progressMinimum()
402 and progressMaximum().
403
404 \sa progressMinimum(), progressMaximum()
405*/
406
407/*! \fn template <typename T> int QFuture<T>::progressMinimum() const
408
409 Returns the minimum progressValue().
410
411 \sa progressValue(), progressMaximum()
412*/
413
414/*! \fn template <typename T> int QFuture<T>::progressMaximum() const
415
416 Returns the maximum progressValue().
417
418 \sa progressValue(), progressMinimum()
419*/
420
421/*! \fn template <typename T> QString QFuture<T>::progressText() const
422
423 Returns the (optional) textual representation of the progress as reported
424 by the asynchronous computation.
425
426 Be aware that not all computations provide a textual representation of the
427 progress, and as such, this function may return an empty string.
428*/
429
430/*! \fn template <typename T> void QFuture<T>::waitForFinished()
431
432 Waits for the asynchronous computation to finish (including cancel()ed
433 computations), i.e. until isFinished() returns \c true.
434*/
435
436/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture<T>::result() const
437
438 Returns the first result in the future. If the result is not immediately
439 available, this function will block and wait for the result to become
440 available. This is a convenience method for calling resultAt(0). Note
441 that \c result() returns a copy of the internally stored result. If \c T is
442 a move-only type, or you don't want to copy the result, use takeResult()
443 instead.
444
445//! [ub_when_invalid]
446 \note Calling this function leads to undefined behavior if isValid()
447 returns \c false for this QFuture. If this QFuture is not yet started, call
448 waitForFinished() before calling this function to avoid undefiend behavior.
449//! [ub_when_invalid]
450
451 \sa resultAt(), results(), takeResult()
452*/
453
454/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture<T>::resultAt(int index) const
455
456 Returns the result at \a index in the future. If the result is not
457 immediately available, this function will block and wait for the result to
458 become available.
459
460 \include qfuture.qdoc ub_when_invalid
461
462 \sa result(), results(), takeResult(), resultCount()
463*/
464
465/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture<T>::isResultReadyAt(int index) const
466
467 Returns \c true if the result at \a index is immediately available; otherwise
468 returns \c false.
469
470 \include qfuture.qdoc ub_when_invalid
471
472 \sa resultAt(), resultCount(), takeResult()
473*/
474
475/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture<T>::results() const
476
477 Returns all results from the future. If the results are not immediately available,
478 this function will block and wait for them to become available. Note that
479 \c results() returns a copy of the internally stored results. Getting all
480 results of a move-only type \c T is not supported at the moment. However you can
481 still iterate through the list of move-only results by using \l{STL-style iterators}
482 or read-only \l{Java-style iterators}.
483
484 \include qfuture.qdoc ub_when_invalid
485
486 \sa result(), resultAt(), takeResult(), resultCount(), isValid()
487*/
488
489#if 0
490/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> std::vector<T> QFuture<T>::takeResults()
491
492 If isValid() returns \c false, calling this function leads to undefined behavior.
493 takeResults() takes all results from the QFuture object and invalidates it
494 (isValid() will return \c false for this future). If the results are
495 not immediately available, this function will block and wait for them to
496 become available. This function tries to use move semantics for the results
497 if available and falls back to copy construction if the type is not movable.
498
499 \note QFuture in general allows sharing the results between different QFuture
500 objects (and potentially between different threads). takeResults() was introduced
501 to make QFuture also work with move-only types (like std::unique_ptr), so it
502 assumes that only one thread can move the results out of the future, and only
503 once.
504
505 \sa takeResult(), result(), resultAt(), results(), resultCount(), isValid()
506*/
507#endif
508
509/*! \fn template <typename T> template<typename U = T, typename = QtPrivate::EnableForNonVoid<U>> std::vector<T> QFuture<T>::takeResult()
510
511 \since 6.0
512
513 Call this function only if isValid() returns \c true, otherwise
514 the behavior is undefined. This function takes (moves) the first result from
515 the QFuture object, when only one result is expected. If there are any other
516 results, they are discarded after taking the first one.
517 If the result is not immediately available, this function will block and
518 wait for the result to become available. The QFuture will try to use move
519 semantics if possible, and will fall back to copy construction if the type
520 is not movable. After the result was taken, isValid() will evaluate
521 as \c false.
522
523 \note QFuture in general allows sharing the results between different QFuture
524 objects (and potentially between different threads). takeResult() was introduced
525 to make QFuture also work with move-only types (like std::unique_ptr), so it
526 assumes that only one thread can move the results out of the future, and
527 do it only once. Also note that taking the list of all results is not supported
528 at the moment. However you can still iterate through the list of move-only
529 results by using \l{STL-style iterators} or read-only \l{Java-style iterators}.
530
531 \sa result(), results(), resultAt(), isValid()
532*/
533
534/*! \fn template <typename T> bool QFuture<T>::isValid() const
535
536 \since 6.0
537
538 Returns \c true if a result or results can be accessed or taken from this
539 QFuture object. Returns \c false if the related QPromise has not yet
540 started or the result has already been collected from the future.
541
542 \note The return value of this function only implies whether the future
543 result can be consumed, not if it is ready. This function will return
544 \c true when the related QPromise is started, but the result is not yet
545 ready. To test readiness, call \l isResultReadyAt() or \l isFinished().
546
547 \sa takeResult(), result(), results(), resultAt(), isFinished(),
548 isResultReadyAt()
549*/
550
551/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::begin() const
552
553 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the
554 future.
555
556 \sa constBegin(), end()
557*/
558
559/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::end() const
560
561 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result
562 after the last result in the future.
563
564 \sa begin(), constEnd()
565*/
566
567/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::constBegin() const
568
569 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the
570 future.
571
572 \sa begin(), constEnd()
573*/
574
575/*! \fn template<typename T> template<class U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture<T>::constEnd() const
576
577 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result
578 after the last result in the future.
579
580 \sa constBegin(), end()
581*/
582
583/*! \class QFuture::const_iterator
584 \reentrant
585 \since 4.4
586 \inmodule QtCore
587
588 \brief The QFuture::const_iterator class provides an STL-style const
589 iterator for QFuture.
590
591 QFuture provides both \l{STL-style iterators} and \l{Java-style iterators}.
592 The STL-style iterators are more low-level and more cumbersome to use; on
593 the other hand, they are slightly faster and, for developers who already
594 know STL, have the advantage of familiarity.
595
596 The default QFuture::const_iterator constructor creates an uninitialized
597 iterator. You must initialize it using a QFuture function like
598 QFuture::constBegin() or QFuture::constEnd() before you start iterating.
599 Here's a typical loop that prints all the results available in a future:
600
601 \snippet code/src_corelib_thread_qfuture.cpp 0
602
603 \sa QFutureIterator, QFuture
604*/
605
606/*! \typedef QFuture::const_iterator::iterator_category
607
608 Typedef for std::bidirectional_iterator_tag. Provided for STL compatibility.
609*/
610
611/*! \typedef QFuture::const_iterator::difference_type
612
613 Typedef for ptrdiff_t. Provided for STL compatibility.
614*/
615
616/*! \typedef QFuture::const_iterator::value_type
617
618 Typedef for T. Provided for STL compatibility.
619*/
620
621/*! \typedef QFuture::const_iterator::pointer
622
623 Typedef for const T *. Provided for STL compatibility.
624*/
625
626/*! \typedef QFuture::const_iterator::reference
627
628 Typedef for const T &. Provided for STL compatibility.
629*/
630
631/*! \fn template <typename T> QFuture<T>::const_iterator::const_iterator()
632
633 Constructs an uninitialized iterator.
634
635 Functions like operator*() and operator++() should not be called on an
636 uninitialized iterartor. Use operator=() to assign a value to it before
637 using it.
638
639 \sa QFuture::constBegin(), QFuture::constEnd()
640*/
641
642/*! \fn template <typename T> QFuture<T>::const_iterator::const_iterator(QFuture const * const future, int index)
643 \internal
644*/
645
646/*! \fn template <typename T> QFuture<T>::const_iterator::const_iterator(const const_iterator &other)
647
648 Constructs a copy of \a other.
649*/
650
651/*! \fn template <typename T> QFuture<T>::const_iterator &QFuture<T>::const_iterator::operator=(const const_iterator &other)
652
653 Assigns \a other to this iterator.
654*/
655
656/*! \fn template <typename T> const T &QFuture<T>::const_iterator::operator*() const
657
658 Returns the current result.
659*/
660
661/*! \fn template <typename T> const T *QFuture<T>::const_iterator::operator->() const
662
663 Returns a pointer to the current result.
664*/
665
666/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
667
668 Returns \c true if \a lhs points to a different result than \a rhs iterator;
669 otherwise returns \c false.
670
671 \sa operator==()
672*/
673
674/*! \fn template <typename T> bool QFuture<T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
675
676 Returns \c true if \a lhs points to the same result as \a rhs iterator;
677 otherwise returns \c false.
678
679 \sa operator!=()
680*/
681
682/*! \fn template <typename T> QFuture<T>::const_iterator &QFuture<T>::const_iterator::operator++()
683
684 The prefix \c{++} operator (\c{++it}) advances the iterator to the next result
685 in the future and returns an iterator to the new current result.
686
687 Calling this function on QFuture<T>::constEnd() leads to undefined results.
688
689 \sa operator--()
690*/
691
692/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::const_iterator::operator++(int)
693
694 \overload
695
696 The postfix \c{++} operator (\c{it++}) advances the iterator to the next
697 result in the future and returns an iterator to the previously current
698 result.
699*/
700
701/*! \fn template <typename T> QFuture<T>::const_iterator &QFuture<T>::const_iterator::operator--()
702
703 The prefix \c{--} operator (\c{--it}) makes the preceding result current and
704 returns an iterator to the new current result.
705
706 Calling this function on QFuture<T>::constBegin() leads to undefined results.
707
708 \sa operator++()
709*/
710
711/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::const_iterator::operator--(int)
712
713 \overload
714
715 The postfix \c{--} operator (\c{it--}) makes the preceding result current and
716 returns an iterator to the previously current result.
717*/
718
719/*! \fn template <typename T> QFuture<T>::const_iterator &QFuture<T>::const_iterator::operator+=(int j)
720
721 Advances the iterator by \a j results. (If \a j is negative, the iterator
722 goes backward.)
723
724 \sa operator-=(), operator+()
725*/
726
727/*! \fn template <typename T> QFuture<T>::const_iterator &QFuture<T>::const_iterator::operator-=(int j)
728
729 Makes the iterator go back by \a j results. (If \a j is negative, the
730 iterator goes forward.)
731
732 \sa operator+=(), operator-()
733*/
734
735/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::const_iterator::operator+(int j) const
736
737 Returns an iterator to the results at \a j positions forward from this
738 iterator. (If \a j is negative, the iterator goes backward.)
739
740 \sa operator-(), operator+=()
741*/
742
743/*! \fn template <typename T> QFuture<T>::const_iterator QFuture<T>::const_iterator::operator-(int j) const
744
745 Returns an iterator to the result at \a j positions backward from this
746 iterator. (If \a j is negative, the iterator goes forward.)
747
748 \sa operator+(), operator-=()
749*/
750
751/*! \typedef QFuture::ConstIterator
752
753 Qt-style synonym for QFuture::const_iterator.
754*/
755
756/*!
757 \class QFutureIterator
758 \reentrant
759 \since 4.4
760 \inmodule QtCore
761
762 \brief The QFutureIterator class provides a Java-style const iterator for
763 QFuture.
764
765 QFutureIterator<T> is a template class where \a T specifies the result
766 type of the QFuture being iterated over.
767
768 QFuture has both \l{Java-style iterators} and \l{STL-style iterators}. The
769 Java-style iterators are more high-level and easier to use than the
770 STL-style iterators; on the other hand, they are slightly less efficient.
771
772 An alternative to using iterators is to use index positions. Some QFuture
773 member functions take an index as their first parameter, making it
774 possible to access results without using iterators.
775
776 QFutureIterator<T> allows you to iterate over a QFuture<T>. Note that
777 there is no mutable iterator for QFuture (unlike the other Java-style
778 iterators).
779
780 The QFutureIterator constructor takes a QFuture as its argument. After
781 construction, the iterator is located at the very beginning of the result
782 list (i.e. before the first result). Here's how to iterate over all the
783 results sequentially:
784
785 \snippet code/src_corelib_thread_qfuture.cpp 1
786
787 The next() function returns the next result (waiting for it to become
788 available, if necessary) from the future and advances the iterator. Unlike
789 STL-style iterators, Java-style iterators point \e between results rather
790 than directly \e at results. The first call to next() advances the iterator
791 to the position between the first and second result, and returns the first
792 result; the second call to next() advances the iterator to the position
793 between the second and third result, and returns the second result; and
794 so on.
795
796 \image javaiterators1.svg
797
798 Here's how to iterate over the elements in reverse order:
799
800 \snippet code/src_corelib_thread_qfuture.cpp 2
801
802 If you want to find all occurrences of a particular value, use findNext()
803 or findPrevious() in a loop.
804
805 Multiple iterators can be used on the same future. If the future is
806 modified while a QFutureIterator is active, the QFutureIterator will
807 continue iterating over the original future, ignoring the modified copy.
808
809 \sa QFuture::const_iterator, QFuture
810*/
811
812/*!
813 \fn template <typename T> QFutureIterator<T>::QFutureIterator(const QFuture<T> &future)
814
815 Constructs an iterator for traversing \a future. The iterator is set to be
816 at the front of the result list (before the first result).
817
818 \sa operator=()
819*/
820
821/*! \fn template <typename T> QFutureIterator<T> &QFutureIterator<T>::operator=(const QFuture<T> &future)
822
823 Makes the iterator operate on \a future. The iterator is set to be at the
824 front of the result list (before the first result).
825
826 \sa toFront(), toBack()
827*/
828
829/*! \fn template <typename T> void QFutureIterator<T>::toFront()
830
831 Moves the iterator to the front of the result list (before the first
832 result).
833
834 \sa toBack(), next()
835*/
836
837/*! \fn template <typename T> void QFutureIterator<T>::toBack()
838
839 Moves the iterator to the back of the result list (after the last result).
840
841 \sa toFront(), previous()
842*/
843
844/*! \fn template <typename T> bool QFutureIterator<T>::hasNext() const
845
846 Returns \c true if there is at least one result ahead of the iterator, e.g.,
847 the iterator is \e not at the back of the result list; otherwise returns
848 false.
849
850 \sa hasPrevious(), next()
851*/
852
853/*! \fn template <typename T> const T &QFutureIterator<T>::next()
854
855 Returns the next result and advances the iterator by one position.
856
857 Calling this function on an iterator located at the back of the result
858 list leads to undefined results.
859
860 \sa hasNext(), peekNext(), previous()
861*/
862
863/*! \fn template <typename T> const T &QFutureIterator<T>::peekNext() const
864
865 Returns the next result without moving the iterator.
866
867 Calling this function on an iterator located at the back of the result
868 list leads to undefined results.
869
870 \sa hasNext(), next(), peekPrevious()
871*/
872
873/*! \fn template <typename T> bool QFutureIterator<T>::hasPrevious() const
874
875 Returns \c true if there is at least one result ahead of the iterator, e.g.,
876 the iterator is \e not at the front of the result list; otherwise returns
877 false.
878
879 \sa hasNext(), previous()
880*/
881
882/*! \fn template <typename T> const T &QFutureIterator<T>::previous()
883
884 Returns the previous result and moves the iterator back by one position.
885
886 Calling this function on an iterator located at the front of the result
887 list leads to undefined results.
888
889 \sa hasPrevious(), peekPrevious(), next()
890*/
891
892/*! \fn template <typename T> const T &QFutureIterator<T>::peekPrevious() const
893
894 Returns the previous result without moving the iterator.
895
896 Calling this function on an iterator located at the front of the result
897 list leads to undefined results.
898
899 \sa hasPrevious(), previous(), peekNext()
900*/
901
902/*! \fn template <typename T> bool QFutureIterator<T>::findNext(const T &value)
903
904 Searches for \a value starting from the current iterator position forward.
905 Returns \c true if \a value is found; otherwise returns \c false.
906
907 After the call, if \a value was found, the iterator is positioned just
908 after the matching result; otherwise, the iterator is positioned at the
909 back of the result list.
910
911 \sa findPrevious()
912*/
913
914/*! \fn template <typename T> bool QFutureIterator<T>::findPrevious(const T &value)
915
916 Searches for \a value starting from the current iterator position
917 backward. Returns \c true if \a value is found; otherwise returns \c false.
918
919 After the call, if \a value was found, the iterator is positioned just
920 before the matching result; otherwise, the iterator is positioned at the
921 front of the result list.
922
923 \sa findNext()
924*/
925
926/*!
927 \namespace QtFuture
928 \inheaderfile QFuture
929
930 \inmodule QtCore
931 \brief Contains miscellaneous identifiers used by the QFuture class.
932*/
933
934
935/*!
936 \enum QtFuture::Launch
937
938 \since 6.0
939
940 Represents execution policies for running a QFuture continuation.
941
942 \value Sync The continuation will be launched in the same thread that
943 fulfills the promise associated with the future to which the
944 continuation was attached, or if it has already finished, the
945 continuation will be invoked immediately, in the thread that
946 executes \c then().
947
948 \value Async The continuation will be launched in a separate thread taken from
949 the global QThreadPool.
950
951 \value Inherit The continuation will inherit the launch policy or thread pool of
952 the future to which it is attached.
953
954 \c Sync is used as a default launch policy.
955
956 \sa QFuture::then(), QThreadPool::globalInstance()
957
958*/
959
960/*!
961 \class QtFuture::WhenAnyResult
962 \inmodule QtCore
963 \ingroup thread
964 \brief QtFuture::WhenAnyResult is used to represent the result of QtFuture::whenAny().
965 \since 6.3
966
967 WhenAnyResult<T> is a template struct where \a T specifies the result
968 type of the futures.
969
970 The \c {QtFuture::WhenAnyResult<T>} struct is used for packaging the copy and
971 the index of the first completed \c QFuture<T> in the sequence of futures
972 packaging type \c T that are passed to QtFuture::whenAny().
973
974 \sa QFuture, QtFuture::whenAny()
975*/
976
977/*!
978 \variable QtFuture::WhenAnyResult::index
979
980 The field contains the index of the first completed QFuture in the sequence
981 of futures passed to whenAny(). It has type \c qsizetype.
982
983 \sa QtFuture::whenAny()
984*/
985
986/*!
987 \variable QtFuture::WhenAnyResult::future
988
989 The field contains the copy of the first completed QFuture that packages type
990 \c T, where \c T is the type packaged by the futures passed to whenAny().
991
992 \sa QtFuture::whenAny()
993*/
994
995/*! \fn template<class Sender, class Signal, typename = QtPrivate::EnableIfInvocable<Sender, Signal>> static QFuture<ArgsType<Signal>> QtFuture::connect(Sender *sender, Signal signal)
996
997 Creates and returns a QFuture which will become available when the \a sender emits
998 the \a signal. If the \a signal takes no arguments, a QFuture<void> is returned. If
999 the \a signal takes a single argument, the resulted QFuture will be filled with the
1000 signal's argument value. If the \a signal takes multiple arguments, the resulted QFuture
1001 is filled with std::tuple storing the values of signal's arguments. If the \a sender
1002 is destroyed before the \a signal is emitted, the resulted QFuture will be canceled.
1003
1004 For example, let's say we have the following object:
1005
1006 \snippet code/src_corelib_thread_qfuture.cpp 10
1007
1008 We can connect its signals to QFuture objects in the following way:
1009
1010 \snippet code/src_corelib_thread_qfuture.cpp 11
1011
1012 We can also chain continuations to be run when a signal is emitted:
1013
1014 \snippet code/src_corelib_thread_qfuture.cpp 12
1015
1016 You can also start the continuation in a new thread or a custom thread pool
1017 using QtFuture::Launch policies. For example:
1018
1019 \snippet code/src_corelib_thread_qfuture.cpp 13
1020
1021 Throwing an exception from a slot invoked by Qt's signal-slot connection
1022 is considered to be an undefined behavior, if it is not handled within the
1023 slot. But with QFuture::connect(), you can throw and handle exceptions from
1024 the continuations:
1025
1026 \snippet code/src_corelib_thread_qfuture.cpp 14
1027
1028 \note The connected future will be fulfilled only once, when the signal is
1029 emitted for the first time.
1030
1031 \sa QFuture, QFuture::then()
1032*/
1033
1034/*! \fn template<typename T, typename = QtPrivate::EnableForNonVoid<T>> static QFuture<std::decay_t<T>> QtFuture::makeReadyFuture(T &&value)
1035
1036 \since 6.1
1037 \overload
1038 \deprecated [6.6] Use makeReadyValueFuture() instead.
1039
1040 Creates and returns a QFuture which already has a result \a value.
1041 The returned QFuture has a type of std::decay_t<T>, where T is not void.
1042
1043 \code
1044 auto f = QtFuture::makeReadyFuture(std::make_unique<int>(42));
1045 ...
1046 const int result = *f.takeResult(); // result == 42
1047 \endcode
1048
1049 The method should be avoided because
1050 it has an inconsistent set of overloads. From Qt 6.10 onwards, using it
1051 in code will result in compiler warnings.
1052
1053 \sa QFuture, QtFuture::makeReadyVoidFuture(),
1054 QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(),
1055 QtFuture::makeExceptionalFuture()
1056*/
1057
1058/*! \fn QFuture<void> QtFuture::makeReadyFuture()
1059
1060 \since 6.1
1061 \overload
1062 \deprecated [6.6] Use makeReadyVoidFuture() instead.
1063
1064 Creates and returns a void QFuture. Such QFuture can't store any result.
1065 One can use it to query the state of the computation.
1066 The returned QFuture will always be in the finished state.
1067
1068 \code
1069 auto f = QtFuture::makeReadyFuture();
1070 ...
1071 const bool started = f.isStarted(); // started == true
1072 const bool running = f.isRunning(); // running == false
1073 const bool finished = f.isFinished(); // finished == true
1074 \endcode
1075
1076 The method should be avoided because
1077 it has an inconsistent set of overloads. From Qt 6.10 onwards, using it
1078 in code will result in compiler warnings.
1079
1080 \sa QFuture, QFuture::isStarted(), QFuture::isRunning(),
1081 QFuture::isFinished(), QtFuture::makeReadyVoidFuture(),
1082 QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(),
1083 QtFuture::makeExceptionalFuture()
1084*/
1085
1086/*! \fn template<typename T> static QFuture<T> QtFuture::makeReadyFuture(const QList<T> &values)
1087
1088 \since 6.1
1089 \overload
1090 \deprecated [6.6] Use makeReadyRangeFuture() instead.
1091
1092 Creates and returns a QFuture which already has multiple results set from \a values.
1093
1094 \code
1095 const QList<int> values { 1, 2, 3 };
1096 auto f = QtFuture::makeReadyFuture(values);
1097 ...
1098 const int count = f.resultCount(); // count == 3
1099 const auto results = f.results(); // results == { 1, 2, 3 }
1100 \endcode
1101
1102 The method should be avoided because
1103 it has an inconsistent set of overloads. From Qt 6.10 onwards, using it
1104 in code will result in compiler warnings.
1105
1106 \sa QFuture, QtFuture::makeReadyVoidFuture(),
1107 QtFuture::makeReadyValueFuture(), QtFuture::makeReadyRangeFuture(),
1108 QtFuture::makeExceptionalFuture()
1109*/
1110
1111/*! \fn template<typename T> static QFuture<std::decay_t<T>> QtFuture::makeReadyValueFuture(T &&value)
1112
1113 \since 6.6
1114
1115 Creates and returns a QFuture which already has a result \a value.
1116 The returned QFuture has a type of std::decay_t<T>, where T is not void.
1117 The returned QFuture will already be in the finished state.
1118
1119 \snippet code/src_corelib_thread_qfuture.cpp 35
1120
1121 \sa QFuture, QtFuture::makeReadyRangeFuture(),
1122 QtFuture::makeReadyVoidFuture(), QtFuture::makeExceptionalFuture()
1123*/
1124
1125/*! \fn QFuture<void> QtFuture::makeReadyVoidFuture()
1126
1127 \since 6.6
1128
1129 Creates and returns a void QFuture. Such QFuture can't store any result.
1130 One can use it to query the state of the computation.
1131 The returned QFuture will already be in the finished state.
1132
1133 \snippet code/src_corelib_thread_qfuture.cpp 36
1134
1135 \sa QFuture, QFuture::isStarted(), QFuture::isRunning(),
1136 QFuture::isFinished(), QtFuture::makeReadyValueFuture(),
1137 QtFuture::makeReadyRangeFuture(), QtFuture::makeExceptionalFuture()
1138*/
1139
1140/*! \fn template<typename T> static QFuture<T> QtFuture::makeExceptionalFuture(const QException &exception)
1141
1142 \since 6.1
1143
1144 Creates and returns a QFuture which already has an exception \a exception.
1145
1146 \code
1147 QException e;
1148 auto f = QtFuture::makeExceptionalFuture<int>(e);
1149 ...
1150 try {
1151 f.result(); // throws QException
1152 } catch (QException &) {
1153 // handle exception here
1154 }
1155 \endcode
1156
1157 \sa QFuture, QException, QtFuture::makeReadyVoidFuture(),
1158 QtFuture::makeReadyValueFuture()
1159*/
1160
1161/*! \fn template<typename T> static QFuture<T> QtFuture::makeExceptionalFuture(std::exception_ptr exception)
1162
1163 \since 6.1
1164 \overload
1165
1166 Creates and returns a QFuture which already has an exception \a exception.
1167
1168 \code
1169 struct TestException
1170 {
1171 };
1172 ...
1173 auto exception = std::make_exception_ptr(TestException());
1174 auto f = QtFuture::makeExceptionalFuture<int>(exception);
1175 ...
1176 try {
1177 f.result(); // throws TestException
1178 } catch (TestException &) {
1179 // handle exception here
1180 }
1181 \endcode
1182
1183 \sa QFuture, QException, QtFuture::makeReadyVoidFuture(),
1184 QtFuture::makeReadyValueFuture()
1185*/
1186
1187/*! \fn template<typename Container, QtFuture::if_container_with_input_iterators<Container>> static QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)
1188
1189 \since 6.6
1190 \overload
1191
1192 Takes an input container \a container and returns a QFuture with multiple
1193 results of type \c ContainedType initialized from the values of the
1194 \a container.
1195
1196 \snippet code/src_corelib_thread_qfuture.cpp 32
1197 \dots
1198 \snippet code/src_corelib_thread_qfuture.cpp 34
1199
1200 \constraints the \c Container has input iterators.
1201
1202 \sa QFuture, QtFuture::makeReadyVoidFuture(),
1203 QtFuture::makeReadyValueFuture(), QtFuture::makeExceptionalFuture()
1204*/
1205
1206/*! \fn template<typename ValueType> static QFuture<ValueType> QtFuture::makeReadyRangeFuture(std::initializer_list<ValueType> values)
1207
1208 \since 6.6
1209 \overload
1210
1211 Returns a QFuture with multiple results of type \c ValueType initialized
1212 from the input initializer list \a values.
1213
1214 \snippet code/src_corelib_thread_qfuture.cpp 33
1215 \dots
1216 \snippet code/src_corelib_thread_qfuture.cpp 34
1217
1218 \sa QFuture, QtFuture::makeReadyVoidFuture(),
1219 QtFuture::makeReadyValueFuture(), QtFuture::makeExceptionalFuture()
1220*/
1221
1222/*! \fn template<class T> template<class Function> QFuture<typename QFuture<T>::ResultType<Function>> QFuture<T>::then(Function &&function)
1223
1224 \since 6.0
1225 \overload
1226
1227 Attaches a continuation to this future, allowing to chain multiple asynchronous
1228 computations if desired, using the \l {QtFuture::Launch}{Sync} policy.
1229 \a function is a callable that takes an argument of the type packaged by this
1230 future if this has a result (is not a QFuture<void>). Otherwise it takes no
1231 arguments. This method returns a new QFuture that packages a value of the type
1232 returned by \a function. The returned future will be in an uninitialized state
1233 until the attached continuation is invoked, or until this future fails or is
1234 canceled.
1235
1236 \note Use other overloads of this method if you need to launch the continuation in
1237 a separate thread.
1238
1239 You can chain multiple operations like this:
1240
1241 \code
1242 QFuture<int> future = ...;
1243 future.then([](int res1){ ... }).then([](int res2){ ... })...
1244 \endcode
1245
1246 Or:
1247 \code
1248 QFuture<void> future = ...;
1249 future.then([](){ ... }).then([](){ ... })...
1250 \endcode
1251
1252 The continuation can also take a QFuture argument (instead of its value), representing
1253 the previous future. This can be useful if, for example, QFuture has multiple results,
1254 and the user wants to access them inside the continuation. Or the user needs to handle
1255 the exception of the previous future inside the continuation, to not interrupt the chain
1256 of multiple continuations. For example:
1257
1258 \snippet code/src_corelib_thread_qfuture.cpp 5
1259
1260 \warning If the previous future contains multiple results of type \c {T},
1261 and the continuation takes an argument of type \c {T} as a parameter, only
1262 the first result from the previous QFuture will be handled in the
1263 continuation!
1264
1265 If the previous future throws an exception and it is not handled inside the
1266 continuation, the exception will be propagated to the continuation future, to
1267 allow the caller to handle it:
1268
1269 \snippet code/src_corelib_thread_qfuture.cpp 6
1270
1271 In this case the whole chain of continuations will be interrupted.
1272
1273 \note If this future gets canceled, the continuations attached to it will
1274 also be canceled.
1275
1276 \sa onFailed(), onCanceled()
1277*/
1278
1279/*! \fn template<class T> template<class Function> QFuture<typename QFuture<T>::ResultType<Function>> QFuture<T>::then(QtFuture::Launch policy, Function &&function)
1280
1281 \since 6.0
1282 \overload
1283
1284 Attaches a continuation to this future, allowing to chain multiple asynchronous
1285 computations. When the asynchronous computation represented by this future
1286 finishes, \a function will be invoked according to the given launch \a policy.
1287 A new QFuture representing the result of the continuation is returned.
1288
1289 Depending on the \a policy, continuation will be invoked in the same thread as
1290 this future, in a new thread, or will inherit the launch policy and thread pool of
1291 this future. If no launch policy is specified (see the overload taking only a callable),
1292 the \c Sync policy will be used.
1293
1294 In the following example both continuations will be invoked in a new thread (but in
1295 the same one).
1296
1297 \code
1298 QFuture<int> future = ...;
1299 future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });
1300 \endcode
1301
1302 In the following example both continuations will be invoked in new threads using the
1303 same thread pool.
1304
1305 \code
1306 QFuture<int> future = ...;
1307 future.then(QtFuture::Launch::Async, [](int res){ ... })
1308 .then(QtFuture::Launch::Inherit, [](int res2){ ... });
1309 \endcode
1310
1311 See the documentation of the other overload for more details about \a function.
1312
1313 \sa onFailed(), onCanceled()
1314*/
1315
1316/*! \fn template<class T> template<class Function> QFuture<typename QFuture<T>::ResultType<Function>> QFuture<T>::then(QThreadPool *pool, Function &&function)
1317
1318 \since 6.0
1319 \overload
1320
1321 Attaches a continuation to this future, allowing to chain multiple asynchronous
1322 computations if desired. When the asynchronous computation represented by this
1323 future finishes, \a function will be scheduled on \a pool.
1324
1325 \sa onFailed(), onCanceled()
1326*/
1327
1328/*! \fn template<class T> template<class Function> QFuture<typename QFuture<T>::ResultType<Function>> QFuture<T>::then(QObject *context, Function &&function)
1329
1330 \since 6.1
1331 \overload
1332
1333 Attaches a continuation to this future, allowing to chain multiple asynchronous
1334 computations if desired. When the asynchronous computation represented by this
1335 future finishes, \a function will be invoked in the thread of the \a context object.
1336 This can be useful if the continuation needs to be invoked in a specific thread.
1337 For example:
1338
1339 \snippet code/src_corelib_thread_qfuture.cpp 17
1340
1341 The continuation attached into QtConcurrent::run updates the UI elements and cannot
1342 be invoked from a non-gui thread. So \c this is provided as a context to \c .then(),
1343 to make sure that it will be invoked in the main thread.
1344
1345 The following continuations will be also invoked from the same context,
1346 unless a different context or launch policy is specified:
1347
1348 \snippet code/src_corelib_thread_qfuture.cpp 18
1349
1350 This is because by default \c .then() is invoked from the same thread as the
1351 previous one.
1352
1353 But note that if the continuation is attached after this future has already finished,
1354 it will be invoked immediately, in the thread that executes \c then():
1355
1356 \snippet code/src_corelib_thread_qfuture.cpp 20
1357
1358 In the above example if \c cachedResultsReady is \c true, and a ready future is
1359 returned, it is possible that the first \c .then() finishes before the second one
1360 is attached. In this case it will be resolved in the current thread. Therefore, when
1361 in doubt, pass the context explicitly.
1362
1363 \target context_lifetime
1364 If the \a context is destroyed before the chain has finished, the future is canceled.
1365 This implies that a cancellation handler might be invoked when the \a context is not valid
1366 anymore. To guard against this, capture the \a context as a QPointer:
1367
1368 \snippet code/src_corelib_thread_qfuture.cpp 37
1369
1370 When the context object is destroyed, cancellation happens immediately. Previous futures in the
1371 chain are \e {not} cancelled and keep running until they are finished.
1372
1373 \note When calling this method, it should be guaranteed that the \a context stays alive
1374 during setup of the chain.
1375
1376 \sa onFailed(), onCanceled()
1377*/
1378
1379/*! \fn template<class T> template<class Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture<T>::onFailed(Function &&handler)
1380
1381 \since 6.0
1382
1383 Attaches a failure handler to this future, to handle any exceptions. The
1384 returned future behaves exactly as this future (has the same state and result)
1385 unless this future fails with an exception.
1386
1387 The \a handler is a callable which takes either no argument or one argument, to
1388 filter by specific error types, similar to the
1389 \l {https://en.cppreference.com/w/cpp/language/try_catch} {catch} statement.
1390 It returns a value of the type packaged by this future. After the failure, the
1391 returned future packages the value returned by \a handler.
1392
1393 The handler will only be invoked if an exception is raised. If the exception
1394 is raised after this handler is attached, the handler is executed in the thread
1395 that reports the future as finished as a result of the exception. If the handler
1396 is attached after this future has already failed, it will be invoked immediately,
1397 in the thread that executes \c onFailed(). Therefore, the handler cannot always
1398 make assumptions about which thread it will be run on. Use the overload that
1399 takes a context object if you want to control which thread the handler is
1400 invoked on.
1401
1402 The example below demonstrates how to attach a failure handler:
1403
1404 \snippet code/src_corelib_thread_qfuture.cpp 7
1405
1406 If there are multiple handlers attached, the first handler that matches with the
1407 thrown exception type will be invoked. For example:
1408
1409 \snippet code/src_corelib_thread_qfuture.cpp 8
1410
1411 If none of the handlers matches with the thrown exception type, the exception
1412 will be propagated to the resulted future:
1413
1414 \snippet code/src_corelib_thread_qfuture.cpp 9
1415
1416 \note You can always attach a handler taking no argument, to handle all exception
1417 types and avoid writing the try-catch block.
1418
1419 \sa then(), onCanceled()
1420*/
1421
1422/*! \fn template<class T> template<class Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture<T>::onFailed(QObject *context, Function &&handler)
1423
1424 \since 6.1
1425 \overload
1426
1427 Attaches a failure handler to this future, to handle any exceptions that the future
1428 raises, or that it has already raised. Returns a QFuture of the same type as this
1429 future. The handler will be invoked only in case of an exception, in the thread of
1430 the \a context object. This can be useful if the failure needs to be handled in a
1431 specific thread. For example:
1432
1433 \snippet code/src_corelib_thread_qfuture.cpp 19
1434
1435 The failure handler attached into QtConcurrent::run updates the UI elements and cannot
1436 be invoked from a non-gui thread. So \c this is provided as a context to \c .onFailed(),
1437 to make sure that it will be invoked in the main thread.
1438
1439 If the \a context is destroyed before the chain has finished, the future is canceled.
1440 See \l {context_lifetime}{then()} for details.
1441
1442 \note When calling this method, it should be guaranteed that the \a context stays alive
1443 during setup of the chain.
1444
1445 See the documentation of the other overload for more details about \a handler.
1446
1447 \sa then(), onCanceled()
1448*/
1449
1450/*! \fn template<class T> template<class Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture<T>::onCanceled(Function &&handler)
1451
1452 \since 6.0
1453
1454 Attaches a cancellation \a handler to this future. The returned future
1455 behaves exactly as this future (has the same state and result) unless
1456 this future is cancelled. The \a handler is a callable which takes no
1457 arguments and returns a value of the type packaged by this future. After
1458 cancellation, the returned future packages the value returned by \a handler.
1459
1460 If attached before the cancellation, \a handler will be invoked in the same
1461 thread that reports the future as finished after the cancellation. If the
1462 handler is attached after this future has already been canceled, it will be
1463 invoked immediately in the thread that executes \c onCanceled(). Therefore,
1464 the handler cannot always make assumptions about which thread it will be run
1465 on. Use the overload that takes a context object if you want to control
1466 which thread the handler is invoked on.
1467
1468 The example below demonstrates how to attach a cancellation handler:
1469
1470 \snippet code/src_corelib_thread_qfuture.cpp 21
1471
1472 If \c testFuture is canceled, \c {Block 3} will be called and the
1473 \c resultFuture will have \c -1 as its result. Unlike \c testFuture, it won't
1474 be in a \c Canceled state. This means that you can get its result, attach
1475 countinuations to it, and so on.
1476
1477 Also note that you can cancel the chain of continuations while they are
1478 executing via the future that started the chain. Let's say \c testFuture.cancel()
1479 was called while \c {Block 1} is already executing. The next continuation will
1480 detect that cancellation was requested, so \c {Block 2} will be skipped, and
1481 the cancellation handler (\c {Block 3}) will be called.
1482
1483 \note This method returns a new \c QFuture representing the result of the
1484 continuation chain. Canceling the resulting \c QFuture itself won't invoke the
1485 cancellation handler in the chain that lead to it. This means that if you call
1486 \c resultFuture.cancel(), \c {Block 3} won't be called: because \c resultFuture is
1487 the future that results from attaching the cancellation handler to \c testFuture,
1488 no cancellation handlers have been attached to \c resultFuture itself. Only
1489 cancellation of \c testFuture or the futures returned by continuations attached
1490 before the \c onCancelled() call can trigger \c{Block 3}.
1491
1492 \sa then(), onFailed()
1493*/
1494
1495/*! \fn template<class T> template<class Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture<T>::onCanceled(QObject *context, Function &&handler)
1496
1497 \since 6.1
1498 \overload
1499
1500 Attaches a cancellation \a handler to this future, to be called when the future is
1501 canceled. The \a handler is a callable which doesn't take any arguments. It will be
1502 invoked in the thread of the \a context object. This can be useful if the cancellation
1503 needs to be handled in a specific thread.
1504
1505 If the \a context is destroyed before the chain has finished, the future is canceled.
1506 See \l {context_lifetime}{then()} for details.
1507
1508 \note When calling this method, it should be guaranteed that the \a context stays alive
1509 during setup of the chain.
1510
1511 See the documentation of the other overload for more details about \a handler.
1512
1513 \sa then(), onFailed()
1514*/
1515
1516/*! \fn template<class T> template<class U> QFuture<U> QFuture<T>::unwrap()
1517
1518 \since 6.4
1519
1520 Unwraps the inner future from this \c QFuture<T>, where \c T is a future
1521 of type \c QFuture<U>, i.e. this future has type of \c QFuture<QFuture<U>>.
1522 For example:
1523
1524 \snippet code/src_corelib_thread_qfuture.cpp 28
1525
1526 \c unwrappedFuture will be fulfilled as soon as the inner future nested
1527 inside the \c outerFuture is fulfilled, with the same result or exception
1528 and in the same thread that reports the inner future as finished. If the
1529 inner future is canceled, \c unwrappedFuture will also be canceled.
1530
1531 This is especially useful when chaining multiple computations, and one of
1532 them returns a \c QFuture as its result type. For example, let's say we
1533 want to download multiple images from an URL, scale the images, and reduce
1534 them to a single image using QtConcurrent::mappedReduced(). We could write
1535 something like:
1536
1537 \snippet code/src_corelib_thread_qfuture.cpp 29
1538
1539 Here \c QtConcurrent::mappedReduced() returns a \c QFuture<QImage>, so
1540 \c .then(processImages) returns a \c QFuture<QFuture<QImage>>. Since
1541 \c show() takes a \c QImage as argument, the result of \c .then(processImages)
1542 can't be passed to it directly. We need to call \c .unwrap(), that will
1543 get the result of the inner future when it's ready and pass it to the next
1544 continuation.
1545
1546 In case of multiple nesting, \c .unwrap() goes down to the innermost level:
1547
1548 \snippet code/src_corelib_thread_qfuture.cpp 30
1549*/
1550
1551/*! \fn template<typename OutputSequence, typename InputIt> QFuture<OutputSequence> QtFuture::whenAll(InputIt first, InputIt last)
1552
1553 \since 6.3
1554
1555 Returns a new QFuture that succeeds when all futures from \a first to \a last
1556 complete. \a first and \a last are iterators to a sequence of futures packaging
1557 type \c T. \c OutputSequence is a sequence containing all completed futures
1558 from \a first to \a last, appearing in the same order as in the input. If the
1559 type of \c OutputSequence is not specified, the resulting futures will be
1560 returned in a \c QList of \c QFuture<T>. For example:
1561
1562 \snippet code/src_corelib_thread_qfuture.cpp 22
1563
1564 \note The output sequence must support random access and the \c resize()
1565 operation.
1566
1567 If \c first equals \c last, this function returns a ready QFuture that
1568 contains an empty \c OutputSequence.
1569
1570//! [whenAll]
1571 The returned future always completes successfully after all the specified
1572 futures complete. It doesn't matter if any of these futures completes with
1573 error or is canceled. You can use \c .then() to process the completed futures
1574 after the future returned by \c whenAll() succeeds:
1575//! [whenAll]
1576
1577 \snippet code/src_corelib_thread_qfuture.cpp 23
1578
1579//! [whenAll-note]
1580 \note If the input futures complete on different threads, the future returned
1581 by this method will complete in the thread that the last future completes in.
1582 Therefore, the continuations attached to the future returned by \c whenAll()
1583 cannot always make assumptions about which thread they will be run on. Use the
1584 overload of \c .then() that takes a context object if you want to control which
1585 thread the continuations are invoked on.
1586//! [whenAll-note]
1587*/
1588
1589/*! \fn template<typename OutputSequence, typename... Futures> QFuture<OutputSequence> QtFuture::whenAll(Futures &&... futures)
1590
1591 \since 6.3
1592
1593 Returns a new QFuture that succeeds when all \a futures packaging arbitrary
1594 types complete. \c OutputSequence is a sequence of completed futures. The type
1595 of its entries is \c std::variant<Futures...>. For each \c QFuture<T> passed to
1596 \c whenAll(), the entry at the corresponding position in \c OutputSequence
1597 will be a \c std::variant holding that \c QFuture<T>, in its completed state.
1598 If the type of \c OutputSequence is not specified, the resulting futures will
1599 be returned in a QList of \c std::variant<Futures...>. For example:
1600
1601 \snippet code/src_corelib_thread_qfuture.cpp 24
1602
1603 \note The output sequence should support random access and the \c resize()
1604 operation.
1605
1606 \include qfuture.qdoc whenAll
1607
1608 \snippet code/src_corelib_thread_qfuture.cpp 25
1609
1610 \include qfuture.qdoc whenAll-note
1611*/
1612
1613/*! \fn template<typename T, typename InputIt> QFuture<QtFuture::WhenAnyResult<T>> QtFuture::whenAny(InputIt first, InputIt last)
1614
1615 \since 6.3
1616
1617 Returns a new QFuture that succeeds when any of the futures from \a first to
1618 \a last completes. \a first and \a last are iterators to a sequence of futures
1619 packaging type \c T. The returned future packages a value of type
1620 \c {QtFuture::WhenAnyResult<T>} which in turn packages the index of the
1621 first completed \c QFuture and the \c QFuture itself. If \a first equals \a last,
1622 this function returns a ready \c QFuture that has \c -1 for the \c index field in
1623 the QtFuture::WhenAnyResult struct and a default-constructed \c QFuture<T> for
1624 the \c future field. Note that a default-constructed QFuture is a completed
1625 future in a cancelled state.
1626
1627//! [whenAny]
1628 The returned future always completes successfully after the first future
1629 from the specified futures completes. It doesn't matter if the first future
1630 completes with error or is canceled. You can use \c .then() to process the
1631 result after the future returned by \c whenAny() succeeds:
1632//! [whenAny]
1633
1634 \snippet code/src_corelib_thread_qfuture.cpp 26
1635
1636//! [whenAny-note]
1637 \note If the input futures complete on different threads, the future returned
1638 by this method will complete in the thread that the first future completes in.
1639 Therefore, the continuations attached to the future returned by \c whenAny()
1640 cannot always make assumptions about which thread they will be run on. Use the
1641 overload of \c .then() that takes a context object if you want to control which
1642 thread the continuations are invoked on.
1643//! [whenAny-note]
1644
1645 \sa QtFuture::WhenAnyResult
1646*/
1647
1648/*! \fn template<typename... Futures> QFuture<std::variant<std::decay_t<Futures>...>> QtFuture::whenAny(Futures &&... futures)
1649
1650 \since 6.3
1651
1652 Returns a new QFuture that succeeds when any of the \a futures completes.
1653 \a futures can package arbitrary types. The returned future packages the
1654 value of type \c std::variant<Futures...> which in turn packages the first
1655 completed QFuture from \a futures. You can use
1656 \l {https://en.cppreference.com/w/cpp/utility/variant/index} {std::variant::index()}
1657 to find out the index of the future in the sequence of \a futures that
1658 finished first.
1659
1660 \include qfuture.qdoc whenAny
1661
1662 \snippet code/src_corelib_thread_qfuture.cpp 27
1663
1664 \include qfuture.qdoc whenAny-note
1665*/