MozillaWiki

DOMWorkerThreads current: Difference between revisions

Page Discussion

DOMWorkerThreads current (view source)

Revision as of 19:48, 6 November 2008

2,424 bytes removed ,  6 November 2008
no edit summary
No edit summary
No edit summary
Line 1: Line 1:
This page describes the API used in the Firefox 3.1 Alpha 2 release. We expect to update it to follow the spec before shipping Firefox 3.1, possibly as early as beta 1.
This page describes the API used in the Firefox 3.1 Beta 2 release. We expect few changes before final release, and nothing that would break compatibility with what we currently implement.


Though the syntax will change, the implementation for the current feature set will remain largely the same, so please do file bugs if you find any.
Please do file bugs if you find any!


== Sample usage ==
== Sample usage ==
fibonacci.html:


<blockquote>
<blockquote>
<code>
<code>
<pre>
<pre>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<html>
   <title>Fibonacci from a worker thread</title>
   <title>Test threads fibonacci</title>
   <body>
   <body>


   <div id="start-div"></div>
   <div id="result"></div>
  <p><div id="result-div">Result from worker: (pending)</div></p>
  <div id="end-div"></div>


   <script language="javascript">
   <script language="javascript">
    var startdiv = document.getElementById("start-div");
    var resultdiv = document.getElementById("result-div");
    var enddiv = document.getElementById("end-div");


     startdiv.innerHTML = "Started: " + new Date();
     var worker = new Worker("fibonacci.js");


     function scriptToRun() {
     worker.onmessage = function(event) {
       // Hook us up to receive messages from the pool
       document.getElementById("result").textContent = event.data;
      this.messageListener = function (message, source) {
        var num = parseInt(message);
        if (isNaN(num))
          throw "Pool sent a value we couldn't interpret!";
        postMessageToPool(fibonacci(num));
      };
 
      // Worst implementation of fibonacci *ever*!
      function fibonacci(n) {
        if (n == 0)
          return 0;
        if (n == 1)
          return 1;
        return fibonacci(n - 1) + fibonacci(n - 2);
      }
    }
 
    var wp = navigator.newWorkerPool();
 
    wp.messageListener = function (message, source) {
      resultdiv.innerHTML = "Result from worker: " + message;
      enddiv.innerHTML = "Finished: " + new Date();
     };
     };


     wp.errorListener = function (error, source) {
     worker.onerror = function(event) {
       alert("Worker had an error: " + error);
       dump("Worker error: " + event.data + "\n");
     };
     };


     var thread = wp.createWorker(scriptToRun.toString() + "scriptToRun();");
     worker.postMessage(10);
    thread.postMessage(35);


   </script>
   </script>
   </body>
   </body>
</html>
</html>
</pre>
</code>
</blockquote>


fibonacci.js:


<blockquote>
<code>
<pre>
var results = [];
function resultReceiver(event) {
  results.push(parseInt(event.data));
  if (results.length == 2) {
    postMessage(results[0] + results[1]);
  }
}
onmessage = function(event) {
  var n = parseInt(event.data);
  if (n == 0 || n == 1) {
    postMessage(n);
    return;
  }
  for (var i = 1; i <= 2; i++) {
    var worker = new Worker("fibonacci.js");
    worker.onmessage = resultReceiver;
    worker.postMessage(n - i);
  }
}
</pre>
</pre>
</code>
</code>
Line 69: Line 72:
== Full API ==
== Full API ==


This API has *already* changed, so it is only valid for Alpha 2.
This API shouldn't change between Beta 2 and final with the exception of adding a few properties, so code written to the following spec should continue to work.
 
=== The worker object ===
 
Workers are created as follows:


<blockquote>
<blockquote>
<code>
<code>
<pre>
<pre>
#include "nsISupports.idl"
var worker = new Worker("workerScript.js");
</pre>
</code>
</blockquote>


interface nsIDOMWorkerThread;
Once created, the worker object has the following interface:
interface nsIScriptError;


[scriptable, function, uuid(e50ca05d-1381-4abb-a021-02eb720cfc38)]
<blockquote>
interface nsIDOMWorkerMessageListener : nsISupports
<code>
<pre>
interface Worker : DOMEventTarget
{
{
   /**
   /**
   * An nsIDOMWorkerThread receives the onMessage callback when another
   * Event listener that will be called whenever a MessageEvent bubbles through
   * worker posts a message to it.
   * the worker with type 'error'. The error message will be stored in the
  *
   * 'data' member of the event.
  * @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,
   attribute EventListener onerror;
                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
   * Event listener that will be called whenever a MesageEvent bubbles through
  * workers has a parse error or an unhandled exception.
   * the worker with type 'message'. The message will be stored in the 'data'
  *
   * member of the event.
  * @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,
   attribute EventListener onmessage;
              in nsIDOMWorkerThread aSource);
};


[scriptable, uuid(6f19f3ff-2aaa-4504-9b71-dca3c191efed)]
interface nsIDOMWorkerThread : nsISupports
{
   /**
   /**
   * Sends a message to the worker.
   * Sends 'aMessage' as the 'data' member of a MessageEvent targeted at the
   *
   * worker's inner scope.
  * @param aMessage (in DOMString)
  *        The message to send.
   */
   */
   void postMessage(in DOMString aMessage);
   void postMessage(in DOMString aMessage);
};
};
</pre>
</code>
</blockquote>


[scriptable, uuid(45312e93-8a3e-4493-9bd9-272a6c23a16c)]
=== The worker scope ===
interface nsIDOMWorkerPool : nsIDOMWorkerThread
{
  /**
  * The nsIDOMWorkerMessageListener which handles messages for this pool.
  *
  * Developers should set this attribute to a proper object before another
  * worker begins sending messages to ensure that all messages are received.
  */
  attribute nsIDOMWorkerMessageListener messageListener;
 
  /**
  * 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;


  /**
The global object for the scope in which a worker's script runs has the following interface:
  * 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 aScriptText);
};


interface nsIDOMWorkerThreadContext
{
  /**
  * The worker object that created this scope.
  */
  readonly attribute nsIDOMWorkerThread thisThread;
};


interface nsIDOMWorkerGlobalScope
<blockquote>
<code>
<pre>
interface WorkerScope : DOMEventTarget
{
{
   /**
   /**
   * The thread context.
   * Gets WorkerScope object itself.
   */
   */
   readonly attribute nsIDOMWorkerThreadContext threadContext;
   readonly attribute WorkerScope self;


   /**
   /**
   * The nsIDOMWorkerMessageListener which handles messages for this worker.
   * Event listener that will be called whenever a MesageEvent bubbles through
   *  
   * the worker's inner scope with type 'message'. The message will be stored
   * Developers should set this attribute to a proper object before another
   * in the 'data' member of the event.
  * worker begins sending messages to ensure that all messages are received.
   */
   */
   attribute nsIDOMWorkerMessageListener messageListener;
   attribute EventListener onmessage;


   /**
   /**
   * Sends a message to the pool that created the worker.
   * Sends 'aMessage' as the 'data' member of a MessageEvent targeted at the
   *
   * scope's parent worker object.
  * @param aMessage (in DOMString)
  *        The message to send.
   */
   */
   void postMessageToPool(in DOMString aMessage);
   void postMessage(in DOMString aMessage);


   /**
   /**
   * See nsIDOMJSWindow.idl
   * Loads the scripts referenced by the given urls. Begins downloading all
  * scripts simultaneously but ensures that they are executed in the order
  * given.
   */
   */
   void dump(in DOMString str);
   void importScripts([Variadic] in DOMString aURLs);


   /**
   /**
   * See nsIDOMJSWindow.idl
   * The following constructors are available just as on the main thread:
   */
   *
  long setTimeout(/* in JSObject aFunctionOrString, */
  * 1. Worker(in DOMString aURL);
                  /* in JSObject aMilisecondDelay, */
  *     var worker = new Worker("scriptUrl.js");
                  /* [optional] in aArgsToFunctionOrString */);
  *
 
   * 2. XMLHttpRequest();
  /**
   *     var xhr = new XMLHttpRequest();
   * See nsIDOMJSWindow.idl
  *
   */
  *   Note: The XHR objects created in a worker script behave identically to
  long setInterval(/* in JSObject aFunctionOrString, */
  *         the XHR objects created on the main thread except that the
                  /* in JSObject aMilisecondDelay, */
  *         'responseXML' and 'channel' attributes always return null (see
                  /* [optional] in aArgsToFunctionOrString */);
   *         nsIXMLHttpRequest.idl).
 
  /**
   * See nsIDOMJSWindow.idl
   */
   */
  void clearTimeout(/* in JSObject aTimeoutId */);


   /**
   /**
   * See nsIDOMJSWindow.idl
   * See nsIDOMJSWindow.idl for info on the following methods.
   */
   */
   void clearInterval(/* in JSObject aIntervalId */);
  void dump(in DOMString aMessage);
  long setTimeout();
  long setInterval();
  void clearTimeout();
   void clearInterval();
};
};
</pre>
</pre>
</code>
</code>
</blockquote>
</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. See <code>nsIDOMWorkerGlobalScope</code> above for details.
Bent.mozilla
Confirmed users
137

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/115625"