Класс QFutureWatcher

Класс QFutureWatcher позволяет отслеживать QFuture с помощью сигналов и слотов. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются повторно входящими.

Публичные функции

Публичные слоты

Сигналы

Подробное описание

QFutureWatcher предоставляет информацию и уведомления о QFuture. Используйте функцию setFuture(), чтобы начать отслеживание определенного QFuture. Функция future() возвращает заданное функцией setFuture() будущее.

Для удобства, несколько функций QFuture также доступны в QFutureWatcher: progressValue(), progressMinimum(), progressMaximum(), progressText(), isStarted(), isFinished(), isRunning(), isCanceled(), isSuspending(), isSuspended(), waitForFinished(), result() и resultAt(). Функции cancel(), setSuspended(), suspend(), resume() и toggleSuspended() являются слотами в QFutureWatcher.

Изменения состояния сообщаются с помощью сигналов started(), finished(), canceled(), suspending(), suspended(), resumed(), resultReadyAt() и resultsReadyAt(). Информация о прогрессе предоставляется сигналами progressRangeChanged(), progressValueChanged() и progressTextChanged().

Управление регулировкой скорости обеспечивается функцией setPendingResultsLimit(). Когда количество ожидающих сигналов resultReadyAt() или resultsReadyAt() превышает лимит, вычисления, представленные будущим, будут автоматически ограничены. Вычисления возобновятся, когда количество ожидающих сигналов упадет ниже лимита.

Пример: Запуск вычисления и получение слота обратного вызова при завершении:

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

Обратите внимание, что не все выполняемые асинхронные вычисления можно отменить или приостановить. Например, будущее, возвращаемое QtConcurrent::run(), не может быть отменено; но будущее, возвращаемое QtConcurrent::mappedReduced(), может.

QFutureWatcher<void> специализируется на том, чтобы не содержать функций извлечения результата. Любое QFuture<T> может быть отслеживаться QFutureWatcher<void> так же. Это полезно, если требуется только информация о статусе или прогрессе; а не фактические данные результата.

См. также QFuture и Qt Concurrent.

Документация по функциям-членам

QFutureWatcher::QFutureWatcher(QObject *parent = nullptr)

Конструирует новый QFutureWatcher с заданным parent. Пока будущее не будет установлено с помощью setFuture(), функции isStarted(), isCanceled() и isFinished() возвращают true.

[slot] void QFutureWatcher::cancel()

Отменяет асинхронное вычисление, представленное свойством future(). Обратите внимание, что отмена выполняется асинхронно. Используйте waitForFinished() после вызова cancel(), если вам нужна синхронная отмена.

Доступ к текущим результатам все еще возможен в отменённом QFuture, но новые результаты не будут доступны после вызова этой функции. Кроме того, этот QFutureWatcher не будет передавать сигналы о прогрессе и готовности результатов после отмены. Это включает сигналы progressValueChanged(), progressRangeChanged(), progressTextChanged(), resultReadyAt() и resultsReadyAt().

Помните, что не все асинхронные вычисления, которые выполняются, могут быть отменены. Например, QFuture, возвращаемый QtConcurrent::run(), отменить нельзя; но QFuture, возвращаемый QtConcurrent::mappedReduced(), можно.

[signal] void QFutureWatcher::canceled()

Этот сигнал испускается, если отслеживаемое будущее отменено.

[signal] void QFutureWatcher::finished()

Этот сигнал испускается, когда отслеживаемое будущее завершено.

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

Диапазон прогресса для отслеживаемого будущего изменился на minimum и maximum.

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

Этот сигнал испускается, когда отслеживаемое будущее сообщает текстовую информацию о прогрессе, progressText.

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

Этот сигнал испускается, когда отслеживаемое будущее сообщает о прогрессе, progressValue указывает текущий прогресс. Для предотвращения перегрузки цикла событий графического интерфейса QFutureWatcher ограничивает скорость испускания сигналов прогресса. Это означает, что подписчики, подключенные к этому слоту, могут не получить все сообщения о прогрессе, отправленные будущим. Последнее обновление прогресса (где progressValue равно максимальному значению) всегда будет передано.

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

Этот сигнал испускается, когда отслеживаемое будущее сообщает о готовом результате в позиции index. Если будущее сообщает о нескольких результатах, индекс указывает, какой именно.

Результаты могут поступать вне очереди. Чтобы получить результат, вызовите resultAt(индекс);

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

Этот сигнал испускается, когда отслеживаемое будущее сообщает о готовых результатах. Результаты индексируются от beginIndex до endIndex.

[slot] void QFutureWatcher::resume()

Возобновляет асинхронное вычисление, представленное свойством future(). Это удобный метод, который просто вызывает setSuspended(false).

См. также suspend().

[signal] void QFutureWatcher::resumed()

Этот сигнал испускается, когда отслеживаемое будущее возобновляется.

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

Если suspend равно true, эта функция приостанавливает асинхронное вычисление, представленное свойством future(). Если вычисление уже приостановлено, эта функция ничего не делает. QFutureWatcher немедленно не прекратит передачу сигналов прогресса и готовности результатов, когда будущее приостанавливается. В момент приостановки могут все еще продолжаться вычисления, которые не могут быть остановлены. Сигналы для таких вычислений все равно будут передаваться.

Если suspend равно false, эта функция возобновляет асинхронное вычисление. Если вычисление не было ранее приостановлено, эта функция ничего не делает.

Обратите внимание, что не все вычисления могут быть приостановлены. Например, QFuture, возвращаемый QtConcurrent::run(), приостановить нельзя; но QFuture, возвращаемый QtConcurrent::mappedReduced(), можно.

Эта функция была добавлена в 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() и suspended().

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

Этот сигнал испускается, когда состояние отслеживаемого будущего устанавливается в приостановленное.

Примечание: Этот сигнал только сообщает о том, что запрос на приостановку был выполнен. Он не указывает, что все фоновые операции остановлены. Сигналы для вычислений, которые выполнялись в момент приостановки, все равно будут передаваться. Чтобы быть уведомленным о том, когда приостановление действительно вступило в силу, используйте сигнал suspended().

Эта функция была добавлена в Qt 6.0.

См. также setSuspended(), suspend() и suspended().

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

Переключает состояние приостановки асинхронного вычисления. Другими словами, если вычисление в настоящее время приостановлено или приостановлено, вызов этой функции возобновляет его; если вычисление выполняется, оно приостанавливается. Это удобный метод для вызова setSuspended(!(isSuspending() || isSuspended())).

Эта функция была добавлена в Qt 6.0.

См. также setSuspended(), suspend() и resume().

[virtual] QFutureWatcher::~QFutureWatcher()

Удаляет QFutureWatcher.

QFuture<T> QFutureWatcher::future() const

Возвращает отслеживаемое будущее.

См. также setFuture().

bool QFutureWatcher::isCanceled() const

Возвращает true , если асинхронное вычисление было отменено с помощью функции cancel(), или если будущее не было установлено; в противном случае возвращает false.

Обратите внимание, что вычисление может все еще выполняться, даже если эта функция возвращает true. См. cancel() для получения более подробной информации.

bool QFutureWatcher::isFinished() const

Возвращает true , если асинхронное вычисление, представленное свойством future(), завершено, или если будущее не было установлено; в противном случае возвращает false.

bool QFutureWatcher::isRunning() const

Возвращает true , если асинхронное вычисление, представленное свойством future(), выполняется в данный момент; в противном случае возвращает false.

bool QFutureWatcher::isStarted() const

Возвращает true , если асинхронное вычисление, представленное свойством future(), было запущено, или если будущее не было установлено; в противном случае возвращает false.

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

Возвращает true , если была запрошена приостановка асинхронного вычисления, и она в действии, что означает, что больше результатов или изменений прогресса ожидаться не должно.

Эта функция была добавлена в Qt 6.0.

См. также suspended(), setSuspended() и isSuspending().

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

Возвращает true, если асинхронное вычисление было приостановлено с помощью функции suspend(), но работа еще не приостановлена, и вычисление все еще выполняется. В противном случае возвращает false.

Чтобы проверить, действительно ли приостановление активное, используйте isSuspended() вместо этого.

Эта функция была добавлена в Qt 6.0.

См. также setSuspended(), toggleSuspended() и isSuspended().

int QFutureWatcher::progressMaximum() const

Возвращает максимальное значение progressValue().

См. также progressValue() и progressMinimum().

int QFutureWatcher::progressMinimum() const

Возвращает минимальное значение progressValue().

См. также progressValue() и progressMaximum().

QString QFutureWatcher::progressText() const

Возвращает (необязательное) текстовое представление прогресса, как сообщается асинхронным вычислением.

Обратите внимание, что не все вычисления предоставляют текстовое представление прогресса, и поэтому эта функция может возвращать пустую строку.

int QFutureWatcher::progressValue() const

Возвращает текущее значение прогресса, которое находится между progressMinimum() и progressMaximum().

См. также progressMinimum() и progressMaximum().

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

Возвращает первый результат в future(). Если результат недоступен немедленно, эта функция заблокируется и дождётся, пока результат станет доступным. Это удобный метод для вызова resultAt(0).

См. также resultAt().

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

Возвращает результат по индексу index в future(). Если результат недоступен немедленно, эта функция заблокируется и дождётся, пока результат станет доступным.

См. также result().

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

Начинает наблюдение за заданным future.

Может быть выведено одно из сигналов для текущего состояния future. Например, если задача уже остановлена, будет выведено завершенное событие.

Для предотвращения гонки, важно вызвать эту функцию после выполнения соединений.

См. также future().

void QFutureWatcher::setPendingResultsLimit(int limit)

setPendingResultsLimit() предоставляет управление ограничением. Когда количество ожидающих сигналов resultReadyAt() или resultsReadyAt() превышает limit, вычисление, представленное future, будет автоматически ограничено. Вычисление возобновится, когда количество ожидающих сигналов станет меньше limit.

void QFutureWatcher::waitForFinished()

Ожидает завершения асинхронного вычисления (включая отмененные вычисления cancel()), т.е. пока isFinished() не вернёт true.