QFuture Class

成员函数文档

QFuture::QFuture()

创建一个空的、已被取消的未来。

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

创建other 的副本。

另请参见 operator=()。

QFuture::~QFuture()

破坏未来。

请注意，此操作既不会等待也不会取消异步计算。若需确保计算在销毁未来之前完成，请使用waitForFinished() 或QFutureSynchronizer 。

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

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

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

void QFuture::cancel()

取消由该未来对象所代表的异步计算。请注意，取消操作本身也是异步的。若需要同步取消，请在调用 cancel() 之后使用waitForFinished()。

对于已被取消的 Future，仍可访问当前已有的结果，但在调用此函数后将不会有新的结果产生。任何监听此 Future 的QFutureWatcher 对象，在该 Future 被取消后都不会发送进度和结果就绪信号。

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

另请参阅 cancelChain()。

[since 6.10] void QFuture::cancelChain()

取消整个延续链。所有已完成的未来对象保持不变，其结果仍然可用。每个待处理的延续都会被取消，如果延续链中存在onCanceled()处理程序，则会调用该处理程序。

auto f = QtConcurrent::run([] {/*...*/})
                .then([]{
                    // Then 1
                })
                .then([]{
                    // Then 2
                })
                .onCanceled([]{
                    // OnCanceled 1
                })
                .then([]{
                    // Then 3
                })
                .then([]{
                    // Then 4
                })
                .onCanceled([]{
                    // OnCanceled 2
                });
//...
f.cancelChain();

在示例中，如果链在 `Then 2 ` 延续执行之前被取消，则 `OnCanceled 1 ` 和 `OnCanceled 2 ` 两个取消处理程序都会被调用。

如果链在Then 2 之后、但Then 4 之前被取消，则仅会调用OnCanceled 2 。

如果链中的任何延续执行了异步计算并返回了一个表示该计算的QFuture ，那么一旦该嵌套计算开始，cancelChain() 的调用将不会传播到该嵌套计算中。 原因在于：该未来对象只有在外层未来对象完成时才会出现在延续链中，但取消操作可能发生在外层和嵌套的未来对象都在等待其计算完成之时。在这种情况下，需要显式捕获并取消该嵌套的未来对象。

QFuture<void> nested;
auto f = createFuture()
            .then([&]{
                nested = runNestedComputation();
                // do some other work
                return nested;
            })
            .unwrap()
            .then([]{
                // other continuation
            })
            .onCanceled([]{
                // handle cancellation
            });
//...
f.cancelChain();
nested.cancel();

在此示例中，如果 `runNestedComputation() ` 已处于执行中，则只能通过调用 `nested.cancel()` 来取消它。

该函数在 Qt 6.10 中引入。

另请参阅 cancel()。

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

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

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

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

返回一个指向未来中最后一个结果之后的虚拟结果的、STL 风格的const迭代器。

另请参阅 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

如果由该未来对象表示的异步计算已完成，则返回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

如果由该未来对象表示的异步计算当前正在运行，则返回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 。如果相关的QPromise 尚未开始，或者结果已从该未来对象中收集，则返回false 。

该函数在 Qt 6.0 中引入。

另请参阅 takeResult()、result()、results()、resultAt()、isFinished() 以及isResultReadyAt()。

[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 ` 是一个不带参数的可调用对象，其返回值类型由该未来对象封装。取消后，返回的未来对象将封装由 `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 状态。这意味着您可以获取其结果、向其附加延续等。

另请注意，你可以通过启动该链的未来，在延续链执行期间取消该链。假设在Block 1 已经执行时调用了testFuture.cancel() 。下一个延续会检测到已请求取消，因此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 在链完成之前被销毁，则该Future将被取消。详情请参阅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 返回的值进行封装。

只有当抛出异常时，处理程序才会被调用。如果异常是在此处理程序附加之后抛出的，则该处理程序将在因异常导致该未来被报告为已完成的那条线程中执行。 如果处理程序是在该未来对象已经失败后附加的，它将立即在执行 `onFailed()` 的线程中被调用。因此，处理程序不能总是假设它将在哪个线程上运行。若要控制处理程序在哪个线程上被调用，请使用接受上下文对象的重载版本。

下面的示例演示了如何挂接失败处理程序：

QFuture<int> future = someIntFuture;
auto resultFuture = future.then([](int res) {
    //...
    throw Error();
    //...
    return res;
}).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 = someIntFuture;
future.then([](int res) {
    //...
    throw std::runtime_error("message");
    //...
}).onFailed([](const std::exception &e) {
    // This handler will be invoked
    return -1;
}).onFailed([](const std::runtime_error &e) {
    // This handler won't be invoked, because of the handler above.
    return -1;
});

如果没有任何一个处理程序与抛出的异常类型匹配，则该异常将传播到结果 Future：

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

try {
    auto result = resultFuture.result();
} catch(QException &someException) {
    // 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)

将一个故障处理程序附加到该未来对象上，用于处理该未来对象可能抛出的或已经抛出的任何异常。返回一个与该未来对象类型相同的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 上的失败处理程序会更新UI元素，且无法从非GUI线程调用。因此，将this 作为上下文传递给.onFailed() ，以确保其将在主线程中被调用。

如果context 在链处理完成前被销毁，则该Future将被取消。详情请参阅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 ` 为真，则该函数会挂起由 `future()` 表示的异步计算。如果计算已被挂起，则该函数不执行任何操作。当 `future` 被挂起时，`QFutureWatcher ` 不会立即停止发送进度和结果就绪信号。 在暂停的瞬间，可能仍有正在进行且无法停止的计算。此类计算的信号仍会继续被分发。

如果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] 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 是一个可调用对象，如果该未来对象有结果（即不是QFuture<void>），则它会接受一个由该未来对象封装的类型的参数。 否则，它不接受任何参数。该方法返回一个新的QFuture ，该对象封装了由function 返回的类型的值。返回的Future将处于未初始化状态，直到附加的延续被调用，或者直到该Future失败或被取消。

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

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

或者：

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

延续还可以接受一个QFuture 类型的参数（而非其值），该参数代表前一个未来对象。例如，当QFuture 返回多个结果，且用户希望在延续内部访问这些结果时，此功能便十分有用。或者，当用户需要在延续内部处理前一个未来对象的异常，以避免中断多个延续的链式调用时，此功能同样适用。例如：

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

如果前一个未来对象抛出了异常，且该异常未在延续内部被处理，则该异常将传播到延续的未来对象中，以便调用方进行处理：

QFuture<int> future = someIntFuture;
auto continuation = future.then([](int res1){ /*...*/ return res1; }).then([](int res2){ /*...*/ return 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)

将一个延续附加到此未来对象上，从而可在需要时将多个异步计算串联起来。当此未来对象所代表的异步计算完成时，将在context 对象所属的线程中调用function 。如果需要在线程中调用该延续，此功能将非常有用。例如：

// 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::makeReadyVoidFuture()
                                : QtConcurrent::run([] { /* compute result */});
auto continuation = future.then(context, [] {
    // Runs in the context's thread
}).then([] {
    // May or may not run in the context's thread
});

在上例中，如果 `cachedResultsReady ` 为 `true`，且返回了一个已就绪的未来，那么第一个 `.then() ` 可能在第二个被附加之前就已完成。在这种情况下，它将在当前线程中被解析。因此，如有疑问，请显式传递上下文。

如果context 在链完成之前被销毁，则该Future将被取消。这意味着，当context 不再有效时，取消处理程序仍可能被调用。为防范这种情况，请将context 捕获为QPointer ：

QObject *context /*...*/;
QFuture<Result> 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)

将一个延续附加到此未来对象上，以便在需要时串联多个异步计算。当此未来对象所代表的异步计算完成时，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 所代表的异步计算完成时，将根据给定的启动策略policy 调用function 。返回一个表示该延续结果的新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> 中解包内部Future，其中T 是一个类型为QFuture<U> 的Future，即该Future的类型为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 = [scale, reduceImages](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()

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

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

将other 赋值给该未来对象，并返回该未来对象的引用。