Confirm
137
edits
Changes
New page: == DOM Worker Threads API Proposal == == Abstract == This is an API '''proposal''' for DOM Worker Threads. At this time this document is not complete and is not yet ready for general co...
== DOM Worker Threads API Proposal ==
== Abstract ==
This is an API '''proposal''' for DOM Worker Threads.
At this time this document is not complete and is not yet ready for general consideration or debate. It's just getting started!
Look for a post to mozilla.dev.platform when this proposal is ready to be discussed.
== Introduction ==
=== Use Cases ===
=== Terminology ===
A '''worker''' is an execution context for JavaScript that runs off of the main UI thread. The global scope for a worker is almost empty - familiar objects such as <code>window</code> and <code>document</code> are not available, nor is the Mozilla-specific <code>Components</code> object.
A '''worker pool''' is a collection of related workers. Workers within a pool can communicate with each other freely, but workers cannot communicate with workers from another pool.
== Conformance ==
== Dependencies ==
== Specification Proposal ==
<blockquote>
<code>
<pre>
#include "nsISupports.idl"
interface nsIDOMWorkerThread;
interface nsIScriptError;
interface nsIURI;
[scriptable, function, uuid(e50ca05d-1381-4abb-a021-02eb720cfc38)]
interface nsIDOMWorkerMessageListener : nsISupports
{
/**
* An nsIDOMWorkerThread receives the onMessage callback when another
* worker posts a message to it.
*
* @param aMessage (in DOMString)
* The message sent from another worker.
* @param aSource (in nsIDOMWorkerThread)
* The worker that sent the message. Useful for a quick response.
*/
void onMessage(in DOMString aMessage,
in nsIDOMWorkerThread aSource);
};
[scriptable, function, uuid(9df8422e-25dd-43f4-b9b9-709f9e074647)]
interface nsIDOMWorkerErrorListener : nsISupports
{
/**
* An nsIDOMWorkerPool receives the onError callback when one of its child
* workers has a parse error or an unhandled exception.
*
* @param aMessage (in nsIScriptError)
* Details about the error that occurred. See nsIScriptError.
* @param aSource (in nsIDOMWorkerThread)
* The worker that sent the message. Depending on the specific error in
* question it may not be possible to use this object (in the case of a
* parse error, for instance, aSource will be unusable).
*/
void onError(in nsIScriptError aError,
in nsIDOMWorkerThread aSource);
};
[scriptable, uuid(6f19f3ff-2aaa-4504-9b71-dca3c191efed)]
interface nsIDOMWorkerThread : nsISupports
{
/**
* The nsIDOMWorkerMessageListener which handles messages for this worker.
*
* Developers should set this attribute to a proper object before another
* worker begins sending messages to ensure that all messages are received.
*
* The main script can set this property directly on the pool object.
*
* Worker scripts must set this attribute on the 'thisThread' global object
* defined in its scope. Setting the messageListener from the pool's script is
* not permitted.
*/
attribute nsIDOMWorkerMessageListener messageListener;
/**
* Sends a message to the worker.
*
* @param aMessage (in DOMString)
* The message to send. This may be a string or an object that can be
* serialized via JSON (see http://developer.mozilla.org/en/docs/JSON).
*/
void postMessage(in DOMString aMessage);
};
[scriptable, uuid(45312e93-8a3e-4493-9bd9-272a6c23a16c)]
interface nsIDOMWorkerPool : nsIDOMWorkerThread
{
/**
* The nsIDOMWorkerErrorListener which handles errors in child threads.
*
* Developers should set this attribute to a proper object before calling
* createWorker in order to catch parse errors as well as runtime exceptions.
*/
attribute nsIDOMWorkerErrorListener errorListener;
/**
* Create a new worker object by evaluating the given script.
*
* @param aSourceScript (in DOMString)
* The script to compile. See below for details on the scope in which
* the script will run.
*/
nsIDOMWorkerThread createWorker(in DOMString aSourceScript);
/**
* Create a new worker object by evaluating the given script file.
*
* @param aSourceScript (in nsIURI)
* The script file to compile. See below for details on the scope in
* which the script will run. See nsIURI.
*/
nsIDOMWorkerThread createWorkerFromURI(in nsIURI aSourceScript);
};
</pre>
</code>
</blockquote>
=== The worker pool's scope ===
The scope for the worker pool is the standard DOM scope. All DOM objects such as <code>window</code> and <code>document</code> are available, as well as functions such as <code>alert()</code> and <code>dump()</code>.
=== The worker's scope ===
The worker's scope is far more limited.
A worker has access to the following objects:
* <code>thisThread</code>
** This is the <code>nsIDOMWorkerThread</code> object representing the current worker. It can be passed as an argument to the <code>postMessage</code> method on another <code>nsIDOMWorkerThread</code> object or on the <code>postMessageToPool()</code> function.
A worker has access to the following global functions:
* <code>dump(in DOMString aString)</code>
** The same as normal <code>dump()</code> for DOM scopes. <code>aString</code> is output to the console.
* <code>postMessageToPool(in DOMString aMessage)</code>
** The same as calling <code>postMessage</code> on the <code>nsIDOMWorkerPool</code> object that created the worker.
=== Sample usage ===
<blockquote>
<code>
<pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<title>Test threads</title>
<body>
<script language="javascript">
var scriptToRun = 'function messageListener(message, source) { ' +
' dump("Worker: " + message + "\\n"); ' +
'} ' +
'thisThread.messageListener = messageListener; ' +
'for (var i = 0; i < 10000000; i++) { ' +
' /* do something */ ' +
'} '+
'sendMessageToPool("Done!"); ';
var wp = navigator.newWorkerPool();
wp.messageListener = function(message, source) {
dump("Pool: " + message + "\n");
};
wp.errorListener = function(error, source) {
dump("Pool: error = '" + error + "'\n");
}
var threads = []
for (var i = 0; i < 10; i++) {
var thread = wp.createWorker(scriptToRun);
thread.postMessage("hello");
threads.push(thread);
}
</script>
</body>
</html>
</pre>
</code>
</blockquote>
== Not In This Specification ==
== References ==
The only thing I've seen so far is the [http://code.google.com/apis/gears/api_workerpool.html Google Gears WorkerPool API]. We would certainly like to provide a compatibility API that would make migrating Gears code trivial.
== Acknowledgements ==
== Abstract ==
This is an API '''proposal''' for DOM Worker Threads.
At this time this document is not complete and is not yet ready for general consideration or debate. It's just getting started!
Look for a post to mozilla.dev.platform when this proposal is ready to be discussed.
== Introduction ==
=== Use Cases ===
=== Terminology ===
A '''worker''' is an execution context for JavaScript that runs off of the main UI thread. The global scope for a worker is almost empty - familiar objects such as <code>window</code> and <code>document</code> are not available, nor is the Mozilla-specific <code>Components</code> object.
A '''worker pool''' is a collection of related workers. Workers within a pool can communicate with each other freely, but workers cannot communicate with workers from another pool.
== Conformance ==
== Dependencies ==
== Specification Proposal ==
<blockquote>
<code>
<pre>
#include "nsISupports.idl"
interface nsIDOMWorkerThread;
interface nsIScriptError;
interface nsIURI;
[scriptable, function, uuid(e50ca05d-1381-4abb-a021-02eb720cfc38)]
interface nsIDOMWorkerMessageListener : nsISupports
{
/**
* An nsIDOMWorkerThread receives the onMessage callback when another
* worker posts a message to it.
*
* @param aMessage (in DOMString)
* The message sent from another worker.
* @param aSource (in nsIDOMWorkerThread)
* The worker that sent the message. Useful for a quick response.
*/
void onMessage(in DOMString aMessage,
in nsIDOMWorkerThread aSource);
};
[scriptable, function, uuid(9df8422e-25dd-43f4-b9b9-709f9e074647)]
interface nsIDOMWorkerErrorListener : nsISupports
{
/**
* An nsIDOMWorkerPool receives the onError callback when one of its child
* workers has a parse error or an unhandled exception.
*
* @param aMessage (in nsIScriptError)
* Details about the error that occurred. See nsIScriptError.
* @param aSource (in nsIDOMWorkerThread)
* The worker that sent the message. Depending on the specific error in
* question it may not be possible to use this object (in the case of a
* parse error, for instance, aSource will be unusable).
*/
void onError(in nsIScriptError aError,
in nsIDOMWorkerThread aSource);
};
[scriptable, uuid(6f19f3ff-2aaa-4504-9b71-dca3c191efed)]
interface nsIDOMWorkerThread : nsISupports
{
/**
* The nsIDOMWorkerMessageListener which handles messages for this worker.
*
* Developers should set this attribute to a proper object before another
* worker begins sending messages to ensure that all messages are received.
*
* The main script can set this property directly on the pool object.
*
* Worker scripts must set this attribute on the 'thisThread' global object
* defined in its scope. Setting the messageListener from the pool's script is
* not permitted.
*/
attribute nsIDOMWorkerMessageListener messageListener;
/**
* Sends a message to the worker.
*
* @param aMessage (in DOMString)
* The message to send. This may be a string or an object that can be
* serialized via JSON (see http://developer.mozilla.org/en/docs/JSON).
*/
void postMessage(in DOMString aMessage);
};
[scriptable, uuid(45312e93-8a3e-4493-9bd9-272a6c23a16c)]
interface nsIDOMWorkerPool : nsIDOMWorkerThread
{
/**
* The nsIDOMWorkerErrorListener which handles errors in child threads.
*
* Developers should set this attribute to a proper object before calling
* createWorker in order to catch parse errors as well as runtime exceptions.
*/
attribute nsIDOMWorkerErrorListener errorListener;
/**
* Create a new worker object by evaluating the given script.
*
* @param aSourceScript (in DOMString)
* The script to compile. See below for details on the scope in which
* the script will run.
*/
nsIDOMWorkerThread createWorker(in DOMString aSourceScript);
/**
* Create a new worker object by evaluating the given script file.
*
* @param aSourceScript (in nsIURI)
* The script file to compile. See below for details on the scope in
* which the script will run. See nsIURI.
*/
nsIDOMWorkerThread createWorkerFromURI(in nsIURI aSourceScript);
};
</pre>
</code>
</blockquote>
=== The worker pool's scope ===
The scope for the worker pool is the standard DOM scope. All DOM objects such as <code>window</code> and <code>document</code> are available, as well as functions such as <code>alert()</code> and <code>dump()</code>.
=== The worker's scope ===
The worker's scope is far more limited.
A worker has access to the following objects:
* <code>thisThread</code>
** This is the <code>nsIDOMWorkerThread</code> object representing the current worker. It can be passed as an argument to the <code>postMessage</code> method on another <code>nsIDOMWorkerThread</code> object or on the <code>postMessageToPool()</code> function.
A worker has access to the following global functions:
* <code>dump(in DOMString aString)</code>
** The same as normal <code>dump()</code> for DOM scopes. <code>aString</code> is output to the console.
* <code>postMessageToPool(in DOMString aMessage)</code>
** The same as calling <code>postMessage</code> on the <code>nsIDOMWorkerPool</code> object that created the worker.
=== Sample usage ===
<blockquote>
<code>
<pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<title>Test threads</title>
<body>
<script language="javascript">
var scriptToRun = 'function messageListener(message, source) { ' +
' dump("Worker: " + message + "\\n"); ' +
'} ' +
'thisThread.messageListener = messageListener; ' +
'for (var i = 0; i < 10000000; i++) { ' +
' /* do something */ ' +
'} '+
'sendMessageToPool("Done!"); ';
var wp = navigator.newWorkerPool();
wp.messageListener = function(message, source) {
dump("Pool: " + message + "\n");
};
wp.errorListener = function(error, source) {
dump("Pool: error = '" + error + "'\n");
}
var threads = []
for (var i = 0; i < 10; i++) {
var thread = wp.createWorker(scriptToRun);
thread.postMessage("hello");
threads.push(thread);
}
</script>
</body>
</html>
</pre>
</code>
</blockquote>
== Not In This Specification ==
== References ==
The only thing I've seen so far is the [http://code.google.com/apis/gears/api_workerpool.html Google Gears WorkerPool API]. We would certainly like to provide a compatibility API that would make migrating Gears code trivial.
== Acknowledgements ==
