A universal mechanism to manage goroutine lifecycles
Switch branches/tags
Nothing to show
Clone or download
Latest commit 6934b12 Mar 8, 2018
Permalink
Failed to load latest commit information.
.gitignore Initial commit Nov 13, 2017
.travis.yml Initial commit (#1) Nov 13, 2017
LICENSE Initial commit Nov 13, 2017
README.md README.md: clarify wording Mar 8, 2018
example_test.go Rename to run (#2) Nov 13, 2017
group.go Rename to run (#2) Nov 13, 2017
group_test.go Rename to run (#2) Nov 13, 2017

README.md

run

GoDoc Build Status Go Report Card Apache 2 licensed

run.Group is a universal mechanism to manage goroutine lifecycles.

Create a zero-value run.Group, and then add actors to it. Actors are defined as a pair of functions: an execute function, which should run synchronously; and an interrupt function, which, when invoked, should cause the execute function to return. Finally, invoke Run, which concurrently runs all of the actors, waits until the first actor exits, invokes the interrupt functions, and finally returns control to the caller only once all actors have returned. This general-purpose API allows callers to model pretty much any runnable task, and achieve well-defined lifecycle semantics for the group.

run.Group was written to manage component lifecycles in func main for OK Log. But it's useful in any circumstance where you need to orchestrate multiple goroutines as a unit whole. Click here to see a video of a talk where run.Group is described.

Examples

context.Context

ctx, cancel := context.WithCancel(context.Background())
g.Add(func() error {
	return myProcess(ctx, ...)
}, func(error) {
	cancel()
})

net.Listener

ln, _ := net.Listen("tcp", ":8080")
g.Add(func() error {
	return http.Serve(ln, nil)
}, func(error) {
	ln.Close()
})

io.ReadCloser

var conn io.ReadCloser = ...
g.Add(func() error {
	s := bufio.NewScanner(conn)
	for s.Scan() {
		println(s.Text())
	}
	return s.Err()
}, func(error) {
	conn.Close()
})

Comparisons

Package run is somewhat similar to package errgroup, except it doesn't require actor goroutines to understand context semantics.

It's somewhat similar to package tomb.v1 or tomb.v2, except it has a much smaller API surface, delegating e.g. staged shutdown of goroutines to the caller.