Documentation
¶
Overview ¶
Package supervisor 提供「按键常驻循环集合」与动态目标集的持续对齐原语: Reconcile 对齐、Stop/Wait 停机排水,组内单条循环的监督语义复用 async.Supervise。
收编自通道/连接/租户 worker 池类服务反复手写的那份形状——`map[K]entry{cancel, spec, done}` + mutex,自己实现 spec diff、done 非阻塞探活、意外死亡重启。锁内的 cancel/delete 顺序、快照比对都是并发正确性敏感点,每抄一份就多一处漂移。
在矩阵里的位置 ¶
async.Supervise 单条循环活得好不好(panic 收编 + 指数退避重启 + 失败上限) loop.Run 固定周期任务(心跳 / 清理 / 对账) supervisor.Group 一组循环的**集合**与外部目标集持续对齐(起/停/规格变更/探活)
三者职责不重叠:Group 只管集合对齐,组内单条循环的健壮性交给 Supervise。
最小用法 ¶
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
g := supervisor.NewGroup(ctx,
func(b Bot) string { return fmt.Sprintf("%d:%s", b.ID, b.Token) }, // 身份 + 规格变更判据
func(ctx context.Context, b Bot) error { return b.Run(ctx) }, // 常驻循环
supervisor.WithGroupTask("bot"),
)
// 定期把目标集拉下来对齐(对齐节奏交给 loop,不在本包再写一份定时器语义)
loop.Run(ctx, loop.Config{Interval: 30 * time.Second}, func(ctx context.Context) {
bots, err := loadBots(ctx)
if err != nil {
return // 拉不到就保持现状:别因为一次读库失败把全部循环停掉
}
g.Reconcile(bots)
})
// 停机
cancel() // 或 g.Stop()
g.Wait() // 排水
观测 ¶
Len(受管目标数)/ Running(循环仍在跑的目标数)/ Draining(已移除但未退出的 循环数)三个非阻塞探针足够区分「集合对但没在服务」与「停机卡住」两类故障。
Index ¶
- type Group
- type GroupOption
- func WithGroupMaxConsecutiveFailures(max int) GroupOption
- func WithGroupOnGiveUp(hook func(id string, cause error)) GroupOption
- func WithGroupOnRestart(hook func(id string, restarts int64, cause error, wait time.Duration)) GroupOption
- func WithGroupRestartBackoff(initial, max time.Duration) GroupOption
- func WithGroupTask(prefix string) GroupOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group[T any] struct { // contains filtered or unexported fields }
Group 管理「按键常驻循环集合」与动态目标集的持续对齐(#143)。
它补的是哪个缺口 ¶
async.Supervise 管**单条**循环的监督重启,loop.Run 管**固定周期**任务,但 「目标集来自外部存储(DB / 配置中心 / 平台接口),运行中要 reconcile——新增目标 起循环、消失目标停循环、规格变更重启循环、意外死亡探活重启」这一类常见形态 没有原语:通道/连接/租户 worker 池类服务各手写一份 `map[K]entry{cancel, spec, done}` + mutex,而锁内 cancel/delete 顺序、快照比对、done 非阻塞探活全是 并发正确性敏感点,抄一遍就多漂移一次。
Group 把这套收敛成两个动作:**对齐**(Reconcile)+ **停机排水**(Stop/Wait)。 组内单条循环的监督语义**完全复用** Supervise(panic 收编 + 指数退避重启 + 失败上限),Group 只负责集合对齐——两层职责不重叠。
身份与「规格变更」 ¶
IDOf 返回的不是「主键」而是**reconcile 键**:状态比较走这个字符串,组不做 结构比较。所以「哪些字段变了要重启」完全由调用方决定——把需要触发重启的规格 字段一并编进键里即可:
id := fmt.Sprintf("%d:%s", bot.ID, bot.Token) // token 变了 ⇒ 键变了 ⇒ 重启
这个设计是刻意的:拿 reflect.DeepEqual 比较规格会在「规格里含 mutex / 函数 / 时间戳字段」时给出假差异,进而变成重启风暴;而缺字段(该重启的没编进键)只是 少重启一次,两种失效方向不对称,故选宽容侧并由调用方掌握敏感度。
语义契约 ¶
- Reconcile(targets) 由**单个 goroutine** 调用(控制器式 reconcile 循环); Len/Targets/Running/Draining/Wait/Stop 可并发调用。
- 新增目标 ⇒ 起一条监督循环;消失目标 ⇒ 取消其 ctx 并转入排水集合 (不阻塞 Reconcile:慢排水的循环不能拖住对齐)。
- start 返回 nil = 该目标的循环**优雅结束**,不重启(目标仍在集合里, 见 Running);返回错误或 panic = 失败 ⇒ 按退避重启。
- start 收不到「该目标的 ctx」以外的任何东西:目标本身(含规格)由闭包捕获 —— start 的第二个参数就是规格,规格变更经 IDOf 变键后自然重启。
- 目标 id 为空字符串或同一批 targets 里 id 重复都是调用方契约违反 ⇒ panic (两者都会让「哪个循环属于谁」失去唯一性,静默容忍只会让错配在运行期才暴露)。
- Reconcile 不启动、不停止任何循环**在持锁状态下**:用户回调里读组状态 (Len/Running)不会自锁。
典型用法 ¶
g := supervisor.NewGroup(ctx, func(b Bot) string { return fmt.Sprintf("%d:%s", b.ID, b.Token) },
func(ctx context.Context, b Bot) error { return b.Run(ctx) }, // 常驻,ctx 取消后返回
supervisor.WithGroupTask("bot"),
supervisor.WithGroupValid(func(b Bot) bool { return b.Token != "" }),
)
defer g.Wait() // 配合 Stop 做排水
loop.Run(ctx, loop.Config{Interval: 30 * time.Second}, func(ctx context.Context) {
bots, err := loadBots(ctx)
if err != nil {
return // 拉不到目标集就保持现状,别把全部循环停掉
}
g.Reconcile(bots)
})
func NewGroup ¶
func NewGroup[T any]( ctx context.Context, idOf func(T) string, start func(ctx context.Context, target T) error, opts ...GroupOption, ) *Group[T]
NewGroup 构造受管组。组的生命周期由 ctx 决定:ctx 取消 ⇒ 所有目标循环一起取消。
idOf 返回目标的 reconcile 键(见 Group 文档「身份与规格变更」);start 是该目标 的常驻循环体——阻塞到 ctx 取消或该目标的连接确实结束为止,返回 nil 表示「优雅 结束、不要重启」,返回错误/panic 表示失败、按退避重启。
func (*Group[T]) Draining ¶
Draining 返回已从目标集移除、但循环还没退出的数量(非阻塞)。
停机观察用:Stop 之后该值长时间不归零,说明有循环不肯收尾(ctx 没被透传下去, 或阻塞在不可取消的调用里)。
func (*Group[T]) Reconcile ¶
func (g *Group[T]) Reconcile(targets []T)
Reconcile 把运行中的循环集合对齐到 targets:新增的起、消失的停、已排水的回收。
目标经 IDOf 得到的键既作身份也作「是否需要重启」的判据(见 Group 文档)。 必须由单个 goroutine 调用。组已 Stop 后调用是空操作。
idOf 是用户回调,**在锁外**调用(文档承诺回调里读组状态——Len/Targets/Running/ Draining——不会自锁,#188);其自身 panic 经 RunSafe 收编为 *PanicError 后转为 panic 上抛——上抛发生在无锁区,组不会被一次坏回调永久锁死(#189)。
func (*Group[T]) Running ¶
Running 返回**循环仍在跑**的目标数(非阻塞探活)。
小于 Len 说明有的目标优雅结束或连续失败后被放弃重启——这是「集合对齐了, 但实际没在服务」的唯一观测口。两项相等不代表健康(循环可能在空转), 但不等一定说明有目标缺位。
type GroupOption ¶
type GroupOption func(*groupConfig)
GroupOption 配置 Group 的重启策略与观测钩子。
选项是**非泛型**的:Go 不为「类型参数只出现在返回值里」的函数做推断,泛型选项 会让所有不关心目标类型的选项(任务名/退避/上限/钩子)在每个调用点被迫写实参。 目标类型相关的能力(如「规格不完整的目标跳过」)交给调用方在传 targets 前过滤。
func WithGroupMaxConsecutiveFailures ¶
func WithGroupMaxConsecutiveFailures(max int) GroupOption
WithGroupMaxConsecutiveFailures 配置组内单条循环的连续失败上限:超过后放弃重启 该目标并调用 WithGroupOnGiveUp。0(缺省)= 不限。
「放弃」是终态:该目标仍在目标集里、但已经没有循环在跑(见 Running)。要复活它, 先从目标集里摘掉再重新加入(让 Reconcile 当作新增目标从头启动)。
func WithGroupOnGiveUp ¶
func WithGroupOnGiveUp(hook func(id string, cause error)) GroupOption
WithGroupOnGiveUp 配置放弃重启某目标时的告警钩子(需配合 WithGroupMaxConsecutiveFailures)。钩子自身 panic 被收编上报。
func WithGroupOnRestart ¶
func WithGroupOnRestart(hook func(id string, restarts int64, cause error, wait time.Duration)) GroupOption
WithGroupOnRestart 配置组内单条循环的重启前观测钩子(id 是该目标经 IDOf 得到的 标识,restarts 从 1 起)。钩子自身 panic 被收编上报,不影响监督。
func WithGroupRestartBackoff ¶
func WithGroupRestartBackoff(initial, max time.Duration) GroupOption
WithGroupRestartBackoff 配置组内单条循环的重启节奏(语义同 async.WithRestartBackoff: 第 k 次连续失败后等 initial*2^(k-1),受 max 封顶)。缺省沿用 Supervise 的 1s/30s。
initial <= 0 表示失败后立即重启——慎用:秒挂的常驻错误会退化成热循环。
func WithGroupTask ¶
func WithGroupTask(prefix string) GroupOption
WithGroupTask 给组内每条循环设任务名:panic 汇报与重启日志带 `task=<prefix>[<id>]` 标签,可按目标维度聚合告警。缺省不打标签。