QtFuture Namespace

Contains miscellaneous identifiers used by the QFuture class. More...

Header: #include <QFuture>
CMake: find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Types

enum class Launch { Sync, Async, Inherit }

Functions

QFuture<ArgsType<Signal> > connect(Sender *sender, Signal signal)
QFuture<T> makeExceptionalFuture(const QException &exception)
QFuture<T> makeExceptionalFuture(std::exception_ptr exception)
QFuture<std::decay_t<T> > makeReadyFuture(T &&value)
QFuture<void> makeReadyFuture()
QFuture<T> makeReadyFuture(const QList<T> &values)

Detailed Description

Type Documentation

[since 6.0] enum class QtFuture::Launch

Represents execution policies for running a QFuture continuation.

ConstantValueDescription
QtFuture::Launch::Sync0The continuation will be launched in the same thread in which the parent has been executing, or in the thread where the parent lives if the continuation is attached after the parent has already finished.
QtFuture::Launch::Async1The continuation will be launched in in a separate thread taken from the global QThreadPool.
QtFuture::Launch::Inherit2The continuation will inherit the launch policy of the parent or its thread pool, if it was using a custom one.

This enum was introduced or modified in Qt 6.0.

See also QFuture::then() and QThreadPool::globalInstance().

Function Documentation

template <typename Sender, typename Signal, typename> QFuture<ArgsType<Signal> > QtFuture::connect(Sender *sender, Signal signal)

Creates and returns a QFuture which will become available when the sender emits the signal. If the signal takes no arguments, a QFuture<void> is returned. If the signal takes a single argument, the resulted QFuture will be filled with the signal's argument value. If the signal takes multiple arguments, the resulted QFuture is filled with std::tuple storing the values of signal's arguments. If the sender is destroyed before the signal is emitted, the resulted QFuture will be canceled.

For example, let's say we have the following object:

class Object : public QObject
{
    Q_OBJECT
    ...
signals:
    void noArgSignal();
    void singleArgSignal(int value);
    void multipleArgs(int value1, double value2, const QString &value3);
};

We can connect its signals to QFuture objects in the following way:

Object object;
QFuture<void> voidFuture = QtFuture::connect(&object, &Object::noArgSignal);
QFuture<int> intFuture = QtFuture::connect(&object, &Object::singleArgSignal);

using Args = std::tuple<int, double, QString>;
QFuture<Args> tupleFuture = QtFuture::connect(&object, &Object::multipleArgs)

We can also chain continuations to be run when a signal is emitted:

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    // do something with the value
});

You can also start the continuation in a new thread or a custom thread pool using QtFuture::Launch policies. For example:

QtFuture::connect(&object, &Object::singleArgSignal).then(QtFuture::Launch::Async, [](int value) {
    // this will run in a new thread
});

Throwing an exception from a slot invoked by Qt's signal-slot connection is considered to be an undefined behavior, if it is not handled within the slot. But with QFuture::connect(), you can throw and handle exceptions from the continuations:

QtFuture::connect(&object, &Object::singleArgSignal).then([](int value) {
    ...
    throw std::exception();
    ...
}).onFailed([](const std::exception &e) {
    // handle the exception
}).onFailed([] {
    // handle other exceptions
});

Note: The connected future will be fulfilled only once, when the signal is emitted for the first time.

See also QFuture and QFuture::then().

[since 6.1] template <typename T> QFuture<T> QtFuture::makeExceptionalFuture(const QException &exception)

Creates and returns a QFuture which already has an exception exception.

QException e;
auto f = QtFuture::makeExceptionalFuture<int>(e);
...
try {
    f.result(); // throws QException
} catch (QException &) {
    // handle exception here
}

This function was introduced in Qt 6.1.

See also QFuture, QException, and QtFuture::makeReadyFuture().

[since 6.1] template <typename T> QFuture<T> QtFuture::makeExceptionalFuture(std::exception_ptr exception)

This is an overloaded function.

Creates and returns a QFuture which already has an exception exception.

struct TestException
{
};
...
auto exception = std::make_exception_ptr(TestException());
auto f = QtFuture::makeExceptionalFuture<int>(exception);
...
try {
    f.result(); // throws TestException
} catch (TestException &) {
    // handle exception here
}

This function was introduced in Qt 6.1.

See also QFuture, QException, and QtFuture::makeReadyFuture().

[since 6.1] template <typename T, typename> QFuture<std::decay_t<T> > QtFuture::makeReadyFuture(T &&value)

This is an overloaded function.

Creates and returns a QFuture which already has a result value. The returned QFuture has a type of std::decay_t<T>, where T is not void.

auto f = QtFuture::makeReadyFuture(std::make_unique<int>(42));
...
const int result = *f.takeResult(); // result == 42

This function was introduced in Qt 6.1.

See also QFuture and QtFuture::makeExceptionalFuture().

[since 6.1] QFuture<void> QtFuture::makeReadyFuture()

This is an overloaded function.

Creates and returns a void QFuture. Such QFuture can't store any result. One can use it to query the state of the computation. The returned QFuture will always be in the finished state.

auto f = QtFuture::makeReadyFuture();
...
const bool started = f.isStarted(); // started == true
const bool running = f.isRunning(); // running == false
const bool finished = f.isFinished(); // finished == true

This function was introduced in Qt 6.1.

See also QFuture, QFuture::isStarted(), QFuture::isRunning(), QFuture::isFinished(), and QtFuture::makeExceptionalFuture().

[since 6.1] template <typename T> QFuture<T> QtFuture::makeReadyFuture(const QList<T> &values)

This is an overloaded function.

Creates and returns a QFuture which already has multiple results set from values.

const QList<int> values { 1, 2, 3 };
auto f = QtFuture::makeReadyFuture(values);
...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

This function was introduced in Qt 6.1.

See also QFuture and QtFuture::makeExceptionalFuture().

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.