Packageflash.concurrent
Classpublic final class Mutex
InheritanceMutex Inheritance Object

Language version: ActionScript 3.0
Runtime version: AIR 3.5

The Mutex (short for "mutual exclusion") class provides a way to make sure that only one set of code operates on a particular block of memory or other shared resource at a time. The primary use for a Mutex is to manage code in different workers accessing a shareable byte array (a ByteArray object whose shareable property is true). However, a Mutex can be used to manage workers' access to any shareable resource, such as an AIR native extension or a filesystem file. No matter what the resource, the purpose of the mutex is to ensure that only one set of code accesses the resource at a time.

A mutex manages access using the concept of resource ownership. At any time a single mutex is "owned" by at most one worker. When ownership of a mutex switches from one worker to another the transision is atomic. This guarantees that it will never be possible for more than one worker to take ownership of the mutex. As long as code in a worker only operates on a shared resource when that worker owns the mutex, you can be certain that there will never be a conflict from multiple workers.

Use the tryLock() method to take ownership of the mutex if it is available. Use the lock() method to pause the current worker's execution until the mutex is available, then take ownership of the mutex. Once the current worker has ownership of the mutex, it can safely operate on the shared resource. When those operations are complete, call the unlock() method to release the mutex. At that point the current worker should no longer access the shared resource.

The Mutex class is one of the special object types that are shared between workers rather than copied between them. When you pass a mutex 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 Mutex object in the runtime's memory.

See also

Worker class
ByteArray.shareable property
Condition class


Public Properties
 PropertyDefined by
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  isSupported : Boolean
[static][read-only] Indicates whether the use of the Mutex class is supported for the current platform.
Mutex
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
Public Methods
 MethodDefined by
  
Creates a new Mutex instance.
Mutex
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Pauses execution of the current worker until this mutex is available and then takes ownership of the mutex.
Mutex
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
Acquires ownership of the mutex if it is available.
Mutex
  
Releases ownership of this mutex, allowing any worker to acquire it and perform work on the associated resource.
Mutex
 Inherited
Returns the primitive value of the specified object.
Object
Property detail
isSupportedproperty
isSupported:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 3.5

Indicates whether the use of the Mutex class is supported for the current platform.

This property is true if the current platform supports mutexes; otherwise false.

Implementation
    public static function get isSupported():Boolean
Constructor detail
Mutex()constructor
public function Mutex()

Language version: ActionScript 3.0
Runtime version: AIR 3.5

Creates a new Mutex instance.


Throws
Error — if the mutex could not be initialized.
Method detail
lock()method
public function lock():void

Language version: ActionScript 3.0
Runtime version: AIR 3.5

Pauses execution of the current worker until this mutex is available and then takes ownership of the mutex. If another worker owns the mutex when lock() is called, the calling worker's execution thread pauses at the lock() call and the worker is added to the queue of ownership requests. Once the calling worker acquires the mutex, the worker's execution continues with the line of code following the lock() call.

Once the current worker has ownership of the mutex, it can safely operate on the shared resource. When those operations are complete, call the unlock() method to release the mutex. At that point the current worker should no longer access the shared resource.

Internally, a mutex keeps a count of the number of lock requests it has received. The mutex must receive the same number of unlock requests before it is completely released. If code in the worker that owns the mutex locks it again (by calling the lock() method) the internal lock count increases by one. You must call the unlock() method as many times as the number of lock requests to release ownership of the mutex.

When multiple workers are waiting for a mutex, the mutex gives priority to assigning ownership to the longest-waiting worker. However, scheduling of worker threads is managed by the host operating system so there is no guarantee of a particular code execution order across workers.

tryLock()method 
public function tryLock():Boolean

Language version: ActionScript 3.0
Runtime version: AIR 3.5

Acquires ownership of the mutex if it is available. If another worker already owns the mutex or another worker has called the lock() method and is waiting to acquire the mutex, the mutex is not available. In that case, calling this method returns false and code execution continues immediately.

Once the current worker has ownership of the mutex, it can safely operate on the shared resource. When those operations are complete, call the unlock() method to release the mutex. At that point the current worker should no longer access the shared resource.

When multiple workers are waiting for a mutex, the mutex gives priority to assigning ownership to the longest-waiting worker. However, scheduling of worker threads is managed by the host operating system so there is no guarantee of a particular code execution order across workers.

Returns
Booleantrue if the mutex was available (and is now owned by the current worker), or false if the current worker did not acquire ownership of the mutex.
unlock()method 
public function unlock():void

Language version: ActionScript 3.0
Runtime version: AIR 3.5

Releases ownership of this mutex, allowing any worker to acquire it and perform work on the associated resource.

Internally, a mutex keeps a count of the number of lock requests it has received. Code in a worker must call the unlock() method as many times as the number of lock requests in order to release ownership of the mutex.


Throws
Error — when the current worker doesn't own the mutex.