tmr module¶

Status	Last Update	API Version
Active	2020-1-18	V1.00.00

Description¶

This is timer API, usually used in event-driven applications.

Typically, 3 steps should be taken in place to use a timer:

Call tmr.new() to get a timer instance.
Call instance:setup() to setup the timer.
Call instance:start() to start the timer.
If needed, call instance:remove().
See example code on the bottom of this page to get a clear look.

tmr.new()¶

Description¶

Create a new timer object.

Parameters¶

nil

Return value¶

Name	Type	Range	Usage
<instance>	timer		timer instance

Example call¶

tim1 = tmr.new()

timer:setup()¶

Description¶

Set the timer with given parameters.

Parameters¶

Name	Type	Range	Usage
<FirstTriggerTime>	number	0~(2^32-1)	Set the first trigger time (in ms) after timer:start() is called.
<Period>	number	0~(2^32-1)	Set the period of the the timer, if it is in mode `tmr.ONESHOT`, this parameter is ignored.
<Mode>	number	`tmr.ONESHOT` `tmr.MANUAL_RELOAD` `tmr.AUTO_RELOAD`	Set the mode of the timer: If `tmr.ONESHOT` is present, the timer is expired only once, it's `FirstTriggerTime` mili-seconds after `timer:start()` call. If `tmr.MANUAL_RELOAD` is present, the timer expires `FirstTriggerTime` mili-seconds after `timer:start()` call for the first time, and user should call `timer:reload()` to manually reload the timer, the next expire will happen `Period` miliseconds after the reload. If `tmr.AUTO_RELOAD` is set, the timer expires `FirstTriggerTime` mili-seconds after `timer:start()` call for the first time, and expires periodically every `Period` miliseconds.
<Callback>	function		Set the callback when the timer expires, the timer instance is passed to the callback as the first argument.

Return Value¶

nil

Example call¶

cnt3 = 0

function Auto_Timer_Callback(timer_self) 
  cnt3 = cnt3 + 1

  if cnt3 < 10 then 
    print('Auto-reload timer fired.','cnt3 =',cnt3,'t =',sys.gTick())
  else
    os.exit(0)
  end
end

tim = tmr.new()
tim:setup(1000,1000,tmr.AUTO_RELOAD,Auto_Timer_Callback)
tim:start()

timer:remove()¶

Description¶

Remove a timer and release its resources.

Parameters¶

nil

Return value¶

nil

Example call¶

tim:remove()

timer:suspend()¶

Description¶

Suspend a timer.

Parameters¶

nil

Return value¶

nil

Example call¶

tim:suspend()

timer:getCallback()¶

Description¶

Get callback function of an existing timer.

Parameters¶

nil

Return value¶

nil

Example call¶

cb = tim:getCallback()

Example Code¶

--[[This is a demo for timer APIs. The output will be on the terminal.
Notice that the timer is ONLY triggered AFTER THE SCRIPT EXITED and entered the EVENT LOOP. Therefore, if you want to use this API, your whole programme should be event-driven.
    Detailed Documentation:
    Version: 191111
    Author:  yanke928]]

cnt1=0
cnt2=0
cnt3=0

function OneShot_Timer_Callback(timer_self) 
  cnt1 = cnt1 + 1
  print('Oneshot timer fired. Starting tim2.','cnt1 =',cnt1,'t =',sys.gTick())
  tim2:start()
end

function ManualReload_Timer_Callback(timer_self) 
  cnt2 = cnt2 + 1

  if cnt2 < 5 then
    print('Manual-reload timer fired, reloading.','cnt2 =',cnt2,'t =',sys.gTick())
    timer_self:reload()
  else 
    print('Manual-reload timer fired, starting tim3','cnt2 =',cnt2,'t =',sys.gTick())
    tim3:start()
  end
end

function Auto_Timer_Callback(timer_self) 
  cnt3 = cnt3 + 1

  if cnt3 < 10 then 
    print('Auto-reload timer fired.','cnt3 =',cnt3,'t =',sys.gTick())
  else
    print('Demo is over')
    os.exit(0)
  end
end

tim1 = tmr.new()
tim1:setup(1000,1000,tmr.ONESHOT,OneShot_Timer_Callback)
--{startDelay} {interval} {mode} {callback}
tim1:start()

tim2 = tmr.new()
tim2:setup(1000,1000,tmr.MANUAL_RELOAD,ManualReload_Timer_Callback)

tim3 = tmr.new()
tim3:setup(1000,1000,tmr.AUTO_RELOAD,Auto_Timer_Callback)