State Machine Factory

The State Machine Factory object is used to both create new instances of state machines and also to monitor state machines once they have been created and have started running. 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.

To create a new State Machine Factory the Factory constructor function on the main ignite API object is called. This constructor takes three arguments. The first, which is required, is the State Machine Generator Function. The second and third arguments are optional. The first of these is the imports argument. This tells the factory which asynchronous functions should be provided for use with the asynchronous function call proxy syntax (see Function proxies). The last argument is the options argument. This allows control of both the logging and tracking features (see Addons)

Example

The following example shows how to create a State Machine Factory by calling the Factory constructor (Line 19). In this case the SMGF returns a very simple single state state machine which just opens and reads a file.

var machineGF = function (fire) {
  this.startState = 'ReadAFile';
  this.states = {
    ReadAFile: {
      entry: function (filePath) {
        fire.fs.readFile(filePath);
      },
      actions: {
        'fs.readFile.done': '@exit',
        'fs.readFile.err': '@error'
      }
    }
  };
};

var ignite = require('ignite'),
    imports = { fs: require('fs') },
    options = { /* no options */ },    
    factory = new ignite.Factory(machineGF, imports, options);

Notice that the node.js file system library was declared in the imports object using a property called fs. This allows file system functions to be called on the function proxy object fire.fs, for example the readFile function on line 6.

All Factory objects are EventEmitters. A complete list and description of the events can be found in the State Machine Factory API. Two of the most commonly listened to events are the exit and error events. Not surprisingly, the exit event is emitted when a state machine exits through the @exit state and the error event is emitted when a state machine exits through the @error state.

Creating a new instance of a state machine and starting it are done in a single step. This is by calling one of the two following methods, spawn or spawnWithCb. These differ only in that the latter also allows a callback function to be provided as the last argument. This callback function is called when either the exit or error events are emitted by the State Machine Factory.

The arguments of spawn and spawnWithCb (with the exception of the last argument for spawnWithCb which is reserved for the callback function described above) are used to set the initial transition arguments. These are the arguments that will be passed into the State Machine Generator Function (after the fire object) and also into the entry function (or guard function if it exists) of the start state.

Example

// create and start a new instance of the state machine
factory.spawnWithCb('interestingFile.txt', function (err, data) {
  if (err) {
    // there was an error
    ....
  } else {
    // data contains the contents of the file ('interestingFile.txt')
    ....
  }
});

In the above example the spawnWithCb function is used. It is worth noting that this function call is identical in structure (and indeed in its behaviour) to any of the asynchronous function calls found in the node.js modules.