bare-worker 4.1.8 → 4.2.0

package/README.md

@@ -1,6 +1,6 @@
 # bare-worker
 
-Higher-level worker threads for JavaScript.
+Higher-level worker threads for JavaScript. Built on top of <https://github.com/holepunchto/bare-thread> and <https://github.com/holepunchto/bare-channel>, it provides a `Worker` class together with `MessageChannel` and `MessagePort` primitives for passing structured messages between threads.
 
 ```
 npm i bare-worker
@@ -22,6 +22,170 @@ if (Worker.isMainThread) {
 }
 ```
 
+## API
+
+#### `const worker = new Worker(entry[, options])`
+
+Spawn a new worker thread that loads and runs the module at `entry`. `Worker` extends `MessagePort`, so the returned instance can be used to exchange messages with the worker.
+
+Options include:
+
+```js
+options = {
+  workerData: null
+}
+```
+
+`workerData` is an arbitrary value cloned into the worker and made available there as `Worker.workerData`.
+
+#### `worker.detached`
+
+Whether the underlying message port has been detached for transfer. See `MessagePort`.
+
+#### `await worker.terminate()`
+
+Stop the worker as soon as possible. Returns a `Promise` that resolves with the worker's exit code once it has fully closed. Safe to call multiple times; subsequent calls resolve with the same exit code.
+
+#### `event: 'online'`
+
+Emitted when the worker thread has started executing.
+
+#### `event: 'message'`
+
+Emitted for each message sent from the worker with `parentPort.postMessage()`. The message value is passed to the listener.
+
+#### `event: 'error'`
+
+Emitted when an uncaught exception or unhandled rejection occurs in the worker. The error is passed to the listener and the worker exits with code `1`.
+
+#### `event: 'exit'`
+
+Emitted when the worker has stopped. The exit code is passed to the listener.
+
+#### `Worker.isMainThread`
+
+`true` when the current thread is the main thread, `false` when running inside a worker.
+
+#### `Worker.parentPort`
+
+Within a worker, the `MessagePort` connected to the parent thread. `null` on the main thread.
+
+#### `Worker.workerData`
+
+Within a worker, the `workerData` value passed when the worker was spawned. `null` on the main thread.
+
+#### `Worker.MessageChannel`
+
+The `MessageChannel` class. See below.
+
+#### `Worker.MessagePort`
+
+The `MessagePort` class. See below.
+
+#### `Worker.BroadcastChannel`
+
+The `BroadcastChannel` class. See below.
+
+#### `Worker.preload(entry)`
+
+Register the module at `entry` to be loaded in every worker before its own entry module runs. Preloads are inherited by nested workers.
+
+#### `Worker.setEnvironmentData(key[, value])`
+
+Set a value on the environment data shared with workers. The data is cloned into each worker as it is spawned. Omitting `value` removes `key`.
+
+#### `Worker.getEnvironmentData(key)`
+
+Get a value previously set with `Worker.setEnvironmentData()`.
+
+### `MessageChannel`
+
+#### `const channel = new MessageChannel()`
+
+Create a pair of connected message ports for two-way communication. A port may be transferred to a worker by including it in the transfer list of a `postMessage()` call.
+
+#### `channel.port1`
+
+One end of the channel, a `MessagePort`.
+
+#### `channel.port2`
+
+The other end of the channel, a `MessagePort`.
+
+### `MessagePort`
+
+The endpoint of a message channel. `MessagePort` extends `EventEmitter`. A port begins receiving messages once it is started, which happens automatically when a `'message'` listener is added.
+
+#### `port.detached`
+
+Whether the port has been detached for transfer to another thread.
+
+#### `port.postMessage(message[, transferList])`
+
+Send `message` to the other end of the channel. `transferList` is an optional array of transferable objects, such as other `MessagePort` instances, whose ownership is moved to the receiving thread rather than cloned.
+
+#### `port.start()`
+
+Begin receiving messages on the port. Called automatically when a `'message'` listener is added, but may be called explicitly to start before any listener is attached.
+
+#### `port.close()`
+
+Close the port. No further messages will be sent or received.
+
+#### `port.ref()`
+
+Keep the underlying I/O resource referenced so it prevents the thread from exiting while the port is open.
+
+#### `port.unref()`
+
+Allow the thread to exit even while the port is open. Inflight writes are still awaited.
+
+#### `port.hasRef()`
+
+Whether the port is currently referenced.
+
+#### `event: 'message'`
+
+Emitted for each message received on the port. The message value is passed to the listener.
+
+#### `event: 'close'`
+
+Emitted when the port has closed.
+
+### `BroadcastChannel`
+
+A named channel for broadcasting messages to every other `BroadcastChannel` with the same name across the entire worker tree, including the main thread and nested workers. `BroadcastChannel` extends `EventEmitter` and follows the semantics of the Web `BroadcastChannel`: a channel never receives its own messages, but every other channel sharing its name does.
+
+```js
+const Worker = require('bare-worker')
+
+const channel = new Worker.BroadcastChannel('updates')
+
+channel.on('message', console.log)
+
+channel.postMessage('Hello everyone')
+```
+
+#### `const channel = new BroadcastChannel(name)`
+
+Create a channel bound to `name`. All channels constructed with the same `name`, in any thread of the worker tree, are connected.
+
+#### `channel.name`
+
+The name the channel is bound to.
+
+#### `channel.postMessage(message)`
+
+Broadcast `message` to every other connected channel sharing this channel's name. The message is cloned; unlike `MessagePort.postMessage()`, transferring is not supported. Throws if the channel has been closed.
+
+#### `channel.close()`
+
+Close the channel, disconnecting it from the others. No further messages will be sent or received.
+
+#### `event: 'message'`
+
+Emitted for each message broadcast to the channel by another channel sharing its name. The message value is passed to the listener.
+
 ## License
 
 Apache-2.0

package/global.js

@@ -1,4 +1,5 @@
-const { MessageChannel, MessagePort } = require('.')
+const { MessageChannel, MessagePort, BroadcastChannel } = require('.')
 
 global.MessageChannel = MessageChannel
 global.MessagePort = MessagePort
+global.BroadcastChannel = BroadcastChannel

package/index.js

@@ -1,12 +1,15 @@
 const Thread = require('bare-thread')
 const Channel = require('bare-channel')
+const Broadcast = require('bare-broadcast-channel')
 const WorkerState = require('./lib/worker-state')
 const MessageChannel = require('./lib/message-channel')
 const MessagePort = require('./lib/message-port')
+const BroadcastChannel = require('./lib/broadcast-channel')
 const constants = require('./lib/constants')
 
 const preloads = new Map()
 
+let broadcast = null
 let environmentData = new Map()
 let parentPort = null
 let workerData = null
@@ -16,11 +19,18 @@ if (WorkerState.parent) {
     preloads.set(entry, source)
   }
 
+  broadcast = WorkerState.parent.broadcast
   parentPort = WorkerState.parent.port
   workerData = WorkerState.parent.data
   environmentData = WorkerState.parent.environmentData
+} else {
+  broadcast = new Broadcast()
 }
 
+// Every named broadcast channel on this thread connects to the same underlying
+// channel, which is shared across the whole worker tree.
+BroadcastChannel._channel = broadcast
+
 const worker = Thread.prepare(require.resolve('./lib/worker-thread'), { shared: true })
 
 module.exports = exports = class Worker extends MessagePort {
@@ -37,6 +47,7 @@ module.exports = exports = class Worker extends MessagePort {
       data: {
         source: Thread.prepare(entry, { shared: true }),
         channel: channel.handle,
+        broadcast: broadcast.handle,
         data: workerData,
         preloads,
         environmentData
@@ -97,6 +108,7 @@ exports.Worker = exports
 
 exports.MessageChannel = MessageChannel
 exports.MessagePort = MessagePort
+exports.BroadcastChannel = BroadcastChannel
 
 exports.parentPort = parentPort
 exports.workerData = workerData

package/lib/broadcast-channel.js

@@ -0,0 +1,103 @@
+const EventEmitter = require('bare-events')
+const errors = require('./errors')
+
+module.exports = exports = class BroadcastChannel extends EventEmitter {
+  constructor(name) {
+    super()
+
+    this.name = String(name)
+
+    this._port = exports._channel.connect()
+    this._inflight = 0
+    this._closed = false
+    this._reading = false
+
+    // The read loop terminates once the last peer leaves, so restart it when
+    // peers reappear to resume receiving broadcasts.
+    this._port.on('peers', this._onpeers.bind(this))
+
+    // An idle channel without listeners should not hold the thread alive.
+    this._port.unref()
+
+    this.on('newListener', this._onnewlistener).on('removeListener', this._onremovelistener)
+
+    this._read()
+  }
+
+  postMessage(message) {
+    if (this._closed) {
+      throw errors.CHANNEL_CLOSED('BroadcastChannel is closed')
+    }
+
+    this._write(message)
+  }
+
+  close() {
+    if (this._closed) return
+
+    this._closed = true
+
+    this._port.close()
+  }
+
+  [Symbol.for('bare.inspect')]() {
+    return {
+      __proto__: { constructor: BroadcastChannel },
+
+      name: this.name
+    }
+  }
+
+  async _write(message) {
+    this._inflight++
+    this._port.ref()
+
+    try {
+      await this._port.write({ name: this.name, message })
+    } finally {
+      this._inflight--
+      this._unref()
+    }
+  }
+
+  _unref() {
+    if (this._inflight === 0 && this.listenerCount('message') === 0) this._port.unref()
+  }
+
+  async _read() {
+    if (this._reading) return
+
+    this._reading = true
+
+    try {
+      for await (const data of this._port) {
+        // The channel shares a single underlying broadcast channel across the
+        // whole worker tree, so messages are tagged with their channel name and
+        // filtered on read.
+        if (data.name === this.name) this.emit('message', data.message)
+      }
+    } finally {
+      this._reading = false
+    }
+  }
+
+  _onpeers(peers) {
+    if (peers > 0 && !this._closed) this._read()
+  }
+
+  _onnewlistener(name) {
+    if (name !== 'message') return
+
+    if (this.listenerCount('message') === 0) this._port.ref()
+  }
+
+  _onremovelistener(name) {
+    if (name !== 'message') return
+
+    if (this.listenerCount('message') === 0) this._unref()
+  }
+
+  // The underlying broadcast channel shared by every named channel on this
+  // thread. Set when the worker module is loaded.
+  static _channel = null
+}

package/lib/errors.js

@@ -14,4 +14,8 @@ module.exports = class WorkerError extends Error {
   static ALREADY_STARTED(msg) {
     return new WorkerError(msg, WorkerError.ALREADY_STARTED)
   }
+
+  static CHANNEL_CLOSED(msg) {
+    return new WorkerError(msg, WorkerError.CHANNEL_CLOSED)
+  }
 }

package/lib/message-channel.js

@@ -1,5 +1,4 @@
 const Channel = require('bare-channel')
-const WorkerState = require('./worker-state')
 const MessagePort = require('./message-port')
 
 module.exports = class MessageChannel {
@@ -10,5 +9,3 @@ module.exports = class MessageChannel {
     this.port2 = new MessagePort(channel)
   }
 }
-
-if (WorkerState.parent) module.exports = WorkerState.parent.MessageChannel

package/lib/message-port.js

@@ -1,6 +1,5 @@
 const EventEmitter = require('bare-events')
 const Channel = require('bare-channel')
-const WorkerState = require('./worker-state')
 const constants = require('./constants')
 const errors = require('./errors')
 
@@ -219,8 +218,6 @@ module.exports = exports = class MessagePort extends EventEmitter {
   static _ports = new Set()
 }
 
-if (WorkerState.parent) module.exports = WorkerState.parent.MessagePort
-
 Bare.on('beforeExit', (exitCode) => {
   for (const port of exports._ports) port._beforeExit(exitCode)
 })

package/lib/worker-state.js

@@ -1,27 +1,44 @@
 const Channel = require('bare-channel')
+const Broadcast = require('bare-broadcast-channel')
+const MessagePort = require('./message-port')
 
 const state = Symbol.for('bare.worker.state')
 const kind = Symbol.for('bare.worker.state.kind')
 
-class WorkerState {
+module.exports = class WorkerState {
   static get [kind]() {
-    return 0 // Compatibility version
+    return 1 // Compatibility version
   }
 
-  constructor() {
-    this._MessageChannel = require('./message-channel')
-    this._MessagePort = require('./message-port')
+  static get parent() {
+    const parent = global[state]
+
+    if (typeof parent === 'object' && parent !== null && parent[kind] === WorkerState[kind]) {
+      return parent
+    }
+
+    return null
+  }
 
-    const { source, preloads, data, environmentData, channel: handle } = Bare.Thread.self.data
+  constructor() {
+    const {
+      source,
+      preloads,
+      data,
+      environmentData,
+      channel: handle,
+      broadcast: broadcastHandle
+    } = Bare.Thread.self.data
 
     this.source = source
     this.preloads = preloads
     this.data = Bare.Thread.self.data = data
     this.environmentData = environmentData
+    this.broadcast = Broadcast.from(broadcastHandle)
 
-    const channel = Channel.from(handle, { interfaces: [this._MessagePort] })
+    const channel = Channel.from(handle, { interfaces: [MessagePort] })
 
-    this.port = new this._MessagePort(channel)
+    this.port = new MessagePort(channel)
     this.port._online()
 
     global[state] = this
@@ -30,24 +47,4 @@ class WorkerState {
   get [kind]() {
     return WorkerState[kind]
   }
-
-  get MessageChannel() {
-    return this._MessageChannel
-  }
-
-  get MessagePort() {
-    return this._MessagePort
-  }
-}
-
-module.exports = exports = WorkerState
-
-if (
-  typeof global[state] === 'object' &&
-  global[state] !== null &&
-  global[state][kind] === WorkerState[kind]
-) {
-  exports.parent = global[state]
-} else {
-  exports.parent = null
 }

package/lib/worker-thread.js

@@ -8,17 +8,11 @@ Bare.on('newListener', onnewlistener)
   .on('uncaughtException', onerror)
   .on('unhandledRejection', onerror)
 
-const cache = Object.create(null)
-
 for (const [, source] of state.preloads) {
-  Module.load(
-    new URL(`bare:/worker/preload-${Math.random().toString(16).slice(2)}.bundle`),
-    source,
-    { cache }
-  )
+  Module.load(new URL(`bare:/worker/preload-${Math.random().toString(16).slice(2)}.bundle`), source)
 }
 
-Module.load(new URL('bare:/worker.bundle'), state.source, { cache })
+Module.load(new URL('bare:/worker.bundle'), state.source)
 
 function onnewlistener(name, fn) {
   if (fn === onremovelistener || fn === onerror) return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-worker",
-  "version": "4.1.8",
+  "version": "4.2.0",
   "description": "Higher-level worker threads for JavaScript",
   "exports": {
     ".": "./index.js",
@@ -9,7 +9,8 @@
     "./constants": "./lib/constants.js",
     "./errors": "./lib/errors.js",
     "./message-channel": "./lib/message-channel.js",
-    "./message-port": "./lib/message-port.js"
+    "./message-port": "./lib/message-port.js",
+    "./broadcast-channel": "./lib/broadcast-channel.js"
   },
   "files": [
     "index.js",
@@ -32,6 +33,7 @@
   },
   "homepage": "https://github.com/holepunchto/bare-worker#readme",
   "dependencies": {
+    "bare-broadcast-channel": "^0.2.0",
     "bare-channel": "^5.1.5",
     "bare-events": "^2.2.1",
     "bare-module": "^6.0.1",