1 *java.util.concurrent.locks.AbstractQueuedSynchronizer* *AbstractQueuedSynchronizer*
3 public abstract class AbstractQueuedSynchronizer
4 extends |java.lang.Object|
5 implements |java.io.Serializable|
7 |java.util.concurrent.locks.AbstractQueuedSynchronizer_Description|
8 |java.util.concurrent.locks.AbstractQueuedSynchronizer_Fields|
9 |java.util.concurrent.locks.AbstractQueuedSynchronizer_Constructors|
10 |java.util.concurrent.locks.AbstractQueuedSynchronizer_Methods|
12 ================================================================================
14 *java.util.concurrent.locks.AbstractQueuedSynchronizer_Constructors*
15 |java.util.concurrent.locks.AbstractQueuedSynchronizer()|Creates a new Abstract
17 *java.util.concurrent.locks.AbstractQueuedSynchronizer_Methods*
18 |java.util.concurrent.locks.AbstractQueuedSynchronizer.acquire(int)|Acquires in
19 |java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireInterruptibly(int)|
20 |java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireShared(int)|Acqui
21 |java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireSharedInterruptibly(int)|
22 |java.util.concurrent.locks.AbstractQueuedSynchronizer.compareAndSetState(int,int)|
23 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getExclusiveQueuedThreads()|
24 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getFirstQueuedThread()|R
25 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getQueuedThreads()|Retur
26 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getQueueLength()|Returns
27 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getSharedQueuedThreads()|
28 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getState()|Returns the c
29 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getWaitingThreads(AbstractQueuedSynchronizer.ConditionObject)|
30 |java.util.concurrent.locks.AbstractQueuedSynchronizer.getWaitQueueLength(AbstractQueuedSynchronizer.ConditionObject)|
31 |java.util.concurrent.locks.AbstractQueuedSynchronizer.hasContended()|Queries w
32 |java.util.concurrent.locks.AbstractQueuedSynchronizer.hasQueuedThreads()|Queri
33 |java.util.concurrent.locks.AbstractQueuedSynchronizer.hasWaiters(AbstractQueuedSynchronizer.ConditionObject)|
34 |java.util.concurrent.locks.AbstractQueuedSynchronizer.isHeldExclusively()|Retu
35 |java.util.concurrent.locks.AbstractQueuedSynchronizer.isQueued(Thread)|Returns
36 |java.util.concurrent.locks.AbstractQueuedSynchronizer.owns(AbstractQueuedSynchronizer.ConditionObject)|
37 |java.util.concurrent.locks.AbstractQueuedSynchronizer.release(int)|Releases in
38 |java.util.concurrent.locks.AbstractQueuedSynchronizer.releaseShared(int)|Relea
39 |java.util.concurrent.locks.AbstractQueuedSynchronizer.setState(int)|Sets the v
40 |java.util.concurrent.locks.AbstractQueuedSynchronizer.toString()|Returns a str
41 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquire(int)|Attempts
42 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireNanos(int,long)|
43 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireShared(int)|At
44 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireSharedNanos(int,long)|
45 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryRelease(int)|Attempts
46 |java.util.concurrent.locks.AbstractQueuedSynchronizer.tryReleaseShared(int)|At
48 *java.util.concurrent.locks.AbstractQueuedSynchronizer_Description*
50 Provides a framework for implementing blocking locks and related synchronizers
51 (semaphores, events, etc) that rely on first-in-first-out (FIFO) wait queues.
52 This class is designed to be a useful basis for most kinds of synchronizers
53 that rely on a single atomic int value to represent state. Subclasses must
54 define the protected methods that change this state, and which define what that
55 state means in terms of this object being acquired or released. Given these,
56 the other methods in this class carry out all queuing and blocking mechanics.
57 Subclasses can maintain other state fields, but only the atomically updated int
58 value manipulated using methods
59 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) ,
60 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) and
61 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) is tracked with
62 respect to synchronization.
64 Subclasses should be defined as non-public internal helper classes that are
65 used to implement the synchronization properties of their enclosing class.
66 Class AbstractQueuedSynchronizer does not implement any synchronization
67 interface. Instead it defines methods such as
68 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) that can be invoked
69 as appropriate by concrete locks and related synchronizers to implement their
72 This class supports either or both a default exclusive mode and a shared mode.
73 When acquired in exclusive mode, attempted acquires by other threads cannot
74 succeed. Shared mode acquires by multiple threads may (but need not) succeed.
75 This class does not understand these differences except in the mechanical sense
76 that when a shared mode acquire succeeds, the next waiting thread (if one
77 exists) must also determine whether it can acquire as well. Threads waiting in
78 the different modes share the same FIFO queue. Usually, implementation
79 subclasses support only one of these modes, but both can come into play for
80 example in a (|java.util.concurrent.locks.ReadWriteLock|) . Subclasses that
81 support only exclusive or only shared modes need not define the methods
82 supporting the unused mode.
84 This class defines a nested
85 (|java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject|) class
86 that can be used as a (|java.util.concurrent.locks.Condition|) implementation
87 by subclasses supporting exclusive mode for which method
88 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) reports whether
89 synchronization is exclusively held with respect to the current thread, method
90 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) invoked with the
91 current (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) value fully
92 releases this object, and
93 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , given this saved
94 state value, eventually restores this object to its previous acquired state. No
95 AbstractQueuedSynchronizer method otherwise creates such a condition, so if
96 this constraint cannot be met, do not use it. The behavior of
97 (|java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject|)
98 depends of course on the semantics of its synchronizer implementation.
100 This class provides inspection, instrumentation, and monitoring methods for the
101 internal queue, as well as similar methods for condition objects. These can be
102 exported as desired into classes using an AbstractQueuedSynchronizer for their
103 synchronization mechanics.
105 Serialization of this class stores only the underlying atomic integer
106 maintaining state, so deserialized objects have empty thread queues. Typical
107 subclasses requiring serializability will define a readObject method that
108 restores this to a known initial state upon deserialization.
112 To use this class as the basis of a synchronizer, redefine the following
113 methods, as applicable, by inspecting and/or modifying the synchronization
114 state using (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) ,
115 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) and/or
116 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) :
118 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
119 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
120 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
121 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
122 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
124 Each of these methods by default throws
125 (|java.lang.UnsupportedOperationException|) . Implementations of these methods
126 must be internally thread-safe, and should in general be short and not block.
127 Defining these methods is the only supported means of using this class. All
128 other methods are declared final because they cannot be independently varied.
130 Even though this class is based on an internal FIFO queue, it does not
131 automatically enforce FIFO acquisition policies. The core of exclusive
132 synchronization takes the form:
136 Acquire: while (!tryAcquire(arg)) { enqueue thread if it is not already queued;
137 possibly block current thread; }
139 Release: if (tryRelease(arg)) unblock the first queued thread;
141 (Shared mode is similar but may involve cascading signals.)
143 Because checks in acquire are invoked before enqueuing, a newly acquiring
144 thread may barge ahead of others that are blocked and queued. However, you can,
145 if desired, define tryAcquire and/or tryAcquireShared to disable barging by
146 internally invoking one or more of the inspection methods. In particular, a
147 strict FIFO lock can define tryAcquire to immediately return false if
148 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) does not return the
149 current thread. A normally preferable non-strict fair version can immediately
150 return false only if (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
151 returns true and getFirstQueuedThread is not the current thread; or
152 equivalently, that getFirstQueuedThread is both non-null and not the current
153 thread. Further variations are possible.
155 Throughput and scalability are generally highest for the default barging (also
156 known as greedy, renouncement, and convoy-avoidance) strategy. While this is
157 not guaranteed to be fair or starvation-free, earlier queued threads are
158 allowed to recontend before later queued threads, and each recontention has an
159 unbiased chance to succeed against incoming threads. Also, while acquires do
160 not spin in the usual sense, they may perform multiple invocations of
161 tryAcquire interspersed with other computations before blocking. This gives
162 most of the benefits of spins when exclusive synchronization is only briefly
163 held, without most of the liabilities when it isn't. If so desired, you can
164 augment this by preceding calls to acquire methods with "fast-path" checks,
165 possibly prechecking (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
166 and/or (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) to only do so
167 if the synchronizer is likely not to be contended.
169 This class provides an efficient and scalable basis for synchronization in part
170 by specializing its range of use to synchronizers that can rely on int state,
171 acquire, and release parameters, and an internal FIFO wait queue. When this
172 does not suffice, you can build synchronizers from a lower level using
173 atomic(|java.util.concurrent.atomic|) classes, your own custom
174 (|java.util.Queue|) classes, and (|java.util.concurrent.locks.LockSupport|)
179 Here is a non-reentrant mutual exclusion lock class that uses the value zero to
180 represent the unlocked state, and one to represent the locked state. It also
181 supports conditions and exposes one of the instrumentation methods:
185 class Mutex implements Lock, java.io.Serializable {
187 // Our internal helper class private static class Sync extends
188 AbstractQueuedSynchronizer { // Report whether in locked state protected
189 boolean isHeldExclusively() { return getState() == 1; }
191 // Acquire the lock if state is zero public boolean tryAcquire(int acquires) {
192 assert acquires == 1; // Otherwise unused return compareAndSetState(0, 1); }
194 // Release the lock by setting state to zero protected boolean tryRelease(int
195 releases) { assert releases == 1; // Otherwise unused if (getState() == 0)
196 throw new IllegalMonitorStateException(); setState(0); return true; }
198 // Provide a Condition Condition newCondition() { return new ConditionObject();
201 // Deserialize properly private void readObject(ObjectInputStream s) throws
202 IOException, ClassNotFoundException { s.defaultReadObject(); setState(0); //
203 reset to unlocked state } }
205 // The sync object does all the hard work. We just forward to it. private final
206 Sync sync = new Sync();
208 public void lock() { sync.acquire(1); } public boolean tryLock() { return
209 sync.tryAcquire(1); } public void unlock() { sync.release(1); } public
210 Condition newCondition() { return sync.newCondition(); } public boolean
211 isLocked() { return sync.isHeldExclusively(); } public boolean
212 hasQueuedThreads() { return sync.hasQueuedThreads(); } public void
213 lockInterruptibly() throws InterruptedException { sync.acquireInterruptibly(1);
214 } public boolean tryLock(long timeout, TimeUnit unit) throws
215 InterruptedException { return sync.tryAcquireNanos(1, unit.toNanos(timeout)); }
218 Here is a latch class that is like a (|java.util.concurrent.CountDownLatch|)
219 except that it only requires a single signal to fire. Because a latch is
220 non-exclusive, it uses the shared acquire and release methods.
226 private static class Sync extends AbstractQueuedSynchronizer { boolean
227 isSignalled() { return getState() != 0; }
229 protected int tryAcquireShared(int ignore) { return isSignalled()? 1 : -1; }
231 protected boolean tryReleaseShared(int ignore) { setState(1); return true; } }
233 private final Sync sync = new Sync(); public boolean isSignalled() { return
234 sync.isSignalled(); } public void signal() { sync.releaseShared(1); } public
235 void await() throws InterruptedException { sync.acquireSharedInterruptibly(1);
241 *java.util.concurrent.locks.AbstractQueuedSynchronizer()*
243 protected AbstractQueuedSynchronizer()
245 Creates a new AbstractQueuedSynchronizer instance with initial synchronization
249 *java.util.concurrent.locks.AbstractQueuedSynchronizer.acquire(int)*
251 public final void acquire(int arg)
253 Acquires in exclusive mode, ignoring interrupts. Implemented by invoking at
254 least once (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) ,
255 returning on success. Otherwise the thread is queued, possibly repeatedly
256 blocking and unblocking, invoking
257 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) until success. This
258 method can be used to implement method (|java.util.concurrent.locks.Lock|)
260 arg - the acquire argument. This value is conveyed to {@link #tryAcquire} but is
261 otherwise uninterpreted and can represent anything you like.
263 *java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireInterruptibly(int)*
265 public final void acquireInterruptibly(int arg)
266 throws |java.lang.InterruptedException|
268 Acquires in exclusive mode, aborting if interrupted. Implemented by first
269 checking interrupt status, then invoking at least once
270 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , returning on
271 success. Otherwise the thread is queued, possibly repeatedly blocking and
272 unblocking, invoking (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
273 until success or the thread is interrupted. This method can be used to
274 implement method (|java.util.concurrent.locks.Lock|)
276 arg - the acquire argument. This value is conveyed to {@link #tryAcquire} but is
277 otherwise uninterpreted and can represent anything you like.
279 *java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireShared(int)*
281 public final void acquireShared(int arg)
283 Acquires in shared mode, ignoring interrupts. Implemented by first invoking at
284 least once (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) ,
285 returning on success. Otherwise the thread is queued, possibly repeatedly
286 blocking and unblocking, invoking
287 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) until success.
289 arg - the acquire argument. This value is conveyed to {@link #tryAcquireShared} but
290 is otherwise uninterpreted and can represent anything you like.
292 *java.util.concurrent.locks.AbstractQueuedSynchronizer.acquireSharedInterruptibly(int)*
294 public final void acquireSharedInterruptibly(int arg)
295 throws |java.lang.InterruptedException|
297 Acquires in shared mode, aborting if interrupted. Implemented by first checking
298 interrupt status, then invoking at least once
299 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , returning on
300 success. Otherwise the thread is queued, possibly repeatedly blocking and
301 unblocking, invoking (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
302 until success or the thread is interrupted.
304 arg - the acquire argument. This value is conveyed to {@link #tryAcquireShared} but
305 is otherwise uninterpreted and can represent anything you like.
307 *java.util.concurrent.locks.AbstractQueuedSynchronizer.compareAndSetState(int,int)*
309 protected final boolean compareAndSetState(
313 Atomically sets synchronization state to the given updated value if the current
314 state value equals the expected value. This operation has memory semantics of a
315 volatile read and write.
317 expect - the expected value
318 update - the new value
320 Returns: true if successful. False return indicates that the actual value was not equal
321 to the expected value.
322 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getExclusiveQueuedThreads()*
324 public final |java.util.Collection| getExclusiveQueuedThreads()
326 Returns a collection containing threads that may be waiting to acquire in
327 exclusive mode. This has the same properties as
328 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) except that it only
329 returns those threads waiting due to an exclusive acquire.
332 Returns: the collection of threads
333 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getFirstQueuedThread()*
335 public final |java.lang.Thread| getFirstQueuedThread()
337 Returns the first (longest-waiting) thread in the queue, or null if no threads
338 are currently queued.
340 In this implementation, this operation normally returns in constant time, but
341 may iterate upon contention if other threads are concurrently modifying the
345 Returns: the first (longest-waiting) thread in the queue, or null if no threads are
347 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getQueuedThreads()*
349 public final |java.util.Collection| getQueuedThreads()
351 Returns a collection containing threads that may be waiting to acquire. Because
352 the actual set of threads may change dynamically while constructing this
353 result, the returned collection is only a best-effort estimate. The elements of
354 the returned collection are in no particular order. This method is designed to
355 facilitate construction of subclasses that provide more extensive monitoring
359 Returns: the collection of threads
360 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getQueueLength()*
362 public final int getQueueLength()
364 Returns an estimate of the number of threads waiting to acquire. The value is
365 only an estimate because the number of threads may change dynamically while
366 this method traverses internal data structures. This method is designed for use
367 in monitoring system state, not for synchronization control.
370 Returns: the estimated number of threads waiting for this lock
371 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getSharedQueuedThreads()*
373 public final |java.util.Collection| getSharedQueuedThreads()
375 Returns a collection containing threads that may be waiting to acquire in
376 shared mode. This has the same properties as
377 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) except that it only
378 returns those threads waiting due to a shared acquire.
381 Returns: the collection of threads
382 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getState()*
384 protected final int getState()
386 Returns the current value of synchronization state. This operation has memory
387 semantics of a volatile read.
390 Returns: current state value
391 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getWaitingThreads(AbstractQueuedSynchronizer.ConditionObject)*
393 public final |java.util.Collection| getWaitingThreads(java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject condition)
395 Returns a collection containing those threads that may be waiting on the given
396 condition associated with this synchronizer. Because the actual set of threads
397 may change dynamically while constructing this result, the returned collection
398 is only a best-effort estimate. The elements of the returned collection are in
401 condition - the condition
403 Returns: the collection of threads
404 *java.util.concurrent.locks.AbstractQueuedSynchronizer.getWaitQueueLength(AbstractQueuedSynchronizer.ConditionObject)*
406 public final int getWaitQueueLength(java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject condition)
408 Returns an estimate of the number of threads waiting on the given condition
409 associated with this synchronizer. Note that because timeouts and interrupts
410 may occur at any time, the estimate serves only as an upper bound on the actual
411 number of waiters. This method is designed for use in monitoring of the system
412 state, not for synchronization control.
414 condition - the condition
416 Returns: the estimated number of waiting threads.
417 *java.util.concurrent.locks.AbstractQueuedSynchronizer.hasContended()*
419 public final boolean hasContended()
421 Queries whether any threads have ever contended to acquire this synchronizer;
422 that is if an acquire method has ever blocked.
424 In this implementation, this operation returns in constant time.
427 Returns: true if there has ever been contention
428 *java.util.concurrent.locks.AbstractQueuedSynchronizer.hasQueuedThreads()*
430 public final boolean hasQueuedThreads()
432 Queries whether any threads are waiting to acquire. Note that because
433 cancellations due to interrupts and timeouts may occur at any time, a true
434 return does not guarantee that any other thread will ever acquire.
436 In this implementation, this operation returns in constant time.
439 Returns: true if there may be other threads waiting to acquire the lock.
440 *java.util.concurrent.locks.AbstractQueuedSynchronizer.hasWaiters(AbstractQueuedSynchronizer.ConditionObject)*
442 public final boolean hasWaiters(java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject condition)
444 Queries whether any threads are waiting on the given condition associated with
445 this synchronizer. Note that because timeouts and interrupts may occur at any
446 time, a true return does not guarantee that a future signal will awaken any
447 threads. This method is designed primarily for use in monitoring of the system
450 condition - the condition
452 Returns: true if there are any waiting threads.
453 *java.util.concurrent.locks.AbstractQueuedSynchronizer.isHeldExclusively()*
455 protected boolean isHeldExclusively()
457 Returns true if synchronization is held exclusively with respect to the current
458 (calling) thread. This method is invoked upon each call to a non-waiting
459 (|java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject|)
460 method. (Waiting methods instead invoke
461 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) .) The default
462 implementation throws (|java.lang.UnsupportedOperationException|) . This method
463 is invoked internally only within
464 (|java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject|)
465 methods, so need not be defined if conditions are not used.
468 Returns: true if synchronization is held exclusively; else false
469 *java.util.concurrent.locks.AbstractQueuedSynchronizer.isQueued(Thread)*
471 public final boolean isQueued(java.lang.Thread thread)
473 Returns true if the given thread is currently queued.
475 This implementation traverses the queue to determine presence of the given
480 Returns: true if the given thread in on the queue
481 *java.util.concurrent.locks.AbstractQueuedSynchronizer.owns(AbstractQueuedSynchronizer.ConditionObject)*
483 public final boolean owns(java.util.concurrent.locks.AbstractQueuedSynchronizer.ConditionObject condition)
485 Queries whether the given ConditionObject uses this synchronizer as its lock.
487 condition - the condition
489 Returns: true if owned
490 *java.util.concurrent.locks.AbstractQueuedSynchronizer.release(int)*
492 public final boolean release(int arg)
494 Releases in exclusive mode. Implemented by unblocking one or more threads if
495 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) returns true. This
496 method can be used to implement method (|java.util.concurrent.locks.Lock|)
498 arg - the release argument. This value is conveyed to {@link #tryRelease} but is
499 otherwise uninterpreted and can represent anything you like.
501 Returns: the value returned from {@link #tryRelease}
502 *java.util.concurrent.locks.AbstractQueuedSynchronizer.releaseShared(int)*
504 public final boolean releaseShared(int arg)
506 Releases in shared mode. Implemented by unblocking one or more threads if
507 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) returns true.
509 arg - the release argument. This value is conveyed to {@link #tryReleaseShared} but
510 is otherwise uninterpreted and can represent anything you like.
512 Returns: the value returned from {@link #tryReleaseShared}
513 *java.util.concurrent.locks.AbstractQueuedSynchronizer.setState(int)*
515 protected final void setState(int newState)
517 Sets the value of synchronization state. This operation has memory semantics of
520 newState - the new state value
522 *java.util.concurrent.locks.AbstractQueuedSynchronizer.toString()*
524 public |java.lang.String| toString()
526 Returns a string identifying this synchronizer, as well as its state. The
527 state, in brackets, includes the String State = followed by the current value
528 of (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , and either
529 nonempty or empty depending on whether the queue is empty.
532 Returns: a string identifying this synchronizer, as well as its state.
533 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquire(int)*
535 protected boolean tryAcquire(int arg)
537 Attempts to acquire in exclusive mode. This method should query if the state of
538 the object permits it to be acquired in the exclusive mode, and if so to
541 This method is always invoked by the thread performing acquire. If this method
542 reports failure, the acquire method may queue the thread, if it is not already
543 queued, until it is signalled by a release from some other thread. This can be
544 used to implement method (|java.util.concurrent.locks.Lock|) .
546 The default implementation throws (|java.lang.UnsupportedOperationException|)
548 arg - the acquire argument. This value is always the one passed to an acquire method,
549 or is the value saved on entry to a condition wait. The value is
550 otherwise uninterpreted and can represent anything you like.
552 Returns: true if successful. Upon success, this object has been acquired.
553 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireNanos(int,long)*
555 public final boolean tryAcquireNanos(
558 throws |java.lang.InterruptedException|
560 Attempts to acquire in exclusive mode, aborting if interrupted, and failing if
561 the given timeout elapses. Implemented by first checking interrupt status, then
562 invoking at least once
563 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , returning on
564 success. Otherwise, the thread is queued, possibly repeatedly blocking and
565 unblocking, invoking (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
566 until success or the thread is interrupted or the timeout elapses. This method
567 can be used to implement method (|java.util.concurrent.locks.Lock|) .
569 arg - the acquire argument. This value is conveyed to {@link #tryAcquire} but is
570 otherwise uninterpreted and can represent anything you like.
571 nanosTimeout - the maximum number of nanoseconds to wait
573 Returns: true if acquired; false if timed out
574 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireShared(int)*
576 protected int tryAcquireShared(int arg)
578 Attempts to acquire in shared mode. This method should query if the state of
579 the object permits it to be acquired in the shared mode, and if so to acquire
582 This method is always invoked by the thread performing acquire. If this method
583 reports failure, the acquire method may queue the thread, if it is not already
584 queued, until it is signalled by a release from some other thread.
586 The default implementation throws (|java.lang.UnsupportedOperationException|)
588 arg - the acquire argument. This value is always the one passed to an acquire method,
589 or is the value saved on entry to a condition wait. The value is
590 otherwise uninterpreted and can represent anything you like.
592 Returns: a negative value on failure, zero on exclusive success, and a positive value if
593 non-exclusively successful, in which case a subsequent waiting
594 thread must check availability. (Support for three different
595 return values enables this method to be used in contexts where
596 acquires only sometimes act exclusively.) Upon success, this
597 object has been acquired.
598 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryAcquireSharedNanos(int,long)*
600 public final boolean tryAcquireSharedNanos(
603 throws |java.lang.InterruptedException|
605 Attempts to acquire in shared mode, aborting if interrupted, and failing if the
606 given timeout elapses. Implemented by first checking interrupt status, then
607 invoking at least once
608 (|java.util.concurrent.locks.AbstractQueuedSynchronizer|) , returning on
609 success. Otherwise, the thread is queued, possibly repeatedly blocking and
610 unblocking, invoking (|java.util.concurrent.locks.AbstractQueuedSynchronizer|)
611 until success or the thread is interrupted or the timeout elapses.
613 arg - the acquire argument. This value is conveyed to {@link #tryAcquireShared} but
614 is otherwise uninterpreted and can represent anything you like.
615 nanosTimeout - the maximum number of nanoseconds to wait
617 Returns: true if acquired; false if timed out
618 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryRelease(int)*
620 protected boolean tryRelease(int arg)
622 Attempts to set the state to reflect a release in exclusive mode. This method
623 is always invoked by the thread performing release.
625 The default implementation throws (|java.lang.UnsupportedOperationException|)
627 arg - the release argument. This value is always the one passed to a release method,
628 or the current state value upon entry to a condition wait. The value is
629 otherwise uninterpreted and can represent anything you like.
631 Returns: true if this object is now in a fully released state, so that any waiting
632 threads may attempt to acquire; and false otherwise.
633 *java.util.concurrent.locks.AbstractQueuedSynchronizer.tryReleaseShared(int)*
635 protected boolean tryReleaseShared(int arg)
637 Attempts to set the state to reflect a release in shared mode. This method is
638 always invoked by the thread performing release. The default implementation
639 throws (|java.lang.UnsupportedOperationException|)
641 arg - the release argument. This value is always the one passed to a release method,
642 or the current state value upon entry to a condition wait. The value is
643 otherwise uninterpreted and can represent anything you like.
645 Returns: true if this object is now in a fully released state, so that any waiting
646 threads may attempt to acquire; and false otherwise.