0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * This file is available under and governed by the GNU General Public 0N/A * License version 2 only, as published by the Free Software Foundation. 0N/A * However, the following notice accompanied the original version of this 0N/A * Written by Doug Lea with assistance from members of JCP JSR-166 0N/A * Expert Group and released to the public domain, as explained at 0N/A * A reentrant mutual exclusion {@link Lock} with the same basic 0N/A * behavior and semantics as the implicit monitor lock accessed using 0N/A * {@code synchronized} methods and statements, but with extended 0N/A * <p>A {@code ReentrantLock} is <em>owned</em> by the thread last 0N/A * successfully locking, but not yet unlocking it. A thread invoking 0N/A * {@code lock} will return, successfully acquiring the lock, when 0N/A * the lock is not owned by another thread. The method will return 0N/A * immediately if the current thread already owns the lock. This can 0N/A * be checked using methods {@link #isHeldByCurrentThread}, and {@link 0N/A * <p>The constructor for this class accepts an optional 0N/A * <em>fairness</em> parameter. When set {@code true}, under 0N/A * contention, locks favor granting access to the longest-waiting 0N/A * thread. Otherwise this lock does not guarantee any particular 0N/A * access order. Programs using fair locks accessed by many threads 0N/A * may display lower overall throughput (i.e., are slower; often much 0N/A * slower) than those using the default setting, but have smaller 0N/A * variances in times to obtain locks and guarantee lack of 0N/A * starvation. Note however, that fairness of locks does not guarantee 0N/A * fairness of thread scheduling. Thus, one of many threads using a 0N/A * fair lock may obtain it multiple times in succession while other 0N/A * active threads are not progressing and not currently holding the 0N/A * Also note that the untimed {@link #tryLock() tryLock} method does not 0N/A * honor the fairness setting. It will succeed if the lock 0N/A * is available even if other threads are waiting. 0N/A * <p>It is recommended practice to <em>always</em> immediately 0N/A * follow a call to {@code lock} with a {@code try} block, most 0N/A * private final ReentrantLock lock = new ReentrantLock(); 0N/A * lock.lock(); // block until condition holds 0N/A * // ... method body 0N/A * <p>In addition to implementing the {@link Lock} interface, this 0N/A * class defines methods {@code isLocked} and 0N/A * {@code getLockQueueLength}, as well as some associated 0N/A * {@code protected} access methods that may be useful for 0N/A * instrumentation and monitoring. 0N/A * <p>Serialization of this class behaves in the same way as built-in 0N/A * locks: a deserialized lock is in the unlocked state, regardless of 0N/A * its state when serialized. 0N/A * <p>This lock supports a maximum of 2147483647 recursive locks by 0N/A * the same thread. Attempts to exceed this limit result in 0N/A * {@link Error} throws from locking methods. 0N/A /** Synchronizer providing all implementation mechanics */ 0N/A * Base of synchronization control for this lock. Subclassed 0N/A * into fair and nonfair versions below. Uses AQS state to 0N/A * represent the number of holds on the lock. 0N/A * Performs {@link Lock#lock}. The main reason for subclassing 0N/A * is to allow fast path for nonfair version. 0N/A * Performs non-fair tryLock. tryAcquire is 0N/A * implemented in subclasses, but both need nonfair 0N/A * try for trylock method. 0N/A throw new Error(
"Maximum lock count exceeded");
0N/A // While we must in general read state before owner, 0N/A // we don't need to do so to check if current thread is owner 0N/A // Methods relayed from outer class 0N/A * Reconstitutes this lock instance from a stream. 0N/A * @param s the stream 0N/A * Sync object for non-fair locks 0N/A * Performs lock. Try immediate barge, backing up to normal 0N/A * acquire on failure. 0N/A * Sync object for fair locks 0N/A * Fair version of tryAcquire. Don't grant access unless 0N/A * recursive call or no waiters or is first. 0N/A throw new Error(
"Maximum lock count exceeded");
0N/A * Creates an instance of {@code ReentrantLock}. 0N/A * This is equivalent to using {@code ReentrantLock(false)}. 0N/A * Creates an instance of {@code ReentrantLock} with the 0N/A * given fairness policy. 0N/A * @param fair {@code true} if this lock should use a fair ordering policy 0N/A * Acquires the lock. 0N/A * <p>Acquires the lock if it is not held by another thread and returns 0N/A * immediately, setting the lock hold count to one. 0N/A * <p>If the current thread already holds the lock then the hold 0N/A * count is incremented by one and the method returns immediately. 0N/A * <p>If the lock is held by another thread then the 0N/A * current thread becomes disabled for thread scheduling 0N/A * purposes and lies dormant until the lock has been acquired, 0N/A * at which time the lock hold count is set to one. 0N/A * Acquires the lock unless the current thread is 0N/A * {@linkplain Thread#interrupt interrupted}. 0N/A * <p>Acquires the lock if it is not held by another thread and returns 0N/A * immediately, setting the lock hold count to one. 0N/A * <p>If the current thread already holds this lock then the hold count 0N/A * is incremented by one and the method returns immediately. 0N/A * <p>If the lock is held by another thread then the 0N/A * current thread becomes disabled for thread scheduling 0N/A * purposes and lies dormant until one of two things happens: 0N/A * <li>The lock is acquired by the current thread; or 0N/A * <li>Some other thread {@linkplain Thread#interrupt interrupts} the 0N/A * <p>If the lock is acquired by the current thread then the lock hold 0N/A * count is set to one. 0N/A * <p>If the current thread: 0N/A * <li>has its interrupted status set on entry to this method; or 0N/A * <li>is {@linkplain Thread#interrupt interrupted} while acquiring 0N/A * then {@link InterruptedException} is thrown and the current thread's 0N/A * interrupted status is cleared. 0N/A * <p>In this implementation, as this method is an explicit 0N/A * interruption point, preference is given to responding to the 0N/A * interrupt over normal or reentrant acquisition of the lock. 0N/A * @throws InterruptedException if the current thread is interrupted 0N/A * Acquires the lock only if it is not held by another thread at the time 0N/A * <p>Acquires the lock if it is not held by another thread and 0N/A * returns immediately with the value {@code true}, setting the 0N/A * lock hold count to one. Even when this lock has been set to use a 0N/A * fair ordering policy, a call to {@code tryLock()} <em>will</em> 0N/A * immediately acquire the lock if it is available, whether or not 0N/A * other threads are currently waiting for the lock. 0N/A * This "barging" behavior can be useful in certain 0N/A * circumstances, even though it breaks fairness. If you want to honor 0N/A * the fairness setting for this lock, then use 0N/A * {@link #tryLock(long, TimeUnit) tryLock(0, TimeUnit.SECONDS) } 0N/A * which is almost equivalent (it also detects interruption). 0N/A * <p> If the current thread already holds this lock then the hold 0N/A * count is incremented by one and the method returns {@code true}. 0N/A * <p>If the lock is held by another thread then this method will return 0N/A * immediately with the value {@code false}. 0N/A * @return {@code true} if the lock was free and was acquired by the 0N/A * current thread, or the lock was already held by the current 0N/A * thread; and {@code false} otherwise 0N/A * Acquires the lock if it is not held by another thread within the given 0N/A * waiting time and the current thread has not been 0N/A * {@linkplain Thread#interrupt interrupted}. 0N/A * <p>Acquires the lock if it is not held by another thread and returns 0N/A * immediately with the value {@code true}, setting the lock hold count 0N/A * to one. If this lock has been set to use a fair ordering policy then 0N/A * an available lock <em>will not</em> be acquired if any other threads 0N/A * are waiting for the lock. This is in contrast to the {@link #tryLock()} 0N/A * method. If you want a timed {@code tryLock} that does permit barging on 0N/A * a fair lock then combine the timed and un-timed forms together: 0N/A * <pre>if (lock.tryLock() || lock.tryLock(timeout, unit) ) { ... } 0N/A * <p>If the current thread 0N/A * already holds this lock then the hold count is incremented by one and 0N/A * the method returns {@code true}. 0N/A * <p>If the lock is held by another thread then the 0N/A * current thread becomes disabled for thread scheduling 0N/A * purposes and lies dormant until one of three things happens: 0N/A * <li>The lock is acquired by the current thread; or 0N/A * <li>Some other thread {@linkplain Thread#interrupt interrupts} 0N/A * the current thread; or 0N/A * <li>The specified waiting time elapses 0N/A * <p>If the lock is acquired then the value {@code true} is returned and 0N/A * the lock hold count is set to one. 0N/A * <p>If the current thread: 0N/A * <li>has its interrupted status set on entry to this method; or 0N/A * <li>is {@linkplain Thread#interrupt interrupted} while 0N/A * acquiring the lock, 0N/A * then {@link InterruptedException} is thrown and the current thread's 0N/A * interrupted status is cleared. 0N/A * <p>If the specified waiting time elapses then the value {@code false} 0N/A * is returned. If the time is less than or equal to zero, the method 0N/A * will not wait at all. 0N/A * <p>In this implementation, as this method is an explicit 0N/A * interruption point, preference is given to responding to the 0N/A * interrupt over normal or reentrant acquisition of the lock, and 0N/A * over reporting the elapse of the waiting time. 0N/A * @param timeout the time to wait for the lock 0N/A * @param unit the time unit of the timeout argument 0N/A * @return {@code true} if the lock was free and was acquired by the 0N/A * current thread, or the lock was already held by the current 0N/A * thread; and {@code false} if the waiting time elapsed before 0N/A * the lock could be acquired 0N/A * @throws InterruptedException if the current thread is interrupted 0N/A * @throws NullPointerException if the time unit is null 0N/A * Attempts to release this lock. 0N/A * <p>If the current thread is the holder of this lock then the hold 0N/A * count is decremented. If the hold count is now zero then the lock 0N/A * is released. If the current thread is not the holder of this 0N/A * lock then {@link IllegalMonitorStateException} is thrown. 0N/A * @throws IllegalMonitorStateException if the current thread does not 0N/A * Returns a {@link Condition} instance for use with this 0N/A * {@link Lock} instance. 0N/A * <p>The returned {@link Condition} instance supports the same 0N/A * usages as do the {@link Object} monitor methods ({@link 0N/A * Object#wait() wait}, {@link Object#notify notify}, and {@link 0N/A * Object#notifyAll notifyAll}) when used with the built-in 0N/A * <li>If this lock is not held when any of the {@link Condition} 0N/A * {@linkplain Condition#await() waiting} or {@linkplain 0N/A * Condition#signal signalling} methods are called, then an {@link 0N/A * IllegalMonitorStateException} is thrown. 0N/A * <li>When the condition {@linkplain Condition#await() waiting} 0N/A * methods are called the lock is released and, before they 0N/A * return, the lock is reacquired and the lock hold count restored 0N/A * to what it was when the method was called. 0N/A * <li>If a thread is {@linkplain Thread#interrupt interrupted} 0N/A * while waiting then the wait will terminate, an {@link 0N/A * InterruptedException} will be thrown, and the thread's 0N/A * interrupted status will be cleared. 0N/A * <li> Waiting threads are signalled in FIFO order. 0N/A * <li>The ordering of lock reacquisition for threads returning 0N/A * from waiting methods is the same as for threads initially 0N/A * acquiring the lock, which is in the default case not specified, 0N/A * but for <em>fair</em> locks favors those threads that have been 0N/A * waiting the longest. 0N/A * @return the Condition object 0N/A * Queries the number of holds on this lock by the current thread. 0N/A * <p>A thread has a hold on a lock for each lock action that is not 0N/A * matched by an unlock action. 0N/A * <p>The hold count information is typically only used for testing and 0N/A * debugging purposes. For example, if a certain section of code should 0N/A * not be entered with the lock already held then we can assert that 0N/A * ReentrantLock lock = new ReentrantLock(); 0N/A * assert lock.getHoldCount() == 0; 0N/A * // ... method body 0N/A * @return the number of holds on this lock by the current thread, 0N/A * or zero if this lock is not held by the current thread 0N/A * Queries if this lock is held by the current thread. 0N/A * <p>Analogous to the {@link Thread#holdsLock} method for built-in 0N/A * monitor locks, this method is typically used for debugging and 0N/A * testing. For example, a method that should only be called while 0N/A * a lock is held can assert that this is the case: 0N/A * ReentrantLock lock = new ReentrantLock(); 0N/A * assert lock.isHeldByCurrentThread(); 0N/A * // ... method body 0N/A * <p>It can also be used to ensure that a reentrant lock is used 0N/A * in a non-reentrant manner, for example: 0N/A * ReentrantLock lock = new ReentrantLock(); 0N/A * assert !lock.isHeldByCurrentThread(); 0N/A * // ... method body 0N/A * @return {@code true} if current thread holds this lock and 0N/A * {@code false} otherwise 0N/A * Queries if this lock is held by any thread. This method is 0N/A * designed for use in monitoring of the system state, 0N/A * not for synchronization control. 0N/A * @return {@code true} if any thread holds this lock and 0N/A * {@code false} otherwise 0N/A * Returns {@code true} if this lock has fairness set true. 0N/A * @return {@code true} if this lock has fairness set true 0N/A * Returns the thread that currently owns this lock, or 0N/A * {@code null} if not owned. When this method is called by a 0N/A * thread that is not the owner, the return value reflects a 0N/A * best-effort approximation of current lock status. For example, 0N/A * the owner may be momentarily {@code null} even if there are 0N/A * threads trying to acquire the lock but have not yet done so. 0N/A * This method is designed to facilitate construction of 0N/A * subclasses that provide more extensive lock monitoring 0N/A * @return the owner, or {@code null} if not owned 0N/A * Queries whether any threads are waiting to acquire this lock. Note that 0N/A * because cancellations may occur at any time, a {@code true} 0N/A * return does not guarantee that any other thread will ever 0N/A * acquire this lock. This method is designed primarily for use in 0N/A * monitoring of the system state. 0N/A * @return {@code true} if there may be other threads waiting to 0N/A * Queries whether the given thread is waiting to acquire this 0N/A * lock. Note that because cancellations may occur at any time, a 0N/A * {@code true} return does not guarantee that this thread 0N/A * will ever acquire this lock. This method is designed primarily for use 0N/A * in monitoring of the system state. 0N/A * @param thread the thread 0N/A * @return {@code true} if the given thread is queued waiting for this lock 0N/A * @throws NullPointerException if the thread is null 0N/A * Returns an estimate of the number of threads waiting to 0N/A * acquire this lock. The value is only an estimate because the number of 0N/A * threads may change dynamically while this method traverses 0N/A * internal data structures. This method is designed for use in 0N/A * monitoring of the system state, not for synchronization 0N/A * @return the estimated number of threads waiting for this lock 0N/A * Returns a collection containing threads that may be waiting to 0N/A * acquire this lock. Because the actual set of threads may change 0N/A * dynamically while constructing this result, the returned 0N/A * collection is only a best-effort estimate. The elements of the 0N/A * returned collection are in no particular order. This method is 0N/A * designed to facilitate construction of subclasses that provide 0N/A * more extensive monitoring facilities. 0N/A * @return the collection of threads 0N/A * Queries whether any threads are waiting on the given condition 0N/A * associated with this lock. Note that because timeouts and 0N/A * interrupts may occur at any time, a {@code true} return does 0N/A * not guarantee that a future {@code signal} will awaken any 0N/A * threads. This method is designed primarily for use in 0N/A * monitoring of the system state. 0N/A * @param condition the condition 0N/A * @return {@code true} if there are any waiting threads 0N/A * @throws IllegalMonitorStateException if this lock is not held 0N/A * @throws IllegalArgumentException if the given condition is 0N/A * not associated with this lock 0N/A * @throws NullPointerException if the condition is null 0N/A * Returns an estimate of the number of threads waiting on the 0N/A * given condition associated with this lock. Note that because 0N/A * timeouts and interrupts may occur at any time, the estimate 0N/A * serves only as an upper bound on the actual number of waiters. 0N/A * This method is designed for use in monitoring of the system 0N/A * state, not for synchronization control. 0N/A * @param condition the condition 0N/A * @return the estimated number of waiting threads 0N/A * @throws IllegalMonitorStateException if this lock is not held 0N/A * @throws IllegalArgumentException if the given condition is 0N/A * not associated with this lock 0N/A * @throws NullPointerException if the condition is null 0N/A * Returns a collection containing those threads that may be 0N/A * waiting on the given condition associated with this lock. 0N/A * Because the actual set of threads may change dynamically while 0N/A * constructing this result, the returned collection is only a 0N/A * best-effort estimate. The elements of the returned collection 0N/A * are in no particular order. This method is designed to 0N/A * facilitate construction of subclasses that provide more 0N/A * extensive condition monitoring facilities. 0N/A * @param condition the condition 0N/A * @return the collection of threads 0N/A * @throws IllegalMonitorStateException if this lock is not held 0N/A * @throws IllegalArgumentException if the given condition is 0N/A * not associated with this lock 0N/A * @throws NullPointerException if the condition is null 0N/A * Returns a string identifying this lock, as well as its lock state. 0N/A * The state, in brackets, includes either the String {@code "Unlocked"} 0N/A * or the String {@code "Locked by"} followed by the 0N/A * {@linkplain Thread#getName name} of the owning thread. 0N/A * @return a string identifying this lock, as well as its lock state