Documentation
¶
Overview ¶
Package async 提供安全的 goroutine 启动工具。
适用于所有使用此包的后端服务,防止 goroutine panic 导致进程崩溃。
核心特性 ¶
- 自动 recover panic 并记录堆栈
- 支持共享 channel 收集错误(GoSafeWithErrChannel)
- 一行代码替代 go func(){...}()
快速接入 ¶
替代裸 go 关键字:
async.GoSafe(func() {
doSomething()
})
需要收集多个 goroutine 的错误到同一 channel 时:
ch := make(chan error, 10)
async.GoSafeWithErrChannel(ch, func() error {
return doSomething()
})
错误只需日志上报的后台任务:
async.GoSafeWithErr(func() error {
return flushBatch(ctx)
})
携带 context 的安全 goroutine:
async.GoWithContext(ctx, func(ctx context.Context) { doWork(ctx) })
async.GoSafeWithContext(ctx, func(ctx context.Context) error { return doWork(ctx) })
命名后台任务(panic 日志带 task 标签,可按任务聚合告警):
async.GoSafeLabeled("janitor", func() { sweep() })
async.RunSafeLabeled("batch-flush", func() { flush() })
脱离请求生命周期、但保留 trace 追踪的后台任务(fire-and-forget 可观测):
async.GoDetached(ctx, "deploy-trigger", func(ctx context.Context) { trigger(ctx) })
旁路任务带句柄(脱离请求生命周期 + 限时 join 主路径,主路径失败也不腰斩旁路):
h := async.Spawn(ctx, "operation-stats", func(ctx context.Context) (Stats, error) {
return collectStats(ctx)
})
list, err := svc.ListOperations(ctx) // 主路径并行跑
stats, serr, timedOut := h.WaitUpTo(context.Background(), 5*time.Second)
if timedOut || serr != nil {
stats = degradedStats() // 旁路超时/失败 ⇒ 降级数据源(任务继续跑完、结果丢弃)
}
在**别人的 goroutine 边界**上就地收编 panic(第三方 SDK 回调,外层监督够不着), 且收编后要把 panic 连同 ctx 交给调用方自己记:
err := async.RunSafeCtx(ctx, func(ctx context.Context) { handleEvent(ctx, ev) })
var pe *async.PanicError
if errors.As(err, &pe) { log.ErrorContext(ctx, "事件处理 panic", "panic", pe.Value) }
需要同时拿返回值用 RunSafeCtxRet:panic 时返回零值与 *PanicError。 # 使用场景
- 后台任务:日志上报、指标采集、缓存预热
- 并发请求:同时调用多个下游服务
- 异步处理:消息发送、文件处理
Panic 处理 ¶
panic 被 recover 后会:
- 记录 panic 信息和完整堆栈到日志
- GoSafeWithErrChannel 会将 panic 转为 error 发送到共享 channel
- 不会影响主 goroutine 的正常运行
为什么使用标准库 log 而非 logx ¶
本包是使用方的 panic 兜底层,必须保持零内部依赖(依赖叶子节点)。 logx 会间接依赖 middleware、ratelimit 等上层包,而这些包又依赖 async, 若 async 反向依赖 logx 将形成导入环。因此本包刻意使用标准库 log。
Index ¶
- func DetachedContext(parent context.Context) context.Context
- func GoDetached(parent context.Context, task string, fn func(ctx context.Context))
- func GoSafe(fn func())
- func GoSafeLabeled(task string, fn func())
- func GoSafeWithContext(ctx context.Context, fn func(ctx context.Context) error)
- func GoSafeWithContextLabeled(ctx context.Context, task string, fn func(ctx context.Context))
- func GoSafeWithErr(fn func() error)
- func GoSafeWithErrChannel(ch chan<- error, fn func() error)
- func GoWithContext(ctx context.Context, fn func(ctx context.Context))
- func ReportPanic(r any)
- func RunSafe(fn func())
- func RunSafeCtx(ctx context.Context, fn func(context.Context)) (panicErr error)
- func RunSafeCtxRet[T any](ctx context.Context, fn func(context.Context) (T, error)) (val T, err error)
- func RunSafeErr(fn func() error) (err error)
- func RunSafeLabeled(task string, fn func())
- func RunSafeRet[T any](fn func() (T, error)) (val T, err error)
- func RunSafeRetLabeled[T any](task string, fn func() (T, error)) (val T, err error)
- func RunSafeRetWith[T any](r Runner, fn func() (T, error)) (val T, err error)
- func SetContextEnricher(fn func(parent, bg context.Context) context.Context)
- func SetPanicHandler(handler PanicHandler)
- func TaskFromContext(ctx context.Context) string
- type Handle
- type PanicError
- type PanicHandler
- type Runner
- type SuperviseOption
- func WithMaxConsecutiveFailures(max int) SuperviseOption
- func WithOnGiveUp(hook func(cause error)) SuperviseOption
- func WithOnRestart(hook func(restarts int64, cause error, wait time.Duration)) SuperviseOption
- func WithRestartBackoff(initial, max time.Duration) SuperviseOption
- func WithTask(name string) SuperviseOption
- type Supervision
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetachedContext ¶ added in v0.28.0
DetachedContext 返回与 parent 生命周期解耦、但保留 values 与观测信息的 ctx(#211):实现为 context.WithoutCancel(parent)(go 地板 1.24 直接用 stdlib),parent 的 values 经 Value 链原样继承——与 WithoutCancel 的 标准语义一致。
对照表(parent 的什么被保留/丢弃):
维度 | 保留?
-----------+------------------------------------------------------
Done/Err | 丢弃——返回值永不取消(Done 为 nil、Err 恒 nil),
| parent 的 cancel/超时不波及 fire-and-forget 任务
Deadline | 丢弃——WithoutCancel 不继承时限(连 values 一起留在
| 脱钩面上)——后台任务不受请求超时牵连
Values | 保留——Value 委托 parent(请求作用域:会话 scope、
| 租户标识等照常可读,ScopeFrom 类收编件不再静默降级)
trace | 保留——经 SetContextEnricher 注册的钩子把 parent 的
| trace_id 等注入返回值(无钩子、钩子返回 nil 或钩子 panic
| 时退回脱钩面,#217),日志仍能跟请求串起来
与手拼五件套(WithoutCancel + traceid 注入 + GoSafeLabeled)等价; 供需要自管 spawn 策略的调用方复用同一口径,常规后台任务直接用 GoDetached。
func GoDetached ¶ added in v0.28.0
GoDetached 启动**脱离请求生命周期、保留 values 与追踪信息**的后台安全 goroutine(#155、#211):
- fn 收到的 ctx 与 parent 解耦(DetachedContext:WithoutCancel 派生), 请求超时/断连不会腰斩在飞任务;
- parent 的 values 经 Value 链保留(#211:与 context.WithoutCancel 标准语义一致——请求作用域/会话 scope 在 fn 内照常可读,手拼 WithoutCancel 场景收编后不再静默丢 values);
- 经 SetContextEnricher 注册的钩子保留 parent 的 trace_id(由 tracing/ traceid 模块 init 注册,concurrency 不依赖具体实现);
- panic 收编并带 task 标签(与 GoSafeLabeled 同口径),汇报的 ctx 即 富化后的后台 ctx——trace 保留到 panic 日志里(#184)。
与既有原语的分工:
GoSafeWithContext(Labeled) = 跟随请求生命周期(请求取消即止); GoDetached = 与请求解耦但可追踪(fire-and-forget)。
适合构建/部署触发、通知下发、缓存失效等「异步但不该被请求取消牵死、日志又要 跟请求串起来」的调用点,替代各服务手抄的 WithoutCancel+traceid+GoSafe 三件套。
func GoSafeLabeled ¶ added in v0.5.0
func GoSafeLabeled(task string, fn func())
GoSafeLabeled 与 GoSafe 相同,但 panic 汇报的 ctx 携带任务归属标签。 后台循环 / 心跳 / 清扫等命名任务用本变体,运维可直接按 task 聚合。
func GoSafeWithContext ¶
GoSafeWithContext 启动一个携带 ctx 的安全 goroutine,fn 返回的 error (含 panic 转换的 error)经 PanicHandler 记录(r 为该 error 值)。 等价 GoWithContext + 错误上报;panic 与错误汇报均携带该 ctx。
func GoSafeWithContextLabeled ¶ added in v0.5.0
GoSafeWithContextLabeled 启动带 ctx 的安全 goroutine,panic 汇报携带该 ctx 与任务归属标签(#184 统一签名前标签拼在 msg 里,ctx 与标签只能二选一)。
func GoSafeWithErr ¶
func GoSafeWithErr(fn func() error)
GoSafeWithErr 启动一个带 panic 恢复的 goroutine 执行 fn。 fn 返回的 error(含 panic 转换的 error)经 PanicHandler 记录后丢弃—— 适合"错误只需日志上报"的后台任务;需要收集错误到共享 channel 用 GoSafeWithErrChannel,需要同步等待/级联取消用 concurrency/group。 handler 收到的 r 即该 error 值(非 panic 值)。
func GoSafeWithErrChannel ¶
GoSafeWithErrChannel 启动 fn 并把 panic 与 fn 返回值都发送到共享 channel。
用于需要收集多个 goroutine 的错误到同一 channel 的场景(如 concurrency/group)。 调用方需保证 ch 缓冲足够大(建议至少为参与 goroutine 的数量),避免阻塞。 发送始终非阻塞;若 channel 已满或已被调用方关闭,不阻塞、不崩溃, 相关 panic 经 PanicHandler 输出。调用方应避免在还有 goroutine 未返回时关闭 ch。
panic 分支发送统一收编载体 *PanicError(#268:携带栈、errors.As 可辨, 与同文件其余收编点同口径——此前 fmt.Errorf("panic: %v") 把 error 身份 拍平成纯文本,消费方无法判定「panic 失败」)。
func GoWithContext ¶
GoWithContext 启动一个携带 ctx 的安全 goroutine(panic 恢复,无错误上报)。 fn 收到的就是调用方传入的 ctx,取消/超时由调用方管理;panic 汇报也携带该 ctx(#184:handler 可按请求聚合日志)。
func ReportPanic ¶ added in v0.5.0
func ReportPanic(r any)
ReportPanic 将一次「已被调用方 recover 的 panic」上报给全局 PanicHandler, 供自管 recover 的编排原语(如 syncx.FanInErr 逐槽收编)保持与 GoSafe/RunSafe 统一的观测面——handler 注入方(日志/告警)不漏接任何恢复事件。 r 为 recover 的原始值;stack 取当前调用栈;ctx 为 Background(调用方自管 recover,手上没有可透传的任务 ctx)。
func RunSafe ¶ added in v0.4.0
func RunSafe(fn func())
RunSafe 在当前 goroutine 同步运行 fn,panic 被 recover 并经 PanicHandler 汇报(不重新 panic)。适合"第三方回调不应打死调用方"的场景,如批量执行器 执行用户回调;需要独立 goroutine 用 GoSafe。
func RunSafeCtx ¶ added in v0.26.0
RunSafeCtx 在当前 goroutine **同步**运行 fn,并把 panic 收编成 *PanicError 返回。
它补的是哪个缺口 ¶
三个既有形态都装不下「在别人的 goroutine 边界上就地收编 panic」:
- GoSafe / RunSafe:不返回任何值 ⇒ 调用方拿不到这次执行的结局;
- GoSafeWithContext:新开 goroutine,同样拿不到结局(#184 起 panic 汇报 虽已携带 ctx,结局仍不可知);
- RunSafeErr:能返回 error,但 fn 收不到 ctx ⇒ 收编点自己记不了 ctx 维度的账。
典型用途是**第三方 SDK 回调**:ws 客户端的读循环在 SDK 自己的 goroutine 里分发 事件,外层 GoSafe/Supervise 覆盖不到它,panic 必须在回调内就地收编,否则一条 坏事件就打死整个进程;而回调里又确实需要 ctx(trace/租户/超时)才能把这条 panic 记得有用。
语义 ¶
- fn 正常返回 ⇒ 返回 nil。
- fn panic(含 fn 为 nil 的调用)⇒ 返回 *PanicError(带原始 Value 与 Stack), errors.As 可辨;**同时**照 RunSafeErr 的口径向全局 PanicHandler 汇报一份—— 全局观测面不能因为「调用方自己也要记一笔」而漏掉这类事件。
- 本函数不开 goroutine、不做 ctx 取消判定:ctx 原样交给 fn,生命周期由调用方管。
用法:
err = async.RunSafeCtx(ctx, func(ctx context.Context) {
handleEvent(ctx, ev) // SDK 回调体
})
if pe := (*async.PanicError)(nil); errors.As(err, &pe) {
log.ErrorContext(ctx, "事件处理 panic", "panic", pe.Value) // 带 ctx 记日志
}
func RunSafeCtxRet ¶ added in v0.26.0
func RunSafeCtxRet[T any](ctx context.Context, fn func(context.Context) (T, error)) (val T, err error)
RunSafeCtxRet 同 RunSafeCtx,但 fn 带返回值——panic 时返回零值与 *PanicError。
单独一档而不是让 RunSafeCtx 泛型化:两者签名不同(一个无返回、一个 (T, error)), 合成一个会让「只要收编不要值」的调用点被迫写泛型实参。语义与 RunSafeRet 同款, 只多了 ctx 透传与「panic 也向全局汇报」。
func RunSafeErr ¶ added in v0.6.0
RunSafeErr 同步运行 fn,panic 收编为 error 返回(不再静默)。 适合「panic → 领域 error 透给调用方」场景(如 guardedCall)。 正常返回值原样透传;panic 时额外经 PanicHandler 汇报(r 为 recover 原始值)。
func RunSafeLabeled ¶ added in v0.5.0
func RunSafeLabeled(task string, fn func())
RunSafeLabeled 与 RunSafe 相同,但 panic 汇报的 ctx 携带任务归属标签 (TaskFromContext 可取),便于按任务维度聚合告警,不依赖堆栈解析。 task 为空时等价 RunSafe。
func RunSafeRet ¶ added in v0.6.0
RunSafeRet 同步运行返回 (T, error) 的 fn,panic 收编为 error(零值 T)。 调用方能区分「合法零值 + nil」与「panic 失败」。
func RunSafeRetLabeled ¶ added in v0.6.0
RunSafeRetLabeled 同 RunSafeRet,panic 汇报的 ctx 携带任务归属标签。
func RunSafeRetWith ¶ added in v0.7.0
RunSafeRetWith 是 Runner 版的 RunSafeRet(方法不能带类型参数, 泛型形态以包级函数提供)。
func SetContextEnricher ¶ added in v0.28.0
SetContextEnricher 注册全局「后台 ctx 富化」钩子(#155):GoDetached/DetachedContext 派生脱钩 ctx(WithoutCancel(parent),values 已继承)时回调 fn,由其把 parent 的追踪信息(trace_id 等)注入 bg。
典型接线(tracing/traceid 模块 init,一次注册全局生效):
func init() {
async.SetContextEnricher(func(parent, bg context.Context) context.Context {
if tid := traceid.FromContext(parent); tid != "" {
return traceid.ContextWith(bg, tid)
}
return bg
})
}
fn 为 nil 清除钩子(回到裸 Background)。钩子在后台 goroutine 启动前同步调用, 注意不要长时间阻塞。钩子自身的 panic 由 DetachedContext 就地收编(#217): 回退脱钩面并上报 PanicHandler——观测注入丢失,但调用方(含 GoDetached/ Spawn 的调用方 goroutine)不受影响,不会被打穿。重复注册以后一次为准 (进程级单钩子,与 SetPanicHandler 同形态)。
func SetPanicHandler ¶
func SetPanicHandler(handler PanicHandler)
func TaskFromContext ¶ added in v0.28.2
TaskFromContext 返回 panic 汇报 ctx 携带的任务归属标签(RunSafeLabeled / GoSafeLabeled / GoSafeWithContextLabeled / Supervise(WithTask) / GoDetached 注入);无标签返回空串。handler 注入方按任务维度聚合告警用它——#184 签名 统一前标签拼在消息前缀("task=<name>: ...")里,现在随 ctx 走,结构化日志 不必再解析消息文本。
Types ¶
type Handle ¶ added in v0.29.0
type Handle[T any] struct { // contains filtered or unexported fields }
Handle 是 Spawn 旁路任务的等待句柄。Done/Wait/WaitUpTo 并发安全, 可多调用方同时等待同一份结果(fan-in join 形态)。 T 为旁路任务的返回值类型——channel 元素类型的编译期对位由泛型承担, 「结果类型错了 run-time 才发现」这类手拼问题不再存在。
func Spawn ¶ added in v0.29.0
func Spawn[T any](ctx context.Context, task string, fn func(ctx context.Context) (T, error)) *Handle[T]
Spawn 发射**带句柄的旁路任务**(#197):脱离 parent 生命周期(WithoutCancel 语义内置——values 经 Value 链照常继承,#211 修正后与 stdlib 同语义)、 保留 trace、panic 收编进结果,返回句柄供限时等待。
「主路径旁路发一个任务、限时收结果」是请求处理器的高频形态(列表页的旁路 统计/预热/降级数据源)。既有原语盖不住它:
- GoDetached(#155)是 fire-and-forget——不返回句柄,「发出去了还想 限时等结果」表达不了;
- 手拼 channel 五件套(缓冲 1 的 chan + WithoutCancel + GoSafe + defer send + 限时 receive,git-ferry operation_log 实测 15 行)四处易错: 缓冲 <1 且主路径提前 return ⇒ sender 永远阻塞(goroutine 泄漏); 漏 WithoutCancel ⇒ 请求取消连带腰斩旁路任务;结果类型手写 channel 元素 ⇒ 类型错误 run-time 才发现;超时后「任务还在跑、结果已丢弃」 没有显式语义可观测。
Spawn 把五件套收编成一个泛型调用:
h := async.Spawn(ctx, "operation-stats", func(ctx context.Context) (Stats, error) {
return svc.Stats(ctx)
})
list, err := svc.ListOperations(ctx) // 主路径并行跑
stats, serr, timedOut := h.WaitUpTo(context.Background(), 5*time.Second)
if timedOut {
stats = degradedStats() // 旁路超时 ⇒ 降级数据源(任务继续跑完,结果丢弃)
} else if serr != nil {
stats = degradedStats() // 旁路失败 ⇒ 降级数据源
}
收编与日志口径:fn 的 panic 经全局 PanicHandler 汇报(新签名 ctx/r/stack, #184——汇报 ctx 为富化后的后台 ctx 并携带 task 标签,与 GoDetached 同口径) 并收编为 *PanicError 从 Wait/WaitUpTo 返回(errors.As 可辨)。fn 为 nil 时 同样走 panic 收编路径(runtime 「nil 函数调用」panic 转结果),不另设特判。
与既有原语的分工:
GoSafeWithContext(Labeled) = 跟随请求生命周期(请求取消即止),无结果句柄; GoDetached = 与请求解耦但可追踪,fire-and-forget,无结果句柄; Spawn = 与请求解耦 + 可等待句柄(限时 join 主路径)。
func (*Handle[T]) Done ¶ added in v0.29.0
func (h *Handle[T]) Done() <-chan struct{}
Done 返回完成信号 channel(任务完成或 fn panic 后关闭),供调用方把 「旁路完成」对接进自己的 select(与 Wait/WaitUpTo 并用不冲突)。
func (*Handle[T]) Wait ¶ added in v0.29.0
Wait 等到旁路任务完成,返回结果与错误;ctx 取消/超时(含包装链)提前 返回 (零值, ctx.Err())——**任务不会因此取消**(Spawn 已脱离 ctx 生命周期, 这只是放弃等待),任务继续跑完、结果丢弃。
ctx 为 nil 按 context.Background() 处理。 任务已完成且 ctx 恰好也已取消时,返回已完成的结果而非 ctx.Err() (结果已就位时取消没有意义)。
func (*Handle[T]) WaitUpTo ¶ added in v0.29.0
WaitUpTo 限时等待旁路任务:
- d 内完成 ⇒ (结果, 错误, false);
- d 内未完成 ⇒ (零值, nil, true)——timedOut 标记把「放弃后结果丢弃」 的语义显式化:任务继续在后台跑完(不受放弃影响、不会因超时被腰斩), 超时的这次调用不再收到结果;Handle 本身不关闭、不取消,**后来的** Wait/WaitUpTo(fan-in join 的其它等待方)仍能拿到真实完成结果—— 「迟到」只对放弃等待的那一路生效;
- ctx 先取消 ⇒ (零值, ctx.Err(), false)——与 Wait 的放弃等待同语义, 注意此时 timedOut 为 false(是「取消」不是「超时」,两条失败路径 调用方要能区分:超时可降级重试,取消应当级联收手)。
d <= 0 退化为非阻塞探活:已完成返回结果,否则立即 (零值, nil, true)。 ctx 为 nil 按 context.Background() 处理。
返回值序 (T, error, bool) 中 bool 置尾是刻意为之(区别于惯用的 ok 在尾 的单返回布尔):timedOut 与 error 是**并列的两种「没拿到结果」**—— timedOut=true 时 err 恒为 nil,调用方先判 timedOut 再判 err。
type PanicError ¶ added in v0.7.0
type PanicError struct {
// Value 是 recover() 的原始值。
Value any
// Stack 是 panic 时的调用栈(pkg errors.Recovered 采集,与 PanicHandler
// 收到的同一份)。
Stack []byte
// Task 是 Labeled 变体的任务标签;非 Labeled 为空。
Task string
}
PanicError 是 panic 收编为 error 的统一载体(#12)。
RunSafeErr / RunSafeRet / RunSafeRetLabeled 的 panic 分支、syncx.FanInErr 的逐槽收编、singleflight.Flight 的 waiter 错误路径均使用本类型——调用方 用 errors.As 即可区分「panic 失败」与「业务错误」,拿到原始 payload 与栈, 再按自己的 logger 补挂领域上下文后决定降级或透传。
Error() 文案与历史实现一致("panic: <Value>";Labeled 变体 "task=<Task>: panic: <Value>"),现有字符串匹配零破坏。
与 org panic 收编单源(pkg/errors.PanicError,#381)的分工:捕获与转换 全部走 pkg errors.Recovered(全矩阵唯一实现——nil 判定、栈采集、error 身份内建);本类型是本仓的兼容载体,额外携带 Task 标签并保留历史 Error() 文案,Unwrap(#267)与 pkg 同口径。
func NewPanicError ¶ added in v0.7.0
func NewPanicError(r any) *PanicError
NewPanicError 供包内其他收编点(syncx.FanInErr 逐槽、singleflight waiter) 构造统一载体;外部消费方一般不需要——错误已经从 RunSafe*/Slot.Err 拿到。
func (*PanicError) Error ¶ added in v0.7.0
func (e *PanicError) Error() string
func (*PanicError) Unwrap ¶ added in v0.34.0
func (e *PanicError) Unwrap() error
Unwrap 返回 panic 值中的 error(panic 值不是 error 时返回 nil)(#267): 业务侧 panic(err)(断言失败、require 类 panic 的常见形态)经收编后, 调用方仍能 errors.Is / errors.As 穿透本类型直达原始错误——错误身份全链 不再丢,与 pkg errors.PanicError 及同簇 fanout.ItemError 的 Unwrap 纪律 对齐。
type PanicHandler ¶
PanicHandler 是 panic 恢复时的处理函数,签名与 gopool.PanicHandler 完全一致 (#184):ctx 为任务提交/执行时的上下文(无可用 ctx 时为 context.Background; Labeled 家族与 Supervise(WithTask) 会把任务标签放进 ctx,经 TaskFromContext 可取),r 为 recover 的原始值,stack 为调用栈。 默认使用标准库 log.Printf。可通过 SetPanicHandler 注入自定义实现(如 logx)。
注意 r 不一定来自 panic:GoSafeWithErr / GoSafeWithContext 的「错误上报」 路径也走本 handler,此时 r 是 fn 返回的 error——全局观测面统一从这一个口子过。
func GlobalPanicHandler ¶ added in v0.36.1
func GlobalPanicHandler() PanicHandler
SetPanicHandler 设置全局 panic 恢复处理器(签名与 gopool.PanicHandler 同一 形态,#184)。应在 main.go 初始化阶段调用,注入 logx 等结构化日志实现。
handler 为 nil 时**恢复默认 handler**(标准库 log,与同矩阵 gopool.SetPanicHandler(nil) 同口径,#165)——而非静默关闭所有 panic 汇报; 两个同名 API 对 nil 的语义保持一致,一次误传 nil 不再让 panic 观测面整体失明。
用法:
async.SetPanicHandler(func(ctx context.Context, r any, stack []byte) {
logx.CtxError(ctx, "goroutine panic", logx.ErrKey, r, "stack", string(stack))
})
(logx.ErrKey 为 oekit/logx 的错误字段常量——错误字段名统一走该常量, 禁止手写 "err" 字面量,消费方仓 AGENTS 同款红线,#288。) GlobalPanicHandler 返回当前生效的全局 panic 处理器(#338:async 与 gopool 此前各持一套互不相通的 SetPanicHandler 全局——按 async godoc 在 main 注入 logx 后,gopool 默认池的 panic 仍走 stdlib log)。gopool 的池级处理器未显式 设置时经此回退到本全局;init 恒装载非 nil,调用方拿到的恒可用。
type Runner ¶ added in v0.7.0
type Runner struct {
// Handler 本实例的 panic 汇报函数(签名与全局 PanicHandler 一致,#184);
// nil 回退全局 PanicHandler。
Handler PanicHandler
}
Runner 携带自己的 PanicHandler 的 GoSafe/RunSafe 家族(#13)。
服务形态消费方继续用包级函数 + SetPanicHandler(进程入口一次); 库形态消费方(被宿主 import,不能动全局)在包级持有一个 Runner, panic 路由到自己的组件 logger,宿主的全局设置不受影响、互不覆盖。 零值 Runner 回退全局 handler(与包级函数行为一致)。
用法:
var runner = async.Runner{Handler: func(ctx context.Context, r any, stack []byte) {
logx.CtxError(ctx, "agentkit.worker.task_panic", logx.ErrKey, r, "stack", string(stack))
}}
(logx.ErrKey 为 oekit/logx 的错误字段常量——错误字段名统一走该常量, 禁止手写 "err" 字面量,消费方仓 AGENTS 同款红线,#288。)
runner.GoSafeLabeled("claim", func() { ... })
err := runner.RunSafeErr(func() error { ... })
func (Runner) GoSafe ¶ added in v0.7.0
func (r Runner) GoSafe(fn func())
GoSafe 启动带 panic 恢复的 goroutine(汇报走本实例 handler)。
func (Runner) GoSafeLabeled ¶ added in v0.7.0
GoSafeLabeled 带 task 标签的 GoSafe:标签经 panic 汇报的 ctx 携带 (TaskFromContext 可取,#184 前拼在 msg 前缀 "task=<name>: ..." 里)。
func (Runner) GoWithContext ¶ added in v0.7.0
GoWithContext 启动携带 ctx 的安全 goroutine(汇报走本实例 handler)。 panic 汇报携带该 ctx(#184:此前经由 GoSafe 委托,ctx 到不了 handler)。
func (Runner) RunSafe ¶ added in v0.7.0
func (r Runner) RunSafe(fn func())
RunSafe 同步运行 fn,panic 经本实例 handler 汇报(不重新 panic)。
func (Runner) RunSafeErr ¶ added in v0.7.0
RunSafeErr 同步运行 fn,panic 收编为 *PanicError 返回并经本实例 handler 汇报。
type SuperviseOption ¶ added in v0.24.0
type SuperviseOption func(*superviseConfig)
SuperviseOption 是 Supervise 的函数选项。
func WithMaxConsecutiveFailures ¶ added in v0.24.0
func WithMaxConsecutiveFailures(max int) SuperviseOption
WithMaxConsecutiveFailures 配置连续失败上限:连续 max 轮失败(错误或 panic) 后放弃重启并调用 onGiveUp(告警钩子),监督结束。0(缺省)= 不限,一直重启 到 ctx 取消或 loop 优雅返回。
func WithOnGiveUp ¶ added in v0.24.0
func WithOnGiveUp(hook func(cause error)) SuperviseOption
WithOnGiveUp 配置放弃重启时的告警钩子(需配合 WithMaxConsecutiveFailures)。 hook 自身 panic 被收编上报,不影响监督循环。
func WithOnRestart ¶ added in v0.24.0
func WithOnRestart(hook func(restarts int64, cause error, wait time.Duration)) SuperviseOption
WithOnRestart 配置每次重启前的观测钩子:restarts 是重启序号(从 1 起), cause 是该轮失败原因(loop 返回的错误或 *PanicError),wait 是本次重启等待。 hook 自身 panic 被收编上报,不影响监督循环。
func WithRestartBackoff ¶ added in v0.24.0
func WithRestartBackoff(initial, max time.Duration) SuperviseOption
WithRestartBackoff 配置重启节奏:第 k 次连续失败后等待 initial*2^(k-1),受 max 封顶(指数退避);max <= 0 时退化为固定 initial。 initial <= 0 = 失败后立即重启——**慎用**:loop 秒挂的常驻错误会退化成 热循环烧 CPU,除非调用方确有外部节流。 缺省:initial=1s、max=30s(指数退避封顶 30s)。
func WithTask ¶ added in v0.24.0
func WithTask(name string) SuperviseOption
WithTask 给监督循环设任务名:panic 汇报的 ctx 携带 task 标签(GoSafeLabeled 同款,TaskFromContext 可取),便于按任务维度聚合告警。
type Supervision ¶ added in v0.24.0
type Supervision struct {
// contains filtered or unexported fields
}
Supervision 是一个正在运行的监督循环句柄。
func Supervise ¶ added in v0.24.0
func Supervise(ctx context.Context, loop func(ctx context.Context) error, opts ...SuperviseOption) *Supervision
Supervise 启动监督循环(后台运行,立即返回 *Supervision)。
消费方多处手写的「后台循环防护」收编为一个原语(#137):GoSafe/GoSafeLabeled 只保进程不保循环——循环体 panic 后 goroutine 死亡、循环静默停摆(消费队列的 worker 停摆=丢消息、巡检循环停摆=新对象永不启动、活性表里的僵尸条目永占位)。 Supervise 提供监督语义三件套:
- **单轮 panic 收编**:loop panic 转成 *PanicError(errors.As 可辨、携带栈) 并带 task 标签上报全局 PanicHandler(标签经 panic 汇报的 ctx 携带, TaskFromContext 可取);
- **退避重启**:失败轮(错误或 panic)按指数退避重启(见 WithRestartBackoff), 重启等待可被 ctx 取消打断;
- **失败上限 + 告警钩子**:连续失败达上限放弃重启(WithMaxConsecutiveFailures + WithOnGiveUp),观测钩子见 WithOnRestart;Rounds/Restarts/ConsecutiveFailures 可做活性导出。
轮次语义:一次 loop 调用 = 一轮。
- loop 返回 nil = 优雅结束,监督随之结束(循环自己决定生命周期完成了; 常驻循环应在 ctx.Done 后返回);
- loop 返回 error 或 panic = 失败轮,触发重启流程;
- ctx 取消优先于一切重启:取消后不再启动新一轮,监督尽快结束 (结束原因见 Wait/Err)。
与 loop.Run 的分工:loop.Run 管「周期性 tick」(固定节奏、单轮 panic 不打断 后续轮次);Supervise 管「单个长驻循环活得好不好」(loop 自含迭代逻辑,整轮 死亡后从头重启——重启即丢失 loop 内部状态,有状态的循环应把状态外置或在 loop 内部自旋、只在整轮确实无法自愈时返回错误)。
用法:
sup := async.Supervise(ctx, func(ctx context.Context) error {
return consumeQueue(ctx) // panic/错误都会被监督重启
}, async.WithTask("outbox-worker"), async.WithMaxConsecutiveFailures(5))
async.GoSafe(func() { // 需要告警时另行监听
if err := sup.Wait(); err != nil { alert(err) }
})
func (*Supervision) ConsecutiveFailures ¶ added in v0.24.0
func (s *Supervision) ConsecutiveFailures() int64
ConsecutiveFailures 返回当前连续失败计数。轮次语义下「成功轮」即监督结束, 不存在中途清零——监督进行中该值就是自启动以来的失败轮累计,重启成功与否 要看 Rounds 是否增长(liveness 观测:失败计数增长而轮数不增长 = 循环一直 没能跑完一轮);优雅结束后归零(末轮成功),放弃重启后保留失败终值。
func (*Supervision) Done ¶ added in v0.24.0
func (s *Supervision) Done() <-chan struct{}
Done 返回监督结束的信号 channel。
func (*Supervision) Err ¶ added in v0.24.0
func (s *Supervision) Err() error
Err 返回结束原因(非阻塞;监督未结束时返回 nil——与 Done 配合使用)。
func (*Supervision) Restarts ¶ added in v0.24.0
func (s *Supervision) Restarts() int64
Restarts 返回因失败重启的累计次数。
func (*Supervision) Rounds ¶ added in v0.24.0
func (s *Supervision) Rounds() int64
Rounds 返回已完成的 loop 调用轮数(liveness 观测面:轮数停止增长 = 循环没在跑)。
func (*Supervision) Wait ¶ added in v0.24.0
func (s *Supervision) Wait() error
Wait 阻塞至监督结束并返回结束原因:
- nil:loop 优雅返回(返回值 nil);
- ctx.Err():ctx 取消(无论最后一轮 loop 是否报错——取消是调用方的停机 决定,业务错误不该伪装成监督的结束原因;调用方告警判据 「err != nil && !errors.Is(err, context.Canceled)」因此可靠);
- loop 的错误 / *PanicError:连续失败达上限放弃重启时最后的失败原因。
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package supervisor 提供「按键常驻循环集合」与动态目标集的持续对齐原语: Reconcile 对齐、Stop/Wait 停机排水,组内单条循环的监督语义复用 async.Supervise。
|
Package supervisor 提供「按键常驻循环集合」与动态目标集的持续对齐原语: Reconcile 对齐、Stop/Wait 停机排水,组内单条循环的监督语义复用 async.Supervise。 |