Parameterised Triggers and Re-Entrant States in Stateless v2

niblumha — Sun, 30 Aug 2009 04:34:51 GMT

Since working on a clinical outcomes review system a couple of years ago, I’ve been aware of the gap between simple hand-coded workflows and the full-blown workflow tools.

Stateless embodies the idea that a state machine can use closures to implement workflow without taking on persistence responsibilities. So long as all of the data used to drive the state machine is external to it, a regular ORM or other persistence mechanism can deal with identity, persistence and transactional issues. This substantially reduces the technical complexity of the framework.

As a ‘fun’ project, I haven’t done much other than maintain the site since the first version was finished. The second version extends the paradigm just a little, but in doing so makes a wider range of scenarios cleanly approachable.

To illustrate the new features I’ll draw on Scott Allen’s nifty bug tracker example for Windows Workflow.

Parameterised Triggers

The triggers that drive transitions in a state machine are approximately analogous to events or commands. Like events and commands, triggers can be associated with parameters.

When a bug is assigned, the parameter may be the assignee;
When an order is cancelled, the parameter may be the reason;
etc.

Modelling these details in Stateless, I adopted the some design goals and constraints:

Retain the existing simple syntax for non-parameterised triggers;
Execute parameter-driven logic during the transition, i.e. after the exit events for the last state have fired;
Make it clear to the user exactly when parameter-driven logic will execute;
Control interference between parameter-driven logic and guard conditions;
Ensure parameter type-safety at compile time.

New APIs

To associate parameters with a trigger, StateMachine provides the SetTriggerParameters() generic methods:

SetTriggerParameters() accepts one generic parameter for each of the trigger’s parameters, so in this case the Assign trigger is being associated with a single parameter of type string.

This method is called once, when the state machine is being configured.

The return value in this case is a TriggerWithParameters<string> object that lets us invoke the Fire() method in a strongly-typed way:

The C# compiler will use inference to determine that the parameter to the trigger is of type string. Attempting to fire assignTrigger with any other parameters will be rejected at compile-time.

Now, all of this would be fairly pointless if Fire() was the only place that the parameters needed checking. However, the firing of the trigger is only half of the story.

When the machine transitions into the new state, logic based on the trigger parameters will need to run:

Because assignTrigger is provided to the OnEntryFrom() method, the compiler knows that the provided entry action accepts a single parameter of type string.

Putting everything together behind the facade of a domain object leads to a natural, understandable design:

A more complete example is in the Stateless Mercurial repository.

Alternatives

One alternative I considered but later discarded was to parameterise the states rather than the triggers, something that seems to be more established in traditional state machine models. After a good deal of unsuccessful experimentation I concluded that state parameterisation isn’t as useful as the trigger-based version.

Re-Entrant States

Stateless encourages you to attach program logic to entry and exit events for the states in your state machine.

One of the edge cases that the bug tracker example reveals is re-initialisation of an already active state. When the bug is assigned, an email might be sent to the assignee. If Assign() is called again, to reassign the bug to someone else, it makes sense to re-initialise the Assigned state by executing the exit actions then executing the entry actions again.

To enable this behaviour for a state, the PermitReentry() method is supplied:

The previous version of Stateless considered a self-transition to be the same as an ignored trigger. Version 2 requires that self-transitions are either explicitly ignored, or configured as re-entrant.

Next?

These small additions were actually quite a challenge, but Stateless is still a very small library. One idea I’m toyed with is to use it as a ‘kernel’ for higher-level state machine functionality, e.g. an XML or DSL-driven framework. If you have ideas or requests, feel free to visit the UserVoice forum!

State Machines in Domain Models

niblumha — Thu, 16 Apr 2009 09:52:37 GMT

I was reminded today of Stateless, a little project that I’m quite fond of.

Stateless is a hierarchical state machine framework based on Simple State Machine for Boo, but configured using C# 3.0.

When I announced Stateless last year, I hardly even explained its purpose, let alone its tongue-in-cheek name. I think I owe it a better start in life!

If you’re doing heavy duty state-machine based programming (writing parsers, radiotherapy machines or flight control systems) then Stateless is probably not what you’re looking for.

If you’re doing domain-driven design, and anxious about the ugly nested ‘if’ and ‘switch’ statements building up around _state variables, Stateless can help.

State-based behaviour is awkward because despite careful programming, it is difficult to see how the states relate to each other. Adding and removing states is error-prone, repetition creeps in, and refactoring gets tricky.

There’s more than one way out. The State pattern can be one very elegant solution.

Another solution that works nicely is to create a declarative model of the states, transitions and associated actions, and have a state machine framework ‘run’ it for you. This is the approach enabled by Stateless.

The Telephone Call state chart is broken down into the following states and triggers:

You can use any types to represent states and triggers, but enumerations are convenient.

After creating an instance of StateMachine, each state is configured independently. Configuration for a state revolves around the triggers that the state can accept, the transitions that these triggers will cause (to new states) and the actions that will be performed when entering or leaving a state.

Once the state machine has been configured, the triggers can be ‘fired’. The side-effects from firing triggers drive the program.

You might wonder how this fits into a domain model. StateMachine certainly doesn’t belong on the public surface area of your domain model classes. It’s an implementation detail – like, for example, StringBuilder or Regex.

Users of the class interact with the state machine indirectly, by calling public methods on the domain object.

The state machine is configured to call two methods when entering and leaving the Connected state (see the configuration above.)

Stateless does all of the heavy lifting. For example, the state machine understands that because OnHold is a sub-state of Connected, the Connected entry/exit actions aren’t called when moving between these two states.

Now for a justification of the silly name…

Notice the way that the _state field belongs to the PhoneCall object, rather than the state machine? This allows the field to be easily mapped to a database column by NHibernate or your ORM of choice. The state machine reads and writes the _state value using the pair of lambdas provided to its constructor. In that sense you can almost say that the state machine itself is ‘stateless’. Almost.

There’s some more basic documentation and a source download at the site. I hope you’ll try Stateless and be pleasantly surprised by how expressive it can make your code. Search your domain model for “State” or “Status” and see what Stateless can do!

This post also comes with a challenge: Stateless is fairly simple and very hackable - if you’re a fluent-interface aficionado and think you can improve the configuration API, join the project!