- NAME
- INSTALLATION
- USAGE
- DESCRIPTION
- EXPORTS
- PROPERTIES
- METHODS
- SEE ALSO
- VERSION
- AUTHOR
- COPYRIGHT AND LICENSE
ipc-event-emitter - an EventEmitter wrapper for IPC between parent and child processes with support for states (AKA pinned events) and logging
$ npm install ipc-event-emitter
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()
})
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')
got "ready", sending "ping"
got "ping", sending "pong"
got "pong", disconnecting
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 behavior
when coordinating communicating processes.
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 behavior as its
base class, events.EventEmitter
,
apart from the differences listed below.
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
orpin
is rejected. The default value isundefined
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.
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)
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.
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.
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 occurs 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 behavior as emit
. As with emit
, the value
resolved by the promise is unspecified.
ipc.unpin('ready')
// or
ipc.unpin('ready').then(() => {
console.log('unpinned "ready" event')
})
Signature: event: string → Promise
Unregister a "sticky" event. The behavior 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 behavior as emit
. As with emit
, the value
resolved by the promise is unspecified.
2.0.2
Copyright © 2015-2021 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms of the MIT license.