1 *java.util.concurrent.locks.ReentrantLock* *ReentrantLock* A reentrant mutual ex
3 public class ReentrantLock
4 extends |java.lang.Object|
5 implements |java.util.concurrent.locks.Lock|
8 |java.util.concurrent.locks.ReentrantLock_Description|
9 |java.util.concurrent.locks.ReentrantLock_Fields|
10 |java.util.concurrent.locks.ReentrantLock_Constructors|
11 |java.util.concurrent.locks.ReentrantLock_Methods|
13 ================================================================================
15 *java.util.concurrent.locks.ReentrantLock_Constructors*
16 |java.util.concurrent.locks.ReentrantLock()|Creates an instance of ReentrantLoc
17 |java.util.concurrent.locks.ReentrantLock(boolean)|Creates an instance of Reent
19 *java.util.concurrent.locks.ReentrantLock_Methods*
20 |java.util.concurrent.locks.ReentrantLock.getHoldCount()|Queries the number of
21 |java.util.concurrent.locks.ReentrantLock.getOwner()|Returns the thread that cu
22 |java.util.concurrent.locks.ReentrantLock.getQueuedThreads()|Returns a collecti
23 |java.util.concurrent.locks.ReentrantLock.getQueueLength()|Returns an estimate
24 |java.util.concurrent.locks.ReentrantLock.getWaitingThreads(Condition)|Returns
25 |java.util.concurrent.locks.ReentrantLock.getWaitQueueLength(Condition)|Returns
26 |java.util.concurrent.locks.ReentrantLock.hasQueuedThread(Thread)|Queries wheth
27 |java.util.concurrent.locks.ReentrantLock.hasQueuedThreads()|Queries whether an
28 |java.util.concurrent.locks.ReentrantLock.hasWaiters(Condition)|Queries whether
29 |java.util.concurrent.locks.ReentrantLock.isFair()|Returns true if this lock ha
30 |java.util.concurrent.locks.ReentrantLock.isHeldByCurrentThread()|Queries if th
31 |java.util.concurrent.locks.ReentrantLock.isLocked()|Queries if this lock is he
32 |java.util.concurrent.locks.ReentrantLock.lock()|Acquires the lock.
33 |java.util.concurrent.locks.ReentrantLock.lockInterruptibly()|Acquires the lock
34 |java.util.concurrent.locks.ReentrantLock.newCondition()|Returns aConditioninst
35 |java.util.concurrent.locks.ReentrantLock.toString()|Returns a string identifyi
36 |java.util.concurrent.locks.ReentrantLock.tryLock()|Acquires the lock only if i
37 |java.util.concurrent.locks.ReentrantLock.tryLock(long,TimeUnit)|Acquires the l
38 |java.util.concurrent.locks.ReentrantLock.unlock()|Attempts to release this loc
40 *java.util.concurrent.locks.ReentrantLock_Description*
42 A reentrant mutual exclusion (|java.util.concurrent.locks.Lock|) with the same
43 basic behavior and semantics as the implicit monitor lock accessed using
44 synchronized methods and statements, but with extended capabilities.
46 A ReentrantLock is owned by the thread last successfully locking, but not yet
47 unlocking it. A thread invoking lock will return, successfully acquiring the
48 lock, when the lock is not owned by another thread. The method will return
49 immediately if the current thread already owns the lock. This can be checked
50 using methods (|java.util.concurrent.locks.ReentrantLock|) , and
51 (|java.util.concurrent.locks.ReentrantLock|) .
53 The constructor for this class accepts an optional fairness parameter. When set
54 true, under contention, locks favor granting access to the longest-waiting
55 thread. Otherwise this lock does not guarantee any particular access order.
56 Programs using fair locks accessed by many threads may display lower overall
57 throughput (i.e., are slower; often much slower) than those using the default
58 setting, but have smaller variances in times to obtain locks and guarantee lack
59 of starvation. Note however, that fairness of locks does not guarantee fairness
60 of thread scheduling. Thus, one of many threads using a fair lock may obtain it
61 multiple times in succession while other active threads are not progressing and
62 not currently holding the lock. Also note that the untimed
63 tryLock(|java.util.concurrent.locks.ReentrantLock|) method does not honor the
64 fairness setting. It will succeed if the lock is available even if other
67 It is recommended practice to always immediately follow a call to lock with a
68 try block, most typically in a before/after construction such as:
72 class X { private final ReentrantLock lock = new ReentrantLock(); // ...
74 public void m() { lock.lock(); // block until condition holds try { // ...
75 method body } finally { lock.unlock() } } }
77 In addition to implementing the (|java.util.concurrent.locks.Lock|) interface,
78 this class defines methods isLocked and getLockQueueLength, as well as some
79 associated protected access methods that may be useful for instrumentation and
82 Serialization of this class behaves in the same way as built-in locks: a
83 deserialized lock is in the unlocked state, regardless of its state when
86 This lock supports a maximum of 2147483648 recursive locks by the same thread.
89 *java.util.concurrent.locks.ReentrantLock()*
91 public ReentrantLock()
93 Creates an instance of ReentrantLock. This is equivalent to using
97 *java.util.concurrent.locks.ReentrantLock(boolean)*
99 public ReentrantLock(boolean fair)
101 Creates an instance of ReentrantLock with the given fairness policy.
103 fair - true if this lock will be fair; else false
105 *java.util.concurrent.locks.ReentrantLock.getHoldCount()*
107 public int getHoldCount()
109 Queries the number of holds on this lock by the current thread.
111 A thread has a hold on a lock for each lock action that is not matched by an
114 The hold count information is typically only used for testing and debugging
115 purposes. For example, if a certain section of code should not be entered with
116 the lock already held then we can assert that fact:
120 class X { ReentrantLock lock = new ReentrantLock(); // ... public void m() {
121 assert lock.getHoldCount() == 0; lock.lock(); try { // ... method body }
122 finally { lock.unlock(); } } }
125 Returns: the number of holds on this lock by the current thread, or zero if this lock is
126 not held by the current thread.
127 *java.util.concurrent.locks.ReentrantLock.getOwner()*
129 protected |java.lang.Thread| getOwner()
131 Returns the thread that currently owns this lock, or null if not owned. Note
132 that the owner may be momentarily null even if there are threads trying to
133 acquire the lock but have not yet done so. This method is designed to
134 facilitate construction of subclasses that provide more extensive lock
135 monitoring facilities.
138 Returns: the owner, or null if not owned.
139 *java.util.concurrent.locks.ReentrantLock.getQueuedThreads()*
141 protected |java.util.Collection| getQueuedThreads()
143 Returns a collection containing threads that may be waiting to acquire this
144 lock. Because the actual set of threads may change dynamically while
145 constructing this result, the returned collection is only a best-effort
146 estimate. The elements of the returned collection are in no particular order.
147 This method is designed to facilitate construction of subclasses that provide
148 more extensive monitoring facilities.
151 Returns: the collection of threads
152 *java.util.concurrent.locks.ReentrantLock.getQueueLength()*
154 public final int getQueueLength()
156 Returns an estimate of the number of threads waiting to acquire this lock. The
157 value is only an estimate because the number of threads may change dynamically
158 while this method traverses internal data structures. This method is designed
159 for use in monitoring of the system state, not for synchronization control.
162 Returns: the estimated number of threads waiting for this lock
163 *java.util.concurrent.locks.ReentrantLock.getWaitingThreads(Condition)*
165 protected |java.util.Collection| getWaitingThreads(java.util.concurrent.locks.Condition condition)
167 Returns a collection containing those threads that may be waiting on the given
168 condition associated with this lock. Because the actual set of threads may
169 change dynamically while constructing this result, the returned collection is
170 only a best-effort estimate. The elements of the returned collection are in no
171 particular order. This method is designed to facilitate construction of
172 subclasses that provide more extensive condition monitoring facilities.
174 condition - the condition
176 Returns: the collection of threads
177 *java.util.concurrent.locks.ReentrantLock.getWaitQueueLength(Condition)*
179 public int getWaitQueueLength(java.util.concurrent.locks.Condition condition)
181 Returns an estimate of the number of threads waiting on the given condition
182 associated with this lock. Note that because timeouts and interrupts may occur
183 at any time, the estimate serves only as an upper bound on the actual number of
184 waiters. This method is designed for use in monitoring of the system state, not
185 for synchronization control.
187 condition - the condition
189 Returns: the estimated number of waiting threads.
190 *java.util.concurrent.locks.ReentrantLock.hasQueuedThread(Thread)*
192 public final boolean hasQueuedThread(java.lang.Thread thread)
194 Queries whether the given thread is waiting to acquire this lock. Note that
195 because cancellations may occur at any time, a true return does not guarantee
196 that this thread will ever acquire this lock. This method is designed primarily
197 for use in monitoring of the system state.
201 Returns: true if the given thread is queued waiting for this lock.
202 *java.util.concurrent.locks.ReentrantLock.hasQueuedThreads()*
204 public final boolean hasQueuedThreads()
206 Queries whether any threads are waiting to acquire this lock. Note that because
207 cancellations may occur at any time, a true return does not guarantee that any
208 other thread will ever acquire this lock. This method is designed primarily for
209 use in monitoring of the system state.
212 Returns: true if there may be other threads waiting to acquire the lock.
213 *java.util.concurrent.locks.ReentrantLock.hasWaiters(Condition)*
215 public boolean hasWaiters(java.util.concurrent.locks.Condition condition)
217 Queries whether any threads are waiting on the given condition associated with
218 this lock. Note that because timeouts and interrupts may occur at any time, a
219 true return does not guarantee that a future signal will awaken any threads.
220 This method is designed primarily for use in monitoring of the system state.
222 condition - the condition
224 Returns: true if there are any waiting threads.
225 *java.util.concurrent.locks.ReentrantLock.isFair()*
227 public final boolean isFair()
229 Returns true if this lock has fairness set true.
232 Returns: true if this lock has fairness set true.
233 *java.util.concurrent.locks.ReentrantLock.isHeldByCurrentThread()*
235 public boolean isHeldByCurrentThread()
237 Queries if this lock is held by the current thread.
239 Analogous to the (|java.lang.Thread|) method for built-in monitor locks, this
240 method is typically used for debugging and testing. For example, a method that
241 should only be called while a lock is held can assert that this is the case:
245 class X { ReentrantLock lock = new ReentrantLock(); // ...
247 public void m() { assert lock.isHeldByCurrentThread(); // ... method body } }
249 It can also be used to ensure that a reentrant lock is used in a non-reentrant
254 class X { ReentrantLock lock = new ReentrantLock(); // ...
256 public void m() { assert !lock.isHeldByCurrentThread(); lock.lock(); try { //
257 ... method body } finally { lock.unlock(); } } }
260 Returns: true if current thread holds this lock and false otherwise.
261 *java.util.concurrent.locks.ReentrantLock.isLocked()*
263 public boolean isLocked()
265 Queries if this lock is held by any thread. This method is designed for use in
266 monitoring of the system state, not for synchronization control.
269 Returns: true if any thread holds this lock and false otherwise.
270 *java.util.concurrent.locks.ReentrantLock.lock()*
276 Acquires the lock if it is not held by another thread and returns immediately,
277 setting the lock hold count to one.
279 If the current thread already holds the lock then the hold count is incremented
280 by one and the method returns immediately.
282 If the lock is held by another thread then the current thread becomes disabled
283 for thread scheduling purposes and lies dormant until the lock has been
284 acquired, at which time the lock hold count is set to one.
287 *java.util.concurrent.locks.ReentrantLock.lockInterruptibly()*
289 public void lockInterruptibly()
290 throws |java.lang.InterruptedException|
292 Acquires the lock unless the current thread is interrupted(|java.lang.Thread|)
295 Acquires the lock if it is not held by another thread and returns immediately,
296 setting the lock hold count to one.
298 If the current thread already holds this lock then the hold count is
299 incremented by one and the method returns immediately.
301 If the lock is held by another thread then the current thread becomes disabled
302 for thread scheduling purposes and lies dormant until one of two things
307 The lock is acquired by the current thread; or
309 Some other thread interrupts(|java.lang.Thread|) the current thread.
313 If the lock is acquired by the current thread then the lock hold count is set
316 If the current thread:
320 has its interrupted status set on entry to this method; or
322 is interrupted(|java.lang.Thread|) while acquiring the lock,
326 then (|java.lang.InterruptedException|) is thrown and the current thread's
327 interrupted status is cleared.
329 In this implementation, as this method is an explicit interruption point,
330 preference is given to responding to the interrupt over normal or reentrant
331 acquisition of the lock.
334 *java.util.concurrent.locks.ReentrantLock.newCondition()*
336 public |java.util.concurrent.locks.Condition| newCondition()
338 Returns a (|java.util.concurrent.locks.Condition|) instance for use with this
339 (|java.util.concurrent.locks.Lock|) instance.
341 The returned (|java.util.concurrent.locks.Condition|) instance supports the
342 same usages as do the (|java.lang.Object|) monitor methods (
343 wait(|java.lang.Object|) , notify(|java.lang.Object|) , and
344 notifyAll(|java.lang.Object|) ) when used with the built-in monitor lock.
348 If this lock is not held when any of the
349 (|java.util.concurrent.locks.Condition|)
350 waiting(|java.util.concurrent.locks.Condition|) or
351 signalling(|java.util.concurrent.locks.Condition|) methods are called, then an
352 (|java.lang.IllegalMonitorStateException|) is thrown.
354 When the condition waiting(|java.util.concurrent.locks.Condition|) methods are
355 called the lock is released and, before they return, the lock is reacquired and
356 the lock hold count restored to what it was when the method was called.
358 If a thread is interrupted(|java.lang.Thread|) while waiting then the wait will
359 terminate, an (|java.lang.InterruptedException|) will be thrown, and the
360 thread's interrupted status will be cleared.
362 Waiting threads are signalled in FIFO order
364 The ordering of lock reacquisition for threads returning from waiting methods
365 is the same as for threads initially acquiring the lock, which is in the
366 default case not specified, but for fair locks favors those threads that have
367 been waiting the longest.
372 Returns: the Condition object
373 *java.util.concurrent.locks.ReentrantLock.toString()*
375 public |java.lang.String| toString()
377 Returns a string identifying this lock, as well as its lock state. The state,
378 in brackets, includes either the String Unlocked or the String Locked by
379 followed by the (|java.lang.Thread|) of the owning thread.
382 Returns: a string identifying this lock, as well as its lock state.
383 *java.util.concurrent.locks.ReentrantLock.tryLock()*
385 public boolean tryLock()
387 Acquires the lock only if it is not held by another thread at the time of
390 Acquires the lock if it is not held by another thread and returns immediately
391 with the value true, setting the lock hold count to one. Even when this lock
392 has been set to use a fair ordering policy, a call to tryLock() will
393 immediately acquire the lock if it is available, whether or not other threads
394 are currently waiting for the lock. This barging behavior can be useful in
395 certain circumstances, even though it breaks fairness. If you want to honor the
396 fairness setting for this lock, then use tryLock(0, TimeUnit.SECONDS)
397 (|java.util.concurrent.locks.ReentrantLock|) which is almost equivalent (it
398 also detects interruption).
400 If the current thread already holds this lock then the hold count is
401 incremented by one and the method returns true.
403 If the lock is held by another thread then this method will return immediately
404 with the value false.
407 Returns: true if the lock was free and was acquired by the current thread, or the lock
408 was already held by the current thread; and false otherwise.
409 *java.util.concurrent.locks.ReentrantLock.tryLock(long,TimeUnit)*
411 public boolean tryLock(
413 java.util.concurrent.TimeUnit unit)
414 throws |java.lang.InterruptedException|
416 Acquires the lock if it is not held by another thread within the given waiting
417 time and the current thread has not been interrupted(|java.lang.Thread|) .
419 Acquires the lock if it is not held by another thread and returns immediately
420 with the value true, setting the lock hold count to one. If this lock has been
421 set to use a fair ordering policy then an available lock will not be acquired
422 if any other threads are waiting for the lock. This is in contrast to the
423 (|java.util.concurrent.locks.ReentrantLock|) method. If you want a timed
424 tryLock that does permit barging on a fair lock then combine the timed and
425 un-timed forms together:
427 if (lock.tryLock() || lock.tryLock(timeout, unit) ) { ... }
429 If the current thread already holds this lock then the hold count is
430 incremented by one and the method returns true.
432 If the lock is held by another thread then the current thread becomes disabled
433 for thread scheduling purposes and lies dormant until one of three things
438 The lock is acquired by the current thread; or
440 Some other thread interrupts(|java.lang.Thread|) the current thread; or
442 The specified waiting time elapses
446 If the lock is acquired then the value true is returned and the lock hold count
449 If the current thread:
453 has its interrupted status set on entry to this method; or
455 is interrupted(|java.lang.Thread|) while acquiring the lock,
457 then (|java.lang.InterruptedException|) is thrown and the current thread's
458 interrupted status is cleared.
460 If the specified waiting time elapses then the value false is returned. If the
461 time is less than or equal to zero, the method will not wait at all.
463 In this implementation, as this method is an explicit interruption point,
464 preference is given to responding to the interrupt over normal or reentrant
465 acquisition of the lock, and over reporting the elapse of the waiting time.
467 timeout - the time to wait for the lock
468 unit - the time unit of the timeout argument
470 Returns: true if the lock was free and was acquired by the current thread, or the lock
471 was already held by the current thread; and false if the waiting
472 time elapsed before the lock could be acquired.
473 *java.util.concurrent.locks.ReentrantLock.unlock()*
477 Attempts to release this lock.
479 If the current thread is the holder of this lock then the hold count is
480 decremented. If the hold count is now zero then the lock is released. If the
481 current thread is not the holder of this lock then
482 (|java.lang.IllegalMonitorStateException|) is thrown.