Documentation
¶
Overview ¶
Package machine implements the state-machine block: typed statuses, triggers, guards, actions, and the transition table.
Map: status.go = Status; trigger.go = Trigger; transition.go = Guard, Action, Transition; inout.go = InOut; definition.go = Definition, New, Validate, Fire, Initial, Transitions, AllowedTransitions, AllowedTriggers. Rationale: ../docs/plans/machine.md. Contribution rules: ../AGENTS.md.
Index ¶
- Constants
- Variables
- type Action
- type Definition
- func (d Definition) AllowedTransitions(from Status) []Transition
- func (d Definition) AllowedTriggers(from Status) []Trigger
- func (d *Definition) Fire(ctx context.Context, from Status, trig Trigger, in InOut) (Status, InOut, error)
- func (d Definition) Initial() Status
- func (d Definition) Transitions() []Transition
- func (d *Definition) Validate() error
- type Guard
- type InOut
- type Status
- type Transition
- type Trigger
Constants ¶
const MoveEvent events.Name = "machine.move"
MoveEvent is the event kind a caller emits after a successful Fire. It is a machine concern, so its constant lives in this package.
Variables ¶
var ErrGuardRejected = errors.New("machine: guard rejected move")
ErrGuardRejected reports that a matched row's guard returned false. Fire wraps it with the status and the trigger.
var ErrNoTransition = errors.New("machine: no transition")
ErrNoTransition reports that no transition row matches the current status and trigger. Fire wraps it with the status and the trigger.
Functions ¶
This section is empty.
Types ¶
type Action ¶
Action runs an entry or exit side effect on a move. rec is the record the move carries. The action may write rec.Output. A nil Action is allowed; it means no side effect.
type Definition ¶
type Definition struct {
// contains filtered or unexported fields
}
Definition holds an initial status and a validated transition table. The fields are unexported; the type is immutable after New.
func New ¶
func New(initial Status, ts ...Transition) (*Definition, error)
New builds a Definition and validates the transition table. It rejects an empty transition list. It copies the input slice so later caller mutation of ts cannot change the built table.
func (Definition) AllowedTransitions ¶
func (d Definition) AllowedTransitions(from Status) []Transition
AllowedTransitions returns all transitions whose From matches from. The returned slice is a fresh copy; mutating it cannot affect the definition. Returns an empty slice when no transitions match.
func (Definition) AllowedTriggers ¶
func (d Definition) AllowedTriggers(from Status) []Trigger
AllowedTriggers returns the distinct triggers available from from. Distinctness is enforced by Validate: two transitions that share From and Trigger are rejected at construction. Returns an empty slice when no transitions match.
func (*Definition) Fire ¶
func (d *Definition) Fire( ctx context.Context, from Status, trig Trigger, in InOut, ) (Status, InOut, error)
Fire moves a record from from through the row selected by trig. It runs the guard, then OnExit, then OnEntry, in that order. It returns the target status and the record in in. An action writes the output record through the InOut it receives. A nil Guard or a nil Action is checked, never invoked. Fire does not run OnExit when the guard fails.
func (Definition) Initial ¶
func (d Definition) Initial() Status
Initial returns the initial status of the definition.
func (Definition) Transitions ¶
func (d Definition) Transitions() []Transition
Transitions returns a copy of the transition table. The copy keeps the definition immutable; callers cannot mutate the internal table.
func (*Definition) Validate ¶
func (d *Definition) Validate() error
Validate checks the transition table for invalid shapes. It rejects self loops and transitions whose From is not reachable from the initial status through the table.
type Guard ¶
Guard decides whether a transition may fire. A nil Guard is allowed; it means no check.
type InOut ¶
InOut carries the record a transition moves. Input is the caller payload. Output is the record the move writes.
type Transition ¶
type Transition struct {
From Status
To Status
Trigger Trigger
Guard Guard
OnExit Action
OnEntry Action
}
Transition is one row in the transition table. From is the source status. To is the target status. Trigger selects this row. Guard is the optional check. OnExit and OnEntry are the optional move actions.
Source Files