loop

Documentation

Overview

A typical Go idiom for concurrent applications is running a loop in the background doing a select on one or more channels. Stopping those loops or getting aware of internal errors requires extra efforts. The loop package helps to manage this kind of goroutines.

Index

• Constants
• func PackageVersion() version.Version
• type Loop
  • func Go(lf LoopFunc) Loop
  • func GoRecoverable(lf LoopFunc, rf RecoverFunc) Loop
• type LoopFunc
• type RecoverFunc
• type Recovering
• type Recoverings
  • func (rs Recoverings) First() *Recovering
  • func (rs Recoverings) Frequency(num int, dur time.Duration) bool
  • func (rs Recoverings) Last() *Recovering
  • func (rs Recoverings) Len() int
  • func (rs Recoverings) Trim(l int) Recoverings

Constants

const (
	Running = iota
	Stopping
	Stopped
)

Status of the loop.

Functions

func PackageVersion

func PackageVersion() version.Version

PackageVersion returns the version of the version package.

Types

type Loop

type Loop interface {
	// Stop tells the loop to stop working without a passed error and
	// waits until it is done.
	Stop() error

	// Kill tells the loop to stop working due to the passed error.
	// Here only the first error will be stored for later evaluation.
	Kill(err error)

	// Wait blocks the caller until the loop ended and returns the error.
	Wait() (err error)

	// Error returns the current status and error of the loop.
	Error() (status int, err error)

	// ShallStop returns a channel signalling the loop to
	// stop working.
	ShallStop() <-chan struct{}

	// IsStopping returns a channel that can be used to wait until
	// the loop is stopping or to avoid deadlocks when communicating
	// with the loop.
	IsStopping() <-chan struct{}
}

Loop manages running loops in the background as goroutines.

func Go

func Go(lf LoopFunc) Loop

Go starts the loop function in the background. The loop can be stopped or killed. This leads to a signal out of the channel Loop.ShallStop(). The loop then has to end working returning a possible error. Wait() then waits until the loop ended and returns the error.

func GoRecoverable

func GoRecoverable(lf LoopFunc, rf RecoverFunc) Loop

GoRecoverable starts the loop function in the background. The loop can be stopped or killed. This leads to a signal out of the channel Loop.ShallStop(). The loop then has to end working returning a possible error. Wait() then waits until the loop ended and returns the error.

If the loop panics a Recovering is created and passed with all Recoverings before to the RecoverFunc. If it returns nil the loop will be started again. Otherwise the loop will be killed with that error.

type LoopFunc

type LoopFunc func(l Loop) error

LoopFunc is managed loop function.

type RecoverFunc

type RecoverFunc func(rs Recoverings) (Recoverings, error)

RecoverFunc decides if a loop shall be started again or end with an error. It is also responsible to trim the list of revocerings if needed.

type Recovering

type Recovering struct {
	Time   time.Time
	Reason interface{}
}

Recovering stores time and reason of one of the recoverings.

type Recoverings

type Recoverings []*Recovering

Recoverings is a list of recoverings a loop already had.

func (Recoverings) First

func (rs Recoverings) First() *Recovering

Last returns the last recovering.

func (Recoverings) Frequency

func (rs Recoverings) Frequency(num int, dur time.Duration) bool

Frequency checks if a given number of restarts happened during a given duration.

func (Recoverings) Last

func (rs Recoverings) Last() *Recovering

Last returns the last recovering.

func (Recoverings) Len

func (rs Recoverings) Len() int

Len returns the length of the recoverings.

func (Recoverings) Trim

func (rs Recoverings) Trim(l int) Recoverings

Trim returns the last recoverings defined by l. This way the recover func can con control the length and take care that the list not grows too much.