企业官网建设流程全解析

• 编程语言
• 语言运行时
• 编译器

Wren 的timer模块为 CLI 环境提供了一种挂起当前纤程（fiber）的机制：Timer.sleep(milliseconds)既可以当作简单的延时等待使用，也可以与Scheduler类配合，在休眠期间让 Wren 调度执行其他已排队的任务。读完本文，你将掌握Timer.sleep的完整 API 语义、参数约束与运行时错误条件，并学会用Timer.sleep+Scheduler.add编写基于纤程协作的异步脚本。

timer 模块概览

根据 CLI 模块索引，Wren 的命令行可执行文件（CLI）在语言内置模块之外，还自带一组面向脚本场景的模块，提供 IO 等设施。timer就是其中之一，其模块说明（见 timer/index.markdown）明确指出：

该模块提供一种机制，将当前纤程挂起一段指定时间——既可以作为简单的延时，也可以在此期间让其他操作异步执行。

整个模块只包含一个类：Timer。它没有构造函数、没有实例方法，所有能力都通过一个静态方法sleep暴露，属于典型的"工具类"设计。

Timer.sleep 的 API 与语义

签名与参数

Timer.sleep(milliseconds)

sleep是一个静态方法，直接通过类名调用，作用是将当前纤程挂起指定的毫秒数：

• 参数milliseconds表示休眠时长，单位是毫秒；
• 调用会挂起当前正在执行的纤程，而不是整个进程；
• 挂起期间，Wren 虚拟机可以继续执行其他纤程的任务。

这一点是理解Timer.sleep的关键：Wren 的并发模型基于纤程（fiber），Timer.sleep并不阻塞整个程序，而是只暂停当前纤程的执行流。

参数约束与运行时错误

官方文档（timer.markdown）明确规定了参数约束：

如果参数不是非负数（non-negative number），将产生运行时错误。

也就是说，milliseconds必须满足两个条件：

1. 必须是数字（number）类型；
2. 必须大于等于 0，即不能为负数。

例如以下调用都是合法的：

Timer.sleep(0) // 立即返回 Timer.sleep(100) // 挂起 100 毫秒 Timer.sleep(3000) // 挂起 3 秒

而传入负数、字符串等非法参数，都会在运行时抛出错误。文档并未给出具体错误消息文本，仓库源码中也没有针对该 API 的专门测试用例（当前仓库test/目录下未发现Timer.sleep相关测试），因此以官方文档描述的"运行时错误"为准即可。

挂起期间发生了什么：纤程协作模型

文档特别强调，Timer.sleep挂起的是当前纤程，而非整个程序。这在 Wren 中意味着：

• 当前纤程的后续代码暂时停止执行；
• 虚拟机的控制权让出，其他可运行的纤程有机会继续执行；
• 休眠时间结束后，当前纤程从挂起点恢复，继续向下执行。

这种"让出式"的协作调度，使得Timer.sleep天然适合与 Scheduler 类 搭配使用。Scheduler 维护了一个纤程队列，当收到"信号"时依次启动这些纤程；而该信号通常正是由File、Timer这些类的长耗时方法发出的——它们挂起当前纤程，让 Wren 在等待期间去做其他事情。

实战：Timer.sleep 与 Scheduler 协同编排任务

Scheduler 类只提供一个静态方法Scheduler.add(callable)：把一个新纤程加入调度队列，该纤程会调用传入的callable（一个函数或其他带call()方法的对象），执行完毕后转移到队列中的下一个纤程。

Scheduler 官方文档给出的完整示例，正好演示了Timer.sleep的核心用法——在休眠期间执行已排队的任务：

var a = 3 Scheduler.add { a = a * a } Scheduler.add { a = a + 1 } System.print(a) // still 3 Timer.sleep(3000) // wait 3 seconds System.print(a) // now 3 * 3 + 1 = 10

逐步解读这段脚本的执行过程：

1. 主纤程开始时a = 3；
2. 通过Scheduler.add依次注册两个闭包任务（先乘后加），但此时它们尚未执行，所以System.print(a)输出的仍是3；
3. 调用Timer.sleep(3000)挂起主纤程 3 秒——关键就在这一步：主纤程休眠期间，Scheduler 收到信号，依次启动队列中的两个纤程，分别执行a = a * a和a = a + 1；
4. 3 秒后主纤程恢复，此时a已经是3 * 3 + 1 = 10，第二次System.print(a)输出10。

这个例子直观展示了 Wren CLI 中"延时 + 异步任务编排"的典型模式：Timer.sleep不是简单地空等，而是把时间让渡给 Scheduler 处理其他待办任务。

注意事项：sleep 会冻结 System.clock

文档在 timer.markdown 中特别提示了一个容易被忽略的副作用：

注意：该方法也会挂起System.clock，因此程序无法据此获得正确的运行时间。

这与 System 类文档 中System.clock的定义直接相关——它返回"程序启动以来经过的秒数（含小数部分）"，通常用于基准测试（benchmarking）。当程序处于Timer.sleep休眠期间时，System.clock同样处于挂起状态，不会继续计时。

实际影响是：

• 如果在一个包含Timer.sleep的程序里用System.clock测量耗时，测量结果会偏小，因为它没有计入休眠时间；
• 对包含休眠等待的脚本做基准测试时，应改用不受挂起影响的计时方式，或在测量区间内避免调用Timer.sleep。

使用边界：CLI 专属模块

需要特别说明的是，timer（连同io、os、scheduler）属于 Wren CLI 扩展模块，而非语言内核。根据 CLI 模块索引 的说明：

CLI 模块与 libuv、彼此之间以及命令行应用的其他内部实现深度耦合，难以单独拆分出来供希望嵌入 Wren 的主机应用使用。因此，为 CLI 编写的脚本具有 CLI 特异性，除非其他宿主实现了相同的 API。

这意味着：

• Timer.sleep只在 Wren 的命令行可执行文件中可用；
• 如果你的脚本依赖Timer或Scheduler，它就无法直接移植到嵌入 Wren 的自定义宿主程序中；
• 想要在其他宿主里获得类似能力，需要自行实现同一套 API。

小结

• Timer.sleep(milliseconds)是timer模块唯一的 API，负责把当前纤程挂起指定毫秒数，参数必须是非负数字，否则产生运行时错误；
• 它采用协作式调度：休眠期间让出控制权，配合Scheduler.add可在等待期间按队列执行其他纤程任务；
• 它会连带挂起System.clock，涉及计时/基准测试时需避开休眠区间；
• 该模块是 CLI 专属扩展（与 libuv 深度绑定），不可用于嵌入式宿主场景。

对并发脚本而言，Timer.sleep+Scheduler.add组合是 Wren CLI 中最基础的异步编排工具：一个负责让出执行权，一个负责接管并推进待办任务，二者配合即可在单线程的纤程模型上实现"延时期间干别的事"的异步效果。

• 编程语言
• 语言运行时
• 编译器