lifecycle

Documentation

Index

• Variables
• type Manager
  • func NewManager(run, shutdown func(context.Context) error) *Manager
  • func (m *Manager) IsPausing() bool
  • func (m *Manager) Pause(ctx context.Context) error
  • func (m *Manager) PauseWait() <-chan struct{}
  • func (m *Manager) Resume(ctx context.Context) error
  • func (m *Manager) Run(ctx context.Context) error
  • func (m *Manager) SetPauseResumer(pr PauseResumer) error
  • func (m *Manager) SetStartupFunc(fn func(context.Context) error) error
  • func (m *Manager) Shutdown(ctx context.Context) error
  • func (m *Manager) Status() Status
  • func (m *Manager) WaitForStartup(ctx context.Context) error
• type Pausable
• type PauseResumer
  • func MultiPauseResume(pr ...PauseResumer) PauseResumer
  • func PauseResumerFunc(pause, resume func(context.Context) error) PauseResumer
• type Status

Variables

var (
	ErrAlreadyStarted   = errors.New("already started")
	ErrShutdown         = errors.New("shutting down")
	ErrNotStarted       = errors.New("not started")
	ErrPauseUnsupported = errors.New("pause not supported or unset")
)

Static errors

Types

type Manager

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

Manager is used to wrap lifecycle methods with strong guarantees.

func NewManager

func NewManager(run, shutdown func(context.Context) error) *Manager

NewManager will construct a new manager wrapping the provided run and shutdown funcs.

func (*Manager) IsPausing

func (m *Manager) IsPausing() bool

IsPausing will return true if the manager is in a state of pause, or is currently fulfilling a Pause request.

func (*Manager) Pause

func (m *Manager) Pause(ctx context.Context) error

Pause will bein a pause operation. SetPauseResumer must have been called or ErrPauseUnsupported is returned.

Pause is atomic and guarantees a paused state if nil is returned or normal operation otherwise.

func (*Manager) PauseWait

func (m *Manager) PauseWait() <-chan struct{}

PauseWait will return a channel that blocks until a pause operation begins.

func (*Manager) Resume

func (m *Manager) Resume(ctx context.Context) error

Resume will always result in normal operation (unless Shutdown was called).

If the context deadline is reached, "graceful" operations may fail, but will always result in a Ready state.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context) error

Run starts the main loop.

func (*Manager) SetPauseResumer

func (m *Manager) SetPauseResumer(pr PauseResumer) error

SetPauseResumer will set the PauseResumer used by Pause and Resume methods.

func (*Manager) SetStartupFunc

func (m *Manager) SetStartupFunc(fn func(context.Context) error) error

SetStartupFunc can be used to optionally specify a startup function that will be called before calling run.

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown begins the shutdown procedure.

func (*Manager) Status

func (m *Manager) Status() Status

Status returns the current status.

func (*Manager) WaitForStartup

func (m *Manager) WaitForStartup(ctx context.Context) error

WaitForStartup will wait for startup to complete (even if failed or shutdown). err is nil unless context deadline is reached or startup produced an error.

type Pausable

type Pausable interface {
	IsPausing() bool

	// PauseWait will block until a pause operation begins.
	//
	// It should only be used once, it will not block again
	// once resume is called.
	PauseWait() <-chan struct{}
}

Pausable is able to indicate if a pause operation is on-going.

It is used in cases to initiate a graceful/safe abort of long-running operations when IsPausing returns true.

type PauseResumer

type PauseResumer interface {
	// Pause should result in pausing all operations if nil is returned.
	//
	// If a pause cannot complete within the context deadline,
	// the context error should be returned, and normal operation should
	// resume, as if pause was never called.
	Pause(context.Context) error

	// Resume should always result in normal operation.
	//
	// Context can be used for control of graceful operations,
	// but Resume should not return until normal operation is restored.
	//
	// Operations that are required for resuming, should use a background context
	// internally (possibly linking any trace spans).
	Resume(context.Context) error
}

A PauseResumer can be atomically paused and resumed.

func MultiPauseResume

func MultiPauseResume(pr ...PauseResumer) PauseResumer

MultiPauseResume will join multiple PauseResumers where all will be paused, or none.

Any that pause successfully, when another fails, will have Resume called.

func PauseResumerFunc

func PauseResumerFunc(pause, resume func(context.Context) error) PauseResumer

PauseResumerFunc is a convenience method that takes a pause and resume func and returns a PauseResumer.

type Status

type Status int

Status represents lifecycle state.

const (
	StatusUnknown Status = iota
	StatusStarting
	StatusReady
	StatusShutdown
	StatusPausing
	StatusPaused
)

Possible states.