Task is an interface for tasks that can be executed within BGThread. More...

#include <Radiant/Task.hpp>

Inheritance diagram for Radiant::Task:

Public Types
enum	{ PRIORITY_LOW = 1, PRIORITY_NORMAL = 500, PRIORITY_HIGH = 1000, PRIORITY_URGENT = 1500 }
	Standard priorities for tasks. More...

enum	State { WAITING, RUNNING, DONE }
	State of the task. More...

Public Member Functions
virtual void	doTask ()=0
	The actual work the task does should be implemented in here. More...

bool	isCanceled () const
	Returns whether a task has been canceled. More...

Priority	priority () const
	Get the current priority of the task. More...

void	runNow (bool finish)
	If the task isn't already finished, runs the task immediately in the calling thread. More...

void	schedule (Radiant::TimeStamp ts)
	Schedule the next execution time for this task. More...

Radiant::TimeStamp	scheduled () const
	Return a timestamp for the next execution of the task. More...

void	scheduleFromNow (Radiant::TimeStamp wait)
	Schedule the next execution time for this task. More...

void	scheduleFromNowSecs (double seconds)
	Schedule the next execution time for this task. More...

void	setCanceled ()
	Marks the task as canceled, so it will be removed.

void	setFinished ()
	Marks the task as finished, so it will be removed.

void	setPriority (Priority priority)
	Sets priority for task. More...

State	state () const
	Get the current state of the task. More...

	Task (Priority p=PRIORITY_NORMAL)
	Constructs a task with the given priority. More...

virtual	~Task ()
	Destructor.

Protected Member Functions
virtual void	canceled ()
	Cancel the task. More...

virtual void	finished ()
	Finished the task. More...

virtual void	initialize ()
	Initialize the task. Called by BGThread before the task is processed.

void	setState (State s)
	Sets the task state. More...

Friends
class	BGThread

Detailed Description

Task is an interface for tasks that can be executed within BGThread.

The purpose of Task is to make it easy to move time-consuing operations away from the main thread of the application. Tasks are placed in the Radiant::BGThread, that schedules and runs them as specified.

Typical operations that can be implemented with tasks are:

Loading data from disk
Creating new widgets, before inserting them into the scene
Checking for changes in the application configuration files

Please note that Tasks are expected to execute fast. In other words, a task should not perform long, blocking operations. Such operations (for example database queries, or network file transfers), are best handled by launching a separate thread for them. For this purpose, see Radiant::Thread.

If you implement tasks that take a long time to execute, you should check the task state periodically inside you Task::doTask function and return from the method if the task is set to Task::DONE state. Otherwise your application may stall for a while when closing down because the application will wait for any tasks to finish before it stops the BGThread running them.

Member Enumeration Documentation

anonymous enum

Standard priorities for tasks.

Enumerator
PRIORITY_LOW	Low priority.
PRIORITY_NORMAL	Normal priority.
PRIORITY_HIGH	High priority.
PRIORITY_URGENT	Urgent priority.

enum Radiant::Task::State

State of the task.

Enumerator
WAITING	Task is waiting in queue to be processed.
RUNNING	Task is currently running.
DONE	Task has finished.

Constructor & Destructor Documentation

Radiant::Task::Task ( Priority p = PRIORITY_NORMAL )

Constructs a task with the given priority.

Parameters

p	Priority for task

Member Function Documentation

virtual void Radiant::Task::canceled ( )

protectedvirtual

Cancel the task.

Called by BGThread after the task has been canceled

virtual void Radiant::Task::doTask ( )

pure virtual

The actual work the task does should be implemented in here.

Override in the derived class. When the task is finished it is important to set the State of the task to State::DONE (f.ex. calling setFinished) so that BGThread can properly release the task. If the state of the task is not set to State::DONE after call to this function this task is scheduled to be executed later.

Implemented in Radiant::SingleShotTask, Radiant::FunctionTask, and Luminous::MipMapGenerator.

virtual void Radiant::Task::finished ( )

protectedvirtual

Finished the task.

Called by BGThread after the task has been processed

bool Radiant::Task::isCanceled ( ) const

inline

Returns whether a task has been canceled.

Returns: True if the task has been canceled, false otherwise

Priority Radiant::Task::priority ( ) const

inline

Get the current priority of the task.

Returns: Priority of the task

void Radiant::Task::runNow ( bool finish )

If the task isn't already finished, runs the task immediately in the calling thread.

If the task is running in a background thread, waits until the task is released. Will call initialize() and finished() -functions if necessary. It's fine to call this function either before or after the task is added to BGThread, but this shouldn't be called at the same time as BGThread::addTask.

Parameters

finish run doTask until the task is in DONE state, otherwise just run the task once.

void Radiant::Task::schedule ( Radiant::TimeStamp ts )

inline

Schedule the next execution time for this task.

Parameters

ts	Time when the task is next executed

Radiant::TimeStamp Radiant::Task::scheduled ( ) const

inline

Return a timestamp for the next execution of the task.

Returns: Time when the task is next executed

void Radiant::Task::scheduleFromNow ( Radiant::TimeStamp wait )

inline

Schedule the next execution time for this task.

Parameters

wait	How long to wait before the execution of the task

void Radiant::Task::scheduleFromNowSecs ( double seconds )

inline

Schedule the next execution time for this task.

Parameters

seconds number of seconds before next execution

void Radiant::Task::setPriority ( Priority priority )

inline

Sets priority for task.

Parameters

priority Priority of the task

void Radiant::Task::setState ( State s )

inlineprotected

Sets the task state.

Parameters

s	State to set

State Radiant::Task::state ( ) const

inline

Get the current state of the task.

Returns: State of the task

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation