angular-workers

A wrapper for web workers in angular

###Why?

Using web workers is somewhat awkward in raw Javascript. Doing it in angular applications even more so. Each web worker runs in it's own context, and this context is isolated from the angular application.

###What does angular-workers do angular-workers provides an angular service which upon request creates a web worker. The returned web worker runs it's own angular context which allows it to resolve angular dependencies.

Mor information about how angular-worker work can be found in this blog post.

##Installation

install with bower using:

bower install angular-workers

##How to use

• Depend on the WorkerService.

• Specify the URL to the file containing the angular script by invoking:

  // The URL must be absolute because of the URL blob specification  
  WorkerService.setAngularUrl(url)

• OPTIONALLY: Specify how the web worker is to find any dependencies by invoking:

  // The URL must be absolute because of the URL blob specification  
  WorkerService.addDependency(serviceName, moduleName, url) 

• Create create a promise of an angularWorker by invoking:

  var workerPromise = WorkerService.createAngularWorker(['input', 'output' /*additional optional deps*/,   
      function(input, output /*additional optional deps*/) {  
          // This contains the worker body.
          // The function must be self contained. The function body will be 
          // converted to source and passed to the worker.  
          // The input parameter is what will be passed to the worker when
          // it is executed. It must be a serializable object.
          // The output parameter is a promise and is what the 
          // worker will return to the main thread.  
          // All communication from the worker to the main thread is performed
          // by resolving, rejecting or notifying the output promise.
          // We may optionally depend on other angular services. 
          // These services can be used just as in the main thread. 
          // But be aware that no state changes in the angular services in the
          // worker are propagates to the main thread. Workers run in fully isolated
          // contexts. All communication must be performed through the output parameter.
    }]);
    ```

• When the workerPromise resolves the worker is initialized with it's own angular context and is ready to use. Like so:

  workerPromise.then(function success(angularWorker) {  
      //The input must be serializable  
      return angularWorker.run(inputObject);    
    }, function error(reason) {  
      //for some reason the worker failed to initialize  
      //not all browsers support the HTML5 tech that is required, see below.  
    }).then(function success(result) {  
      //handle result  
    }, function error(reason) {  
      //handle error  
    }, function notify(update) {  
      //handle update  
    });
    ```

The same initialized worker can be used many times with different input.

##Requirements

The browser running the angular service needs to support the following:

• Web Workers (angular-workers does not use shared workers)
• Blob URLs, specifically creating blobs from strings

##Limitations

The angular-workers is a wrapper around standard web workers. So all limitations with web workers apply.

• Data sent between the worker and main thread is deep cloned. (angular-workers does not use transferable objects, yet) This means transferring large object (about >20Mb, Communicating Large Objects with Web Workers in javascript, Samuel Mendenhall) will cause noticeable delays. Samuel Mendenhall recommends sending the data in chunks. This can be achieved using the notify in the angular promise.
• There is no DOM in the worker. Other things are missing as well. No global "document" object. The bare minimum of these have been mocked to allow angular to start in the worker.
• The web worker share no runtime data with the main thread. This is great since it prevents deadlock, starvation and many other concurrency issues. But it also means that any angular service instance upon which your worker depends is created in that worker, and not shared with the main thread. One can not communicate data between worker and main thread by using service states. All communication must be done through the input object and output promise.
• Running in a separate context means the web worker does not share the cookies set in the main thread! If you depend on cookies for authentication pass these manually to the worker.