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

Heart of our engine system, where tasks are running. More...

Public Member Functions
void	sendEvents (bool bSend=true)
bool	isSendingEvents () const
Result	Execute ()
Result	OneTick ()
TaskId	AddTask (SharedPtr< ITask > task, TaskOrder order=ORDER_NORMAL, TaskProperty property=TASK_NONE)
Result	RemoveTask (TaskId id)
Result	SuspendTask (TaskId id)
Result	ResumeTask (TaskId id)
Result	StopExecution ()
Result	ChangeTaskOrder (TaskId id, TaskOrder order=ORDER_NORMAL)
SharedPtr< ITask >	getTaskByID (TaskId id)
SharedPtr< ITask >	getTaskByName (const std::string &name)
Protected Member Functions
bool	areSystemTasksAccessable ()
	Get information about lock state of the kernel.
Protected Attributes
std::list< SharedPtr< ITask > >	taskList
	Here kernel does store all currently running tasks.
std::list< SharedPtr< ITask > >	pausedTaskList
	Here kernel store all tasks that are sleeping now.
Friends
class	Engine
	Engine is allowed to create instances of that object.

---

Detailed Description

Heart of our engine system, where tasks are running.

Kernel - is the heart of our engine. Kernel is something like the oldschool Game Loop. You can add, remove, suspend or resume tasks from kernel's pipeline Tasks would be executed in their order - smaller order number comes before greater order number.

What should tasks supports:

• They should implement the ITask Interface
• They should be loaded and be ready to start before adding to kernels pipeline
• In each game cycle ITask::updateTask() Method will be executed
• By suspending or resuming the Tasks ITask::onSuspendTask()/onResumeTask() Method will be executed
• Before task will be removed ITask::stopTask() Method will executed
• Each taskID is unique and is greater than 0
• There is no TaskId wich will be given twice

Tasks can depends on each other, so one task should be updated before another one. This can be defined through task dependencies functions. Sometimes you also need to execute a task more than once per one kernel tick. This also can be specified by executing of appropriate functions.
Sleeping tasks will not be sorted in into the kernel's pipeline if any task will be added, that depends on such one. If the task will be resumed than the sorting will be done. So be warned that it is possible to retrieve a circularity error code during the waking up.

In our Engine their exisists system and user tasks. System tasks are not accessable through the user, because they are essential for engine's work. So to allow the engine to use same functions for task access, we define a boolean lock variable. If this variable is true, so all accesses to the kernel are done through the engine. The kernel can give then all tasks engine ask about. Locking of the kernel can only be done through the engine, so the user is not able to do the locking.
Better way to implement this is to have other programming language that allows "sandboxes" or similar techniques to distinguish between engine's own and user calls.

Note:

: Try to optimise this kernel by implementing O(1) Scheduler or something else if kernel loop/pipeline need a lot of time for updating. Better if you implement supporting of multithreaded Kernel, so we can support Multiple-CPU-System to increase game speed

Definition at line 85 of file Kernel.h.

---

Member Function Documentation

void nrEngine::Kernel::sendEvents

(

bool

bSend = true

)

Define if a kernel should send special task events on the engines default channel. Task events are used to inform the application and the engine, that state of certain tasks is changed.

Actually the engine does not need this events, cause engine's modules does not depend on each other, so they do not need this information. However your application could require this messages to react to certain conditions, i.e. clock task is sleeping

Parameters:

bSend

if true the events would be sent, if false so kernel is silent

Definition at line 100 of file Kernel.h.

bool nrEngine::Kernel::isSendingEvents

(

)

const

If true, so the kernel is currently inform teh application about task state changes by sending messages over the engine's default communication channel.

Definition at line 107 of file Kernel.h.

Result nrEngine::Kernel::Execute

(

)

Executes the kernel (old school main loop :-) Before main loop is started all tasks will be intialized by calling task function ITask::taskStart() . If taskStart returns error, so this task will be excluded from execution task list.

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error

If you get an error code back, so you can probably found more useful information in a log file filled out by the engine's kernel.

Definition at line 276 of file Kernel.cpp.

References nrEngine::Log::LOG_KERNEL, nrEngine::OK, OneTick(), taskList, and nrEngine::UNKNOWN_ERROR.

Referenced by nrEngine::Engine::runEngine().

Result nrEngine::Kernel::OneTick

(

)

Executes all task according to their order. After that return back. If you call this function for the first time, so the task will start before updating.

See also:

ITask manual to understand how tasks works

Definition at line 60 of file Kernel.cpp.

References ChangeTaskOrder(), nrEngine::Log::LOG_KERNEL, nrEngine::OK, RemoveTask(), nrEngine::TASK_RUN_ONCE, nrEngine::TASK_RUNNING, nrEngine::TASK_STOPPED, and taskList.

Referenced by Execute(), and nrEngine::Engine::updateEngine().

TaskId nrEngine::Kernel::AddTask	(	SharedPtr< ITask >	task,
		TaskOrder	order = ORDER_NORMAL,
		TaskProperty	property = TASK_NONE
	)

Add the given task into our kernel pipeline (main loop) Before task will be added it's ITask::taskInit()) function will be executed The returned task id number can be used to access to the task through kernel.

Parameters:

	task	- is a smart pointer to an object implementing ITask-Interface
	order	Order number for this task (default is ORDER_NORMAL)
	property	Specifiy the special property of the task

Returns:

task id of added task or 0 if task could not be added

Definition at line 300 of file Kernel.cpp.

References nrEngine::Log::LOG_KERNEL, nrEngine::OK, nrEngine::ORDER_SYS_LAST, nrEngine::ORDER_SYS_ROOT, nrEngine::orderToString(), pausedTaskList, nrEngine::TASK_IS_THREAD, nrEngine::TASK_STOPPED, nrEngine::TASK_USER, taskList, and nrEngine::UNKNOWN_ERROR.

Referenced by nrEngine::IScript::execute(), and nrEngine::Engine::initializeEngine().

Result nrEngine::Kernel::RemoveTask

(

TaskId

id

)

Remove the task from our game loop (pipeline).

Parameters:

id

- id of a task to be removed

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error
• KERNEL_NO_TASK_FOUND if no such task was found
• KERNEL_NO_RIGHTS if you try to remove a system task

Definition at line 374 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::KERNEL_NO_RIGHTS, nrEngine::KERNEL_NO_TASK_FOUND, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, nrEngine::OK, nrEngine::TASK_SYSTEM, and nrEngine::UNKNOWN_ERROR.

Referenced by OneTick(), and nrEngine::IScript::updateTask().

Result nrEngine::Kernel::SuspendTask

(

TaskId

id

)

Suspend task to prevent it from update. Task will get to sleep.

Parameters:

id

- id of a task to be suspended

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error
• KERNEL_NO_TASK_FOUND if such a task was not found
• KERNEL_NO_RIGHTS if you try to remove a system task

Definition at line 413 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::EventManager::emitSystem(), nrEngine::KERNEL_NO_RIGHTS, nrEngine::KERNEL_NO_TASK_FOUND, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, nrEngine::OK, pausedTaskList, nrEngine::Engine::sEventManager(), nrEngine::TASK_PAUSED, nrEngine::TASK_SYSTEM, taskList, and nrEngine::UNKNOWN_ERROR.

Result nrEngine::Kernel::ResumeTask

(

TaskId

id

)

Resume task from sleeping.

Parameters:

id

- id of a task to waik

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error
• KERNEL_NO_TASK_FOUND if such a task was not found
• KERNEL_NO_RIGHTS if you try to remove a system task

Definition at line 467 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::EventManager::emitSystem(), nrEngine::KERNEL_NO_RIGHTS, nrEngine::KERNEL_NO_TASK_FOUND, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, nrEngine::OK, pausedTaskList, nrEngine::Engine::sEventManager(), nrEngine::TASK_RUNNING, nrEngine::TASK_SYSTEM, taskList, and nrEngine::UNKNOWN_ERROR.

Result nrEngine::Kernel::StopExecution

(

)

Remove and kill all tasks from the kernel's task list. If no tasks are in the list, so the kernel will stop executing.

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error

Definition at line 526 of file Kernel.cpp.

References nrEngine::Log::LOG_KERNEL, nrEngine::OK, pausedTaskList, taskList, and nrEngine::UNKNOWN_ERROR.

Referenced by nrEngine::Engine::stopEngine().

Result nrEngine::Kernel::ChangeTaskOrder	(	TaskId	id,
		TaskOrder	order = ORDER_NORMAL
	)

Changes the order number of task with given id

Parameters:

	id	id of a task
	order	New order number for the task

Returns:

OK or error code:

• ERROR_UNKNOWN for unknown error
• KERNEL_NO_TASK_FOUND if such a task was not found
• KERNEL_NO_RIGHTS if you try to remove a system task

Definition at line 559 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::KERNEL_NO_RIGHTS, nrEngine::KERNEL_NO_TASK_FOUND, nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, nrEngine::OK, pausedTaskList, nrEngine::TASK_SYSTEM, nrEngine::TASK_USER, taskList, and nrEngine::UNKNOWN_ERROR.

Referenced by OneTick().

SharedPtr< ITask > nrEngine::Kernel::getTaskByID

(

TaskId

id

)

Returns smart pointer to a task with the given id.

Parameters:

id

ID of the task

Returns:

smart pointer to the task or NULL if no such task found or task is system task

Definition at line 685 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, and nrEngine::TASK_SYSTEM.

Referenced by nrEngine::ITask::addTaskDependency().

SharedPtr< ITask > nrEngine::Kernel::getTaskByName

(

const std::string &

name

)

Get the task wich has the same name as the given one.

Parameters:

name

Unique name of the task

Returns:

smart poitner to the task or to the NULL if no such task found or task is system task

Definition at line 713 of file Kernel.cpp.

References areSystemTasksAccessable(), nrEngine::Log::LL_WARNING, nrEngine::Log::LOG_KERNEL, and nrEngine::TASK_SYSTEM.

Referenced by nrEngine::ITask::addTaskDependency().

---

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

• Kernel.h
• Kernel.cpp

---