# thread.timer 库模块帮助文档

<details>  <summary>基础用法</summary>  <p>

```aardio 
import thread.timer;

var timer = thread.timer(1000, function(){
    // 工作线程中执行，不阻塞 UI
    print("定时执行", time());
});

timer.start();
thread.delay(3500);
timer.stop();
```

</p></details>

[» 调用范例](https://www.aardio.com/zh-cn/docs/examples/aardio/Thread/timer.html)

## thread 成员列表 <a id="thread" href="#thread">&#x23;</a>

### thread.timer <a id="thread.timer" href="#thread.timer">&#x23;</a>
线程定时器。  
基于 thread.event 创建独立工作线程定时执行任务，不会阻塞界面线程消息循环。

创建线程定时器。  
注意必须调用 start 方法才会启动定时线程。

### thread.timer() <a id="thread.timer" href="#thread.timer">&#x23;</a>
[返回对象:threadTimerObject](#threadTimerObject)

### thread.timer(interval,callback,...) <a id="thread.timer" href="#thread.timer">&#x23;</a>
创建线程定时器。  
参数 @interval 指定定时间隔（单位：毫秒），省略则默认为 1000 毫秒。  
参数 @callback 指定在独立工作线程中定时执行的纯函数（不能直接引用外部局部变量）。  
可选跟任意个附加参数（支持跨线程序列化传递的数据或 winform/控件对象），每次触发时作为参数传给 @callback。

## threadTimerObject 成员列表 <a id="threadTimerObject" href="#threadTimerObject">&#x23;</a>

### threadTimerObject.close() <a id="threadTimerObject.close" href="#threadTimerObject.close">&#x23;</a>
停止定时线程并释放相关内核句柄与线程共享变量。  
对象回收时会自动调用此方法。

### threadTimerObject.getInterval() <a id="threadTimerObject.getInterval" href="#threadTimerObject.getInterval">&#x23;</a>
获取当前定时间隔（单位：毫秒）。

### threadTimerObject.handle <a id="threadTimerObject.handle" href="#threadTimerObject.handle">&#x23;</a>
当前定时工作线程句柄（未运行时为 null）。

### threadTimerObject.interval <a id="threadTimerObject.interval" href="#threadTimerObject.interval">&#x23;</a>
读写定时间隔（单位：毫秒），支持在运行中动态修改。

### threadTimerObject.running() <a id="threadTimerObject.running" href="#threadTimerObject.running">&#x23;</a>
定时线程是否正在运行。

### threadTimerObject.setInterval() <a id="threadTimerObject.setInterval" href="#threadTimerObject.setInterval">&#x23;</a>
修改定时间隔（单位：毫秒），可在运行中动态调整。

### threadTimerObject.start <a id="threadTimerObject.start" href="#threadTimerObject.start">&#x23;</a>
启动线程定时器。  
如果定时器已在运行，则仅更新定时间隔（若指定了 @interval 参数）并返回 true。

### threadTimerObject.start(interval,count,...) <a id="threadTimerObject.start" href="#threadTimerObject.start">&#x23;</a>
启动线程定时器。  
可选用 @interval 修改定时间隔（毫秒）。  
可选用 @count 限定最大执行次数，达到次数后自动退出定时线程。  
可选传递新的回调参数覆盖构造时指定的附加参数。

### threadTimerObject.stop <a id="threadTimerObject.stop" href="#threadTimerObject.stop">&#x23;</a>
停止线程定时器并通知工作线程退出。

### threadTimerObject.stop(wait,timeout) <a id="threadTimerObject.stop" href="#threadTimerObject.stop">&#x23;</a>
停止线程定时器。  
@wait 指定是否等待当前正在执行的任务结束，默认为 true（使用 thread.waitOne 等待，不阻塞 UI 消息）。  
可选用 @timeout 指定最长等待毫秒数。

### threadTimerObject.threadId <a id="threadTimerObject.threadId" href="#threadTimerObject.threadId">&#x23;</a>
当前定时工作线程 ID（未运行时为 null）。

### threadTimerObject.wait(timeout) <a id="threadTimerObject.wait" href="#threadTimerObject.wait">&#x23;</a>
阻塞等待定时线程退出，可选指定超时毫秒数。

### threadTimerObject.waitOne(timeout) <a id="threadTimerObject.waitOne" href="#threadTimerObject.waitOne">&#x23;</a>
等待定时线程退出（不阻塞 UI 消息循环），可选指定超时毫秒数。

## threadTimerObject 事件列表 <a id="threadTimerObjectEvent" href="#threadTimerObjectEvent">&#x23;</a>

### threadTimerObject.onEnd <a id="threadTimerObject.onEnd" href="#threadTimerObject.onEnd">&#x23;</a>

```aardio
threadTimerObject.onEnd = function(){
	/*定时器通过 stop/wait/waitOne 确认结束时在调用线程触发此回调*/
}
```

### threadTimerObject.onTimer <a id="threadTimerObject.onTimer" href="#threadTimerObject.onTimer">&#x23;</a>

```aardio
threadTimerObject.onTimer = function(...){
	/*在独立工作线程中定时执行的纯函数。  
返回 false 或 0 可主动停止定时器；  
返回大于 0 的数值可动态修改下次定时间隔（毫秒）。*/
}
```

