Back to Qt.io
Contact Us Blog Download Qt

QtFuture Namespace

包含QFuture 类使用的其他标识符。更多

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

类

(since 6.3) struct WhenAnyResult

类型

(since 6.0) enum class Launch { Sync, Async, Inherit }

函数

QFuture<QtFuture::ArgsType<Signal>> connect(Sender *sender, Signal signal)
(since 6.1) QFuture<T> makeExceptionalFuture(const QException &exception)
(since 6.1) QFuture<T> makeExceptionalFuture(std::__exception_ptr::exception_ptr exception)
(since 6.6) QFuture<QtFuture::ContainedType<Container>> makeReadyRangeFuture(Container &&container)
(since 6.6) QFuture<ValueType> makeReadyRangeFuture(std::initializer_list<ValueType> values)
(since 6.6) QFuture<std::decay_t<T>> makeReadyValueFuture(T &&value)
(since 6.6) QFuture<void> makeReadyVoidFuture()
(since 6.3) QFuture<OutputSequence> whenAll(Futures &&... futures)
(since 6.3) QFuture<OutputSequence> whenAll(InputIt first, InputIt last)
(since 6.3) QFuture<std::variant<std::decay_t<Futures>...>> whenAny(Futures &&... futures)
(since 6.3) QFuture<QtFuture::WhenAnyResult<T>> whenAny(InputIt first, InputIt last)

详细说明

类

类WhenAnyResult

QtFuture::WhenAnyResult 用于表示 () 的结果。QtFuture::whenAny更多

类型文档

[since 6.0] enum class QtFuture::Launch

代表运行QFuture continuation 的执行策略。

常量值说明
QtFuture::Launch::Sync0续程将在履行与续程所连接的未来相关的承诺的同一线程中启动，如果未来已经结束，续程将在执行then() 的线程中立即调用。
QtFuture::Launch::Async1继续将在全局QThreadPool 的单独线程中启动。
QtFuture::Launch::Inherit2继续程序将继承其所连接的未来程序的启动策略或线程池。

Sync 被用作默认启动策略。

该枚举在 Qt 6.0 中引入。

另请参阅 QFuture::then() 和QThreadPool::globalInstance() 。

函数文档

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

创建并返回一个QFuture ，该 在sender 发送signal 时可用。如果signal 不带参数，则返回QFuture<void>。如果signal 只接受一个参数，则生成的QFuture 将填入信号的参数值。如果signal 接收多个参数，返回的QFuture 将填充存储信号参数值的 std::元组。如果sender 在发送signal 之前被销毁，则生成的QFuture 将被取消。

例如，假设我们有以下对象：

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

我们可以通过以下方式将其信号连接到QFuture 对象：

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)

我们还可以在信号发出时连锁运行连续程序：

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

还可以使用QtFuture::Launch 策略，在新线程或自定义线程池中启动延续。例如

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

从 Qt 的信号槽连接调用的槽中抛出异常，如果未在槽中处理，则会被视为未定义的行为。但有了 QFuture::connect()，您就可以从连续体中抛出并处理异常：

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

注意： 连接的未来仅会在第一次发出信号时执行一次。

另请参阅 QFuture 和QFuture::then()。

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

创建并返回一个已有异常exception 的QFuture 。

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

该函数在 Qt 6.1 中引入。

另请参阅 QFuture,QException,QtFuture::makeReadyVoidFuture() 和QtFuture::makeReadyValueFuture() 。

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

这是一个重载函数。

创建并返回一个QFuture ，该 已包含一个异常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
}

该函数在 Qt 6.1 中引入。

另请参阅 QFuture,QException,QtFuture::makeReadyVoidFuture() 和QtFuture::makeReadyValueFuture() 。

[since 6.6] template <typename Container, QtFuture::if_container_with_input_iterators<Container> = true> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

这是一个重载函数。

接收一个输入容器container ，并返回一个QFuture ，其中包含根据container 的值初始化的ContainedType 类型的多个结果。

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

限制条件

仅当Container 具有输入迭代器时才参与重载解析。

此函数在 Qt 6.6 中引入。

另请参阅 QFuture,QtFuture::makeReadyVoidFuture(),QtFuture::makeReadyValueFuture() 和QtFuture::makeExceptionalFuture() 。

[since 6.6] template <typename ValueType> QFuture<ValueType> QtFuture::makeReadyRangeFuture(std::initializer_list<ValueType> values)

这是一个重载函数。

Returns aQFuture with multiple results of typeValueType initialized from the input initializer listvalues 。

auto f = QtFuture::makeReadyRangeFuture({1, 2, 3});
    ...
const int count = f.resultCount(); // count == 3
const auto results = f.results(); // results == { 1, 2, 3 }

此函数在 Qt 6.6 中引入。

另请参阅 QFuture,QtFuture::makeReadyVoidFuture(),QtFuture::makeReadyValueFuture() 和QtFuture::makeExceptionalFuture() 。

[since 6.6] template <typename T> QFuture<std::decay_t<T>> QtFuture::makeReadyValueFuture(T &&value)

创建并返回一个已有结果value 的QFuture 。返回的QFuture 类型为 std::decent_t<T>，其中 T 不是 void。返回的QFuture 已处于完成状态。

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

此函数在 Qt 6.6 中引入。

另请参阅 QFuture,QtFuture::makeReadyRangeFuture(),QtFuture::makeReadyVoidFuture() 和QtFuture::makeExceptionalFuture() 。

[since 6.6] QFuture<void> QtFuture::makeReadyVoidFuture()

创建并返回 voidQFuture 。这种QFuture 不能存储任何结果。我们可以用它来查询计算的状态。返回的QFuture 将已处于完成状态。

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

此函数在 Qt 6.6 中引入。

另请参阅 QFuture,QFuture::isStarted(),QFuture::isRunning(),QFuture::isFinished(),QtFuture::makeReadyValueFuture(),QtFuture::makeReadyRangeFuture() 和QtFuture::makeExceptionalFuture() 。

[since 6.3] template <typename OutputSequence, typename... Futures> QFuture<OutputSequence> QtFuture::whenAll(Futures &&... futures)

QFuture futures OutputSequence 是一个已完成期货的序列。其条目类型是 。对于传递给 的每个 ， 中相应位置的条目将是一个持有该 的 ，处于完成状态。如果未指定 的类型，则所产生的期货将以 的 返回。例如：std::variant<Futures...> whenAll() QFuture<T> OutputSequence QFuture<T> std::variant OutputSequence std::variant<Futures...> QList 

QFuture<int> intFuture = ...;
QFuture<QString> stringFuture = ...;
QFuture<void> voidFuture = ...;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

// whenAll has type QFuture<QList<FuturesVariant>>
auto whenAll = QtFuture::whenAll(intFuture, stringFuture, voidFuture);

// whenAllVector has type QFuture<std::vector<FuturesVariant>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<FuturesVariant>>(intFuture, stringFuture, voidFuture);

注意： 输出序列应支持随机存取和resize() 操作。

返回的未来总是在所有指定的未来完成后才成功完成。如果这些期货中的任何一个出现错误或被取消，都没有关系。在whenAll() 返回的未来成功后，可以使用.then() 处理已完成的未来：

QFuture<int> intFuture = ...;
QFuture<QString> stringFuture = ...;
QFuture<void> voidFuture = ...;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAll(intFuture, stringFuture, voidFuture)
        .then([](const QList<FuturesVariant> &results) {
            ...
            for (auto result : results)
            {
                // assuming handleResult() is overloaded based on the QFuture type
                std::visit([](auto &&future) { handleResult(future); }, result);
            }
            ...
        });

注意： 如果输入的期货在不同的线程上完成，本方法返回的期货将在最后一个期货完成的线程中完成。因此，连接到whenAll() 返回的 future 的连续函数不能总是假设它们将在哪个线程上运行。如果您想控制在哪个线程上调用 continuations，请使用.then() 的重载，该重载需要一个上下文对象。

此函数在 Qt 6.3 中引入。

[since 6.3] template <typename OutputSequence, typename InputIt> QFuture<OutputSequence> QtFuture::whenAll(InputIt first, InputIt last)

当从first 到last 的所有期货都完成时，返回一个新的QFuture 。first 和last 是期货序列的迭代器，封装类型为T 。OutputSequence 是一个序列，包含从first 到last 的所有已完成期货，出现顺序与输入相同。如果未指定OutputSequence 的类型，产生的期货将以QFuture<T> 的QList 返回。例如

QList<QFuture<int>> inputFutures {...};

// whenAll has type QFuture<QList<QFuture<int>>>
auto whenAll = QtFuture::whenAll(inputFutures.begin(), inputFutures.end());

// whenAllVector has type QFuture<std::vector<QFuture<int>>>
auto whenAllVector =
        QtFuture::whenAll<std::vector<QFuture<int>>>(inputFutures.begin(), inputFutures.end());

注意： 输出序列必须支持随机存取和resize() 操作。

如果first 等于last ，该函数将返回一个包含空OutputSequence 的就绪QFuture 。

返回的未来总是在所有指定的未来完成后才成功完成。如果这些期货中的任何一个出错或被取消，都没有关系。在whenAll() 返回的未来成功完成后，可以使用.then() 处理已完成的未来：

QList<QFuture<int>> inputFutures {...};

QtFuture::whenAll(inputFutures.begin(), inputFutures.end())
        .then([](const QList<QFuture<int>> &results) {
            for (auto future : results) {
                if (future.isCanceled())
                    // handle the cancellation (possibly due to an exception)
                else
                    // do something with the result
            }
        });

注意： 如果输入的期货在不同的线程上完成，本方法返回的期货将在最后一个期货完成的线程中完成。因此，连接到whenAll() 返回的 future 的连续函数不能总是假设它们将在哪个线程上运行。如果您想控制在哪个线程上调用 continuations，请使用.then() 的重载，该重载需要一个上下文对象。

此函数在 Qt 6.3 中引入。

[since 6.3] template <typename... Futures> QFuture<std::variant<std::decay_t<Futures>...>> QtFuture::whenAny(Futures &&... futures)

QFuture futures futures 可以封装任意类型。返回的 future 封装了 类型的值，而 又封装了 中第一个完成的 。您可以使用std::variant<Futures...> futures QFuture std::variant::index()查找 序列中最先完成的 future 的索引。futures

返回的未来总是在指定未来中的第一个未来完成后成功完成。如果第一个 future 出错或被取消，也没有关系。您可以使用.then() 在whenAny() 返回的未来成功后处理结果：

QFuture<int> intFuture = ...;
QFuture<QString> stringFuture = ...;
QFuture<void> voidFuture = ...;

using FuturesVariant = std::variant<QFuture<int>, QFuture<QString>, QFuture<void>>;

QtFuture::whenAny(intFuture, stringFuture, voidFuture).then([](const FuturesVariant &result) {
    ...
    // assuming handleResult() is overloaded based on the QFuture type
    std::visit([](auto &&future) { handleResult(future); }, result);
    ...
});

注意： 如果输入的未来在不同的线程上完成，本方法返回的未来将在第一个未来完成的线程中完成。因此，连接到whenAny() 返回的 future 的连续函数不能总是假设它们将在哪个线程上运行。如果您想控制在哪个线程上调用延续性，请使用.then() 的重载，该重载需要一个上下文对象。

此函数在 Qt 6.3 中引入。

[since 6.3] template <typename T, typename InputIt> QFuture<QtFuture::WhenAnyResult<T>> QtFuture::whenAny(InputIt first, InputIt last)

返回一个新的QFuture ，当从first 到last 的任何一个期货完成时，这个 将成功。first 和last 是一个迭代器，指向一个封装类型为T 的期货序列。返回的期货会打包QtFuture::WhenAnyResult<T> 类型的值，而 类型的值又会打包第一个完成的QFuture 的索引和QFuture 本身。如果first 等于last ，该函数将返回一个就绪的QFuture ，-1 代表QtFuture::WhenAnyResult 结构中的index 字段，默认构造的QFuture<T> 代表future 字段。请注意，默认构造的QFuture 是处于取消状态的已完成 future。

返回的未来总是在指定未来中的第一个未来完成后成功完成。至于第一个 future 是错误完成还是被取消，这并不重要。您可以使用.then() 在whenAny() 返回的未来成功后处理结果：

QList<QFuture<int>> inputFutures = ...;

QtFuture::whenAny(inputFutures.begin(), inputFutures.end())
        .then([](const QtFuture::WhenAnyResult<int> &result) {
            qsizetype index = result.index;
            QFuture<int> future = result.future;
            // ...
        });

注意： 如果输入的未来在不同的线程上完成，本方法返回的未来将在第一个未来完成的线程中完成。因此，连接到whenAny() 返回的 future 的连续函数不能总是假设它们将在哪个线程上运行。如果您想控制在哪个线程上调用延续性，请使用.then() 的重载，该重载需要一个上下文对象。

该函数在 Qt 6.3 中引入。

另请参见 QtFuture::WhenAnyResult 。

© 2025 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.