Latch API in Java : CountDownLatch

Literally, latch means a device for keeping a door or gate closed.  Its meaning is analogous to a gate in Java as well. So if latch (gate) is open, everyone can pass through it but when it's shut, no one is allowed to cross over. With this as background let's go in detail:

It's one of the advanced threading/concurrency concepts of Java. Java provides a Latch API named as  CountDownLatch which got introduced in Java 5 ( java.util.concurrent package). So now on; I will refer Latch and CountDownLatch interchangeably to refer to the same thing. Latch is a synchronizer that can delay the progress of threads until it reaches its terminal state. [A synchronizer is any object that coordinates the control flow of threads based on its state] So it is used to synchronize one or more tasks by forcing them to wait for the completion of a set of operation being performed by other tasks.

CountDownLatch in action

Let me start directly with a simple example to stress on the fundamentals of this API. Below sample program has two tasks (as taskone() and tasktwo()) represented as methods. And I want to make sure that taskone() should get completed before tasktwo(). 

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;

public class CountDownLatchTest {
 static CountDownLatch latch;

 CountDownLatchTest(final int count) {
  latch = new CountDownLatch(count);
 }

 public void firstTask() {
  Runnable s1 = new Runnable() {
   public void run() {
    try {
         System.out.println("waiting....");
         TimeUnit.SECONDS.sleep(5);
    } catch (InterruptedException e) {
         e.printStackTrace();
    }
    // finish first activity before last line
    latch.countDown();
   }
  };
  Thread t = new Thread(s1);
  t.start();
 }

 public void secondTask() {
  Runnable s2 = new Runnable() {
   public void run() {
    try {
         System.out.println("wait....");
         latch.await();
         // perform task here
         System.out.println("after wait.... done");
    } catch (InterruptedException e1) {
         e1.printStackTrace();
    }
   }
  };
  Thread t = new Thread(s2);
  t.start();
 }

 public static void main(String[] args) throws InterruptedException {
  CountDownLatchTest cdlt = new CountDownLatchTest(1);
  cdlt.secondTask();
  TimeUnit.SECONDS.sleep(5);
  cdlt.firstTask();
 }
}

 Output:

 wait....
waiting....
after wait.... done

Above example shows CountDownLatch attribute getting initialized to a value of 1 through constructor. Two tasks in above example are synchronized though CountDownLatch. Task2 i.e. secondTask() should wait for completion of Task1 i.e. firstTask(). Run above example and notice the sequence in which output appears on the console. 

Please note few important points

1. Any task that calls await() on the object will block until the count reaches zero or it's interrupted by another thread. secondTask() gets blocked after call to await(); evident from output.
2. Call countDown() on the object to reduce the count. The task that call countDown() are not blocked.  This cal signals the end of the task. This method need to be called at the end of the task.
3. As soon as count reaches zero; threads awaiting starts running. 
4. The value of count which is passed during creation of latch object is very important. It should be same as the number of task which needs to be finished first. If count is 5 then first task should be called five times to make sure that count has reduced to 0.
5. You can also use wait and notify mechanism of Java to achieve the same behavior but code will become quite complicated. 
6. One of the disadvantage of CountDownLatch is that its not reusable once count reaches to zero. But Java provides another concurrency API called CyclicBarrier for such cases. 

Usage of CountDownLatch

1. Use this when your current executing thread/main thread needs to wait for the completion of other dependent activities. 
2. Ensure that a service doesn't start until other services on which it depends have not completed.
3. In a multi-player game like RoadRash; wait for all players to get ready to start the race. 

---
do post your comments/questions !!!