Класс QFutureWatcher

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

Этот класс был представлен в Qt 4.4.

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

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

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

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

Сигналы

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

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

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

Изменения статуса сообщаются через сигналы started(), finished(), canceled(), paused(), 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()

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

[signal] void QFutureWatcher::finished()

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

[slot] void QFutureWatcher::pause()

Приостанавливает асинхронное вычисление, представленное future(). Это удобный метод, который просто вызывает setPaused(true).

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

[signal] void QFutureWatcher::paused()

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

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

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

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

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

[slot] void QFutureWatcher::resume()

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

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

[signal] void QFutureWatcher::resumed()

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

[slot] void QFutureWatcher::setPaused(bool paused)

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

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

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

См. также paused(), pause(), resume() и togglePaused().

[signal] void QFutureWatcher::started()

Этот сигнал излучается, когда этот QFutureWatcher начинает отслеживать будущее, установленное с помощью setFuture().

[slot] void QFutureWatcher::togglePaused()

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

См. также setPaused(), pause() и 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::isPaused() const

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

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

См. также setPaused() и togglePaused().

bool QFutureWatcher::isRunning() const

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

bool QFutureWatcher::isStarted() const

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

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

T QFutureWatcher::result() const

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

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

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() вычисления).