ipc-event-emitter

• NAME
• INSTALLATION
• USAGE
  • parent
  • child
  • output
• DESCRIPTION
• EXPORTS
  • IPC (default)
    • Options
  • IPCEventEmitter
• PROPERTIES
  • process
• METHODS
  • emit
  • pin
  • unpin
• SEE ALSO
• VERSION
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

ipc-event-emitter - an EventEmitter wrapper for IPC between parent and child processes with support for states (AKA pinned events) and logging

INSTALLATION

$ npm install ipc-event-emitter

USAGE

parent

import { fork } from 'child_process'
import IPC      from 'ipc-event-emitter'

let child = fork('./child.js')
let ipc = IPC(child)

ipc.on('ready', () => {
    console.log('got "ready", sending "ping"')
    ipc.emit('ping')
})

ipc.on('pong', () => {
    console.log('got "pong", disconnecting')
    child.disconnect()
})

child

import IPC from 'ipc-event-emitter'

let ipc = IPC(process)

ipc.on('ping', () => {
    console.log('got "ping", sending "pong"')
    ipc.emit('pong')
})

ipc.pin('ready')

output

got "ready", sending "ping"
got "ping", sending "pong"
got "pong", disconnecting

DESCRIPTION

This module provides an EventEmitter wrapper for child/parent processes which eliminates the need to use the child_process.send and process.send methods for IPC.

Instead, messages are sent to the connected process via the standard emit method. Exposing inter-process communication through the EventEmitter API makes it easy to pass the wrapper to code which expects a standard event emitter.

In addition, the wrapper extends the EventEmitter API to include support for states i.e. "sticky" events that can be subscribed to after they've fired. This ensures events are safely delivered regardless of when listeners are registered, and eliminates a common source of bugs and unpredictable behaviour when coordinating communicating processes.

EXPORTS

IPC (default)

import IPC from 'ipc-event-emitter'

let ipc = IPC(process, { debug: true })

ipc.emit('start')

Signature: (process: Process | ChildProcess, options?: object) → IPCEventEmitter

Takes a process or child process and an optional options object and returns an event emitter which translates emit calls to the send protocol used for IPC between parent and child processes.

Events are fired remotely (i.e. in the IPC wrapper in the connected process) and listeners are registered locally i.e. in the IPC wrapper in the current process.

Otherwise, the wrapper has the same interface and the same behaviour as its base class, events.EventEmitter, apart from the differences listed below.

Options

The following options are available:

• Type: boolean, default: false

  Enables event logging. Events are logged to the console. By default, the emitter is identified by the PID of its process, but this can be overridden via the name option.

  Logging can also be enabled by setting the IPC_EVENT_EMITTER_DEBUG environment variable to a true value.

• Type: string

  If logging is enabled, this value is used to identify the event emitter being logged. If not supplied, it defaults to the process's PID.

• Type: positive integer

  If an IPC message takes longer than this number of milliseconds to deliver (Node.js < 4.0.0) or send (>= 4.0.0), the promise returned by emit or pin is rejected. The default value is undefined i.e. no time limit.

  Note that it's up to you to perform any cleanup (e.g. disconnecting the relevant process) if a message times out.

IPCEventEmitter

import { EventEmitter }         from 'events'
import IPC, { IPCEventEmitter } from 'ipc-event-emitter'

let ipc = IPC(fork('./child.js'))

assert(ipc instanceof IPCEventEmitter) // => true
assert(ipc instanceof EventEmitter)    // => true

The EventEmitter subclass the IPC helper function returns instances of i.e.:

import IPC from 'ipc-event-emitter'

let ipc = IPC(process, options)

is equivalent to:

import { IPCEventEmitter } from 'ipc-event-emitter'

let ipc = new IPCEventEmitter(process, options)

PROPERTIES

process

let ipc = IPC(fork('./child.js'))

ipc.on('complete', () => {
    ipc.process.disconnect()
})

Type: Process | ChildProcess

The process or child process supplied to the IPC call.

METHODS

emit

ipc.emit('start')

// or

ipc.emit('start').then(() => {
    console.log('emitted "start" event')
})

Signature: event: string, args: ...any → Promise

Emit an IPC event i.e. send a message from a parent process to a child process or vice versa. If arguments are supplied, they are passed to the registered listener(s). Arguments must be JSON-serializable as per send.

The return value is a promise. This is intended to provide a way to smooth over the differences between Node.js < v4.0.0, where send (and thus emit and pin) is synchronous, and Node.js >= v4.0.0, where it's asynchronous.

Note that on Node.js >= v4.0.0, the promise is resolved when the message has been sent, whereas on older versions it's resolved when the message has been received. As a result, only the former guarantee should be relied upon unless the target environment is known to be locked down to 0.x.

The value resolved by the promise is unspecified.

pin

ipc.pin('ready')

// or

ipc.pin('ready').then(() => {
    console.log('pinned "ready" event')
})

Signature: event: string, args: ...any → Promise

A "sticky" version of emit. Listeners registered before this event occurs are notified in the same way as emit. Listeners registered after this event are called immediately with the supplied arguments.

Pinning an event makes it act like a state rather than a blink-and-you-miss-it notification. This is useful for states such as "ready" which are poorly modeled by events.

Note that the "error" event is special-cased by EventEmitter, and can't be pinned. Attempting to pin an event with this name will raise an error.

Returns a promise with the same behaviour as emit. As with emit, the value resolved by the promise is unspecified.

unpin

ipc.unpin('ready')

// or

ipc.unpin('ready').then(() => {
    console.log('unpinned "ready" event')
})

Signature: event: string → Promise

Unregister a "sticky" event. The behaviour prior to the pinning of the event is restored i.e. listeners registered after an event has been unpinned will only be invoked if the event occurs again in the future.

Returns a promise with the same behaviour as emit. As with emit, the value resolved by the promise is unspecified.

SEE ALSO

• fixed-event
• ipcee
• ipc-emitter
• ipc-events

VERSION

2.0.2

AUTHOR

chocolateboy

COPYRIGHT AND LICENSE

Copyright © 2015-2019 by chocolateboy.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.