QFutureWatcher Class

// Instantiate the objects and connect to the finished signal.
MyClass myObject;
QFutureWatcher<int> watcher;
QObject::connect(&watcher, &QFutureWatcher<int>::finished, &myObject, &MyClass::handleFinished);

// Start the computation.
QFuture<int> future = QtConcurrent::run([result](){ /*...*/ return result;});
watcher.setFuture(future);

成员函数文档

[explicit] QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)

使用给定的parent 创建一个新的QFutureWatcher。在通过setFuture()设置未来对象之前，函数isStarted()、isCanceled()和isFinished()返回true 。

[virtual] QFutureWatcher::~QFutureWatcher()

销毁QFutureWatcher 。

[slot] void QFutureWatcher::cancel()

取消由 `future()` 所表示的异步计算。请注意，该取消操作是异步的。若需同步取消，请在调用 `cancel()` 后使用 `waitForFinished()`。

虽然仍可访问已取消的QFuture 中当前可用的结果，但在调用此函数后将不会产生新的结果。此外，一旦被取消，该QFutureWatcher 将不再发出进度和结果就绪信号。这包括progressValueChanged()、progressRangeChanged()、progressTextChanged()、resultReadyAt()以及resultsReadyAt()信号。

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

[signal] void QFutureWatcher::canceled()

如果被监视的期货合约被取消，则会触发此信号。

[signal] void QFutureWatcher::finished()

当被监控的期货合约到期时，会发出此信号。

QFuture<T> QFutureWatcher::future() const

返回被监视的未来对象。

另请参阅 ` setFuture()`。

bool QFutureWatcher::isCanceled() const

如果异步计算已被通过cancel()函数取消，或者未设置任何Future，则返回true ；否则返回false 。

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

bool QFutureWatcher::isFinished() const

如果由 `future()` 表示的异步计算已完成，或者未设置任何未来对象，则返回 `true `；否则返回 `false`。

bool QFutureWatcher::isRunning() const

如果由 `future()` 表示的异步计算当前正在运行，则返回 `true `；否则返回 `false`。

bool QFutureWatcher::isStarted() const

如果由 `future()` 表示的异步计算已启动，或者尚未设置任何未来对象，则返回 `true `；否则返回 `false`。

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

如果已请求暂停异步计算且该请求生效（即不再预期有结果或进度变化），则返回true 。

该函数于 Qt 6.0 中引入。

另请参见 suspended()、setSuspended() 和isSuspending()。

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

如果异步计算已被suspend()函数挂起，但工作尚未挂起且计算仍在进行，则返回true ；否则返回false 。

若要检查暂停是否已生效，请改用isSuspended()。

该函数在 Qt 6.0 中引入。

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

int QFutureWatcher::progressMaximum() const

返回progressValue()的最大值。

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

int QFutureWatcher::progressMinimum() const

返回progressValue()的最小值。

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

[signal] void QFutureWatcher::progressRangeChanged(int minimum, int maximum)

所关注期货合约的进度范围已更改为minimum 和maximum 。

QString QFutureWatcher::progressText() const

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

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

[signal] void QFutureWatcher::progressTextChanged(const QString &progressText)

当被监视的期货合约报告文本形式的进度信息时，会触发此信号，progressText 。

int QFutureWatcher::progressValue() const

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

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

[signal] void QFutureWatcher::progressValueChanged(int progressValue)

当被监视的未来对象报告进度时，会发出此信号，progressValue 返回当前进度。为了避免给 GUI 事件循环带来过重负担，QFutureWatcher 会限制进度信号的发出频率。这意味着连接到此槽的监听器可能无法收到该未来对象生成的所有进度报告。但最后一次进度更新（即progressValue 等于最大值时）始终会被传递。

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

返回future()中的第一个结果。如果结果尚未立即可用，则该函数将阻塞并等待结果可用。这是调用resultAt(0)的一个便捷方法。

另请参阅 resultAt()。

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

返回“index ”中future()的处理结果。如果结果无法立即获取，该函数将阻塞并等待结果可用。

另请参阅 result()。

[signal] void QFutureWatcher::resultReadyAt(int index)

当被监视的未来事件在index 上报告结果已准备就绪时，会发出此信号。如果未来事件报告了多个结果，该索引将指示具体是哪个结果。结果可能以非顺序方式报告。要获取结果，请调用resultAt(index)；

[signal] void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex)

当被监视的期货合约报告结果已准备就绪时，会触发此信号。结果的索引范围为beginIndex 至endIndex 。

[slot] void QFutureWatcher::resume()

恢复由 `future()` 表示的异步计算。这是一个便捷方法，仅调用 `setSuspended(false)`。

另请参阅 suspend()。

[signal] void QFutureWatcher::resumed()

当被监视的期货恢复交易时，会发出此信号。

void QFutureWatcher::setFuture(const QFuture<T> &future)

开始监听指定的future 。

如果future 已经启动，监听器最初会发出信号，使监听者了解该未来对象的状态。以下信号（如适用）将按给定顺序发出：started()、progressRangeChanged()、progressValueChanged()、progressTextChanged()、resultsReadyAt()、resultReadyAt()、suspending()、suspended()、canceled() 以及finished()。 其中，resultsReadyAt() 和resultReadyAt() 可能会被多次触发，以涵盖所有可用的结果。progressValueChanged() 和progressTextChanged() 仅会触发一次，以返回最新的进度值和文本。

为避免竞争条件，务必在建立连接后调用此函数。

另请参阅 future()。

void QFutureWatcher::setPendingResultsLimit(int limit)

setPendingResultsLimit() 方法提供了限流控制。当待处理的resultReadyAt() 或resultsReadyAt() 信号的数量超过limit 时，由该未来对象所代表的计算将自动被限流。一旦待处理信号的数量降至limit 以下，计算将恢复。

[slot, since 6.0] void QFutureWatcher::setSuspended(bool suspend)

如果 `suspend ` 为真，则该函数会挂起由 `future()` 表示的异步计算。如果计算已被挂起，则该函数不执行任何操作。当未来被挂起时，`QFutureWatcher ` 不会立即停止发送进度和结果就绪信号。 在暂停的瞬间，可能仍有正在进行的计算无法被停止。此类计算的信号仍将被传递。

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

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

该函数在 Qt 6.0 中引入。

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

[signal] void QFutureWatcher::started()

当该QFutureWatcher 开始监听通过setFuture()设置的未来集合时，会触发此信号。

[slot, since 6.0] void QFutureWatcher::suspend()

暂停由该未来对象所表示的异步计算。这是一个便捷方法，仅调用setSuspended(true)。

该函数在 Qt 6.0 中引入。

另请参阅 resume()。

[signal, since 6.0] void QFutureWatcher::suspended()

当suspend()生效时，会发出此信号，这表示不再有正在运行的计算任务。收到此信号后，预计不会再有结果就绪或进度报告信号。

该函数在 Qt 6.0 中引入。

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

[signal, since 6.0] void QFutureWatcher::suspending()

当被监视的未来对象的状态被设置为“暂停”时，会发出此信号。

该函数在 Qt 6.0 中引入。

另请参见 setSuspended()、suspend() 和suspended()。

[slot, since 6.0] void QFutureWatcher::toggleSuspended()

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

该函数在 Qt 6.0 中引入。

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

void QFutureWatcher::waitForFinished()

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