Класс 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(), void 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()

Этот сигнал генерируется, если отслеживаемое future отменено.

[signal] void QFutureWatcher::finished()

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

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

Диапазон прогресса для отслеживаемого future изменён на minimum и maximum

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

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

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

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

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

Этот сигнал генерируется, когда отслеживаемое future сообщает о готовом результате по индексу index. Если future сообщает о нескольких результатах, индекс указывает, какой из них. Результаты могут быть сообщены вне очереди. Для получения результата вызовите resultAt(index);

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

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

[slot] void QFutureWatcher::resume()

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

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

[signal] void QFutureWatcher::resumed()

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

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

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

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

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

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

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

[signal] void QFutureWatcher::started()

Этот сигнал генерируется, когда этот QFutureWatcher начинает отслеживать future, заданное с помощью 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()

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

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

Возвращает отслеживаемое future.

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

bool QFutureWatcher::isCanceled() const

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

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

bool QFutureWatcher::isFinished() const

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

bool QFutureWatcher::isRunning() const

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

bool QFutureWatcher::isStarted() const

Возвращает true если асинхронное вычисление, представленное future(), было начато или если 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, вычисление, представленное задачей, будет автоматически ограничено. Вычисление возобновится, как только количество ожидающих сигналов станет меньше limit.

void QFutureWatcher::waitForFinished()

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