MeVisLabToolboxReference
ml::BackgroundTask Class Referenceabstract

Base class for a task that is started in an extra thread. More...

#include <mlBackgroundTask.h>

Inheritance diagram for ml::BackgroundTask:
ml::MessagingBackgroundTask ml::ImagingBackgroundTask ml::ModuleBackgroundTask ml::ProcessAllPagesBackgroundTask ml::RTObjectSaveBackgroundTask

Classes

class  Observer
 Abstract interface to observe the BackgroundTask. More...
 

Public Types

enum  Status {
  NotInTaskManager, Queued, Running, Finished,
  Canceled, Suspended
}
 Defines current status of the task. More...
 

Public Member Functions

 BackgroundTask (void *owner)
 Create a new task with given owner (the owner can be used to associate the task with a given class instance, e.g. More...
 
virtual ~BackgroundTask ()
 
Methods to reimplement
virtual void run ()=0
 run method that needs to be reimplemented (called from worker thread) More...
 
Setup of task properties
bool isSynchronous () const
 check if task is synchronous (which means it is NOT run in an extra thread) More...
 
void setSynchronous (bool flag)
 set if task is handled synchronous (call this ONLY on setup of the task, not while it is already running) More...
 
void setSynchronousCancelField (NotifyField *field)
 set a cancel field that is used in synchronous mode to check if cancel was pressed More...
 
Status handling / canceling
Status status () const
 returns the status of the task (threadsafe) More...
 
void cancel ()
 cancel the task (sets status to canceled) (threadsafe, typically called from GUI) More...
 
bool isCanceled () const
 check if the task was canceled (threadsafe, typically called from GUI) More...
 
bool shouldStop ()
 returns if the task should stop its work because it has been canceled. More...
 
void resume ()
 resume task after it was suspended (will only do something if current status() is Suspended) (threadsafe) More...
 
void suspend ()
 suspend task, so that it will wait until resume() is called (threadsafe). More...
 
std::string statusString () const
 get current status string (threadsafe) More...
 
virtual void setStatusString (const std::string &status)
 update the status string while processing (from run() method only) More...
 
float progress () const
 get current progress (threadsafe) More...
 
virtual void setProgress (float progress)
 update the progress while processing (from run() method only) More...
 
Owner related methods
void setOwnerWasDeleted ()
 tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task More...
 
bool hasOwner () const
 check if owner was deleted (only call from GUI thread!) More...
 
void * owner () const
 get the owner of the task (only call from GUI thread!) More...
 
Message handling
void waitAndExecuteNextMessage ()
 execute the next message (waits if no messages are available and processes the first message that is received) NOTE: only call from within run() More...
 
bool executeNextMessage ()
 execute the next message (does not block if no message is available) It returns true if there was a message to process. More...
 
void sendMessageToGUI (BackgroundTaskMessage *message)
 send the message to the GUI (ownership of message is passed to the method) and it sets the sender of the message to this BackgroundTask. More...
 
Logging
void logMessage (const std::string &message)
 log a message (only logged if verbose logging is turned on) (threadsafe) More...
 
bool isVerbose () const
 check if task uses verbose logging More...
 
void setVerbose (bool flag)
 set if task uses verbose logging (call this ONLY on setup of the task, not while it is already running) More...
 
Misc
double runningTime () const
 returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread) More...
 
double idleTime () const
 returns the idle time (in seconds) of the task (which it e.g. waited for getTile to complete), (after it has finished or canceled, only call from GUI thread) More...
 
void getStatusInformation (BackgroundTaskStatusInformation &info)
 get the complete status information (threadsafe) More...
 
MLuint32 taskId () const
 get the unique id of this task, the id of a task never changes More...
 
Observing a task
void setTaskFinishedCB (BackgroundTaskFinishedCB *callback, void *userdata)
 set this directly after initialization of the task (from the GUI thread) this callback will be called whenever a task is either finished or canceled More...
 
void addObserver (Observer *observer)
 add the given observer (threadsafe) (ownership stays with caller) More...
 
void removeObserver (Observer *observer)
 remove the given observer (threadsafe) (ownership stays with caller) More...
 

Protected Member Functions

void sendStatusChangedToObservers ()
 send the status change to all observers More...
 
void sendStatusStringChangedToObservers ()
 send the status string change to all observers More...
 
void sendLogMessageToObservers (const std::string &msg)
 send the status string change to all observers More...
 
void addIdleTime (double timeInSecs)
 add given timeInSecs as spent idle time More...
 

Friends

class BackgroundTaskManager
 
struct BackgroundTaskManagerWorkerFunc
 

Detailed Description

Base class for a task that is started in an extra thread.

Reimplement the virtual run() method to implement processing that is done in the task. A task can be scheduled using BackgroundTaskManager::self()->runTask(task).

Definition at line 40 of file mlBackgroundTask.h.

Member Enumeration Documentation

Defines current status of the task.

Enumerator
NotInTaskManager 
Queued 
Running 
Finished 
Canceled 
Suspended 

Definition at line 46 of file mlBackgroundTask.h.

Constructor & Destructor Documentation

ml::BackgroundTask::BackgroundTask ( void *  owner)

Create a new task with given owner (the owner can be used to associate the task with a given class instance, e.g.

a ml::Module. The task never accesses the owner itself).

virtual ml::BackgroundTask::~BackgroundTask ( )
virtual

Member Function Documentation

void ml::BackgroundTask::addIdleTime ( double  timeInSecs)
inlineprotected

add given timeInSecs as spent idle time

Definition at line 250 of file mlBackgroundTask.h.

void ml::BackgroundTask::addObserver ( Observer observer)

add the given observer (threadsafe) (ownership stays with caller)

void ml::BackgroundTask::cancel ( )

cancel the task (sets status to canceled) (threadsafe, typically called from GUI)

bool ml::BackgroundTask::executeNextMessage ( )

execute the next message (does not block if no message is available) It returns true if there was a message to process.

NOTE: only call from within run()

void ml::BackgroundTask::getStatusInformation ( BackgroundTaskStatusInformation info)

get the complete status information (threadsafe)

bool ml::BackgroundTask::hasOwner ( ) const

check if owner was deleted (only call from GUI thread!)

double ml::BackgroundTask::idleTime ( ) const
inline

returns the idle time (in seconds) of the task (which it e.g. waited for getTile to complete), (after it has finished or canceled, only call from GUI thread)

Definition at line 192 of file mlBackgroundTask.h.

bool ml::BackgroundTask::isCanceled ( ) const

check if the task was canceled (threadsafe, typically called from GUI)

bool ml::BackgroundTask::isSynchronous ( ) const
inline

check if task is synchronous (which means it is NOT run in an extra thread)

Definition at line 76 of file mlBackgroundTask.h.

Referenced by ml::RTObjectSaveBackgroundTask::setDicomTree().

bool ml::BackgroundTask::isVerbose ( ) const
inline

check if task uses verbose logging

Definition at line 176 of file mlBackgroundTask.h.

void ml::BackgroundTask::logMessage ( const std::string &  message)

log a message (only logged if verbose logging is turned on) (threadsafe)

void* ml::BackgroundTask::owner ( ) const

get the owner of the task (only call from GUI thread!)

float ml::BackgroundTask::progress ( ) const

get current progress (threadsafe)

void ml::BackgroundTask::removeObserver ( Observer observer)

remove the given observer (threadsafe) (ownership stays with caller)

void ml::BackgroundTask::resume ( )

resume task after it was suspended (will only do something if current status() is Suspended) (threadsafe)

virtual void ml::BackgroundTask::run ( )
pure virtual

run method that needs to be reimplemented (called from worker thread)

Implemented in ml::RTObjectSaveBackgroundTask, and ml::ProcessAllPagesBackgroundTask.

double ml::BackgroundTask::runningTime ( ) const
inline

returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread)

Definition at line 189 of file mlBackgroundTask.h.

void ml::BackgroundTask::sendLogMessageToObservers ( const std::string &  msg)
protected

send the status string change to all observers

void ml::BackgroundTask::sendMessageToGUI ( BackgroundTaskMessage message)

send the message to the GUI (ownership of message is passed to the method) and it sets the sender of the message to this BackgroundTask.

NOTE: only call from within run()

Referenced by ml::MessagingBackgroundTask::callMethodOnGUI().

void ml::BackgroundTask::sendStatusChangedToObservers ( )
protected

send the status change to all observers

void ml::BackgroundTask::sendStatusStringChangedToObservers ( )
protected

send the status string change to all observers

void ml::BackgroundTask::setOwnerWasDeleted ( )

tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task

virtual void ml::BackgroundTask::setProgress ( float  progress)
virtual

update the progress while processing (from run() method only)

Reimplemented in ml::ModuleBackgroundTask.

virtual void ml::BackgroundTask::setStatusString ( const std::string &  status)
virtual

update the status string while processing (from run() method only)

Reimplemented in ml::ModuleBackgroundTask.

void ml::BackgroundTask::setSynchronous ( bool  flag)
inline

set if task is handled synchronous (call this ONLY on setup of the task, not while it is already running)

Definition at line 78 of file mlBackgroundTask.h.

void ml::BackgroundTask::setSynchronousCancelField ( NotifyField field)
inline

set a cancel field that is used in synchronous mode to check if cancel was pressed

Definition at line 83 of file mlBackgroundTask.h.

void ml::BackgroundTask::setTaskFinishedCB ( BackgroundTaskFinishedCB callback,
void *  userdata 
)

set this directly after initialization of the task (from the GUI thread) this callback will be called whenever a task is either finished or canceled

void ml::BackgroundTask::setVerbose ( bool  flag)
inline

set if task uses verbose logging (call this ONLY on setup of the task, not while it is already running)

Definition at line 178 of file mlBackgroundTask.h.

bool ml::BackgroundTask::shouldStop ( )

returns if the task should stop its work because it has been canceled.

Note: This method should be called regularly from the implementation of run() to allow that a task stops/is suspended when the user presses/suspend cancel. If it returns true, the task should cleanup and return from run() asap. This method may only be called from the run() method and only from that thread, since it will block when the task is suspended.

Status ml::BackgroundTask::status ( ) const

returns the status of the task (threadsafe)

std::string ml::BackgroundTask::statusString ( ) const

get current status string (threadsafe)

void ml::BackgroundTask::suspend ( )

suspend task, so that it will wait until resume() is called (threadsafe).

To make this feature work, the task's run() implementation needs to call shouldStop() regularly.

MLuint32 ml::BackgroundTask::taskId ( ) const
inline

get the unique id of this task, the id of a task never changes

Definition at line 198 of file mlBackgroundTask.h.

void ml::BackgroundTask::waitAndExecuteNextMessage ( )

execute the next message (waits if no messages are available and processes the first message that is received) NOTE: only call from within run()

Friends And Related Function Documentation

friend class BackgroundTaskManager
friend

Definition at line 253 of file mlBackgroundTask.h.

friend struct BackgroundTaskManagerWorkerFunc
friend

Definition at line 254 of file mlBackgroundTask.h.


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