QFutureWatcher Class

The QFutureWatcher class allows monitoring a QFuture using signals and slots. More...

Header: #include <QFutureWatcher>
qmake: QT += core
Since: Qt 4.4

Note: All functions in this class are reentrant.

Public Functions

QFutureWatcher(int *_parent = nullptr)
~QFutureWatcher()
void canceled()
void finished()
QFuture<T> future() const
bool isCanceled() const
bool isFinished() const
bool isPaused() const
bool isRunning() const
bool isStarted() const
void pause()
void paused()
int progressMaximum() const
int progressMinimum() const
void progressRangeChanged(int minimum, int maximum)
QString progressText() const
void progressTextChanged(const QString &progressText)
int progressValue() const
void progressValueChanged(int progressValue)
T result() const
T resultAt(int index) const
void resultReadyAt(int resultIndex)
void resultsReadyAt(int beginIndex, int endIndex)
void resume()
void resumed()
void setFuture(const QFuture<T> &future)
void setPaused(bool paused)
void setPendingResultsLimit(int limit)
void togglePaused()
void waitForFinished()

Public Variables

int

Detailed Description

The QFutureWatcher class allows monitoring a QFuture using signals and slots.

QFutureWatcher provides information and notifications about a QFuture. Use the setFuture() function to start watching a particular QFuture. The future() function returns the future set with setFuture().

For convenience, several of QFuture's functions are also available in QFutureWatcher: progressValue(), progressMinimum(), progressMaximum(), progressText(), isStarted(), isFinished(), isRunning(), isCanceled(), isPaused(), waitForFinished(), result(), and resultAt(). The cancel(), setPaused(), pause(), resume(), and togglePaused() functions are slots in QFutureWatcher.

Status changes are reported via the started(), finished(), canceled(), paused(), resumed(), resultReadyAt(), and resultsReadyAt() signals. Progress information is provided from the progressRangeChanged(), void progressValueChanged(), and progressTextChanged() signals.

Throttling control is provided by the setPendingResultsLimit() function. When the number of pending resultReadyAt() or resultsReadyAt() signals exceeds the limit, the computation represented by the future will be throttled automatically. The computation will resume once the number of pending signals drops below the limit.

Example: Starting a computation and getting a slot callback when it's finished:


  // Instantiate the objects and connect to the finished signal.
  MyClass myObject;
  QFutureWatcher<int> watcher;
  connect(&watcher, SIGNAL(finished()), &myObject, SLOT(handleFinished()));

  // Start the computation.
  QFuture<int> future = QtConcurrent::run(...);
  watcher.setFuture(future);

Be aware that not all asynchronous computations can be canceled or paused. For example, the future returned by QtConcurrent::run() cannot be canceled; but the future returned by QtConcurrent::mappedReduced() can.

QFutureWatcher<void> is specialized to not contain any of the result fetching functions. Any QFuture<T> can be watched by a QFutureWatcher<void> as well. This is useful if only status or progress information is needed; not the actual result data.

See also QFuture and Qt Concurrent.

Member Function Documentation

QFutureWatcher::QFutureWatcher(int *_parent = nullptr)

Default constructs an instance of QFutureWatcher.

QFutureWatcher::~QFutureWatcher()

Destroys the instance of QFutureWatcher.

void QFutureWatcher::canceled()

void QFutureWatcher::finished()

QFuture<T> QFutureWatcher::future() const

See also setFuture().

bool QFutureWatcher::isCanceled() const

bool QFutureWatcher::isFinished() const

bool QFutureWatcher::isPaused() const

bool QFutureWatcher::isRunning() const

bool QFutureWatcher::isStarted() const

void QFutureWatcher::pause()

void QFutureWatcher::paused()

See also setPaused().

int QFutureWatcher::progressMaximum() const

int QFutureWatcher::progressMinimum() const

void QFutureWatcher::progressRangeChanged(int minimum, int maximum)

QString QFutureWatcher::progressText() const

void QFutureWatcher::progressTextChanged(const QString &progressText)

int QFutureWatcher::progressValue() const

void QFutureWatcher::progressValueChanged(int progressValue)

T QFutureWatcher::result() const

T QFutureWatcher::resultAt(int index) const

void QFutureWatcher::resultReadyAt(int resultIndex)

void QFutureWatcher::resultsReadyAt(int beginIndex, int endIndex)

void QFutureWatcher::resume()

void QFutureWatcher::resumed()

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

See also future().

void QFutureWatcher::setPaused(bool paused)

See also paused().

void QFutureWatcher::setPendingResultsLimit(int limit)

void QFutureWatcher::togglePaused()

void QFutureWatcher::waitForFinished()