README
¶
Shutdown Manager for Go
A lightweight library to manage graceful shutdowns in Go applications. This package simplifies signal handling, ensuring your application can clean up resources properly and exit gracefully under various conditions.
Features
- Graceful handling of termination signals (
SIGTERM,SIGINT, etc.) - Timeout-based forced exit to prevent stalling
- Double-signal handling for immediate application termination
- Ability to add custom conditions for terminating the application
- No external dependencies
Installation
go get github.com/burik666/shutdown
Usage
Basic usage
func main() {
ctx, ctxCancel := shutdown.Watch(
// Allows pressing Ctrl+C twice to force shutdown
shutdown.WithDoubleSignal(),
// Timeout for graceful shutdown
shutdown.WithTimeout(30*time.Second),
)
defer ctxCancel()
go func() {
// Do something
}()
<-ctx.Done()
// Shutdown and cleanup
}
Custom conditions
func main() {
ctx, ctxCancel := shutdown.Watch(
shutdown.WithWatcher(func(ctx context.Context, ch chan<- error) error {
// If something happens and you need to shut down the application,
// send an error to the channel (ch) to trigger the shutdown process.
ch <- errors.New("shutdown")
// To shut down the application immediately,
// send another error to the channel (ch).
ch <- errors.New("shutdown NOW")
return nil
}),
)
defer ctxCancel()
go func() {
// Do something
}()
<-ctx.Done()
// Shutdown and cleanup
}
For more examples, see the examples directory.
License
The project is licensed under the MIT License.
Documentation
¶
Index ¶
- func Watch(opts ...func(*config)) (context.Context, context.CancelFunc)
- func WithContext(ctx context.Context) func(*config)
- func WithDoubleSignal() func(*config)
- func WithExitFunc(exit func(int)) func(*config)
- func WithForceExitCode(code int) func(*config)
- func WithLog(logFn func(string, ...any)) func(*config)
- func WithSignals(signals ...os.Signal) func(*config)
- func WithTimeout(timeout time.Duration) func(*config)
- func WithTimeoutExitCode(code int) func(*config)
- func WithWatcher(watchers ...func(context.Context, chan<- error) error) func(*config)
- func WithoutLog() func(*config)
- func WithoutSignals() func(*config)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Watch ¶
func Watch(opts ...func(*config)) (context.Context, context.CancelFunc)
Watch starts a shutdown watcher.
Example ¶
package main
import (
"time"
"github.com/burik666/shutdown"
)
func main() {
ctx, ctxCancel := shutdown.Watch(
// Allows pressing Ctrl+C twice to force shutdown
shutdown.WithDoubleSignal(),
// Timeout for graceful shutdown
shutdown.WithTimeout(30*time.Second))
defer ctxCancel()
go func() {
// Do something
}()
<-ctx.Done()
// shutdown and cleanup
}
Output:
func WithContext ¶
WithContext allows passing a context to the Watcher. By default, it uses context.Background.
func WithDoubleSignal ¶
func WithDoubleSignal() func(*config)
WithDoubleSignal allows receiving a second signal to force an exit.
func WithExitFunc ¶
func WithExitFunc(exit func(int)) func(*config)
WithExitFunc allows passing a custom exit function. By default, it uses os.Exit.
func WithForceExitCode ¶
func WithForceExitCode(code int) func(*config)
WithForceExitCode allows setting a custom exit code for forced exits. By default, it uses 1.
func WithSignals ¶
WithSignals allows passing a list of signals to the shutdown process. By default, it listens to os.Interrupt and syscall.SIGTERM.
func WithTimeout ¶
WithTimeout allows setting a timeout for forcing an exit.
func WithTimeoutExitCode ¶
func WithTimeoutExitCode(code int) func(*config)
WithTimeoutExitCode allows setting a custom exit code for timeouts. By default, it uses 1.
func WithWatcher ¶
WithWatcher allows custom watchers to be added to the shutdown process. Each watcher receives the main context and a channel for reporting errors. If a watcher returns an error, the main context is canceled. Sending an error to the channel initiates the shutdown process. Sending a second error triggers an immediate shutdown. The error channel is closed after the watcher completes.
Example ¶
package main
import (
"context"
"errors"
"github.com/burik666/shutdown"
)
func main() {
ctx, ctxCancel := shutdown.Watch(
shutdown.WithWatcher(func(ctx context.Context, ch chan<- error) error {
// If something occurs and you need to shut down the application,
// send an error to the channel (ch) to trigger the shutdown process.
ch <- errors.New("shutdown")
// To shut down the application immediately,
// send another error to the channel (ch).
ch <- errors.New("shutdown NOW")
return nil
}),
)
defer ctxCancel()
go func() {
// Do something
}()
<-ctx.Done()
// Shutdown and cleanup
}
Output:
func WithoutSignals ¶
func WithoutSignals() func(*config)
WithoutSignals disables the default signals.
Types ¶
This section is empty.
Source Files
Directories