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 延续的执行策略。

常量值描述
QtFuture::Launch::Sync0该延续将在满足与该延续所附加的未来相关的承诺的同一线程中启动；如果该承诺已经完成，则该延续将在执行then() 的线程中立即被调用。
QtFuture::Launch::Async1延续将在从全局QThreadPool 取出的单独线程中启动。
QtFuture::Launch::Inherit2延续将继承其所关联的 Future 的启动策略或线程池。

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::tuple。如果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)

创建并返回一个QFuture ，该对象已包含一个exception 异常。

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> requires if_container_with_input_iterators<Container> QFuture<QtFuture::ContainedType<Container>> QtFuture::makeReadyRangeFuture(Container &&container)

接受一个输入容器container ，并返回一个QFuture ，其中包含多个类型为ContainedType 的结果，这些结果由container 的值初始化而来。

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)

返回一个包含多个类型为ValueType 的结果的QFuture ，这些结果由输入初始化列表values 初始化。

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)

创建并返回一个QFuture ，该对象已包含结果value 。返回的QFuture 类型为std::decay_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 中相应位置的条目将是一个std::variant ，其中包含处于已完成状态的QFuture<T> 。如果未指定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 上的延续函数无法始终确定其将在哪个线程上运行。若需控制延续函数的调用线程，请使用接受上下文对象的 `.then() ` 重载版本。

该函数于 Qt 6.3 中引入。

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

返回一个新的QFuture ，当first 到last 之间的所有未来对象均完成时，该对象返回成功。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 ，则该函数返回一个已就绪的QFuture ，其中包含一个空的OutputSequence 。

返回的未来对象总是在所有指定的未来对象完成后成功完成。即使其中任何一个未来对象因错误而完成或被取消，也不会影响结果。您可以在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 上的延续函数不能总是假设它们将在哪个线程上运行。若要控制延续函数在哪个线程上被调用，请使用接受上下文对象的.then() 重载版本。

该函数于 Qt 6.3 版本中引入。

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

返回一个新的QFuture ，当futures 中的任意一个完成时，该Future即成功。futures 可以封装任意类型。返回的Future封装了类型为std::variant<Futures...> 的值，该值又封装了futures 中第一个完成的QFuture 。您可以使用std::variant::index()来查找在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 ，其QtFuture::WhenAnyResult 结构中的index 字段值为-1 ，而future 字段则为默认构造的QFuture<T> 。请注意，默认构造的QFuture 是一个处于已取消状态的已完成Future。

当指定未来集合中的第一个未来完成时，返回的未来总是会成功完成。无论第一个未来是因错误完成还是被取消，都不影响结果。您可以在whenAny() 返回的未来成功后，使用.then() 来处理结果：

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 。

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