lifecycle

Documentation

Overview

Package lifecycle provides a helper for objects that have a synchronized lifecycle from idle, through running, to stopped or errored, executing start and stop transitions exactly once.

Example

package main

import (
	"fmt"

	"go.uber.org/yarpc/pkg/lifecycle"
)

// Engine is an example of a type that uses a lifecycle.Once to synchronize its
// lifecycle.
type Engine struct {
	once *lifecycle.Once
}

// NewEngine returns a lifecycle example.
func NewEngine() (*Engine, error) {
	return &Engine{
		once: lifecycle.NewOnce(),
	}, nil
}

// Start advances the engine to the running state (if it has not already done
// so), printing "started".
func (e *Engine) Start() error {
	return e.once.Start(e.start)
}

func (e *Engine) start() error {
	fmt.Printf("started\n")
	return nil
}

// Stop advances the engine to the stopped state (if it has not already done
// so), printing "stopped".
func (e *Engine) Stop() error {
	return e.once.Stop(e.stop)
}

func (e *Engine) stop() error {
	fmt.Printf("stopped\n")
	return nil
}

func main() {
	engine, err := NewEngine()
	if err != nil {
		fmt.Printf("%v\n", err)
	}
	go engine.Start() // might win race to start
	engine.Start()    // blocks until started
	defer engine.Stop()

}

Output:

started
stopped

Index

• type Once
  • func NewOnce() *Once
  • func (o *Once) IsRunning() bool
  • func (o *Once) Start(f func() error) error
  • func (o *Once) Started() <-chan struct{}
  • func (o *Once) State() State
  • func (o *Once) Stop(f func() error) error
  • func (o *Once) Stopped() <-chan struct{}
  • func (o *Once) Stopping() <-chan struct{}
  • func (o *Once) WaitUntilRunning(ctx context.Context) error
• type State
  • func (i State) String() string

Examples

• Package

Types

type Once

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

Once is a helper for implementing objects that advance monotonically through lifecycle states using at-most-once start and stop implementations in a thread safe manner.

func NewOnce

func NewOnce() *Once

NewOnce returns a lifecycle controller.

0. The observable lifecycle state must only go forward from birth to death.
1. Start() must block until the state is >= Running
2. Stop() must block until the state is >= Stopped
3. Stop() must pre-empt Start() if it occurs first
4. Start() and Stop() may be backed by a do-actual-work function, and that function must be called at-most-once.

func (*Once) IsRunning

func (o *Once) IsRunning() bool

IsRunning will return true if current state of the Lifecycle is running

func (*Once) Start

func (o *Once) Start(f func() error) error

Start will run the `f` function once and return the error. If Start is called multiple times it will return the error from the first time it was called.

func (*Once) Started

func (o *Once) Started() <-chan struct{}

Started returns a channel that will close when the lifecycle starts.

func (*Once) State

func (o *Once) State() State

State returns the state of the object within its life cycle, from start to full stop. The function only guarantees that the lifecycle has at least passed through the returned state and may have progressed further in the intervening time.

func (*Once) Stop

func (o *Once) Stop(f func() error) error

Stop will run the `f` function once and return the error. If Stop is called multiple times it will return the error from the first time it was called.

func (*Once) Stopped

func (o *Once) Stopped() <-chan struct{}

Stopped returns a channel that will close when the lifecycle stops.

func (*Once) Stopping

func (o *Once) Stopping() <-chan struct{}

Stopping returns a channel that will close when the lifecycle is stopping.

func (*Once) WaitUntilRunning

func (o *Once) WaitUntilRunning(ctx context.Context) error

WaitUntilRunning blocks until the instance enters the running state, or the context times out.

type State

type State int

State represents `states` that a lifecycle object can be in.

const (
	// Idle indicates the Lifecycle hasn't been operated on yet.
	Idle State = iota

	// Starting indicates that the Lifecycle has begun it's "start" command
	// but hasn't finished yet.
	Starting

	// Running indicates that the Lifecycle has finished starting and is
	// available.
	Running

	// Stopping indicates that the Lifecycle 'stop' method has been called
	// but hasn't finished yet.
	Stopping

	// Stopped indicates that the Lifecycle has been stopped.
	Stopped

	// Errored indicates that the Lifecycle experienced an error and we can't
	// reasonably determine what state the lifecycle is in.
	Errored
)

func (State) String

func (i State) String() string