Documentation
¶
Overview ¶
Package apprun 提供实例式常驻服务监督、统一停收和并行排空，依赖标准库与 logit。 Manager 零值默认 30 秒，New 可设置整个停收与排空期限。 Stop 只封闭入口，Wait(ctx) 等待实际工作与收尾，Cancel 必须立即发出取消通知并返回。 全部回调必填，停收可先于 Run；未停收时 Run 返回 nil 视为 ErrUnexpectedExit。
以 HTTP 为例（需导入 context、errors、net/http、time、apprun 和 httpserver）：
server, err := httpserver.New(httpserver.Config{
Addr: ":8888",
}, http.NotFoundHandler())
if err != nil {
return err
}
var manager apprun.Manager
if err := manager.Register(apprun.Service{
Name: "http",
Run: func() error {
err := server.Run()
if errors.Is(err, httpserver.ErrClosed) {
return nil
}
return err
},
Stop: server.Stop,
Wait: server.Wait,
Cancel: server.Cancel,
}); err != nil {
_ = server.Stop()
server.Cancel()
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
return errors.Join(err, server.Wait(ctx))
}
return manager.RunSignals()
Run 的 context 只通知停机，不提前取消业务。收到信号、取消或服务退出后，向全部服务发起 Stop， 并行等待 Wait 与 Run；同一截止时间从停机开始计算，不逐组件重置。已接收的队列工作属于存量。 错误与 panic 保留；超时返回 ErrShutdownTimeout 并取消未完成服务，不再等待业务响应。 Wait 返回错误或 panic 时按未确认排空处理，返回前 Cancel 兜底；超时错误包含未完成服务名与关闭阶段。 无论是否超时，入口随后调用资源栈回收；lifecycle.Stack 默认整体 20 秒，可通过 New 自定义。 资源回收超时须立即退出进程；本包不接管资源栈或调用 os.Exit，不能强杀 goroutine。 登记顺序不提供服务就绪或停机依赖保证；已停收的业务消费者不保证接收在途任务发出的新请求。 RunSignals 订阅 SIGINT/SIGTERM，首次停机后恢复原信号行为；应用只应有一个信号所有者。 SIGKILL/SIGSTOP 不可捕获，SIGHUP/SIGQUIT 保持原行为。回调不得同步等待 Manager.Run 或使用 runtime.Goexit。
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrStarted = errors.New("apprun: manager already started") ErrNilContext = errors.New("apprun: nil context") ErrNoServices = errors.New("apprun: no services registered") ErrInvalidService = errors.New("apprun: invalid service") ErrDuplicateService = errors.New("apprun: duplicate service name") ErrUnexpectedExit = errors.New("apprun: service exited before shutdown") // ErrShutdownTimeout 表示统一停收与排空期限耗尽；尚未结束的回调可能继续执行。 ErrShutdownTimeout = errors.New("apprun: shutdown timeout") )
Functions ¶
This section is empty.
Types ¶
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 并发运行常驻服务，统一停收并并行排空。零值可用，使用后不可复制。 自定义关闭期限须通过 New 设置，创建后不可修改。 登记顺序不代表启动依赖或停机顺序；登记成功的服务由本次 Run 负责停收。
func (*Manager) Run ¶
Run 等待 ctx 取消或任一服务退出，统一停收并在同一个期限内等待全部服务排空。 ctx 只通知管理器，不提前取消业务；预取消也会停收已登记服务，但不启动 Run。 超时通知未完成服务 Cancel 并返回 ErrShutdownTimeout；入口随后有界回收资源并退出。
func (*Manager) RunSignals ¶
RunSignals 使用内部后台 context 显式订阅 SIGINT/SIGTERM，收到信号后按 Run 的协议关闭服务。 首次停机时恢复原有信号行为，使后续中断可直接终止进程；应用只应有一个信号所有者。 不接管 SIGKILL/SIGSTOP；信号处理不覆盖调用前的配置加载和初始化。
type PanicError ¶
PanicError 保存运行或关闭回调的 panic；保留堆栈并通过返回错误交给调用方。
func (*PanicError) Error ¶
func (e *PanicError) Error() string
type Service ¶
type Service struct {
Name string
Run func() error
Stop func() error
Wait func(context.Context) error
Cancel func()
}
Service 描述常驻服务，全部回调必填。Stop 只封闭入口并启动排空，Wait 等待实际工作结束。 Wait 返回 nil 才确认排空；错误或 panic 保留，管理器返回前仍会调用 Cancel 兜底。 Cancel 只发出协作取消通知，必须立即返回；超时不保证任意 Go 任务已经终止。 Stop/Cancel 可先于或并发于 Run，停收后 Run 不得重新启动。Run 不得只启动后台任务就返回。
Source Files