Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tomwright/grace
Easy graceful shutdowns in your go applications.
https://github.com/tomwright/grace
graceful graceful-shutdown gracefully runner runners shutdown
Last synced: 20 days ago
JSON representation
Easy graceful shutdowns in your go applications.
- Host: GitHub
- URL: https://github.com/tomwright/grace
- Owner: TomWright
- License: mit
- Created: 2021-01-27T19:36:15.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-04-14T11:07:41.000Z (over 3 years ago)
- Last Synced: 2024-10-03T19:43:17.493Z (about 1 month ago)
- Topics: graceful, graceful-shutdown, gracefully, runner, runners, shutdown
- Language: Go
- Homepage:
- Size: 20.5 KB
- Stars: 6
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://goreportcard.com/report/github.com/TomWright/grace)
[](https://pkg.go.dev/github.com/tomwright/grace)
[](https://codecov.io/gh/TomWright/grace)
# grace
Easy graceful shutdowns in your go applications.
## Table of Contents
- [Usage](#usage)
- [Quickstart](#quickstart)
- [Runners](#runners)
- [Pre-made Runners](#pre-made-runners)
- [Triggering Shutdowns](#triggering-shutdowns)
## Usage
First import the module:
```bash
go get github.com/tomwright/grace
```
## Quickstart
```go
package main
import (
"context"
"github.com/tomwright/grace"
"time"
)
type myRunner struct {
}
func (mr *myRunner) Run(ctx context.Context) error {
// Block until we are told to shutdown or until all work is done.
<-ctx.Done()
return nil
}
func main() {
// Initialise grace.
g := grace.Init(context.Background())
// The following runners are equivalent.
runnerA := &myRunner{}
runnerB := grace.RunnerFunc(func(ctx context.Context) error {
// Block until we are told to shutdown or until all work is done.
<-ctx.Done()
return nil
})
// Run both runners.
g.Run(runnerA)
g.Run(runnerB)
go func() {
// Manually shutdown after 2.5 seconds.
// Alternatively leave this out and rely on os signals to shutdown.
<-time.After(time.Millisecond * 2500)
g.Shutdown()
}()
// Optionally wait for the shutdown signal to be sent.
<-g.Context().Done()
// Wait for all Runners to end.
g.Wait()
}
```
## Options
Grace allows you to modify the way it is initialised using `InitOption`s.
```go
g := grace.Init(
context.Background(),
grace.InitOptionFn(func(g *grace.Grace) {
g.LogFn = log.Printf
g.ErrHandler = func(err error) bool {
g.LogFn("something terrible went wrong: %s", err.Error())
return true
}
})
)
```
## Runners
Grace implements logic to execute and gracefully shutdown any number of `Runner`s.
Each runner must react when the given contexts `Done` channel is closed.
A runner must implement the `Runner` interface. It can do this by implementing the `Run(context.Context) error` func, or by passing a func to `RunnerFunc()`.
### Pre-made Runners
Grace doesn't provide any runners in this module in order to reduce forced dependencies... instead please import the required modules below.
Implemented your own runner that you want to share? Raise a PR!
- [HTTP Server](https://github.com/TomWright/gracehttpserverrunner)
- [GRPC Server](https://github.com/TomWright/gracegrpcserverrunner)
- [Sarama Consumer + Producer](https://github.com/TomWright/gracesarama)
## Triggering Shutdowns
Shutdowns can be triggered in a number of ways:
1. `SIGKILL` will immediately terminate the application using `os.Exit(1)`.
2. `SIGINT` or `SIGTERM` will trigger a graceful shutdown. Sending 2 or more of these will immediately exit the application using `os.Exit(1)`.
3. Calling `Shutdown()` on a grace instance will start a graceful shutdown.
4. Cancelling the context you gave to grace will start a graceful shutdown.