启动一次或周期定时并取消，到期事件进入统一事件队列的公共接口。
源码浏览已生成；不能解析的文件以纯文本展示，不表示通过类型检查。
# 网页定时接口规范 0.1.0
本包让浏览器（及能提供同义事件队列的宿主）里的豫言应用启动一次或周期定时并取消。定时**只产生事件**：到期时宿主向应用的统一事件队列投递一个类型为“定时”的事件，应用用网页事件包的 `等待网页事件` 取出。宿主不在定时器回调里运行任何应用代码，业务刷新逻辑由应用在取到事件后自行决定。应用依赖本包后，全部函数都必须实现。
## 函数
### `启动一次定时 : 整数 → 字符串 → 整数`
参数依次为**延时毫秒**（0 至 2147483647）与**标记**（任意文字，至多 1024 个 UTF-16 码元；宿主原样带回，应用用它区分用途）。返回**定时号**（正整数，在宿主实例内单调递增，不复用）。延时到期后宿主投递一个事件，之后该定时器消失。
### `启动重复定时 : 整数 → 字符串 → 整数`
参数为**间隔毫秒**（10 至 2147483647）与标记，返回定时号。每隔一个间隔投递一个事件，直到 `取消定时`。**不积压**：上一个事件还没被应用取走时，到期的定时器不再投递新事件，因此应用忙碌时不会被淹没，也不会“补投”错过的期次；应用可用事件里的 `时刻` 判断实际间隔。
### `取消定时 : 整数 → 爻`
取消定时器并移除该定时号尚未被取走的事件。若这次调用阻止了之后的事件——定时器仍然存在，或队列里有该定时号未取走的事件被移除——返回阳；定时号未知，或一次定时的事件早已被取走时返回阴。**取消之后保证不再收到该定时号的事件**；已被 `等待网页事件` 取走的事件无法撤回，应用用自己的“世代”记录判断即可。
## 事件
类型 `定时`，字段依网页事件规范：`订阅号` 为定时号，`名称` 为 `定时`，`详情` 为
```json
{"种类":"一次","标记":"轮询","时刻":1790000000123}
```
`种类` 为 `一次` 或 `重复`；`时刻` 是触发时宿主墙上时钟的 Unix 毫秒。同一个周期定时器同一时刻至多有一个未取走的事件；多个定时器的事件按触发先后排队。定时事件与其他类型的事件独立计数，默认队列上限 1024，满时丢弃最旧的定时事件并计入丢弃数（一次定时器的事件被丢弃即永久丢失，应用应尽快取事件）。
## 限额与失败
| 项 | 限额 |
| --- | --- |
| 同时存在的定时器 | 至多 64 个（一次定时器到期后即释放名额） |
| 一次定时延时 | 0 至 2147483647 毫秒 |
| 周期定时间隔 | 10 至 2147483647 毫秒 |
| 标记 | 至多 1024 个 UTF-16 码元 |
**违规调用**（数值越界、标记过长、定时器已满）抛豫言事故，消息为中文；取消未知的号不是失败，返回阴。宿主关闭后所有定时器被清除，之后启动定时同样抛事故。
## 浏览器的实际约束
- 页面在后台标签时，浏览器会把定时降频到约每秒一次，长时间后台可能更慢；应用不应依赖后台精度。
- 定时事件与界面事件共用应用的单个事件循环：应用正在处理一个耗时的事件时，到期事件在队列里等待。
- 计时基于宿主的 `setTimeout`/`setInterval`，不承诺毫秒级精确。
## 一致性样例
1. `启动一次定时(30, "甲")` 返回 1；`等待网页事件` 得类型 `定时`、订阅号 1、详情 `{"种类":"一次","标记":"甲",…}`；再次等待不会再有该定时号的事件。
2. `启动重复定时(20, "乙")` 后应用忙碌 200 毫秒再取事件：只得到一个事件（不积压）；取走后继续每隔约 20 毫秒有新事件。
3. `启动一次定时(1000, "丙")` 立即 `取消定时`：返回阳，1 秒后没有事件；再取消同一号返回阴。
4. 定时到期、事件排在队列里尚未取走时 `取消定时`：返回阳，队列里该事件被移除。
5. 同时存在 64 个定时器时再启动：抛事故；取消一个后可以再启动。
## 边界
本包不规定：动画帧与空闲回调（见宿主库的“宿主”类事件）、按墙上时钟日期触发（云端的定时事件包是另一回事，见“定时事件”包）、跨窗口共享、休眠恢复后的补偿。
# 网页定时之约 0.1.0
此包令浏览器（及能供同义事列之宿主）中豫言之客，启一次之期或周期之期而撤之。期**惟生事**：期至，宿主投类曰“定时”之事于客之统一事列，客以网页事件之约所载等待网页事件取之。宿主不于期回调中行客之代码，业务更新之法，客取事后自决。客依此包，诸术皆当具。
## 诸术
### 启动一次定时：整数、字符串，返整数
参数依次为**延时毫秒**（零至二十一亿四千七百四十八万三千六百四十七）与**标记**（任意文，至多一千零二十四 UTF-16 码元；宿主原样返之，客以别其用）。返**定时号**（正整数，实例内递增，不复用）。延时至则宿主投一事，其后此期消亡。
### 启动重复定时：整数、字符串，返整数
参数为**间隔毫秒**（十至二十一亿四千七百四十八万三千六百四十七）与标记，返定时号。每隔一间投一事，直至取消定时。**不积压**：前一事未被客取，则至期之定时不复投新事；客忙则不见淹没，亦不补投所失之期；客可以事中之“时刻”察其实际间隔。
### 取消定时：整数，返爻
撤其期，并去此号未取之事。若此一调阻止后事——期仍在，或列中有此号未取之事被去——则返阳；号未知，或一次之期其事已被取，则返阴。**既撤，保证不复收此号之事**；已被取之事不可追，客以己之“世代”记之可也。
## 事
类曰“定时”，诸字段依网页事件之约：订阅号即定时号，名曰“定时”，详情为
```json
{"种类":"一次","标记":"轮询","时刻":1790000000123}
```
种类曰“一次”或“重复”；时刻乃触发时宿主墙上钟之 Unix 毫秒。同一周期之期，同时至多一未取之事；诸期之事以触发先后排列。定时事与他类事各自计数，默认列限一千零二十四，满则弃最旧之定时事而计其数（一次之期其事被弃则永失，客当速取）。
## 限额与败
| 项 | 限 |
| --- | --- |
| 同时之期 | 至多六十四（一次之期至则释其额） |
| 一次之延时 | 零至二十一亿四千七百四十八万三千六百四十七毫秒 |
| 周期之间隔 | 十至二十一亿四千七百四十八万三千六百四十七毫秒 |
| 标记 | 至多一千零二十四 UTF-16 码元 |
**违约之调用**（数越界、标记过长、期已满）发豫言事故，其辞为中文；撤未知之号非败，返阴。宿主闭则诸期尽除，其后启期亦发事故。
## 浏览器之实约
- 页在后台，浏览器降定时至约每秒一次，久处后台或更缓；客勿恃后台之精。
- 定时事与界面事共一事环：客方处一耗时之事，至期之事于列中待之。
- 计时凭宿主之 setTimeout 与 setInterval，不保毫秒之准。
## 一致性之例
1. 启动一次定时（三十，“甲”）返一；等待网页事件得类定时、订阅号一、详情 `{"种类":"一次","标记":"甲",…}`；再候不复有此号之事。
2. 启动重复定时（二十，“乙”）后客忙二百毫秒再取事：仅得一事（不积压）；取后续每约二十毫秒有新事。
3. 启动一次定时（一千，“丙”）即取消定时：返阳，一秒后无事；再撤同号返阴。
4. 期至而事在列未取时取消定时：返阳，列中此事被去。
5. 同时有六十四期而再启：发事故；撤其一后可再启。
## 界
此包不定：动画帧与空闲回调（见宿主库“宿主”类之事）、依墙上钟日期而触发（云端之“定时事件”包乃别事）、跨窗共享、休眠复起之补偿。