QFutureWatcher Class

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

// Start the computation.
QFuture<int> future = QtConcurrent::run(...);
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() 函数取消了异步计算，或者没有设置未来，则返回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

返回future() 中index 的结果。如果无法立即获得结果，该函数将阻塞并等待结果出现。

另请参见 result()。

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

当被监视的 future 在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 为 true，此函数将暂停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()

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

此函数在 Qt 6.0 中引入。

另请参阅 resume()。

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

该信号在suspend() 生效时发出，意味着不再有正在运行的计算。收到此信号后，将不再有结果就绪或进度报告信号。

此函数在 Qt 6.0 中引入。

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

[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()ed 计算），即直到isFinished() 返回true 。