component

Documentation

Index

• Variables
• func RunComponent(ctx context.Context, componentFactory ComponentFactory, handler OnError) error
• type Component
• type ComponentFactory
• type ComponentManager
  • func (c *ComponentManager) Done() <-chan struct{}
  • func (c *ComponentManager) Ready() <-chan struct{}
  • func (c *ComponentManager) ShutdownSignal() <-chan struct{}
  • func (c *ComponentManager) Start(parent irrecoverable.SignalerContext)
• type ComponentManagerBuilder
  • func NewComponentManagerBuilder() ComponentManagerBuilder
• type ComponentWorker
• type ErrorHandlingResult
• type OnError
• type ReadyFunc

Variables

var ErrComponentShutdown = fmt.Errorf("component has already shut down")

ErrComponentShutdown is returned by a component which has already been shut down.

Functions

func RunComponent

func RunComponent(ctx context.Context, componentFactory ComponentFactory, handler OnError) error

RunComponent repeatedly starts components returned from the given ComponentFactory, shutting them down when they encounter irrecoverable errors and passing those errors to the given error handler. If the given context is cancelled, it will wait for the current component instance to shutdown before returning. The returned error is either: - The context error if the context was canceled - The last error handled if the error handler returns ErrorHandlingStop - An error returned from componentFactory while generating an instance of component

Types

type Component

type Component interface {
	module.Startable
	module.ReadyDoneAware
}

Component represents a component which can be started and stopped, and exposes channels that close when startup and shutdown have completed. Once Start has been called, the channel returned by Done must close eventually, whether that be because of a graceful shutdown or an irrecoverable error.

type ComponentFactory

type ComponentFactory func() (Component, error)

type ComponentManager

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

ComponentManager is used to manage the worker routines of a Component, and implements all of the methods required by the Component interface, abstracting them away from individual implementations.

Since component manager implements the Component interface, its Ready() and Done() methods are idempotent, and can be called immediately after instantiation. The Ready() channel is closed when all worker functions have called their ReadyFunc, and its Done() channel is closed after all worker functions have returned.

Shutdown is signalled by cancelling the irrecoverable.SignalerContext passed to Start(). This context is also used by workers to communicate irrecoverable errors. All irrecoverable errors are considered fatal and are propagated to the caller of Start() via the context's Throw method.

func (*ComponentManager) Done

func (c *ComponentManager) Done() <-chan struct{}

Done returns a channel which is closed once the ComponentManager has shut down. This happens after all worker routines have shut down (either gracefully or by throwing an error).

func (*ComponentManager) Ready

func (c *ComponentManager) Ready() <-chan struct{}

Ready returns a channel which is closed once all the worker routines have been launched and are ready. If any worker routines exit before they indicate that they are ready, the channel returned from Ready will never close.

func (*ComponentManager) ShutdownSignal

func (c *ComponentManager) ShutdownSignal() <-chan struct{}

ShutdownSignal returns a channel that is closed when shutdown has commenced. This can happen either if the ComponentManager's context is canceled, or a worker routine encounters an irrecoverable error. If this is called before Start, a nil channel will be returned.

func (*ComponentManager) Start

func (c *ComponentManager) Start(parent irrecoverable.SignalerContext)

Start initiates the ComponentManager by launching all worker routines. Start must only be called once. It will panic if called more than once.

type ComponentManagerBuilder

type ComponentManagerBuilder interface {
	// AddWorker adds a worker routine for the ComponentManager
	AddWorker(ComponentWorker) ComponentManagerBuilder

	// Build builds and returns a new ComponentManager instance
	Build() *ComponentManager
}

ComponentManagerBuilder provides a mechanism for building a ComponentManager

func NewComponentManagerBuilder

func NewComponentManagerBuilder() ComponentManagerBuilder

NewComponentManagerBuilder returns a new ComponentManagerBuilder

type ComponentWorker

type ComponentWorker func(ctx irrecoverable.SignalerContext, ready ReadyFunc)

ComponentWorker represents a worker routine of a component. It takes a SignalerContext which can be used to throw any irrecoverable errors it encounters, as well as a ReadyFunc which must be called to signal that it is ready. The ComponentManager waits until all workers have signaled that they are ready before closing its own Ready channel.

type ErrorHandlingResult

type ErrorHandlingResult int

const (
	ErrorHandlingRestart ErrorHandlingResult = iota
	ErrorHandlingStop
)

type OnError

type OnError = func(error) ErrorHandlingResult

OnError reacts to an irrecoverable error It is meant to inspect the error, determining its type and seeing if e.g. a restart or some other measure is suitable, and then return an ErrorHandlingResult indicating how RunComponent should proceed. Before returning, it could also: - panic (in canary / benchmark) - log in various Error channels and / or send telemetry ...

type ReadyFunc

type ReadyFunc func()

ReadyFunc is called within a ComponentWorker function to indicate that the worker is ready ComponentManager's Ready channel is closed when all workers are ready.