Documentation
¶
Overview ¶
Package app provides a managed lifecycle for command-line applications, ensuring graceful shutdown on OS signals.
The Run function is the main entry point. It wraps your application logic, listening for interrupt signals (like SIGINT/SIGTERM) and propagating a cancellation signal via a context. This allows your application to perform cleanup tasks before exiting.
Usage ¶
A typical use case involves starting a server or a worker that needs to shut down cleanly. The Run function handles the signal boilerplate, letting you focus on your application's logic.
func main() {
// Create a logger with a custom level.
logger := log.New(log.WithLevel("debug"))
// Run the application, providing the main logic as a function.
if err := app.Run(func(ctx context.Context) error {
logger.Info("Application logic started")
// Simulate work by waiting for the context to be cancelled.
<-ctx.Done()
// Perform cleanup tasks here.
logger.Info("Performing cleanup before shutdown...")
time.Sleep(500 * time.Millisecond) // Simulate cleanup delay.
return nil
}, app.WithLogger(logger)); err != nil {
logger.Error("Application exited with an error", "error", err)
os.Exit(1)
}
}
Index ¶
Constants ¶
const DefaultTimeout = 10 * time.Second
DefaultTimeout is the default duration to wait for the application to gracefully shut down after receiving a termination signal.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run provides a managed execution environment for a Runnable. It launches the Runnable in a separate goroutine and blocks until it either completes on its own, an OS interrupt signal is caught, or the parent context (if specified via WithContext) is canceled.
Upon receiving a signal, it cancels the context passed to the Runnable and waits for the specified shutdown timeout. The Runnable is expected to honor the context cancellation and perform any necessary cleanup before returning. Run returns any error from the Runnable itself, or an error if the shutdown process times out.
Types ¶
type Option ¶
type Option func(*config)
Option is a function that configures the application runner.
func WithContext ¶
WithContext sets a parent context for the runner. The runner's main context will be a child of this parent. Cancelling the parent context triggers a graceful shutdown. If not set, context.Background() is used as the default parent. A nil value will be ignored.
func WithLogger ¶
WithLogger provides a custom logger for the application runner. If not set, the runner defaults to slog.Default(). A nil value will be ignored.
func WithSignals ¶
WithSignals allows customization of which OS signals trigger a shutdown. If not used, it defaults to SIGTERM and SIGINT.
func WithTimeout ¶
WithTimeout sets a custom timeout for the graceful shutdown process. If the application logic takes longer than this duration to return after a shutdown signal is received, the runner will exit with an error. A negative or zero duration will be ignored, and the DefaultTimeout is used instead.
Source Files