tomb

README

Installation and usage

See gopkg.in/tomb.v1 for documentation and usage details.

Documentation

Overview

The tomb package offers a conventional API for clean goroutine termination.

A Tomb tracks the lifecycle of a goroutine as alive, dying or dead, and the reason for its death.

The zero value of a Tomb assumes that a goroutine is about to be created or already alive. Once Kill or Killf is called with an argument that informs the reason for death, the goroutine is in a dying state and is expected to terminate soon. Right before the goroutine function or method returns, Done must be called to inform that the goroutine is indeed dead and about to stop running.

A Tomb exposes Dying and Dead channels. These channels are closed when the Tomb state changes in the respective way. They enable explicit blocking until the state changes, and also to selectively unblock select statements accordingly.

When the tomb state changes to dying and there's still logic going on within the goroutine, nested functions and methods may choose to return ErrDying as their error value, as this error won't alter the tomb state if provided to the Kill method. This is a convenient way to follow standard Go practices in the context of a dying tomb.

For background and a detailed example, see the following blog post:

http://blog.labix.org/2011/10/09/death-of-goroutines-under-control

For a more complex code snippet demonstrating the use of multiple goroutines with a single Tomb, see:

http://play.golang.org/p/Xh7qWsDPZP

Index

• Variables
• type Tomb
  • func (t *Tomb) Dead() <-chan struct{}
  • func (t *Tomb) Done()
  • func (t *Tomb) Dying() <-chan struct{}
  • func (t *Tomb) Err() (reason error)
  • func (t *Tomb) Kill(reason error)
  • func (t *Tomb) Killf(f string, a ...interface{}) error
  • func (t *Tomb) Wait() error

Variables

var (
	ErrStillAlive = errors.New("tomb: still alive")
	ErrDying      = errors.New("tomb: dying")
)

Types

type Tomb

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

A Tomb tracks the lifecycle of a goroutine as alive, dying or dead, and the reason for its death.

See the package documentation for details.

func (*Tomb) Dead

func (t *Tomb) Dead() <-chan struct{}

Dead returns the channel that can be used to wait until t.Done has been called.

func (*Tomb) Done

func (t *Tomb) Done()

Done flags the goroutine as dead, and should be called a single time right before the goroutine function or method returns. If the goroutine was not already in a dying state before Done is called, it will be flagged as dying and dead at once with no error.

func (*Tomb) Dying

func (t *Tomb) Dying() <-chan struct{}

Dying returns the channel that can be used to wait until t.Kill or t.Done has been called.

func (*Tomb) Err

func (t *Tomb) Err() (reason error)

Err returns the reason for the goroutine death provided via Kill or Killf, or ErrStillAlive when the goroutine is still alive.

func (*Tomb) Kill

func (t *Tomb) Kill(reason error)

Kill flags the goroutine as dying for the given reason. Kill may be called multiple times, but only the first non-nil error is recorded as the reason for termination.

If reason is ErrDying, the previous reason isn't replaced even if it is nil. It's a runtime error to call Kill with ErrDying if t is not in a dying state.

func (*Tomb) Killf

func (t *Tomb) Killf(f string, a ...interface{}) error

Killf works like Kill, but builds the reason providing the received arguments to fmt.Errorf. The generated error is also returned.

func (*Tomb) Wait

func (t *Tomb) Wait() error

Wait blocks until the goroutine is in a dead state and returns the reason for its death.