1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve docs for QFuture continuations

Browse Source 
Replace phrases like "future has been running", "parent" with more
precise descriptions.

Fixes: QTBUG-95273
Change-Id: Ibd5a464007d41cc437da49ba250b9ea0a46078c6
Reviewed-by: Andrei Golubev <andrei.golubev@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
(cherry picked from commit d61820e5ab3176818b8a2326fa25d05a9f135244)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
This commit is contained in:
Sona Kurazyan 2021-08-03 10:42:46 +02:00 committed by Qt Cherry-pick Bot
parent 851ed7cd3f
commit 2c5de45781
2 changed files with 53 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
View File

@ -114,10 +114,10 @@ QFuture<int> future = ...;
//! [5] //! [5]
//! [6] //! [6]
QFuture<int> parentFuture = ...; QFuture<int> future = ...;
auto continuation = parentFuture.then([](int res1){ ... }).then([](int res2){ ... })... auto continuation = future.then([](int res1){ ... }).then([](int res2){ ... })...
... ...
// parentFuture throws an exception // future throws an exception
try { try {
auto result = continuation.result(); auto result = continuation.result();
} catch (QException &e) { } catch (QException &e) {
@ -286,9 +286,9 @@ auto future = QtConcurrent::run([] {
//! [20] //! [20]
QObject *context = ...; QObject *context = ...;
auto parentFuture = cachedResultsReady ? QtFuture::makeReadyFuture(results) auto future = cachedResultsReady ? QtFuture::makeReadyFuture(results)
: QtConcurrent::run([] { /* compute results */}); : QtConcurrent::run([] { /* compute results */});
auto future = parentFuture.then(context, [] (Results results) { auto continuation = future.then(context, [] (Results results) {
// Runs in the context's thread // Runs in the context's thread
}).then([] { }).then([] {
// May or may not run in the context's thread // May or may not run in the context's thread

90
src/corelib/thread/qfuture.qdoc
View File

@ -65,7 +65,7 @@
using exceptions. Let's say we want to send a network request to obtain a large using exceptions. Let's say we want to send a network request to obtain a large
file from a network location. Then we want to write it to the file system and file from a network location. Then we want to write it to the file system and
return its location in case of a success. Both of these operations may fail return its location in case of a success. Both of these operations may fail
with different errors. So, we use std::variant to keep the result with different errors. So, we use \c std::variant to keep the result
or error: or error:
\snippet code/src_corelib_thread_qfuture.cpp 3 \snippet code/src_corelib_thread_qfuture.cpp 3
@ -75,13 +75,13 @@
\snippet code/src_corelib_thread_qfuture.cpp 4 \snippet code/src_corelib_thread_qfuture.cpp 4
It's possible to chain multiple continuations and handlers in any order. It's possible to chain multiple continuations and handlers in any order.
The first handler that can handle the state of its parent is invoked first. For example:
If there's no proper handler, the state is propagated to the next continuation
or handler. For example:
\snippet code/src_corelib_thread_qfuture.cpp 15 \snippet code/src_corelib_thread_qfuture.cpp 15
If \c testFuture is successfully fulfilled \c {Block 1} will be called. If Depending on the state of \c testFuture (canceled, has exception or has a
result), the next onCanceled(), onFailed() or then() will be called. So
if \c testFuture is successfully fulfilled, \c {Block 1} will be called. If
it succeeds as well, the next then() (\c {Block 4}) is called. If \c testFuture it succeeds as well, the next then() (\c {Block 4}) is called. If \c testFuture
gets canceled or fails with an exception, either \c {Block 2} or \c {Block 3} gets canceled or fails with an exception, either \c {Block 2} or \c {Block 3}
will be called respectively. The next then() will be called afterwards, and the will be called respectively. The next then() will be called afterwards, and the
@ -897,16 +897,19 @@
Represents execution policies for running a QFuture continuation. Represents execution policies for running a QFuture continuation.
\value Sync The continuation will be launched in the same thread in \value Sync The continuation will be launched in the same thread that
which the parent has been executing, or in the thread where fulfills the promise associated with the future to which the
the parent lives if the continuation is attached after the continuation was attached, or if it has already finished, the
parent has already finished. continuation will be invoked immediately, in the thread that
executes \c then().
\value Async The continuation will be launched in in a separate thread taken from \value Async The continuation will be launched in a separate thread taken from
the global QThreadPool. the global QThreadPool.
\value Inherit The continuation will inherit the launch policy of the parent or its \value Inherit The continuation will inherit the launch policy or thread pool of
thread pool, if it was using a custom one. the future to which it is attached.
\c Sync is used as a default launch policy.
\sa QFuture::then(), QThreadPool::globalInstance() \sa QFuture::then(), QThreadPool::globalInstance()
@ -1058,11 +1061,8 @@
\overload \overload
Attaches a continuation to this future, allowing to chain multiple asynchronous Attaches a continuation to this future, allowing to chain multiple asynchronous
computations if desired. When the asynchronous computation represented by this computations if desired, using the \l {QtFuture::Launch}{Sync} policy.
future finishes, \a function will be invoked in the same thread in which this This method returns a new QFuture representing the result of the continuation.
future has been running. If the continuation is attached after the parent has
already finished, it will be invoked in the thread where the parent lives. This
method returns a new QFuture representing the result of the continuation.
\note Use other overloads of this method if you need to launch the continuation in \note Use other overloads of this method if you need to launch the continuation in
a separate thread. a separate thread.
@ -1099,7 +1099,7 @@
In this case the whole chain of continuations will be interrupted. In this case the whole chain of continuations will be interrupted.
\note If the parent future gets canceled, its continuations will \note If this future gets canceled, the continuations attached to it will
also be canceled. also be canceled.
\sa onFailed(), onCanceled() \sa onFailed(), onCanceled()
@ -1115,10 +1115,12 @@
finishes, \a function will be invoked according to the given launch \a policy. finishes, \a function will be invoked according to the given launch \a policy.
A new QFuture representing the result of the continuation is returned. A new QFuture representing the result of the continuation is returned.
Depending on the \a policy, continuation will run in the same thread as the parent, Depending on the \a policy, continuation will be invoked in the same thread as
run in a new thread, or inherit the launch policy and thread pool of the parent. this future, in a new thread, or will inherit the launch policy and thread pool of
this future. If no launch policy is specified (see the overload taking only a callable),
the \c Sync policy will be used.
In the following example both continuations will run in a new thread (but in In the following example both continuations will be invoked in a new thread (but in
the same one). the same one).
\code \code
@ -1126,8 +1128,8 @@
future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... }); future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });
\endcode \endcode
In the following example both continuations will run in new threads using the same In the following example both continuations will be invoked in new threads using the
thread pool. same thread pool.
\code \code
QFuture<int> future = ...; QFuture<int> future = ...;
@ -1173,10 +1175,11 @@
\snippet code/src_corelib_thread_qfuture.cpp 18 \snippet code/src_corelib_thread_qfuture.cpp 18
This is because by default \c .then() is invoked from the same thread as the parent. This is because by default \c .then() is invoked from the same thread as the
previous one.
But note that if the continuation is attached after the parent has already finished, But note that if the continuation is attached after this future has already finished,
it will be invoked in the thread where the parent future lives: it will be invoked immediately, in the thread that executes \c then():
\snippet code/src_corelib_thread_qfuture.cpp 20 \snippet code/src_corelib_thread_qfuture.cpp 20
@ -1196,13 +1199,14 @@
\since 6.0 \since 6.0
Attaches a failure handler to this future, to handle any exceptions that may Attaches a failure handler to this future, to handle any exceptions that may
have been generated. Returns a QFuture of the parent type. The handler will have been generated. Returns a QFuture of the same type as this future. The
be invoked only in case of an exception, in the same thread as the parent handler will be invoked only in case of an exception, in the same thread that
future has been running. If the continuation is attached after the parent has reported that the promise associated with this future is finished with an exception.
already finished, it will be invoked in the thread where the parent lives. If the handler is attached after this future has already finished, it will be
\a handler is a callable which takes either no argument or one argument, to invoked immediately, in the thread that executes \c onFailed(). \a handler is a
filter by specific error types similar to callable which takes either no argument or one argument, to filter by specific error
\l {https://en.cppreference.com/w/cpp/language/try_catch} {catch} statement. types, similar to the \l {https://en.cppreference.com/w/cpp/language/try_catch} {catch}
statement.
For example: For example:
@ -1229,11 +1233,11 @@
\since 6.1 \since 6.1
\overload \overload
Attaches a failure handler to this future, to handle any exceptions that may Attaches a failure handler to this future, to handle any exceptions that the future
have been generated. Returns a QFuture of the parent type. The handler will raises, or that it has already raised. Returns a QFuture of the same type as this
be invoked only in case of an exception, in the thread of the \a context object. future. The handler will be invoked only in case of an exception, in the thread of
This can be useful if the failure needs to be handled in a specific thread. the \a context object. This can be useful if the failure needs to be handled in a
For example: specific thread. For example:
\snippet code/src_corelib_thread_qfuture.cpp 19 \snippet code/src_corelib_thread_qfuture.cpp 19
@ -1251,11 +1255,11 @@
\since 6.0 \since 6.0
Attaches a cancellation \a handler to this future, to be called when the future is Attaches a cancellation \a handler to this future, to be called when or if the future
canceled. The \a handler is a callable which doesn't take any arguments. It will be is canceled. The \a handler is a callable which doesn't take any arguments. It will be
invoked in the same thread in which this future has been running. If the continuation invoked in the same thread that canceled the promise associated with this future. If
is attached after the parent has already finished, it will be invoked in the thread the continuation is attached after this future has already finished, it will be invoked
where the parent lives. immediately, in the thread that executes \c onCanceled().
\sa then(), onFailed() \sa then(), onFailed()
*/ */