# tmr模块

| 状态 |最后更新 | API版本 |
| ------ | ------ | ------ |
| Active | 2020-1-18 | V1.00.00 |

## 描述

定时器API。
典型的定时器API操作如下：
1.调用`tmr.new()`获得一个timer对象。
2.调用`instance:setup()`来配置timer。
3.调用`instance:start()`来启动timer。
4.如需要，调用`instance:remove()`。
5.页末有示例代码。

## tmr.new()

### 描述

创建一个定时器对象。

### 参数

nil

### 返回值

| 名称 | 类型 | 范围 | 用途 |
| ------ | ----- | --------- | ---------------- |
| <instance> | timer |  | 返回对象 |

### 调用例

```lua
tim1 = tmr.new()
```



## timer:setup()

### 描述

配置一个定时器。

### 参数

| Name                     | Type   | Range                                               | Usage                                                        |
| ------------------------ | ------ | --------------------------------------------------- | ------------------------------------------------------------ |
| <FirstTriggerTime> | number | 0~(2^32-1)                                          | 设置在`timer:start()`之后，第一次被触发的时刻(ms单位) |
| <Period>           | number | 0~(2^32-1)                                          | 设置timer的周期, 如果timer的模式是 `tmr.ONESHOT`, 这个参数没有作用 |
| <Mode>             | number | `tmr.ONESHOT` `tmr.MANUAL_RELOAD` `tmr.AUTO_RELOAD` | 设置timer的模式: 如果选择`tmr.ONESHOT`，timer只会到期一次，时间为调用`timer:start()`后的`FirstTriggerTime`毫秒。如果选择`tmr.MANUAL_RELOAD`, timer第一次在`timer:start()`调用后的`FirstTriggerTime`毫秒到期, 用户需手动调用`timer:reload()`来重载定时器, 下一次将在`Period`毫秒后到期。如果选择`tmr.AUTO_RELOAD`，timer第一次在`timer:start()`调用后的`FirstTriggerTime`毫秒到期, 之后每过`Period`毫秒后到期一次 |
| <Callback>           | function |                                                     | 设置timer到期时的回调函数，timer对象本身将作为回调函数的第一个参数 |

### 返回值
nil

### 调用例

```lua
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()

### 描述

移除一个timer并释放其资源。

### 参数

nil

### 返回值

nil

### 调用例

```lua
tim:remove()
```



## timer:suspend()

### 描述

挂起一个timer。

### 参数

nil

### 返回值

nil

### 调用例

```lua
tim:suspend()
```



## timer:getCallback()

### 描述

获取一个timer的回调函数。

### 参数

nil

### 返回值

nil

### 调用例

```lua
cb = tim:getCallback()
```



## Example Code

```lua
--[[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)


```