Show HN: State Trooper – Tiny, no frills state machine for Go(github.com)
github.com
Show HN: State Trooper – Tiny, no frills state machine for Go
https://github.com/hishamk/statetrooper
Needed to isolate a bit of DRY logic for some of my projects. Might be of use to others out there.
62 comments
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
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
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.
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.
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.
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.
Re the visualization, I think that would be cool. I might give that a shot.
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.
you mean like:
> Add valid transitions between states:
> `fsm.AddRule(CustomStateEnumA, CustomStateEnumB)`
> `fsm.AddRule(CustomStateEnumB, CustomStateEnumC)`
> Add valid transitions between states:
> `fsm.AddRule(CustomStateEnumA, CustomStateEnumB)`
> `fsm.AddRule(CustomStateEnumB, CustomStateEnumC)`
No.
The README has an example of shipment, so let’s think about that. It is a bad example though because it just has packed → shipped → delivered, which is not a real business process.
Let’s say you’re a seller, as opposed to UPS or FedEx. The first thing that happens is a customer makes an order. What happens next? Well, the customer can cancel their order. Or the order can be sent and then the customer can ask for a refund. Let’s try to model it:
Ordered + cancelled → cancelled
Ordered + warehouse packing → packed
Packed + cancelled → cancelled
Packed + warehouse handed package to shipper → shipped
Shipped + cancelled → too late, it’s still in the shipped state
Shipped + return request → awaiting return
Awaiting return + received return → refund
Shipped + received return → no RMA, so no refund. No state change.
Shipped + 30 days → archived
Etc. I am too lazy to do the full model, but you start to get the idea. The important thing is that actions happen from outside the system and then they cause state transitions based on what the current state is. Sometimes the system just stays in the state it is already is in, and sometimes the system moves backwards. Some actions can’t happen in certain states (can’t get something back before it goes out, can’t dismiss a closed modal dialog), but that’s not because of business logic but because of the real world. The business logic only enforces itself, not the world.
The README has an example of shipment, so let’s think about that. It is a bad example though because it just has packed → shipped → delivered, which is not a real business process.
Let’s say you’re a seller, as opposed to UPS or FedEx. The first thing that happens is a customer makes an order. What happens next? Well, the customer can cancel their order. Or the order can be sent and then the customer can ask for a refund. Let’s try to model it:
Ordered + cancelled → cancelled
Ordered + warehouse packing → packed
Packed + cancelled → cancelled
Packed + warehouse handed package to shipper → shipped
Shipped + cancelled → too late, it’s still in the shipped state
Shipped + return request → awaiting return
Awaiting return + received return → refund
Shipped + received return → no RMA, so no refund. No state change.
Shipped + 30 days → archived
Etc. I am too lazy to do the full model, but you start to get the idea. The important thing is that actions happen from outside the system and then they cause state transitions based on what the current state is. Sometimes the system just stays in the state it is already is in, and sometimes the system moves backwards. Some actions can’t happen in certain states (can’t get something back before it goes out, can’t dismiss a closed modal dialog), but that’s not because of business logic but because of the real world. The business logic only enforces itself, not the world.
No.
The README has an example of shipment, so let’s think about that. It is a bad example though because it just has packed → shipped → delivered, which is not a real business process.
Let’s say you’re a seller, as opposed to UPS or FedEx. The first thing that happens is a customer makes an order. What happens next? Well, the customer can cancel their order. Or the order can be sent and then the customer can ask for a refund. Let’s try to model it:
Ordered + cancelled → cancelled Ordered + warehouse packing → packed Packed + cancelled → cancelled Packed + warehouse handed package to shipper → shipped Shipped + cancelled → too late, it’s still in the shipped state Shipped + return request → awaiting return Awaiting return + received return → refund Shipped + received return → no RMA, so no refund. No state change. Shipped + 30 days → archived
Etc. I am too lazy to do the full model, but you start to get the idea. The important thing is that actions happen from outside the system and then they cause state transitions based on what the current state is. Sometimes the system just stays in the state it is already is in, and sometimes the system moves backwards. Some actions can’t happen in certain states (can’t get something back before it goes out, can’t dismiss a closed modal dialog), but that’s not because of business logic but because of the real world. The business logic only enforces itself, not the world.
The README has an example of shipment, so let’s think about that. It is a bad example though because it just has packed → shipped → delivered, which is not a real business process.
Let’s say you’re a seller, as opposed to UPS or FedEx. The first thing that happens is a customer makes an order. What happens next? Well, the customer can cancel their order. Or the order can be sent and then the customer can ask for a refund. Let’s try to model it:
Ordered + cancelled → cancelled Ordered + warehouse packing → packed Packed + cancelled → cancelled Packed + warehouse handed package to shipper → shipped Shipped + cancelled → too late, it’s still in the shipped state Shipped + return request → awaiting return Awaiting return + received return → refund Shipped + received return → no RMA, so no refund. No state change. Shipped + 30 days → archived
Etc. I am too lazy to do the full model, but you start to get the idea. The important thing is that actions happen from outside the system and then they cause state transitions based on what the current state is. Sometimes the system just stays in the state it is already is in, and sometimes the system moves backwards. Some actions can’t happen in certain states (can’t get something back before it goes out, can’t dismiss a closed modal dialog), but that’s not because of business logic but because of the real world. The business logic only enforces itself, not the world.
I don’t like that name.
IMO, AddValidTransition would be way better. I think I would go for AddTransition, though. It’s not as if there’s also a way to add invalid transitions.
IMO, AddValidTransition would be way better. I think I would go for AddTransition, though. It’s not as if there’s also a way to add invalid transitions.
They should be named and other transitions disallowed.
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?
If your only reasoning behind releasing an open source project is to receive uncritical accolades just for producing open source, then I think you need to examine your motives and seriously question why you expected this deference in the first place.
Commenters like you are why people don’t give honest feedback. Why review something for free when someone like you is unable to accept honest feedback even if it is critical.
[deleted]
If you post your project on a public forum with a comment section, you should expect some people to be critical and suggest things, no matter what it is or how much it costs.
Perhaps the real issue is commenters like GP is why YOU don't share things?
Perhaps the real issue is commenters like GP is why YOU don't share things?
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.
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.
May I suggest for a logo: A directed graph in the form of a sheriff's star badge
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
Ha! Not bad at all.
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.
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.
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.
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.
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
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:
Here's a state machine for an (echo) server that is intended to be mapped to epoll or libiouring:
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);
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 }
That is a description of flow-based programming, minus the generalization to "arbitrary packets of data in bounded buffers" - that is, your only data type is true/false and your only buffer size is 1, which lets you get some very clean syntax on it. It's a good invention!
FBP adapts the physical concept of unit record machines that operate over punchcard stacks, which predisposes it to thinking in terms of processing and transforming richer data like "characters in a string" or "records in an array", but it basically works for truth-signalling logic too - let truth packets wait in a buffer, and then when the node signals that the packets are able to move, that is the transition.
The emphasis does differ in that if we are thinking "FSM", the rest of the program and the data it handles have been abstracted, while if we are thinking "FBP" we're engaged with designing specific machines to connect together in terms of I/O, which is more helpful when you have a library of data operations to reuse.
FBP adapts the physical concept of unit record machines that operate over punchcard stacks, which predisposes it to thinking in terms of processing and transforming richer data like "characters in a string" or "records in an array", but it basically works for truth-signalling logic too - let truth packets wait in a buffer, and then when the node signals that the packets are able to move, that is the transition.
The emphasis does differ in that if we are thinking "FSM", the rest of the program and the data it handles have been abstracted, while if we are thinking "FBP" we're engaged with designing specific machines to connect together in terms of I/O, which is more helpful when you have a library of data operations to reuse.
Thank you syntheweave for an interesting reply.
You're right about the buffers with a truth value in a buffer. I actually use a style of promises or my own count down latch.
I am inspired by Prolog and Drools, a rule engine. I want to "fire" and "retract" facts and the state machine shall work out what to do next.
Here's something that I find especially useful about the formulation: the state machine only moves in one direction, from left to right, but there are multiple transition signals available (facts/atoms) that can be fired to cause the state machine to move forwards.
If you define multiple independent state machines it should be possible to detect "stuck states" where it is impossible for the state machine to continue progressing! This is useful for liveness analysis.
I want the state machine formulation to be useful in designing distributed systems such as Raft.
You're right about the buffers with a truth value in a buffer. I actually use a style of promises or my own count down latch.
I am inspired by Prolog and Drools, a rule engine. I want to "fire" and "retract" facts and the state machine shall work out what to do next.
Here's something that I find especially useful about the formulation: the state machine only moves in one direction, from left to right, but there are multiple transition signals available (facts/atoms) that can be fired to cause the state machine to move forwards.
If you define multiple independent state machines it should be possible to detect "stuck states" where it is impossible for the state machine to continue progressing! This is useful for liveness analysis.
I want the state machine formulation to be useful in designing distributed systems such as Raft.
love it! shutup and take my money/adoption/usage/attention! ha
no but seriously, sounds like a good/useful plan/approach. please let me know if you share out a spec or impl sometime
BONUS points for a Golang or C lib
no but seriously, sounds like a good/useful plan/approach. please let me know if you share out a spec or impl sometime
BONUS points for a Golang or C lib
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.
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.
func (fsm *FSM[T]) Transition(...) {
...
fsm.Transitions[time.Now()] = Transition[T]{
FromState: *fsm.CurrentState,
ToState: targetState,
Timestamp: &tn,
Metadata: metadata,
}
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.
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
I am actually angry at how good the project name is.
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.
But yes, his name pisses me off because I didnt think of it either.
Thanks for this. I like the simplicity!
enums with associated values (like in swift) really are the thing i miss the most in go.
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.
I really don't get how one can suggest the iota const dance with a straight face as an alternative.
what do you think would happen if there was a comment about go on the internet that you somehow didn't see, and to which you weren't able to reply with a sarcastic and sneering dismissal?
probably some serious kind of disaster, right?
probably some serious kind of disaster, right?
At crazy as it might seem, I do miss a lot.
Then again, too busy reading papers.
Then again, too busy reading papers.
so, i had a look because i wondered if you were joking or not, but algol 60 doesn't seem to have enums (putting it here just in case someone else may read this conversation)
[deleted]
wahnfrieden(1)
giraffe_lady(2)