QPromise Class

template <typename T> class QPromise

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

List of all members, including inherited members

Public Functions

Detailed Description

A QPromise is the writing end of a QFuture. The computation calls start(), reports results with addResult(), looks at isCanceled() and suspendIfRequested() now and then, and calls finish() when done. The reading side is future().

QPromise<int> promise;
QFuture<int> future = promise.future();
pool.start([p = std::make_shared<QPromise<int>>(std::move(promise))] {
    p->start();
    for (int i = 0; i < 100 && !p->isCanceled(); ++i)
        p->addResult(i);
    p->finish();
});

A promise can be moved but not copied. If it is destroyed before finish() was called, the future is canceled and finished, so nobody waits for it forever. Every function can be called from any thread, but only one thread should report.

See also QFuture and QFutureInterface.

Differences from Qt

Member Function Documentation

QPromise::QPromise()

Constructs a promise whose future is pending: waiting for it blocks until the promise finishes, and isStarted() of the future is false until start() is called.

See also future() and start().

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

Constructs a promise that completes the computation that other observes. At most one promise should exist for a computation.

QPromise::QPromise(QPromise &&other)

Moves other into this promise. other can only be destroyed or assigned to afterwards.

QPromise::~QPromise()

Destroys the promise. A computation that has not finished is canceled and finished, so that the threads that wait for it wake up. Waiting then throws nothing, and the future has no further results.

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<std::decay_t<U>>>>bool QPromise::addResult(U &&result, int index = -1)

Stores a copy of, or moves, result as the next result, or at index. Returns true if it was stored. It is not if the computation was canceled or finished, or if there already is a result at index.

See also emplaceResult() and addResults().

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>bool QPromise::addResults(const QList<U> &results, int beginIndex = -1)

Stores a copy of results as consecutive results, from beginIndex or after the last one. They become available together. Returns true if they were stored.

See also addResult().

template <typename... Args>bool QPromise::emplaceResult(Args &&...args)

Constructs a result in place from args as the next result. Returns true if it was stored.

See also addResult() and emplaceResultAt().

template <typename... Args>bool QPromise::emplaceResultAt(int index, Args &&...args)

Constructs a result in place from args at index. Returns true if it was stored.

See also emplaceResult().

void QPromise::finish()

Reports that the computation has finished, wakes the threads that wait for the future and runs its continuation. Calling it again does nothing.

See also start().

QFuture<T> QPromise::future() const

Returns a future for the computation of this promise. It can be called any number of times, from any thread.

bool QPromise::isCanceled() const

Returns true if the future was canceled. The computation should then stop and call finish().

See also QFuture::cancel().

QPromise & QPromise::operator=(QPromise &&other)

Finishes the computation of this promise, as the destructor does, and then takes over the one of other. Returns a reference to this promise.

void QPromise::setException(const QException &e)

Stores e, and cancels the computation. Waiting for the future then throws e. It is copied with clone(), so a class derived from QException keeps its type if it reimplements it.

See also finish().

void QPromise::setException(std::exception_ptr e)

This is an overloaded function.

Stores e, which can be any exception, and cancels the computation.

void QPromise::setProgressRange(int minimum, int maximum)

Sets the range of progress values to minimum to maximum.

See also setProgressValue().

void QPromise::setProgressValue(int progressValue)

Sets the progress value to progressValue.

See also setProgressValueAndText().

void QPromise::setProgressValueAndText(int progressValue, const QString &progressText)

Sets the progress value to progressValue and the progress text to progressText.

See also setProgressValue().

void QPromise::start()

Reports that the computation has started. The state of the future changes to running.

See also finish() and QFuture::isStarted().

void QPromise::suspendIfRequested()

Blocks while the future is suspended, until it is resumed or canceled. Call it regularly in a long computation to honour QFuture::suspend(). Returns at once if no suspension was requested.

See also QFuture::suspend() and QFuture::resume().

void QPromise::swap(QPromise &other)

Swaps this promise with other.