Timer module

Timer module description

The module provides functions (timers) which allow to delay the execution of arbitrary scripts.
The set_timeout function is commonly used if desired to have function called once after the specified delay. The set_interval function is commonly used to set a delay for functions that are executed again and again.
The interval the timer will wait before executing its action may not be exactly the same as the interval specified by the user.


Timer module API ( require "timer" )

Functions

Return Name and parameters
timer_id set_timeout( delay, script, args )
none set_timeout_with_id( delay, timer_id, script, args )
timer_id set_interval( delay, script, args )
none set_interval_with_id( delay, timer_id, script, args )
none cancel( timer_id )
bool exists( timer_id )
none reset( delay, timer_id )

set_timeout

Calls a script after specified delay.

Syntax

local timer_id = timer.set_timeout( delay, script, args )

Params

fields type description
delay number The time, in milliseconds (thousandths of a second), the timer should wait before the specified script is executed. Note that the actual delay may be longer
script string A script to be executed after the timer expires
args table Parameters which are passed through to the script. Note timeId will be added to args table

Returns

fields type description
timer_id string ID which uniquely identifies the timer

Examples

local timer = require("timer")

local timer_id = timer.set_timeout(1000, "HUB:module_name", { arg_name = "arg_value" })

set_timeout_with_id

Calls a script after specified delay.

Syntax

timer.set_timeout_with_id( delay, timer_id, script, args )

Params

fields type description
delay number The time, in milliseconds (thousandths of a second), the timer should wait before the specified script is executed. Note that the actual delay may be longer
timer_id string ID which uniquely identifies the timer (No timer will be created, if timer with specified timer_id exists)
script string A script to be executed after the timer expires
args table Parameters which are passed through to the script. Note timeId will be added to args table

Returns

fields type description
none

Examples

local timer = require("timer")

timer.set_timeout_with_id(1000, "ID", "HUB:module_name", { arg_name = "arg_value" })

set_interval

Calls a script repeatedly, with a fixed time delay between each call.

Syntax

local timer_id = timer.set_interval( delay, script, args )

Params

fields type description
delay number The time, in milliseconds (thousandths of a second), the timer should delay in between executions of the specified script. Note that the actual delay may be longer
script string A script to be executed every delay milliseconds
args table Parameters which are passed through to the script. Note timeId will be added to args table

Returns

fields type description
timer_id string ID which uniquely identifies the timer

Examples

local timer = require("timer")

local timer_id = timer.set_interval(1000, "HUB:module_name", { arg_name = "arg_value" })

set_interval_with_id

Calls a script repeatedly, with a fixed time delay between each call.

Syntax

timer.set_interval_with_id( delay, timer_id, script, args )

Params

fields type description
delay number The time, in milliseconds (thousandths of a second), the timer should delay in between executions of the specified script. Note that the actual delay may be longer
timer_id string ID which uniquely identifies the timer (No timer will be created, if timer with specified timer_id exists)
script string A script to be executed every delay milliseconds
args table Parameters which are passed through to the script. Note timeId will be added to args table

Returns

fields type description
none

Examples

local timer = require("timer")

timer.set_interval_with_id(1000, "ID", "HUB:module_name", { arg_name = "arg_value" })

cancel

Cancels a timer previously established by calling set_timeout or set_interval. Passing an invalid ID to cancel() silently does nothing; no exception is thrown.

Syntax

timer.cancel( timer_id )

Params

fields type description
timer_id string The identifier of the timer desired to cancel

Returns

fields type description
none

Examples

-- some_module.lua

local timer = require("timer")

local timer_id = timer.set_interval(1000, "HUB:handler", { arg_name = "arg_value" })
-- handler.lua

params = ...

local timer = require("timer")

print(params.arg_name)

timer.cancel(params.timerId)


exists

Check if timer established with specified ID

Syntax

timer.exists( timer_id )

Params

fields type description
timer_id string The identifier of the timer

Returns

fields type description
bool true if timer is established, false otherwise

Examples

-- module.lua

local timer = require("timer")

if timer.exists("timer_id") then
    print("timer exist")
else
    print("timer does not exist")
end

reset

Reset a timer previously established by calling set_timeout or set_interval. Passing an invalid ID to restart() silently does nothing; no exception is thrown.

Syntax

timer.reset( delay, timer_id )

Params

fields type description
delay number New delay for the timer. The time, in milliseconds (thousandths of a second). Note that the actual delay may be longer
timer_id string The identifier of the timer desired to restart

Returns

fields type description
none

Examples

-- module.lua

local timer = require("timer")

local timer_id = timer.set_interval(1000, "HUB:handler", { arg_name = "arg_value" })

timer.reset(2500, timer_id)