krishedges / ember-parallel

An Ember.js plugin proving integration with Parallel.js

Ember-Parallel

An Ember.js plugin proving integration with Parallel.js

This plugin allows you to run code inside web workers in the browser (i.e. in background threads) and access the results easily within your ember app. This is particularly useful when you're dealing with large quantities of data, or computationally expensive algorithms within your app that would otherwise lock up the browser for a period of time.

Requires

• Ember.js
• Parallel.js

Builds

Find the current version in build/.

Find the latest stable release in dist/.

Note that Ember-Parallel is still new so should be considered unstable and subject to change without warning.

Demo

See the demo/ folder for a demo.

Usage

Ember-Parallel wraps Parallel.js and makes it usable with Ember.js. To do this, it provides a few things:

###Computed Promises

Computed promises let you use promises as if they were computed properties. This means that you can create computed properties in an asynchronous manner and have them update asynchronously when dependencies change. Use them as follows:

Em.computed.promise([deps...], func, [defaultValue])

deps are optional and specify dependencies for your promise func is a function that returns a promise defaultValue is optional and provides a value until the promise resolves

App.Foo = Em.Object.extend({
	currentPage: 1,

	pageContents: Em.computed.promise('currentPage', function() {
		return $.getJSON('/api/todos?page=' + this.get('currentPage'));
	}, [])
});

pageContents can then be used as a regular computed property, with the last argument ([]) becoming the initial default value. When the promise has resolved, `pageContents will take on the fulfilled value of the promise.

The promise itself is also available at pageContentsPromise.

###Em.JSONify

As Ember-Parallel uses Web Workers, it needs to serialise Ember objects into plain old javaScript objects (POJOs). To do this, it expects every object to have a toJSON method on it. It provides a basic toJSON method with can then be replaced with custom, improved methods in your own code.

Em.JSONify is also provided, and converts any JS object (whether Ember or already a POJO) into a POJO.

var obj = Em.Object.create({ foo: 1 });

obj.toJSON();

Em.JSONify(obj);

###Parallel Computed Properties

Ember-Parallel provides some convenience wrappers around ParallelJS to help you work with web workers inside Ember.

The following computed properties are provided by default:

####Em.computed.parallel.map

Em.computed.parallel.map(propName, func, initValue);

propName is the name of the property containing the list that you want to map over func is a function that takes a single element of the list and transforms it is some way initValue is returned when the map is running in the background

App.foo = Em.Object.extend({
	list: [40, 41, 42],

	fibs: Em.computed.parallel.map('list', function fib(n) {
		return n < 2 ? 1 : fib(n - 1) + fib(n - 2);
	})
});

Note that the function fib needs to be named in order to deal with recursion, and that it cannot reference anything Ember related, or anything outside of the function itself. This is because the function is run inside a separate thread, so has no access to any other JS present outside that thread.

####Em.computed.parallel.reduce

Em.computed.parallel.reduce(propName, func, initValue)

propName is the name of the property containing the list that you want to reduce func is a function that takes a list containing two elements from the original list and returns a reduced value initValue is a default value to use until the reduce function completes

App.foo = Em.Object.extend({
	list: [40, 41, 42],

	total: Em.computed.parallel.reduce('list', function (list) {
		return list[0] + list[1];
	}, 0)
});

Em.computed.reduce takes property name to reduce on, a reducer function (note that the same restrictions as Em.computed.parallel.map apply), and a default initial value (in this case case 0. The reducer function take a list of two elements as the argument.

####Em.computed.parallel.spawn

Em.computed.parallel.spawn(dep, func, initValue)

dep is the dependency that your spawn function relies on. func will be passed this dependency as an argument func is a function that takes all of the data in dep and returns a completed value initValue is a default value to use until the spawn function completes

App.foo = Em.Object.extend({
	list: [40, 41, 42],

	total: Em.computed.parallel.spawn('list.[]', function (list) {
		return list.map(function(d) {
			return d * 2;
		}).reduce(function(total, d) {
			return d + total;
		}, 0);
	}, 0)
});

Em.computed.parallel.spawn is useful for operations that do no fit cleanly into parallel map/reduce but that still need to be done in the background. It runs the given function inside it's own web worker for you to do whatever you like with (e.g. sorting a list).

###Em.parallelConfig

Em.parallelConfig = {
	maxWorkers: 4,
	evalPath: null
};

Set up some default config to be passed through to each created ParallelJS instance. Options and defaults are the same as for paralleljs. To use ember-parallel in IE, you'll need to grab eval.js from parallel.js and set evalPath here to its location.

###parallelDependencies

App.foo = Em.Object.extend({
	list: [40, 41, 42],

	parallelDependencies: {
		fib: function(n) {
			return n < 2 ? 1 : fib(n - 1) + fib(n - 2);
		}
	}

	fibs: Em.computed.parallel.map('list', function(n) {
		return fib(n);
	}
});

parallelDependencies is a list of name/function pairs that you define on an Ember object. Any functions you define here will be available to you inside your Em.computed.parallel functions.