Factory API

constructor(SMGF [,imports [,options]])

JavaScript function constructor used to create a new State Machine Factory. Each State Machine Factory is specific to one type of state machine (i.e. a single State Machine Generator Function) but can be used to create and monitor multiple instances of the same type of machine.

parameters

SMGF
The State Machine Generator Function used to define the state machines generated by the factory.
imports
An object containing any asynchronous functions required by the state machine (see Function Call Proxy). The property names of this object form the namespace for calling asynchronous functions within a running state machine. E.g. the following imports object would allow functions like fs.readFile or http.request to be called using the function call proxies fire.fs.readFile and fire.coreHttp.request respectively or to be used by the plug-ins by using the string names 'fs.readFile' and 'coreHttp.request'.
{ 
  'fs': require('fs'),
  'coreHttp': require('http')
}
options
An object controlling various the various options used by the state machine. The boolean options.strict property is used to indicate whether or not the state machine should be run in strict mode, the default value for this property is false. When the machine is run in strict mode all unhandled events result in the machine exiting through the '@error' state instead of being ignored. The integer property options.logLevel is used to set the level of logging required (0 to 8 inclusive).

method spawn([arg1 [,arg2 [...]]])

Creates and starts a new instance of a state machine.

parameters

[arg1 [,arg2 [...]]]
varargs: Arguments used to set the initial transition arguments for the newly created machine.

method spawnWithCb([arg1 [,arg2 [...]]], callback)

Creates and starts a new instance of a state machine. When the method is called, the last argument should be a callback function which will be called when the state machine exits. This allows state machines to be used in an identical fashion to standard node.js asynchronous function calls.

parameters

[arg1 [,arg2 [...]]]
varargs: Arguments used to set the initial transition arguments for the newly created machine.
callback
Function: The callback function.

method launch(defaults)

A convenient method for spawning a new state machine using default values either defined on the SMGF or passed as arguments when the method is called.

parameters

defaults
A State Machine Factory defaults object. Any properties defined in this defaults object will be used to override the SMGF defaults object for this particular instance of the state machine.

method broadcast(eventName [,arg1 [,arg2 [...]]])

Used to generate and inject an event into each running state machine created by the State Machine Factory.

parameters

eventName
String: The event name.
[arg1 [,arg2 [...]]]
varargs: The event arguments.

method count()

The integer number of state machines created by the State Machine Factory that are currently still running.

method setThreshold(logic, level)

Used to control a mechanism to emit 'threshold' events from the State Machine Factory that are dependent on the number of currently running machines created by the factory. The logic used to determine the threshold can be specified in one of the following ways

  • low, true when the number of machines decreases so that the number running hits a specified level
  • high, true when the number of machines increases so that the number running hits a specified level
  • below, true when the number of machines running is below a specified level
  • above, true when the number of machines running is above a specified level

The above logic is tested every time a new machine is started, exits, or when the setThreshold method is called to define a new threshold. A 'threshold' event is emitted for each true logic threshold.

parameters

logic
String: The threshold logic, either 'low', 'high', 'below' or 'above'
level
Integer: Defines the number of running state machines used for the threshold.

method clearThreshold(logic, level)

Used to clear a previous defined threshold (see setThreshold)

parameters

logic
String: The threshold logic, either 'low', 'high', 'below' or 'above'
level
Integer: Defines the number of running state machines used for the threshold.

event 'entry'

The event emitted when a newly created machine starts. This event has no arguments.

event 'done'

The event emitted when one of the state machines created by the State Machine Factory exits, either through the '@exit' or '@error' states. The first event argument is a string set to either 'exit' or 'error' depending on which state the machine exited through. The subsequent arguments are set to the final values of the state machines transition arguments.

event 'quiet'

The event emitted when one of the state machines created by the State Machine Factory exits and there are then no machines currently still running.

event 'threshold'

The event emitted when a threshold logic is tested and is true (see setThreshold). This event has three arguments, logic name, current state machine count and change (either +1 or -1).