fsm

package module
Version: v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 16, 2016 License: MIT Imports: 2 Imported by: 11

README

go-fsm

TravisCI Build Status GoDoc

fsm is a finite state machine written in Go. This package aims to be very simple, while making it easy to maintain predictable state.

License

This code is released for use under the MIT License, of which the full contense can be found within the LICENSE file.

This license is extremely permissve, and should allow the full use of this code in almost all situations. When in doubt, consult a lawyer.

Installation

go get github.com/theckman/go-fsm

Usage

The purpose of the machine is to be a field within your struct. You then interact with the machine to enforce the state of struct. For the full API documentation, check out the GoDoc page. Here's an example of a machine with some states you can transition between:

import "github.com/theckman/go-fsm"

type T struct {
	M *fsm.Machine
}

func main() {
	t := &T{M: &fsm.Machine{}}

	// add initial rule
	err := t.M.AddStateTransitionRules("started", "finished", "aborted", "exited")

	if err != nil {
		// handle
	}

	// add rest of rules
	t.M.AddStateTransitionRules("aborted", "started")
	t.M.AddStateTransitionRules("finished", "started")
	t.M.AddStateTransitionRules("exited") // final state

	// set initial state
	err = t.M.StateTransition("aborted") // nil

	// get the current state
	state := t.M.CurrentState() // "aborted"

	// try to transition to an non-whitelisted state
	err = t.M.StateTransition("finished") // ErrTransitionNotPermitted

	// try to transition to a permitted state
	err = t.M.StateTransition("started") // nil
}

Documentation

Overview

Package fsm is a simple finite state machine in Go. This state machine is safe for concurrent use, so multiple goroutines can work with the machine safely.

Index

Constants

View Source
const Version = "0.0.2"

Version is the semantic version (SemVer) string.

Variables

This section is empty.

Functions

This section is empty.

Types

type CallbackHandler

type CallbackHandler interface {
	StateTransitionCallback(State) error
}

CallbackHandler is an interface type defining the interface for receiving callbacks.

type Error

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

Error is the struct representing internal errors. This implements the error interface

func (*Error) Code

func (e *Error) Code() ErrorCode

Code returns the error code.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Message

func (e *Error) Message() string

Message returns the error message.

type ErrorCode

type ErrorCode uint

ErrorCode is the type for package-specific error codes. This is used within the Error struct, which allows you to programatically determine the error cause.

const (
	// ErrorUnknown is the default value
	ErrorUnknown ErrorCode = iota

	// ErrorMachineNotInitialized is an error returned when actions are taken on
	// a machine before it has been initialized. A machine is initialized by
	// adding at least one state and setting it as the initial state.
	ErrorMachineNotInitialized

	// ErrorTransitionNotPermitted is the error returned when trying to
	// transition to an invalid state. In other words, the machine is not
	// permitted to transition from the current state to the one requested.
	ErrorTransitionNotPermitted

	// ErrorStateUndefined is the error returned when the requested state is
	// not defined within the machine.
	ErrorStateUndefined
)

func (ErrorCode) String

func (e ErrorCode) String() string

type Machine

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

Machine is the state machine.

func (*Machine) AddStateTransitionRules

func (m *Machine) AddStateTransitionRules(sourceState State, destinationStates ...State) error

AddStateTransitionRules is a function for adding valid state transitions to the machine. This allows you to define which states any given state can be transitioned to.

func (*Machine) CurrentState

func (m *Machine) CurrentState() State

CurrentState returns the machine's current state. If the State returned is "", then the machine has not been given an initial state.

func (*Machine) SetStateTransitionCallback

func (m *Machine) SetStateTransitionCallback(callback CallbackHandler, synchronous bool) error

SetStateTransitionCallback for the state transition. This is meant to send callbacks back to the consumer for state changes. The callback only sends the new state. The synchonous parameter indicates whether the callback is done synchronously with the StateTransition() call.

func (*Machine) StateTransition

func (m *Machine) StateTransition(toState State) error

StateTransition triggers a transition to the toState. This function is also used to set the initial state of machine.

Before you can transition to any state, even for the initial, you must define it with AddStateTransition(). If you are setting the initial state, and that state is not define, this will return an ErrInvalidInitialState error.

When transitioning from a state, this function will return an error either if the state transition is not allowed, or if the destination state has not been defined. In both cases, it's seen as a non-permitted state transition.

func (*Machine) StateTransitionRules

func (m *Machine) StateTransitionRules(state State) (TransitionRuleSet, error)

StateTransitionRules returns the allowed states for

type State

type State string

State is the machine state. It's really just a string.

type TransitionRuleSet

type TransitionRuleSet map[State]struct{}

TransitionRuleSet is a set of allowed transitions. This uses map of struct{} to implement a set.

func (TransitionRuleSet) Copy

Copy copies the TransitionRuleSet in to a different TransitionRuleSet.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL