CountDownLatch

class CountDownLatch(context, group_id, service_name, proxy_name, object_name)

Bases: hazelcast.proxy.cp.BaseCPProxy

A distributed, concurrent countdown latch data structure.

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

CountDownLatch count can be reset using try_set_count() method after a countdown has finished but not during an active count. This allows the same latch instance to be reused.

There is no await_latch() 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.

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

await_latch(timeout)

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 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 the following things happen:

  • The count reaches zero due to invocations of the count_down() method

  • This CountDownLatch instance is destroyed

  • The countdown owner becomes disconnected

  • The specified waiting time elapses

If the count reaches zero, then the method returns with the value True.

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 (int) – The maximum time to wait in seconds

Returns

True if the count reached zero,

False if the waiting time elapsed before the count reached zero

Return type

hazelcast.future.Future[bool]

Raises

IllegalStateError – If the Hazelcast instance was shut down while waiting.

count_down()

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

  • Countdown owner is set to None.

If the current count equals zero, then nothing happens.

Returns

Return type

hazelcast.future.Future[None]

get_count()

Returns the current count.

Returns

The current count.

Return type

hazelcast.future.Future[int]

try_set_count(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 (int) – The number of times count_down() must be invoked before callers can pass through await_latch().

Returns

True if the new count was set,

False if the current count is not zero.

Return type

hazelcast.future.Future[bool]