QPromise Class

template <typename T> class QPromise

The QPromise class provides a way to store computation results to be accessed by QFuture. \since 6.0. More...

Header: #include <QPromise>

Public Functions

QPromise()
QPromise(const QFutureInterface<T> &other)
QPromise(QFutureInterface<T> &&other)
QPromise(QPromise<T> &&other)
~QPromise()
QFuture<T> future() const
QPromise<T> &operator=(QPromise<T> &&other)

Detailed Description

\inmoduleQtCore \threadsafe

\ingroupthread

QPromise provides a simple way to communicate progress and results of the user-defined computation to QFuture in an asynchronous fashion. For the communication to work, QFuture must be constructed by QPromise.

You can use QPromise based workloads as an alternative to Qt Concurrent framework when fine-grained control is needed or high-level communication primitive to accompany QFuture is sufficient.

The simplest case of promise and future collaboration would be a single result communication:

     QPromise<int> promise;
     QFuture<int> future = promise.future();

     QScopedPointer<QThread> thread(QThread::create([] (QPromise<int> promise) {
         promise.start();   // notifies QFuture that the computation is started
         promise.addResult(42);
         promise.finish();  // notifies QFuture that the computation is finished
     }, std::move(promise)));
     thread->start();

     future.waitForFinished();  // blocks until QPromise::finish is called
     future.result();  // returns 42

By design, QPromise is a move-only object. This behavior helps to ensure that whenever the promise is destroyed, the associated future object is notified and will not wait forever for the results to become available. However, this is inconvenient if one wants to use the same promise to report results from different threads. There is no specific way to do that at the moment, but known mechanisms exist, such as the use of smart pointers or raw pointers/references. QSharedPointer is a good default choice if you want to copy your promise and use it in multiple places simultaneously. Raw pointers or references are, in a sense, easier, and probably perform better (since there is no need to do a resource management) but may lead to dangling.

Here is an example of how a promise can be used in multiple threads:

     QSharedPointer<QPromise<int>> sharedPromise(new QPromise<int>());
     QFuture<int> future = sharedPromise->future();

     // ...

     sharedPromise->start();

     // here, QPromise is shared between threads via a smart pointer
     QScopedPointer<QThread> threads[] = {
         QScopedPointer<QThread>(QThread::create([] (auto sharedPromise) {
             sharedPromise->addResult(0, 0);  // adds value 0 by index 0
         }, sharedPromise)),
         QScopedPointer<QThread>(QThread::create([] (auto sharedPromise) {
             sharedPromise->addResult(-1, 1);  // adds value -1 by index 1
         }, sharedPromise)),
         QScopedPointer<QThread>(QThread::create([] (auto sharedPromise) {
             sharedPromise->addResult(-2, 2);  // adds value -2 by index 2
         }, sharedPromise)),
         // ...
     };
     // start all threads
     for (auto& t : threads)
         t->start();

     // ...

     future.resultAt(0);  // waits until result at index 0 becomes available. returns value  0
     future.resultAt(1);  // waits until result at index 1 becomes available. returns value -1
     future.resultAt(2);  // waits until result at index 2 becomes available. returns value -2

     sharedPromise->finish();

See also QFuture.

Member Function Documentation

[noexcept] QPromise::QPromise(QFutureInterface<T> &&other)

QPromise::QPromise(const QFutureInterface<T> &other)

\internalConstructs a QPromise with a passed QFutureInterface other. Used internally for QtConcurrent::run(), when its callable takes a reference to the associated promise as its first argument (run with promise mode).

See also operator=().

QPromise::QPromise()

Constructs a QPromise with a default state.

QPromise::QPromise(QPromise<T> &&other)

Move constructs a new QPromise from other.

See also operator=().

QPromise::~QPromise()

Destroys the promise.

Note: The promise implicitly transitions to a canceled state on destruction unless finish() is called beforehand by the user.

QFuture<T> QPromise::future() const

Returns a future associated with this promise.

[noexcept] QPromise<T> &QPromise::operator=(QPromise<T> &&other)

Move assigns other to this promise and returns a reference to this promise.