fsm

Documentation

Index

• type Action
• type Clock
  • func NewClock() *Clock
  • func Wall(tick <-chan time.Time) *Clock
  • func (t *Clock) Start()
  • func (t *Clock) Stop()
  • func (t *Clock) Tick()
• type Expiry
• type Flap
• type ID
• type Index
• type Instance
• type Limit
• type Options
  • func DefaultOptions(name string) Options
• type Set
  • func NewSet(spec *Spec, clock *Clock, optional ...Options) *Set
  • func (s *Set) Add(initial Index) Instance
  • func (s *Set) CountByState(state Index) int
  • func (s *Set) Delete(instance Instance)
  • func (s *Set) ForEachInstance(view func(ID, Index, interface{}) bool)
  • func (s *Set) ForEachInstanceInState(check Index, view func(ID, Index, interface{}) bool)
  • func (s *Set) Instance(id ID) Instance
  • func (s *Set) Signal(signal Signal, instance ID, optionalData ...interface{}) error
  • func (s *Set) Size() int
  • func (s *Set) Stop()
• type Signal
• type Spec
  • func Define(s State, more ...State) (spec *Spec, err error)
  • func (s *Spec) CheckFlapping(checks []Flap) (*Spec, error)
  • func (s *Spec) CheckFlappingMust(checks []Flap) *Spec
  • func (s *Spec) SetAction(state Index, signal Signal, action Action) error
• type State
• type Tick
• type Time

Types

type Action

type Action func(Instance) error

Action is the action to take when a signal is received, prior to transition to the next state. The error returned by the function is an exception which will put the state machine in an error state. This error state is not the same as some application-specific error state which is a state defined to correspond to some external event indicating a real-world error event (as opposed to a programming error here).

type Clock

type Clock struct {
	C <-chan Tick
	// contains filtered or unexported fields
}

Clock adapts a timer tick

func NewClock

func NewClock() *Clock

NewClock returns a clock

func Wall

func Wall(tick <-chan time.Time) *Clock

Wall adapts a regular time.Tick to return a clock

func (*Clock) Start

func (t *Clock) Start()

Start starts the clock

func (*Clock) Stop

func (t *Clock) Stop()

Stop stops the ticks

func (*Clock) Tick

func (t *Clock) Tick()

Tick makes one tick of the clock

type Expiry

type Expiry struct {
	TTL   Tick
	Raise Signal
}

Expiry specifies the rule for TTL.. A state can have TTL / deadline that when it expires a signal can be raised.

type Flap

type Flap struct {
	States [2]Index
	Count  int
	Raise  Signal
}

Flap is oscillation between two adjacent states. For example, a->b followed by b->a is counted as 1 flap. Similarly, b->a followed by a->b is another flap.

type ID

type ID uint64

ID is the id of the instance in a given set. It's unique in that set.

type Index

type Index int

Index is the index of the state in a FSM

type Instance

type Instance interface {

	// ID returns the ID of the instance
	ID() ID

	// State returns the state of the instance. This is an expensive call to be submitted to queue to view
	State() Index

	// Data returns the custom data attached to the instance.  It's set via the optional arg in Signal
	Data() interface{}

	// Signal signals the instance with optional custom data
	Signal(Signal, ...interface{}) error

	// CanReceive returns true if the current state of the instance can receive the given signal
	CanReceive(Signal) bool
}

Instance is the interface that returns ID and state of the fsm instance safely.

type Limit

type Limit struct {
	Value int
	Raise Signal
}

Limit is a struct that captures the limit and what signal to raise

type Options

type Options struct {
	// Name is the name of the set
	Name string

	// BufferSize is the size of transaction queue/buffered channel
	BufferSize int
}

Options contains options for the set

func DefaultOptions

func DefaultOptions(name string) Options

DefaultOptions returns default values

type Set

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

Set is a collection of fsm instances that follow a given spec. This is the primary interface to manipulate the instances... by sending signals to it via channels.

func NewSet

func NewSet(spec *Spec, clock *Clock, optional ...Options) *Set

NewSet returns a new set

func (*Set) Add

func (s *Set) Add(initial Index) Instance

Add adds an instance given initial state

func (*Set) CountByState

func (s *Set) CountByState(state Index) int

CountByState returns a count of instances in a given state.

func (*Set) Delete

func (s *Set) Delete(instance Instance)

Delete deletes an instance

func (*Set) ForEachInstance

func (s *Set) ForEachInstance(view func(ID, Index, interface{}) bool)

ForEachInstance iterates through the set and provides a consistent view of the instances

func (*Set) ForEachInstanceInState

func (s *Set) ForEachInstanceInState(check Index, view func(ID, Index, interface{}) bool)

ForEachInstanceInState iterates through the set and provides a consistent view of the instances

func (*Set) Instance

func (s *Set) Instance(id ID) Instance

Instance returns the instance by id

func (*Set) Signal

func (s *Set) Signal(signal Signal, instance ID, optionalData ...interface{}) error

Signal sends a signal to the instance

func (*Set) Size

func (s *Set) Size() int

Size returns the size of the set

func (*Set) Stop

func (s *Set) Stop()

Stop stops the state machine loop

type Signal

type Signal int

Signal is a signal that can drive the state machine to transfer from one state to next.

type Spec

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

Spec is a specification of all the rules for the fsm

func Define

func Define(s State, more ...State) (spec *Spec, err error)

Define performs basic validation, consistency checks and returns a compiled spec.

func (*Spec) CheckFlapping

func (s *Spec) CheckFlapping(checks []Flap) (*Spec, error)

CheckFlapping - Limit is the maximum of a->b b->a transitions allowable. For detecting oscillations between two adjacent states (no hops)

func (*Spec) CheckFlappingMust

func (s *Spec) CheckFlappingMust(checks []Flap) *Spec

CheckFlappingMust is a Must version (will panic if err) of CheckFlapping

func (*Spec) SetAction

func (s *Spec) SetAction(state Index, signal Signal, action Action) error

SetAction sets the action associated with a signal in a given state

type State

type State struct {

	// Index is a unique key of the state
	Index Index

	// Transitions fully specifies all the possible transitions from this state, by the way of signals.
	Transitions map[Signal]Index

	// Actions specify for each signal, what code / action is to be executed as the fsm transits from one state to next.
	Actions map[Signal]Action

	// Errors specifies the handling of errors when executing action.  On action error, the mapped state is transitioned.
	Errors map[Signal]Index

	// TTL specifies how long this state can last before a signal is raised.
	TTL Expiry

	// Visit specifies a limit on the number of times the fsm can visit this state before raising a signal.
	Visit Limit
}

State encapsulates all the possible transitions and actions to perform during the state transition. A state can have a TTL so that it is allowed to be in that state for a given TTL. On expiration, a signal is raised.

type Tick

type Tick int64

Tick is a unit of time. Time is in relative terms and synchronized with an actual timer that's provided by the client.

type Time

type Time int64

Time is a unit of time not corresponding to wall time