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

#include <qfuture.h>

Inheritance diagram for QFutureWatcher< T >:

Public Slots
void	cancel ()
	Cancels the asynchronous computation represented by the future(). More...

void	pause ()
	Pauses the asynchronous computation represented by the future(). More...

void	resume ()
	Resumes the asynchronous computation represented by the future(). More...

void	setPaused (bool paused)
	If paused is true, this function pauses the asynchronous computation represented by the future(). More...

void	togglePaused ()
	Toggles the paused state of the asynchronous computation. More...

Public Slots inherited from QFutureWatcherBase
void	cancel ()

void	pause ()

void	resume ()

void	setPaused (bool paused)

void	togglePaused ()

Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...

Signals
void	canceled ()
	This signal is emitted if the watched future is canceled. More...

void	finished ()
	This signal is emitted when the watched future finishes. More...

void	paused ()
	This signal is emitted when the watched future is paused. More...

void	progressRangeChanged (int minimum, int maximum)
	The progress range for the watched future has changed to minimum and maximum. More...

void	progressTextChanged (const QString &progressText)
	This signal is emitted when the watched future reports textual progress information, progressText. More...

void	progressValueChanged (int progressValue)
	This signal is emitted when the watched future reports progress, progressValue gives the current progress. More...

void	resultReadyAt (int resultIndex)
	This signal is emitted when the watched future reports a ready result at index. More...

void	resultsReadyAt (int beginIndex, int endIndex)
	This signal is emitted when the watched future reports ready results. More...

void	resumed ()
	This signal is emitted when the watched future is resumed. More...

void	started ()
	This signal is emitted when this QFutureWatcher starts watching the future set with setFuture(). More...

Signals inherited from QFutureWatcherBase
void	canceled ()

void	finished ()

void	paused ()

void	progressRangeChanged (int minimum, int maximum)

void	progressTextChanged (const QString &progressText)

void	progressValueChanged (int progressValue)

void	resultReadyAt (int resultIndex)

void	resultsReadyAt (int beginIndex, int endIndex)

void	resumed ()

void	started ()

Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
QFuture< T >	future () const
	Returns the watched future. More...

bool	isCanceled () const
	Returns true if the asynchronous computation has been canceled with the cancel() function; otherwise returns false. More...

bool	isFinished () const
	Returns true if the asynchronous computation represented by the future() has finished; otherwise returns false. More...

bool	isPaused () const
	Returns true if the asynchronous computation has been paused with the pause() function; otherwise returns false. More...

bool	isRunning () const
	Returns true if the asynchronous computation represented by the future() is currently running; otherwise returns false. More...

bool	isStarted () const
	Returns true if the asynchronous computation represented by the future() has been started; otherwise returns false. More...

int	progressMaximum () const
	Returns the maximum progressValue(). More...

int	progressMinimum () const
	Returns the minimum progressValue(). More...

QString	progressText () const
	Returns the (optional) textual representation of the progress as reported by the asynchronous computation. More...

int	progressValue () const
	Returns the current progress value, which is between the progressMinimum() and progressMaximum(). More...

	QFutureWatcher (QObject *_parent=0)
	Constructs a new QFutureWatcher with the given parent. More...

T	result () const
	Returns the first result in the future(). More...

T	resultAt (int index) const
	Returns the result at index in the future(). More...

void	setFuture (const QFuture< T > &future)
	Starts watching the given future. More...

void	setPendingResultsLimit (int limit)
	The setPendingResultsLimit() provides throttling control. More...

void	waitForFinished ()
	Waits for the asynchronous computation to finish (including cancel()ed computations). More...

	~QFutureWatcher ()
	Destroys the QFutureWatcher. More...

Public Functions inherited from QFutureWatcherBase
bool	event (QEvent *event)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...

bool	isCanceled () const

bool	isFinished () const

bool	isPaused () const

bool	isRunning () const

bool	isStarted () const

int	progressMaximum () const

int	progressMinimum () const

QString	progressText () const

int	progressValue () const

	QFutureWatcherBase (QObject *parent=0)

void	setPendingResultsLimit (int limit)

void	waitForFinished ()

Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...

const QObjectList &	children () const
	Returns a list of child objects. More...

bool	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=0, const QObject receiver=0, const char *member=0)

bool	disconnect (const QObject receiver, const char member=0)

void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...

void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...

QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...

virtual bool	eventFilter (QObject , QEvent )
	Filters events if this object has been installed as an event filter for the watched object. More...

template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...

template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...

template<typename T >
QList< T >	findChildren (const QRegExp &re) const

bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...

void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...

bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...

void	killTimer (int id)
	Kills the timer with timer identifier, id. More...

virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...

void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...

QString	objectName () const

QObject *	parent () const
	Returns a pointer to the parent object. More...

QVariant	property (const char *name) const
	Returns the value of the object's name property. More...

Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...

void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...

void	setObjectName (const QString &name)

void	setParent (QObject *)
	Makes the object a child of parent. More...

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...

void	setUserData (uint id, QObjectUserData *data)

bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...

int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...

QThread *	thread () const
	Returns the thread in which the object lives. More...

QObjectUserData *	userData (uint id) const

virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Private Functions
const QFutureInterfaceBase &	futureInterface () const

QFutureInterfaceBase &	futureInterface ()

Properties
QFuture< T >	m_future

Additional Inherited Members
Static Public Functions inherited from QObject
static bool	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...

static bool	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	Disconnects signal in object sender from method in object receiver. More...

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static uint	registerUserData ()

static QString	tr (const char sourceText, const char comment=0, int n=-1)

static QString	trUtf8 (const char sourceText, const char comment=0, int n=-1)

Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...

Protected Functions inherited from QFutureWatcherBase
void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...

void	connectOutputInterface ()

void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...

void	disconnectOutputInterface (bool pendingAssignment=false)

Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...

virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...

	QObject (QObjectPrivate &dd, QObject *parent=0)

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...

QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject

Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()

T *	qobject_cast (QObject *object)

	QObjectList

void *	qt_find_obj_child (QObject parent, const char type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

template<typename T>
class QFutureWatcher< T >

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

Note: This class or function is reentrant.

Since: 4.4

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, {Concurrent Programming}{Qt Concurrent}

Definition at line 59 of file qfuture.h.

Constructors and Destructors

◆ QFutureWatcher()

template<typename T>

QFutureWatcher< T >::QFutureWatcher ( QObject * _parent = 0 )

inline

Constructs a new QFutureWatcher with the given parent.

Definition at line 126 of file qfuturewatcher.h.

127 : QFutureWatcherBase(_parent)

128 { }

QFutureWatcherBase::QFutureWatcherBase

QFutureWatcherBase(QObject *parent=0)

Definition: qfuturewatcher.cpp:109

◆ ~QFutureWatcher()

template<typename T>

QFutureWatcher< T >::~QFutureWatcher ( )

inline

Destroys the QFutureWatcher.

Definition at line 129 of file qfuturewatcher.h.

130 { disconnectOutputInterface(); }

QFutureWatcherBase::disconnectOutputInterface

void disconnectOutputInterface(bool pendingAssignment=false)

Definition: qfuturewatcher.cpp:453

Functions

◆ cancel

template<typename T>

void QFutureWatcher< T >::cancel ( )

slot

Cancels the asynchronous computation represented by the future().

Note that the cancelation is asynchronous. Use waitForFinished() after calling cancel() when you need synchronous cancelation.

Currently available results may still be accessed on a canceled QFuture, but new results will not become available after calling this function. Also, this QFutureWatcher will not deliver progress and result ready signals once canceled. This includes the progressValueChanged(), progressRangeChanged(), progressTextChanged(), resultReadyAt(), and resultsReadyAt() signals.

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

◆ canceled

template<typename T>

void QFutureWatcher< T >::canceled ( )

signal

This signal is emitted if the watched future is canceled.

◆ finished

template<typename T>

void QFutureWatcher< T >::finished ( )

signal

This signal is emitted when the watched future finishes.

◆ future()

template<typename T>

QFuture< T > QFutureWatcher< T >::future ( ) const

inline

Returns the watched future.

Definition at line 133 of file qfuturewatcher.h.

134 { return m_future; }

QFutureWatcher::m_future

QFuture< T > m_future

Definition: qfuturewatcher.h:176

◆ futureInterface() [1/2]

template<typename T>

const QFutureInterfaceBase& QFutureWatcher< T >::futureInterface ( ) const

inlineprivatevirtual

Implements QFutureWatcherBase.

Definition at line 177 of file qfuturewatcher.h.

177 { return m_future.d; }

QFutureWatcher::m_future

QFuture< T > m_future

Definition: qfuturewatcher.h:176

◆ futureInterface() [2/2]

template<typename T>

QFutureInterfaceBase& QFutureWatcher< T >::futureInterface ( )

inlineprivatevirtual

Implements QFutureWatcherBase.

Definition at line 178 of file qfuturewatcher.h.

178 { return m_future.d; }

QFutureWatcher::m_future

QFuture< T > m_future

Definition: qfuturewatcher.h:176

◆ isCanceled()

template<typename T>

bool QFutureWatcher< T >::isCanceled ( ) const

Returns true if the asynchronous computation has been canceled with the cancel() function; otherwise returns false.

Be aware that the computation may still be running even though this function returns true. See cancel() for more details.

◆ isFinished()

template<typename T>

bool QFutureWatcher< T >::isFinished ( ) const

Returns true if the asynchronous computation represented by the future() has finished; otherwise returns false.

◆ isPaused()

template<typename T>

bool QFutureWatcher< T >::isPaused ( ) const

Returns true if the asynchronous computation has been paused with the pause() function; otherwise returns false.

Be aware that the computation may still be running even though this function returns true. See setPaused() for more details.

See also: setPaused(), togglePaused()

◆ isRunning()

template<typename T>

bool QFutureWatcher< T >::isRunning ( ) const

Returns true if the asynchronous computation represented by the future() is currently running; otherwise returns false.

◆ isStarted()

template<typename T>

bool QFutureWatcher< T >::isStarted ( ) const

Returns true if the asynchronous computation represented by the future() has been started; otherwise returns false.

◆ pause

template<typename T>

void QFutureWatcher< T >::pause ( )

slot

Pauses the asynchronous computation represented by the future().

This is a convenience method that simply calls setPaused(true).

See also: resume()

◆ paused

template<typename T>

void QFutureWatcher< T >::paused ( )

signal

This signal is emitted when the watched future is paused.

◆ progressMaximum()

template<typename T>

int QFutureWatcher< T >::progressMaximum ( ) const

Returns the maximum progressValue().

See also: progressValue(), progressMinimum()

◆ progressMinimum()

template<typename T>

int QFutureWatcher< T >::progressMinimum ( ) const

Returns the minimum progressValue().

See also: progressValue(), progressMaximum()

◆ progressRangeChanged

template<typename T>

void QFutureWatcher< T >::progressRangeChanged	(	int	minimum,
		int	maximum
	)

signal

The progress range for the watched future has changed to minimum and maximum.

◆ progressText()

template<typename T>

QString QFutureWatcher< T >::progressText ( ) const

Returns the (optional) textual representation of the progress as reported by the asynchronous computation.

Be aware that not all computations provide a textual representation of the progress, and as such, this function may return an empty string.

Referenced by QFutureInterfaceBasePrivate::internal_updateProgress().

◆ progressTextChanged

template<typename T>

void QFutureWatcher< T >::progressTextChanged ( const QString & progressText )

signal

This signal is emitted when the watched future reports textual progress information, progressText.

◆ progressValue()

template<typename T>

int QFutureWatcher< T >::progressValue ( ) const

Returns the current progress value, which is between the progressMinimum() and progressMaximum().

See also: progressMinimum(), progressMaximum()

◆ progressValueChanged

template<typename T>

void QFutureWatcher< T >::progressValueChanged ( int progressValue )

signal

This signal is emitted when the watched future reports progress, progressValue gives the current progress.

In order to avoid overloading the GUI event loop, QFutureWatcher limits the progress signal emission rate. This means that listeners connected to this slot might not get all progress reports the future makes. The last progress update (where progressValue equals the maximum value) will always be delivered.

◆ result()

template<typename T>

const T & QFutureWatcher< T >::result ( ) const

inline

Returns the first result in the future().

If the result is not immediately available, this function will block and wait for the result to become available. This is a convenience method for calling resultAt(0).

See also: resultAt()

Definition at line 136 of file qfuturewatcher.h.

136 { return m_future.result(); }

QFutureWatcher::m_future

QFuture< T > m_future

Definition: qfuturewatcher.h:176

◆ resultAt()

template<typename T>

const T & QFutureWatcher< T >::resultAt ( int index ) const

inline

Returns the result at index in the future().

If the result is not immediately available, this function will block and wait for the result to become available.

See also: result()

Definition at line 137 of file qfuturewatcher.h.

137 { return m_future.resultAt(index); }

QFutureWatcher::m_future

QFuture< T > m_future

Definition: qfuturewatcher.h:176

index

quint16 index

Definition: qfontsubset.cpp:116

◆ resultReadyAt

template<typename T>

void QFutureWatcher< T >::resultReadyAt ( int index )

signal

This signal is emitted when the watched future reports a ready result at index.

If the future reports multiple results, the index will indicate which one it is. Results can be reported out-of-order. To get the result, call future().result(index);

◆ resultsReadyAt

template<typename T>

void QFutureWatcher< T >::resultsReadyAt	(	int	beginIndex,
		int	endIndex
	)

signal

This signal is emitted when the watched future reports ready results.

The results are indexed from beginIndex to endIndex.

◆ resume

template<typename T>

void QFutureWatcher< T >::resume ( )

slot

Resumes the asynchronous computation represented by the future().

This is a convenience method that simply calls setPaused(false).

See also: pause()

◆ resumed

template<typename T>

void QFutureWatcher< T >::resumed ( )

signal

This signal is emitted when the watched future is resumed.

◆ setFuture()

template<typename T >

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

Starts watching the given future.

One of the signals might be emitted for the current state of the future. For example, if the future is already stopped, the finished signal will be emitted.

To avoid a race condition, it is important to call this function after doing the connections.

Definition at line 182 of file qfuturewatcher.h.

 {
     if (_future == m_future)
         return;
 
     disconnectOutputInterface(true);
     m_future = _future;
     connectOutputInterface();
 }

◆ setPaused

template<typename T>

void QFutureWatcher< T >::setPaused ( bool paused )

slot

If paused is true, this function pauses the asynchronous computation represented by the future().

If the computation is already paused, this function does nothing. This QFutureWatcher will stop delivering progress and result ready signals while the future is paused. Signal delivery will continue once the computation is resumed.

If paused is false, this function resumes the asynchronous computation. If the computation was not previously paused, this function does nothing.

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

See also: pause(), resume(), togglePaused()

◆ setPendingResultsLimit()

template<typename T>

void QFutureWatcher< T >::setPendingResultsLimit ( int limit )

The setPendingResultsLimit() provides throttling control.

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.

◆ started

template<typename T>

void QFutureWatcher< T >::started ( )

signal

This signal is emitted when this QFutureWatcher starts watching the future set with setFuture().

◆ togglePaused

template<typename T>

void QFutureWatcher< T >::togglePaused ( )

slot

Toggles the paused state of the asynchronous computation.

In other words, if the computation is currently paused, calling this function resumes it; if the computation is running, it becomes paused. This is a convenience method for calling setPaused(!isPaused()).

See also: setPaused(), pause(), resume()

◆ waitForFinished()

template<typename T>

void QFutureWatcher< T >::waitForFinished ( )

Waits for the asynchronous computation to finish (including cancel()ed computations).

Properties

◆ m_future

template<typename T>

QFuture<T> QFutureWatcher< T >::m_future

private

Definition at line 176 of file qfuturewatcher.h.

The documentation for this class was generated from the following files:

/src/corelib/concurrent/qfuture.h
/src/corelib/concurrent/qfuturewatcher.h
/src/corelib/concurrent/qfuturewatcher.cpp

Public Slots

Signals

Public Functions

Private Functions

Properties

Additional Inherited Members

Detailed Description

template<typename T> class QFutureWatcher< T >

Constructors and Destructors

◆ QFutureWatcher()

◆ ~QFutureWatcher()

Functions

◆ cancel

◆ canceled

◆ finished

◆ future()

◆ futureInterface() [1/2]

◆ futureInterface() [2/2]

◆ isCanceled()

◆ isFinished()

◆ isPaused()

◆ isRunning()

◆ isStarted()

◆ pause

◆ paused

◆ progressMaximum()

◆ progressMinimum()

◆ progressRangeChanged

◆ progressText()

◆ progressTextChanged

◆ progressValue()

◆ progressValueChanged

◆ result()

◆ resultAt()

◆ resultReadyAt

◆ resultsReadyAt

◆ resume

◆ resumed

◆ setFuture()

◆ setPaused

◆ setPendingResultsLimit()

◆ started

◆ togglePaused

◆ waitForFinished()

Properties

◆ m_future

template<typename T>
class QFutureWatcher< T >