USRZ Rodosha API

Rodosha (労働者 - or "worker" in Japanese) are an easier way to deal with multi-threading in the browser by using Web Workers

The implementation is wrapped in a rodosha Esquire module which provides a create(...) method. This method will return a Promise which will be resolved with the instance of the Rodosha or rejected with a failure:

esquire.inject(['rodosha'], function(rodoshaFactory) {
  rodoshaFactory.create().then(function(rodosha) {
    // foo! do something...
  });
})

Rodoshas operate mainly of Esquire modules which can be imported directly in a remote worker:

rodosha.import('module-a', 'module-b').then(function(imported) {
  // the modules (and all their dipendencies) were imported...
});

Object proxies

After those modules are imported, local proxy objects pointing to their instances in the worker can be created quite trivially:

rodosha.proxy('module-a').then(function(proxy) {
  // the "proxy" variable is a local object proxying an instance in the worker
})

Any method and variable in objects being proxied will be replaced with a Promise, and method execution, or value retrieval will trigger a message, be executed in the Worker and its result will resolve or reject the promise.

So if a module defines a method called foo() and a variable bar like:

{
  foo: function(arg) {
    return "Called with " + arg;
  },
  bar: "hello, world"
}

It's proxy will return promises for both:

proxy.foo("my value").then(result) {
  // result will be "Called with my value"
}
proxy.bar.then(value) {
  // value will be "hello world"
}

What will happen under the covers is that messages will be sent to the Worker asking for the method to be executed in its remote native thread (or the variable's value to be evaluated) and once a response is received locally the returned promises will be resolved or rejected.

Proxies from functions

A special note for function calls is that their return values can also be retrieved as a proxy object by invoking the asProxy() method on the returned promise.

So, for example, if a function is defined as:

function gimmeAnObject() {
  // this will return a complex object, with functions and properties
}

Locally its result can be used through a proxy (henceforth, its methods will still be invoked - and variables evaluated - in the Worker):

proxy.gimmeAnObject().asProxy().then(function(newProxy) {
  // newProxy will be a proxy object to what's returned...
})

Cleaning up

Proxies can (should) be discarded when no longer needed, freeing up memory in the Worker:

rodosha.destroy(proy);

The Worker itself can be closed gracefully

rodosha.close().then(function() {
  // nicely closed
});

or terminated abruptly calling rodosha.terminate().