supervisor

Documentation

Overview

Package supervisor provides a supervisor implementation for starting, stopping, and monitoring its child processes.

Index

• Variables
• type Iterator
• type Options
• type Supervisor
  • func NewSupervisor[K comparable, P process.Runnable](t Table[K, P], o Options) *Supervisor[K, P]
  • func (m *Supervisor[K, P]) Get(ctx context.Context, pk K) (P, error)
  • func (m *Supervisor[K, P]) Run(ctx context.Context, callback process.Callback) error
  • func (m *Supervisor[K, P]) Start(ctx context.Context, pk K) (P, error)
  • func (m *Supervisor[K, P]) Stop(ctx context.Context, pk K) error
• type Table

Variables

var (
	// ErrNotRunning is an error that is returned when a process
	// supervisor temporarily unavailable (i.e. it is not running).
	ErrNotRunning = errors.New("supervisor: not running")

	// ErrProcessNotFound is an error that is returned if the requested
	// process was not found.
	ErrProcessNotFound = errors.New("supervisor: process not found")

	// ErrProcessNotRunning is an error that is returned when a process is
	// not running (i.e. exists but is in the starting state).
	ErrProcessNotRunning = errors.New("supervisor: process is not running")

	// ErrProcessExists is an error that is returned if the process already
	// exists for the given ID.
	ErrProcessExists = errors.New("supervisor: process already exists")
)

Types

type Iterator

type Iterator[K comparable, V any] interface {
	// Next prepares the value for the next iteration. It returns true on
	// success, and false if there is no next value. Consult Err to check
	// whether iterator successfully reached the end or an error occurred.
	Next() bool

	// Get returns the key and value for the current iteration.
	Get(ctx context.Context) (K, V, error)

	// Err returns any error that occurred during iteration.
	Err() error
	// Close closes the iterator.
	Close() error
}

Iterator iterates over key and value pairs in the Table. It follows the semantics of the standard sql.Rows type and does not necessarily correspond to any consistent snapshot of the Table’s contents.

type Options

type Options struct {
	// Clock is the clock to use. Defaults to system clock.
	Clock *clock.Clock
}

Options is a set of options for supervisor constructor.

type Supervisor

type Supervisor[K comparable, P process.Runnable] struct {
	// contains filtered or unexported fields
}

Supervisor is responsible for starting, stopping, and monitoring its child processes.

func NewSupervisor

func NewSupervisor[K comparable, P process.Runnable](t Table[K, P], o Options) *Supervisor[K, P]

NewSupervisor returns a new Supervisor instance. The given table is used to lookup managed processes and periodically restart failed units (or processes that were added externally). Managed processes are uniquely identifiable by key.

A managed process may remove itself from the Supervisor by deleting the associated entry from the table before terminating. Likewise, to stop a process, it must be removed from the table prior to Stop call. That is, processes must be aware of being managed and the removal is tighly coupled with the table.

As a rule of thumb, to keep the underlying table consistent, processes should not be re-added to table after being removed from the table. It is possible to implement re-adding on top of the Supervisor but that requires handling possible orderings of table removal, addition, re-addition and process startup, shutdown and self-removal (or a subset of these operations depending on the use cases).

func (*Supervisor[K, P]) Get

func (m *Supervisor[K, P]) Get(ctx context.Context, pk K) (P, error)

Get returns a running process or either a ErrProcessNotFound error if the process does not exist or ErrProcessNotRunning is the process exists but is not running.

func (*Supervisor[K, P]) Run

func (m *Supervisor[K, P]) Run(ctx context.Context, callback process.Callback) error

Run starts the supervisor and executes callback on successful initialization.

func (*Supervisor[K, P]) Start

func (m *Supervisor[K, P]) Start(ctx context.Context, pk K) (P, error)

Start starts the process with the given key from the table. It returns ErrNotRunning if the supervisor is not running and ErrProcessExists if the process already exists. Otherwise it returns an error from process initialization.

func (*Supervisor[K, P]) Stop

func (m *Supervisor[K, P]) Stop(ctx context.Context, pk K) error

Stop stops the process with the given key. It returns ErrProcessNotFound if the process does not exist, and an error from running the process otherwise.

type Table

type Table[K comparable, V any] interface {
	// Get returns the value for the given key.
	Get(ctx context.Context, key K) (V, error)
	// Iter returns an iterator for key and value pairs in the table.
	Iter(ctx context.Context) (Iterator[K, V], error)
}

Table defines a table of key and value pairs that is potentially backed by a persistent and shared storage.