Class: ModuleProcess

ModuleProcess

new ModuleProcess(moduleName, moduleOpts, logger)

ModuleProcess

A wrapper for module to make it running its functionality within subprocess accepting IPC messages as commands.

The main purpose of the ModuleProcess is to invoke within subprocess any module function by name (available via module.exports of wrapped module) passing parameters to it (see ModuleProcess.invoke for details). The function name to call and parameters are accepted via IPC, the callback invoked then on IPC chanel in form of message back to parent.

Parameters:
Name Type Description
moduleName String Module name (script file name). E.g. __filename
moduleOpts Object Options object to pass to the module
logger
Source:

Methods

(static) listenIPCMessages(moduleFn, moduleFileName, logger)

Create listener to catch the IPC messages within the process the module is running in.

Important: The module should be running within process otherwise registering listener makes no sense. This will invoke process.on('message', function() {}) to listen for parent process commands.

Use ProcessDispatcher to manage module processes.

Parameters:
Name Type Description
moduleFn function Module function exposing the API for ProcessDispatcher.dispatch calls.
moduleFileName String File name (whole patch with file name) of the module defined by module function.
logger
Source:

(static) makeCommandId(command) → {string}

Make unique command token to use in send/receive model to distinguish calls for the child process.

Parameters:
Name Type Description
command COMMANDS A COMMANDS definition for possible commands.
Source:
Returns:
Token
Type
string

addCallback(commandId, callback)

Bind callback to unique command id (or token) to be called once function finished.

Parameters:
Name Type Description
commandId String Unique string Token. See. ModuleProcess.makeCommandId
callback ModuleProcess~onReadyCallback Callback to run on function finished.
Source:

getCallback(commandId) → {ModuleProcess~onInvokeCallback}

Get callback by token. See. ModuleProcess.addCallback, ModuleProcess.makeCommandId.

Parameters:
Name Type Description
commandId String Unique string token. See. ModuleProcess.makeCommandId.
Source:
Returns:
callback Callback function that has been stored for this commandId.
Type
ModuleProcess~onInvokeCallback

init(callback)

Initialize child process and incoming commands listener.

This will do the following steps:

  • - Prepare options to be passed for module (functionality options) and process (environment mostly) initialization
  • - Fork new subprocess from moduleName
  • - Start listening incoming IPC messages from forked sub-process to current process:
    • - init command response: will invoke the ModuleProcess.init function callback, notifying the module has been initialized in subprocess
    • - other command response: will invoke a callback registered with addCallback on incoming command call via ModuleProcess.invoke.
Parameters:
Name Type Description
callback ModuleProcess~onReadyCallback Callback to run on initialization has finished.
Source:

invoke(functionName, params) → {ModuleProcess~onReadyCallback}

Request a functionName to be called within subprocess with supplied parameters. This call return a callback-style function wrapping the invoked function. See invokeExample.js below.

Behind the scenes...

The function invocation workflow is based on the following:

1. On ModuleProcess init the module is wrapped by subprocess. Since that the ModuleProcess object API contains module members that are exposed via ProcessDispatcher.listenIPCMessages. First parameter in ProcessDispatcher.listenIPCMessages is 'moduleFn' (function(moduleOpts) { ... }). moduleOpts is used eventually as 'moduleOpts' parameter for that function. Then the functionName passed to the ModuleProcess.invoke is one of that functions installed via ProcessDispatcher.listenIPCMessages invocation.

2. Once functionName invocation requested the callback is registered for that particular function call (i.e. unique token created for the function call)

3. Later under the hood the callback will be called when the subprocess that wraps the module will respond via IPC message to its parent process. The response will be caught by ModuleProcess functionality. To understand that see how initialization goes in ModuleProcess.init, the "case COMMANDS.MODULE_PROCESS_COMMAND_INVOKE" block is what catching command result responses and calling callback that is registered when ModuleProcess.invoke has been called.

Parameters:
Name Type Description
functionName string Function name to be invoked. It is a wrapped module module.export member.
params object Params to be passed to function.
Source:
Returns:
A callback function to be run on command invocation has finished.
Type
ModuleProcess~onReadyCallback
Example

invokeExample.js

var modProc = ...; // modProc is instance of ModuleProcess
modProc.invoke('foo', {param1: "test"})(function(error, result) {
  console.log("result is ", result);
});

removeCallback(commandId)

Unbind callback from Token. See. ModuleProcess.addCallback.

Parameters:
Name Type Description
commandId String Unique string token. See. ModuleProcess.makeCommandId
Source:

Type Definitions

onReadyCallback(error)

Callback to run on function finished. Note: It might contain arbitrary number of arguments (required at least one - error)

Parameters:
Name Type Description
error Error An Error object if the callback has raised an error.
Source: