CountDownLatch by example

     Java concurrent package provides CountDownLatch class which helps to control execution of set of threads depends on some external activity. CountDownLatch has two main methods countdown() and await().
     CountDownLatch’s constructor takes an integer as a parameter which decides its behavior. Calling await() holds execution till countdownLatch’s count(constructor parameter) become zero and countdown() reduces the count on every call.
     To explain its use, here is an example of horse race. Here every horse is thread and if you have to stimulate race condition , these threads have to start at a time.  As well as you should know when all complete the race. We can stimulate this functionality using CountDownLatch.

  1: import java.util.*;
  2: import java.util.concurrent.*;
  3: public class TestCountDownLatch 
  4: {
  5:  public static void main(String[] args) throws Exception 
  6:  {
  7:   List<String> horseList = Collections.synchronizedList(
  8:      new ArrayList<String>());
  9:   //all horse threads wait for only one start latch
 10:   CountDownLatch startLatch = new CountDownLatch(1);
 11:   //all horse has to pass end latch , so initiating with no of horses
 12:   CountDownLatch endLatch = new CountDownLatch(5);
 13:   for(int i=0;i<5;i++){
 14:    new HorseThread(String.valueOf(i),
 15:      startLatch, 
 16:      endLatch, 
 17:      horseList).start();
 18:   }
 19:   //Start the race
 20:   startLatch.countDown();
 21:   //wait till a endLatch count is 0 (endLatch.countDown() called 5 times)
 22:   endLatch.await();
 23:   System.out.println("First position Horse is Horse No " + 
 24:      horseList.get(0));
 25:   System.out.println("Second position Horse is Horse No " + 
 26:      horseList.get(1));
 27:  }
 28: }
 29: 
 30: class HorseThread extends Thread
 31: {
 32:  private String horseId;
 33:  private CountDownLatch startLatch, endLatch;
 34:  List<String> list;
 35: 
 36:  public HorseThread(String horseId, 
 37:     CountDownLatch startLatch, 
 38:     CountDownLatch endLatch, 
 39:     List<String> list){
 40:   this.horseId = horseId;
 41:   this.startLatch = startLatch;
 42:   this.endLatch = endLatch;
 43:   this.list = list;
 44:  }
 45: 
 46:  public void run(){
 47:   try{
 48:    //wait till start latch opened
 49:    startLatch.await();
 50:    sleep(new Random().nextInt(10)*100);
 51:    //notify race end crossed,endLatch decrease count;
 52:    endLatch.countDown();
 53:    list.add(horseId);
 54:    //System.out.println("Horse "+horseId +" has completed.");
 55:   } catch(Exception exp){ 
 56:    exp.printStackTrace(); 
 57:   }
 58:  }
 59: }

        This program call await() on startLatch at starting of run method and countdown() on endLatch at the end to notify end of race. Countdown() is called on startLatch as soon as all threads are started and ready to run.
Once startLatch.countdown() is called all threads start running (As we have initialized startLatch with 1, only one call to countdown() make internal count to zero and all waiting  threads start executing).
endLatch.await() is called before printing results, so it waits for all horses (threads in this example) to complete race.

Output :

---------- java ----------
First position Horse is Horse No 1
Second position Horse is Horse No 4

Output completed (1 sec consumed)
Reference: http://www.ibm.com/developerworks/java/library/j-5things5.html?ca=drs-