public class UpAndDownLatch extends Object implements Awaitable
sync.WaitGroup. Code
can both add and subtract references from the latch. Awaiting the latch will return when the
count of references reaches zero. Unlike a CountDownLatch, this can be re-used after it
reaches zero by simply adding one or more references. Subsequent attempts to await will block
until the count reaches zero again.
The count of references cannot be negative. Operations that would cause this condition will
throw an IllegalStateException. Similarly, the count of references cannot exceed
Integer.MAX_VALUE, and operations that would cause this condition will also throw.
This latch has qualities similar to a Phaser, but is much simpler. These latches
cannot be grouped into trees (for handling huge numbers of references), and they do not track
"phases" or "generations". Awaiting the latch just waits for it to become zero, essentially for
references to "quiesce". It is not possible to wait for a particular phase to end. For example,
if one thread queries the count, sees a positive number, and then awaits the latch, it could be
awaiting a subsequent phase. This can happen if, concurrently, the count reached zero and then
another reference was added, all in-between the other thread's observing the count and initiating
an await operation.
Memory consistency effects: things that occur in a thread before a call to countUp()
or countDown() happen before any actions on a thread after a subsequent return
from a successful await operation. Similarly, things that happen in a thread before calls to
countDown() that result in the count reaching zero happen before any actions
after a subsequent call to countUp() that returns true (e.g. when the count becomes
non-zero). Vice versa is also true: things that happen in a thread prior to calls to
countUp() happen before actions on another thread after a subsequent call to
countDown() that returns true (e.g. when the count returns to zero).
| Constructor and Description |
|---|
UpAndDownLatch()
Constructs a new latch that has zero references.
|
UpAndDownLatch(int count)
Constructs a new latch that has the given number of initial references.
|
| Modifier and Type | Method and Description |
|---|---|
void |
await()
Waits for the number of references to reach zero.
|
boolean |
await(long limit,
TimeUnit unit)
Waits up to specified amount of time for the number of references to reach zero.
|
boolean |
countDown()
Removes a single reference from the latch.
|
boolean |
countDown(int count)
Removes the given number of single references from the latch.
|
boolean |
countUp()
Adds a single reference to the latch.
|
boolean |
countUp(int count)
Adds the given number of references to the latch.
|
int |
getCount()
Returns the current number of references.
|
boolean |
isDone()
Returns true if the event has occurred.
|
String |
toString() |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitawaitUninterruptibly, awaitUninterruptibly, fromCondition, fromFuture, fromIntrinsic, fromLatch, fromTerminatingExecutorpublic UpAndDownLatch()
countUp() to
add references.public UpAndDownLatch(int count)
IllegalArgumentException - if the given count is negativepublic boolean countUp()
IllegalStateException - if adding a reference would cause the count of latches to
overflow (e.g. exceed Integer.MAX_VALUE)public boolean countUp(int count)
If a negative number is provided, this acts like countDown(), removing references,
but its return value would always be false in this case.
IllegalStateException - if adding the given number of references would cause the count
of latches to overflow (e.g. exceed Integer.MAX_VALUE)public boolean countDown()
IllegalStateException - if the latch has no referencespublic boolean countDown(int count)
If a negative number is provided, this acts like countUp(), adding references,
but its return value would always be false in this case.
IllegalStateException - if the latch has fewer references than the given countpublic int getCount()
public boolean isDone()
Awaitablepublic void await()
throws InterruptedException
await in interface AwaitableInterruptedException - if this thread is interrupted while waitingpublic boolean await(long limit,
TimeUnit unit)
throws InterruptedException
await in interface Awaitablelimit - the maximum amount of time to waitunit - the unit of limitInterruptedException - if this thread is interrupted while waiting