README.md
1# lifecycle
2
3[](https://godoc.org/github.com/joshuarubin/lifecycle) [](https://goreportcard.com/report/github.com/joshuarubin/lifecycle) [](https://codecov.io/gh/joshuarubin/lifecycle) [](https://circleci.com/gh/joshuarubin/lifecycle)
4
5## Overview
6
7`lifecycle` helps manage goroutines at the application level. `context.Context` has been great for propagating cancellation signals, but not for getting any feedback about _when_ goroutines actually finish.
8
9This package works with `context.Context` to ensure that applications don't quit before their goroutines do.
10
11The semantics work similarly to the `go` (`lifecycle.Go`) and `defer` (`lifecycle.Defer`) keywords as well as `sync.WaitGroup.Wait` (`lifecycle.Wait`). Additionally, there are `lifecycle.GoErr` and `lifecycle.DeferErr` which only differ in that they take funcs that return errors.
12
13`lifecycle.Wait` will block until one of the following happens:
14
15- all funcs registered with `Go` complete successfully then all funcs registered with `Defer` complete successfully
16- a func registered with `Go` returns an error, immediately canceling `ctx` and triggering `Defer` funcs to run. Once all `Go` and `Defer` funcs complete, `Wait` will return the error
17- a signal (by default `SIGINT` and `SIGTERM`, but configurable with `WithSignals`) is received, immediately canceling `ctx` and triggering `Defer` funcs to run. Once all `Go` and `Defer` funcs complete, `Wait` will return `ErrSignal`
18- a func registered with `Go` or `Defer` panics. the panic will be propagated to the goroutine that `Wait` runs in. there is no attempt, in case of a panic, to manage the state within the `lifecycle` package.
19
20## Example
21
22Here is an example that shows how `lifecycle` could work with an `http.Server`:
23
24```go
25// At the top of your application
26ctx := lifecycle.New(
27 context.Background(),
28 lifecycle.WithTimeout(30*time.Second), // optional
29)
30
31helloHandler := func(w http.ResponseWriter, req *http.Request) {
32 _, _ = io.WriteString(w, "Hello, world!\n")
33}
34
35mux := http.NewServeMux()
36mux.HandleFunc("/hello", helloHandler)
37
38srv := &http.Server{
39 Addr: ":8080",
40 Handler: mux,
41}
42
43lifecycle.GoErr(ctx, srv.ListenAndServe)
44
45lifecycle.DeferErr(ctx, func() error {
46 // use a background context because we already have a timeout and when
47 // Defer funcs run, ctx is necessarily canceled.
48 return srv.Shutdown(context.Background())
49})
50
51// Any panics in Go or Defer funcs will be passed to the goroutine that Wait
52// runs in, so it is possible to handle them like this
53defer func() {
54 if r := recover(); r != nil {
55 panic(r) // example, you probably want to do something else
56 }
57}()
58
59// Then at the end of main(), or run() or however your application operates
60//
61// The returned err is the first non-nil error returned by any func
62// registered with Go or Defer, otherwise nil.
63if err := lifecycle.Wait(ctx); err != nil {
64 log.Fatal(err)
65}
66```
67
){kind=link}
){kind=link}
){kind=link}