nrEngine::ITask Class Reference
[Kernel (Heart) of the nrEngine]

Each component of the engine/application does run as tasks in the Kernel. More...

Inheritance diagram for nrEngine::ITask:

Public Member Functions
virtual	~ITask ()
bool	operator< (const ITask &t)
bool	operator== (const ITask &t)
bool	operator<= (const ITask &t)
bool	operator> (const ITask &t)
bool	operator>= (const ITask &t)
bool	operator!= (const ITask &t)
virtual Result	updateTask ()=0
virtual Result	stopTask ()
virtual Result	onStartTask ()
virtual Result	onAddTask ()
virtual Result	onResumeTask ()
virtual Result	onSuspendTask ()
const char *	getTaskName ()
NR_FORCEINLINE TaskOrder	getTaskOrder () const
NR_FORCEINLINE TaskId	getTaskID () const
NR_FORCEINLINE TaskType	getTaskType () const
NR_FORCEINLINE TaskState	getTaskState () const
NR_FORCEINLINE TaskProperty	getTaskProperty () const
Result	addTaskDependency (SharedPtr< ITask > task)
Result	addTaskDependency (TaskId id)
Result	addTaskDependency (const std::string &name)
Protected Member Functions
void	setTaskName (const std::string &name)
	Setup the name of the task.
	ITask ()
	ITask (const std::string &name)
Friends
class	Kernel
	Kernel should have the full access to the task data. So kernel is our friend.
class	Engine
	Engine should also get full access to running tasks, to allow setting up system tasks.

---

Detailed Description

Each component of the engine/application does run as tasks in the Kernel.

ITask - is an interface for tasks of our kernel system. Kernel runs all specified and added task in their queue order (think on OS). So ITask Interface defines functions to be implemented by each task.

There is a rule to understanding order numbers:

• Each order-number is a number
• Bigger number - task will be executed later
• Between each defined default order-numbers there is ORDER_STEP numbers available
• There is no guarantee that two or more tasks with same order would be executed in next cycle in same order
• you can increase/decrease the order by substracting/adding of any number to any predefined order state
• Task names must be unique

Sometimes tasks depends on each other. So for example on task should be executed before another one. One way to solve this problem is to set the order number of each task manually. Other way is to use the dependencies infrastructure provided by task interface. You can setup task through it's ids to define tasks on which this one depends. Kernel will try to solve all dependencies and will bring all dependeable tasks in the right order according to their order numbers. If there is circular dependencies, so both tasks will not be added to the kernel's task list and an error code according to that problem will be given back.

• if task A depends on task B, so task A will be updated after the task B.
• if task A depends on task B and order number of task A is greater than B, so B will be updated before A, but the ordering number will not be changed.

Each task should support error handling routines. Tasks are running in the try-catch block. If kernel will catch any error by updating the task, the ITask::taskHandleError() function will be called. You have either to handle the error there or to pass the error back. Kernel will then send up the error along the function stack.
If the task couldn't handle the error it will be stopped and will be removed from the kernel task list. So each task object should be able to release all used memory also if there was an error before in the task update function.
This infrastructure allows us to catch up and to handle errors produced by the tasks. We can also remove tasks which couldn't handle their own errors. If you implement the task in the right way, then we can guarantee that no tasks would crash the kernel.

Definition at line 192 of file ITask.h.

---

Constructor & Destructor Documentation

nrEngine::ITask::~ITask

(

)

[virtual]

Virtual destructor to allow to derive new classes from this one

Definition at line 47 of file ITask.cpp.

nrEngine::ITask::ITask

(

)

[protected]

Define default variables. Set also default task order to ORDER_NORMAL and define the current state of the task to TASK_STOPPED.

Definition at line 24 of file ITask.cpp.

nrEngine::ITask::ITask

(

const std::string &

name

)

[protected]

You are allowed to specify the task name as a parameter for the task. Because no one can create directly the ITask instance, so only derived classes can setup their names.

Definition at line 29 of file ITask.cpp.

---

Member Function Documentation

bool nrEngine::ITask::operator<

(

const ITask &

t

)

One task is smaller than another one if it's order number is smaller

Definition at line 52 of file ITask.cpp.

References _taskOrder.

bool nrEngine::ITask::operator==

(

const ITask &

t

)

Two tasks are the same if their order number are equal or they are the same objects

Definition at line 57 of file ITask.cpp.

References _taskOrder.

virtual Result nrEngine::ITask::updateTask

(

)

[pure virtual]

In each cycle of our game loop this method will be called if task was added to our kernel.

Implemented in nrEngine::Clock, nrEngine::EventManager, nrEngine::IScript, and nrEngine::EmptyTask.

virtual Result nrEngine::ITask::stopTask

(

)

[virtual]

Stop the task before task will be killed. Each derived object should release used memory here or in the destructor.

Reimplemented in nrEngine::Clock.

Definition at line 225 of file ITask.h.

References nrEngine::OK.

virtual Result nrEngine::ITask::onStartTask

(

)

[virtual]

This method will be called by the kernel as soon as the task is prepared to run. So it will be started and in the next cycle it will be updated.

Reimplemented in nrEngine::Clock, and nrEngine::IScript.

Definition at line 231 of file ITask.h.

References nrEngine::OK.

virtual Result nrEngine::ITask::onAddTask

(

)

[virtual]

This method will be called by kernel when the kernel will try to add this task into the kernel's pipeline. If this method return other value then OK, so the task will not be added into pipeline.

Definition at line 238 of file ITask.h.

References nrEngine::OK.

virtual Result nrEngine::ITask::onResumeTask

(

)

[virtual]

Will be executed on waiking up the task from sleeping.

Definition at line 243 of file ITask.h.

References nrEngine::OK.

virtual Result nrEngine::ITask::onSuspendTask

(

)

[virtual]

Kernel will call this method if task will be aked to go for sleeping.

Definition at line 248 of file ITask.h.

References nrEngine::OK.

const char* nrEngine::ITask::getTaskName

(

)

Task should return his name. Name must not be unique. We will need this to read Log-Files in simple way.

Definition at line 254 of file ITask.h.

Referenced by addTaskDependency().

NR_FORCEINLINE TaskOrder nrEngine::ITask::getTaskOrder

(

)

const

Get order number of this task

Definition at line 259 of file ITask.h.

NR_FORCEINLINE TaskId nrEngine::ITask::getTaskID

(

)

const

Get id number of the task

Definition at line 264 of file ITask.h.

NR_FORCEINLINE TaskType nrEngine::ITask::getTaskType

(

)

const

Get the type of the task.

Definition at line 269 of file ITask.h.

NR_FORCEINLINE TaskState nrEngine::ITask::getTaskState

(

)

const

Get the state in which the task is

Definition at line 274 of file ITask.h.

Referenced by nrEngine::IScript::execute().

NR_FORCEINLINE TaskProperty nrEngine::ITask::getTaskProperty

(

)

const

Get task property

Definition at line 279 of file ITask.h.

Result nrEngine::ITask::addTaskDependency

(

SharedPtr< ITask >

task

)

Add a new task on which one this task depends.

Parameters:

task

Smart poitner to the task

Returns:

either OK or:

Definition at line 121 of file ITask.cpp.

References getTaskName(), nrEngine::Log::LL_DEBUG, nrEngine::Log::LOG_KERNEL, and nrEngine::OK.

Referenced by addTaskDependency().

Result nrEngine::ITask::addTaskDependency

(

TaskId

id

)

Add a new task on which one this task depends.

Parameters:

id

Unique ID of a task on which one this depends

Returns:

either OK or:

Definition at line 136 of file ITask.cpp.

References addTaskDependency(), nrEngine::Kernel::getTaskByID(), nrEngine::KERNEL_NO_TASK_FOUND, and nrEngine::Engine::sKernel().

Result nrEngine::ITask::addTaskDependency

(

const std::string &

name

)

Add a new task on which one this task depends.

Parameters:

name

Unique name of a task on which one this depends

Returns:

either OK or:

Definition at line 150 of file ITask.cpp.

References addTaskDependency(), nrEngine::Kernel::getTaskByName(), nrEngine::KERNEL_NO_TASK_FOUND, and nrEngine::Engine::sKernel().

---

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

• ITask.h
• ITask.cpp

---