HTML5

9 Web workers

9.1 Introduction

9.1.1 Scope

This section is non-normative.

This specification defines an API for running scripts in the background independently of any user interface scripts.

This allows for long-running scripts that are not interrupted by scripts that respond to clicks or other user interactions, and allows long tasks to be executed without yielding to keep the page responsive.

Workers (as these background scripts are called herein) are relatively heavy-weight, and are not intended to be used in large numbers. For example, it would be inappropriate to launch one worker for each pixel of a four megapixel image. The examples below show some appropriate uses of workers.

Generally, workers are expected to be long-lived, have a high start-up performance cost, and a high per-instance memory cost.

9.1.2 Examples

This section is non-normative.

There are a variety of uses that workers can be put to. The following subsections show various examples of this use.

9.1.2.1 A background number-crunching worker

This section is non-normative.

The simplest use of workers is for performing a computationally expensive task without interrupting the user interface.

In this example, the main document spawns a worker to (naïvely) compute prime numbers, and progressively displays the most recently found prime number.

The main page is as follows:

EXAMPLE workers/primes/page.html

The Worker() constructor call creates a worker and returns a Worker object representing that worker, which is used to communicate with the worker. That object's onmessage event handler allows the code to receive messages from the worker.

The worker itself is as follows:

EXAMPLE workers/primes/worker.js

The bulk of this code is simply an unoptimized search for a prime number. The postMessage() method is used to send a message back to the page when a prime is found.

View this example online.

9.1.2.2 Worker used for background I/O

This section is non-normative.

In this example, the main document uses two workers, one for fetching stock updates for at regular intervals, and one for fetching performing search queries that the user requests.

The main page is as follows:

EXAMPLE workers/stocks/page.html

The two workers use a common library for performing the actual network calls. This library is as follows:

EXAMPLE workers/stocks/io.js

The stock updater worker is as follows:

EXAMPLE workers/stocks/ticker.js

The search query worker is as follows:

EXAMPLE workers/stocks/searcher.js

View this example online.

9.1.2.3 Shared workers introduction

This section is non-normative.

This section introduces shared workers using a Hello World example. Shared workers use slightly different APIs, since each worker can have multiple connections.

This first example shows how you connect to a worker and how a worker can send a message back to the page when it connects to it. Received messages are displayed in a log.

Here is the HTML page:

EXAMPLE workers/shared/001/test.html

Here is the JavaScript worker:

EXAMPLE workers/shared/001/test.js

View this example online.

This second example extends the first one by changing two things: first, messages are received using addEventListener() instead of an event handler IDL attribute, and second, a message is sent to the worker, causing the worker to send another message in return. Received messages are again displayed in a log.

Here is the HTML page:

EXAMPLE workers/shared/002/test.html

Here is the JavaScript worker:

EXAMPLE workers/shared/002/test.js

View this example online.

Finally, the example is extended to show how two pages can connect to the same worker; in this case, the second page is merely in an iframe on the first page, but the same principle would apply to an entirely separate page in a separate top-level browsing context.

Here is the outer HTML page:

EXAMPLE workers/shared/003/test.html

Here is the inner HTML page:

EXAMPLE workers/shared/003/inner.html

Here is the JavaScript worker:

EXAMPLE workers/shared/003/test.js

View this example online.

9.1.2.4 Shared state using a shared worker

This section is non-normative.

In this example, multiple windows (viewers) can be opened that are all viewing the same map. All the windows share the same map information, with a single worker coordinating all the viewers. Each viewer can move around independently, but if they set any data on the map, all the viewers are updated.

The main page isn't interesting, it merely provides a way to open the viewers:

EXAMPLE workers/multiviewer/page.html

The viewer is more involved:

EXAMPLE workers/multiviewer/viewer.html

There are several key things worth noting about the way the viewer is written.

Multiple listeners. Instead of a single message processing function, the code here attaches multiple event listeners, each one performing a quick check to see if it is relevant for the message. In this example it doesn't make much difference, but if multiple authors wanted to collaborate using a single port to communicate with a worker, it would allow for independent code instead of changes having to all be made to a single event handling function.

Registering event listeners in this way also allows you to unregister specific listeners when you are done with them, as is done with the configure() method in this example.

Finally, the worker:

EXAMPLE workers/multiviewer/worker.js

Connecting to multiple pages. The script uses the onconnect event listener to listen for multiple connections.

Direct channels. When the worker receives a "msg" message from one viewer naming another viewer, it sets up a direct connection between the two, so that the two viewers can communicate directly without the worker having to proxy all the messages.

View this example online.

9.1.2.5 Delegation

This section is non-normative.

With multicore CPUs becoming prevalent, one way to obtain better performance is to split computationally expensive tasks amongst multiple workers. In this example, a computationally expensive task that is to be performed for every number from 1 to 10,000,000 is farmed out to ten subworkers.

The main page is as follows, it just reports the result:

EXAMPLE workers/multicore/page.html

The worker itself is as follows:

EXAMPLE workers/multicore/worker.js

It consists of a loop to start the subworkers, and then a handler that waits for all the subworkers to respond.

The subworkers are implemented as follows:

EXAMPLE workers/multicore/core.js

They receive two numbers in two events, perform the computation for the range of numbers thus specified, and then report the result back to the parent.

View this example online.

9.1.3 Tutorials

9.1.3.1 Creating a dedicated worker

This section is non-normative.

Creating a worker requires a URL to a JavaScript file. The Worker() constructor is invoked with the URL to that file as its only argument; a worker is then created and returned:

var worker = new Worker('helper.js');

9.1.3.2 Communicating with a dedicated worker

This section is non-normative.

Dedicated workers use MessagePort objects behind the scenes, and thus support all the same features, such as sending structured data, transferring binary data, and transferring other ports.

To receive messages from a dedicated worker, use the onmessage event handler IDL attribute on the Worker object:

worker.onmessage = function (event) { ... };

You can also use the addEventListener() method.

The implicit MessagePort used by dedicated workers has its port message queue implicitly enabled when it is created, so there is no equivalent to the MessagePort interface's start() method on the Worker interface.

To send data to a worker, use the postMessage() method. Structured data can be sent over this communication channel. To send ArrayBuffer objects efficiently (by transferring them rather than cloning them), list them in an array in the second argument.

worker.postMessage({
  operation: 'find-edges',
  input: buffer, // an ArrayBuffer object
  threshold: 0.6,
}, [buffer]);

To receive a message inside the worker, the onmessage event handler IDL attribute is used.

onmessage = function (event) { ... };

You can again also use the addEventListener() method.

In either case, the data is provided in the event object's data attribute.

To send messages back, you again use postMessage(). It supports the structured data in the same manner.

postMessage(event.data.input, [event.data.input]); // transfer the buffer back

9.1.3.3 Shared workers

This section is non-normative.

Shared workers are identified in one of two ways: either by the URL of the script used to create it, or by explicit name. When created by name, the URL used by the first page to create the worker with that name is the URL of the script that will be used for that worker. This allows multiple applications on a domain to all use a single shared worker to provide a common service, without the applications having to keep track of a common URL for the script used to provide the service.

In either case, shared workers are scoped by origin. Two different sites using the same names will not collide.

Creating shared workers is done using the SharedWorker() constructor. This constructor takes the URL to the script to use for its first argument, and the name of the worker, if any, as the second argument.

var worker = new SharedWorker('service.js');

Communicating with shared workers is done with explicit MessagePort objects. The object returned by the SharedWorker() constructor holds a reference to the port on its port attribute.

worker.port.onmessage = function (event) { ... };
worker.port.postMessage('some message');
worker.port.postMessage({ foo: 'structured', bar: ['data', 'also', 'possible']});

Inside the shared worker, new clients of the worker are announced using the connect event. The port for the new client is given by the event object's source attribute.

onconnect = function (event) {
  var newPort = event.source;
  // set up a listener
  newPort.onmessage = function (event) { ... };
  // send a message back to the port
  newPort.postMessage('ready!'); // can also send structured data, of course
};

9.2 Infrastructure

There are two kinds of workers; dedicated workers, and shared workers. Dedicated workers, once created, and are linked to their creator; but message ports can be used to communicate from a dedicated worker to multiple other browsing contexts or workers. Shared workers, on the other hand, are named, and once created any script running in the same origin can obtain a reference to that worker and communicate with it.

9.2.1 The global scope

The global scope is the "inside" of a worker.

9.2.1.1 The WorkerGlobalScope common interface

interface WorkerGlobalScope : EventTarget {
  readonly attribute WorkerGlobalScope self;
  readonly attribute WorkerLocation location;

  void close();
           attribute EventHandler onerror;
           attribute EventHandler onoffline;
           attribute EventHandler ononline;
};
WorkerGlobalScope implements WorkerUtils;

The self attribute must return the WorkerGlobalScope object itself.

The location attribute must return the WorkerLocation object created for the WorkerGlobalScope object when the worker was created. It represents the absolute URL of the script that was used to initialize the worker, after any redirects.

When a script invokes the close() method on a WorkerGlobalScope object, the user agent must run the following steps (atomically):

1. Discard any tasks that have been added to the event loop's task queues.

2. Set the worker's WorkerGlobalScope object's closing flag to true. (This prevents any further tasks from being queued.)

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the WorkerGlobalScope interface:

Each WorkerGlobalScope object has a worker origin that is set when the object is created.

For data: URLs, this is the origin of the entry script that called the constructor. For other URLs, this is the origin of the value of the absolute URL given in the worker's attribute.

9.2.1.2 Dedicated workers and the DedicatedWorkerGlobalScope interface

interface DedicatedWorkerGlobalScope : WorkerGlobalScope {
  void postMessage(any message, optional sequence<Transferable> transfer);
           attribute EventHandler onmessage;
};

The DedicatedWorkerGlobalScope interface must only be exposed if the JavaScript global environment is a dedicated worker environment.

DedicatedWorkerGlobalScope objects act as if they had an implicit MessagePort associated with them. This port is part of a channel that is set up when the worker is created, but it is not exposed. This object must never be garbage collected before the DedicatedWorkerGlobalScope object.

All messages received by that port must immediately be retargeted at the DedicatedWorkerGlobalScope object.

The postMessage() method on DedicatedWorkerGlobalScope objects must act as if, when invoked, it immediately invoked the method of the same name on the port, with the same arguments, and returned the same return value.

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the DedicatedWorkerGlobalScope interface:

For the purposes of the application cache networking model, a dedicated worker is an extension of the cache host from which it was created.

9.2.1.3 Shared workers and the SharedWorkerGlobalScope interface

interface SharedWorkerGlobalScope : WorkerGlobalScope {
  readonly attribute DOMString name;
  readonly attribute ApplicationCache applicationCache;
           attribute EventHandler onconnect;
};

The SharedWorkerGlobalScope interface must only be exposed if the JavaScript global environment is a shared worker environment.

Shared workers receive message ports through connect events on their global object for each connection.

The name attribute must return the value it was assigned when the SharedWorkerGlobalScope object was created by the "run a worker" algorithm. Its value represents the name that can be used to obtain a reference to the worker using the SharedWorker constructor.

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the SharedWorkerGlobalScope interface:

For the purposes of the application cache networking model, a shared worker is its own cache host. The run a worker algorithm takes care of associating the worker with an application cache.

The applicationCache attribute returns the ApplicationCache object for the worker.

9.2.2 The event loop

Each WorkerGlobalScope object has an event loop distinct from those defined for units of related similar-origin browsing contexts. This event loop has no associated browsing context, and its task queues only have events, callbacks, and networking activity as tasks. The processing model of these event loops is defined below in the run a worker algorithm.

Each WorkerGlobalScope object also has a closing flag, which must initially be false, but which can get set to true by the algorithms in the processing model section below.

Once the WorkerGlobalScope's closing flag is set to true, the event loop's task queues must discard any further tasks that would be added to them (tasks already on the queue are unaffected except where otherwise specified). Effectively, once the closing flag is true, timers stop firing, notifications for all pending asynchronous operations are dropped, etc.

9.2.3 The worker's lifetime

Workers communicate with other workers and with browsing contexts through message channels and their MessagePort objects.

Each WorkerGlobalScope worker global scope has a list of the worker's ports, which consists of all the MessagePort objects that are entangled with another port and that have one (but only one) port owned by worker global scope. This list includes the implicit MessagePort in the case of dedicated workers.

Each WorkerGlobalScope also has a list of the worker's workers. Initially this list is empty; it is populated when the worker creates or obtains further workers.

Finally, each WorkerGlobalScope also has a list of the worker's Documents. Initially this list is empty; it is populated when the worker is created.

Whenever a Document d is added to the worker's Documents, the user agent must, for each worker q in the list of the worker's workers whose list of the worker's Documents does not contain d, add d to q's WorkerGlobalScope owner's list of the worker's Documents.

Whenever a Document object is discarded, it must be removed from the list of the worker's Documents of each worker whose list contains that Document.

Given a script's global object o when creating or obtaining a worker, the list of relevant Document objects to add depends on the type of o. If o is a WorkerGlobalScope object (i.e. if we are creating a nested worker), then the relevant Documents are the Documents that are in o's own list of the worker's Documents. Otherwise, o is a Window object, and the relevant Document is just the Document that is the active document of the Window object o.

A worker is said to be a permissible worker if its list of the worker's Documents is not empty.

A worker is said to be a protected worker if it is a permissible worker and either it has outstanding timers, database transactions, or network connections, or its list of the worker's ports is not empty, or its WorkerGlobalScope is actually a SharedWorkerGlobalScope object (i.e. the worker is a shared worker).

A worker is said to be an active needed worker if any of the Document objects in the worker's Documents are fully active.

A worker is said to be a suspendable worker if it is not an active needed worker but it is a permissible worker.

9.2.4 Processing model

When a user agent is to run a worker for a script with URL url, a browsing context owner browsing context, a Document owner document, an origin owner origin, and with global scope worker global scope, it must run the following steps:

1. Create a separate parallel execution environment (i.e. a separate thread or process or equivalent construct), and run the rest of these steps asynchronously in that context.

2. If worker global scope is actually a SharedWorkerGlobalScope object (i.e. the worker is a shared worker), and there are any relevant application caches that are identified by a manifest URL with the same origin as url and that have url as one of their entries, not excluding entries marked as foreign, then associate the worker global scope with the most appropriate application cache of those that match.

3. Attempt to fetch the resource identified by url, from the owner origin, with the synchronous flag set and the force same-origin flag set.

   If the attempt fails, then for each Worker or SharedWorker object associated with worker global scope, queue a task to fire a simple event named error at that object. Abort these steps.

   If the attempt succeeds, then let source be the script resource decoded as UTF-8, with error handling.

   Let language be JavaScript.

   As with script elements, the MIME type of the script is ignored. Unlike with script elements, there is no way to override the type. It's always assumed to be JavaScript.

4. In the newly created execution environment, create a JavaScript global environment whose global object is worker global scope. If worker global scope is a DedicatedWorkerGlobalScope object, then this is a dedicated worker environment. Otherwise, worker global scope is a SharedWorkerGlobalScope object, and this is a shared worker environment. (In either case, by definition, it is a worker environment.)

5. A new script is now created, as follows.

   Create a new script execution environment set up as appropriate for the scripting language language.

   Parse/compile/initialize source using that script execution environment, as appropriate for language, and thus obtain a list of code entry-points; set the initial code entry-point to the entry-point for any executable code to be immediately run.

   Set the script's global object to worker global scope.

   Set the script's browsing context to owner browsing context.

   Set the script's document to owner document.

   Set the script's URL character encoding to UTF-8. (This is just used for encoding non-ASCII characters in the query component of URLs.)

   Set the script's base URL to url.

6. Closing orphan workers: Start monitoring the worker such that no sooner than it stops being either a protected worker or a suspendable worker, and no later than it stops being a permissible worker, worker global scope's closing flag is set to true.

7. Suspending workers: Start monitoring the worker, such that whenever worker global scope's closing flag is false and the worker is a suspendable worker, the user agent suspends execution of script in that worker until such time as either the closing flag switches to true or the worker stops being a suspendable worker.

8. Jump to the script's initial code entry-point, and let that run until it either returns, fails to catch an exception, or gets prematurely aborted by the "kill a worker" or "terminate a worker" algorithms defined below.

9. If worker global scope is actually a DedicatedWorkerGlobalScope object (i.e. the worker is a dedicated worker), then enable the port message queue of the worker's implicit port.

10. Event loop: Wait until either there is a task in one of the event loop's task queues or worker global scope's closing flag is set to true.

11. Run the oldest task on one of the event loop's task queues, if any. The user agent may pick any task queue.

    The handling of events or the execution of callbacks might get prematurely aborted by the "kill a worker" or "terminate a worker" algorithms defined below.

12. If the storage mutex is now owned by the worker's event loop, release it so that it is once again free.

13. Remove the task just run in the earlier step, if any, from its task queue.

14. If there are any more events in the event loop's task queues or if worker global scope's closing flag is set to false, then jump back to the step above labeled event loop.

15. Empty the worker global scope's list of active timers.

16. Disentangle all the ports in the list of the worker's ports.

When a user agent is to kill a worker it must run the following steps in parallel with the worker's main loop (the "run a worker" processing model defined above):

1. Set the worker's WorkerGlobalScope object's closing flag to true.

2. If there are any tasks queued in the event loop's task queues, discard them without processing them.

3. Wait a user-agent-defined amount of time.

4. Abort the script currently running in the worker.

User agents may invoke the "kill a worker" processing model on a worker at any time, e.g. in response to user requests, in response to CPU quota management, or when a worker stops being an active needed worker if the worker continues executing even after its closing flag was set to true.

When a user agent is to terminate a worker it must run the following steps in parallel with the worker's main loop (the "run a worker" processing model defined above):

1. Set the worker's WorkerGlobalScope object's closing flag to true.

2. If there are any tasks queued in the event loop's task queues, discard them without processing them.

3. Abort the script currently running in the worker.

4. If the worker's WorkerGlobalScope object is actually a DedicatedWorkerGlobalScope object (i.e. the worker is a dedicated worker), then empty the port message queue of the port that the worker's implicit port is entangled with.

The task source for the tasks mentioned above is the DOM manipulation task source.

9.2.5 Runtime script errors

Whenever an uncaught runtime script error occurs in one of the worker's scripts, if the error did not occur while handling a previous script error, the user agent must report the error at the URL of the resource that contained the script, with the position (line number and column number) where the error occurred, in the origin of the scripts running in the worker, using the WorkerGlobalScope object's onerror attribute.

For shared workers, if the error is still not handled afterwards, or if the error occurred while handling a previous script error, the error may be reported to the user.

For dedicated workers, if the error is still not handled afterwards, or if the error occurred while handling a previous script error, the user agent must queue a task to fire an event that uses the ErrorEvent interface, with the name error, that doesn't bubble and is cancelable, with its message, filename, and lineno attributes initialized appropriately, at the Worker object associated with the worker. If the event is not canceled, the user agent must act as if the uncaught runtime script error had occurred in the global scope that the Worker object is in, thus repeating the entire runtime script error reporting process one level up.

If the implicit port connecting the worker to its Worker object has been disentangled (i.e. if the parent worker has been terminated), then the user agent must act as if the Worker object had no error event handler and as if that worker's onerror attribute was null, but must otherwise act as described above.

Thus, error reports propagate up to the chain of dedicated workers up to the original Document, even if some of the workers along this chain have been terminated and garbage collected.

The task source for the task mentioned above is the DOM manipulation task source.

[Constructor(DOMString type, optional ErrorEventInit eventInitDict)]
interface ErrorEvent : Event {
  readonly attribute DOMString message;
  readonly attribute DOMString filename;
  readonly attribute unsigned long lineno;
};

dictionary ErrorEventInit : EventInit {
  DOMString message;
  DOMString filename;
  unsigned long lineno;
};

The message attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to the empty string. It represents the error message.

The filename attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to the empty string. It represents the absolute URL of the script in which the error originally occurred.

The lineno attribute must return the value it was initialized to. When the object is created, this attribute must be initialized to zero. It represents the line number where the error occurred in the script.

9.2.6 Creating workers

9.2.6.1 The AbstractWorker abstract interface

[NoInterfaceObject]
interface AbstractWorker {
           attribute EventHandler onerror;

};

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the AbstractWorker interface:

9.2.6.2 Dedicated workers and the Worker interface

[Constructor(DOMString scriptURL)]
interface Worker : EventTarget {
  void terminate();

  void postMessage(any message, optional sequence<Transferable> transfer);
           attribute EventHandler onmessage;
};
Worker implements AbstractWorker;

The terminate() method, when invoked, must cause the "terminate a worker" algorithm to be run on the worker with with the object is associated.

Worker objects act as if they had an implicit MessagePort associated with them. This port is part of a channel that is set up when the worker is created, but it is not exposed. This object must never be garbage collected before the Worker object.

All messages received by that port must immediately be retargeted at the Worker object.

The postMessage() method on Worker objects must act as if, when invoked, it immediately invoked the method of the same name on the port, with the same arguments, and returned the same return value.

worker.postMessage({opcode: 'activate', device: 1938, parameters: [23, 102]});

The following are the event handlers (and their corresponding event handler event types) that must be supported, as IDL attributes, by objects implementing the Worker interface:

When the Worker(scriptURL) constructor is invoked, the user agent must run the following steps:

1. Resolve the scriptURL argument relative to the entry script's base URL, when the method is invoked.

2. If this fails, throw a SyntaxError exception.

3. If the <scheme> component of the resulting absolute URL is not "data", and the origin of the resulting absolute URL is not the same as the origin of the entry script, then throw a SecurityError exception and abort these steps.

   Thus, scripts must either be external files with the same scheme, host, and port as the original page, or data: URLs. For example, you can't load a script from a javascript: URL, and an https: page couldn't start workers using scripts with http: URLs.

4. Create a new DedicatedWorkerGlobalScope object whose worker origin is the origin of the entry script. Let worker global scope be this new object.

5. Create a new Worker object, associated with worker global scope. Let worker be this new object.

6. Create a new MessagePort object owned by the global object of the script that invoked the constructor. Let this be the outside port.

7. Associate the outside port with worker.

8. Create a new MessagePort object owned by worker global scope. Let inside port be this new object.

9. Associate inside port with worker global scope.

10. Entangle outside port and inside port.

11. Return worker, and run the following steps asynchronously.

12. Enable outside port's port message queue.

13. Let docs be the list of relevant Document objects to add given the global object of the script that invoked the constructor.

14. Add to worker global scope's list of the worker's Documents the Document objects in docs.

15. If the global object of the script that invoked the constructor is a WorkerGlobalScope object (i.e. we are creating a nested worker), add worker global scope to the list of the worker's workers of the WorkerGlobalScope object that is the global object of the script that invoked the constructor.

16. Run a worker for the resulting absolute URL, with the script's browsing context of the script that invoked the method as the owner browsing context, with the script's document of the script that invoked the method as the owner document, with the origin of the entry script as the owner origin, and with worker global scope as the global scope.

This constructor must be visible when the script's global object is either a Window object or an object implementing the WorkerUtils interface.

9.2.6.3 Shared workers and the SharedWorker interface

[Constructor(DOMString scriptURL, optional DOMString name)]
interface SharedWorker : EventTarget {
  readonly attribute MessagePort port;
};
SharedWorker implements AbstractWorker;

The port attribute must return the value it was assigned by the object's constructor. It represents the MessagePort for communicating with the shared worker.

When the SharedWorker(scriptURL, name) constructor is invoked, the user agent must run the following steps:

1. Resolve the scriptURL argument.

2. If this fails, throw a SyntaxError exception.

3. Otherwise, let scriptURL be the resulting absolute URL.

4. Let name be the value of the second argument, or the empty string if the second argument was omitted.

5. If the <scheme> component of scriptURL is not "data", and the origin of scriptURL is not the same as the origin of the entry script, then throw a SecurityError exception and abort these steps.

   Thus, scripts must either be external files with the same scheme, host, and port as the original page, or data: URLs. For example, you can't load a script from a javascript: URL, and an https: page couldn't start workers using scripts with http: URLs.

6. Let docs be the list of relevant Document objects to add given the global object of the script that invoked the constructor.

7. Execute the following substeps atomically:

   1. Create a new SharedWorker object, which will shortly be associated with a SharedWorkerGlobalScope object. Let this SharedWorker object be worker.

   2. Create a new MessagePort object owned by the global object of the script that invoked the method. Let this be the outside port.

   3. Assign outside port to the port attribute of worker.

   4. Let worker global scope be null.

   5. If name is not the empty string and there exists a SharedWorkerGlobalScope object whose closing flag is false, whose name attribute is exactly equal to name, and whose worker origin is the same origin as scriptURL, then let worker global scope be that SharedWorkerGlobalScope object.

      Otherwise, if name is the empty string and there exists a SharedWorkerGlobalScope object whose closing flag is false, whose name attribute is the empty string, and whose location attribute represents an absolute URL that is exactly equal to scriptURL, then let worker global scope be that SharedWorkerGlobalScope object.

   6. If worker global scope is not null, but the user agent has been configured to disallow communication between the script that invoked the constructor and the worker represented by the worker global scope, then set worker global scope to null.

      For example, a user agent could have a development mode that isolates a particular top-level browsing context from all other pages, and scripts in that development mode could be blocked from connecting to shared workers running in the normal browser mode.

   7. If worker global scope is not null, then run these steps:

      1. If worker global scope's location attribute represents an absolute URL that is not exactly equal to scriptURL, then throw a URLMismatchError exception and abort all these steps.

      2. Associate worker with worker global scope.

      3. Create a new MessagePort object owned by worker global scope. Let this be the inside port.

      4. Entangle outside port and inside port.

      5. Return worker and perform the next step asynchronously.

      6. Create an event that uses the MessageEvent interface, with the name connect, which does not bubble, is not cancelable, has no default action, has a data attribute whose value is initialized to the empty string, has a ports attribute whose value is initialized to a read only array containing only the newly created port, and has a source attribute whose value is initialized to the newly created port, and queue a task to dispatch the event at worker global scope.

      7. Add to worker global scope's list of the worker's Documents the Document objects in docs.

      8. If the global object of the script that invoked the constructor is a WorkerGlobalScope object, add worker global scope to the list of the worker's workers of the WorkerGlobalScope object that is the global object of the script that invoked the constructor.

      9. Abort all these steps.

   8. Create a new SharedWorkerGlobalScope object whose worker origin is the origin of the entry script. Let worker global scope be this new object.

   9. Associate worker with worker global scope.

   10. Set the name attribute of worker global scope to name.

   11. Create a new MessagePort object owned by worker global scope. Let inside port be this new object.

   12. Entangle outside port and inside port.

8. Return worker and perform the remaining steps asynchronously.

9. Create an event that uses the MessageEvent interface, with the name connect, which does not bubble, is not cancelable, has no default action, has a data attribute whose value is initialized to the empty string, has a ports attribute whose value is initialized to a read only array containing only the newly created port, and has a source attribute whose value is initialized to the newly created port, and queue a task to dispatch the event at worker global scope.

10. Add to worker global scope's list of the worker's Documents the Document objects in docs.

11. If the global object of the script that invoked the constructor is a WorkerGlobalScope object, add worker global scope to the list of the worker's workers of the WorkerGlobalScope object that is the global object of the script that invoked the constructor.

12. Run a worker for scriptURL, with the script's browsing context of the script that invoked the method as the owner browsing context, with the script's document of the script that invoked the method as the owner document, with the origin of the entry script as the owner origin, and with worker global scope as the global scope.

This constructor must be visible when the script's global object is either a Window object or an object implementing the WorkerUtils interface.

The task source for the tasks mentioned above is the DOM manipulation task source.

9.3 APIs available to workers

[NoInterfaceObject]
interface WorkerUtils {
  void importScripts(DOMString... urls);
  readonly attribute WorkerNavigator navigator;
};
WorkerUtils implements WindowTimers;
WorkerUtils implements WindowBase64;

The DOM APIs (Node objects, Document objects, etc) are not available to workers in this version of this specification.

9.3.1 Importing scripts and libraries

When a script invokes the importScripts(urls) method on a WorkerGlobalScope object, the user agent must run the following steps:

1. If there are no arguments, return without doing anything. Abort these steps.

2. Resolve each argument.

3. If any fail, throw a SyntaxError exception.

4. Attempt to fetch each resource identified by the resulting absolute URLs, from the entry script's origin, with the synchronous flag set.

5. For each argument in turn, in the order given, starting with the first one, run these substeps:

   1. Wait for the fetching attempt for the corresponding resource to complete.

      If the fetching attempt failed, throw a NetworkError exception and abort all these steps.

      If the attempt succeeds, then let source be the script resource decoded as UTF-8, with error handling.

      Let language be JavaScript.

      As with the worker's script, the script here is always assumed to be JavaScript, regardless of the MIME type.

   2. Create a script, using source as the script source, the URL from which source was obtained, and language as the scripting language, using the same global object, browsing context, URL character encoding, base URL, and script group as the script that was created by the worker's run a worker algorithm.

      Let the newly created script run until it either returns, fails to parse, fails to catch an exception, or gets prematurely aborted by the "kill a worker" or "terminate a worker" algorithms defined above.

      If it failed to parse, then throw an ECMAScript SyntaxError exception and abort all these steps. [ECMA262]

      If an exception was thrown or if the script was prematurely aborted, then abort all these steps, letting the exception or aborting continue to be processed by the script that called the importScripts() method.

      If the "kill a worker" or "terminate a worker" algorithms abort the script then abort all these steps.

9.3.2 The WorkerNavigator object

The navigator attribute of the WorkerUtils interface must return an instance of the WorkerNavigator interface, which represents the identity and state of the user agent (the client):

interface WorkerNavigator {};
WorkerNavigator implements NavigatorID;
WorkerNavigator implements NavigatorOnLine;

Objects implementing the WorkerNavigator interface also implement the NavigatorID and NavigatorOnLine interfaces.

The WorkerNavigator interface must only be exposed if the JavaScript global environment is a worker environment.

9.3.3 Interface objects and constructors

Nothing must be exposed when the JavaScript global environment is a worker environment except for the following:

• XMLHttpRequest and all interface objects and constructors defined by the XMLHttpRequest specifications, except that the document response entity body must always be null. The XMLHttpRequest base URL is the script's base URL; the XMLHttpRequest origin is the script's origin. [XHR]

• The interface objects and constructors defined by this specification, except where is further restricted by explicit requirements in this specification.

• The interface objects of any objects made accessible through interfaces implemented by any objects that are themselves exposed (i.e. this requirement is transitive).

These requirements do not override the requirements defined by the Web IDL specification, in particular concerning the visibility of interfaces annotated with the [NoInterfaceObject] extended attribute.

9.3.4 Worker locations

interface WorkerLocation {
  // URL decomposition IDL attributes
  stringifier readonly attribute DOMString href;
  readonly attribute DOMString protocol;
  readonly attribute DOMString host;
  readonly attribute DOMString hostname;
  readonly attribute DOMString port;
  readonly attribute DOMString pathname;
  readonly attribute DOMString search;
  readonly attribute DOMString hash;
};

A WorkerLocation object represents an absolute URL set at its creation.

The href attribute must return the absolute URL that the object represents.

The WorkerLocation interface also has the complement of URL decomposition IDL attributes, protocol, host, port, hostname, pathname, search, and hash. These must follow the rules given for URL decomposition IDL attributes, with the input being the absolute URL that the object represents (same as the href attribute), and the common setter action being a no-op, since the attributes are defined to be readonly.

The WorkerLocation interface must only be exposed if the JavaScript global environment is a worker environment.