Spawn

The spawn plug-in is used as a convenient way to create and start new machines. When the plug-in is initially loaded it registers a new method on the fire object called $spawner. Calling this method within a state machine state does a couple of things. First, it defines and names a state machine factory that can then be used within the state machine to spawn new machines. Second, it registers the named state machine factory as an event emitter so that the spawning state and/or states within the spawning state machine can listen and respond to any events emitted by the registered machine factory.

prop spawnrequired

The spawn property defines an object with properties that control how the state should use the plug-in.

prop spawn.factoryrequired

The name (String) of the State Machine Factory which will be used to spawn a new machine. Note that the State Machine Factory named by this property should have previously been registered with the State Machine by making a call to the fire.$spawner method (see below).

prop spawn.smArgsoptional

The spawn.smArgs property is used to defined the arguments that are passed to the factory defined in spawn.factory. The property can either be a static array, or a function returning an array. If the function syntax is used, it is called using the current Transition Arguments as its arguments.

If the property is missing then the current Transition Aarguments are used.

method fire.$spawner(name, factory [,imports [,options]])

Defines and names a State Machine Factory which can then be used within the state machine to spawn new machines.

parameters

name
The name assigned to the State Machine Factory. This is the name that should be referred to in the spawn property (see below).
factory
Either a State Machine Generator Function or a State Machine Factory object.
imports
The imports object used to create the State Machine Factory if a generator function is supplied as the factory argument. If undefined then the imports object from the spawning machine is used.
options
The options object used to create the State Machine Factory if a generator function is supplied as the factory argument. If undefined then the options object from the spawning machine is used.

event 'spawn.done'

An event called 'spawn.done' is generated and injected into the current state when the new machine has been created and started (spawned). The event has no arguments.

Example

In the following example we define two State Machine Generator Functions. The first is the fileToConsole generator function shown below. This machine has a single state which opens and reads a file and then dumps the contents to the console.

function fileToConsole (fire, filePath) {
  this.startState = 'ReadFile';
  this.states = {
    ReadFile: {
      async: 'fs.readFile',

      actions: {
        'async.done': function (data, args) {
          console.log(data);
          return '@exit';
        },
        'async.err': function (err, args) {
          console.error(err);
          return '@error';
        }
      }
    }
  };
};

The second is the dumpFiles generator function (see below). This machine processes a list of file paths, starting a new machine for each.

function dumpFiles (fire, filePaths) {
  this.startState = 'Init';
  this.states = {
    Init: {
      entry: function() {
        fire.$spawner('SpawnFileToConsole', fileToConsole);
        return 'DumpFiles';
      }
    },

    DumpFiles: {
      spawn: {
        factory: 'SpawnFileToConsole'
      },

      actions: {
        'spawn.done': function (filePaths) {
          if (filePaths.length) {
            return '@self';
          }            
        },
        'SpawnFileToConsole.quiet': '@exit'
      }
    }
  };
};

See