Add support for combining multiple QFutures

[ChangeLog][QtCore] Added QtFuture::whenAll() and QtFuture::whenAny()
functions, returning a QFuture that becomes ready when all or any of the
supplied futures complete.

Task-number: QTBUG-86714
Change-Id: I2bb7dbb4cdc4f79a7a4fd494142df6a0f93a2b39
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

1 files changed, 87 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 b8a4e708a5..176fb4a043 100644
--- a/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_thread_qfuture.cpp
@@ -311,3 +311,90 @@ auto resultFuture = testFuture.then([](int res) {
     return -1;
 });
 //! [21]
+
+//! [22]
+QList<QFuture<int>> inputFutures {...};
+
+// whenAll has type QFuture<QList<QFuture<int>>>
+auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end());
+
+// whenAllVector has type QFuture<std::vector<QFuture<int>>>
+auto whenAllVector =
+        QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end());
+//! [22]
+
+//! [23]
+QList<QFuture<int>> inputFutures {...};
+
+QtFuture::whenAll(inputFutures.begin(), inputFutures.end())
+        .then([](const QList<QFuture<int>> &results) {
+            for (auto future : results) {
+                if (future.isCanceled())
+                    // handle the cancellation (possibly due to an exception)
+                else
+                    // do something with the result
+            }
+        });
+//! [23]
+
+//! [24]
+
+QFuture<int> intFuture = ...;
+QFuture<QString> stringFuture = ...;
+QFuture<void> voidFuture = ...;
+
+using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;
+
+// whenAll has type QFuture<QList<FuturesVariant>>
+auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture);
+
+// whenAllVector has type QFuture<std::vector<FuturesVariant>>
+auto whenAllVector =
+        QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture);
+
+//! [24]
+
+//! [25]
+QFuture<int> intFuture = ...;
+QFuture<QString> stringFuture = ...;
+QFuture<void> voidFuture = ...;
+
+using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;
+
+QtFuture::whenAll(intFuture, stringFuture, voidFuture)
+        .then([](const QList<FuturesVariant> &results) {
+            ...
+            for (auto result : results)
+            {
+                // assuming handleResult() is overloaded based on the QFuture type
+                std::visit([](auto &&future) { handleResult(future); }, result);
+            }
+            ...
+        });
+//! [25]
+
+//! [26]
+QList<QFuture<int>> inputFutures = ...;
+
+QtFuture::whenAny(inputFutures.begin(), inputFutures.end())
+        .then([](const QtFuture::WhenAnyResult<int> &result) {
+            qsizetype index = result.index;
+            QFuture<int> future = result.future;
+            // ...
+        });
+//! [26]
+
+//! [27]
+QFuture<int> intFuture = ...;
+QFuture<QString> stringFuture = ...;
+QFuture<void> voidFuture = ...;
+
+using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;
+
+QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) {
+    ...
+    // assuming handleResult() is overloaded based on the QFuture type
+    std::visit([](auto &&future) { handleResult(future); }, result);
+    ...
+});
+//! [27]