com.hazelcast.core

## Interface ICountDownLatch

- All Superinterfaces:
    DistributedObject
  All Known Implementing Classes:
    ClientCountDownLatchProxy, CountDownLatchProxy

      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 `ICountDownLatch`:

  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.
  Behaviour of `ICountDownLatch` under split-brain scenarios should be taken into account when using this data structure. During a split, each partitioned cluster will either create a brand new and uninitialised (zero'd) `ICountDownLatch` or it will continue to use the primary or back-up version. For example it may be possible for both the back-up and primary to be resident in one cluster partition and for another to be created as new in another side. In any of these cases the counter in the respective `ICountDownLatch` may diverge.

  When the split heals, Hazelcast performs a default largest cluster wins resolution or where clusters sizes are equal a random winner is chosen. This can lead to situations where the is left in 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 appropriate. Supports Quorum `QuorumConfig` since 3.10 in cluster versions 3.10 and higher.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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

Copyright © 2018. All rights reserved.