QFuture Class

成员函数文档

QFuture::QFuture()

构造一个空的、已取消的未来。

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

构造other 的副本。

另请参见 operator=().

QFuture::~QFuture()

销毁未来。

请注意，这既不会等待也不会取消异步计算。如果需要确保在销毁 future 之前完成计算，请使用waitForFinished() 或QFutureSynchronizer 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::begin() const

返回指向未来第一个结果的 ConstSTL 样式迭代器。

另请参阅 constBegin() 和end()。

void QFuture::cancel()

取消该 future 所代表的异步计算。请注意，取消是异步的。如果需要同步取消，请在调用 cancel() 后使用waitForFinished() 。

当前可用的结果仍可在已取消的 future 上访问，但调用此函数后，新结果将不可用。任何正在关注此 future 的QFutureWatcher 对象都不会在取消的 future 上发送进度和结果就绪信号。

请注意，并非所有正在运行的异步计算都可以取消。例如，QtConcurrent::run() 返回的 future 不能取消；但 QtConcurrent::mappedReduced() 返回的 future 可以。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constBegin() const

返回指向未来第一个结果的 ConstSTL 样式迭代器。

另请参阅 begin() 和constEnd()。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::constEnd() const

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

另请参阅 constBegin() 和end() 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> QFuture<T>::const_iterator QFuture::end() const

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

另请参阅 begin() 和constEnd() 。

bool QFuture::isCanceled() const

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

请注意，即使此函数返回true ，计算仍可能在运行。更多详情，请参阅cancel() 。

bool QFuture::isFinished() const

如果该 future 所代表的异步计算已经完成，则返回true ；否则返回false 。

template <typename U = T, typename = QtPrivate::EnableForNonVoid<U>> bool QFuture::isResultReadyAt(int index) const

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

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

bool QFuture::isRunning() const

如果此 future 代表的异步计算当前正在运行，则返回true ；否则返回false 。

bool QFuture::isStarted() const

如果该 future 所代表的异步计算已经启动，则返回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] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(Function &&handler)

将取消handler 附加到此未来。除非该未来被取消，否则返回的未来的行为与该未来完全相同（具有相同的状态和结果）。handler 是一个不带参数的可调用程序，它返回的值与此 future 封装的值类型相同。取消后，返回的 future 将打包handler 返回的值。

如果在取消前附加了处理程序，handler 将在同一线程中被调用，该线程会在取消后报告未来已完成。如果处理程序是在未来已取消后附加的，它将立即在执行onCanceled() 的线程中被调用。因此，处理程序不能总是假设将在哪个线程上运行。如果想控制在哪个线程上调用处理程序，请使用接收上下文对象的重载。

下面的示例演示了如何附加取消处理程序：

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 不同，它不会处于Canceled 状态。这意味着您可以获取它的结果、附加计数等。

还要注意的是，您可以通过启动连续操作链的未来取消正在执行的连续操作链。假设testFuture.cancel() 被调用时，Block 1 已经在执行。下一个延续将检测到取消请求，因此Block 2 将被跳过，取消处理程序 (Block 3) 将被调用。

该函数在 Qt 6.0 中引入。

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

[since 6.1] template <typename Function, typename = std::enable_if_t<std::is_invocable_r_v<T, Function>>> QFuture<T> QFuture::onCanceled(QObject *context, Function &&handler)

这是一个重载函数。

将取消handler 附加到此未来，在未来被取消时调用。handler 是一个不带任何参数的可调用函数。它将在context 对象的线程中调用。如果需要在特定线程中处理取消，这将非常有用。

如果context 在链结束前被销毁，则未来将被取消。详情请参见then() 。

有关handler 的详细信息，请参阅其他重载的文档。

此函数在 Qt 6.1 中引入。

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

[since 6.0] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(Function &&handler)

为该未来附加一个失败处理程序，以处理任何异常。返回的未来行为与此未来完全相同（具有相同的状态和结果），除非此未来因异常而失败。

handler 是一个不带参数或只带一个参数的可调用函数，用于过滤特定的错误类型，类似于catch语句。它返回一个由该 future 封装的类型值。失败后，返回的 future 会打包handler 返回的值。

只有当异常发生时，处理程序才会被调用。如果异常是在附加了该处理程序后发生的，那么处理程序将在因异常而报告 future 已结束的线程中执行。如果处理程序是在未来已失败后附加的，则会立即在执行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()。

[since 6.1] template <typename Function, typename = std::enable_if_t<!QtPrivate::ArgResolver<Function>::HasExtraArgs>> QFuture<T> QFuture::onFailed(QObject *context, Function &&handler)

这是一个重载函数。

为该 future 附加一个失败处理程序，以处理该 future 引发或已经引发的任何异常。返回一个与此 future 类型相同的QFuture 。只有在发生异常时，才会在context 对象的线程中调用该处理程序。如果需要在特定线程中处理故障，这将非常有用。例如

// 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 的故障处理程序会更新用户界面元素，因此不能在非用户界面线程中调用。因此，this 将作为.onFailed() 的上下文，以确保在主线程中调用。

如果context 在链结束前被销毁，则未来会被取消。详情请参见then() 。

有关handler 的详细信息，请参阅其他重载的文档。

此函数在 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()。

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

返回未来的第一个结果。如果结果不是立即可用，该函数将阻塞并等待结果可用。这是一种方便的方法，用于调用resultAt(0)。请注意，result() 返回的是内部存储结果的副本。如果T 是只允许移动的类型，或者您不想复制结果，请使用takeResult() 代替。

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

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

返回index 的结果。如果结果不是立即可用，该函数将阻塞并等待结果可用。

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

int QFuture::resultCount() const

返回未来可用的连续结果数。由于结果集中存在间隙，存储结果的实际数量可能与此值不同。从 0 到 resultCount() 之间遍历结果始终是安全的。

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

template <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() 所代表的异步计算。如果计算已经暂停，则此函数不会执行任何操作。当 future 被暂停时，QFutureWatcher 不会立即停止发送进度和结果就绪信号。在暂停的时刻，可能仍有正在进行的计算无法停止。这些计算的信号仍将被发送。

如果suspend 为 false，此函数将恢复异步计算。如果之前没有暂停计算，则此函数不会执行任何操作。

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

该函数在 Qt 6.0 中引入。

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

[since 6.0] void QFuture::suspend()

暂停此 future 所代表的异步计算。这是一个方便的方法，只需调用setSuspended(true)。

此函数在 Qt 6.0 中引入。

另请参阅 resume()。

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

只有当isValid() 返回true 时才调用该函数，否则行为未定义。当预期只有一个结果时，该函数从QFuture 对象中获取（移动）第一个结果。如果还有其他结果，则在获取第一个结果后将其丢弃。如果结果不是立即可用，该函数将阻塞并等待结果可用。QFuture 将尽可能使用移动语义，如果类型不可移动，将退回到复制结构。在得到结果后，isValid() 将作为false 进行评估。

此函数在 Qt 6.0 中引入。

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

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

这是一个重载函数。

Sync function 是一个可调用的函数，如果有结果（不是 <void>），它将接收一个由该 future 封装的类型的参数。否则，它不需要任何参数。此方法返回一个新的 ，它封装了一个由 返回类型的值。返回的 future 将处于未初始化状态，直到所附的延续被调用，或这个 future 失败或被取消。QFuture QFuture function

您可以像这样链式执行多个操作：

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

或者

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

Continuation 也可以接受一个QFuture 参数（而不是其值），代表前一个 future。举例来说，如果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()。

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

这是一个重载函数。

将一个延续附加到此 future，以便在需要时链式执行多个异步计算。当该 future 所代表的异步计算完成后，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 中的延续会更新用户界面元素，因此不能在非 gui 线程中调用。因此，this 将作为.then() 的上下文，以确保在主线程中调用。

除非指定了不同的上下文或启动策略，否则也将在同一上下文中调用以下继续程序：

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

这是因为默认情况下，.then() 与前一个程序在同一线程中调用。

但要注意的是，如果在这个 future 已经结束后才附加该延续，那么它将立即在执行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() 有可能在第二个未来被附加之前就已完成。在这种情况下，它将在当前线程中解决。因此，如有疑问，请明确传递上下文。

如果context 在链结束前被销毁，则未来会被取消。这意味着当context 不再有效时，可能会调用取消处理程序。为防止出现这种情况，可将context 作为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()。

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

这是一个重载函数。

为该 future 附加一个延续，以便在需要时连锁多个异步计算。当该 future 所代表的异步计算完成时，function 将被调度到pool 。

此函数在 Qt 6.0 中引入。

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

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

这是一个重载函数。

为该 future 附加一个延续，从而可以链式执行多个异步计算。当该 future 所代表的异步计算结束时，function 将根据给定的启动policy 被调用。会返回一个新的QFuture ，代表继续的结果。

根据policy ，继续将在与此 future 相同的线程、新线程或继承此 future 的启动策略和线程池中调用。如果没有指定启动策略（请参阅重载只接收一个可调用代码），则将使用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()。

[since 6.0] void QFuture::toggleSuspended()

切换异步计算的暂停状态。换句话说，如果计算当前处于暂停或中止状态，则调用此函数可恢复计算；如果计算正在运行，则处于暂停状态。这是调用setSuspended(!(isSuspending() ||isSuspended())) 的便捷方法。

该函数在 Qt 6.0 中引入。

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

[since 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 一旦嵌套在 中的内部将来时执行完毕，就会立即执行，并在报告内部将来时执行完毕的同一线程中出现相同的结果或异常。如果内部 future 被取消， 也会被取消。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() ，它将在准备就绪时获取内部 future 的结果，并将其传递给下一个延续。

在多重嵌套的情况下，.unwrap() 会向下传递到最内层：

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

该函数在 Qt 6.4 中引入。

void QFuture::waitForFinished()

等待异步计算结束（包括cancel()ed 计算），即直到isFinished() 返回true 。

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

将other 赋值给此 future，并返回此 future 的引用。