Класс QFutureWatcher

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

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

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

Открытые слоты

Сигналы

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

QFutureWatcher предоставляет информацию и уведомления о QFuture. Используйте функцию setFuture() для начала отслеживания конкретного QFuture. Функция future() возвращает 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(), void progressValueChanged() и progressTextChanged().

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

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

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

Обратите внимание, что не все выполняемые асинхронные вычисления могут быть отменены или приостановлены. Например, future, возвращенное QtConcurrent::run(), не может быть отменено; но future, возвращенное 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 — текущий прогресс. Чтобы избежать перегрузки цикла событий GUI, QFutureWatcher ограничивает скорость генерации сигналов прогресса. Это означает, что подписчики, подключенные к этому слоту, могут не получить все сообщения о прогрессе, которые генерирует будущее. Последнее обновление прогресса (где progressValue равно максимальному значению) всегда будет доставлено.

[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()

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

[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. Например, если будущее уже остановлено, будет выпущен сигнал finished.

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

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

void QFutureWatcher::setPendingResultsLimit(int limit)

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

void QFutureWatcher::waitForFinished()

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