ember-web-workers

Service to communicate your application with browser web workers.

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).

// 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
      });
  }
}

Installation

git clone https://github.com/BBVAEngineering/ember-web-workers.git
cd ember-web-workers
npm install
bower install

Running

ember serve
Visit your app at http://localhost:4200.

Running Tests

Use Chrome for testing (not sure if PhantomJS has web workers).

npm test (Runs ember try:each to test your addon against multiple Ember versions)
ember test
ember test --server

Building

ember build

For more information on using ember-cli, visit https://ember-cli.com/.

knownasilya / ember-web-workers Goto Github PK