lbry.go/stop/readme.md

# Stop Group

A stop group is meant to help cleanly shut down a component that uses multiple goroutines. 


## The Problem

A shutdown typically works as follows:

- a component receives a shutdown signal
- the component passes the shutdown signal to each outstanding goroutine
- each goroutine stops whatever it is doing and returns
- once all the goroutines have returned, the component does any final cleanup and signals that it is done

There are several gotchas in this process:

- each goroutine must be tracked, so all can be stopped
- the component should not expose implementation details about how many goroutines it uses and how they are managed
- goroutines may be blocked by a read on a channel. they need to be unblocked during shutdown
- goroutines may take a while to finish, and may finish in any order. component shutdown is not complete until all goroutines finish
- using a channel to send the shutdown signal is complicated (doing things in the correct order, closing an already-closed channel, etc)


## The Solution

The solution is a stop group. A stop group is a combination of a `sync.WaitGroup` and a cancelable `context`. Here's how it works:

```
grp := stop.New()
action := func() { ... }
```

All goroutines are started in the start group.

```
grp.Add(1)
go func() {
  defer grp.Done()
  action()
}
```


Any goroutine that may be blocked by a channel read has a simple way of unblocking on shutdown

```
for {
  select {
  case text := <-actionCh:
    fmt.Printf("Got some text: %s", text)
  case <-grp.Ch():
    return
  }
}
```


Shutting down synchronously is easy

```
grp.StopAndWait()
```


## Example

```
type Server struct {
	grp   *stop.Group
}

func NewServer() *Server {
	return &Server{
		grp:     stop.New(),
	}
}

func (s *Server) Shutdown() {
	s.grp.StopAndWait()
}

func (s *Server) Start(address string) error {
	l, err := net.Listen(network, address)
	if err != nil {
		return err
	}
	log.Println("listening on " + address)

	s.grp.Add(1)
	go func() {
		defer s.grp.Done()
		s.listenAndServe(l)
	}()

	s.grp.Add(1)
	go func() {
		defer s.grp.Done()
		for {
			select {
			case <-s.grp.Ch():
				return
			case <-time.Tick(10 * time.Second):
				log.Println("still running")
			}
		}
	}()

	s.grp.Add(1)
	go func() {
		defer s.grp.Done()
		<-s.grp.Ch()
		err := l.Close()
		if err != nil {
			log.Errorln(err)
		}
	}()

	return nil
}


// how this is used

s := NewServer()
log.Println("starting")
s.Start("localhost:1234")
log.Println("started")

// ... do some other things here ...

log.Println("shutting down")
s.Shutdown()
log.Println("shutdown complete")
```