Documentation
¶
Overview ¶
Package signal provides a stateful signal context with introspection and LIFO hooks.
It solves two main problems for CLI applications:
- Distinguishing between SIGINT (soft interrupt) and SIGTERM (hard termination).
- Managing cleanup operations (Hooks) in a reliable, observable way.
Dual Signal Handling ¶
Unlike standard signal.NotifyContext, this package allows configuring SIGINT to initiate a graceful shutdown logic rather than immediate cancellation. Repeated signals can trigger a "Force Exit" (os.Exit(1)) to prevent hung processes.
Lifecycle Hooks ¶
Users can register cleanup functions via Context.OnShutdown. These hooks execution is guaranteed to run in LIFO (Last-In-First-Out) order, simulating `defer`.
Introspection & Visualization ¶
The package implements an "Introspection Pattern". The Context.State method returns a complete snapshot of the configuration, including the Reason why the context was cancelled (e.g., ReasonInterrupt vs ReasonTerminate vs ReasonManualStop).
The MermaidState function can consume this state to generate a visual representation of the lifecycle policy.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MermaidState ¶ added in v1.3.0
MermaidState returns a Mermaid state diagram string representing the lifecycle configuration.
Types ¶
type Context ¶
Context wraps a context and captures the signal that cancelled it.
func NewContext ¶
NewContext creates a context that is cancelled on SIGTERM or SIGINT (standard termination). On the first signal received, it cancels the context to initiate graceful shutdown (if configured). If a second signal is received before the program exits, it performs an immediate os.Exit(1) (if configured).
func (*Context) OnShutdown ¶ added in v1.1.0
func (sc *Context) OnShutdown(f func())
OnShutdown registers a function to be called when the context receives a shutdown signal. Hooks are executed in LIFO (Last-In-First-Out) order, simulating `defer`. Execution happens asynchronously after the context is cancelled. Call Wait() to block until all hooks (including those registered dynamically) have finished.
func (*Context) Signal ¶
Signal returns the signal that caused the context to be cancelled/interrupted, or nil.
type Option ¶ added in v1.1.0
type Option func(*options)
Option is a functional option for configuring signal behavior.
func WithForceExit ¶ added in v1.1.0
WithForceExit configures the threshold of signals required to trigger an immediate os.Exit(1). Set to 0 to disable forced exit. Default is 2.
func WithHookTimeout ¶ added in v1.1.0
WithHookTimeout configures the duration after which a running hook produces a warning log. Default is 5 seconds.
func WithInterrupt ¶ added in v1.1.0
WithInterrupt configures whether SIGINT (Ctrl+C) should cancel the context. Default is true.
type Reason ¶ added in v1.4.0
type Reason string
Reason describes why the context was cancelled.
const ( ReasonNone Reason = "None" ReasonInterrupt Reason = "Interrupt" // SIGINT (Ctrl+C) ReasonTerminate Reason = "Terminate" // SIGTERM ReasonManualStop Reason = "Manual:Stop" // Explicit Stop() call ReasonManualCancel Reason = "Manual:Cancel" // Context Cancel() called ReasonTimeout Reason = "Timeout" // Shutdown timed out )
Source Files