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< ITaskgetTaskByID (TaskId id)
SharedPtr< ITaskgetTaskByName (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:
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:
Generated on Wed Sep 12 23:19:43 2007 for nrEngine by  doxygen 1.5.1