threadify
v0.2.4
Published
Simply transforms a javascript function into a web worker
Downloads
29
Maintainers
Readme
Threadify
Threadify is a browser-side Javascript library that allows you to run any Javascript function into a web worker.
Example of a threadified function:
var myFunction = threadify(function (param1, param2) {
// This will be executed inside a web worker
console.log("Hello from the worker");
return param1 + param2;
});
var job = myFunction("foo", "bar");
job.done = function (result) {
console.log(result);
};
Getting Started
Getting Threadify
Standalone Version
First download the Threadify zip or clone the repository.
Then include the threadify.js
or threadify.min.js
(from the dist
folder) in you HTML page:
<script src="dist/threadify.js"></script>
NPM and Browserify
First install the threadify
package:
npm install --save threadify
Then include it where you need it:
var threadify = require("threadify");
Threadifying a Function
To run a function in a web worker, you have to threadify it:
var myFunction = threadify(function (param1, param2) {
// The code of this function will be executed inside a web worker
return param1 + param2;
});
Then, to run your threadified function, you just have to call it as any other function:
var job = myFunction("param1", "param2");
When you call your threadified function, it returns a Job
object that allow you to control the worker and to retrieve values returned by the function.
To get the result of your function, just define a done
callback on the Job
object:
// this function will be called once the function return something.
job.done = function (result) {
console.log(result);
};
Returning Values
The simplest way to return a value from the threadified function is to use the return
keyword as usual:
var myFunction = threadify(function (param1, param2) {
return param1 + param2;
});
But if you have asynchrone code in your function (or if you want to return more than one value), you will not be able to use the return
keyword. But you can use the this.return()
method instead:
var myFunction = threadify(function (param1, param2) {
this.return(param1, param2);
});
Be careful of the this
context when you call this.return()
from a callback. For instance, the following code will not work because of the wrong this
context:
var myFunction = threadify(function (param1, param2) {
setTimeout(function () {
this.return(param1, param2);
}, 1000);
});
To fix it, you can modify it like this:
var myFunction = threadify(function (param1, param2) {
var thread = this;
setTimeout(function () {
thread.return(param1, param2);
}, 1000);
});
The worker still alive until you return something or you terminate it explicitly.
NOTE: if you just use the return
keyword without any value, the worker will not be terminated.
About Web Workers Limitations
Web workers are executed in an other thread than your main script / page, this causes some limitations detailed bellow.
Accessible Objects
From the worker (the threadified function) you cannot access to all browser's objects you are used to. For instance, this is some objects that are not accessible:
the
window
object,the
document
object ,DOM / DOM elements (you cannot manipulate the HTML of your page),
other functions / classes / objects / variables of your main thread (you cannot access to anything outside your threadified function),
...
Arguements and Returned Values
You cannot send / return any type of argument to / from a worker. Threadify allows you to send / return:
Simple types / values (copied):
Number
String
Boolean
Array
¹Object
¹undefined
null
Infinity
NaN
Blob
, ~~File
~~ (copied) TODO: check if File worksError
objects (copied)ArrayBuffer
(transfered)Typed arrays (transfered):
Int8Array
Uint8Array
Uint8ClampedArray
Int16Array
Uint16Array
Int32Array
Uint32Array
Float32Array
Float64Array
DataView
(transfered)Canvas
ImageData
(transfered)
Depending on their types, arguments can be copied or transfered to the worker. A transfered argument means that its access is transfered to the worker and that it will no more be accessible from the main thread.
NOTE¹: Only if they contains allowed types (no class, no function,...)
Job API
You get the Job
object each time you call a threadified function:
var myFunction = threadify(function (param1, param2) {
// The code of this function will be executed inside a web worker
return param1 + param2;
});
var job = myFunction("foo", "bar");
Methods
job.terminate()
: terminates immediately the worker without letting it an opportunity to finish its operations.
job.terminate();
Callbacks
job.done = function (result) {}
: called when the threadified function returns something. Please note that the worker is terminated right after it returns the value.job.failed = function (error) {}
: called when an error occurred in the threadified function. Please note that the worker is not always terminated when an error occurred.job.terminated = function () {}
: called when the worker is terminated.
Thread API
Inside the threadified function, you have access to a Thread
object through the this
context.
var myFunction = threadify(function (param1, param2) {
var thread = this;
});
Methods
thread.terminate()
: terminates immediately the worker.thread.error(error)
: Reports an error (this will calls thejob.failed
callback function). Please not that calling this method will not terminate the worker.thread.return(param [, param2 [, ...]])
: return one or more values (this will call thejob.done
callback function) and terminates the worker.
Hacking
Threadify is built using Grunt and Browserify. To start hacking Threadify, you will have to install few tools.
Installing Dependencies
To build Threadify, you will first have to install Node.js (or io.js).
NOTE: If you are on Ubuntu / Debian Linux you must install the nodejs-legacy
package.
Next, install globally the grunt-cli
npm package:
npm install -g grunt-cli
Then install the required dependencies:
npm install
Building Threadify
Once the build stuff and dependencies installed, you just have to run the grunt
command to build Threadify:
grunt
All generated files are in the dist
folder.
Coding Style
Threadify follows the Yandex Javascript CodeStyle EXCEPT for the quote marks where double quotes ("
) are used.
You can automatically check that your code follows the conventions by using this command:
grunt jscs
Running Tests
To run the tests, first check that the javascript is well formed and that it follows the coding style:
grunt jshint jscs
Then, open the following page in your web browser:
test/SpecRunner.html
Changelog
- 0.2.4: Cleaner package (avoid including useless files)
- 0.2.3:
- Fixes issue with minification (#6)
- Updates dependencies
- 0.2.2: Avoid minification issue (#3)
- 0.2.1: Fix for old browsers that do not implement
ImageData
- 0.2.0: Allow to tranfer / copy more types between the main thread and the worker
- 0.1.0: First release: basic functionalities required to build and run workers