Documentation
¶
Overview ¶
Package loop 提供周期任务循环原语:ctx 感知 + 单轮 panic 收编 + 两种间隔模式 + 排水。
收编自消费方反复手搓的同一模式(过期清理 / 心跳 / 快照落盘 / 配置轮询等), 把五个易漂移语义一次钉死:
- 忙时丢 tick——fn 同步执行、不重叠,执行期间的 tick 直接丢弃(IntervalFixed)
- 轮次完成后间隔——本轮跑完再等 Interval,轮次间隔 ≥ Interval 由构造保证 (IntervalAfterCompletion,#140)
- 单轮 panic 不打死循环——按 async.RunSafe 收编(走全局 PanicHandler),循环存活
- 停机排水——ctx 取消拦「下一轮」,在飞轮次用独立 ctx 跑完;Wait() 等排水结束
- 首跑延迟可被停机打断——FirstDelay 走 select 而非 time.Sleep
用法 ¶
ctx, cancel := context.WithCancel(context.Background())
l := loop.Run(ctx, loop.Config{Interval: time.Hour, Name: "expire-sweep"}, func(ctx context.Context) {
sweep(ctx)
})
// ... 服务运行 ...
cancel() // 拦下一轮;在飞轮次跑完
l.Wait() // 排水(超时预算由调用方包一层控制)
后台巡检/清扫/指标类任务(跑到停机为止)用进程级变体 RunBackground—— 生命周期不挂调用方 ctx,消除「短函数 + defer cancel 令循环静默退役」的 脚枪(#154,Run 的 godoc 有 ❌/✅ 对照):
_ = loop.RunBackground(loop.Config{Interval: time.Minute, Name: "timeout-check"}, func(ctx context.Context) {
checkBuildTimeout(ctx)
})
⚠️ RunBackground 首次调用会注册 SIGINT/SIGTERM——进程对这两个信号的默认 终止行为随之失效(信号只取消循环,主流程需自行处理停机,#218)。不要该 副作用的调用方在进程启动早期调用 loop.DisableBackgroundSignalHandling (opt-out,见其 godoc)。
间隔模式 ¶
- IntervalFixed(默认):固定节奏 + 忙时丢 tick。关心「固定时刻表」的任务用这档。
- IntervalAfterCompletion:本轮 fn 返回(含 panic 收编)后再等 Interval。关心 「两次执行之间至少隔开 Interval」的任务用这档(清理 / 巡检 / 对账 / 认领-投递类 worker)——固定节奏语义下长轮次只丢 tick 不后移,「轮次间隔 ≥ Interval」无保证; 清理类任务用错模式会静默改变时序假设。
语义契约 ¶
- fn 立即(或 FirstDelay 后)首跑,之后按 IntervalMode 迭代
- fn 内 panic 按 RunSafe 收编,循环存活;Config.Name 非空时汇报带 task 标签; AfterCompletion 模式下 panic 收编完成后同样重新计时
- 忙时丢 tick 仅 IntervalFixed 有(fn 同步执行,不重叠)
- ctx 取消拦「下一轮」,在飞轮次跑完;Wait() 返回即排水完成
- Interval <= 0 时按 0 处理(忙轮询),调用方应给合理间隔
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DisableBackgroundSignalHandling ¶ added in v0.31.0
func DisableBackgroundSignalHandling()
DisableBackgroundSignalHandling 关闭 RunBackground 的进程级 SIGINT/SIGTERM 接管(#218 的 opt-out)。
背景:RunBackground 首次调用会注册 SIGINT/SIGTERM(signal.Notify) ——stdlib 语义下 Notify 一旦安装,进程对所注册信号的**默认终止行为**随即 失效(直至 Stop/Reset):信号只取消后台循环,主流程若阻塞在 listener/ wg.Wait 等原语上将不再因信号退出,运维只能 SIGKILL。这是进程级、godoc 之外不可见的副作用——自带完整停机处理(自己 signal.Notify / 用 Run + NotifyContext)而只想借 RunBackground 起后台巡检的调用方,在进程启动早期 调用本函数即可放弃该副作用:
func main() {
loop.DisableBackgroundSignalHandling() // opt-out:进程信号语义保持原样
loop.RunBackground(...) // 循环 ctx 永不因信号取消
// 停机由调用方自己的信号处理驱动
}
语义:
- 注册尚未发生(首个 RunBackground 之前调用):此后**永不注册**—— RunBackground 的循环 ctx 即 context.Background(),进程默认信号行为 全程不变;
- 注册已发生(已有 RunBackground 调用):立即撤销注册(signal.Stop), 恢复进程默认终止行为;**已启动的循环不受影响、也不再有任何信号可等** ——它们持有的 ctx 从此不会被取消,会一直跑到进程退出(需要收尾的 调用方应在 opt-out 之前自行安排循环退出);
- 幂等,可重复调用;并发安全。
Types ¶
type Config ¶
type Config struct {
// Interval 轮次间隔。<=0 视为 0(只跑首跑轮,避免忙轮询)。
// IntervalMode 两种模式下语义不同:IntervalFixed 是固定节奏的周期;
// IntervalAfterCompletion 是「本轮结束到下一轮开始」的间隔。
Interval time.Duration
// IntervalMode 间隔模式,缺省 IntervalFixed(保持既有语义,#140)。
IntervalMode IntervalMode
// FirstDelay 首跑延迟;0 = 立即首跑。延迟期间 ctx 取消可打断。
// 两种模式下都作用于首跑之前。
FirstDelay time.Duration
// Name 可选任务名:panic 汇报带 task 标签(async.RunSafeLabeled),便于按任务聚合。
Name string
}
Config 周期循环参数。
type IntervalMode ¶ added in v0.25.0
type IntervalMode int
IntervalMode 周期循环的间隔模式(#140)。
const ( // IntervalFixed 固定节奏(默认):按 Interval 的固定时刻表触发,忙时丢 tick—— // fn 同步执行不重叠,执行期间到点的 tick 积压在 ticker 缓冲(cap=1)自然合并。 // 关心「固定时刻表」的任务用这档(心跳 / 快照落盘 / 配置轮询)。 IntervalFixed IntervalMode = iota // IntervalAfterCompletion 轮次完成后间隔:本轮 fn 返回(含 panic 收编)后再等 // Interval 才跑下一轮——本轮跑得久,下一轮相应推迟。关心「两次执行之间至少 // 隔开 Interval」的任务用这档(清理 / 巡检 / 对账 / 认领-投递类 worker): // 固定节奏语义下「轮次间隔 ≥ Interval」没有保证(长轮次只丢 tick 不后移), // 而这类任务对时序的隐含假设恰恰是间隔下限。 // // 间隔从「本轮结束」起算:fn 返回 → 重置计时器 → 等 Interval → 下一轮。 // panic 收编(RunSafe)发生在 fn 外层,收编完成后同样重新计时。 IntervalAfterCompletion )
type Loop ¶
type Loop struct {
// contains filtered or unexported fields
}
Loop 一个正在运行的周期任务循环。
func Run ¶
Run 启动周期循环,立即(或 FirstDelay 后)返回 *Loop,不阻塞调用方。 循环在后台 goroutine 中运行;生命周期由 ctx 控制,排水用 Wait。
⚠️ 生命周期脚枪(#154):Run 非阻塞、循环存活完全挂在 ctx 上——「短函数里 派生 ctx + defer cancel」的顺手写法会在函数返回的瞬间静默退役循环(fn 仍会 跑完第一轮,冒烟测试发现不了,周期行为已死):
// ❌ 反例:函数返回即 cancel,循环存活不足一秒、零报错零日志
func startWorkers(rootCtx context.Context) {
ctx, cancel := context.WithCancel(rootCtx)
defer cancel()
loop.Run(ctx, cfg, fn) // 非阻塞,函数随即 return
}
// ✅ 正例一:长命 ctx(main/service 层持有,随进程/服务关闭取消)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
l := loop.Run(ctx, cfg, fn)
defer l.Wait() // 停机排水:在飞轮次收尾
...
}
// ✅ 正例二:后台巡检/清扫/指标类任务直接用 RunBackground(进程级生命周期;
// 会接管 SIGINT/SIGTERM 的进程默认终止行为——副作用与 opt-out 见 RunBackground)
loop.RunBackground(cfg, fn)
入口已取消的 ctx 会被拒绝启动并打一行可定位的 warn 日志(连首跑都不执行, 与 FirstDelay 路径的取消语义对齐)。
func RunBackground ¶ added in v0.28.0
RunBackground 启动**进程级**周期循环(#154):生命周期不再挂在调用方 ctx 上 ——内部使用共享的进程级 ctx(SIGINT/SIGTERM 取消),把「短函数 + defer cancel 令循环静默退役」的脚枪从 API 形态上消除。后台巡检/清扫/指标上报等「要一直 跑到停机」的任务九成要的就是这个;需要跟随请求/服务生命周期的循环仍用 Run。
⚠️ 进程级副作用(#218):首次 RunBackground 会注册 SIGINT/SIGTERM 的信号 监听(signal.Notify)——进程对这两个信号的**默认终止行为**从那一刻起失效: 信号只取消后台循环,主流程若没有自己的信号处理(此前依赖默认终止),停机 信号到达后循环退了、进程却退不了(阻塞在 listener/wg.Wait 上),只能 SIGKILL。调用方必须二选一:
- 自己处理停机(signal.NotifyContext / Run 的 ✅ 正例一),主流程收到 信号后自行收尾退出;
- 进程启动早期调用 DisableBackgroundSignalHandling 放弃信号接管,进程 默认终止行为保持原样(此时循环 ctx 永不因信号取消,停机由调用方驱动)。
排水:停机信号到达后在飞轮次收尾退出;调用方应在停机序列里(收到信号后) 对返回的 *Loop 调用 Wait,确保周期任务有界完成。