Repository files navigation

The GFSM library provides a simple andfast implementation of a Finite State Machine (FSM) for Go. The library adopts C++-style approaches with a primary focus on speed and simplicity, which is the main difference from alternative Go FSM implementations likelooplab/fsm. You can also create a visual representation of an FSM using thegfsm_uml generator.

Two Phase Commit protocol (TPC protocol) is an excellent example of Finite State Machine use case.

NOTE: Full example is inexamples/two-phase-commit/main.go folder.

Having the following State Machine:

graph TD;    Init-->Wait;    Wait-->Abort;    Wait-->Commit;

we should:

1. Enumerate all possible states
2. Describe each states
3. Describe a state machine
4. Run the state machine

The GFSM library can consume anycomparable interface as a states enumerator, but the recommended approach is usingint-based types. For example, we can define typeState with all TPC protocol-related states.

typeStateintconst (InitState=iotaWaitAbortCommit)

Each State is represented by its uniquestateID,action handler, and list of possibletransitions. Each state can have a unique handler that supportsStateAction interface:

typeStateAction[StateIdentifiercomparable]interface {OnEnter(smCtxStateMachineContext)OnExit(smCtxStateMachineContext)Execute(smCtxStateMachineContext,eventCtxEventContext)StateIdentifier}

WhereOnEnter andOnExit will be called once on the state entering or exiting respectfully, andExecute is the call that the state machine routes to the current state fromStateMachineHandler.ProcessEvent(...).

Any State Machine can have its unique context. For the TPC protocol, it's important to have information about the voting process, like the expected voter count and committed ID.

typecoordinatorContextstruct {commitIDstringpartCntint}

StateMachineContext is stored inside the constructedStateMachineHandler object and will be passed to each state on any calls (OnEnter,OnExit, andExecute).

To create a new state machine,StateMachineBuilder should be used. To build a TPC protocol state machine, you can use the following approach:

sm:=gfsm.NewBuilder[State]().SetDefaultState(Init).SetSmContext(&coordinatorContext{partCnt:3}).RegisterState(Init,&initState{}, []State{Wait}).RegisterState(Wait,&waitState{}, []State{Abort,Commit}).RegisterState(Abort,&responseState{keepResp:Abort,    }, []State{Init}).RegisterState(Commit,&responseState{keepResp:Commit,    }, []State{Init}).Build()

After the construction, the state machine shall be executed and terminated on exit:

sm.Start()defersm.Stop()

To process an event, the state machine object implements aProcessEvent(eventCtx EventContext) error call, whereeventCtx can be any data that the state will process internally as primary input data.

err:=sm.ProcessEvent(commitRequest{"commit_1"})

During the event processing, the state machine will callExecute with the passedEventContext andStateMachineContext. Based on these data, the state can decide either to keep the current state (Init in the example below) or make a switch (Wait) by returning the new expected state.

func (s*initState)Execute(smCtx gfsm.StateMachineContext,eventCtx gfsm.EventContext)State {cCtx:=smCtx.(*coordinatorContext)req,ok:=eventCtx.(commitRequest)if!ok {// ...returnInit}// ...returnWait}