QFuture Class

template <typename T> class QFuture

The QFuture class represents the result of an asynchronous computation. More…

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

A QFuture is the reading end of a QPromise: it tells whether the computation has started, finished or was canceled, gives its results as they arrive, and rethrows the exception that ended it. Copies of a future share the computation, and every function can be called from any thread.

QPromise<int> promise;
QFuture<int> future = promise.future();
std::thread worker([promise = std::move(promise)]() mutable {
    promise.start();
    promise.addResult(6 * 7);
    promise.finish();
});
int answer = future.result(); // waits for the result
worker.join();

A continuation is attached with then(), onFailed() or onCanceled(), and a QFutureWatcher reports the progress of a future to an event loop. QFuture<void> has no results, but everything else.

See also QPromise, QFutureWatcher, QFutureSynchronizer and QtFuture::Launch.

Differences from Qt

Member Type Documentation

typedef QFuture::const_iterator

An iterator over the results of a future that waits for each result it reads, so that a loop over the future follows the computation. It is a bidirectional iterator.

typedef QFuture::ConstIterator

A synonym for const_iterator.

Member Function Documentation

QFuture::QFuture()

Constructs an invalid future. It is canceled and finished, and has no results.

See also isValid().

[explicit] QFuture::QFuture(QFutureInterface<T> *p)

Constructs a future that observes the state of p. It shares the state, so p can go away.

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

This is an overloaded function.

Constructs a future that observes the state of other.

QFuture::QFuture(const QFuture &other)

Constructs a copy of other. Both refer to the same computation.

QFuture::QFuture(QFuture &&other)

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

QFuture::~QFuture()

Destroys the future. The computation is not affected.

const_iterator QFuture::begin() const

Returns an iterator to the first result. Dereferencing an iterator waits for its result.

See also end().

void QFuture::cancel()

Cancels the computation. The computation stops only if it looks at isCanceled() or QPromise::isCanceled(). Continuations that have not run yet are skipped.

See also cancelChain() and isCanceled().

void QFuture::cancelChain()

Cancels this future and the futures that it continues, as long as they still exist.

See also cancel().

const_iterator QFuture::cbegin() const

Returns an iterator to the first result. This is the same as begin().

const_iterator QFuture::cend() const

Returns an iterator that follows the last result. This is the same as end().

const_iterator QFuture::constBegin() const

Returns an iterator that follows the last result. This is the same as end().

const_iterator QFuture::constEnd() const

Returns an iterator that follows the last result. This is the same as end().

const_iterator QFuture::end() const

Returns an iterator that follows the last result. The future may still be running when it is compared with, so the comparison waits for the result that the other iterator points to.

See also begin().

bool QFuture::isCanceled() const

Returns true if the computation was canceled, or ended with an exception.

See also cancel().

bool QFuture::isFinished() const

Returns true if the computation has finished. A canceled computation finishes when it notices.

See also isRunning() and waitForFinished().

bool QFuture::isPaused() const

Returns true if the computation is suspended or about to be.

See also isSuspending() and isSuspended().

bool QFuture::isResultReadyAt(int index) const

Returns true if the result at index is available.

See also resultCount() and resultAt().

bool QFuture::isRunning() const

Returns true if the computation is running, that is started and not finished.

See also isStarted() and isFinished().

bool QFuture::isStarted() const

Returns true if the computation has been started. The answer stays true after it finished.

See also isRunning() and isFinished().

bool QFuture::isSuspended() const

Returns true if the computation acted on a suspension request and waits to be resumed.

See also isSuspending() and resume().

bool QFuture::isSuspending() const

Returns true if a suspension was requested and the computation has not acted on it yet.

See also isSuspended() and suspend().

bool QFuture::isValid() const

Returns true if the future refers to a computation, that is, if it was not default-constructed or moved from.

template <typename Function>QFuture<T> QFuture::onCanceled(Function &&handler)

Attaches handler, which is called without arguments if this future was canceled, and returns a future for its result. handler returns a value of the type of this future, or nothing for a QFuture<void>, and the returned future carries that value. If this future was not canceled, the returned future gets the results of this one. If it ended with an exception, the returned future gets the exception.

See also then() and onFailed().

template <typename Function>QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)

This is an overloaded function.

Attaches handler, which runs in the thread that context lives in.

template <typename Function>QFuture<T> QFuture::onFailed(Function &&handler)

Attaches handler, which is called with the exception if this future ended with an exception of the type that handler takes by reference, or with any exception if it takes nothing, and returns a future for its result. handler returns a value of the type of this future, or nothing for a QFuture<void>. If this future did not fail, the returned future gets its results; an exception of another type passes on.

See also then() and onCanceled().

template <typename Function>QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)

This is an overloaded function.

Attaches handler, which runs in the thread that context lives in.

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>QFuture::operator QFuture< void>() const

Converts the future to one that does not give access to the results, so that futures of every result type can be kept together. The new future refers to the same computation.

template <typename U, typename = std::enable_if_t<std::is_same_v<U, T> && !std::is_void_v<U>>>QFuture::operator U() const

Returns the first result, like result(), so that a future can be used where its value is expected.

bool QFuture::operator!=(const QFuture &other) const

Returns true if other does not refer to the same computation as this future.

QFuture & QFuture::operator=(const QFuture &other)

Makes this future refer to the computation of other and returns a reference to it.

QFuture & QFuture::operator=(QFuture &&other)

Moves other into this future and returns a reference to it.

bool QFuture::operator==(const QFuture &other) const

Returns true if other refers to the same computation as this future.

void QFuture::pause()

Suspends the computation. This is the same as suspend().

int QFuture::progressMaximum() const

Returns the highest progress value.

See also progressMinimum().

int QFuture::progressMinimum() const

Returns the lowest progress value.

See also progressMaximum().

QString QFuture::progressText() const

Returns the text that describes the progress, if the computation set one.

See also progressValue().

int QFuture::progressValue() const

Returns the progress value, between progressMinimum() and progressMaximum().

See also progressText().

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>U QFuture::result() const

Waits for the first result and returns a copy of it. Returns a default-constructed value if the computation ends without a result. It throws the exception that the computation ended with, if any.

See also resultAt(), takeResult() and results().

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>U QFuture::resultAt(int index) const

Waits for the result at index and returns a copy of it. It throws the exception that the computation ended with, if any.

See also result() and isResultReadyAt().

int QFuture::resultCount() const

Returns the number of results that are available from the first one on without a gap.

See also isResultReadyAt() and results().

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>QList<U> QFuture::results() const

Waits for the computation to finish and returns a copy of all results. Returns an empty list if the computation was canceled. It throws the exception that the computation ended with, if any.

See also result() and resultCount().

void QFuture::resume()

Resumes a suspended computation, or cancels a suspension request that was not acted upon.

See also suspend().

void QFuture::setPaused(bool paused)

Suspends the computation if paused is true, and resumes it otherwise. This is the same as setSuspended().

void QFuture::setSuspended(bool suspend)

Asks the computation to suspend if suspend is true, and to resume otherwise.

See also suspend() and resume().

void QFuture::suspend()

Asks the computation to suspend. It does so the next time it calls QPromise::suspendIfRequested().

See also resume() and isSuspending().

template <typename U = T, typename = std::enable_if_t<!std::is_void_v<U>>>U QFuture::takeResult()

Waits for the first result and moves it out of the future, which leaves the result in its moved-from state. No other thread may read the result meanwhile. Use it for a result that cannot be copied.

See also result().

template <typename Function>QFuture<QtPrivate::ThenResult<std::decay_t<Function>, T>> QFuture::then(Function &&function)

Attaches the continuation function, which runs when this future has finished, and returns a future for its result. function takes the result of this future, or this future itself, and runs in the thread that finishes this future. A QFuture<void> passes nothing. function is skipped if this future was canceled or ended with an exception, unless it takes the future; the returned future is canceled, or gets the exception, then. A future has at most one continuation, so a second call returns a canceled future.

See also onCanceled() and onFailed().

template <typename Function>QFuture<QtPrivate::ThenResult<std::decay_t<Function>, T>> QFuture::then(QtFuture::Launch policy, Function &&function)

This is an overloaded function.

Attaches function, which runs as policy says.

See also QtFuture::Launch.

template <typename Function>QFuture<QtPrivate::ThenResult<std::decay_t<Function>, T>> QFuture::then(QThreadPool *pool, Function &&function)

This is an overloaded function.

Attaches function, which runs in a thread of pool.

template <typename Function>QFuture<QtPrivate::ThenResult<std::decay_t<Function>, T>> QFuture::then(QObject *context, Function &&function)

This is an overloaded function.

Attaches function, which runs in the thread that context lives in, from its event loop. If context is destroyed before then, function is not called and the returned future is canceled.

void QFuture::togglePaused()

Suspends the computation if it is not suspended, and resumes it otherwise. This is the same as toggleSuspended().

void QFuture::toggleSuspended()

Suspends the computation if it is not suspended, and resumes it otherwise.

void QFuture::waitForFinished() const

Blocks until the computation has finished. It throws the exception that the computation ended with, if any.

See also isFinished().