com.hazelcast.core

Interface ICountDownLatch

All Superinterfaces:

DistributedObject

All Known Implementing Classes:

ClientCountDownLatchProxy, CountDownLatchProxy, RaftCountDownLatchProxy

public interface ICountDownLatch
extends DistributedObject

ICountDownLatch is a backed-up distributed alternative to the java.util.concurrent.CountDownLatch.

ICountDownLatch is a cluster-wide synchronization aid that allows one or more threads to wait until a set of operations being performed in other threads completes.

There are a few differences compared to the java.util.concurrent.CountDownLatch:

1. the ICountDownLatch count can be reset using trySetCount(int) after a countdown has finished but not during an active count. This allows the same latch instance to be reused.
2. There is no await() method to do an unbound wait since this is undesirable in a distributed application: for example, a cluster can split or the master and replicas could all die. In most cases, it is best to configure an explicit timeout so you have the ability to deal with these situations.

As of version 3.12, Hazelcast offers 2 different ICountDownLatch impls. Behaviour of ICountDownLatch under failure scenarios, including network partitions, depend on the impl. The first impl is the one accessed via HazelcastInstance.getCountDownLatch(String). This impl works on top of Hazelcast's async replication algorithm and does not guarantee linearizability during failures. During a split, each partitioned cluster will either create a brand new and uninitialised (zero'd) ICountDownLatch instance, or it will continue to use the primary or backup replica. For example, it is possible for both the primary and backup replicas to be resident in one cluster partition, and for another one to be created as new in the other side of the network partition. In any of these cases, the counter value in the respective ICountDownLatch instance may diverge.

In this impl, when the split heals, Hazelcast performs a default largest cluster wins resolution, or a random winner is chosen where clusters sizes are equal. This can lead to situations where the ICountDownLatch can fall into an unpredictable state, and a countdown to zero may never be achieved.

If required, when using ICountDownLatch as an orchestration mechanism, you should assess the state of the orchestration outcome and the associated countdown actors after a split-brain heal has taken place, and take steps to re-orchestrate if needed.

This ICountDownLatch impl also supports Quorum QuorumConfig in cluster versions 3.10 and higher. However, Hazelcast quorums do not guarantee strong consistency under failure scenarios.

The second ICountDownLatch impl is a new one introduced with the CPSubsystem in version 3.12. It is accessed via CPSubsystem.getCountDownLatch(String). It has a major difference to the old implementation, that is, it works on top of the Raft consensus algorithm. It offers linearizability during crash failures and network partitions. It is CP with respect to the CAP principle. If a network partition occurs, it remains available on at most one side of the partition.

All of the API methods in the new CP ICountDownLatch impl offer the exactly-once execution semantics. For instance, even if a countDown() call is internally retried because of crashed Hazelcast member, the counter value is decremented only once.

Method Summary

Modifier and Type	Method and Description
boolean	await(long timeout, TimeUnit unit) Causes the current thread to wait until the latch has counted down to zero, or an exception is thrown, or the specified waiting time elapses.
void	countDown() Decrements the count of the latch, releasing all waiting threads if the count reaches zero.
int	getCount() Returns the current count.
boolean	trySetCount(int count) Sets the count to the given value if the current count is zero.

Methods inherited from interface com.hazelcast.core.DistributedObject

destroy, getName, getPartitionKey, getServiceName

Method Detail

await

boolean await(long timeout,
              TimeUnit unit)
       throws InterruptedException

Causes the current thread to wait until the latch has counted down to zero, or an exception is thrown, 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 five things happen:

• the count reaches zero due to invocations of the countDown() method,
• this ICountDownLatch instance is destroyed,
• the countdown owner becomes disconnected,
• 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, false if the waiting time elapsed before the count reached zero

Throws:

InterruptedException - if the current thread is interrupted

IllegalStateException - if the Hazelcast instance is shutdown while waiting

NullPointerException - if unit is null

countDown

void countDown()

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:

• All waiting threads are re-enabled for thread scheduling purposes, and
• Countdown owner is set to null.

If the current count equals zero, then nothing happens.

getCount

int getCount()

Returns the current count.

Returns:

the current count

trySetCount

boolean trySetCount(int count)

Sets the count to the given value if the current count is zero.

If count is not zero, then this method does nothing and returns false.

Parameters:

count - the number of times countDown() must be invoked before threads can pass through await(long, java.util.concurrent.TimeUnit)

Returns:

true if the new count was set, false if the current count is not zero

Throws:

IllegalArgumentException - if count is negative