QFutureWatcher 类

// 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);

成员函数说明

[显式构造函数] QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)

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

[虚析构函数] QFutureWatcher::~QFutureWatcher()

销毁QFutureWatcher对象。

[槽函数] void QFutureWatcher::cancel()

取消由 future() 表示的异步计算。请注意，取消操作是异步进行的。在调用 waitForFinished() 时需要同步取消，请在调用 cancel() 后使用该函数。

在取消的 QFuture 上仍可以访问当前可用结果，但调用此函数后将不再有新结果。此外，一旦取消，此 QFutureWatcher 将不会发送进度和结果就绪信号。这包括 progressValueChanged()、progressRangeChanged()、progressTextChanged()、resultReadyAt() 和 resultsReadyAt() 信号。

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

[signal] void QFutureWatcher::canceled()

如果观察到的 QFuture 被取消，则发出此信号。

[signal] void QFutureWatcher::finished()

当观察到的 QFuture 完成时，发出此信号。

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

返回视图元中的第一个结果。如果结果不可用，则此函数将阻塞并等待结果可用。这是调用resultAt(0)的便捷方法。

参见 resultAt。

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

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

另请参阅 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，计算将恢复。

[槽函数，自6.0版本起] void QFutureWatcher::setSuspended(bool 暂停标志)

如果暂停标志为真，则此函数将挂起由 future对象 表示的异步计算。如果计算已被挂起，则此函数不起作用。QFutureWatcher 在挂起future对象时不会立即停止发送进度和结果准备信号。在挂起时刻，可能仍有正在进行的计算无法停止。此类计算的信号仍将被发送。

如果暂停标志为假，则此函数将继续异步计算。如果计算之前没有被挂起，则此函数不起作用。

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

此函数自 Qt 6.0 起引入。

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

[信号] void QFutureWatcher::started()

当此 QFutureWatcher 开始监控由 setFuture() 设置的未来对象时，将发出此信号。

[槽函数，自6.0版本起] void QFutureWatcher::suspend()

挂起由该future对象表示的异步计算。这是一个便捷方法，它简单调用 setSuspended(true)。

此函数自 Qt 6.0 起引入。

另请参阅resume()。

[信号，自6.0版本起] void QFutureWatcher::suspended()

当 suspend() 生效时，即表示没有更多的正在运行的计算。在收到该信号后不再期望有结果准备或进度报告信号。

此函数自 Qt 6.0 起引入。

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

[信号，自6.0版本起] void QFutureWatcher::suspending()

在将监控的未来对象的状态设置为挂起时将发出此信号。

此函数自 Qt 6.0 起引入。

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

[槽函数，自6.0版本起] void QFutureWatcher::toggleSuspended()

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

此函数自 Qt 6.0 起引入。

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

void QFutureWatcher::waitForFinished()

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