runner

README

An attempt of a cleaner rewrite of github.com/vedranvuk/sync/runner.

Not fully tested, WIP.

Documentation

Index

• Variables
• type DoneCallback
• type Engine
• type Runner
  • func New(donecb DoneCallback) *Runner
  • func (r *Runner) MustRegister(name string, e Engine) *Runner
  • func (r *Runner) Register(name string, e Engine) error
  • func (r *Runner) RunningEngines() int
  • func (r *Runner) Start(ctx context.Context) error
  • func (r *Runner) State() State
  • func (r *Runner) Stop(ctx context.Context) error
• type State

Variables

var (
	// ErrRunner is the base Runner error.
	ErrRunner = errors.New("runner")

	// ErrRegister is the base Register error.
	ErrRegister = fmt.Errorf("%w: register", ErrRunner)
	// ErrEmptyName is returned by Register when Engine name is not specified.
	ErrEmptyName = fmt.Errorf("%w: engine name not specified", ErrRegister)
	// ErrDuplicateName is returned by Register if a duplicate name was specified.
	ErrDuplicateName = fmt.Errorf("%w: engine under specified name already registered", ErrRegister)
	// ErrNilEngine is returned by Register if no engine was specified.
	ErrNilEngine = fmt.Errorf("%w: engine is nil", ErrRegister)
	// ErrRegisterOnRunning is returned by Register if Runner is running.
	ErrRegisterOnRunning = fmt.Errorf("%w: cannot register engine, runner not idle", ErrRegister)

	// ErrStart is the base Start error.
	ErrStart = fmt.Errorf("%w: start error", ErrRunner)
	// ErrRunning is returned when Start was called and Runner was not idle.
	ErrRunning = fmt.Errorf("%w: cannot start, not idle", ErrStart)
	// ErrNoEngines is returned when running a Runner with no defined engines.
	ErrNoEngines = fmt.Errorf("%w: no engines defined", ErrStart)

	// ErrStop is the base Stop error.
	ErrStop = fmt.Errorf("%w: stop error", ErrRunner)
	// ErrIdle is returned when Stop was called and Runner was already idle.
	ErrIdle = fmt.Errorf("%w: already stopped", ErrStop)
	// ErrFailing is returned when Stop is called and Runner is shutting down due to an Engine Start error.
	ErrFailing = fmt.Errorf("%s: already stopping due to failure", ErrStop)
	// ErrShuttingDown is returned when Stop is called and Runner is shutting down.
	ErrShuttingDown = fmt.Errorf("%w: already stopping", ErrStop)
)

Types

type DoneCallback

type DoneCallback = func(name string, start bool, err error)

DoneCallback is a prototype of a callback function to be called when an Engine Start or Stop methods return.

It is intended to report Engine errors mainly to log them as they are all handled by Runner beforehand.

Name will be the name of the Engine as registered. Start, if true will indicate the value is from the Engine Start method. Start, if false will indicate the value is from the Engine Stop method. Err will be the value returned by Engine's Start or Stop methods, depending.

type Engine

type Engine interface {
	// Start must run the Engine then return a nil error on success or an error
	// if it failed. Start can be longrunning and must be stoppable by Stop.
	// If Stop was called, Start should return before Stop,
	// if it does not it is immediately terminated.
	Start(context.Context) error
	// Stop must stop the Engine in a manner described for Start.
	// Errors returned by Stop do not affect Runner's behaviour. They are only
	// optionally reported in DoneCallback.
	Stop(context.Context) error
}

Engine defines an interface to a type that can be Started and Stopped by the Runner. Its' Start method can be longrunning and Stop must be able to stop it.

Both methods receive a context with a timeout value which is free to interpretation of the implementor.

type Runner

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

Runner runs multiple Engine implementors simultaneously.

Engines can be registered with Register then run simultaneously using Start. If any one Engine's Start methods return a non-nil error before all engines finish with a nil Start error or Runner Stop is called, all other running engines are stopped by calling their Stop method.

If all Engines Start methods finish with a nil error Runner's Start method returns nil.

Running engines can be stopped with Stop and will return when all Engines have stopped.

Runner can be restarted multiple times regardless of success of the last Start result.

func New

func New(donecb DoneCallback) *Runner

New returns a new *Runner instance with optional callback donecb.

func (*Runner) MustRegister

func (r *Runner) MustRegister(name string, e Engine) *Runner

MustRegister is like Register but returns the Runner on success or panics if an error occurs.

func (*Runner) Register

func (r *Runner) Register(name string, e Engine) error

Register registers engine under specified name. If an error occurs it is returned and the engine was not registered.

Name specifies the name under which engine will be registered. Engines cannot be registered while the Runner is running and name must not be empty and must be unique.

func (*Runner) RunningEngines

func (r *Runner) RunningEngines() int

RunningEngines returns the number of running engines.

func (*Runner) Start

func (r *Runner) Start(ctx context.Context) error

Start starts the Runner by running all Engines registered with it simultaneously and returns a nil error if all Engines have finished work without an error or have been successfully stopped by Stop before finishing.

If any one Engine Start method returns a non-nil error before all Engines have finished successfully with a nil error or have been stopped by Runner Start will return that error after first stopping any other running Engines. If any other Engines Start method returns a non-nil error during this "failure shutdown" it will be reported via Runner's callback.

Startctx is a context passed to all registered Engines Start methods which is open to Engine's interpretation. If it carries a timeout its' duration is used to construct a new context with same timeout duration that will be passed to Engine Stop methods in case of the "failure shutdown".

If all Engines finished successfully or return no errors before Stop was called result will be nil.

If starting Runner with no registered engines an ErrNoEngines is returned.

func (*Runner) State

func (r *Runner) State() State

State reports current Runner state.

func (*Runner) Stop

func (r *Runner) Stop(ctx context.Context) error

Stop stops the Runner by issuing a Stop request to all Engines. It waits for engines indefinitely.

Context ctx is passed to Engine Stop methods and is open to their interpretation.

If any Engines Stop methods return a non-nil error Stop will return that error. If all Engines stop without an error, Stop returns nil. If any additional Engine Stop methods return a non-nil error they can be examined via Runner's callback.

Issuing Stop on a Runner that is not idle returns one of predefined errors.

type State

type State uint8

State is the Runner state.

const (
	// StateIdle indicates Runner is idle and can be Started.
	StateIdle State = iota
	// StateRunning indicates Runner is Running and can be Stopped.
	StateRunning
	// StateStoppingFail indicates Runner is stopping due to an Engine failure.
	StateStoppingFail
	// StateStoppingRequest indicates Runner is stopping due to a Stop call.
	StateStoppingRequest
)