flash.concurrent

# Mutex - AS3

Package | flash.concurrent
Class | public final class Mutex
Inheritance | Mutex 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.

Related API Elements

Worker class
ByteArray.shareable property
Condition 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Mutex() Creates a new Mutex instance. | Mutex
|  | 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
|  | lock():void Pauses execution of the current worker until this mutex is available and then takes ownership of the mutex. | Mutex
|  | 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
|  | tryLock():Boolean 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
|  | valueOf():Object Returns the primitive value of the specified object. | Object

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

| `Boolean` — `true` 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.

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