RobWorkProject
Public Types | Public Member Functions | List of all members
ThreadTask Class Reference

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::common::Ptr< ThreadTaskPtr
 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::common::Ptr< ThreadPool > pool=NULL)
 Create task that will use a specific thread pool. More...
 
virtual ~ThreadTask ()
 Destruct this task.
 
bool setThreadPool (rw::common::Ptr< ThreadPool > pool)
 Set which ThreadPool to use to do the actual execution of work. More...
 
rw::common::Ptr< ThreadPoolgetThreadPool ()
 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::PtrgetSubTasks ()
 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 Exception &e)
 Mark the task as a failure by registering an exception. More...
 
std::list< ExceptiongetExceptions () 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). 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).
 

Detailed Description

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).

Member Enumeration Documentation

◆ TaskState

enum TaskState

The different execution states of a task.

Enumerator
INITIALIZATION 

Before execute has been called the first time.

IN_QUEUE 

Task has added its work to the pool, waiting for thread to become available.

EXECUTING 

The run function of the task is executing in the pool.

CHILDREN 

The run loop has finished, but children are still running.

IDLE 

The idle function is called and subtasks can still be added. If the keep alive has been enabled, the task will stay in this state and not continue to the POSTWORK state.

POSTWORK 

The task does not accept any more new subtasks - the done function is invoked.

DONE 

The done function has been invoked, and the task is now completed and dead.

Constructor & Destructor Documentation

◆ ThreadTask() [1/2]

Create task that will inherit parents thread pool.

Parameters
parent[in] the parent task to take the thread pool from.

◆ ThreadTask() [2/2]

ThreadTask ( rw::common::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.

Parameters
pool[in] (optional) a pointer to the ThreadPool to use.

Member Function Documentation

◆ addSubTask()

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.

Parameters
subtaskthe ThreadTask to add as child.
Returns
true if child was added successfully (only if task has not already ended)

◆ execute()

bool execute ( )

Start executing the work in this task and all subtasks already added, by using the assigned ThreadPool.

Note
There is no guarantee that the parent run() function starts executing before the childrens run() functions.
Returns
true if execution started successfully, false if already running or thread has finished.

◆ getExceptions()

std::list<Exception> getExceptions ( ) const

Get a list of exceptions registered in task and subtasks.

Returns
a list of exceptions.

◆ getState()

TaskState getState ( )

Get the current state of the task (non-blocking).

Returns
the current TaskState.

◆ getSubTasks()

std::vector<ThreadTask::Ptr> getSubTasks ( )

Get the subtasks currently added to the ThreadTask.

Returns
a vector of subtasks.

◆ getThreadPool()

rw::common::Ptr<ThreadPool> getThreadPool ( )

Get the ThreadPool that is used by this task currently.

Returns
pointer to the ThreadPool.

◆ keepAlive()

bool keepAlive ( )

Check is the task has keep alive option enabled.

Returns
true if task should be kept alive, false otherwise.

◆ registerFailure()

void registerFailure ( const 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.

Parameters
e[in] an exception describing the problem.

◆ setKeepAlive()

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.

Parameters
enable[in] true if the thread should NOT finish automatically.

◆ setThreadPool()

bool setThreadPool ( rw::common::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.

Parameters
pool[in] pointer to the pool
Returns
true if change was successful, false otherwise.

◆ subTaskDone()

virtual void subTaskDone ( ThreadTask subtask)
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:

 BOOST_FOREACH(const Exception& e, subtask->getExceptions()) {
    registerFailure(e);
 }
Parameters
subtask[in] the subtask that just finished.

◆ wait()

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).

Parameters
previous[in] the previous state (wait for changes from this)
Returns
the new TaskState

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