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; wire.go = Encode, Decode, Registry, NewRegistry. The wire form stores guard and action names; Decode rebinds them through a Registry. Rationale: ../docs/plans/machine.md. Contribution rules: ../AGENTS.md.
Index ¶
- Constants
- type Action
- type Definition
- func (d Definition) AllowedTransitions(from Status) []Transition
- func (d Definition) AllowedTriggers(from Status) []Trigger
- func (d *Definition) Encode(reg Registry) ([]byte, error)
- 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 Registry
- 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 ¶
This section is empty.
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. names carries the wire names Decode read; Encode reads them back.
func Decode ¶
func Decode(data []byte, reg Registry) (Definition, error)
Decode parses JSON and validates the result. Each name in the wire form rebinds through reg; a missing or empty name returns an error. Unknown fields are ignored. The read names are stored so Encode can reproduce them on the round trip.
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) Encode ¶
func (d *Definition) Encode(reg Registry) ([]byte, error)
Encode serializes the definition to JSON. It validates first. Each bound guard and action must carry a wire name recorded by Decode; an anonymous function that was never decoded has no name and returns an error. Every emitted name must resolve in reg, so the same registry can decode the bytes back.
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 Registry ¶
Registry holds the named guards and actions that Decode rebinds. Guard names and action names are separate namespaces.
func NewRegistry ¶
func NewRegistry() Registry
NewRegistry builds an empty Registry ready for Decode.
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