From 65d553ce522fa7fd906404f3259550a378603ad7 Mon Sep 17 00:00:00 2001
From: Sona Kurazyan <sona.kurazyan@qt.io>
Date: Wed, 10 Nov 2021 10:59:05 +0100
Subject: [PATCH] QFuture: extend the docs to explain how to cancel
 continuation chain
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task-number: QTBUG-97582
Change-Id: Ib31d0dfb7a74bb88802a21c5875edd789e412529
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
---
 .../code/src_corelib_thread_qfuture.cpp       | 17 +++++++++++++
 src/corelib/thread/qfuture.qdoc               | 24 +++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
index f4278abcbc..b8a4e708a5 100644
--- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
@@ -294,3 +294,20 @@ auto continuation = future.then(context, [] (Results results) {
     // May or may not run in the context's thread
 });
 //! [20]
+
+//! [21]
+QFuture<int> testFuture = ...;
+auto resultFuture = testFuture.then([](int res) {
+    // Block 1
+    ...
+    return 1;
+}).then([](int res) {
+    // Block 2
+    ...
+    return 2;
+}).onCanceled([] {
+    // Block 3
+    ...
+    return -1;
+});
+//! [21]
diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc
index de1800a638..16e20666df 100644
--- a/src/corelib/thread/qfuture.qdoc
+++ b/src/corelib/thread/qfuture.qdoc
@@ -1277,6 +1277,30 @@
     on. Use the overload that takes a context object if you want to control
     which thread the handler is invoked on.
 
+    The example below demonstrates how to attach a cancellation handler:
+
+    \snippet code/src_corelib_thread_qfuture.cpp 21
+
+    If \c testFuture is canceled, \c {Block 3} will be called and the
+    \c resultFuture will have \c -1 as its result. Unlike \c testFuture, it won't
+    be in a \c Canceled state. This means that you can get its result, attach
+    countinuations to it, and so on.
+
+    Also note that you can cancel the chain of continuations while they are
+    executing via the future that started the chain. Let's say \c testFuture.cancel()
+    was called while \c {Block 1} is already executing. The next continuation will
+    detect that cancellation was requested, so \c {Block 2} will be skipped, and
+    the cancellation handler (\c {Block 3}) will be called.
+
+    \note This method returns a new \c QFuture representing the result of the
+    continuation chain. Canceling the resulting \c QFuture itself won't invoke the
+    cancellation handler in the chain that lead to it. This means that if you call
+    \c resultFuture.cancel(), \c {Block 3} won't be called: because \c resultFuture is
+    the future that results from attaching the cancellation handler to \c testFuture,
+    no cancellation handlers have been attached to \c resultFuture itself. Only
+    cancellation of \c testFuture or the futures returned by continuations attached
+    before the \c onCancelled() call can trigger \c{Block 3}.
+
     \sa then(), onFailed()
 */