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)