Notorious Penguin Magicians

    async-thread-worker

    0.9.3 • Public • Published

    async-thread-worker

    An async/await abstraction for Web Workers

    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
    

    Install

    npm i async-thread-worker

    DownloadsWeekly Downloads

    0

    Version

    0.9.3

    License

    MIT

    Unpacked Size

    40 kB

    Total Files

    11

    Last publish

    Collaborators

    • j-devel