Show HN: State Trooper – Tiny, no frills state machine for Go

[hishamk]

Needed to isolate a bit of DRY logic for some of my projects. Might be of use to others out there.

[TheSwordsman]

This state machine is inherently unsafe for concurrent use, because the CurrentState and Transitions fields aren't completely protected by a mutex. You already have an unexported mutex that you lock when mutating those fields, but then consumers trying to read those exported fields are not able to lock the same mutex to prevent concurrent read/write operations.

You should not export those fields, and instead make them available via methods where the reads are protected by the mutex. You'll probably also need to make a copy of the map since it's a reference type, OR make the accessor take the key name and fetch the value directly from the map and return it. I learned this when I wrote a similar simple state machine in Go ~7 years ago. :)

I'd also make sure to return `T` from the CurrentState accessor method and not `*T`, just to make it easier for consumers to do comparison operations with the returned result.

Reference on Go memory safety: https://go.dev/ref/mem

[hishamk]

Thank you so much for this head's up. I've just pushed out a new update that covers this and a few other changes.

[jupp0r]

Nice job. In my own usage of state machine libraries over the years I have found that for complex use cases, it's definitely helpful to have event-based transition dispatching be part of the library. The great benefit of FSMs is that you can express in data a lot of aspects that you would normally express in code. Not knowing what event needs to happen to transition to one state vs another leaves out a lot of the benefits that you get from designing your code around FSMs.

That being said, I appreciate the simplicity and it's a totally fine choice to leave out event based dispatch for less complex use cases!

One thing that has been mentioned here already: it's super helpful to have your library output a diagram file to visualize the FSM. This is a really great way to keep code and documentation in sync always.

[hishamk]

Thank you. The focus was on simplicity and handling less complex scenarios. In my current projects the business logic lends itself to sitting outside the FSM/State Trooper. The logic dictates the transitions at arms length to the FSM. The FSM does not carry on any particular business logic, it just enforces the transition rules from one state to any number of possible states - hence why I've included the metadata aspect to embed info about the reason for a transition.

Re the visualization, I think that would be cool. I might give that a shot.

[earthboundkid]

A state machine should have more than states. It also needs actions which cause transitions. The API should be about writing out which new state an action causes given a base state. Eg you have a modal with a button and it can be clicked or dismissed. In the open state, click and dismiss cause close, and in the closed state, click causes open. Anyway, the whole thing is only valuable once you have actions.

[BSEdlMMldESB]

you mean like:

> Add valid transitions between states:

> `fsm.AddRule(CustomStateEnumA, CustomStateEnumB)`

> `fsm.AddRule(CustomStateEnumB, CustomStateEnumC)`

[packetslave]

Commenters like you are why people don't share thing. Why make something available for free when someone like you is just going to come along and shit on it?

[pokstad]

Looks cool. It’d be nice if you could output the FSM to some kind of diagram markup (plantuml or mermaidjs).

[hishamk]

Thanks for the feedback. I've added a mermaidjs code generator for the ruleset.

[rowls66]

Interesting. I wrote almost the same code for work a couple of weeks ago.

Not sore, but it looks like the Transition function has a race condition. It calls CanTansition() before acquiring the mutex lock. I think this could lead to illegal state transitions.

[hishamk]

Thanks for this. You are indeed correct. I've pushed a fix and also added a race test to confirm the fix.

[hmcamp]

Good eye! Thanks for pointing this out.

[easeout]

May I suggest for a logo: A directed graph in the form of a sheriff's star badge

[icyfox]

Midjourney actually does pretty well with this one (needs a bit of cleanup but shockingly useful as a first draft): https://imgur.com/a/GKzx3vX

[klabb3]

I saw the benchmark which seemed crazy (3us per transition and allocations). So looked quickly at the code.

Recommend putting the tracking of previous states in a separate optional debugging type so you don’t have to pay the cost in general. Oh and using time stamps as a key is kinda weird, but even weirder in Go where maps are non-deterministically enumerable.

Otherwise, seems like a good use of generics, given Golangs particular take on it.

[hishamk]

Thanks for the feedback.

The benchmark was for six transitions. I've now updated a few things and added new benchmarks.

I also got rid of timestamps for the map keys - it's back to a regular slice. In retrospect, that was a tad bit off, I agree.

[syngrog66]

A state machine (specifically a FSM) class is something I end up having to reinvent in every new language I've adopted. Such a useful pattern whose need comes up repeatedly. Especially in games/sims or in anything with a GUI. Since I've been making both for decades I have a lot of homegrown FSM classes sitting around. :-p

[samsquire]

I am working on a state machine formulation/notation that can be executed.

The runtime is multithreaded and parallel.

The idea is to execute the following state machine:

  thread(s) = fact(variable) | send(message) | receive(message2);
  thread(r) = fact(variable) | receive(message) | send(message2);

This program waits until thread(s) is true in another thread until thread(r) is true, everything left of the equals symbol needs to be true before it passes to the next group of facts after the = symbol. Then it waits for "fact(variable)" to be fired, then when all those atoms are true, the state transitions past the pipe symbol and does a send(message) while the other thread does a receive(message) and then the process is repeated in the opposite direction. I've not shown it here, but you can wait for multiple facts to be true too.

Here's a state machine for an (echo) server that is intended to be mapped to epoll or libiouring:

   accept | { submit_recv! | recv | submit_send } { submit_send! | send | submit_recv }

The curly brackets means parallel state machines that run independently, like a fork.

[hishamk]

Thanks for everyone's feedback. I've pushed out a few changes:

1- Regular slice instead of timestamp-keyed map. That didn't make sense in retrospect. 2- Better benchmarks. 3- Non-exported current state and transitions. Mutexed getters to avoid concurrency issues. 4- Variadic rule parameters. 5- Better example.

[victorbjorklund]

Great name!

[hishamk]

Thank you!

[preseinger]

    func (fsm *FSM[T]) Transition(...) {
      ...
      fsm.Transitions[time.Now()] = Transition[T]{
       FromState: *fsm.CurrentState,
       ToState:   targetState,
       Timestamp: &tn,
       Metadata:  metadata,
      }

does fsm.Transitions grow without bounds?

[MobileVet]

Nice work!! I have always appreciated the clarity of FSMs since first learning about them in college. They are a great way to think about a system's state and given X input, clearly define the next state. This makes them very easy to test as well.

[preseinger]

you define Transition over T comparable, but there is no guarantee that comparable implements json.Marshaler, so FSM's MarshalJSON and UnmarshalJSON don't really work

[naikrovek]

I am actually angry at how good the project name is.

[jnordwick]

I've written 2 in C++ for different projects at companies State Farm and State of Decay. I'm trying to write one that kind of inverts things and calling it Enemy of the State.

But yes, his name pisses me off because I didnt think of it either.

[hmcamp]

Thanks for this. I like the simplicity!

[bsaul]

enums with associated values (like in swift) really are the thing i miss the most in go.

[pjmlp]

Yeah, yet another Algol 60 missing feature.

I really don't get how one can suggest the iota const dance with a straight face as an alternative.

[Solvency]

Rust - A memory safe programming language

wahnfrieden: Why the iron oxide name? Besides the fact that it's a pun. Is the code written with it always bound to be rusty and old?

[brigadier132]

This would be hilarious if it was satire

[oofta-boofta]

Tell me your a DEI Director without actually telling me you're a DEI Director.