QFuture 类

成员函数文档

QFuture::QFuture()

构建一个空的、已取消的未来对象。

QFuture::QFuture(const QFuture<T> &other)

构建 other 的副本。

参见：operator=()。

QFuture::~QFuture()

销毁未来对象。

注意，这既不等待也不取消异步计算。当您需要确保计算在未来对象被销毁之前完成时，请使用 waitForFinished() 或 QFutureSynchronizer。

模板 QFuture<T>::const_iterator QFuture::begin() const

返回一个指向未来对象中第一个结果的常量 STL 风格的迭代器。

参见：constBegin() 和 end()。

void QFuture::cancel()

取消由此未来对象表示的异步计算。请注意，取消是异步的。当您需要同步取消时，在调用 cancel() 后使用 waitForFinished()。

取消操作后，可以访问当前可用的结果，但在调用此函数后，将 不会 出现新结果。任何监视此未来对象的 QFutureWatcher 对象将不会在已取消的未来对象上发送进度和结果就绪信号。

请注意，并非所有正在运行的非阻塞计算都可以取消。例如，QtConcurrent::run() 返回的未来对象无法取消；但 QtConcurrent::mappedReduced() 返回的未来对象可以取消。

返回一个指向未来对象中第一个结果的常量 STL 风格的迭代器。

相关条目：begin() 和 constEnd().

返回一个指向未来中最后一个结果之后的虚拟结果的常量STL样式迭代器。

参见：constBegin() 和 end()。

返回一个指向未来中最后一个结果之后的虚拟结果的常量STL样式迭代器。

相关条目：begin() 和 constEnd().

bool QFuture::isCanceled() const

如果异步计算已被cancel()函数取消，则返回true；否则返回false。

请注意，即使此函数返回true，计算也可能仍在进行中。有关更多信息，请参阅cancel。

bool QFuture::isFinished() const

如果由此未来表示的非阻塞计算已完成，则返回true；否则返回false。

如果索引为index的结果立即可用，则返回true；否则返回false。

相关条目：resultAt()，resultCount和takeResult。

bool QFuture::isRunning() const

如果由此未来表示的非阻塞计算当前正在运行，则返回true；否则返回false。

bool QFuture::isStarted() const

如果由此未来表示的非阻塞计算已启动，则返回true；否则返回false。

[since 6.0] bool QFuture::isSuspended() const

如果已请求挂起异步计算，并且它正在生效（即不再期望更多的结果或进度变化），则返回true。

此函数自Qt 6.0开始引入。

相关条目：setSuspended()，toggleSuspended和isSuspending。

[since 6.0] bool QFuture::isSuspending() const

如果异步计算已被suspend()函数挂起，但尚未暂时停止，计算仍在进行，则返回true。否则返回false。

要检查是否实际悬挂，请使用isSuspended()。

此函数自Qt 6.0开始引入。

另请参阅setSuspended()、toggleSuspended()和isSuspended()。

[since 6.0] bool QFuture::isValid() const

如果可以从此QFuture对象访问或获取结果，则返回true。结果从未来中提取后返回false。

此函数自Qt 6.0开始引入。

另请参阅takeResult()、result()、results()和resultAt()。

[since 6.0] 模板 <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(Function &&handler)

将一个取消处理器附加到此未来。返回的未来将具有与当前相同的状态和结果，除非此未来被取消。处理器是一个可调用对象，它不接收任何参数，并返回此未来打包的类型值。在取消后，返回的未来将包装处理器返回的值。

如果在未来取消之前附加，处理器会在这个报告未来结束的线程中被调用。如果在未来已经被取消后附加处理器，则处理器会立即在执行onCanceled()的线程中被调用。因此，处理器不能总是假定将在哪个线程上运行。如果您想要控制处理器在哪个线程上被调用，请使用接收上下文对象的 overload。

以下示例演示了如何附加取消处理器

QFuture<int> testFuture = ...;
auto resultFuture = testFuture.then([](int res) {
    // Block 1
    ...
    return 1;
}).then([](int res) {
    // Block 2
    ...
    return 2;
}).onCanceled([] {
    // Block 3
    ...
    return -1;
});

如果testFuture被取消，则Block 3将被调用，并且resultFuture的结果将为-1。与testFuture不同，它不会处于已取消状态。这意味着您可以获取其结果、向其添加连续性，等等。

请注意，您还可以通过启动连锁的future来在它们执行时通过future取消连锁。假设在Block 1已经执行时调用了testFuture.cancel()。下一个连锁将检测到已请求取消，因此将跳过Block 2，并将取消处理器（Block 3）调用。

此函数自Qt 6.0开始引入。

另请参阅 then() 和 onFailed()。

[自6.1以来] 模板 <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)

这是一个重载函数。

为此将取消处理器附加到此将在此将取消附加到此将取消，以在取消时调用它。处理器是一个无参数的可调用对象。它将在上下文对象的线程中被调用。如果需要在该特定线程中处理取消，这可能很有用。

如果上下文在链完成之前被摧毁，则此将取消。

有关其他重载的详细说明，请参阅处理器的文档。

该功能是在Qt 6.1中引入的。

另请参阅 then() 和 onFailed()。

[自6.0以来] 模板 <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(Function &&handler)

为此将失败处理器附加到此，以处理任何异常。除非此将失败抛出异常，否则返回的未来将与此时的状态和结果相同。

处理器是无参数或有参数的可调用对象，以过滤特定错误类型，类似于捕获语句。它返回由此返回的值。失败后，返回的未来包装处理器返回的值。

处理器只有在抛出异常时才会被调用。如果在此处理器附加之后抛出了异常，则在报告未来完成的线程中将执行处理器。如果在此未来失败后附加处理器，它将立即在执行onFailed()的线程中调用。因此，处理器无法始终假设它将在哪个线程上运行。如果您想控制调用处理器所在的线程，请使用接受上下文对象的泛型重载。

以下示例演示了如何附加失败处理器：

QFuture<int> future = ...;
auto resultFuture = future.then([](int res) {
    ...
    throw Error();
    ...
}).onFailed([](const Error &e) {
    // Handle exceptions of type Error
    ...
    return -1;
}).onFailed([] {
    // Handle all other types of errors
    ...
    return -1;
});

auto result = resultFuture.result(); // result is -1

如果有多个处理器已附加，则将与抛出异常类型匹配的第一个处理器被调用。例如：

QFuture<int> future = ...;
future.then([](int res) {
    ...
    throw std::runtime_error("message");
    ...
}).onFailed([](const std::exception &e) {
    // This handler will be invoked
}).onFailed([](const std::runtime_error &e) {
    // This handler won't be invoked, because of the handler above.
});

如果没有与抛出异常类型匹配的处理器，则异常将传播到结果未来。

QFuture<int> future = ...;
auto resultFuture = future.then([](int res) {
    ...
    throw Error("message");
    ...
}).onFailed([](const std::exception &e) {
    // Won't be invoked
}).onFailed([](const QException &e) {
    // Won't be invoked
});

try {
    auto result = resultFuture.result();
} catch(...) {
    // Handle the exception
}

此函数自Qt 6.0开始引入。

另请参阅 then() 和 onCanceled。

[自6.1以来] 模板 <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)

这是一个重载函数。

将错误处理器附加到该QFuture对象，用于处理该QFuture产生的任何异常，或者它已经产生的异常。返回类型与该QFuture相同的QFuture。只有在发生异常的情况下，处理器才会在上下文对象的线程中调用。如果在特定线程中处理失败情况非常有用。例如

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    ...
    throw std::exception();
}).onFailed(this, [] {
   // Update UI elements
});

附加到QtConcurrent::run的错误处理器更新UI元素，无法从非GUI线程调用。所以提供此上下文给.onFailed()，以确保它将在主线程中调用。

如果上下文在链完成之前被摧毁，则此将取消。

有关其他重载的详细说明，请参阅处理器的文档。

该功能是在Qt 6.1中引入的。

另请参阅 then() 和 onCanceled。

int QFuture::progressMaximum() const

返回的最大progressValue值。

另请参阅 progressValue()和progressMinimum()。

int QFuture::progressMinimum() const

返回最小progressValue值。

另请参阅 progressValue()和progressMaximum。

QString QFuture::progressText() const

返回异步计算报告的进度（可选）文本表示形式。

请注意，并非所有计算都提供进度的文本表示形式，因此此函数可能返回空字符串。

int QFuture::progressValue() const

返回当前进度值，该值在progressMinimum()和progressMaximum()之间。

另请参阅 progressMinimum()和progressMaximum。

模板 <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::result() const

返回QFuture中的第一个结果。如果结果不可立即获得，此函数将阻塞并等待结果可用。这是调用resultAt(0)的便捷方法。请注意，result()返回内部存储结果的副本。如果T是移动类型，或者您不希望复制结果，请使用takeResult()。

另请参阅 resultAt()、results()和takeResult。

模板 <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::resultAt(int index) const

返回位于未来中索引处的结果。如果结果不可立即获得，此函数将阻塞并等待结果可用。

另请参阅 result()、results()、takeResult()和resultCount。

int QFuture::resultCount() const

返回此未来中的连续结果数量。由于结果集可能存在空缺，实际存储的结果数量可能与该值不同。始终可以安全地从0迭代到resultCount()遍历结果。

另请参阅 result()，resultAt()，results()，和takeResult()。

模板 <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QList<T> QFuture::results() const

返回未来中所有结果。如果结果不可立即获得，此函数将阻塞并等待他们变得可用。请注意，results()返回内部存储结果的副本。目前不支持获取移动类型的结果T。但是，您仍然可以使用STL样式迭代器或只读Java样式的迭代器遍历移动结果列表。

另请参阅 result()，resultAt()，takeResult()，resultCount()，和isValid()。

void QFuture::resume()

恢复由future()表示的异步计算。这是一个方便的方法，它简单地调用setSuspended(false)。

另请参阅 suspend()。

[since 6.0] void QFuture::setSuspended(bool suspend)

如果suspend为true，则此函数将挂起由future()表示的异步计算。如果计算已经挂起，此函数将不做任何操作。在挂起时，可能仍有正在进行的计算不能被停止。对于这些计算的信号仍会传递。

如果suspend为false，则此函数将恢复异步计算。如果计算之前未挂起，此函数将不做任何操作。

请注意，并非所有计算都可以挂起。例如，由QtConcurrent::run()返回的QFuture不能挂起；但是由QtConcurrent::mappedReduced()返回的QFuture可以。

此函数自Qt 6.0开始引入。

另请参阅 isSuspended()，suspend()，resume()，和toggleSuspended()。

[since 6.0] void QFuture::suspend()

挂起此未来表示的异步计算。这是一个方便的方法，它简单地调用setSuspended(true)。

此函数自Qt 6.0开始引入。

另请参阅 resume()。

[since 6.0] 模板 <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> T QFuture::takeResult()

只有在isValid()返回true时才调用此函数，否则行为未定义。此函数从QFuture对象中取出（移动）第一个结果，当预期只有一个结果时。如果有其他任何结果，则在取出第一个结果后会丢弃。如果结果不能立即可用，此函数将阻塞并等待结果变得可用。《a href="qfuture.html" translate="no">QFuture会尽可能使用移动语义，如果类型不可移动，则会回退到复制构造函数。结果被提取后，《a href="qfuture.html#isValid" translate="no">isValid()将评估为false。

此函数自Qt 6.0开始引入。

另请参阅：result函数、results函数、resultAt函数以及isValid函数。

[since 6.0] 模板 <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(Function &&function)

这是一个重载函数。

将后续操作附加到此未来上，允许在需要的情况下使用Sync策略链式调用多个异步计算。如果此未来有结果（不是QFuture<void>），则function是可调用的，其需要一个与该未来打包的类型的参数。否则，它不接受任何参数。该方法返回一个新QFuture，该废弃物返回的结果类型为function。返回的未来将在附加的后续操作被调用、此未来失败或被取消之前处于未初始化状态。

您可以像这样链式调用多个操作

QFuture<int> future = ...;
future.then([](int res1){ ... }).then([](int res2){ ... })...

或者

QFuture<void> future = ...;
future.then([](){ ... }).then([](){ ... })...

后续操作也可以接受一个QFuture参数（而不是它的值），表示先前的未来。如果，例如QFuture有多个结果，并且用户希望在后续操作中访问它们，这可能很有用。或者用户需要在后续操作中处理先前的未来的异常，以防止中断多个后续操作的链。例如

QFuture<int> future = ...;
    future.then([](QFuture<int> f) {
        try {
            ...
            auto result = f.result();
            ...
        } catch (QException &e) {
            // handle the exception
        }
    }).then(...);

如果先前的未来抛出一个异常，并且没有在后续操作中处理它，则异常将传播到后续操作未来中，允许调用者处理它。

QFuture<int> future = ...;
auto continuation = future.then([](int res1){ ... }).then([](int res2){ ... })...
...
// future throws an exception
try {
    auto result = continuation.result();
} catch (QException &e) {
    // handle the exception
}

在这种情况下，整个后续操作链将中断。

此函数自Qt 6.0开始引入。

另请参阅：onFailed()和onCanceled()函数。

[自 6.0] 模板 <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QtFuture::Launch policy, Function &&function)

这是一个重载函数。

将为这个未来附加一个后续操作，允许链接多个异步计算。当代表此未来的异步计算完成时，将根据给定的启动policy调用function。将返回一个表示继续操作结果的新的QFuture。

根据policy，后续操作将在与这个未来相同的线程中调用，在一个新线程中，或者将继承这个未来的启动策略和线程池。如果没有指定启动策略（请参阅仅接受可调用对象的重载），则将使用Sync策略。

以下示例中，两个后续操作将在新线程中调用（但属于同一个线程）。

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... }).then([](int res2){ ... });

以下示例中，两个后续操作将使用相同的线程池在新线程中调用。

QFuture<int> future = ...;
future.then(QtFuture::Launch::Async, [](int res){ ... })
      .then(QtFuture::Launch::Inherit, [](int res2){ ... });

有关更多信息，请参阅其他重载的文档，以了解关于function的详细信息。

此函数自Qt 6.0开始引入。

另请参阅：onFailed()和onCanceled()函数。

[自 6.0] 模板 <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QThreadPool *pool, Function &&function)

这是一个重载函数。

将为这个未来附加一个后续操作，如果需要的话，可以链接多个异步计算。当代表此未来的异步计算完成时，function将被安排在高pool。

此函数自Qt 6.0开始引入。

另请参阅：onFailed()和onCanceled()函数。

[自 6.1] 模板 <typename Function> QFuture<QFuture<T>::ResultType<Function>> QFuture::then(QObject *context, Function &&function)

这是一个重载函数。

将为这个未来附加一个后续操作，如果需要的话，可以链接多个异步计算。当代表此未来的异步计算完成时，function将在这个context对象的线程中调用。这对于需要在任何特定线程中调用继续操作非常有用。例如

// somewhere in the main thread
auto future = QtConcurrent::run([] {
    // This will run in a separate thread
    ...
}).then(this, [] {
   // Update UI elements
});

附加到QtConcurrent::run的继续操作将更新UI元素，不能从非GUI线程中调用。因此，this被提供给.then()，以确保它将调用主线程。

以下也会从相同的上下文中调用继续操作，除非指定了不同的上下文或启动策略

auto future = QtConcurrent::run([] {
    ...
}).then(this, [] {
   // Update UI elements
}).then([] {
    // This will also run in the main thread
});

这是因为默认情况下.then()是从之前的同一个线程中调用的。

但是请注意，如果继续操作在未来的完成后附加，它将立即调用，在执行then()的线程中

QObject *context = ...;
auto future = cachedResultsReady ? QtFuture::makeReadyValueFuture(result)
                                 : QtConcurrent::run([] { /* compute result */});
auto continuation = future.then(context, [] (Result result) {
    // Runs in the context's thread
}).then([] {
    // May or may not run in the context's thread
});

在上面的示例中，如果cachedResultsReady为true，并且返回了一个就绪的未来，那么有可能第一个.then()在第二个.then()附加之前完成。在这种情况下，它将在当前线程中解决。因此，在不确定的情况下，请明确传递上下文。

如果在链完成之前销毁了上下文，则取消未来。这意味着可能会在上下文不再有效时调用取消处理程序。为此，将上下文捕获为QPointer

QObject *context = ...;
auto future = ...;
auto continuation = future.then(context, [context](Result result) {
                               // ...
                           }).onCanceled([context = QPointer(context)] {
                               if (!context)
                                   return;  // context was destroyed already
                               // handle cancellation
                           });

当上下文对象销毁时，取消操作立即发生。链中的先前的未来不会取消，将继续执行直到完成。

该功能是在Qt 6.1中引入的。

另请参阅：onFailed()和onCanceled()函数。

[自6.0起] void QFuture::toggleSuspended()

切换异步计算的暂停状态。换句话说，如果计算当前正在挂起或已挂起，调用此函数将恢复它；如果计算正在运行，则将其挂起。这是一个调用setSuspended(!(isSuspending() || isSuspended()))的便利方法。

此函数自Qt 6.0开始引入。

另请参阅setSuspended()、suspend()和resume()

[自6.4起] template <typename U> QFuture<U> QFuture::unwrap()

从此QFuture<T>中解包内部未来，其中T是类型QFuture<U>的未来，即此未来的类型为QFuture<QFuture<U>>。例如

QFuture<QFuture<int>> outerFuture = ...;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

unwrappedFuture将在内部未来解包在outerFuture中完成时满足，具有相同的结果或异常，并在报告内部未来完成的同一线程中。如果内部未来被取消，则unwrappedFuture也将被取消。

这在将多个计算串联起来，并且其中一个返回QFuture作为其结果类型时特别有用。例如，假设我们想从URL下载多个图像，缩放图像，并使用QtConcurrent::mappedReduced()将它们减少到单个图像。我们可以编写如下内容

auto downloadImages = [] (const QUrl &url) {
    QList<QImage> images;
    ...
    return images;
};

auto processImages = [](const QList<QImage> &images) {
   return QtConcurrent::mappedReduced(images, scale, reduceImages);
}

auto show = [](const QImage &image) { ... };

auto future = QtConcurrent::run(downloadImages, url)
               .then(processImages)
               .unwrap()
               .then(show);

在此处 QtConcurrent::mappedReduced()返回一个QFuture<QImage>，因此.then(processImages)返回一个QFuture<QFuture<QImage>>。由于show()需要一个QImage作为参数，因此我们不能直接将.then(processImages)的结果传递给它。我们需要调用.unwrap()，这将获取内部未来的结果并将其传递给下一个回调。

在多层嵌套的情况下，.unwrap()将深入到最内层

QFuture<QFuture<QFuture<int>>>> outerFuture;
QFuture<int> unwrappedFuture = outerFuture.unwrap();

此功能自Qt 6.4引入。

void QFuture::waitForFinished()

等待异步计算完成（包括已取消的计算），即直到isFinished()返回true。

QFuture<T> &QFuture::operator=(const QFuture<T> &other)

将other分配给此未来并返回对此未来的引用。