Documentation
¶
Overview ¶
Package xshutdown coordinates graceful shutdown of an application.
A Manager owns a cancelable context. Children derive from it via Context or Derive, so canceling the Manager cascades through the context tree the same way context cancellation always does. On top of that signal, a Manager can track in-flight work (Go) and run cleanup callbacks (Register, RegisterFnErr) on shutdown, draining everything within a configurable timeout.
There is no global state: create a Manager with New and pass it where needed, either concretely or behind the Shutdowner interface.
Index ¶
- Variables
- type Controller
- type Manager
- func (m *Manager) Context() context.Context
- func (m *Manager) Derive() (context.Context, context.CancelFunc)
- func (m *Manager) Done() <-chan struct{}
- func (m *Manager) Go(fn func(ctx context.Context))
- func (m *Manager) Register(cancels ...context.CancelFunc)
- func (m *Manager) RegisterFnErr(fns ...func(ctx context.Context) error)
- func (m *Manager) Run() error
- func (m *Manager) Stop() error
- func (m *Manager) Wait(ch chan struct{}) error
- func (m *Manager) WaitSignal(ch chan os.Signal) error
- type Option
- type Registrar
- type Shutdowner
Constants ¶
This section is empty.
Variables ¶
var ErrShutdownTimeout = errors.New("xshutdown: timeout waiting for tasks")
ErrShutdownTimeout is returned by Stop when tracked Go tasks do not finish within the configured timeout.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller interface {
Done() <-chan struct{}
Stop() error
Wait(ch chan struct{}) error
WaitSignal(ch chan os.Signal) error
Run() error
}
Controller is the drive side: accept it where shutdown is triggered or awaited (typically main).
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager coordinates shutdown for a context subtree.
func New ¶
New returns a Manager whose context derives from parent. A nil parent is treated as context.Background.
func (*Manager) Context ¶
Context returns the Manager's context. Derive children from it so they cancel when the Manager stops.
func (*Manager) Derive ¶
func (m *Manager) Derive() (context.Context, context.CancelFunc)
Derive returns a child context and its cancel. The child cancels on its own cancel or when the Manager stops (via the context tree).
func (*Manager) Done ¶
func (m *Manager) Done() <-chan struct{}
Done reports shutdown, equivalent to m.Context().Done().
func (*Manager) Go ¶
Go runs fn in a tracked goroutine. fn should observe ctx and return when it is canceled; Stop waits for all such goroutines (bounded by WithTimeout). Calls after shutdown begins still run but are not tracked.
func (*Manager) Register ¶
func (m *Manager) Register(cancels ...context.CancelFunc)
Register adds cancel functions run on Stop, in registration order. Use it for contexts that do not derive from this Manager's context.
func (*Manager) RegisterFnErr ¶
RegisterFnErr adds cleanup callbacks run on Stop after Go tasks drain. Each receives the shutdown context (carrying the WithTimeout deadline); returned errors are joined into Stop's result.
func (*Manager) Run ¶
Run installs a handler for the configured signals (SIGINT and SIGTERM by default), blocks until one arrives, then calls Stop and returns its result.
func (*Manager) Stop ¶
Stop shuts down: optionally wait WithPreStopDelay, cancel the context, run registered cancels, drain Go tasks within the timeout, then run RegisterFnErr cleanups. It is idempotent; the first call's result is returned to all callers. The error joins any cleanup errors with ErrShutdownTimeout if draining timed out.
type Option ¶
type Option func(*Manager)
Option configures a Manager.
func WithErrorHandler ¶
WithErrorHandler sets a callback invoked for every shutdown error as it happens: each cleanup failure and ErrShutdownTimeout. Errors are still joined into Stop's result regardless.
func WithForceExit ¶
WithForceExit makes Stop call os.Exit(code) if Go tasks do not drain within the timeout, instead of running cleanups against an expired deadline. It is a hard backstop against a hung drain; pair with WithTimeout.
func WithPreStopDelay ¶
WithPreStopDelay makes Stop wait d before canceling the context, leaving in-flight work running. Use it so a load balancer or service mesh can deregister the instance before connections drain (e.g. Kubernetes SIGTERM).
func WithSignals ¶
WithSignals sets the OS signals Run listens for. Defaults to SIGINT and SIGTERM when unset.
func WithTimeout ¶
WithTimeout bounds shutdown: Stop waits at most d for Go tasks to finish and passes a context with that deadline to RegisterFnErr callbacks. A value <= 0 (the default) waits indefinitely.
type Registrar ¶
type Registrar interface {
Context() context.Context
Derive() (context.Context, context.CancelFunc)
Register(cancels ...context.CancelFunc)
RegisterFnErr(fns ...func(ctx context.Context) error)
Go(fn func(ctx context.Context))
}
Registrar is the register side: accept it in components that derive contexts and register their own cleanup or tracked work.
type Shutdowner ¶
type Shutdowner interface {
Registrar
Controller
}
Shutdowner is the full contract implemented by Manager, composing Registrar and Controller.