README
¶
Shutdown Module
The Shutdown Module provides functionality for graceful application shutdown in Go applications. It helps ensure that applications terminate cleanly, allowing resources to be properly released and pending operations to complete.
Features
- Signal Handling: Captures OS termination signals (SIGINT, SIGTERM, SIGHUP)
- Context Cancellation: Supports shutdown via context cancellation
- Timeout Management: Applies timeouts to prevent hanging during shutdown
- Multiple Signal Handling: Forces exit if a second signal is received during shutdown
- Error Propagation: Returns errors from shutdown operations
- Logging Integration: Comprehensive logging of shutdown events
Installation
go get github.com/abitofhelp/servicelib/shutdown
Quick Start
See the Basic Usage example for a complete, runnable example of how to use the Shutdown module.
API Documentation
Graceful Shutdown
The GracefulShutdown function waits for termination signals and calls the provided shutdown function.
Basic Usage
See the Basic Usage example for a complete, runnable example of how to implement graceful shutdown.
Programmatic Shutdown
The SetupGracefulShutdown function sets up a goroutine that will handle graceful shutdown, allowing for both signal-based and programmatic shutdown initiation.
Programmatic Shutdown Initiation
See the Programmatic Shutdown example for a complete, runnable example of how to implement programmatic shutdown.
Multiple Resource Shutdown
When shutting down an application with multiple resources, it's important to shut them down in the correct order.
Shutting Down Multiple Resources
See the Multiple Resource example for a complete, runnable example of how to shut down multiple resources in the correct order.
Shutdown Function Signature
The shutdown function passed to the shutdown module should have the following signature:
// Example of a shutdown function
package example
// ShutdownFunc is a function that performs shutdown operations
type ShutdownFunc func() error
Best Practices
-
Resource Ordering: Close resources in the reverse order they were created.
-
Timeouts: Set appropriate timeouts for shutdown operations to prevent hanging.
-
Logging: Log the beginning and completion of each shutdown step.
-
Error Handling: Properly handle and log errors during shutdown, but continue shutting down other resources.
-
Signal Handling: Be prepared to handle multiple termination signals.
-
Context Usage: Use contexts with timeouts for shutdown operations.
-
Graceful Termination: Allow in-flight operations to complete before shutting down.
-
Health Checks: Update health check status during shutdown to prevent new requests.
-
Dependency Management: Consider dependencies between resources when ordering shutdown.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package shutdown provides functionality for graceful application shutdown.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GracefulShutdown ¶
func GracefulShutdown(ctx context.Context, logger *logging.ContextLogger, shutdownFunc func() error) error
GracefulShutdown waits for termination signals and calls the provided shutdown function. It handles OS signals (SIGINT, SIGTERM, SIGHUP) and context cancellation to trigger graceful shutdown. It also handles multiple signals, forcing exit if a second signal is received during shutdown. A default timeout of 30 seconds is applied to the shutdown function to prevent hanging.
Parameters:
- ctx: Context that can be cancelled to trigger shutdown
- logger: Logger for recording shutdown events
- shutdownFunc: Function to execute during shutdown
Returns:
- The error from the shutdown function, if any
func SetupGracefulShutdown ¶
func SetupGracefulShutdown(ctx context.Context, logger *logging.ContextLogger, shutdownFunc func() error) (context.CancelFunc, <-chan error)
SetupGracefulShutdown sets up a goroutine that will handle graceful shutdown. It creates a new context with cancellation and starts a background goroutine that calls GracefulShutdown. This allows for both signal-based and programmatic shutdown initiation.
Parameters:
- ctx: Parent context for the shutdown context
- logger: Logger for recording shutdown events
- shutdownFunc: Function to execute during shutdown
Returns:
- A cancel function that can be called to trigger shutdown programmatically
- A channel that will receive any error that occurs during shutdown
Types ¶
This section is empty.
Source Files