Add a way of notifying QFutureWatcher when pause is in effect

Because setting QFutureInterface to paused state does not mean that
the computations that are already in progress will stop immediately,
it may be useful to get notified when pause actually takes effect.

Introduced the QFutureWatcher::suspended() signal, to be emitted when
there are no more computations in progress, and no more result ready
or progress reporting signals will be emitted, i.e. when pause took
effect. Added {QFuture, QFutureWatcher}::isSuspended() methods for
checking if pause took effect.

QtConcurrent will now to send QFutureCallOutEvent::Suspended event
when the state is paused and there are no more active threads.

[ChangeLog][QtCore][QFutureWatcher] Added a new QFutureWatcher::suspended()
signal, to be emitted when pause took effect, meaning that there are no
more computations in progress. Added {QFuture, QFutureWatcher}::isSuspended()
methods for checking if pause took effect.

Fixes: QTBUG-12152
Change-Id: I88f2ad24d800cd6293dec63977d45bd35f9a09f0
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

1 files changed, 33 insertions, 6 deletions

diff --git a/src/corelib/thread/qfuturewatcher.cpp b/src/corelib/thread/qfuturewatcher.cpp
index 1ab3efee64..12469d4884 100644
--- a/src/corelib/thread/qfuturewatcher.cpp
+++ b/src/corelib/thread/qfuturewatcher.cpp
@@ -69,8 +69,8 @@ QT_BEGIN_NAMESPACE
     QFutureWatcher.
 
     Status changes are reported via the started(), finished(), canceled(),
-    paused(), resumed(), resultReadyAt(), and resultsReadyAt() signals.
-    Progress information is provided from the progressRangeChanged(),
+    paused(), resumed(), suspended(), resultReadyAt(), and resultsReadyAt()
+    signals. Progress information is provided from the progressRangeChanged(),
     void progressValueChanged(), and progressTextChanged() signals.
 
     Throttling control is provided by the setPendingResultsLimit() function.
@@ -292,15 +292,28 @@ bool QFutureWatcherBase::isCanceled() const
     pause() function; otherwise returns \c false.
 
     Be aware that the computation may still be running even though this
-    function returns \c true. See setPaused() for more details.
+    function returns \c true. See setPaused() for more details. To check
+    if pause actually took effect, use isSuspended() instead.
 
-    \sa setPaused(), togglePaused()
+    \sa setPaused(), togglePaused(), isSuspended()
 */
 bool QFutureWatcherBase::isPaused() const
 {
     return futureInterface().queryState(QFutureInterfaceBase::Paused);
 }
 
+/*! \fn template <typename T> bool QFutureWatcher<T>::isSuspended() const
+
+    Returns \c true if a paused asynchronous computation has been suspended,
+    and no more results or progress changes are expected.
+
+    \sa suspended(), paused(), isPaused()
+*/
+bool QFutureWatcherBase::isSuspended() const
+{
+    return futureInterface().isSuspended();
+}
+
 /*! \fn template <typename T> void QFutureWatcher<T>::waitForFinished()
 
     Waits for the asynchronous computation to finish (including cancel()ed
@@ -431,6 +444,11 @@ void QFutureWatcherBasePrivate::sendCallOutEvent(QFutureCallOutEvent *event)
                 break;
             emit q->paused();
         break;
+        case QFutureCallOutEvent::Suspended:
+            if (q->futureInterface().isCanceled())
+                break;
+            emit q->suspended();
+        break;
         case QFutureCallOutEvent::Resumed:
             if (q->futureInterface().isCanceled())
                 break;
@@ -529,9 +547,18 @@ void QFutureWatcherBasePrivate::sendCallOutEvent(QFutureCallOutEvent *event)
     \note This signal only informs that pause has been requested. It
     doesn't indicate that all background operations are stopped. Signals
     for computations that were in progress at the moment of pausing will
-    still be delivered.
+    still be delivered. To to be informed when pause() actually
+    took effect, use the suspended() signal.
+
+    \sa setPaused(), pause(), suspended()
+*/
+
+/*! \fn template <typename T> void QFutureWatcher<T>::suspended()
+    This signal is emitted when pause() took effect, meaning that there are
+    no more running computations. After receiving this signal no more result
+    ready or progress reporting signals are expected.
 
-    \sa setPaused(), pause()
+    \sa setPaused(), pause(), paused()
 */
 
 /*! \fn template <typename T> void QFutureWatcher<T>::resumed()