Hemera::Operation Class Referenceabstract

A pending asynchronous operation. More...

Inherits QObject.

Inherited by Hemera::BoolOperation, Hemera::ByteArrayOperation, Hemera::CompositeOperation, Hemera::DBusObjectPathOperation, Hemera::DBusVoidOperation, Hemera::FailureOperation, Hemera::JsonOperation, Hemera::ObjectOperation, Hemera::StringListOperation, Hemera::StringOperation, Hemera::SuccessOperation, Hemera::UIntOperation, Hemera::VariantMapOperation, and Hemera::VariantOperation.

Signals

void finished (Hemera::Operation *operation)
 Notifies the completion of the asynchronous operation. More...
 

Public Member Functions

virtual ~Operation ()
 
bool isFinished () const
 
bool isValid () const
 
bool isError () const
 
QString errorName () const
 
QString errorMessage () const
 
bool synchronize (int timeout=-1)
 Synchronously awaits for the Operation's completion. More...
 

Protected Slots

virtual void startImpl ()=0
 
void setFinished ()
 
void setFinishedWithError (const QString &name, const QString &message)
 
void setFinishedWithError (const QDBusError &error)
 

Detailed Description

A pending asynchronous operation.

This class tracks a pending asynchronous operation. Hemera is designed to work on fully asynchronous models or over IPC calls; Operation allows to track asynchronous operations (such as a pending IPC call or a delayed initialization) through a nice job-based model.

Operations, once created, are started immediately. Though, it is safe to perform connections and setups right after an Operation's creationm as the starting procedure will be triggered as soon as the event loop returns.

Various subclasses specialize in specific return types. When finished is emitted, the Operation can be evaluated and the result can be extracted. When the operation finishes, it is automatically garbage collected, and after the result recollection the object should be considered dead. Likewise, Operation must not be deleted explicitly by the user.

Constructor & Destructor Documentation

Hemera::Operation::~Operation ( )
virtual

Default destructor

Member Function Documentation

bool Hemera::Operation::isFinished ( ) const

Returns whether this operation has finished.

Returns
true if the Operation has finished, false if not.
bool Hemera::Operation::isValid ( ) const
Returns
Whether this operation is valid or not.
bool Hemera::Operation::isError ( ) const
Returns
Whether this operation has finished with an error or not.
Note
This function returns a meaningful result only when isFinished is true.
QString Hemera::Operation::errorName ( ) const
Returns
The error name of the occurred error, if any.
Note
If isError returns false, this function will return an empty string.
This function returns a meaningful result only when isFinished is true.
QString Hemera::Operation::errorMessage ( ) const
Returns
The error message of the occurred error, if any.
Note
If isError returns false, this function will return an empty string. Given that it is not compulsory to provide an error message for Operations, the returned string might as well be empty even in case the Operation failed.
This function returns a meaningful result only when isFinished is true.
bool Hemera::Operation::synchronize ( int  timeout = -1)

Synchronously awaits for the Operation's completion.

This method allows to process an Operation synchronously, awaiting for its completion and returning when the Operation is finished. It returns whether the operation finished successfully or not, whereas further information can be retrieved from the Operation object once this method returns.

It is possible to specify a timeout after which synchronize will return regardless of the Operation's completion.

timeout Timeout, in seconds, after which the synchronization will fail. A negative value implies the synchronization will never time out.

Returns
Whether the operation succeeded or not.
Note
If the operation has already finished, this method returns immediately. It returns the result of the operation nonetheless.
If synchronize times out, the Operation won't fail or will be stopped. If you set a timeout and synchronize returns false, you should be checking isFinished to make sure the Operation has failed or timed out synchronizing.
As much as synchronize is used extensively in bindings and is safe to use, it is not part of the advised paradigm of development in Hemera Qt5, which strives to be as asynchronous as possible. If you are using Qt5 SDK directly, connecting to finished is usually the advised choice.
void Hemera::Operation::finished ( Hemera::Operation operation)
signal

Notifies the completion of the asynchronous operation.

Emitted when the operation has finished. Connect to this signal to inspect the Operation result upon its completion.

Parameters
operationA pointer to the finished operation.
virtual void Hemera::Operation::startImpl ( )
protectedpure virtualslot

Implements the operation main logic

When implementing an Operation, this method should hold your main logic. It is called by Operation when needed, and the developer should just reimplement it without invoking it.

Once the Operation is completed, either setFinished or setFinishedWithError must be called.

void Hemera::Operation::setFinished ( )
protectedslot

Completes the processing of the Operation

Once setFinished is called, the Operation will be declared successfully completed.

Note
After calling this function, the object will be garbage collected, and no further processing must be done.
void Hemera::Operation::setFinishedWithError ( const QString &  name,
const QString &  message 
)
protectedslot

Completes the processing of the Operation with a failure

Once setFinishedWithError is called, the Operation will be declared failed.

Note
After calling this function, the object will be garbage collected, and no further processing must be done.
void Hemera::Operation::setFinishedWithError ( const QDBusError &  error)
protectedslot

Convenience overload of setFinishedWithError

See also
setFinishedWithError