Easy FSM Add-on: Makes making Finite State Machines with go-statemachine easier #4

hannahhoward · 2020-02-24T17:47:35Z

Goals

This builds somewhat off the work in go-storage-miner, somewhat from looking at other go fsm libraries https://github.com/looplab/fsm . The goal is as follows: provide a simple, mostly type safe, readable way to build finite state machines that work with go-statemachine.

Implementation

There are a few innovations here but:

Provide a simple syntax for defining events -- the state transitions they implement plus any additional state modifications they make. The state transitions, found in eventbuilder.go can be defined as:

FromMany - To
FromAny - To
From - To
any of the above - ToNoChange (just trigger the state handler again
you can do multiple per event (i.e. From-To + From-To if different states trigger different destinations)

A state is any object, but it must have specified field that acts as a "key" to represent its uniquely identifiable state, and which is managed by the FSM according to events dispatched.
Provide a tool for easily defining handlers for each state - all handlers are defined interms of

Context -- for dispatching events & accessing go context
Environment - a shared item for all statemachines that gives access to any external dependencies
State - current value of the state being tracked

Provide an optional notification channel that is called any time an event is successfully applied along with the state connected to it
There is also a lower level event machine class (see eventmachine.go) for defining and type checking the events a state machine has, which also handles actually applying events to manage state.
There is a utility TestContext class that can be paired with an event machine to test statehandlers and the state transitions they generate atomically

For Discussion

There is as you can see, some fairly extensive use of reflect here. I am ultimately not SO worried, cause while errors in the construction of the statemachine will be caught at runtime, they'll likely be caught at the very beginning of executing the program, and early in development -- they're almost a compile error. However, one thing I'm not sure about is the event callbacks themselves. I thought of making these an interface so the parameters could be properties on a struct, and they could be compile time checked. I didn't feel like I'd gotten it exactly right which is why I haven't yet moved forward with this but, it's an option. We could potentially do away with naming events entirely and have the name be the struct, but that gets a bit weird in terms of notification.

add module for constructing statehandlers as simple finite state machines, to support readable definitions, type checking, and testing

Add the ability ot dispatch a synchronous event to the state machine and wait for a result

Use a full transition map for events to make them more flexible

support a transition that applies to any source state

Add ability to get identifier for this instance of the state machine

Allow each instance of fsm to get a unique instance of outside dependencies

remove universal events, add notifications, add params struct, make event name an interface

This reverts commit 206d210.

remove world by indentifier for simplicity, rename world to environment

add more data about why state handlers fail

add begin function from base group to fsm group

simplify builders for state, extract state machine from event machine

adds a utility class for testing state machines by allowing contexts to actually be replayed with a given event machine

shannonwells · 2020-02-25T19:30:06Z

fsm/types.go

+	// - event X does not exist
+	//
+	// - arguments don't match expected transition
+	Event(event EventName, args ...interface{}) error


In reviewing the related go-filecoin PR I found this naming confusing. Can there be some naming distinction between a fsm.Context Event and a statemachine Event? If Event initiates a state transition maybe it could be called (Start|Post|Try|Initiate|Queue)Event, or (Start|etc)Transition or something like that. Then in the go-filecoin call it would read better.

ingar

Awesome, seems nice to use this to build FSM.

One comment, I am more used to the pattern of callbacks on state transitions, not attached to events themselves. I know both are patterns in FSMs. Seems like it could be useful to have StateEntryFunc (and maybe StateExitFunc) callbacks, for things like logging errors or cleanup or whatever.

ingar · 2020-02-25T21:15:15Z

fsm/eventbuilder.go

+func (t transitionToBuilder) To(to StateKey) EventBuilder {
+	transitions := t.transitionsSoFar
+	for _, from := range t.nextFrom {
+		transitions[from] = to


In general, what do you think about emitting a warning or error even if we are clobbering previously-set callbacks or transitions?

good point!

I hate to say it thought I'd rather not mess up the fluidity of the interface I might store the error and fail when you try to construct the event machine which is delayed but preserves the DSL.

ingar · 2020-02-25T21:48:57Z

fsm/types.go

+// func applyTransition<StateType, T extends any[]>(s stateType, args ...T)
+// and then an event can be dispatched on context or group
+// with the form .Event(Name, args ...T)
+type ApplyTransitionFunc interface{}


I'm not familiar with this naming convention... this would have been be clearer to if it was named something like StateMutatorFunc or EventCallbackFunc and WithMutator(), etc. But if it's a well-known naming convention I'm cool with it.

no I just made it up will change :)

I'm leaning towards "actions" cause that is the actual FSM terminolgy for things that happen along with an event

hannahhoward · 2020-02-25T22:03:27Z

@ingar I would consider the StateHandlers to be StateEntryFunc's, effectively

Rename applyTransition to action to match actual FSM concept it represents

rename event -> trigger with context rename eventMachine -> eventProcessor rename eventProcessor.Event -> eventProcessor.Generate rename stateHandler -> stateEntryFunc

track various DSL errors in event builder so it fails when used

hannahhoward added 17 commits February 24, 2020 09:33

feat(fsm): add finite state machine module

5ac8748

add module for constructing statehandlers as simple finite state machines, to support readable definitions, type checking, and testing

feat(fsm): add synchronous event handling

da5aba1

Add the ability ot dispatch a synchronous event to the state machine and wait for a result

feat(fsm): more docs and no-transition state handlers

b253c92

refactor(fsm): switch to transition map

b1ed3ec

Use a full transition map for events to make them more flexible

feat(fsm): support fallback transitions

971ff7d

support a transition that applies to any source state

feat(fsm): add identifier getter

4f04d27

Add ability to get identifier for this instance of the state machine

feat(fsm): add world building by identifier

859924d

Allow each instance of fsm to get a unique instance of outside dependencies

refactor(fsm): switch to notifier

050f1af

remove universal events, add notifications, add params struct, make event name an interface

Revert "feat(fsm): add identifier getter"

88e6fbf

This reverts commit 206d210.

refactor(fsm): revert to single environment

532cb72

remove world by indentifier for simplicity, rename world to environment

feat(fsm): more informative statehandler errors

6733fe9

add more data about why state handlers fail

feat(fsm): add begin function to group

4545331

add begin function from base group to fsm group

refactor(fsm): builder interfaces

85461c4

simplify builders for state, extract state machine from event machine

feat(fsm): add test context util

a9094aa

adds a utility class for testing state machines by allowing contexts to actually be replayed with a given event machine

fix(fsm): doc updates and minor refactors

8c5b822

rerun ci

d855d86

ci(circle): update golangci-lint

054b5d1

hannahhoward mentioned this pull request Feb 24, 2020

Use go-statemachine + FSMs in retrieval market filecoin-project/go-fil-markets#124

Merged

shannonwells reviewed Feb 25, 2020

View reviewed changes

ingar approved these changes Feb 25, 2020

View reviewed changes

hannahhoward added 3 commits February 25, 2020 14:52

refactor(fsm): rename applyTransition to action

c91c30c

Rename applyTransition to action to match actual FSM concept it represents

refactor(fsm): a few more renames

a2059e0

rename event -> trigger with context rename eventMachine -> eventProcessor rename eventProcessor.Event -> eventProcessor.Generate rename stateHandler -> stateEntryFunc

feat(fsm): add err tracking to eventbuilder

fe83f89

track various DSL errors in event builder so it fails when used

hannahhoward merged commit e5b11df into master Feb 26, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Easy FSM Add-on: Makes making Finite State Machines with go-statemachine easier #4

Easy FSM Add-on: Makes making Finite State Machines with go-statemachine easier #4

hannahhoward commented Feb 24, 2020 •

edited

Loading

shannonwells Feb 25, 2020

ingar left a comment

ingar Feb 25, 2020

hannahhoward Feb 25, 2020

hannahhoward Feb 25, 2020

ingar Feb 25, 2020

hannahhoward Feb 25, 2020

hannahhoward Feb 25, 2020

hannahhoward commented Feb 25, 2020

Easy FSM Add-on: Makes making Finite State Machines with go-statemachine easier #4

Easy FSM Add-on: Makes making Finite State Machines with go-statemachine easier #4

Conversation

hannahhoward commented Feb 24, 2020 • edited Loading

Goals

Implementation

For Discussion

shannonwells Feb 25, 2020

Choose a reason for hiding this comment

ingar left a comment

Choose a reason for hiding this comment

ingar Feb 25, 2020

Choose a reason for hiding this comment

hannahhoward Feb 25, 2020

Choose a reason for hiding this comment

hannahhoward Feb 25, 2020

Choose a reason for hiding this comment

ingar Feb 25, 2020

Choose a reason for hiding this comment

hannahhoward Feb 25, 2020

Choose a reason for hiding this comment

hannahhoward Feb 25, 2020

Choose a reason for hiding this comment

hannahhoward commented Feb 25, 2020

hannahhoward commented Feb 24, 2020 •

edited

Loading