fsm
Library for managing the execution of a linked tree of finite state machines.
Overview
The Fsm library and class serves as the base class for chainable finite state machines.
The library improves management of asynchronous work in several ways over more primitive syntactic approaches like plain callbacks, async/await, promises or async libraries. These include:
-
The state of your computation is managed as an explicit set of objects rather than an opaque mixture of callbacks and closures.
-
It is easy to model a computation that proceeds through multiple intermediate states rather than simply "in-process" or "done".
-
Computations (objects) can be built as a tree of dependent computations, effectively acting as a data-flow model, a natural way of describing many computations.
-
The mechanism integrates well with existing mechanisms like callbacks and promises.
-
A state machine more directly models how the computation is proceeding rather than syntactic models like async/await that explicitly try to hide the real control flow.
-
Requiring a class definition to represent the computation tends to facilitate reuse of the asynchronous logic rather than having callbacks sprinkled through the code base.
A potential disadvantage of the FSM mechanism is that requiring a new subclass tends to have a heavier syntactic weight than mechanisms like simple callbacks. For some, this is an advantage in not trivializing the additional state complexity that an outstanding asynchronous computation represents for the application.
The normal usage is to sub-class the Fsm base class and override the tick function to walk the
state machine through its states.
Each machine begins in the FSM_STARTING state.
The tick function on the class gets scheduled to be called (asynchronously) initially after
construction and then explicitly whenever
the state changes (by a call to the class function setState).
A subclass overrides the tick function to run the machine through its state transitions.
Additionally, a finite state machine can waitOn another state machine.
When that machine is marked complete (either FSM_DONE or FSM_ERROR),
any machines waiting on that state machine get scheduled to have their tick function called as well.
A machine is ready when all Fsm's it is waiting on have been marked complete.
The tick function of a dependent state machine is called whenever any machine it is waiting on completes,
but normally the tick function only performs activity when the machine is ready.
Most usage involves the tick function first testing if it is ready before doing any activity,
although a usage that wanted to take action whenever any waitedOn dependent completes might omit that test
(e.g. to race multiple asynchronous operations and use whichever result completes first or
immediately complete if any one of several outstanding dependents fail).
For example, this is typical usage:
tick(): void
{
if (this.ready)
{
// all dependents are complete, take action now
}
}Of course, a state machine can go from ready to not ready as many times as necessary simply by waiting on
some new Fsm within its tick function.
Normally a Fsm-based class does not fire off any activity until the first time its tick function is called (rather than
in the constructor).
So,
constructor(env: Environment)
{
super(env);
// Don't do any real work here.
}
tick(): void
{
if (this.ready)
{
switch (this.state)
{
case FSM_STARTING:
// Kick off activity here
break;
}
}
}That is not a requirement but increases flexibility by allowing clients to construct the Fsm and then add dependents it must wait on before any activity is kicked off.
The infrastructure only cares about the starting state FSM_STARTING and the completion states FSM_ERROR and FSM_DONE.
Any other state values can
be used internally to a state machine to manage walking through different active states prior to completion.
For convenenience, the names FSM_CUSTOM1 through FSM_CUSTOM9 are predefined and internal states can use these
values (typically assigned to something semantically meaningful) however they wish.
The state FSM_PENDING has no special meaning but is defined for convenience since many state machines go through
a single intermediate state (FSM_STARTING to FSM_PENDING to FSM_DONE).
Callbacks can be integrated easily by having the callback set the Fsm state, which allows either completion
notification to any other waiting state machines or the next step in the current state machine to be executed.
tick(): void
{
if (this.ready)
{
switch (this.state)
{
case FSM_STARTING:
asyncAPIWithCallback((err: any, result: any) => {
if (err)
this.setState(FSM_ERROR);
else
this.setState(FSM_DONE);
});
break;
}
}
}or
tick(): void
{
if (this.ready)
{
switch (this.state)
{
case FSM_STARTING:
asyncAPIWithCallback((err: any, result: any) => {
if (err)
this.setState(FSM_ERROR);
else
this.setState(FSM_PENDING);
});
break;
case FSM_PENDING:
// Do more stuff here now that callback has completed.
break;
}
}
}isDependentError
When an Fsm that is being waited on completes with an error, any waiting Fsm's get the isDependentError flag set
and of course get a chance to run their tick function (since the dependent Fsm has completed).
They can decide if the semantics of the relationship then requires them to propagate, consume or otherwise handle the error. No other error propagation happens automatically. So:
tick(): void
{
if (this.ready && this.isDependentError)
this.setState(FSM_ERROR);
else if (this.ready)
{
// Normal code here
}
}would explicitly immediately propagate a dependent error.
Note that the check above to test whether the state machine is ready before isDependentError is to ensure you do not
loop continuously resetting the state to FSM_ERROR on each tick invocation.
Reuse
An Fsm can be reused and transition from ready to not ready or done to not done.
Cancellation
There is no explicit cancellation mechanism.
By convention, a sub-class should override the end member function to allow external cancellation or completion.
By default this function sets the Fsm to FSM_DONE but can optionally take the FSM_ERROR state
to indicate error.
Whether calling end or setting the state explicitly to FSM_DONE or FSM_ERROR from external to
the state machine makes semantic sense depends on the specific properties and semantics of the computation.
FsmOnDone
A simple utility class FsmOnDone provides a way of integrating a callback with an Fsm-based infrastructor.
The FsmOnDone class will wait till the Fsm passed to the constructor completes and then call the provided
callback, passing the completed Fsm as the argument.
let fsm = new FsmOnDone(env, fsmWait, (fsmWait: Fsm) => {
/* do stuff with fsmWait since it is now complete */
});FsmSleep
FsmSleep is a simple utility class that creates a dependency that is marked done after
the number of milliseconds passed to the constructor.
So:
fsm.waitOn(new FsmSleep(env, 1000));will result in the object fsm having a dependency that will complete in 1000ms.
FsmLoop
FsmLoop is a simple utility class to run an asynchronous process in a loop at some maximum rate.
It waits for the Fsm passed in to complete, then uses FsmSleep to wait until the specified
minimum interval is complete (starting when the Fsm started executing)and restarts the Fsm.
It is required that the Fsm properly handles going from the FSM_DONE state back to FSM_STARTING.
FsmArray
FsmArray is a simple utility class that provides a mechanism for waiting for a stream of
objects to appear in an array and consuming them, repeatedly.
It will be marked done when any content is made available in the array (through the member a)
by calling push or concat.
When the content is consumed, it should be removed with splice or reset.
At this point, the Fsm will be placed back in the starting state and can be waited on again.