synchronous-channel
This package provides synchronous message channels for Node.js Worker Threads and Web Workers in modern browsers.
Synchronous message passing should be avoided if possible, and existing
asynchronous APIs such as postMessage
should be used instead.
Communication model
We call a thread synchronous if it requires blocking the event loop for large amounts of time. While generally undesirable, it is sometimes difficult to prevent, for example, when running WebAssembly code in a background thread.
Sending thread type | Receiving thread type | Recommended mechanism |
---|---|---|
Asynchronous | Asynchronous | postMessage |
Asynchronous | Synchronous | SynchronousChannel |
Synchronous | Asynchronous | postMessage |
Synchronous | Synchronous | SynchronousChannel |
Examples
Node.js example:
const Worker isMainThread parentPort workerData = ;const SynchronousChannel = ; if isMainThread // Create a new channel that can store up to 16 messages, each having a size // of up to 32 bytes. const channel = queueLength: 16 maxMessageSize: 32 ; // The main thread will write to the channel. const writer = channel; // Start a new thread. __filename workerData: channel ; else // The worker thread will read from the channel. const channel = workerData; const reader = channel; // Keep reading messages... forever. let message; while message = reader !== false const time = Buffer; parentPort;
API
SynchronousChannel
Class Options:
queueLength
: Maximum numbers of messages to queue.maxMessageSize
: The maximum size of each message, in bytes.
Each channel uses approximately queueLength * maxMessageSize
bytes of memory.
It is currently not possible to resize shared memory.
It is not possible to create more than one Writer
or more than one Reader
for a single SynchronousChannel
. Attempting to create additional Writer
or
Reader
instances will throw.
Example:
const channel = queueLength: 64 maxMessageSize: 1024;
SynchronousChannel.Writer
Class Example:
const writer = channel;writer;
SynchronousChannel.Reader
Class Example:
const reader = channel;const message = reader;
Blocking operations and timeouts
This module supports both blocking and non-blocking read and write operations.
For blocking operations, a timeout can be specified in milliseconds. Setting a
timeout
to true
is equivalent to setting it to +Infinity
, and the
operation will potentially never return.
Browsers usually do not allow the main (renderer) thread to use blocking memory operations. Using a timeout will throw an exception in these cases.
Browser support
Currently, the SharedArrayBuffer
class is the only way to implement
synchronous communication between threads. Due to security concerns, it has been
disabled in most browsers, and at the time of writing, only Chrome fully
supports SharedArrayBuffer
.