worker

Documentation

Overview

SPDX-License-Identifier: AGPL-3.0-or-later

Package worker 提供统一后台任务抽象（Global Constraints #5）：顺序启动、 反向排空、panic 捕获（进程不崩）。

Index

• func CatchPanic(name string, log *logx.Logger)
• func GoLoop(ctx context.Context, name string, log *logx.Logger, fn func(context.Context))
• func GoRecover(name string, log *logx.Logger, fn func())
• func Loop(ctx context.Context, name string, log *logx.Logger, fn func(context.Context))
• func Recover(name string, log *logx.Logger, fn func())
• type Manager
  • func New(log *logx.Logger) *Manager
  • func (m *Manager) Go(ctx context.Context, name string, fn func(ctx context.Context))
  • func (m *Manager) Register(ws ...Worker) error
  • func (m *Manager) Shutdown(ctx context.Context) error
  • func (m *Manager) StartAll(ctx context.Context) error
• type Worker

Functions

func CatchPanic

func CatchPanic(name string, log *logx.Logger)

CatchPanic recovers from panic in the caller goroutine and logs Error. Usage: defer worker.CatchPanic("name", log)

func GoLoop

func GoLoop(ctx context.Context, name string, log *logx.Logger, fn func(context.Context))

GoLoop spawns Loop in a new goroutine.

func GoRecover

func GoRecover(name string, log *logx.Logger, fn func())

GoRecover spawns fn in a new goroutine with one-shot panic recovery (no restart).

func Loop

func Loop(ctx context.Context, name string, log *logx.Logger, fn func(context.Context))

Loop runs fn in the current goroutine with panic containment and restart. On panic: logs Error with worker name + stack, waits loopRestartDelay (respecting ctx cancellation), then restarts fn. If fn returns normally or ctx is cancelled during delay, Loop exits.

func Recover

func Recover(name string, log *logx.Logger, fn func())

Recover runs fn with one-shot panic recovery and error log (no restart).

Types

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager 统一装配后台任务：顺序启动、反向排空、panic 捕获（进程不崩）。 单次生命周期：StartAll/Shutdown 各只允许一次，重启需重建 Manager——复位 started 是伪修复（worker 层 startOnce 均不复位，热重启是伪需求）。

func New

func New(log *logx.Logger) *Manager

func (*Manager) Go

func (m *Manager) Go(ctx context.Context, name string, fn func(ctx context.Context))

Go 托管命名 goroutine：panic 捕获 + Warn（含栈），进程不崩。 边界（不引入"panic 后回调/重启"抽象）：唯一用户 http-server 的 ListenAndServe 错误路径已有 fatalf 兜底、handler panic 由 net/http 内置 recover 兜底返回 500——回调无消费者。m.log==nil 时静默（New 恒注入， 现状全调用点恒非 nil）。

func (*Manager) Register

func (m *Manager) Register(ws ...Worker) error

Register 追加 worker；StartAll 已开始（started 置位）后调用返回错误—— 否则 worker 永不经 Start 却会在 Shutdown 被 Close。返回值可忽略 （main.go 调用点仅位于 StartAll 之前，恒成功）。

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown 反向顺序 Close（后注册先关），收集并返回首个错误；随后等待 Go 托管的 goroutine 全部退出（复用传入 ctx 限时——预算耗尽 Warn 不阻塞退出； 唯一用户 http-server 的退出已由调用方停机链保证，Wait 不引入新阻塞点）。 串行持锁排空是固有属性：单 Close 阻塞压缩后续排空预算，可接受。Go 必须在 Shutdown 之前调用（单次生命周期契约，与 WaitGroup 用法一致）。

func (*Manager) StartAll

func (m *Manager) StartAll(ctx context.Context) error

StartAll 按注册顺序启动；任一失败则已启动者与失败者自身（可能已部分启动 资源）反向 Close 后返回错误。启动期间不持 Manager 锁：并发 Register 要么 进入快照、要么在 started 置位后报错——Start 内回调 Register 不再死锁。 不加启动超时：已证实现状无阻塞 Start，超时属行为新增。

type Worker

type Worker interface {
	Name() string
	Start(ctx context.Context) error
	Close(ctx context.Context) error
}

Worker 是后台任务统一契约：Start 非阻塞启动内部 goroutine，Close 排空/释放。 两者必须幂等；Close 在未 Start 时也必须安全。