A RPC-like facility for making inter-thread function calls.
npm install @far-analytics/port-peerA RPC-like facility for making inter-thread function calls.
Port Peer provides a simple and intuitive interface that makes inter-thread function calls _easy_. Please see the Usage or Examples for instructions on how to use Port Peer in your application.
- Bi-directional inter-thread function calls.
- Port Peer will marshal the return value or Error from the _other_ thread back to the caller.
- The _other_ thread may be the main thread or a worker thread.
- Registered functions (i.e., peer.register) persist until deregistered (i.e., peer.deregister) .
- Late binding registrants will be called with previously awaited invocations.
- Installation
- Concepts
- Usage
- Examples
- API
- Versioning
- Notes
- Support
``bash`
npm install port-peer --save
An instance of a Peer facilitates bi-directional communication between threads. The Peer can be used in order to register a function in one thread and call it from another thread. Calls may be made from the main thread to a worker thread, and conversely from a worker thread to the main thread.
Late binding registrants will be called with previously awaited invocations; thus preventing a race condition. This means that you may await a call to a function that has not yet been registered. Once the function is registered in the _other_ thread it will be called and its return value or Error will be marshalled back to the caller.
Please see the Examples for variations on the Peer's usage.
#### Import the Peer class and relevant dependencies.
`ts`
import { Worker, parentPort } from "node:worker_threads";
import { fileURLToPath } from "node:url";
import { Peer } from "port-peer";
#### You can create a new Peer by passing a MessagePort or Worker instance to the Peer constructor.
In the main thread,
`ts`
const worker = new Worker(fileURLToPath(import.meta.url));
const peer = new Peer(worker);
or, in a worker thread,
`ts`
const peer = new Peer(parentPort);
#### You can register a function in the main thread or in a worker thread using the peer.register method.
`tsHello, ${value} world!
peer.register("hello_world", (value: string): string => );`
#### You can call a function registered in another thread (i.e., the main thread or a worker thread) using the peer.call method:
`ts`
const greeting = await peer.call
console.log(greeting); // Hello, happy world!
Please see the simple example for a working implementation.
Please see the comprehensive example for a working implementation.
#### new Peer(port)
- port or The message port.
_public_ peer.call\
- name The name of the registered function.
- ...args Arguments to be passed to the registered function.
Returns:
Errors:
- If the registered function in the _other_ thread throws an Error, the Error will be marshalled back from the _other_ thread to _this_ thread and the Promise will reject with the Error as its failure reason.Error
- If a worker thread throws an unhandled exception while a call is awaited, the will be marshalled back from the _other_ thread to _this_ thread and the Promise will reject with the unhandled exception as its failure reason.Error
- If a worker exits while a call is awaited, the will be marshalled back from the _other_ thread to _this_ thread and the Promise will reject with the exit code as its failure reason.
_public_ peer.register(name, fn)
- name The name of the registered function.<(...args: Array
- fn The registered function.
Returns:
_public_ peer.deregister(name)
- name The name of the registered function.
Returns:
The Port Peer package adheres to semantic versioning. Breaking changes to the public API will result in a turn of the major. Minor and patch changes will always be backward compatible.
Excerpted from Semantic Versioning 2.0.0:
> Given a version number MAJOR.MINOR.PATCH, increment the:
>
> 1. MAJOR version when you make incompatible API changes
> 2. MINOR version when you add functionality in a backward compatible manner
> 3. PATCH version when you make backward compatible bug fixes
>
> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Port Peer supports one to one communication over a MessagePort. BroadcastChannels are not presently supported.
Port Peer is strictly focused on efficient communication over MessagePorts. Port Peer will not support communication over other communication channels e.g., Socket`s, IPC, etc.
If you have a feature request or run into any issues, feel free to submit an issue. You’re also welcome to reach out directly to one of the authors.