flash.concurrent

# Condition - AS3

Package | flash.concurrent
Class | public final class Condition
Inheritance | Condition Object

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

A Condition object is a tool for sharing a resource between workers with the additional capability of pausing execution until a particular condition is satisfied. A Condition object is used in conjunction with a Mutex object, and adds additional functionality to the mutex's behavior. By working in combination with a mutex, the runtime ensures that each transition of ownership between workers is atomic.

The following is one possible workflow for using a Condition object:

1. Before using a Condition object, the first worker must take ownership of the condition's associated mutex by calling the Mutex object's `lock()` or `tryLock()` methods.
2. The worker's code operates on the shared resource until some condition becomes false, preventing the worker from doing more work with the shared resource. For example, if the shared resource is a set of data to process, when there is no more data to process the worker can't do any more work.
3. At that point, call the Condition object's `wait()` method to pause the worker's execution and release ownership of the mutex.
4. At some point, a second worker takes ownership of the mutex. Because the mutex is available, it is safe for the second worker's code to operate on the shared resource. The second worker does whatever is necessary to satisfy the condition so that the first worker can do its work again. For example, if the first worker has no data to process, the second worker could pass more data to process into the shared resource.
5. At that point, the condition related to the first worker's work is now true, so the first worker needs to be notified that the condition is fulfilled. To notify the first worker, the second worker's code calls the Condition object's `notify()` method or its `notifyAll()` method.
6. In addition to calling `notify()`, the second worker needs to release ownership of the mutex. It does this either by calling the Mutex object's `unlock()` method or the Condition object's `wait()` method. Since the first worker called the `wait()` method, ownership of the mutex returns to the first worker. Code execution in the first worker then continues again with the next line of code following the `wait()` call.

The Condition class is one of the special object types that are shared between workers rather than copied between them. When you pass a condition from one worker to another worker either by calling the Worker object's `setSharedProperty()` method or by using a MessageChannel object, both workers have a reference to the same Condition object in the runtime's memory.

Related API Elements

Mutex class
Worker class

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
|  | isSupported : Boolean [static] [read-only] Indicates whether the Condition class is supported for the current platform. | Condition
|  | mutex : Mutex [read-only] The mutex associated with this condition. | Condition

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Condition(mutex:Mutex) Creates a new Condition instance. | Condition
|  | 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
|  | notify():void Specifes that the condition that this Condition object represents has been satisfied and that ownership of the mutex will be returned to the next worker (if any) that's waiting on this condition. | Condition
|  | notifyAll():void Specifies that the condition that this Condition object represents has been satisfied and that ownership of the mutex will be returned to all workers that are waiting on this condition. | Condition
|  | 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
|  | wait(timeout:Number = -1):Boolean Specifies that the condition that this Condition object represents isn't satisfied, and the current worker needs to wait until it is satisfied before executing more code. | Condition

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Indicates whether the Condition class is supported for the current platform.

Note: if the Mutex class is not supported, creation of a Condition instance is not possible and this property is `false`.

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

### mutex

property

`mutex:Mutex` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

The mutex associated with this condition.

Implementation
`public function get mutex():Mutex`
Constructor Detail

### Condition

()
Constructor

`public function Condition(mutex:Mutex)`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Creates a new Condition instance.

Parameters

| `mutex:Mutex` — the mutex that the condition uses to control transitions between workers

Method Detail

### notify

()
method

`public function notify():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Specifes that the condition that this Condition object represents has been satisfied and that ownership of the mutex will be returned to the next worker (if any) that's waiting on this condition.

Calling this method doesn't automatically release ownership of the mutex. After calling `notify()`, you should explicitly release ownership of the mutex in one of two ways: call the `Mutex.unlock()` method if the current worker doesn't need the mutex again, or call `wait()` if the worker should get ownership of the mutex again after other workers have completed their work.

One the mutex's lock is released, the next worker in the queue of workers that have called the `wait()` method acquires the mutex and resumes code execution.

Throws

| `IllegalOperationError` — if the current worker doesn't own this condition's mutex

### notifyAll

()
method

`public function notifyAll():void`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Specifies that the condition that this Condition object represents has been satisfied and that ownership of the mutex will be returned to all workers that are waiting on this condition.

Calling this method doesn't automatically release ownership of the mutex. After calling `notify()`, you should explicitly release ownership of the mutex in one of two ways: call the `Mutex.unlock()` method if the current worker doesn't need the mutex again, or call `wait()` if the worker should get ownership of the mutex again after other workers have completed their work.

Once the mutex's lock is released, the waiting workers receive ownership one at a time in the order they called the `wait()` method. Each worker that has called the `wait()` method acquires the mutex in turn and resumes code execution. When that worker calls the `Mutex.unlock()` method or the `wait()` method, mutex ownership then switches to the next waiting worker. Each time mutex ownership switches between workers, the transition is performed as a single atomic operation.

Throws

| `IllegalOperationError` — if the current worker doesn't own this condition's mutex

### wait

()
method

`public function wait(timeout:Number = -1):Boolean`

Language Version: | ActionScript 3.0

Runtime Versions: | Flash Player 11.5, AIR 3.5

Specifies that the condition that this Condition object represents isn't satisfied, and the current worker needs to wait until it is satisfied before executing more code. Calling this method pauses the current worker's execution thread and releases ownership of the condition's mutex. These steps are performed as a single atomic operation. The worker remains paused until another worker calls this Condition object's `notify()` or `notifyAll()` methods.

Parameters

| `timeout:Number` (default = `-1`)`` — the maximum amount of time, in milliseconds, that the worker should pause execution before continuing. If this value is -1 (the default) there is no no timeout and execution pauses indefinitely.

Returns

| `Boolean` — `true` if the method returned because the timeout time elapsed. Otherwise the method returns `false`.

Throws

| `IllegalOperationError` — if the current worker doesn't own this condition's mutex
| `ArgumentError` — if the `timeout` argument is less than 0 and not -1
| `ScriptTimeoutError` — if the method is called from code in the primordial worker in Flash Player and worker pauses longer than the script timeout limit (15 seconds by default)
| `Error` — if the method is called and, while the calling worker's execution is paused, the waiting worker is terminated.

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