javafixes.concurrency

Class ReusableCountLatch

java.lang.Object

javafixes.concurrency.ReusableCountLatch

public class ReusableCountLatch
extends java.lang.Object

A synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes.

A ReusableCountLatch is initialized with a given count. The waitTillZero() methods block until the current count reaches zero due to invocations of the decrement() method, after which all waiting threads are released. If zero has been reached any subsequent invocations of waitTillZero() return immediately. The coun cen be increased calling the increment() method and any subsequent thread calling the waitTillZero() method will be block again until another zero is reached.

ReusableCountLatch provides more versatility than CountDownLatch as the count doesn't have to be known upfront and you can reuse this class as many times as you want to. It is also better than a Phaser whose count is limited to 65_535. ReusableCountLatch instead can count up to 2_147_483_647 (2^31-1).

Great use case for ReusableCountLatch is when you wait for tasks on other threads to finish, but these tasks could trigger more tasks and it is not know upfront how many will be triggered in total. To simplify this scenario even further take a look at our implementations of Runner of MonitoringTaskSubmitter.

Since:

07/10/16 00:10 AM

Constructor Summary

Constructors

Constructor and Description
ReusableCountLatch() Constructs a ReusableCountLatch with initial count set to 0.
ReusableCountLatch(int initialCount) Constructs a ReusableCountLatch initialized with the given count.

Method Summary

Modifier and Type	Method and Description
void	decrement() Decrements the count of the latch, releasing all waiting threads if the count reaches zero.
int	getCount() Returns the current count.
void	increment() Increments the count of the latch, which will make it possible to block all threads waiting till count reaches zero.
void	waitTillZero() Causes the current thread to wait until the latch has counted down to zero, unless the thread is interrupted.
boolean	waitTillZero(long timeout, java.util.concurrent.TimeUnit unit) Causes the current thread to wait until the latch has counted down to zero, unless the thread is interrupted, or the specified waiting time elapses.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ReusableCountLatch

public ReusableCountLatch(int initialCount)

Constructs a ReusableCountLatch initialized with the given count.

Parameters:

initialCount - the number of times decrement() must be invoked before threads can pass through waitTillZero(). For each additional call of the increment() method one more decrement() must be called.

Throws:

java.lang.IllegalArgumentException - if initialCount is negative

ReusableCountLatch

public ReusableCountLatch()

Constructs a ReusableCountLatch with initial count set to 0.

Method Detail

getCount

public int getCount()

Returns the current count.

Returns:

the current count

decrement

public void decrement()

Decrements the count of the latch, releasing all waiting threads if the count reaches zero.

If the current count is greater than zero then it is decremented. If the new count is zero then all waiting threads are re-enabled for thread scheduling purposes.

If the current count equals zero then nothing happens.

increment

public void increment()

Increments the count of the latch, which will make it possible to block all threads waiting till count reaches zero.

waitTillZero

public void waitTillZero()
                  throws java.lang.InterruptedException

Causes the current thread to wait until the latch has counted down to zero, unless the thread is interrupted.

If the current count is zero then this method returns immediately.

If the current count is greater than zero then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happen:

• The count reaches zero due to invocations of the decrement() method; or
• Some other thread interrupts the current thread.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting

waitTillZero

public boolean waitTillZero(long timeout,
                            java.util.concurrent.TimeUnit unit)
                     throws java.lang.InterruptedException

Causes the current thread to wait until the latch has counted down to zero, unless the thread is interrupted, or the specified waiting time elapses.

If the current count is zero then this method returns immediately with the value true.

If the current count is greater than zero then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happen:

• The count reaches zero due to invocations of the decrement() method; or
• Some other thread interrupts the current thread; or
• The specified waiting time elapses.

If the count reaches zero then the method returns with the value true.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

true if the count reached zero and false if the waiting time elapsed before the count reached zero

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting