Mutex

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

	Property		Defined By
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object

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.

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.

Legal Notices | Online Privacy Policy

Mutex - AS3

Classes x

Mutex

lock

tryLock

unlock