diff options
| author | Ivan Solovev <ivan.solovev@qt.io> | 2025-11-04 15:25:11 +0100 |
|---|---|---|
| committer | Ivan Solovev <ivan.solovev@qt.io> | 2025-12-04 18:59:04 +0100 |
| commit | 9d6828e9257325b011352a6d6d1a1e0da62f976b (patch) | |
| tree | df52a47ca3ed72c473e874c5da3fd0bf1995619f | |
| parent | eecc41edcaa85a39c5981e9813a33fc8392f7cd3 (diff) | |
Document QFuture::cancelChain() limitations
Explicitly mention that cancelChain() cannot cancel a nested QFuture
once the related computation has started. The user needs to explicitly
capture and cancel the nested future instead.
Task-number: QTBUG-140786
Pick-to: 6.10
Change-Id: Icc629071659a5833f7e9b55c640fd9920b6bd8a9
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
| -rw-r--r-- | src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp | 24 | ||||
| -rw-r--r-- | src/corelib/thread/qfuture.qdoc | 14 |
2 files changed, 38 insertions, 0 deletions
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 6531d025bef..89ac917ccd3 100644 --- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp +++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp @@ -543,6 +543,30 @@ void examples(QFuture<QString> someQStringFuture, f.cancelChain(); //! [38] } + + { + auto createFuture = [] { return QtFuture::makeReadyVoidFuture(); }; + auto runNestedComputation = [] { return QtFuture::makeReadyVoidFuture(); }; + //! [39] + QFuture<void> nested; + auto f = createFuture() + .then([&]{ + nested = runNestedComputation(); + // do some other work + return nested; + }) + .unwrap() + .then([]{ + // other continuation + }) + .onCanceled([]{ + // handle cancellation + }); + //... + f.cancelChain(); + nested.cancel(); + //! [39] + } } class SomeClass : public QObject diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index c4d4daae99f..f3f32e20adc 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -215,6 +215,20 @@ It's recommended to use it on the QFuture object that represents the entire continuation chain, like it's shown in the example above. + If any of the continuations in the chain executes an asynchronous + computation and returns a QFuture representing it, the \c cancelChain() call + will not be propagated into such nested computation once it is started. + The reason for that is that the future will be available in the continuation + chain only when the outer future is fulfilled, but the cancellation might + happen when both an outer and a nested futures are still waiting for their + computations to be finished. In such cases, the nested future needs to be + captured and canceled explicitly. + + \snippet code/src_corelib_thread_qfuture.cpp 39 + + In this example, if \c runNestedComputation() is already in progress, + it can only be canceled by calling \c {nested.cancel()}. + \sa cancel() */ |