![]() |
RobWorkProject
24.12.4-
|
A task that facilitates the use of a hierarchic tree of tasks and subtasks. More...
#include <ThreadTask.hpp>
Public Types | |
enum | TaskState { INITIALIZATION , IN_QUEUE , EXECUTING , CHILDREN , IDLE , POSTWORK , DONE } |
The different execution states of a task. More... | |
typedef rw::core::Ptr< ThreadTask > | Ptr |
smart pointer type to this class | |
typedef enum rw::common::ThreadTask::TaskState | TaskState |
The different execution states of a task. | |
Public Member Functions | |
ThreadTask (ThreadTask::Ptr parent) | |
Create task that will inherit parents thread pool. More... | |
ThreadTask (rw::core::Ptr< ThreadPool > pool=NULL) | |
Create task that will use a specific thread pool. If no thread pool is given, the task will not use parallelization. More... | |
virtual | ~ThreadTask () |
Destruct this task. | |
bool | setThreadPool (rw::core::Ptr< ThreadPool > pool) |
Set which ThreadPool to use to do the actual execution of work. When execution is started the pool can not be changed anymore. More... | |
rw::core::Ptr< ThreadPool > | getThreadPool () |
Get the ThreadPool that is used by this task currently. More... | |
bool | execute () |
Start executing the work in this task and all subtasks already added, by using the assigned ThreadPool. More... | |
TaskState | wait (ThreadTask::TaskState previous) |
Wait until state of task changes (blocking). More... | |
void | waitUntilDone () |
Wait until state of task changes to DONE (blocking). | |
TaskState | getState () |
Get the current state of the task (non-blocking). More... | |
bool | addSubTask (ThreadTask::Ptr subtask) |
Add a child task to this task. More... | |
std::vector< ThreadTask::Ptr > | getSubTasks () |
Get the subtasks currently added to the ThreadTask. More... | |
void | setKeepAlive (bool enable) |
Choose if the thread should exit automatically when all work and children has finished (this is the default). More... | |
bool | keepAlive () |
Check is the task has keep alive option enabled. More... | |
void | registerFailure (const rw::core::Exception &e) |
Mark the task as a failure by registering an exception. More... | |
std::list< rw::core::Exception > | getExceptions () const |
Get a list of exceptions registered in task and subtasks. More... | |
Functions that can be implemented by subclasses. | |
It is optional to implement these functions, but normally at least one should be implemented. | |
virtual void | run () |
Function is the first function executed to do the actual work (new subtasks can be added in this function). | |
virtual void | subTaskDone (ThreadTask *subtask) |
Function is executed each time a subtask has finished (new subtasks can be added in this function). If registerFailure is used to register failures in subtasks, this function should handle or propagate the failures. The default implementation of this function is as follows: More... | |
virtual void | idle () |
Function is executed when the task becomes idle (new subtasks can be added in this function). | |
virtual void | done () |
Function is executed when work is finished (at this point new subtasks can NOT be added). | |
A task that facilitates the use of a hierarchic tree of tasks and subtasks.
Often parallel processing can be done at multiple levels. Typically it is not known beforehand if some task can be split into multiple smaller subtasks or not. The ThreadTask keeps track of the state of all its subtasks - only when all subtasks have been processed, the parent task will be able to finish. Instead of finishing, it can also choose to add new subtasks that depends on the result of the previously run subtasks.
The ThreadTask can utilize a ThreadPool of arbitrary size (down to 0 threads). When 0 threads are used, the addSubTask() function will be blocking and execute the work immediately. If more than 0 threads are used, the addSubTask function will return immediately, and the task is instead added to the work queue for processing when a thread becomes available.
There are two ways to use the ThreadTask:
The four standard functions are as follows:
run() is the main work unit of the ThreadTask.
subTaskDone() is called each time a subtask has ended.
idle() is called when the task has finished its run() function and all subtasks has ended.
done() is the final function called before the ThreadTask is ended completely.
Please remember that the four functions can in general not be expected to be run in the same thread! In the first three functions it is allowed to add new subtasks to keep the thread running. In the done() function this is not allowed (it is simply ignored as the task will end immediately after this function has been called).
enum TaskState |
The different execution states of a task.
ThreadTask | ( | ThreadTask::Ptr | parent | ) |
Create task that will inherit parents thread pool.
parent | [in] the parent task to take the thread pool from. |
ThreadTask | ( | rw::core::Ptr< ThreadPool > | pool = NULL | ) |
Create task that will use a specific thread pool. If no thread pool is given, the task will not use parallelization.
pool | [in] (optional) a pointer to the ThreadPool to use. |
bool addSubTask | ( | ThreadTask::Ptr | subtask | ) |
Add a child task to this task.
This task will not end before all child tasks has ended. Never call execute on the child tasks - they will be executed by the parent task.
subtask | the ThreadTask to add as child. |
bool execute | ( | ) |
Start executing the work in this task and all subtasks already added, by using the assigned ThreadPool.
std::list<rw::core::Exception> getExceptions | ( | ) | const |
Get a list of exceptions registered in task and subtasks.
TaskState getState | ( | ) |
Get the current state of the task (non-blocking).
std::vector<ThreadTask::Ptr> getSubTasks | ( | ) |
Get the subtasks currently added to the ThreadTask.
rw::core::Ptr<ThreadPool> getThreadPool | ( | ) |
Get the ThreadPool that is used by this task currently.
bool keepAlive | ( | ) |
Check is the task has keep alive option enabled.
void registerFailure | ( | const rw::core::Exception & | e | ) |
Mark the task as a failure by registering an exception.
The user should override the subTaskDone function in the parent task to either handle the exceptions appropriately or propagate them further on.
e | [in] an exception describing the problem. |
void setKeepAlive | ( | bool | enable | ) |
Choose if the thread should exit automatically when all work and children has finished (this is the default).
Remember to set this to false when there is no more work to be done by the task, to allow the task to stop.
enable | [in] true if the thread should NOT finish automatically. |
bool setThreadPool | ( | rw::core::Ptr< ThreadPool > | pool | ) |
Set which ThreadPool to use to do the actual execution of work. When execution is started the pool can not be changed anymore.
pool | [in] pointer to the pool |
|
virtual |
Function is executed each time a subtask has finished (new subtasks can be added in this function). If registerFailure is used to register failures in subtasks, this function should handle or propagate the failures. The default implementation of this function is as follows:
for(const Exception& e : subtask->getExceptions()) { registerFailure(e); }
subtask | [in] the subtask that just finished. |
TaskState wait | ( | ThreadTask::TaskState | previous | ) |
Wait until state of task changes (blocking).
Remember to check if the new State is the desired (for instance DONE).
previous | [in] the previous state (wait for changes from this) |