MainLoopScheduler implements the Kanzi application main loop as a sequence of stages, each consisting of a sequence of tasks, where a task is a callable method.

You can customize the application main loop by extending its stages with additional tasks, replacing existing tasks with your own implementations, or adding timer tasks to execute some functionality at regular intervals.

Registering tasks

To register a task, call a prepend or append function. Specifically, those functions are MainLoopScheduler.prependTask and MainLoopScheduler.appendTask.

Example

-- Define the closure which you want to register
local handler = function()
    print("Task is executed")
end

-- Register it in the main loop scheduler.
local token = MainLoopScheduler.prependTask(
    MainLoopStage.USER,
    "MyTask",
    TaskRecurrence.Recurring,
    handler
)

Removing tasks

Remove the task through MainLoopScheduler.removeTask and MainLoopScheduler.clearTasks functions.

Example

-- Remove previously registered task by passing in its stage and a token.
MainLoopScheduler.removeTask(MainLoopStage.USER, token)
token = nil

-- You can also remove all tasks on a stage with a single call
MainLoopScheduler.clearTasks(MainLoopStage.USER)

Registering timers

Registering timers follows similar API to registering tasks. The main difference is that you need to provide an interval after which the task will be executed. The interval should be specified in nanoseconds. Helper functions utils.secs, utils.millis, utils.micros and utils.nanos can be used to make the intent clearer.

Example

-- Define the closure which you want to register
local handler = function()
    print("Timer is fired")
end

-- Register the timer in the main loop scheduler to run every 5 ms.
local token = MainLoopScheduler.prependTimer(
    MainLoopStage.USER,
    "MyTimer",
    TimerRecurrence.Recurring,
    secs(5),
    handler
)

Removing timers

Removing timers also follows similar API to tasks. However note, that the stage does not need to be passed.

Example

-- Remove previously registered task by passing in its stage and a token.
MainLoopScheduler.removeTimer(token)
token = nil

MainLoopScheduler.prependTask(stage, name, recurrence, task) ¶

Adds a task to the front of a stage.

Parameters

stage	(MainLoopStage)	Reference to the stage.
name	(string)	Name for the task.
recurrence	(TaskRecurrence)	Recurrence choice for the task that you want to insert.
task	(function)	The task that you want to insert.

Return Values

(MainLoopTaskToken)

Token of the added task. You can use this token to remove or replace the task.

MainLoopScheduler.appendTask(stage, name, recurrence, task) ¶

Adds a task to the back of a stage.

Parameters

stage	(MainLoopStage)	Reference to the stage.
name	(string)	Name for the task.
recurrence	(TaskRecurrence)	Recurrence choice for the task that you want to insert.
task	(function)	The task that you want to insert.

Return Values

(MainLoopTaskToken)

Token of the added task. You can use this token to remove or replace the task.

MainLoopScheduler.replaceTask(stage, token, task) ¶

Replaces a task in a stage with another one.

Parameters

stage	(MainLoopStage)	Reference to the stage.
token	(MainLoopTaskToken)	Token of the task.
task	(function)	The task with which to replace the current task.

Return Values

(boolean)

If replacement is successful, true. If the function cannot find the matching token, false.

MainLoopScheduler.removeTask(stage, token) ¶

Removes a task from a stage.

Parameters

stage	(MainLoopStage)	Reference to the stage.
token	(MainLoopTaskToken)	Token of the task.

Return Values

(boolean)

If removal is successful, true. If the function cannot find the matching token, false.

MainLoopScheduler.clearTasks(stage) ¶

Removes all tasks in a stage.

Parameters

stage

(MainLoopStage)

Reference to the stage.

MainLoopScheduler.prependTimer(stage, name, recurrence, interval, task) ¶

Adds a timer task to be executed before a stage in the main loop.

Parameters

stage	(MainLoopStage)	Reference to the stage.
name	(string)	Name for the task.
recurrence	(TimerRecurrence)	Recurrence type of the task.
interval	(number)	The length of time in nanoseconds, after which to execute the task.
task	(function)	The task.

Return Values

(MainLoopTimerToken)

Token of the added task. You can use this token to remove the task.

MainLoopScheduler.appendTimer(stage, name, recurrence, interval, task) ¶

Adds a timer task to be executed after a stage in the main loop.

Parameters

stage	(MainLoopStage)	Reference to the stage.
name	(string)	Name for the task.
recurrence	(TimerRecurrence)	Recurrence type of the task.
interval	(number)	The length of time in nanoseconds, after which to execute the task.
task	(function)	The task.

Return Values

(MainLoopTimerToken)

Token of the added task. You can use this token to remove the task.

MainLoopScheduler.removeTimer(token) ¶

Removes a timer task from the main loop.

Parameters

token

(MainLoopTimerToken)

Token of the task.

Return Values

(boolean)

If removal is successful, true. If the function cannot find the matching token, false.

MainLoopScheduler.setCurrentFrameRendered() ¶

Sets whether rendering was performed in the current frame. Call this function from a task in the Render stage to inform the main loop that the task performed rendering. The main loop uses this as a precondition for executing the Present stage for a frame.

MainLoopScheduler.isCurrentFrameRendered() ¶

Returns whether rendering was performed in the current frame. The main loop uses this as a precondition for executing the Present stage for a frame.

Return Values

(boolean)

If rendering was performed in the current frame, true, otherwise false.

MainLoopScheduler.setFrameRateLimit(framerate) ¶

Sets the frame rate limit of the application. This sets an upper limit on the number of frames rendered by Kanzi every second.

Parameters

framerate

(number)

The number of frames to render every second. To disable frame rate limit, use 0.

MainLoopScheduler.enableSuspendWhenIdle(suspendEnable) ¶

Sets whether an application allows suspension.

Parameters

suspendEnable

(boolean)

If the application allows suspension, use true, otherwise false.

MainLoopScheduler.isSuspendWhenIdleEnabled() ¶

Returns whether an application allows suspension.

Return Values

(boolean)

If the application allows suspension, true, otherwise false.