bg

Documentation

Overview

Package bg provides utilities for managing background processes.

Index

• type Group
  • func (g *Group) Add(services ...Service)
  • func (g *Group) Check(callback func(groupIsAlive bool))
  • func (g *Group) Stop()
  • func (g *Group) StopOnSignal(sig ...os.Signal)
  • func (g *Group) Wait() error
• type Service
• type Starter
  • func NewStarter(task Task) Starter
• type Task
• type UnexpectedStop
  • func (u *UnexpectedStop) Error() string
  • func (u *UnexpectedStop) Unwrap() error

Types

type Group

type Group struct {
	// If set, OnShutdown will be called before the Group starts stopping its running services. If the shutdown is
	// caused by an error, that error will be passed as OnShutdown's argument.
	OnShutdown func(err error)
	// contains filtered or unexported fields
}

Group manages a group of services by running them in the background, and stopping them when Stop is called. If any service unexpectedly stops on its own, all other services will also be stopped.

func (*Group) Add

func (g *Group) Add(services ...Service)

Add starts the given services in new goroutines, and adds them to the group.

func (*Group) Check

func (g *Group) Check(callback func(groupIsAlive bool))

Check calls callback with true if all servers are running as expected, or false if the group is shutting down, or has shut down.

It is safe to call Add from within callback. Calls Stop and StopOnSignal will deadlock, as will calls to Wait if the group is still alive.

func (*Group) Stop

func (g *Group) Stop()

Stop calls Service.Stop on all running services, starting with the most recently added service.

func (*Group) StopOnSignal

func (g *Group) StopOnSignal(sig ...os.Signal)

StopOnSignal listens in a new goroutine for the given signals, and calls Stop if and when they are received. If Stop is called manually, the goroutine stops listening and terminates.

Typically, you'll be using an os.Interrupt to catch CTRL+C:

g.StopOnSignal(os.Interrupt)

func (*Group) Wait

func (g *Group) Wait() error

Wait returns when all services have stopped. If Stop was called, the first service to return a non-nil error from its Service.Run will have its error returned from Wait. If a service stopped unexpectedly, its error will be returned, wrapped in UnexpectedStop.

type Service

type Service interface {
	Task

	// Stop should signal the service to shut down gracefully.
	Stop()
}

Service is any Task that can be signalled to stop.

type Starter

type Starter interface {
	// Start starts the task in a new goroutine. It must not be called more than once.
	Start()

	// Wait blocks until the task finishes, and returns its error. Wait can be called before or after Start is called.
	// It can be called multiple times. If called after the task has already finished, it will return the task's error
	// immediately.
	Wait() error
}

Starter is a task that can be started using Start, and then later joined using Wait.

func NewStarter

func NewStarter(task Task) Starter

type Task

type Task interface {
	// Run starts the task, and returns when it finishes.
	Run() error
}

Task is a process that returns an error if it fails.

type UnexpectedStop

type UnexpectedStop struct {
	Service
	Err error
}

func (*UnexpectedStop) Error

func (u *UnexpectedStop) Error() string

func (*UnexpectedStop) Unwrap

func (u *UnexpectedStop) Unwrap() error