automaton

Documentation

Overview

Package automaton defines streamable finite state machines that allow UIs to easily model stateful, multi-step application flows.

Index

• func Run[S, I any](ctx context.Context, impl Implementation[S, I]) (stream.Input[I], <-chan Update[S])
• type Implementation
• type Status
• type Update

Functions

func Run

func Run[S, I any](ctx context.Context, impl Implementation[S, I]) (stream.Input[I], <-chan Update[S])

Run executes the automaton until [Implementation.React] returns running=false. Each change is emitted on the returned channel, and the automaton may be controlled by sending data on the returned Input.

Types

type Implementation

type Implementation[Snapshot, Input any] interface {
	// Prepare is invoked once to acquire the initial state of the automaton. If it returns
	// running=false, the automaton will shut down.
	Prepare(ctx context.Context) (state Snapshot, running bool)
	// React is invoked to update the [Implementation]
	// in response to some asynchronous input. All
	// invocations will be in response to an input, and will include the provided [input] value.
	// This function should return a snapshot of its state that is
	// relevant to asynchronous observers (like GUI code) and a boolean indicating whether it is
	// still running. If [running] is false, the automaton will shut down.
	React(ctx context.Context, input Input) (state Snapshot, running bool)
}

Implementation captures the dynamic state of an automaton in progress.

type Status

type Status uint8

Status represents what a given automaton is currently doing.

const (
	// Waiting indicates that the automaton is waiting for asynchronous input.
	Waiting Status = iota
	// Busy indicates that the automaton is doing work.
	Busy
	// Done indicates that the automaton has shut down and will do no more work and
	// consume no more input.
	Done
)

type Update

type Update[Snapshot any] struct {
	// Status indicates whether the automaton is busy, waiting, or done. It can change
	// without Generation and Snapshot changing.
	Status
	// Generation is incremented every time Snapshot changes.
	Generation int
	// Snapshot of the state of the automaton.
	Snapshot Snapshot
}

Update provides a snapshot of an automaton's state along with its current status.