KAsync::Future

KAsync::Future< T > Class Template Reference

#include <future.h>

Inherits FutureGeneric< T >.

Public Member Functions

 Future ()
 
 Future (const Future< T > &other)
 
int errorCode () const
 
QString errorMessage () const
 
bool isFinished () const
 
T & operator* ()
 
const T & operator* () const
 
T * operator-> ()
 
const T * operator-> () const
 
void setError (int code=1, const QString &message=QString())
 
void setFinished ()
 
void setProgress (int processed, int total)
 
void setProgress (qreal progress)
 
void setResult (const T &value)
 
void setValue (const T &value)
 
value () const
 
void waitForFinished () const
 

Detailed Description

template<typename T>
class KAsync::Future< T >

Future is a promise that is used by Job to deliver result of an asynchronous execution.

The Future is passed internally to each executed task, and the task can use it to report its progress, result and notify when it is finished.

Users use Future they receive from calling Job::exec() to get access to the overall result of the execution. FutureWatcher<T> can be used to wait for the Future to finish in non-blocking manner.

See also
Future<void>

Definition at line 196 of file future.h.

Constructor & Destructor Documentation

template<typename T>
KAsync::Future< T >::Future ( )
explicit

Constructor.

Definition at line 208 of file future.h.

template<typename T>
KAsync::Future< T >::Future ( const Future< T > &  other)

Copy constructor.

Definition at line 215 of file future.h.

Member Function Documentation

template<typename T>
int KAsync::Future< T >::errorCode ( ) const

Returns error code set via setError() or 0 if no error has occurred.

See also
setError(), errorMessage()
template<typename T>
QString KAsync::Future< T >::errorMessage ( ) const

Returns error message set via setError() or empty string if no error occurred.

See also
setError(), errorCode()
template<typename T>
bool KAsync::Future< T >::isFinished ( ) const

Query whether the Future has already finished.

See also
setFinished()
template<typename T>
void KAsync::Future< T >::setError ( int  code = 1,
const QString message = QString() 
)

Used by tasks to report an error that happened during execution.

If an error handler was provided to the task, it will be executed with the given arguments. Otherwise the error will be propagated to next task that has an error handler, or all the way up to user.

This method also internally calls setFinished()

Warning
This method must only be called by the tasks inside Job, never by outside users.
Parameters
codeOptional error code
messageOptional error message
See also
errorCode(), errorMessage()
template<typename T>
void KAsync::Future< T >::setFinished ( )

Marks the future as finished.

This will cause all FutureWatcher<T> objects watching this particular instance to emit FutureWatcher::futureReady() signal, and will cause all callers currently blocked in Future::waitForFinished() method of this particular instance to resume.

Warning
This method must only be called by the tasks inside Job, never by outside users.
See also
isFinished()
template<typename T>
void KAsync::Future< T >::setProgress ( int  processed,
int  total 
)

Sets progress of the task.

All FutureWatcher instances watching this particular future will then emit FutureWatcher::futureProgress() signal.

Parameters
processedAlready processed amount
totalTotal amount to process
template<typename T>
void KAsync::Future< T >::setProgress ( qreal  progress)

Sets progress of the task.

Parameters
progressProgress
template<typename T>
void KAsync::Future< T >::setValue ( const T &  value)

Set the result of the Future.

This method is called by the task upon calculating the result. After setting the value, the caller must also call setFinished() to notify users that the result is available.

Warning
This method must only be called by the tasks inside Job, never by outside users.
Parameters
valueThe result value

Definition at line 230 of file future.h.

template<typename T>
T KAsync::Future< T >::value ( ) const

Retrieve the result of the Future.

Calling this method when the future has not yet finished (i.e. isFinished() returns false) returns undefined result.

Definition at line 240 of file future.h.

template<typename T>
void KAsync::Future< T >::waitForFinished ( ) const

Will block until the Future has finished.

Note
Internally this method is using a nested QEventLoop, which can in some situation cause problems and deadlocks. It is recommended to use FutureWatcher.
See also
isFinished()

The documentation for this class was generated from the following file:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 13 2020 23:06:28 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.