Deprecate the pause-related APIs of QFuture* classes

Deprecated the pause-related APIs of QFuture* classes and
added alternatives having "suspend" in the name instead.

With 2f15927f01ceef0aca490746302a5ea57ea9441c new
isSuspended()/suspended() APIs have been added to QFuture* classes for
checking if pause/suspension is still in progress or it already took
effect. To keep the naming more consistent, renamed:

 - setPaused() -> setSuspended()
 - pause() -> suspend()
 - togglePaused() -> toggleSuspended()
 - QFutureWatcher::paused() -> QFutureWatcher::suspending()

Note that QFuture*::isPaused() now corresponds to (isSuspending() ||
isSuspended()).

[ChangeLog][Deprecation Notice] Deprecated pause-related APIs of
QFuture and QFutureWatcher. Added alternatives having "suspend" in
the name instead.

Change-Id: Ibeb75017a118401d64d18b72fb95d78e28c4661c
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Andrei Golubev <andrei.golubev@qt.io>
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

2 files changed, 244 insertions, 37 deletions

diff --git a/tests/auto/corelib/thread/qfuture/tst_qfuture.cpp b/tests/auto/corelib/thread/qfuture/tst_qfuture.cpp
index d647ce6eba..7a94908f6b 100644
--- a/tests/auto/corelib/thread/qfuture/tst_qfuture.cpp
+++ b/tests/auto/corelib/thread/qfuture/tst_qfuture.cpp
@@ -112,7 +112,10 @@ private slots:
     void implicitConversions();
     void iterators();
     void iteratorsThread();
+#if QT_DEPRECATED_SINCE(6, 0)
     void pause();
+    void suspendCheckPaused();
+#endif
     void suspend();
     void throttling();
     void voidConversions();
@@ -1315,6 +1318,9 @@ public:
     QSet<int> reportedProgress;
 };
 
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 void tst_QFuture::pause()
 {
     QFutureInterface<void> Interface;
@@ -1335,39 +1341,98 @@ void tst_QFuture::pause()
     Interface.reportFinished();
 }
 
+void tst_QFuture::suspendCheckPaused()
+{
+    QFutureInterface<void> interface;
+
+    interface.reportStarted();
+    QFuture<void> f = interface.future();
+    QVERIFY(!f.isSuspended());
+
+    interface.reportSuspended();
+    QVERIFY(!f.isSuspended());
+
+    f.pause();
+    QVERIFY(!f.isSuspended());
+    QVERIFY(f.isPaused());
+
+    // resume when still pausing
+    f.resume();
+    QVERIFY(!f.isSuspended());
+    QVERIFY(!f.isPaused());
+
+    // pause again
+    f.pause();
+    QVERIFY(!f.isSuspended());
+    QVERIFY(f.isPaused());
+
+    interface.reportSuspended();
+    QVERIFY(f.isSuspended());
+    QVERIFY(f.isPaused());
+
+    // resume after suspended
+    f.resume();
+    QVERIFY(!f.isSuspended());
+    QVERIFY(!f.isPaused());
+
+    // pause again and cancel
+    f.pause();
+    interface.reportSuspended();
+
+    interface.reportCanceled();
+    QVERIFY(!f.isSuspended());
+    QVERIFY(!f.isPaused());
+    QVERIFY(f.isCanceled());
+
+    interface.reportFinished();
+}
+
+QT_WARNING_POP
+#endif // QT_DEPRECATED_SINCE(6, 0)
+
 void tst_QFuture::suspend()
 {
     QFutureInterface<void> interface;
 
     interface.reportStarted();
     QFuture<void> f = interface.future();
-    QVERIFY(!interface.isSuspended());
+    QVERIFY(!f.isSuspended());
 
     interface.reportSuspended();
-    QVERIFY(!interface.isSuspended());
+    QVERIFY(!f.isSuspended());
+    QVERIFY(!f.isSuspending());
+
+    f.suspend();
+    QVERIFY(f.isSuspending());
+    QVERIFY(!f.isSuspended());
+
+    // resume when still suspending
+    f.resume();
+    QVERIFY(!f.isSuspending());
+    QVERIFY(!f.isSuspended());
 
-    // pause
-    interface.togglePaused();
-    QVERIFY(!interface.isSuspended());
-    QVERIFY(interface.isPaused());
+    // suspend again
+    f.suspend();
+    QVERIFY(f.isSuspending());
+    QVERIFY(!f.isSuspended());
 
     interface.reportSuspended();
-    QVERIFY(interface.isSuspended());
-    QVERIFY(interface.isPaused());
+    QVERIFY(!f.isSuspending());
+    QVERIFY(f.isSuspended());
 
-    // resume
-    interface.togglePaused();
-    QVERIFY(!interface.isSuspended());
-    QVERIFY(!interface.isPaused());
+    // resume after suspended
+    f.resume();
+    QVERIFY(!f.isSuspending());
+    QVERIFY(!f.isSuspended());
 
-    // pause again
-    interface.togglePaused();
+    // suspend again and cancel
+    f.suspend();
     interface.reportSuspended();
 
     interface.reportCanceled();
-    QVERIFY(!interface.isSuspended());
-    QVERIFY(!interface.isPaused());
-    QVERIFY(interface.isCanceled());
+    QVERIFY(!f.isSuspending());
+    QVERIFY(!f.isSuspended());
+    QVERIFY(f.isCanceled());
 
     interface.reportFinished();
 }
@@ -2715,7 +2780,14 @@ void tst_QFuture::testFutureTaken(QFuture<T> &noMoreFuture)
     QCOMPARE(noMoreFuture.resultCount(), 0);
     QCOMPARE(noMoreFuture.isStarted(), false);
     QCOMPARE(noMoreFuture.isRunning(), false);
+    QCOMPARE(noMoreFuture.isSuspending(), false);
+    QCOMPARE(noMoreFuture.isSuspended(), false);
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
     QCOMPARE(noMoreFuture.isPaused(), false);
+QT_WARNING_POP
+#endif
     QCOMPARE(noMoreFuture.isFinished(), false);
     QCOMPARE(noMoreFuture.progressValue(), 0);
 }
diff --git a/tests/auto/corelib/thread/qfuturewatcher/tst_qfuturewatcher.cpp b/tests/auto/corelib/thread/qfuturewatcher/tst_qfuturewatcher.cpp
index 13fb587607..d4f609874e 100644
--- a/tests/auto/corelib/thread/qfuturewatcher/tst_qfuturewatcher.cpp
+++ b/tests/auto/corelib/thread/qfuturewatcher/tst_qfuturewatcher.cpp
@@ -57,9 +57,13 @@ private slots:
     void sharedFutureInterface();
     void changeFuture();
     void cancelEvents();
+#if QT_DEPRECATED_SINCE(6, 0)
     void pauseEvents();
+    void pausedSuspendedOrder();
+#endif
+    void suspendEvents();
     void suspended();
-    void suspendedEvents();
+    void suspendedEventsOrder();
     void finishedState();
     void throttling();
     void incrementalMapResults();
@@ -548,12 +552,21 @@ void callInterface(T &obj)
     obj.isFinished();
     obj.isRunning();
     obj.isCanceled();
-    obj.isPaused();
+    obj.isSuspended();
+    obj.isSuspending();
 
     obj.cancel();
-    obj.pause();
+    obj.suspend();
     obj.resume();
+    obj.toggleSuspended();
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
+    obj.isPaused();
+    obj.pause();
     obj.togglePaused();
+QT_WARNING_POP
+#endif
     obj.waitForFinished();
 
     const T& objConst = obj;
@@ -566,7 +579,14 @@ void callInterface(T &obj)
     objConst.isFinished();
     objConst.isRunning();
     objConst.isCanceled();
+    objConst.isSuspending();
+    objConst.isSuspended();
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
     objConst.isPaused();
+QT_WARNING_POP
+#endif
 }
 
 template <typename T>
@@ -665,6 +685,9 @@ void tst_QFutureWatcher::cancelEvents()
     QCOMPARE(resultReadySpy.count(), 0);
 }
 
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
 // Tests that events from paused futures are saved and
 // delivered on resume.
 void tst_QFutureWatcher::pauseEvents()
@@ -725,11 +748,120 @@ void tst_QFutureWatcher::pauseEvents()
     }
 }
 
+void tst_QFutureWatcher::pausedSuspendedOrder()
+{
+    QFutureInterface<void> iface;
+    iface.reportStarted();
+
+    QFutureWatcher<void> watcher;
+
+    QSignalSpy pausedSpy(&watcher, &QFutureWatcher<void>::paused);
+    QVERIFY(pausedSpy.isValid());
+
+    QSignalSpy suspendedSpy(&watcher, &QFutureWatcher<void>::suspended);
+    QVERIFY(suspendedSpy.isValid());
+
+    bool pausedBeforeSuspended = false;
+    bool notSuspendedBeforePaused = false;
+    connect(&watcher, &QFutureWatcher<void>::paused,
+            [&] { notSuspendedBeforePaused = (suspendedSpy.count() == 0); });
+    connect(&watcher, &QFutureWatcher<void>::suspended,
+            [&] { pausedBeforeSuspended = (pausedSpy.count() == 1); });
+
+    watcher.setFuture(iface.future());
+    iface.reportSuspended();
+
+    // Make sure reportPaused() is ignored if the state is not paused
+    pausedSpy.wait(100);
+    QCOMPARE(pausedSpy.count(), 0);
+    QCOMPARE(suspendedSpy.count(), 0);
+
+    iface.setPaused(true);
+    iface.reportSuspended();
+
+    QTRY_COMPARE(suspendedSpy.count(), 1);
+    QCOMPARE(pausedSpy.count(), 1);
+    QVERIFY(notSuspendedBeforePaused);
+    QVERIFY(pausedBeforeSuspended);
+
+    iface.reportFinished();
+}
+QT_WARNING_POP
+#endif // QT_DEPRECATED_SINCE(6, 0)
+
+// Tests that events from suspended futures are saved and
+// delivered on resume.
+void tst_QFutureWatcher::suspendEvents()
+{
+    {
+        QFutureInterface<int> iface;
+        iface.reportStarted();
+
+        QFutureWatcher<int> watcher;
+
+        SignalSlotObject object;
+        connect(&watcher, &QFutureWatcher<int>::resultReadyAt, &object,
+                &SignalSlotObject::resultReadyAt);
+        QSignalSpy resultReadySpy(&watcher, &QFutureWatcher<int>::resultReadyAt);
+        QVERIFY(resultReadySpy.isValid());
+
+        QSignalSpy suspendingSpy(&watcher, &QFutureWatcher<int>::suspending);
+        QVERIFY(suspendingSpy.isValid());
+
+        watcher.setFuture(iface.future());
+        watcher.suspend();
+
+        QTRY_COMPARE(suspendingSpy.count(), 1);
+
+        int value = 0;
+        iface.reportFinished(&value);
+
+        // A result is reported, although the watcher is paused.
+        // The corresponding event should be also reported.
+        QTRY_COMPARE(resultReadySpy.count(), 1);
+
+        watcher.resume();
+    }
+    {
+        QFutureInterface<int> iface;
+        iface.reportStarted();
+
+        QFuture<int> a = iface.future();
+
+        QFutureWatcher<int> watcher;
+
+        SignalSlotObject object;
+        connect(&watcher, &QFutureWatcher<int>::resultReadyAt, &object,
+                &SignalSlotObject::resultReadyAt);
+        QSignalSpy resultReadySpy(&watcher, &QFutureWatcher<int>::resultReadyAt);
+        QVERIFY(resultReadySpy.isValid());
+
+        watcher.setFuture(a);
+        a.suspend();
+
+        int value = 0;
+        iface.reportFinished(&value);
+
+        QFuture<int> b;
+        watcher.setFuture(b); // If we watch b instead, resuming a
+        a.resume();           // should give us no results.
+
+        QTest::qWait(10);
+        QCOMPARE(resultReadySpy.count(), 0);
+    }
+}
+
 void tst_QFutureWatcher::suspended()
 {
     QFutureWatcher<void> watcher;
     QSignalSpy resultReadySpy(&watcher, &QFutureWatcher<int>::resultReadyAt);
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_WARNING_PUSH
+QT_WARNING_DISABLE_DEPRECATED
     QSignalSpy pausedSpy(&watcher, &QFutureWatcher<int>::paused);
+QT_WARNING_POP
+#endif
+    QSignalSpy suspendingSpy(&watcher, &QFutureWatcher<int>::suspending);
     QSignalSpy suspendedSpy(&watcher, &QFutureWatcher<int>::suspended);
     QSignalSpy finishedSpy(&watcher, &QFutureWatcher<int>::finished);
 
@@ -748,13 +880,16 @@ void tst_QFutureWatcher::suspended()
     });
     watcher.setFuture(future);
 
-    // Allow some threads to start before pausing.
+    // Allow some threads to start before suspending.
     QThread::msleep(200);
 
-    watcher.pause();
-    watcher.pause();
+    watcher.suspend();
+    watcher.suspend();
     QTRY_COMPARE(suspendedSpy.count(), 1); // suspended() should be emitted only once
+    QCOMPARE(suspendingSpy.count(), 2); // suspending() is emitted as many times as requested
+#if QT_DEPRECATED_SINCE(6, 0)
     QCOMPARE(pausedSpy.count(), 2); // paused() is emitted as many times as requested
+#endif
 
     // Make sure QFutureWatcher::resultReadyAt() is emitted only for already started threads.
     const auto resultReadyAfterPaused = resultReadySpy.count();
@@ -775,41 +910,41 @@ void tst_QFutureWatcher::suspended()
     QCOMPARE(resultReadySpy.count(), numValues - resultReadyAfterPaused);
 }
 
-void tst_QFutureWatcher::suspendedEvents()
+void tst_QFutureWatcher::suspendedEventsOrder()
 {
     QFutureInterface<void> iface;
     iface.reportStarted();
 
     QFutureWatcher<void> watcher;
 
-    QSignalSpy pausedSpy(&watcher, &QFutureWatcher<void>::paused);
-    QVERIFY(pausedSpy.isValid());
+    QSignalSpy suspendingSpy(&watcher, &QFutureWatcher<void>::suspending);
+    QVERIFY(suspendingSpy.isValid());
 
     QSignalSpy suspendedSpy(&watcher, &QFutureWatcher<void>::suspended);
     QVERIFY(suspendedSpy.isValid());
 
-    bool pausedBeforeSuspended = false;
-    bool notSuspendedBeforePasused = false;
-    connect(&watcher, &QFutureWatcher<void>::paused,
-            [&] { notSuspendedBeforePasused = (suspendedSpy.count() == 0); });
+    bool suspendingBeforeSuspended = false;
+    bool notSuspendedBeforeSuspending = false;
+    connect(&watcher, &QFutureWatcher<void>::suspending,
+            [&] { notSuspendedBeforeSuspending = (suspendedSpy.count() == 0); });
     connect(&watcher, &QFutureWatcher<void>::suspended,
-            [&] { pausedBeforeSuspended = (pausedSpy.count() == 1); });
+            [&] { suspendingBeforeSuspended = (suspendingSpy.count() == 1); });
 
     watcher.setFuture(iface.future());
     iface.reportSuspended();
 
     // Make sure reportPaused() is ignored if the state is not paused
-    pausedSpy.wait(100);
-    QCOMPARE(pausedSpy.count(), 0);
+    suspendingSpy.wait(100);
+    QCOMPARE(suspendingSpy.count(), 0);
     QCOMPARE(suspendedSpy.count(), 0);
 
-    iface.setPaused(true);
+    iface.setSuspended(true);
     iface.reportSuspended();
 
     QTRY_COMPARE(suspendedSpy.count(), 1);
-    QCOMPARE(pausedSpy.count(), 1);
-    QVERIFY(notSuspendedBeforePasused);
-    QVERIFY(pausedBeforeSuspended);
+    QCOMPARE(suspendingSpy.count(), 1);
+    QVERIFY(notSuspendedBeforeSuspending);
+    QVERIFY(suspendingBeforeSuspended);
 
     iface.reportFinished();
 }