I consider Statemachines to be a programming gem. An invaluable tool for the software craftsman’s toolkit. It’s not everyday that a Statemachine comes in handy, but for some problems Statemachines are the most elegant and robust solution you’ll find.

Perhaps you learned about Finite State Automata in school but could use a refresher. Or perhaps you’ve never heard of these crazy Statemachines in your entire software career and your curiosity is piqued. This is a place to learn more.

I’ve found Statemachines so valuable I’ve build a Ruby framework to build Statemachines. I hope you find this tool valuable… but for that to happen you have to understand Statemachines.

To that end, this is the first installment of a complete Statemachine lesson. Statemachines are simple. You’ll see.

States and Transitions:

Above is a UML diagram of the Statemachine the runs a simple vending machine. We can see that there are two rectangles with rounded corners. These are States.

The vending machine has two possible states, Waiting and Paid. At any given time during execution, the vending machine will be in one of these states.

Note the arrows going from one state to another. These are called Transitions. Transitions are how Statemachines change state. Also note that each transition is labeled with an Event. Events are the input to Statemachines. They invoke transitions.

For example, when the vending machine is in the Waiting state and the dollar event is received, the Statemachine will transition into the Paid state. When in the paid state and the selection event is received, the Statemachine will transition back into the Waiting state.

This should seem reasonable. Imagine a real vending machine. When you walk up to it it’s waiting for you to put money in. You pay by sticking a dollar in and then you make your selection. After this happy transaction, the vending machine waits for the next client.

This scenario is not the only possibility though. Statemachine are very helpful in examining all possible flows through the system. Take the Waiting state. We don’t normally expect users to make selections if they haven’t paid but it’s a possibility.

As you can see this unexpected event is handled by our vending machine. It will simply continue to wait for your dollar. And it would be foolish for someone to put more money in the vending machine if they’ve already paid. Foolish or not, you and I know it happens.

Our vending machine handles this graciously by taking the money and allowing the user to make a selection for the fist dollar they supplied. Effectively the client loses the extra money they put in.

Implementing the Statemachine:

We have identified 3 fundamental components to a Statemachine: States, Transitions, and Events. It turns out that the simplest way to define a Statemachine is to define its transitions.

Each transition can be defined by identifying the state where it begins, the event by which is invoked, and the state where it ends. Using this scheme we can define out vending machine like so…

Defining it in ruby is not much harder:

require 'rubygems'
require 'statemachine'

vending_machine = Statemachine.build do
		trans :waiting, :dollar, :paid
		trans :paid, :selection, :waiting
		trans :waiting, :selection, :waiting
		trans :paid, :dollar, :paid
end

The above snippet assumes you have the Statemachine gem installed.

Mac users: sudo gem install statmachine
Windows users: gem install Statemachine

The outcome of this code an instance of Statemachine stored in the variable named vending_machine. To use our Statemachine we need to send events to it. This is done by calling methods that correspond to events.

puts vending_machine.state
vending_machine.dollar
puts vending_machine.state
vending_machine.selection
puts vending_machine.state

That’s it for the basics.

This concludes Part 1 of the lessing. Next we’ll learn how to make our Statemachine more functional with by adding actions.