fsm

README

go-fsm

It is a lightweight finite state machine (FSM) implementation in Golang. It has been inspired by the FSM used in Apache Hadoop YARN:

• Thread safe
• Multiple destination states
• Dynamic destination state determination

Installation

go get github.com/zjshen14/go-fsm

Usage

package main

import (
	"fmt"

	"github.com/zjshen14/go-fsm"
)

type evt struct {
	t fsm.EventType
}

func (e *evt) Type() fsm.EventType { return e.t }

func main() {
	fsm, _ := fsm.NewBuilder().
		AddInitialState("s1").
		AddStates("s2", "s3").
		AddTransition("s1", "e1", func(event fsm.Event) (fsm.State, error) { return "s2", nil }, []fsm.State{"s2"}).
		AddTransition("s2", "e2", func(event fsm.Event) (fsm.State, error) { return "s3", nil }, []fsm.State{"s3"}).
		AddTransition("s3", "e3", func(event fsm.Event) (fsm.State, error) { return "s1", nil }, []fsm.State{"s1"}).
		Build()

	fmt.Println(fsm.CurrentState())
	fsm.Handle(&evt{t: "e1"})
	fmt.Println(fsm.CurrentState())
	fsm.Handle(&evt{t: "e2"})
	fmt.Println(fsm.CurrentState())
	fsm.Handle(&evt{t: "e3"})
	fmt.Println(fsm.CurrentState())
}

License

go-fsm is under the Apache 2.0 license. See the LICENSE file for details.

Documentation

Index

• Variables
• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) AddInitialState(s State) *Builder
  • func (b *Builder) AddStates(states ...State) *Builder
  • func (b *Builder) AddTransition(src State, et EventType, trans Transition, dsts []State) *Builder
  • func (b *Builder) Build() (FSM, error)
• type Event
• type EventType
• type FSM
• type State
• type Transition

Variables

var (
	// ErrBuild represents the error of building an FSM.
	ErrBuild = errors.New("error when building an FSM")
	// ErrTransitionNotFound indicates that there doesn't exist a transition defined on the source state and the event.
	ErrTransitionNotFound = errors.New("unable to find a valid transition")
	// ErrInvalidTransition indicates that the actual destination state after transition is not defined.
	ErrInvalidTransition = errors.New("invalid transition")
)

Types

type Builder

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

Builder is an FSM builder to help construct an FSM.

func NewBuilder

func NewBuilder() *Builder

NewBuilder creates an FSM builder instance with empty setup.

func (*Builder) AddInitialState

func (b *Builder) AddInitialState(s State) *Builder

AddInitialState adds an initial state

func (*Builder) AddStates

func (b *Builder) AddStates(states ...State) *Builder

AddStates adds the non-initial state(s)

func (*Builder) AddTransition

func (b *Builder) AddTransition(src State, et EventType, trans Transition, dsts []State) *Builder

AddTransition adds a transition setup, including the source state, the event to trigger the transition, the transition callback, and the legal destination transitions.

func (*Builder) Build

func (b *Builder) Build() (FSM, error)

Build builds an FSM instance based on the configured states and transition setup.

type Event

type Event interface {
	// Type returns the event type
	Type() EventType
}

Event is the interface of the events that could be handled by an FSM

type EventType

type EventType string

EventType represents a event type and it is a string.

type FSM

type FSM interface {
	// CurrentState returns the current state.
	CurrentState() State
	// Handle handles an event and return error if there is any.
	Handle(Event) error
}

FSM is the interface of an FSM (finite state machine). It allows to define the transition logic and destinations after the transition, and intake the event to trigger the transition. The event handling is synchronized, so that it guarantee always processing one event at any time. An FSM must have exactly one initial state.

type State

type State string

State represents the state and it is a string.

type Transition

type Transition func(Event) (State, error)

Transition is the interface of the transition that would happen on a certain state when receiving a certain event. The transition returns a destination state where an FSM should transit into or an error.