Base class for a task that is started in an extra thread. More...
#include <mlBackgroundTask.h>
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. | |
| virtual | ~BackgroundTask () |
Methods to reimplement | |
| virtual void | run ()=0 |
| run method that needs to be reimplemented (called from worker thread) | |
Setup of task properties | |
| bool | isSynchronous () const |
| check if task is synchronous (which means it is NOT run in an extra thread) | |
| void | setSynchronous (bool flag) |
| set if task is handled synchronous (call this ONLY on setup of the task, not while it is already running) | |
| void | setSynchronousCancelField (NotifyField *field) |
| set a cancel field that is used in synchronous mode to check if cancel was pressed | |
Status handling / canceling | |
| Status | status () const |
| returns the status of the task (threadsafe) | |
| void | cancel () |
| cancel the task (sets status to canceled) (threadsafe, typically called from GUI) | |
| bool | isCanceled () const |
| check if the task was canceled (threadsafe, typically called from GUI) | |
| bool | shouldStop () |
| returns if the task should stop its work because it has been canceled. | |
| void | resume () |
| resume task after it was suspended (will only do something if current status() is Suspended) (threadsafe) | |
| void | suspend () |
| suspend task, so that it will wait until resume() is called (threadsafe). | |
| std::string | statusString () const |
| get current status string (threadsafe) | |
| virtual void | setStatusString (const std::string &status) |
| update the status string while processing (from run() method only) | |
| float | progress () const |
| get current progress (threadsafe) | |
| virtual void | setProgress (float progress) |
| update the progress while processing (from run() method only) | |
Owner related methods | |
| void | setOwnerWasDeleted () |
| tell the task that it's owner was deleted (only call from GUI thread!), this also cancels the task | |
| bool | hasOwner () const |
| check if owner was deleted (only call from GUI thread!) | |
| void * | owner () const |
| get the owner of the task (only call from GUI thread!) | |
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() | |
| void | executeNextMessage () |
| execute the next message (does not block if no message is available) NOTE: only call from within run() | |
| 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. | |
Logging | |
| void | logMessage (const std::string &message) |
| log a message (only logged if verbose logging is turned on) (threadsafe) | |
| bool | isVerbose () const |
| check if task uses verbose logging | |
| void | setVerbose (bool flag) |
| set if task uses verbose logging (call this ONLY on setup of the task, not while it is already running) | |
Misc | |
| double | runningTime () const |
| returns the running time (in seconds) of the task (after it has finished or canceled, only call from GUI thread) | |
| 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) | |
| void | getStatusInformation (BackgroundTaskStatusInformation &info) |
| get the complete status information (threadsafe) | |
| MLuint32 | taskId () const |
| get the unique id of this task, the id of a task never changes | |
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 | |
| void | addObserver (Observer *observer) |
| add the given observer (threadsafe) (ownership stays with caller) | |
| void | removeObserver (Observer *observer) |
| remove the given observer (threadsafe) (ownership stays with caller) | |
Protected Member Functions | |
| void | sendStatusChangedToObservers () |
| send the status change to all observers | |
| void | sendStatusStringChangedToObservers () |
| send the status string change to all observers | |
| void | sendLogMessageToObservers (const std::string &msg) |
| send the status string change to all observers | |
| void | addIdleTime (double timeInSecs) |
add given timeInSecs as spent idle time | |
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 38 of file mlBackgroundTask.h.
Member Enumeration Documentation
Defines current status of the task.
Definition at line 44 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 | ) | [inline, protected] |
add given timeInSecs as spent idle time
Definition at line 247 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)
| void ml::BackgroundTask::executeNextMessage | ( | ) |
execute the next message (does not block if no message is available) 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 189 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 74 of file mlBackgroundTask.h.
| bool ml::BackgroundTask::isVerbose | ( | ) | const [inline] |
check if task uses verbose logging
Definition at line 173 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::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 186 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 76 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 81 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 175 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)
Referenced by ml::ProcessAllPagesBackgroundTask::setInitialStatusMessage().
| 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 195 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 250 of file mlBackgroundTask.h.
friend struct BackgroundTaskManagerWorkerFunc [friend] |
Definition at line 251 of file mlBackgroundTask.h.
The documentation for this class was generated from the following file:
- MeVis/Foundation/Sources/MLBackgroundTasks/mlBackgroundTask.h
