async

package
v0.39.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 10 Imported by: 0

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 后会:

  1. 记录 panic 信息和完整堆栈到日志
  2. GoSafeWithErrChannel 会将 panic 转为 error 发送到共享 channel
  3. 不会影响主 goroutine 的正常运行

为什么使用标准库 log 而非 logx

本包是使用方的 panic 兜底层,必须保持零内部依赖(依赖叶子节点)。 logx 会间接依赖 middleware、ratelimit 等上层包,而这些包又依赖 async, 若 async 反向依赖 logx 将形成导入环。因此本包刻意使用标准库 log。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DetachedContext added in v0.28.0

func DetachedContext(parent context.Context) context.Context

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

func GoDetached(parent context.Context, task string, fn func(ctx context.Context))

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 GoSafe

func GoSafe(fn func())

GoSafe launches a goroutine with panic recovery.

func GoSafeLabeled added in v0.5.0

func GoSafeLabeled(task string, fn func())

GoSafeLabeled 与 GoSafe 相同,但 panic 汇报的 ctx 携带任务归属标签。 后台循环 / 心跳 / 清扫等命名任务用本变体,运维可直接按 task 聚合。

func GoSafeWithContext

func GoSafeWithContext(ctx context.Context, fn func(ctx context.Context) error)

GoSafeWithContext 启动一个携带 ctx 的安全 goroutine,fn 返回的 error (含 panic 转换的 error)经 PanicHandler 记录(r 为该 error 值)。 等价 GoWithContext + 错误上报;panic 与错误汇报均携带该 ctx。

func GoSafeWithContextLabeled added in v0.5.0

func GoSafeWithContextLabeled(ctx context.Context, task string, fn func(ctx context.Context))

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

func GoSafeWithErrChannel(ch chan<- error, fn func() error)

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

func GoWithContext(ctx context.Context, fn func(ctx context.Context))

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

func RunSafeCtx(ctx context.Context, fn func(context.Context)) (panicErr error)

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

func RunSafeErr(fn func() error) (err error)

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

func RunSafeRet[T any](fn func() (T, error)) (val T, err error)

RunSafeRet 同步运行返回 (T, error) 的 fn,panic 收编为 error(零值 T)。 调用方能区分「合法零值 + nil」与「panic 失败」。

func RunSafeRetLabeled added in v0.6.0

func RunSafeRetLabeled[T any](task string, fn func() (T, error)) (val T, err error)

RunSafeRetLabeled 同 RunSafeRet,panic 汇报的 ctx 携带任务归属标签。

func RunSafeRetWith added in v0.7.0

func RunSafeRetWith[T any](r Runner, fn func() (T, error)) (val T, err error)

RunSafeRetWith 是 Runner 版的 RunSafeRet(方法不能带类型参数, 泛型形态以包级函数提供)。

func SetContextEnricher added in v0.28.0

func SetContextEnricher(fn func(parent, bg context.Context) context.Context)

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

func TaskFromContext(ctx context.Context) string

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

func (h *Handle[T]) Wait(ctx context.Context) (T, error)

Wait 等到旁路任务完成,返回结果与错误;ctx 取消/超时(含包装链)提前 返回 (零值, ctx.Err())——**任务不会因此取消**(Spawn 已脱离 ctx 生命周期, 这只是放弃等待),任务继续跑完、结果丢弃。

ctx 为 nil 按 context.Background() 处理。 任务已完成且 ctx 恰好也已取消时,返回已完成的结果而非 ctx.Err() (结果已就位时取消没有意义)。

func (*Handle[T]) WaitUpTo added in v0.29.0

func (h *Handle[T]) WaitUpTo(ctx context.Context, d time.Duration) (T, error, bool)

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

type PanicHandler func(ctx context.Context, r any, stack []byte)

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

func (r Runner) GoSafeLabeled(task string, fn func())

GoSafeLabeled 带 task 标签的 GoSafe:标签经 panic 汇报的 ctx 携带 (TaskFromContext 可取,#184 前拼在 msg 前缀 "task=<name>: ..." 里)。

func (Runner) GoWithContext added in v0.7.0

func (r Runner) GoWithContext(ctx context.Context, fn func(ctx context.Context))

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

func (r Runner) RunSafeErr(fn func() error) (err error)

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 提供监督语义三件套:

  1. **单轮 panic 收编**:loop panic 转成 *PanicError(errors.As 可辨、携带栈) 并带 task 标签上报全局 PanicHandler(标签经 panic 汇报的 ctx 携带, TaskFromContext 可取);
  2. **退避重启**:失败轮(错误或 panic)按指数退避重启(见 WithRestartBackoff), 重启等待可被 ctx 取消打断;
  3. **失败上限 + 告警钩子**:连续失败达上限放弃重启(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:连续失败达上限放弃重启时最后的失败原因。

Directories

Path Synopsis
Package supervisor 提供「按键常驻循环集合」与动态目标集的持续对齐原语: Reconcile 对齐、Stop/Wait 停机排水,组内单条循环的监督语义复用 async.Supervise。
Package supervisor 提供「按键常驻循环集合」与动态目标集的持续对齐原语: Reconcile 对齐、Stop/Wait 停机排水,组内单条循环的监督语义复用 async.Supervise。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL