Skip to content

Latest commit

 

History

History
154 lines (119 loc) · 9.83 KB

README.md

File metadata and controls

154 lines (119 loc) · 9.83 KB

async-thread-worker

An async/await abstraction for Web Workers

npm MIT licensed CI

About

async-thread-worker presents an abstraction of Web Worker thread communication based on the client-server model. Supported features are:

  • awaiting thread operations,
  • integration of basic Web Worker APIs (e.g. transferables, the terminate() method etc.), and
  • class methods/interfaces for implementing client-server style functionality.

After introducing some basic examples for quickly getting started, we demonstrate applications using Wasm binaries (C code compiled by Emscripten and Rust code by wasm-pack) embedded inside worker threads.

For other libraries that realize similar functionality, you might also consider:

Getting Started

Installation

$ npm install async-thread-worker

Usage

Here's a basic example of implementing a worker (abstracted as thread) and interacting with it. Use sendRequest() and sendResponse() for client-server style communications. [ demo | source ]

index.html: Synchronously sending requests to a worker.

// <script src='async-thread-worker.min.js'></script>

const thread = new AsyncThreadWorker.Thread('my-thread-worker.js');

for (let payload of ['a', 'b', 'c', 'd']) {
    const response = await thread.sendRequest(payload);
    console.log('[main] got response:', response);
}

my-thread-worker.js: Implementation of the worker. Use the provided id to respond to a request.

importScripts('async-thread-worker.min.js');

class MyThreadWorker extends AsyncThreadWorker.ThreadWorker {
    onRequest(id, payload) { // impl
        console.log('[worker] got request with:', payload);
        this.sendResponse(id, payload.toUpperCase());
    }
}
const myThreadWorker = new MyThreadWorker(self);

The results in the developer console:

[worker] got request: a
[main] got response: A
[worker] got request: b
[main] got response: B
[worker] got request: c
[main] got response: C
[worker] got request: d
[main] got response: D

Examples

API

AsyncThreadWorker.Thread

The Thread class is for abstraction of the main thread's side (client).

  • constructor(path) Creates a Thread object that is a worker's interface. The underlying Web Worker object wrapped by Thread is also created based on its implementation specified by path.

    • path string The path to a worker's implementation.
  • sendRequest(payload=undefined, transferables=[]) Sends a request to the worker (server) with data payload. Transferable objects can be specified in the optional transferbles array so that they are efficiently sent to the other thread without structured clone. Returns a promise corresponding to the server's action (sendResponse() or sendError()).

    • payload object | primitive e.g. 42, or {name: 'foo', input: buf}, where buf is an ArrayBuffer.
    • transferables Array<object> e.g. [buf,]
  • getWorker() Returns the raw Web Worker object wrapped by Thread (or null if the worker is already terminated).

  • terminate() Immediately terminates the worker (internally using Worker.terminate()).

AsyncThreadWorker.ThreadWorker

The ThreadWorker class is for abstraction of the worker's side (server).

  • constructor(self, opts={}) Creates a ThreadWorker object that represents the worker thread by wrapping the bare Web Worker object (self).

  • onRequest(id, payload) Called when the worker thread (server) received a request with data payload from the main thread (client). Implement this method to respond to the client by either sendResponse() or sendError().

  • sendResponse(id, payload=undefined, transferables=[]) Sends a response to the main thread (client) with data payload. Transferable objects can be specified in the optional transferbles array so that they are efficiently sent to the other thread without structured clone.

    • id string A request id provided by onRequest().
    • payload object | primitive e.g. 42, or {name: 'foo', output: buf}, where buf is an ArrayBuffer.
    • transferables Array<object> e.g. [buf,]
  • sendError(id, error) Sends an error response to the main thread (client) with data error.

    • id string A request id provided by onRequest().
    • error object | primitive
  • onCreate(opts) Called when the ThreadWorker is created. One may override this method when extending the ThreadWorker class.

    • opts object Optional parameters given to constructor().

Build

$ npm install  # set up build tools
$ npm run build