workgroup

README

Heptio Workgroup

Maintainers: Heptio

Overview

Workgroup is a small utility to manage the lifetime of a set of related goroutines.

Examples

http.Serve

var g workgroup.Group

g.Add(func(stop <-chan struct{}) error {
	l, err := net.Listen("tcp", ":80") // listen on port 80
        if err != nil {
                return err
        }

        go func() {
                <-stop // close listener on stop request
                l.Close()
        }()
        return http.Serve(l, mux)
})
g.Run()

Related work

workgroup.Group is heavily inspired by prior art including oklog's run.Group and Gustavo Niemeyer's tomb packages.

Contributing

Thanks for taking the time to join our community and start contributing!

Bug reports are most welcome, but with the exception of #5, this project is closed.

• Please familiarize yourself with the Code of Conduct before contributing.
• See CONTRIBUTING.md for information about setting up your environment, the workflow that we expect, and instructions on the developer certificate of origin that we require.

Changelog

See the list of releases to find out about feature changes.

Documentation

Overview

workgroup provides a mechanism for controlling the lifetime of a set of related goroutines.

Index

• type Group
  • func (g *Group) Add(fn func(<-chan struct{}) error)
  • func (g *Group) Run() error

Examples

• Group.Run
• Group.Run (MultipleListeners)
• Group.Run (WithShutdown)

Types

type Group

type Group struct {
	// contains filtered or unexported fields
}

A Group manages a set of goroutines with related lifetimes. The zero value for a Group is fully usable without initalisation.

func (*Group) Add

func (g *Group) Add(fn func(<-chan struct{}) error)

Add adds a function to the Group. The function will be exectuted in its own goroutine when Run is called. Add must be called before Run.

func (*Group) Run

func (g *Group) Run() error

Run exectues each function registered via Add in its own goroutine. Run blocks until all functions have returned. The first function to return will trigger the closure of the channel passed to each function, who should in turn, return. The return value from the first function to exit will be returned to the caller of Run.

Example

package main

import (
	"fmt"
	"time"

	"github.com/heptio/workgroup"
)

func main() {
	var g workgroup.Group

	a := func(stop <-chan struct{}) error {
		defer fmt.Println("A stopped")
		<-time.After(100 * time.Millisecond)
		return fmt.Errorf("timed out")
	}
	g.Add(a)

	b := func(stop <-chan struct{}) error {
		defer fmt.Println("B stopped")
		select {
		case <-stop:
			return nil
		}
	}
	g.Add(b)

	err := g.Run()
	fmt.Println(err)

}

Output:

A stopped
B stopped
timed out

Example (MultipleListeners)

package main

import (
	"fmt"
	"net"
	"net/http"

	"github.com/heptio/workgroup"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprintln(w, "Hello, HTTP!")
	})

	var g workgroup.Group

	// listen on port 80
	g.Add(func(stop <-chan struct{}) error {
		l, err := net.Listen("tcp", ":80")
		if err != nil {
			return err
		}

		go func() {
			<-stop
			l.Close()
		}()
		return http.Serve(l, mux)
	})

	// listen on port 443
	g.Add(func(stop <-chan struct{}) error {
		l, err := net.Listen("tcp", ":443")
		if err != nil {
			return err
		}

		go func() {
			<-stop
			l.Close()
		}()
		return http.Serve(l, mux)
	})

	g.Run()
}

Example (WithShutdown)

package main

import (
	"fmt"
	"time"

	"github.com/heptio/workgroup"
)

func main() {
	var g workgroup.Group

	shutdown := make(chan time.Time)
	g.Add(func(<-chan struct{}) error {
		<-shutdown
		return fmt.Errorf("shutdown")
	})

	g.Add(func(stop <-chan struct{}) error {
		select {
		case <-stop:
			return fmt.Errorf("terminated")
		}
	})

	go func() {
		shutdown <- <-time.After(100 * time.Millisecond)
	}()

	err := g.Run()
	fmt.Println(err)

}

Output:

shutdown