126 |
141 |
142 | RFQ State Machine
2 | 3 |We highlighted quite a few techniques to deal with reactive systems in Reactive Trader. There is another one, that we commonly use, that was not demonstrated. 4 | A state machine is a simple yet powerfull way of decomposing some functionality into states and a set of valid transitions between them. 5 | When you find yourself dealing for instance with user input and/or server events and see lots of branching in your code (if/switch statements) on some _state variables, chances are high that a statemachine could be introduced to simplify things.
6 | 7 |In this post we will look at a concreate usecase, we will define a state machine for it and we will see how we can organise our code around the state machnine and interact with it. I've also created a companion GitHub project where you can find the 8 | full example.
9 | 10 |Example: RFQ workflow
11 | 12 |In finance Request For Quote (RFQ) is a common mechanism used to request a price electronically: the client submits a request to the pricing server. 13 | At some point the server provides a quote (or a serie of quotes) and the client can decide to execute (HIT the price) or pass (cancel). 14 | We are going to build a state machine that would live client side, in some UI application like reactive trader, to control the state of a RFQ.
15 | 16 |The following diagram describes the different states of the RFQ and the possible transitions.
17 | 18 |
This is a visual representation of a statemachine, it contains
21 | 22 |-
23 |
- states:
24 |
-
25 |
- an initial state (at the top), 26 |
- intermediate states (requesting, quoted, Executing) 27 |
- terminal states (Error, Done, Canceled) 28 |
29 | - and transitions between states (arrows) 30 |
I find those diagrams very helpfull to think about the system, while building them I will generally go through all the states I already discovered and ask myself the following questions:
33 | 34 |-
35 |
- could anything else happen in this state? 36 |
- Any unhappy path? (ie. timeout, error, etc) 37 |
- Do we have a representation of this particular state for the corresponding UI? (if you are building a UI). 38 |
Those diagrams are also very usefull to discuss with non developers: business people, UX, etc.
41 | 42 |From diagram to code
43 | 44 |Statemachines can be implemented in many differents ways, either from scratch or using some library. 45 | For any decent size statemachine I tend to use Stateless but the recommendations that follow would stand for any library or hand written statemachine.
46 | 47 |I like to define state machines in a single place: I find that spreading the definition accross multiple files/classes makes it harder to understand.
48 | 49 |Stateless offers a nice fluent syntax to define states and possible transitions.
50 | 51 |Defining states
52 | 53 |The first thing we need to do is to define the set of states, we can use an enum for that:
54 | 55 |csharp
56 | public enum RfqState
57 | {
58 | Input,
59 | Requesting,
60 | Cancelling,
61 | Cancelled,
62 | Quoted,
63 | Executing,
64 | Error,
65 | Done
66 | }
67 |
68 | gist
Events
71 | 72 |Then we define the events which will trigger transitions between states. In our case those are events coming from the client or from the server.
73 | 74 |Again we can use an enum to define those events.
75 | 76 |```csharp 77 | public enum RfqEvent 78 | { 79 | UserRequests, 80 | UserCancels, 81 | UserExecutes,
82 | 83 |ServerNewQuote,
84 | ServerQuoteError,
85 | ServerQuoteStreamComplete,
86 | ServerSendsExecutionReport,
87 | ServerExecutionError,
88 | ServerCancelled,
89 | ServerCancellationError,
90 |
91 | InternalError,
92 | } 95 | ``` 96 | gist
97 | 98 |I like to prefix those events with their origin, just to makes things explicit (here we have 'Server', 'User', 'Internal')
99 | 100 |As you can see events coming from the server always expose a happy path (for instance ServerNewQuote when the server sends a new quote) and at least one corresponding error event (ServerQuoteError).
101 | 102 |
You will also often have internal events, for instance a timer expiring can raise an internal event to trigger a state transition.
105 | 106 |Events may or not carry some data: for instance UserRequests event needs to contain the description of the product being priced. 107 | For those events requiring parameters it is useful to define strongly typed events.
108 | 109 |This is how we declare them with Stateless, for instance for the ServerSendsQuote event:
110 | 111 |csharp
112 | _rfqEventServerSendsQuote = _stateMachine.SetTriggerParameters<IQuote>(RfqEvent.ServerNewQuote);
113 |
114 | gist
Defining transitions
117 | 118 |Now we can define transitions. For each state we define which events are allowed and when they are triggered to which state we will transition. 119 | This is very straight forward with stateless:
120 | 121 |```csharp 122 | _stateMachine.Configure(RfqState.Input) 123 | .Permit(RfqEvent.UserRequests, RfqState.Requesting);
124 | 125 |_stateMachine.Configure(RfqState.Requesting) 126 | .Permit(RfqEvent.ServerNewQuote, RfqState.Quoted) 127 | .Permit(RfqEvent.UserCancels, RfqState.Cancelling) 128 | .Permit(RfqEvent.InternalError, RfqState.Error);
129 | 130 |_stateMachine.Configure(RfqState.Quoted) 131 | .PermitReentry(RfqEvent.ServerNewQuote) 132 | .Permit(RfqEvent.UserCancels, RfqState.Cancelling) 133 | .Permit(RfqEvent.UserExecutes, RfqState.Executing);
134 | 135 |_stateMachine.Configure(RfqState.Executing) 136 | .Permit(RfqEvent.ServerSendsExecutionReport, RfqState.Done);
137 | 138 |_stateMachine.Configure(RfqState.Cancelling) 139 | .Permit(RfqEvent.ServerCancelled, RfqState.Cancelled); 140 | ``` 141 | gist
142 | 143 |Triggering events
144 | 145 |When the user performs an action or the server sends back a message we want to fire an event at the state machine. 146 | This is straight forward with stateless
147 | 148 |```csharp 149 | // for an event without parameters 150 | _stateMachine.Fire(RfqEvent.ServerQuoteStreamComplete)
151 | 152 |// for a strongly typed event 153 | stateMachine.Fire(rfqEventServerSendsExecutionReport, executionReport) 154 | ``` 155 | gist
156 | 157 |Defining actions
158 | 159 |When we send an event to the state machine, two things can happen, the current state has a valid transition for this event or not.
160 | 161 |If the current state can accept an event we generally want to execute our code at some point around the transition:
162 | 163 |-
164 |
- when you enter a state (or re-enter a state since it's also possible to have transitions looping back on the same state) 165 |
- when you exit a state 166 |
- upon transition, if you have different behavior to implement for different transitions leading to a same state 167 |
I tend to apply actions upon entry into a state and use the other variants only in specific scenarios.
170 | 171 |Important: when implementing a statemachine, you want to put all your logic inside those actions (on state entry, on state exit, on transition) because the state machine has already checked that the incoming event was valid for the current state.
172 | 173 |Here is an example with Stateless syntax. When the user requests a quote we want to log the transition and also to perform some logic on entry in the requesting state:
174 | 175 |```csharp 176 | stateMachine.Configure(RfqState.Requesting) 177 | .OnEntry(LogTransition) 178 | .OnEntryFrom(rfqEventUserRequests, OnEntryRequesting) 179 | .Permit(RfqEvent.ServerNewQuote, RfqState.Quoted) 180 | .Permit(RfqEvent.UserCancels, RfqState.Cancelling) 181 | .Permit(RfqEvent.InternalError, RfqState.Error);
182 | 183 |private void OnEntryRequesting(IQuoteRequest quoteRequest) 184 | { 185 | // here goes the code to send a quote request to the server 186 | } 187 | ``` 188 | gist
189 | 190 |Tip: you can think of the OnExit action as a Dispose() method for the corresponding state. It is very useful if for instance you had a timer runing during that state and you need to cancel it or you have whatever active Rx query that you want to unsubscribe.
191 | 192 |Handling errors
193 | 194 |When an event is fired at the state machine and the state machine has no transition defined for this event in the current state we can implement 2 behaviors: ignoring the event or raising an exception.
195 | 196 |By default Stateless will raise an exception but you can handle yourself invalid transitions:
197 | 198 |```csharp 199 | _stateMachine.OnUnhandledTrigger(OnUnhandledTrigger);
200 | 201 |private void OnUnhandledTrigger(RfqState state, RfqEvent trigger) 202 | { 203 | var message = string.Format("State machine received an invalid trigger '{0}' in state '{1}'", trigger, state); 204 | Console.WriteLine(message);
205 | 206 |_rfqUpdateSubject.OnError(new ApplicationException(message));
207 | } 210 | ``` 211 | gist
212 | 213 |You can also ignore individual events on a state with the Stateless .Ignore() method.
214 | 215 |Encapsulation
216 | 217 |We have now defined everything we need for the state machine: 218 | - states, 219 | - events and strongly typed events 220 | - possible transitions 221 | - actions on entry and on exit 222 | - error handling 223 | - how to fire events at the state machine
224 | 225 |The next step is to encapsulate everything in a single class so we don't leak the specifics of Stateless and the state machine to the rest of our code.
226 | 227 |For our example I've created a class Rfq that you can find here.
228 | 229 |This class implements the following interface:
230 | 231 |```csharp 232 | public interface IRfq : IDisposable 233 | { 234 | void RequestQuote(IQuoteRequest quoteRequest); 235 | void Cancel(long rfqId); 236 | void Execute(IExecutionRequest quote);
237 | 238 |IObservable<RfqUpdate> Updates { get; }
239 | } 242 | ``` 243 | gist
244 | 245 |This is very much CQRS style: a view model can call the RequestQuote, Cancel and Execute methods which act as Commands and internally fire events. Don't get confused by 'Command' and 'Event', they are the same, it's just that in the context of CQRS we talk about commands and for state machine I've use the term event from the beginning (we could use message as well if we want).
246 | 247 |The view model also subscribes to the Updates stream which will notify when the state machine transitions and provide the relevant data (a quote, an execution report, etc).
248 | 249 |You can find some sample usage of this API in the test project.
250 | 251 |
Concurrency
254 | 255 |I would strongly suggest to get your state machine running on a single thread. In my example the view model MUST call from the UI thread (Dispatcher) and I explicitly marshal server side initiated messages to the UI thread using ObserveOn in my Rx queries.
256 | 257 |If you are not building a UI you should consider running your statemachine in an actor or an event loop: anything that will guarantee that calls made on the state machine are sequenced and do not have to be synchronized.
258 | 259 |Why? Simply because otherwise you will have to synchronise all accesses to the state machine (and other states in your encasulating class) with locks. If for instance you take a lock while firing an event, all the actions will run under that lock. Those actions will likely call on code external to this class and you now have risks of deadlock..
260 | 261 |Race conditions
262 | 263 |Never forget that in an event driven system things can happen in an order you do not expect, and your state machine should be ready for that.
264 | 265 |Here is an example, which use a slightly different protocol for the RFQ:
266 | 267 |-
268 |
- the user receives a valid quote Q1 from the server 269 |
- the server sends an invalid quote message (to invalidate the quote because the market has moved or for whatever reason) 270 |
- the user HIT the quote Q1 (executes) while the invalidation message is still in flight (ie. still travelling somewhere between the server and the client) 271 |
- the state machine transitions to the state 'Executing' 272 |
- the client receives the invalidate quote message/event but the state machine is in a state where you might not have expected to receive such event... 273 |
Because there is a propagation delay between a client and a server, you will see behaviors in your systems that you did not thought about initially and that you have probably not covered in your unit tests.
276 | 277 |What to do about it?
278 | 279 |-
280 |
- For each state go through the list of all possible events and ask yourself: could this one possibly happen in this state? If it does, how should it be handled? 281 |
- Log all transitions of the state machine and all events fired. This is priceless while investigating for such issues. 282 |
- Unit testing is not enough, you will need to test in a deployed environment. 283 |
Visualisation
286 | 287 |Matt wrote some code which reflectively retrieves the definition of the State machine and is able to produce a graph definition in DOT code (a language to represent graphs).
288 | 289 |To generate a diagram from the output of the graph generation code, you can either download Graphviz and run it locally, or simply use an online GraphViz webapp.
290 | 291 |This is the output I got using the webapp:
292 | 293 |
Wrap up
296 | 297 |It takes a bit of time to get your head around state machines but once you get it those little things yield very nice clean code and it's also very simple to introduce new state and transitions if you follow the few guidelines we discussed here.
298 | 299 |There are a few other things I'd like to talk about with state machines (for instance visualising them while the system is running, code generation, etc) but we will cover that in a future blog post.
300 | 301 |I would also suggest to have a look to the work of Pieter Hintjens (ZeroMQ) on state machines and code generation, he has done some very cool stuff in this area
302 | --------------------------------------------------------------------------------