I wrote a tiny library called Grace to gracefully shutdown your application by catching the OS signals using sync.errgroup.
I often find I have invoked one or more persistent blocking methods, and some other method is needed be invoked in another goroutine to tell it to gracefully shut down when an interrupt is received.
For instance, when ListenAndServe() is invoked, Shutdown needs to be called.
This library allows you to start zero or more concurrent goroutines, and trigger a graceful shutdown when an interrupt is received. You can bring your own cleanup function to listen for the context's Done channel to be closed, so it will work flexibly in a variety of scenarios.
For example, you probably only want your cleanup function to close your database connection after you have drained your http connections or grpc connections.
func() error {
//cleanup: on interrupt, shutdown server
<-ctx.Done()
// We received an interrupt signal, shut down.
if err := srv.Shutdown(ctx); err != nil {
// Error from closing listeners, or context timeout:
log.Printf("HTTP server Shutdown error: %v", err)
}
return db.Close()
})
For reference:
- Go
net/httppackage offersShutdownfunction to gracefully shutdown your http server. - Go
database/sqlpackage offersClosefunction to gracefully close the connection to your SQL database. - Google
google.golang.org/grpcpackage offersServer.GracefulStop, stops accepting new connections, and blocks until all the pending RPCs are finished
Alternatively, this library also allows you to invoke zero or more concurrent goroutines with an optional timeout.
Documentation
Installation
go get -u github.com/StevenACoffman/grace
Usage
Simple Run until Interrupt signal received
package main
import (
"log"
"time"
"github.com/StevenACoffman/grace"
)
func main() {
wait, ctx := grace.NewWait()
err := wait.WaitWithFunc(func() error {
ticker := time.NewTicker(2 * time.Second)
for {
select {
case <-ticker.C:
log.Printf("ticker 2s ticked\n")
// testcase what happens if an error occured
//return fmt.Errorf("test error ticker 2s")
case <-ctx.Done():
log.Printf("closing ticker 2s goroutine\n")
return nil
}
}
})
if err != nil {
log.Println("finished clean")
} else {
log.Printf("received error: %v", err)
}
}
Usage with a default timeout:
package main
import (
"log"
"time"
"github.com/StevenACoffman/grace"
)
func main() {
wait, ctx := grace.NewWait()
err := wait.WaitWithTimeoutAndFunc(15*time.Second, func() error {
ticker := time.NewTicker(2 * time.Second)
for {
select {
case <-ticker.C:
log.Printf("ticker 2s ticked\n")
// testcase what happens if an error occured
//return fmt.Errorf("test error ticker 2s")
case <-ctx.Done():
log.Printf("closing ticker 2s goroutine\n")
return nil
}
}
})
if err != nil {
log.Println("finished clean")
} else {
log.Printf("received error: %v", err)
}
}
Usage with cleanup on shutdown
Bring your own cleanup function!
package main
import (
"fmt"
"log"
"net/http"
"time"
"github.com/StevenACoffman/grace"
)
func main() {
wait, ctx := grace.NewWait()
var httpServer *http.Server
err := wait.WaitWithFunc(
func() error {
http.HandleFunc("/", healthCheck)
httpServer = newHTTPServer()
if err := httpServer.ListenAndServe(); err != http.ErrServerClosed {
return err
}
return nil
},
func() error {
//cleanup: on interrupt, shutdown server
<-ctx.Done()
log.Printf("closing http goroutine\n")
return httpServer.Shutdown(ctx)
})
if err != nil {
log.Println("finished clean")
} else {
log.Printf("received error: %v", err)
}
}
func healthCheck(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/plain")
w.Header().Set("Content-Length", "0")
w.WriteHeader(200)
}
func newHTTPServer() *http.Server {
httpServer := &http.Server{
Addr: fmt.Sprintf(":8080"),
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
}
log.Printf("HTTP Metrics server serving at %s", ":8080")
return httpServer
}
Prior Art and Alternatives
This library uses errgroup, but I found a number of other libraries that use other mechanisms:
- death (sync.WaitGroup)
- graceful (context cancellation)
- finish (context + mutexes)
- waitabit (sync.WaitGroup)
- Gist using errgroup
- Gist using GRPC GracefulStop
Comparing them is pretty instructive. I wish I'd used some of their testing techniques!
Top comments (0)