fsm

Documentation

Overview

Copyright 2024 Robert Terhaar <robbyt@robbyt.net>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2024 Robert Terhaar <robbyt@robbyt.net>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2024 Robert Terhaar <robbyt@robbyt.net>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright 2024 Robert Terhaar <robbyt@robbyt.net>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• Variables
• type Machine
  • func New(logger *slog.Logger, initialState string, allowedTransitions TransitionsConfig) (*Machine, error)
  • func (fsm *Machine) GetState() string
  • func (fsm *Machine) GetStateChan(ctx context.Context) <-chan string
  • func (fsm *Machine) SetChanBufferSize(size int)
  • func (fsm *Machine) SetState(state string) error
  • func (fsm *Machine) Transition(toState string) error
  • func (fsm *Machine) TransitionIfCurrentState(fromState, toState string) error
• type TransitionsConfig

Constants

const (
	StatusNew       = "StatusNew"
	StatusBooting   = "StatusBooting"
	StatusRunning   = "StatusRunning"
	StatusReloading = "StatusReloading"
	StatusStopping  = "StatusStopping"
	StatusStopped   = "StatusStopped"
	StatusError     = "StatusError"
)

Collection of common statuses

Variables

var ErrAvailableStateData = errors.New("available state data is malformed")

ErrAvailableStateData is returned when the available state data is not correctly formatted

var ErrCurrentStateIncorrect = errors.New("current state is incorrect")

ErrCurrentStateIncorrect is returned when the current state does not match with expectations

var ErrInvalidState = errors.New("state is invalid")

ErrInvalidState is returned when the state is somehow invalid

var ErrInvalidStateTransition = errors.New("state transition is invalid")

ErrInvalidStateTransition is returned when the state transition is invalid

var TypicalTransitions = TransitionsConfig{
	StatusNew:       {StatusBooting, StatusError},
	StatusBooting:   {StatusRunning, StatusError},
	StatusRunning:   {StatusReloading, StatusStopping, StatusStopped, StatusError},
	StatusReloading: {StatusRunning, StatusError},
	StatusStopping:  {StatusStopped, StatusError},
	StatusStopped:   {StatusNew, StatusError},
	StatusError:     {StatusNew, StatusStopped},
}

TypicalTransitions is a common set of transitions, useful as a guide. Each key is the current state, and the value is a list of valid next states the FSM can transition to.

Types

type Machine

type Machine struct {
	Logger *slog.Logger
	// contains filtered or unexported fields
}

Machine represents a finite state machine that tracks its current state and manages state transitions.

func New

func New(logger *slog.Logger, initialState string, allowedTransitions TransitionsConfig) (*Machine, error)

New initializes a new finite state machine with the specified initial state and allowed state transitions.

Example of allowedTransitions:

allowedTransitions := TransitionsConfig{
	StatusNew:       {StatusBooting, StatusError},
	StatusBooting:   {StatusRunning, StatusError},
	StatusRunning:   {StatusReloading, StatusExited, StatusError},
	StatusReloading: {StatusRunning, StatusError},
	StatusError:     {StatusNew, StatusExited},
	StatusExited:    {StatusNew},
}

func (*Machine) GetState

func (fsm *Machine) GetState() string

GetState returns the current state of the finite state machine.

func (*Machine) GetStateChan

func (fsm *Machine) GetStateChan(ctx context.Context) <-chan string

GetStateChan returns a channel that emits the FSM's state whenever it changes. The channel is closed when the provided context is canceled. If the channel is not being read, the status changes will be dropped, and a warning will be logged.

func (*Machine) SetChanBufferSize

func (fsm *Machine) SetChanBufferSize(size int)

SetChanBufferSize sets the buffer size for the state change channel.

func (*Machine) SetState

func (fsm *Machine) SetState(state string) error

SetState updates the FSM's state to the provided state, bypassing the usual transition rules. It only succeeds if the requested state is defined in the allowedTransitions configuration.

func (*Machine) Transition

func (fsm *Machine) Transition(toState string) error

Transition changes the FSM's state to toState. It ensures that the transition adheres to the allowed transitions. Returns ErrInvalidState if the target state is undefined, or ErrInvalidStateTransition if the transition is not allowed.

func (*Machine) TransitionIfCurrentState

func (fsm *Machine) TransitionIfCurrentState(fromState, toState string) error

TransitionIfCurrentState changes the FSM's state to toState only if the current state matches fromState. This returns an error if the current state does not match or if the transition is not allowed.

type TransitionsConfig

type TransitionsConfig map[string][]string