flash.system

# WorkerDomain - AS3

Package | flash.system
Class | public final class WorkerDomain
Inheritance | WorkerDomain Object

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, AIR 3.4

The WorkerDomain class provides a way to create Worker objects and access them. A WorkerDomain represents the runtime's mechanism for managing the set of workers within a security domain.

Note: The use of workers for concurrency is supported in both Flash Player and AIR on desktop platforms. For mobile platforms, concurrency is supported in AIR on Android but not in AIR on iOS. You can use the static isSupported property to check whether concurrency is supported before attempting to use it.

You do not create WorkerDomain instances directly by calling the `WorkerDomain()` constructor. There is one single WorkerDomain instance for an application. In contexts where the use of workers for concurrency is supported, the runtime automatically creates the WorkerDomain at startup. You access that instance using the static `current` property.

To create a new instance of the Worker class, use the `createWorker()` method. To access the set of Worker objects that are currently running, use the `listWorkers()` method.

Related API Elements

flash.system.Worker

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | current : WorkerDomain [static] [read-only] The WorkerDomain instance in which the code is currently running. | WorkerDomain
|  | isSupported : Boolean [static] [read-only] Indicates whether the current runtime context supports the WorkerDomain and Worker objects for concurrent code execution. | WorkerDomain

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | createWorker(swf:ByteArray, giveAppPrivileges:Boolean = false):Worker Creates a new Worker instance from the bytes of a swf. | WorkerDomain
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | listWorkers():Vector.<Worker> Provides access to the set of workers in the WorkerDomain that are currently running (the Worker instance's state property is WorkerState.RUNNING). | WorkerDomain
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### current

property

`current:WorkerDomain` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, AIR 3.4

The WorkerDomain instance in which the code is currently running. This is the only WorkerDomain in the application.

Implementation
`public static function get current():WorkerDomain`

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, AIR 3.4

Indicates whether the current runtime context supports the WorkerDomain and Worker objects for concurrent code execution.

If concurrency is available, this property's value is `true`.

Implementation
`public static function get isSupported():Boolean`
Method Detail

### createWorker

()
method

`public function createWorker(swf:ByteArray, giveAppPrivileges:Boolean = false):Worker`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, AIR 3.4

Creates a new `Worker` instance from the bytes of a swf.

Each worker is created from and executes as an isolated swf application. To create a Worker instance, you obtain the bytes of the SWF file as a ByteArray instance and pass it to this method. There are three common ways to access the bytes of a swf for this purpose:

- Use the [Embed] metatag to embed the .swf file in the application as a ByteArray:

  Copy

          // Embed the SWF file
          [Embed(source="../swfs/BgWorker.swf", mimeType="application/octet-stream")]
          private static var BgWorker_ByteClass:Class;

          private function createWorker():void
          {
            // create the background worker
            var workerBytes:ByteArray = new BgWorker_ByteClass();
            var bgWorker:Worker = WorkerDomain.current.createWorker(workerBytes);

            // listen for worker state changes to know when the worker is running
            bgWorker.addEventListener(Event.WORKER_STATE, workerStateHandler);

            // set up communication between workers using
            // setSharedProperty(), createMessageChannel(), etc.
            // ... (not shown)

            bgWorker.start();
          }

- Load an external SWF file using a URLLoader:

  Copy

          // load the SWF file
          var workerLoader:URLLoader = new URLLoader();
          workerLoader.dataFormat = URLLoaderDataFormat.BINARY;
          workerLoader.addEventListener(Event.COMPLETE, loadComplete);
          workerLoader.load(new URLRequest("BgWorker.swf"));

          private function loadComplete(event:Event):void
          {
            // create the background worker
            var workerBytes:ByteArray = event.target.data as ByteArray;
            var bgWorker:Worker = WorkerDomain.current.createWorker(workerBytes);

            // listen for worker state changes to know when the worker is running
            bgWorker.addEventListener(Event.WORKER_STATE, workerStateHandler);

            // set up communication between workers using
            // setSharedProperty(), createMessageChannel(), etc.
            // ... (not shown)

            bgWorker.start();
          }

- Use a single swf as both the primordial worker and the background worker:

  Copy

          // The primordial worker's main class constructor
          public function PrimordialWorkerClass()
          {
            init();
          }

          private function init():void
          {
            var swfBytes:ByteArray = this.loaderInfo.bytes;

            // Check to see if this is the primordial worker
            if (Worker.current.isPrimordial)
            {
              // create a background worker
              var bgWorker:Worker = WorkerDomain.current.createWorker(swfBytes);

              // listen for worker state changes to know when the worker is running
              bgWorker.addEventListener(Event.WORKER_STATE, workerStateHandler);

              // set up communication between workers using
              // setSharedProperty(), createMessageChannel(), etc.
              // ... (not shown)

              bgWorker.start();
            }
            else // entry point for the background worker
            {
              // set up communication between workers using getSharedProperty()
              // ... (not shown)

              // start the background work
            }

Creating a Worker object using `createWorker()` does not start execution of the worker. To start a worker's code execution, call the Worker object's `start()` method.

Workers are useful because they decrease the chances of the frame rate dropping due to the main rendering thread being blocked by other code. However, workers require additional system memory and CPU use, which can be costly to overall application performance. Because each worker uses its own instance of the runtime virtual machine, even the overhead of a trivial worker can be large. When using workers, test your code across all your target platforms to ensure that the demands on the system are not too large. Adobe recommends that you do not use more than one or two background workers in a typical scenario.

Parameters

| `swf:ByteArray` — A ByteArray containing the bytes of a valid swf
| `giveAppPrivileges:Boolean` (default = `false`)`` — indicates whether the worker should be given application sandbox privileges in AIR. This parameter is ignored in Flash Player

Returns

| `Worker` — the newly created Worker if creation succeeds. A return value of `null` indicates that a worker could not be created either because the current context doesn't support concurrency or because creating a new worker would exceed implementation limits.

Throws

| `SecurityError` — if the swf whose bytes are passed to the `swf` parameter is from a different security domain than the swf in which this method is called

### listWorkers

()
method

`public function listWorkers():Vector.<Worker>`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.4, AIR 3.4

Provides access to the set of workers in the WorkerDomain that are currently running (the Worker instance's `state` property is `WorkerState.RUNNING`).

Returns

| `Vector.<Worker>` — A Vector of Worker instances containing the workers that are currently running.

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00