docs: Clarify adding a continuation to a QFuture with multiple results

Explain that the continuation should take QFuture<T> as a parameter in
order to be able to access all results.
Add notes with examples to the QtConcurrent::mapped and
QtConcurrent::filtered overviews.

Task-number: QTBUG-133522
Pick-to: 6.9 6.8 6.5
Change-Id: I65655aadc8d4623b147d22a9bf9b2189c80b14c5
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp

@@ -188,3 +188,22 @@ QFuture<int> sum = QtConcurrent::filteredReduced(list,
     }
 );
 //! [17]
+
+//! [18]
+auto keepPositive = [](int val) {
+    return val > 0;
+};
+
+QList<int> inputs { -1, 1, 2, -3, 5 };
+auto badFuture = QtConcurrent::filtered(inputs, keepPositive)
+                         .then([](int val) {
+                             qDebug() << val;
+                         });
+
+auto goodFuture = QtConcurrent::filtered(inputs, keepPositive)
+                          .then([](QFuture<int> f) {
+                              for (auto r : f.results()) {
+                                  qDebug() << r;
+                              }
+                          });
+//! [18]

src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp

@@ -185,3 +185,22 @@ QList<QImage> collage = QtConcurrent::mappedReduced(images,
         }
    ).results();
 //! [17]
+
+//! [18]
+auto process = [](int val) {
+    return val * 2;
+};
+
+QList<int> inputs { 1, 2, 3 };
+auto badFuture = QtConcurrent::mapped(inputs, process)
+                         .then([](int val) {
+                             qDebug() << val;
+                         });
+
+auto goodFuture = QtConcurrent::mapped(inputs, process)
+                          .then([](QFuture<int> f) {
+                              for (auto r : f.results()) {
+                                  qDebug() << r;
+                              }
+                          });
+//! [18]

src/concurrent/qtconcurrentfilter.cpp

@@ -55,6 +55,18 @@
     return any results via QFuture. However, you can still use QFuture and
     QFutureWatcher to monitor the status of the filter.
 
+    \section2 Concurrent Filtered and Continuations
+
+    The result of QtConcurrent::filtered() call is a QFuture that contains
+    multiple results. When attaching a \c {.then()} continuation to such
+    QFuture, make sure to use a continuation that takes QFuture as a parameter,
+    otherwise only the first result will be processed:
+
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 18
+
+    In this example \c {badFuture} will only print a single result, while
+    \c {goodFuture} will print all results.
+
     \section1 Concurrent Filter-Reduce
 
     QtConcurrent::filteredReduced() is similar to QtConcurrent::filtered(),

src/concurrent/qtconcurrentmap.cpp

@@ -168,6 +168,18 @@
     return any results via QFuture. However, you can still use QFuture and
     QFutureWatcher to monitor the status of the map.
 
+    \section2 Concurrent Mapped and Continuations
+
+    The result of QtConcurrent::mapped() call is a QFuture that contains
+    multiple results. When attaching a \c {.then()} continuation to such
+    QFuture, make sure to use a continuation that takes QFuture as a parameter,
+    otherwise only the first result will be processed:
+
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 18
+
+    In this example \c {badFuture} will only print a single result, while
+    \c {goodFuture} will print all results.
+
     \section1 Concurrent Map-Reduce
 
     QtConcurrent::mappedReduced() is similar to QtConcurrent::mapped(), but

src/corelib/thread/qfuture.qdoc

@@ -1227,6 +1227,11 @@
 
     \snippet code/src_corelib_thread_qfuture.cpp 5
 
+    \warning If the previous future contains multiple results of type \c {T},
+    and the continuation takes an argument of type \c {T} as a parameter, only
+    the first result from the previous QFuture will be handled in the
+    continuation!
+
     If the previous future throws an exception and it is not handled inside the
     continuation, the exception will be propagated to the continuation future, to
     allow the caller to handle it: