Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Concurrency

The CountDownLatch class

Reference for java.util.concurrent.CountDownLatch: a one-shot latch that lets threads wait until a count reaches zero, with timeouts and common pitfalls.

CountDownLatch is a synchronizer that holds a counter. Threads call await() and block until the counter reaches zero; other threads (or the same ones) call countDown() to decrement it. When the count hits zero, every waiting thread is released at once and any later await() returns immediately.

A latch is one-shot: the count can never be reset. Use it for "wait until N things have happened", such as waiting for workers to finish, or for a "start gun" where many threads wait for a single countDown(). If you need something reusable, look at CyclicBarrier or Phaser.

Java
CountDownLatch done = new CountDownLatch(3);
// in each worker:  done.countDown();
done.await();   // returns after three countDown() calls

Try it

Java Wait for three workers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Start gun and timeout

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public class CountDownLatch {
    public CountDownLatch(int count)
    public void await() throws InterruptedException
    public boolean await(long timeout, TimeUnit unit) throws InterruptedException
    public void countDown()
    public long getCount()
}
Member Description
CountDownLatch(int count) Creates a latch with the given initial count. Throws IllegalArgumentException if count is negative. A count of 0 is allowed and means "already open".
await() Blocks until the count is zero or the thread is interrupted. Returns immediately if the count is already zero.
await(long, TimeUnit) Like await() but gives up after the timeout. Returns true if the count reached zero, false if the time ran out.
countDown() Decrements the count; releases all waiters when it reaches zero. Does nothing if the count is already zero.
getCount() Current count. Meant for debugging and tests, not for control flow.

Throws: both await methods throw InterruptedException if the waiting thread is interrupted.

Usage notes

  • Call countDown() in a finally block. If a worker throws before counting down, the waiting thread blocks forever (or until its timeout).
  • Happens-before: actions in a thread before countDown() are visible to the thread that returns from await(). That is why plain results written by workers can be read safely after the latch opens, as long as each result slot is written by one thread.
  • Not reusable. There is no reset(). Create a new latch for each round, or use CyclicBarrier/Phaser.
  • Prefer a timeout in production code so a missed countDown() becomes a visible failure rather than a hang.
  • Executors: when you already have Futures, invokeAll() or close() on an executor can replace a latch. Latches shine when the "events" are not whole tasks.
  • Not a lock. Releasing the latch does not give any thread exclusive access to anything.
  • The count is an int in the constructor, but getCount() returns a long.