shutdown

func AddHandler ¶

func AddHandler(handler Handler) error

AddHandler registers a new shutdown handler.

A handler is a function that will be executed when the application is shutting down, either due to a system signal or a call to Shutdown()/Exit().

How it works:

1. The manager's state is checked:

• If shutdown has not started yet, the handler is added to the list.

• If shutdown is already in progress, adding a handler is not allowed and an error is returned.

  2. All registered handlers will be called during shutdown. They receive the root context and an exit code, allowing services to gracefully stop, release resources, and handle any cleanup or errors.

Constraints:

- Handlers can only be added before shutdown starts. - Any attempts to add handlers after shutdown has begun will fail.

Example:

err := shutdown.AddHandler(func(ctx context.Context, code int) error {
    log.Println("Closing database connection...")
    // perform cleanup
    return nil
})
if err != nil {
    log.Fatal(err)
}

func Context ¶ added in v0.7.0

func Context() context.Context

Context returns the root shutdown-aware context managed by this manager.

This function provides access to the application's root context, which is automatically canceled when the application begins shutting down. Using this context allows goroutines, workers, and services to detect shutdown events and stop gracefully.

How it works:

1. Checks if a shutdown context has been initialized:

• If yes, returns the stored context.
• If no, returns a default background context to ensure the caller always gets a valid context. 2. The returned context can be used anywhere in the application where a cancellable context is needed.

Constraints:

- The returned context is read-only; it should not be re-assigned or replaced. - The context may be canceled automatically during shutdown.

Example:

select {
case <-shutdown.Context().Done():
    // Shutdown signal received, stop work gracefully
default:
    // Continue normal operation
}

func Exit ¶ added in v0.7.0

func Exit(code int) int

Exit initiates the application shutdown process with the specified exit code and returns the resulting exit code once shutdown is complete.

This function performs the following steps:

1. Initiates a graceful shutdown via Shutdown(code), notifying all registered shutdown handlers and cancelling the root context.
2. Blocks the current goroutine until the shutdown process completes.
3. Returns the final exit code to the caller.

Exit does NOT terminate the process itself. It is intended to be used as a convenience helper for initiating shutdown and propagating the exit code to the application entry point.

Important:

• Exit blocks until all shutdown handlers have finished executing.
• The caller is responsible for performing the actual process termination (for example, by calling os.Exit with the returned code).

Example:

func main() {
    code := shutdown.Exit(shutdown.ExitOK)
    os.Exit(code)
}

func NewContext ¶ added in v0.8.0

func NewContext() (context.Context, error)

NewContext creates a root, shutdown-aware context for the entire program.

In any Go application, the root context serves as the base for all other derived contexts. It is typically used to propagate cancellation signals and deadlines across multiple goroutines and services. `NewContext` ensures that the root context is properly initialized and protected from multiple concurrent creations.

This function wraps `WithContext(context.Background())` and returns a cancelable context that will be automatically canceled when the application initiates a shutdown, either manually via `Shutdown()`/`Exit()` or due to system signals (e.g., SIGINT, SIGTERM). Using this root context as the base for all other contexts ensures consistent handling of shutdown across the program.

Example:

ctx, err := shutdown.NewContext()
if err != nil {
    panic(err)
}
// pass `ctx` to servers, workers, or any long-running routines

By standardizing the creation of a root shutdown context, the application can gracefully cancel all operations and clean up resources consistently when shutting down.

func NewExitReason ¶ added in v0.12.0

func NewExitReason(code int, errs ...error) error

NewExitReason creates a new program termination reason with the specified exit code.

ExitReason represents a reason for program termination. It can wrap underlying errors (if provided) and associates them with a machine-readable exit code. This is useful for CLI applications or services where the process exit code matters (for orchestration, CI/CD, or supervisors).

The underlying errors `errs` can be omitted if you only want to signal an exit code without providing actual error messages.

Example:

// Exit with a software error and a descriptive message
return NewExitReason(ExitSoftware, fmt.Errorf("failed to initialize database"))

// Exit with just a code, no underlying error
return NewExitReason(ExitUnavailable)

func ParseExitReason ¶ added in v0.12.0

func ParseExitReason(e error) (int, bool)

ParseExitReason extracts the exit code and error presence from a wrapped ExitReason.

This function recursively unwraps the provided error `e` looking for ExitReason instances. It returns two values:

• code: the most relevant exit code found (defaults to ExitGeneralError if none found)
• hasErr: true if there is an actual underlying error, false if the ExitReason was just signaling a code

ParseExitReason is intended for CLI applications or services that need to translate error chains into appropriate exit codes for process termination.

Example usage:

// Simple case: just an ExitReason with a code
reason := NewExitReason(ExitUnavailable)
code, hasErr := ParseExitReason(reason)
fmt.Println(code, hasErr) // Output: ExitUnavailable, false
fmt.Println(reason.Error()) // Output: exit code: 69

// ExitReason wrapping an underlying error
reason = NewExitReason(ExitSoftware, fmt.Errorf("failed to initialize database"))
code, hasErr = ParseExitReason(reason)
fmt.Println(code, hasErr) // Output: ExitSoftware, true
fmt.Println(reason.Error()) // Output: failed to initialize database

// Nested ExitReasons: inner ExitReason can be preserved
reason1 := NewExitReason(ExitUnavailable, fmt.Errorf("reason1"))
reason2 := NewExitReason(ExitSoftware, fmt.Errorf("reason2: %w", reason1))
code, hasErr = ParseExitReason(reason2)
fmt.Println(code, hasErr) // Output: ExitUnavailable, true
fmt.Println(reason2.Error()) // Output: reason2: reason1

// No ExitReason in chain: defaults to general error
err := fmt.Errorf("just a normal error")
code, hasErr = ParseExitReason(err)
fmt.Println(code, hasErr) // Output: ExitGeneralError, true
fmt.Println(err.Error()) // Output: just a normal error

Use this function whenever you need a single exit code for the process while still capturing whether there was an actual error message to log or display.

func Recover ¶ added in v0.9.0

func Recover()

Recover intercepts panics that occur in the application, logs them, and initiates a graceful shutdown.

This function is used to protect the application from uncontrolled panics. If a panic occurs in any goroutine or part of the code, calling Recover() allows you to:

• capture error information and the stack trace,
• gracefully shut down the application via Exit() with a specific error code.

How it works:

1. Checks whether a panic has occurred in the current goroutine using the built-in recover() function. 2. If a panic is detected:

• Logs a message including the panic details and stack trace.
• Calls Exit() with a predefined panic exit code (ExitPanic) to terminate the application gracefully.

Example:

func main() {
    defer shutdown.Recover()

    // main application logic
    runServer()
}

func SetDefaultManager ¶ added in v0.11.0

func SetDefaultManager(m Manager) error

SetDefaultManager replaces the global default shutdown manager.

This function is intended mainly for testing or special scenarios where you need to provide a custom shutdown manager instead of the default one.

How it works:

1. It checks the current lifecycle state of the default manager:

• If the manager has not yet been initialized, the custom manager is set.
• If the manager is already running or shutdown has started, the call fails with an error. 2. After successfully setting the manager, it becomes the global default for all subsequent shutdown operations.

Constraints:

- Must be called before any call to Default(). - Cannot replace the manager after shutdown has started.

Example:

err := shutdown.SetDefaultManager(customMgr)
if err != nil {
    log.Fatal("failed to set custom shutdown manager:", err)
}

func SetShutdownTimeout ¶ added in v0.11.0

func SetShutdownTimeout(t time.Duration)

SetShutdownTimeout sets the maximum duration allowed for shutdown handlers to complete.

By default, each registered shutdown handler has a fixed amount of time to finish its work before being considered timed out. This function allows you to override that default timeout for the current shutdown manager.

How it works:

1. Sets the internal `timeout` used by the manager when executing shutdown handlers. 2. All subsequent calls to shutdown will use this new timeout value. 3. If handlers do not complete within the timeout, they are canceled, and a warning is logged.

Example:

// Allow handlers up to 5 seconds to complete
shutdown.SetShutdownTimeout(5 * time.Second)

Important:

- This timeout affects all handlers added before and after the call. - Should be called before triggering Shutdown/Exit for predictable behavior.

func Shutdown ¶

func Shutdown(code int)

Shutdown initiates program termination with the specified exit code.

This function signals the manager that the application should shut down. It **does not block** execution at the call site — shutdown proceeds in the background, including execution of all registered shutdown handlers (graceful shutdown). The exit code will be used when the program finally terminates.

How it works:

1. Sends the exit code to the manager's internal channel. 2. The manager, in a separate goroutine, starts the graceful shutdown process:

• cancels the root context,
• runs all registered shutdown handlers,
• exits the program with the specified code.

Constraints:

- Handlers may take some time to complete — shutdown proceeds asynchronously. - If the channel is blocked, the exit code might not be sent, and a warning is logged.

Example:

// Initiate shutdown with exit code 0 (shutdown.ExitOK)
shutdown.Shutdown(shutdown.ExitOK)
// Program execution continues; graceful shutdown runs in parallel

func Wait ¶

func Wait() int

Wait blocks the current goroutine until a shutdown signal is received and returns the resulting exit code.

This function keeps the application running until a shutdown is initiated. It waits for one of the following events:

• A call to Shutdown() or Exit() within the application code.
• Receiving an OS termination signal (SIGINT, SIGTERM, SIGQUIT).

How it works:

1. The function blocks until an exit code is sent to the internal exit channel.
2. Once the code is received, it is returned to the caller.
3. The function does NOT terminate the process itself.

Any registered shutdown handlers are executed before the exit code becomes available, as Shutdown/Exit triggers them beforehand.

It is the caller’s responsibility to decide how to handle the returned exit code (for example, by passing it to os.Exit in the application's entry point).

Example:

func main() {
    // Setup root context
    ctx, _ := shutdown.NewContext()

    // Add shutdown handlers
    shutdown.AddHandler(func(ctx context.Context, code int) error {
        log.Println("Closing database connections")
        return nil
    })

    // Wait for shutdown signal and handle exit code explicitly
    code := shutdown.Wait()
    os.Exit(code)
}

func WithContext ¶ added in v0.7.0

func WithContext(parent context.Context) (context.Context, error)