     }
 
     /**
-     * Wait until this mutex is available and then take exclusive ownership,
-     * increase the mutex's lock count by one, and proceed.
-     * This is also known as "acquiring" this mutex.
-     *
-     * If a thread already owns a mutex when this call is made to lock it,
-     * then its internal lock count is increased and no other action occurs.
-     *
+     * Pauses execution of the current worker until this mutex is available and 
+     * then takes ownership of the mutex. If another worker currently owns the 
+     * mutex, the calling worker's execution thread pauses at the 
+     * <code>lock()</code> call and the worker is added to the queue of ownership 
+     * requests. Once it is this worker's turn to own the mutex, the worker's 
+     * execution continues with the line of code following the 
+     * <code>lock()</code> call.
+     *
+     * <p>Once the current worker has ownership of the mutex, it can safely 
+     * operate on the shared resource. When those operations are complete, call 
+     * the <code>unlock()</code> method to release the mutex. At that point the 
+     * current worker should no longer access the shared resource.</p>
+     *
+     * <p>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 <code>lock()</code> method) the 
+     * internal lock count increases by one. You must call the 
+     * <code>unlock()</code> method as many times as the number of lock requests 
+     * to release ownership of the mutex.</p>
+     * 
      * @langversion 3.0
      * @playerversion Flash 11.4	
      * @playerversion AIR 3.4

include "api-versions.as"

/**
 * A Mutex is an object that facilitates "mutual exclusion"
 * of competing threads of execution in critical sections.
 *
 * At any given time there can be at most one thread of execution
 * which has ownership of a given mutex.
 * Transitions between who owns a mutex and who does not are always atomic.
 * The methods of this class are such that a critical section can be guarded
 * by acquiring and then releasing a mutex at its boundaries.
 *
 * Every new running worker contains at least one new thread of execution.
 * Mutexes treat all threads the same, irrespective of the workers they are in.
 * Thus mutexes can be used to control concurrency between workers as a whole
 * as well as threads within and across them.
 *
 * When a mutex is transported to another worker via an argument of a 
 * MessageChannel call or via Worker.setSharedProperty()
 * then the remote copy of the mutex will continue to use
 * the identical underlying lock handling data structures.
 * This makes the original mutex effectively shared between workers,
 * which can thus create critical sections that exclude each other.
 *
 * Note that locking and unlocking are not lexically paired.
 * Also note that these mutexes are recursive,
 * i.e. repeated locking increases an internal lock count
 * and only an equal amount of unlock calls finally releases a mutex.
 * Otherwise it stays locked.
 *
 * Any attempt to unlock a mutex that is not owned by the caller throws an error.
 *
 * @langversion 3.0
 * @playerversion Flash 11.4	

    public native function lock() :void

    /**
     * Acquires ownership of the mutex if it is available. Otherwise, calling 
     * this method returns <code>false</code> and code execution continues 
     * immediately.
     *
     * <p>Once the current worker has ownership of the mutex, it can safely 
     * operate on the shared resource. When those operations are complete, call 
     * the <code>unlock()</code> method to release the mutex. At that point the 
     * current worker should no longer access the shared resource.</p>
     *
     * @return <code>true</code> if the mutex was available (and is now owned 
     * by the current worker), or <code>false</code> if the current worker did 
     * not acquire ownership of the mutex
     *
     * @langversion 3.0
     * @playerversion Flash 11.4	
