Packageflash.concurrent
Classpublic final class Mutex
InheritanceMutex Inheritance Object

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 11.5, 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 Methods
 MethodDefined By
  
Creates a new Mutex instance.
Mutex
 Inherited
_init():*
[static]
_init
 Inherited
AS3
 Inherited
init():*
[static]
init
 Inherited
AS3
  
lock():void
Pauses execution of the current worker until this mutex is available and then takes ownership of the mutex.
Mutex
 Inherited
AS3
  
Acquires ownership of the mutex if it is available.
Mutex
  
unlock():void
Releases ownership of this mutex, allowing any worker to acquire it and perform work on the associated resource.
Mutex
Protected Methods
 MethodDefined By
 Inherited
[static]
protected
 Inherited
_setPropertyIsEnumerable(o:*, V:String, enumerable:Boolean):void
[static]
protected
Public Constants
 ConstantDefined By
 Inheritedlength : int = 1
[static]
length
Constructor Detail
Mutex()Constructor
public function Mutex()

Language Version : ActionScript 3.0
Runtime Versions : Flash Player 11.5, 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 Versions : Flash Player 11.5, 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 Versions : Flash Player 11.5, 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 Versions : Flash Player 11.5, 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
IllegalOperationError — when the current worker doesn't own the mutex.