BBVAEngineering/ember-web-workers

Service to communicate your application with browser web workers

ember-web-workers

Information

Service to communicate your application with browser web workers.

• Ember.js v3.12 or above
• Ember CLI v2.13 or above
• Node.js v10 or above

This addon can be installed with ember-cli:

• ember install ember-web-workers

Usage

• Create the web worker file in public (follow this blueprint):

// public/assets/web-workers/test.js

// Wait for the initial message event.
self.addEventListener('message', function(e) {
  var data = e.data;
  var port = e.ports[0];

  // Do your stuff here.
  if (port) {
    // Message sended throught a worker created with 'open' method.
    port.postMessage({ foo: 'foo' });
  } else {
    // Message sended throught a worker created with 'send' or 'on' method.
    postMessage({ bar: 'bar' });
  }
}, false);

// Ping the Ember service to say that everything is ok.
postMessage(true);

• Import the service in your application:

// Some Ember context.
{
  worker: Ember.inject.service()
}

• Use the methods to communicate with the web worker:

postMessage

Method used to make a request and wait for a response. This method returns a promise that will be resolved after the worker responses.

When promise resolves the worker will be terminated.

Arguments:

• worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).
• data: transferable object (true will be ignored, def. for ping).

// Some Ember context.
{
  foo() {
    return this.get('worker').postMessage('test', { foo: 'bar' }).then((response) => {
        // response => { bar: 'bar' }
      }, (error) => {
        // error contains the message thrown by the worker.
      });
  }
}

terminate

Using this method a pending promise can be cancelled, this will terminate the worker associated and the promise will be rejected.

If promise is not provided, it will kill all the active workers.

Arguments:

• promise: the promise returned by the send function (optional).

// Some Ember context.
{
  foo() {
    const worker = this.get('worker');
    const promise = worker.postMessage('test', { foo: 'bar' });

    worker.terminate(promise);
  }
}

on/off

Methods used to subscribe to a worker events. The worker will be alive until the event is detached.

Arguments:

• worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).
• callback: callback to be executed each time worker sends a message (postMessage). callback is optional for off method.
  • If callback is not passed for off method, then all the instantiated worker with the passed name will be terminated
  • If callback is passed, then the corresponding worker associated with the callback will only be terminated.

// Some Ember context.

function callback(data) {
  console.log(data.foo, data.bar); // 'foo bar'
}

{
  foo() {
    const worker = this.get('worker');

    return worker.on('test', callback).then(() => {
        // Worker has been created.
        // Terminate it after 5 seconds.
        setTimeout(() => {
          worker.off('test', callback);
        }, 5000);
      }, (error) => {
        // Worker error, it has been terminated.
      });
  }
}

open

This method creates a new worker and stablish a communication allowing to keep it alive to send 1..n messages until terminates.

Arguments:

• worker: the name of the worker to create (used to create the file path dist/assets/web-workers/${name}.js).

Promise argument (object):

• postMessage: Alias to send a message to the worker.
• terminate: Close the connection and terminate the worker

// Some Ember context.

{
  foo() {
    const worker = this.get('worker');

    return worker.open('test').then((stream) => {
        const data1 = stream.send({ foo: 'foo' });
        const data2 = stream.send({ bar: 'bar' });

        // Wait responses.
        return Ember.RSVP.all([data1, data2]).then(() => {
          // Kill the worker.
          stream.terminate();

          // Do something with the worker responses.
          return data1.foo + data2.bar;
        });
      }, (error) => {
        // Worker error, it has been terminated.
      });
  }
}

Handling errors

To reject the promise an error must be thrown inside the worker:

// Worker context.

throw new Error('foo');

// Some Ember context.

{
  foo() {
    return this.get('worker').postMessage('test').catch((error) => {
        console.error(error); // Unhandled error: foo
      });
  }
}

Contribute

If you want to contribute to this addon, please read the CONTRIBUTING.md.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

See the list of contributors who participated in this project.

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details