From 7332d3937dbad3b0995eb38d6e06cc0220a1d2d0 Mon Sep 17 00:00:00 2001 From: Andrei Golubev Date: Wed, 14 Oct 2020 11:57:59 +0200 Subject: [PATCH] Rename QPromise starting and finishing methods to start and finish MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Proposed during API review Change-Id: I9c43e1915c50803ab69bfe07a91c05d2224b86c4 Reviewed-by: Lars Knoll Reviewed-by: Mårten Nordheim Reviewed-by: Sona Kurazyan --- src/corelib/thread/qpromise.h | 6 +- src/corelib/thread/qpromise.qdoc | 20 +++---- .../thread/qpromise/snippet_qpromise.cpp | 14 ++--- .../corelib/thread/qpromise/tst_qpromise.cpp | 58 +++++++++---------- 4 files changed, 49 insertions(+), 49 deletions(-) diff --git a/src/corelib/thread/qpromise.h b/src/corelib/thread/qpromise.h index 4225abd771..225ce3dee1 100644 --- a/src/corelib/thread/qpromise.h +++ b/src/corelib/thread/qpromise.h @@ -80,7 +80,7 @@ public: // potential waits if (!(state & QFutureInterfaceBase::State::Finished)) { d.cancel(); - reportFinished(); // required to finalize the state + finish(); // required to finalize the state } } @@ -97,8 +97,8 @@ public: void setException(const QException &e) { d.reportException(e); } void setException(std::exception_ptr e) { d.reportException(e); } #endif - void reportStarted() { d.reportStarted(); } - void reportFinished() { d.reportFinished(); } + void start() { d.reportStarted(); } + void finish() { d.reportFinished(); } void suspendIfRequested() { d.suspendIfRequested(); } diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc index 279bc8766a..d5537efb4d 100644 --- a/src/corelib/thread/qpromise.qdoc +++ b/src/corelib/thread/qpromise.qdoc @@ -99,7 +99,7 @@ Destroys the promise. \note The promise implicitly transitions to a cancelled state on destruction - unless reportFinished() is called beforehand by the user. + unless finish() is called beforehand by the user. */ /*! \fn template QFuture QPromise::future() const @@ -136,7 +136,7 @@ execution. \note This method must not be used after QFuture::cancel() or - reportFinished(). + finish(). \sa isCanceled() */ @@ -146,25 +146,25 @@ \overload */ -/*! \fn template void QPromise::reportStarted() +/*! \fn template void QPromise::start() Reports that the computation is started. Calling this method is important to state the beginning of the computation as QFuture methods rely on this information. - \note Extra attention is required when reportStarted() is called from a + \note Extra attention is required when start() is called from a newly created thread. In such case, the call might naturally be delayed due to the implementation details of the thread scheduling. - \sa QFuture::isStarted(), QFuture::waitForFinished(), reportFinished() + \sa QFuture::isStarted(), QFuture::waitForFinished(), finish() */ -/*! \fn template void QPromise::reportFinished() +/*! \fn template void QPromise::finish() Reports that the computation is finished. Once finished, no new results will - be added when calling addResult(). This method accompanies reportStarted(). + be added when calling addResult(). This method accompanies start(). - \sa QFuture::isFinished(), QFuture::waitForFinished(), reportStarted() + \sa QFuture::isFinished(), QFuture::waitForFinished(), start() */ /*! \fn template void QPromise::suspendIfRequested() @@ -206,7 +206,7 @@ Returns whether the computation has been cancelled with the QFuture::cancel() function. The returned value \c true indicates that the - computation should be finished and reportFinished() called. + computation should be finished and finish() called. \note After cancellation, results currently available may still be accessed by a future, but new results will not be added when calling addResult(). @@ -239,7 +239,7 @@ state. \sa QFuture::progressValue(), QFuture::progressText(), QFuture::cancel(), - reportFinished() + finish() */ /*! \fn template void QPromise::swap(QPromise &other) noexcept diff --git a/tests/auto/corelib/thread/qpromise/snippet_qpromise.cpp b/tests/auto/corelib/thread/qpromise/snippet_qpromise.cpp index 7180baccca..65a0921616 100644 --- a/tests/auto/corelib/thread/qpromise/snippet_qpromise.cpp +++ b/tests/auto/corelib/thread/qpromise/snippet_qpromise.cpp @@ -76,13 +76,13 @@ void snippet_QPromise::basicExample() QFuture future = promise.future(); QScopedPointer thread(QThread::create([] (QPromise promise) { - promise.reportStarted(); // notifies QFuture that the computation is started + promise.start(); // notifies QFuture that the computation is started promise.addResult(42); - promise.reportFinished(); // notifies QFuture that the computation is finished + promise.finish(); // notifies QFuture that the computation is finished }, std::move(promise))); thread->start(); - future.waitForFinished(); // blocks until QPromise::reportFinished is called + future.waitForFinished(); // blocks until QPromise::finish is called future.result(); // returns 42 //! [basic] @@ -99,7 +99,7 @@ void snippet_QPromise::multithreadExample() // ... //! [multithread_init] - sharedPromise->reportStarted(); + sharedPromise->start(); //! [multithread_main] // here, QPromise is shared between threads via a smart pointer @@ -132,7 +132,7 @@ void snippet_QPromise::multithreadExample() for (auto& t : threads) t->wait(); - sharedPromise->reportFinished(); + sharedPromise->finish(); } void snippet_QPromise::suspendExample() @@ -142,7 +142,7 @@ void snippet_QPromise::suspendExample() QPromise promise; QFuture future = promise.future(); - promise.reportStarted(); + promise.start(); // Start a computation thread that supports suspension and cancellation QScopedPointer thread(QThread::create([] (QPromise promise) { for (int i = 0; i < 100; ++i) { @@ -151,7 +151,7 @@ void snippet_QPromise::suspendExample() if (promise.isCanceled()) // support cancellation break; } - promise.reportFinished(); + promise.finish(); }, std::move(promise))); thread->start(); //! [suspend_start] diff --git a/tests/auto/corelib/thread/qpromise/tst_qpromise.cpp b/tests/auto/corelib/thread/qpromise/tst_qpromise.cpp index 600c0fd150..80a7ee2551 100644 --- a/tests/auto/corelib/thread/qpromise/tst_qpromise.cpp +++ b/tests/auto/corelib/thread/qpromise/tst_qpromise.cpp @@ -125,9 +125,9 @@ struct ThreadWrapper void tst_QPromise::promise() { const auto testCanCreatePromise = [] (auto promise) { - promise.reportStarted(); + promise.start(); promise.suspendIfRequested(); // should not block on its own - promise.reportFinished(); + promise.finish(); }; RUN_TEST_FUNC(testCanCreatePromise, QPromise()); @@ -144,11 +144,11 @@ void tst_QPromise::futureFromPromise() auto future = promise.future(); QVERIFY(!future.isValid()); - promise.reportStarted(); + promise.start(); QCOMPARE(future.isStarted(), true); QVERIFY(future.isValid()); - promise.reportFinished(); + promise.finish(); QCOMPARE(future.isFinished(), true); QVERIFY(future.isValid()); @@ -257,9 +257,9 @@ void tst_QPromise::setException() struct TestException {}; // custom exception class const auto testExceptionCaught = [] (auto promise, const auto& exception) { auto f = promise.future(); - promise.reportStarted(); + promise.start(); promise.setException(exception); - promise.reportFinished(); + promise.finish(); bool caught = false; try { @@ -324,7 +324,7 @@ void tst_QPromise::progress() void tst_QPromise::addInThread() { const auto testAddResult = [] (auto promise, const auto &result) { - promise.reportStarted(); + promise.start(); auto f = promise.future(); // move construct QPromise ThreadWrapper thr([p = std::move(promise), &result] () mutable { @@ -343,7 +343,7 @@ void tst_QPromise::addInThread() void tst_QPromise::addInThreadMoveOnlyObject() { QPromise promise; - promise.reportStarted(); + promise.start(); auto f = promise.future(); ThreadWrapper thr([p = std::move(promise)] () mutable { @@ -359,7 +359,7 @@ void tst_QPromise::reportFromMultipleThreads() { QPromise promise; auto f = promise.future(); - promise.reportStarted(); + promise.start(); ThreadWrapper threads[] = { ThreadWrapper([&promise] () mutable { promise.addResult(42); }), @@ -368,7 +368,7 @@ void tst_QPromise::reportFromMultipleThreads() }; for (auto& t : threads) t.join(); - promise.reportFinished(); + promise.finish(); QList expected = {42, 43, 44}; for (auto actual : f.results()) { @@ -386,7 +386,7 @@ void tst_QPromise::reportFromMultipleThreadsByMovedPromise() // move-constructed) must be able to set results, QFuture must still // hold correct references to results. auto promise = std::move(initialPromise); - promise.reportStarted(); + promise.start(); ThreadWrapper threads[] = { ThreadWrapper([&promise] () mutable { promise.addResult(42); }), ThreadWrapper([&promise] () mutable { promise.addResult(43); }), @@ -394,7 +394,7 @@ void tst_QPromise::reportFromMultipleThreadsByMovedPromise() }; for (auto& t : threads) t.join(); - promise.reportFinished(); + promise.finish(); } QCOMPARE(f.isFinished(), true); @@ -411,10 +411,10 @@ void tst_QPromise::doNotCancelWhenFinished() { const auto testFinishedPromise = [] (auto promise) { auto f = promise.future(); - promise.reportStarted(); + promise.start(); // Finish QPromise inside thread, destructor must not call cancel() - ThreadWrapper([p = std::move(promise)] () mutable { p.reportFinished(); }).join(); + ThreadWrapper([p = std::move(promise)] () mutable { p.finish(); }).join(); f.waitForFinished(); @@ -436,7 +436,7 @@ void tst_QPromise::cancelWhenDestroyed() try { // Move QPromise to local scope. On destruction, it must call cancel(). auto promise = std::move(initialPromise); - promise.reportStarted(); + promise.start(); ThreadWrapper threads[] = { ThreadWrapper([&promise] () mutable { promise.addResult(42); }), ThreadWrapper([&promise] () mutable { promise.addResult(43); }), @@ -444,8 +444,8 @@ void tst_QPromise::cancelWhenDestroyed() }; for (auto& t : threads) t.join(); - throw "Throw in the middle, we lose our promise here, reportFinished() not called!"; - promise.reportFinished(); + throw "Throw in the middle, we lose our promise here, finish() not called!"; + promise.finish(); } catch (...) {} QCOMPARE(f.isFinished(), true); @@ -464,7 +464,7 @@ void tst_QPromise::cancelWhenReassigned() { QPromise promise; auto f = promise.future(); - promise.reportStarted(); + promise.start(); ThreadWrapper thr([p = std::move(promise)] () mutable { QThread::msleep(100); @@ -481,11 +481,11 @@ void tst_QPromise::finishWhenSwapped() { QPromise promise1; auto f1 = promise1.future(); - promise1.reportStarted(); + promise1.start(); QPromise promise2; auto f2 = promise2.future(); - promise2.reportStarted(); + promise2.start(); ThreadWrapper thr([&promise1, &promise2] () mutable { QThread::msleep(100); @@ -494,8 +494,8 @@ void tst_QPromise::finishWhenSwapped() swap(promise1, promise2); // ADL must resolve this promise1.addResult(2); promise2.addResult(3); - promise1.reportFinished(); // this finish is for future #2 - promise2.reportFinished(); // this finish is for future #1 + promise1.finish(); // this finish is for future #2 + promise2.finish(); // this finish is for future #1 }); f1.waitForFinished(); @@ -519,17 +519,17 @@ void tst_QPromise::cancelWhenMoved() { QPromise promise1; auto f1 = promise1.future(); - promise1.reportStarted(); + promise1.start(); QPromise promise2; auto f2 = promise2.future(); - promise2.reportStarted(); + promise2.start(); // Move promises to local scope to test cancellation behavior ThreadWrapper thr([p1 = std::move(promise1), p2 = std::move(promise2)] () mutable { QThread::msleep(100); p1 = std::move(p2); - p1.reportFinished(); // this finish is for future #2 + p1.finish(); // this finish is for future #2 }); f1.waitForFinished(); @@ -547,14 +547,14 @@ void tst_QPromise::cancelWhenMoved() void tst_QPromise::waitUntilResumed() { QPromise promise; - promise.reportStarted(); + promise.start(); auto f = promise.future(); f.suspend(); ThreadWrapper thr([p = std::move(promise)] () mutable { p.suspendIfRequested(); p.addResult(42); // result added after suspend - p.reportFinished(); + p.finish(); }); while (!f.isSuspended()) { // busy wait until worker thread suspends @@ -572,14 +572,14 @@ void tst_QPromise::waitUntilResumed() void tst_QPromise::waitUntilCanceled() { QPromise promise; - promise.reportStarted(); + promise.start(); auto f = promise.future(); f.suspend(); ThreadWrapper thr([p = std::move(promise)] () mutable { p.suspendIfRequested(); p.addResult(42); // result not added due to QFuture::cancel() - p.reportFinished(); + p.finish(); }); while (!f.isSuspended()) { // busy wait until worker thread suspends