调度器

概述

每个 ActorContext 拥有独立的 Scheduler 实例，通过 ctx.Scheduler() 获取。调度器用于在指定时间或周期向目标 ActorRef（通常为当前 Actor 或子 Actor）投递消息。

• 生命周期：任务与当前 Actor 绑定，Actor 终止时其调度器上的任务会被自动清理。
• 作用域：系统不提供全局 Scheduler，所有调度均通过某一 Actor 的 Context 创建。

一次性延时（Once）

在延时一段时间后向目标 Actor 投递一次消息。

方法：Once(receiver ActorRef, delay time.Duration, message Message, options ...ScheduleOption) error

err := ctx.Scheduler().Once(ctx.Ref(), 5*time.Second, &MyMessage{Data: "delayed"})

• 返回 error 表示调度是否成功（如参数不合法）。
• delay 为 0 时会在极短延时后投递一次；任务到期后只投递一次。

固定间隔循环（Loop）

按固定间隔重复向目标 Actor 投递消息，直到任务被取消或 Actor 终止。

方法：Loop(receiver ActorRef, interval time.Duration, message Message, options ...ScheduleOption) error

err := ctx.Scheduler().Loop(ctx.Ref(), 10*time.Second, &TickMessage{})

Cron 表达式（Cron）

使用 Cron 表达式定义日历式调度，在匹配的时间点向目标 Actor 投递消息。

方法：Cron(receiver ActorRef, cron string, message Message, options ...ScheduleOption) error

// 每天 0 点
err := ctx.Scheduler().Cron(ctx.Ref(), "0 0 * * *", &DailyJob{})

• 若 Cron 表达式非法，返回 ErrorCronParse。

任务管理

创建任务时若未传 WithSchedulerReference，框架会自动生成唯一 reference；若需后续取消或查询，应在创建时传入并保存 reference。

检查任务是否存在（Exists）

判断指定 reference 的调度任务是否仍存在（未取消且未到期）。

方法：Exists(reference string) bool

• 返回 true 表示该 reference 对应的任务仍在调度器中；false 表示不存在或已取消/已到期。

取消任务（Cancel）

按 reference 取消该调度任务。

方法：Cancel(reference string) error

• 取消成功返回 nil。
• 若 reference 不存在，返回 ErrorNotFound。

refID := "my-timer-1"
ctx.Scheduler().Once(ctx.Ref(), time.Minute, msg, vivid.WithSchedulerReference(refID))
// ...
err := ctx.Scheduler().Cancel(refID)

清空全部任务（Clear）

取消当前 Scheduler 上全部已注册任务。

方法：Clear()

• 无参数、无返回值，调用后该 Actor 的调度器上不再有任何任务。

调度选项（ScheduleOptions）

通过 vivid.NewScheduleOptions 或 WithScheduleOptions、WithScheduleLocation、WithSchedulerReference 配置：