Structured concurrency and resource lifetimes for Go: a tree of scopes that
own goroutines, io.Closers and child scopes, a bounded queue whose
behaviour when full is chosen up front, and newest-value-wins mailboxes.
- Standard library only, tests included.
- Every goroutine started with
Gois joined; panics become errors with the task name and stack. Closenever blocks and runs no user code;Waitis bounded by a context.- No background goroutines: the package starts only the task goroutines,
at most one goroutine per scope while it closes its resources, and the
context.AfterFunccallback of a root scope whose parent context ends.
go get github.com/djylb/lifecycle
Requires Go 1.26 or later.
s := lifecycle.New(ctx, lifecycle.CancelOnError())
ln, err := net.Listen("tcp", addr)
if err != nil {
return err
}
s.Add(ln) // closed when the scope closes
s.Go("accept", func(ctx context.Context) error {
for {
c, err := ln.Accept()
if err != nil {
return err // reported unless the scope is already closing
}
conn, err := s.Child("conn", lifecycle.Isolate(logError))
if err != nil {
c.Close()
return err
}
conn.Add(c)
conn.Go("serve", func(ctx context.Context) error { return serve(ctx, c) })
}
})
// Later, on shutdown:
s.Close(nil)
waitCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
err = s.Wait(waitCtx) // errors.Is(err, lifecycle.ErrNotFinished) on timeoutEvery scope is created with an error policy, and there is no default:
| Policy | A task error... |
|---|---|
CancelOnError() |
closes the scope; Wait returns it |
Isolate(handler) |
goes to handler; the scope keeps running |
Policies are refined with two options:
.Propagate()on a child's policy hands the child's result, when it finishes with an error, to the parent's policy like a task error. Without it a child's errors stay in the child..Expected(fn)decides which errors are a normal exit once the scope is closing. The default,IsExpectedExit, acceptscontext.Canceled,ErrClosed,ErrQueueClosedandnet.ErrClosed; an error matching the close cause is always expected. Expected errors are not reported; panics always are.
For a batch of work, Run waits for every task, then closes the scope and
returns the first error:
err := lifecycle.Run(ctx, func(s *lifecycle.Scope) error {
for _, u := range urls {
s.Go(u, func(ctx context.Context) error { return fetch(ctx, u) })
}
return nil
})CloseWhenIdle is the same behaviour for any scope: it closes once no task
and no child is left.
Closing a scope:
- marks it and its whole subtree closed and cancels their contexts before
Closereturns; from then onGo,AddandChildreturnErrClosed; - closes resources in reverse order of
Add, children's resources before the parent's; errors and panics ofClosemethods are joined into the result; - does not wait for tasks:
Waitdoes, and returns once every task of the subtree has returned and every resource is closed.
Add on a closed scope closes the resource at once and returns
ErrClosed, so a resource handed to a scope is never leaked. Add also
returns a function that takes the resource back without closing it.
q, err := lifecycle.NewQueue(lifecycle.QueueConfig[*Job]{
Capacity: 256,
Full: lifecycle.DropOldest,
OnDrop: (*Job).Release,
})Full |
Push on a full queue |
|---|---|
Reject |
returns ErrFull |
DropOldest |
removes the oldest item, passes it to OnDrop, adds the new |
Block |
waits up to BlockTimeout and while the context lasts |
Close stops new pushes and wakes every waiter; queued items remain
available to Pop until the queue is empty, then Pop returns
ErrQueueClosed. Drain removes the rest. Stats reports pushed,
dropped, rejected and waited counts. Push and Pop do not allocate, apart
from the timer of a Block push that has to wait with a BlockTimeout.
For state where only the newest value matters, such as configuration or health updates:
cfg := lifecycle.NewLatest(lifecycle.LatestConfig[*Config]{})
cfg.Set(c) // never blocks; replaces a value not taken yet
c, missed, err := cfg.Wait(ctx) // missed: values overwritten since the last WaitKeyedLatest keeps the newest value per key for a bounded number of keys:
h, err := lifecycle.NewKeyedLatest(lifecycle.KeyedLatestConfig[string, Health]{
Capacity: 1024,
Full: lifecycle.Reject, // or DropOldest (evicts the oldest key) or Block
})
h.Set(ctx, "peer-1", Up)
peer, state, err := h.Pop(ctx)Keys come out in the order they became pending; a Set on a pending key
replaces its value in place without moving it and never hits the full
policy, which applies only to new keys. OnDrop receives every value that
is overwritten or evicted before it was taken (required with
DropOldest), outside any lock. Close, Drain, Stats, ErrFull and
ErrQueueClosed behave as for Queue. Set, Wait and Pop do not
allocate, apart from the timer of a Block set that has to wait with a
BlockTimeout.
func TestMain(m *testing.M) { lifecycletest.VerifyMain(m) } // goroutine leak check
func TestServer(t *testing.T) {
err := lifecycletest.RunCycle(t, 5*time.Second, func(s *lifecycle.Scope) error {
return startServer(s) // start → close → wait → empty → no leaks
})
if err != nil {
t.Fatal(err)
}
}CheckGoroutines(t) checks a single test, AssertEmpty(t, s) a scope
tree, and Leaks exposes the stack-dump based check itself.
Apache License 2.0