supervisor

Documentation

Index

• Constants
• type Option
  • func WithContext(ctx context.Context) Option
  • func WithLogHandler(handler slog.Handler) Option
  • func WithRunnables(runnables ...Runnable) Option
  • func WithShutdownTimeout(timeout time.Duration) Option
  • func WithSignals(signals ...os.Signal) Option
  • func WithStartupInitial(initial time.Duration) Option
  • func WithStartupTimeout(timeout time.Duration) Option
• type PIDZero
  • func New(opts ...Option) (*PIDZero, error)
  • func (p *PIDZero) AddStateSubscriber(ch chan StateMap) func()
  • func (p *PIDZero) GetCurrentState(r Runnable) string
  • func (p *PIDZero) GetCurrentStates() map[Runnable]string
  • func (p *PIDZero) GetStateMap() StateMap
  • func (p *PIDZero) ReloadAll()
  • func (p *PIDZero) Run() error
  • func (p *PIDZero) Shutdown()
  • func (p *PIDZero) String() string
  • func (p *PIDZero) SubscribeStateChanges(ctx context.Context) <-chan StateMap
• type Readiness
• type ReloadSender
• type Reloadable
• type Runnable
• type ShutdownSender
• type StateMap
• type Stateable

Constants

const (
	DefaultStartupTimeout = 2 * time.Minute       // Default per-Runnable max timeout for startup
	DefaultStartupInitial = 50 * time.Millisecond // Initial wait time for startup

	// DefaultShutdownTimeout is the TOTAL timeout for waiting on all supervisor goroutines
	// (including external runnables) to complete during shutdown, *after* Stop() has been called
	// on all of the runnables.
	DefaultShutdownTimeout = 2 * time.Minute
)

Types

type Option

type Option func(*PIDZero)

Option represents a functional option for configuring PIDZero.

func WithContext

func WithContext(ctx context.Context) Option

WithContext sets a custom context for the PIDZero instance. This allows for more granular control over cancellation and timeouts.

func WithLogHandler

func WithLogHandler(handler slog.Handler) Option

WithLogHandler sets a custom slog handler for the PIDZero instance. For example, to use a custom JSON handler with debug level:

handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug})
sv := supervisor.New(runnables, supervisor.WithLogHandler(handler))

func WithRunnables

func WithRunnables(runnables ...Runnable) Option

WithRunnables sets the runnables to be managed by the PIDZero instance. Accepts multiple runnables as variadic arguments.

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) Option

WithShutdownTimeout sets the timeout for graceful shutdown of all runnables. If the timeout is reached before all runnables have completed their shutdown, the supervisor will log a warning but continue with the shutdown process.

func WithSignals

func WithSignals(signals ...os.Signal) Option

WithSignals sets custom signals for the PIDZero instance to listen for.

func WithStartupInitial

func WithStartupInitial(initial time.Duration) Option

WithStartupInitial sets the initial startup delay for the PIDZero instance.

func WithStartupTimeout

func WithStartupTimeout(timeout time.Duration) Option

WithStartupTimeout sets the startup timeout for the PIDZero instance.

type PIDZero

type PIDZero struct {
	SignalChan chan os.Signal
	// contains filtered or unexported fields
}

PIDZero manages multiple "runnables" and handles OS signals for HUP or graceful shutdown.

func New

func New(opts ...Option) (*PIDZero, error)

New creates a new PIDZero instance with the provided options.

func (*PIDZero) AddStateSubscriber

func (p *PIDZero) AddStateSubscriber(ch chan StateMap) func()

AddStateSubscriber adds a channel to the internal list of broadcast targets. It will receive the current state immediately (if possible), and will also receive future state changes when any runnable's state is updated. A callback function is returned that should be called to remove the channel from the list of subscribers when it is no longer needed.

func (*PIDZero) GetCurrentState

func (p *PIDZero) GetCurrentState(r Runnable) string

GetCurrentState returns the current state of a specific runnable service. If the service doesn't implement Stateable, returns "unknown".

func (*PIDZero) GetCurrentStates

func (p *PIDZero) GetCurrentStates() map[Runnable]string

GetCurrentStates returns a map of all Stateable runnables and their current states.

func (*PIDZero) GetStateMap

func (p *PIDZero) GetStateMap() StateMap

GetStateMap returns a map of runnable string representation to its current state. It uses cached state values from stateMap for consistency with the state monitoring system.

func (*PIDZero) ReloadAll

func (p *PIDZero) ReloadAll()

ReloadAll triggers a reload of all runnables that implement the Reloadable interface.

func (*PIDZero) Run

func (p *PIDZero) Run() error

Run starts all runnables and listens for OS signals to handle graceful shutdown or reload.

func (*PIDZero) Shutdown

func (p *PIDZero) Shutdown()

Shutdown stops all runnables in reverse initialization order and attempts to wait for their goroutines to complete. Each runnable's Stop method will always be called regardless of timeouts. However, if shutdownTimeout is configured and exceeded, this function will return before all goroutines complete, potentially causing unclean termination if the program exits immediately afterward.

func (*PIDZero) String

func (p *PIDZero) String() string

String returns a string representation of the PIDZero instance.

func (*PIDZero) SubscribeStateChanges

func (p *PIDZero) SubscribeStateChanges(ctx context.Context) <-chan StateMap

SubscribeStateChanges returns a channel that receives a StateMap whenever any runnable's state changes. The channel is closed when the context is done.

type Readiness

type Readiness interface {
	IsRunning() bool
}

Readiness provides a way to check if a Runnable is currently running, used to determine if a Runnable is done with it's startup phase.

type ReloadSender

type ReloadSender interface {
	// GetReloadTrigger returns a channel that emits signals when a reload is requested.
	GetReloadTrigger() <-chan struct{}
}

ReloadSender represents a service that can trigger reloads.

type Reloadable

type Reloadable interface {
	// Reload signals the service to reload its configuration.
	// Reload is a blocking call that reloads the configuration of the work unit.
	Reload()
}

Reloadable represents a service that can be reloaded.

type Runnable

type Runnable interface {
	fmt.Stringer // Runnables implement a String() method to be identifiable in logs

	// Run starts the service with the given context and returns an error if it fails.
	// Run is a blocking call that runs the work unit until it is stopped.
	Run(ctx context.Context) error
	// Stop signals the service to stop.
	// Stop is a blocking call that stops the work unit.
	Stop()
}

Runnable represents a service that can be run and stopped.

type ShutdownSender

type ShutdownSender interface {
	// GetShutdownTrigger returns a channel that emits signals when a shutdown is requested.
	GetShutdownTrigger() <-chan struct{}
}

ShutdownSender represents a service that can trigger system shutdown.

type StateMap

type StateMap map[string]string

StateMap is a map of runnable string representation to its current state

type Stateable

type Stateable interface {
	Readiness

	// GetState returns the current state of the service.
	GetState() string

	// GetStateChan returns a channel that will receive the current state of the service.
	GetStateChan(context.Context) <-chan string
}

Stateable represents a service that can report its state.