fsm

Documentation

Index

• Constants
• Variables
• func UseLogger(logger btclog.Logger)
• type AbortEarlyOnErrorOption
• type Action
• type CachedObserver
  • func NewCachedObserver(maxElements int) *CachedObserver
  • func (c *CachedObserver) GetCachedNotifications() []Notification
  • func (c *CachedObserver) Notify(notification Notification)
  • func (c *CachedObserver) WaitForState(ctx context.Context, timeout time.Duration, state StateType, ...) error
  • func (c *CachedObserver) WaitForStateAsync(ctx context.Context, state StateType, abortOnEarlyError bool) chan error
• type ErrConfigError
  • func NewErrConfigError(msg string) ErrConfigError
  • func (e ErrConfigError) Error() string
• type ErrWaitingForStateTimeout
  • func NewErrWaitingForStateTimeout(expected StateType) ErrWaitingForStateTimeout
  • func (e ErrWaitingForStateTimeout) Error() string
• type EventContext
• type EventType
  • func NoOpAction(_ EventContext) EventType
• type ExampleFSM
  • func NewExampleFSMContext(service ExampleService, store ExampleStore) *ExampleFSM
  • func (e *ExampleFSM) GetStates() States
• type ExampleService
• type ExampleStore
• type FixedSizeSlice
  • func NewFixedSizeSlice[T any](maxLen int) *FixedSizeSlice[T]
  • func (fs *FixedSizeSlice[T]) Add(element T)
  • func (fs *FixedSizeSlice[T]) Get() []T
  • func (fs *FixedSizeSlice[T]) GetElement(index int) T
• type InitStuffRequest
• type InitialWaitOption
• type Notification
• type Observer
• type State
• type StateMachine
  • func NewStateMachine(states States, observerSize int) *StateMachine
  • func NewStateMachineWithState(states States, current StateType, observerSize int) *StateMachine
  • func (s *StateMachine) HandleError(err error) EventType
  • func (s *StateMachine) RegisterObserver(observer Observer)
  • func (s *StateMachine) RemoveObserver(observer Observer) bool
  • func (s *StateMachine) SendEvent(event EventType, eventCtx EventContext) error
• type StateType
• type States
• type Transitions
• type WaitForStateOption
  • func WithAbortEarlyOnErrorOption() WaitForStateOption
  • func WithWaitForStateOption(initialWait time.Duration) WaitForStateOption

Constants

const (
	InitFSM         = StateType("InitFSM")
	StuffSentOut    = StateType("StuffSentOut")
	WaitingForStuff = StateType("WaitingForStuff")
	StuffFailed     = StateType("StuffFailed")
	StuffSuccess    = StateType("StuffSuccess")
)

States.

const (
	// EmptyState represents the default state of the system.
	EmptyState StateType = ""

	// NoOp represents a no-op event.
	NoOp EventType = "NoOp"

	// OnError can be used when an action returns a generic error.
	OnError EventType = "OnError"

	// ContextValidationFailed can be when the passed context if
	// not of the expected type.
	ContextValidationFailed EventType = "ContextValidationFailed"
)

const Subsystem = "FSM"

Subsystem defines the sub system name of this package.

Variables

var (
	OnRequestStuff = EventType("OnRequestStuff")
	OnStuffSentOut = EventType("OnStuffSentOut")
	OnStuffSuccess = EventType("OnStuffSuccess")
)

Events.

var (
	ErrEventRejected        = errors.New("event rejected")
	ErrWaitForStateTimedOut = errors.New(
		"timed out while waiting for event",
	)
	ErrInvalidContextType             = errors.New("invalid context")
	ErrWaitingForStateEarlyAbortError = errors.New(
		"waiting for state early abort",
	)
)

ErrEventRejected is the error returned when the state machine cannot process an event in the state that it is in.

Functions

func UseLogger

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type AbortEarlyOnErrorOption

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

AbortEarlyOnErrorOption is an option that can be passed to the WaitForState function to abort early if an error occurs.

type Action

type Action func(eventCtx EventContext) EventType

Action represents the action to be executed in a given state.

type CachedObserver

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

CachedObserver is an observer that caches all states and transitions of the observed state machine.

func NewCachedObserver

func NewCachedObserver(maxElements int) *CachedObserver

NewCachedObserver creates a new cached observer with the given maximum number of cached notifications.

func (*CachedObserver) GetCachedNotifications

func (c *CachedObserver) GetCachedNotifications() []Notification

GetCachedNotifications returns a copy of the cached notifications.

func (*CachedObserver) Notify

func (c *CachedObserver) Notify(notification Notification)

Notify implements the Observer interface.

func (*CachedObserver) WaitForState

func (c *CachedObserver) WaitForState(ctx context.Context,
	timeout time.Duration, state StateType,
	opts ...WaitForStateOption) error

WaitForState waits for the state machine to reach the given state. If the optional initialWait parameter is set, the function will wait for the given duration before checking the state. This is useful if the function is called immediately after sending an event to the state machine and the state machine needs some time to process the event.

func (*CachedObserver) WaitForStateAsync

func (c *CachedObserver) WaitForStateAsync(ctx context.Context, state StateType,
	abortOnEarlyError bool) chan error

WaitForStateAsync waits asynchronously until the passed context is canceled or the expected state is reached. The function returns a channel that will receive an error if the expected state is reached or an error occurred. If the context is canceled before the expected state is reached, the channel will receive an ErrWaitingForStateTimeout error.

type ErrConfigError

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

ErrConfigError is an error returned when the state machine is misconfigured.

func NewErrConfigError

func NewErrConfigError(msg string) ErrConfigError

NewErrConfigError creates a new ErrConfigError.

func (ErrConfigError) Error

func (e ErrConfigError) Error() string

Error returns the error message.

type ErrWaitingForStateTimeout

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

ErrWaitingForStateTimeout is an error returned when the state machine times out while waiting for a state.

func NewErrWaitingForStateTimeout

func NewErrWaitingForStateTimeout(expected StateType) ErrWaitingForStateTimeout

NewErrWaitingForStateTimeout creates a new ErrWaitingForStateTimeout.

func (ErrWaitingForStateTimeout) Error

func (e ErrWaitingForStateTimeout) Error() string

Error returns the error message.

type EventContext

type EventContext interface{}

EventContext represents the context to be passed to the action implementation.

type EventType

type EventType string

EventType represents an extensible event type in the state machine.

func NoOpAction

func NoOpAction(_ EventContext) EventType

NoOpAction is a no-op action that can be used by states that don't need to execute any action.

type ExampleFSM

type ExampleFSM struct {
	*StateMachine
	// contains filtered or unexported fields
}

ExampleFSM implements the FSM and uses the ExampleService and ExampleStore to implement the actions.

func NewExampleFSMContext

func NewExampleFSMContext(service ExampleService,
	store ExampleStore) *ExampleFSM

NewExampleFSMContext creates a new example FSM context.

func (*ExampleFSM) GetStates

func (e *ExampleFSM) GetStates() States

GetStates returns the states for the example FSM.

type ExampleService

type ExampleService interface {
	WaitForStuffHappening() (<-chan bool, error)
}

ExampleService is an example service that we want to wait for in the FSM.

type ExampleStore

type ExampleStore interface {
	StoreStuff() error
}

ExampleStore is an example store that we want to use in our exitFunc.

type FixedSizeSlice

type FixedSizeSlice[T any] struct {
	sync.Mutex
	// contains filtered or unexported fields
}

FixedSizeSlice is a slice with a fixed size.

func NewFixedSizeSlice

func NewFixedSizeSlice[T any](maxLen int) *FixedSizeSlice[T]

NewFixedSlice initializes a new FixedSlice with a given maximum length.

func (*FixedSizeSlice[T]) Add

func (fs *FixedSizeSlice[T]) Add(element T)

Add appends a new element to the slice. If the slice reaches its maximum length, the first element is removed.

func (*FixedSizeSlice[T]) Get

func (fs *FixedSizeSlice[T]) Get() []T

Get returns a copy of the slice.

func (*FixedSizeSlice[T]) GetElement

func (fs *FixedSizeSlice[T]) GetElement(index int) T

GetElement returns the element at the given index.

type InitStuffRequest

type InitStuffRequest struct {
	Stuff string
	// contains filtered or unexported fields
}

InitStuffRequest is the event context for the InitFSM state.

type InitialWaitOption

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

InitialWaitOption is an option that can be passed to the WaitForState function to wait for a given duration before checking the state.

type Notification

type Notification struct {
	// PreviousState is the state the state machine was in before the event
	// was processed.
	PreviousState StateType
	// NextState is the state the state machine is in after the event was
	// processed.
	NextState StateType
	// Event is the event that was processed.
	Event EventType
	// LastActionError is the error returned by the last action executed.
	LastActionError error
}

Notification represents a notification sent to the state machine's notification channel.

type Observer

type Observer interface {
	Notify(Notification)
}

Observer is an interface that can be implemented by types that want to observe the state machine.

type State

type State struct {
	// EntryFunc is a function that is called when the state is entered.
	EntryFunc func()
	// ExitFunc is a function that is called when the state is exited.
	ExitFunc func()
	// Action is the action to be executed in the state.
	Action Action
	// Transitions is a mapping of events and states.
	Transitions Transitions
}

State binds a state with an action and a set of events it can handle.

type StateMachine

type StateMachine struct {
	// Context represents the state machine context.
	States States

	// ActionEntryFunc is a function that is called before an action is
	// executed.
	ActionEntryFunc func(Notification)

	// ActionExitFunc is a function that is called after an action is
	// executed, it is called with the EventType returned by the action.
	ActionExitFunc func(NextEvent EventType)

	// LastActionError is an error set by the last action executed.
	LastActionError error

	// DefaultObserver is the default observer that is notified when the
	// state machine transitions between states.
	DefaultObserver *CachedObserver
	// contains filtered or unexported fields
}

StateMachine represents the state machine.

func NewStateMachine

func NewStateMachine(states States, observerSize int) *StateMachine

NewStateMachine creates a new state machine.

func NewStateMachineWithState

func NewStateMachineWithState(states States, current StateType,
	observerSize int) *StateMachine

NewStateMachineWithState creates a new state machine and sets the initial state.

func (*StateMachine) HandleError

func (s *StateMachine) HandleError(err error) EventType

HandleError is a helper function that can be used by actions to handle errors.

func (*StateMachine) RegisterObserver

func (s *StateMachine) RegisterObserver(observer Observer)

RegisterObserver registers an observer with the state machine.

func (*StateMachine) RemoveObserver

func (s *StateMachine) RemoveObserver(observer Observer) bool

RemoveObserver removes an observer from the state machine. It returns true if the observer was removed, false otherwise.

func (*StateMachine) SendEvent

func (s *StateMachine) SendEvent(event EventType, eventCtx EventContext) error

SendEvent sends an event to the state machine. It returns an error if the event cannot be processed in the current state. Otherwise, it only returns nil if the event for the last action is a no-op.

type StateType

type StateType string

StateType represents an extensible state type in the state machine.

type States

type States map[StateType]State

States represents a mapping of states and their implementations.

type Transitions

type Transitions map[EventType]StateType

Transitions represents a mapping of events and states.

type WaitForStateOption

type WaitForStateOption interface {
	// contains filtered or unexported methods
}

WaitForStateOption is an option that can be passed to the WaitForState function.

func WithAbortEarlyOnErrorOption

func WithAbortEarlyOnErrorOption() WaitForStateOption

WithAbortEarlyOnErrorOption creates a new AbortEarlyOnErrorOption.

func WithWaitForStateOption

func WithWaitForStateOption(initialWait time.Duration) WaitForStateOption

WithWaitForStateOption creates a new InitialWaitOption.