到点，自己醒来

# 到点，自己醒来

11 月 13 日，上游多了一笔 `feat: add cron scheduler core (#55)`。`fun/lib/cron.fun`，410 行，纯 Fun；测试 105 行，进回归清单。标准库的模块数从 80 变成 81。

Fun 的服务端没有线程，这事在 9 月 25 日那篇里写过。没有线程，定时任务就只剩一条路：有人在一个循环里不停看表。cron 干的就是这件事。

```fun
use 'cron.fun';

cron.addJob('0 3 * * *', cleanup);
cron.addJob('0-30 * * * * *', cleanup, [withSeconds: true]);
cron.every('1s', refresh);

cron.run();
```

`run()` 阻塞，`stop()` 让它在当前回调结束后退出。四行，一个 daemon 的骨架就有了。

## 一、50 毫秒看一次表

`run()` 的循环只有三句：

```fun
while not _cronStop do
  _cronTick(_cronNow(), _cronNowMs());
  if not _cronStop then sleep(50); end if;
end do;
```

`_cronNow()` 把 `1.time().format('yyyy-mm-dd hh:nn:ss')` 切成七个整数，再补一个 `_cronDow` 算星期。没有引入日期库，星期是拿 0、3、2、5、0、3、5、1、4、6、2、4 十二个常数算的，月、日、闰年都在一行整除里。`_cronNowMs()` 用两个内建时间值相除，换算出毫秒。

（吐槽：写调度器的人，最后都得自己算一次星期。）

轮询 50 毫秒，意味着一个任务最多晚 50 毫秒被看见。对 `0 3 * * *` 这种一天一次的活，没人计较；对秒级任务，50 毫秒是 5% 的抖动。README 写得很直白：v1 的粒度约 50ms，暂不提供时区与 DST 控制。

## 二、分钟任务只在第 0 秒匹配

不带 `withSeconds` 时，`_cronMatch` 有一句额外的判断：

```fun
elsif n['second'] <> 0 then
  result = false;
  return;
end if;
```

所以 5 字段表达式只在整分那一秒成立。循环 50 毫秒跑一次，同一分钟里会撞上它好几回。去重靠 `lastKey`：把年月日时分（带秒的再拼上秒）拼成字符串，跟任务里存的比，一样就不再触发。

```fun
if j['lastKey'] <> key then
  j['lastKey'] = key;
  fired += 1;
  try
    j['fn']();
  except
  end try;
end if;
```

这个 `try/except` 是空的。回调抛错，调度器吞掉，接着看下一个任务。README 的说法是「回调异常会被隔离、不停止循环，但调度器不会上报」，建议在回调内部自己处理预期错误。我理解这个取舍：v1 先保证钟不停，报错通道留到后面。

（吐槽：一个空 `except` 放在别处是事故，放在调度循环里是设计。）

## 三、五个字段，和一些不猜的东西

解析按 Vixie/POSIX 来。每个字段先按逗号拆，再认 `*`、`a-b`、`*/n`、`a-b/n`、单值；月份认 `jan` 到 `dec`，星期认 `sun` 到 `sat`，大小写都行。星期里的 `7` 会并到 `0`，周日写两种都对。

宏只认五个：

```
@hourly  @daily/@midnight  @weekly  @monthly  @yearly/@annually
```

别的 `@` 开头一律报错，`@reboot` 也不例外。Quartz/AWS 的 `?`、`L`、`W`、`#` 和年字段，直接拒绝。源码注释里写的是「deliberately rejected rather than guessed」，翻过来就是：看不懂的写法，宁可让你当场改，也不替你猜一个意思。

6 字段得显式开：

```fun
cron.addJob('0-30 * * * * *', tick, [withSeconds: true]);
```

不开却给 6 段，报 `expected 5 fields, got 6`；开了却给 5 段，反过来。步长给 0、范围倒着写、值越界，报错都带字段名和原值，比如 `cron: minute: value out of range: 60`。这种消息不漂亮，但半夜看日志时够用。

## 四、日与星期，是「或」

`0 0 1 * 1` 是什么意思？每月 1 号，还是每周一？

Vixie cron 的规矩是：两个字段都受限时取「或」。测试里拿 2026 年 11 月对了一遍：11 月 1 日是 1 号，命中；11 月 2 日是周一，也命中；11 月 3 日两样都不是，不命中。

实现用 `domWild` 和 `dowWild` 记「这个字段是不是 `*`」，分三种情况：

```fun
if j['domWild'] then
  if j['dowWild'] then result = true; else result = dw; end if;
elsif j['dowWild'] then
  result = dm;
else
  result = dm or dw;
end if;
```

只有一边写了 `*`，就听另一边的；两边都写了 `*`，天天跑；两边都没写，才是「或」。这条规则跟直觉相反，但它是 cron 三十年留下的方言，改了就成另一种东西了。

## 五、慢回调不补课

固定间隔的任务是另一条路。`every('1m30s', fn)` 先解析成毫秒，`_cronDurationMs` 认 `ms`、`s`、`m`、`h`、`d`，可以连写，也可以直接给数字当毫秒。`0s`、`1x`、只有数字没单位，都报错。

到点执行时，下一次的时间不是「上次计划加间隔」，而是：

```fun
var nextAt = nowMs + interval;
try
  j['fn']();
except
end try;
var after = _cronNowMs();
if nextAt <= after then nextAt = after + interval; end if;
```

回调跑了 10 秒，间隔 1 秒，醒来时 `nextAt` 早过了，于是下一次从「现在」再往后排。中间漏掉的九次不补。注释写的是 `Missed runs are skipped; a long callback does not create a burst.`

这个选择对定时清理、心跳、刷新缓存都合适；对「每一次都必须发生」的账目任务就不合适。真要做后者，得在回调里自己记游标，不能指望调度器补。

## 六、怎么测一个时钟

最麻烦的是测试：等一分钟太慢，等到凌晨三点更慢。cron 的办法是把「现在」做成参数。`_cronParseExpr`、`_cronMatch`、`_cronTick` 都不读真实时间，时间结构由调用者递进去：

```fun
var n5 = at(2026, 11, 12, 3, 5, 0);
?. _cronTick(n5, 0) = 1;
?. fired = 1;
?. _cronTick(n5, 0) = 0;   // 同一分钟不重复
```

`_cronTick` 的第二个参数是毫秒，固定间隔任务靠它。真正跑循环的只有最后一段：`every(20, ...)`，命中三次就 `stop()`，测试里等的是几十毫秒，不是五分钟。

105 行测试，45 个 `?.`，快照里 45 个 `True`。断言只比布尔，不比字符串，报错文案改了也不用重录快照。这个做法朴素，但省事。

## 七、v1 的边界

README 把话说在前头：

- `run()` 占住当前线程，暂时不能和 `HttpServer.run` 共用；
- 用本地时间，不处理时区与 DST；
- 没有任务删除、下次执行查询、错误回调；
- 轮询约 50ms。

想删任务，只能 `stop()` 之后重建；想知道下次几点跑，只能自己按表达式算。都在路线图上，也都没到。

（吐槽：一个调度器最诚实的地方，是先把「我不做什么」写进 README。）

从 80 个模块到 81 个，多出来的这一个是钟。一个脚本语言长到能自己看表，离「常驻」就近了一步。至于它准不准，得让它跑过一个真实的凌晨三点才知道。