package java.util.concurrent; /** * A CountDownLatch allows one set of threads to wait until * the actions of another set of threads allow the first set to proceed. *

A CountDownLatch is initialized with a given count. * The {@link #await} methods block until the current {@link #getCount count} * reaches zero due to invocations of the {@link #countDown} method, * after which all waiting threads are * released and any subsequent invocations of {@link #await} return * immediately. This is a one-shot phenomenon -- the count * cannot be reset. If you need a version that resets the count, * consider using a {@link CyclicBarrier}. * *

A CountDownLatch is a versatile synchronization tool * and can be used for a number of purposes. * A CountDownLatch initialized to one serves as a simple on/off * latch, or gate: all threads invoking {@link #await} wait at the gate until * it is opened by a thread invoking {@link #countDown}. * A CountDownLatch initialized to N can be used to make * one thread wait until N threads have completed some action. * A useful property of a CountDownLatch is that it doesn't * require that all threads wait before any can proceed, it simply * prevents any thread from proceeding past the {@link #await wait} until * all threads could pass. * *

Sample usage: Here is a pair of classes in which a group * of worker threads use two countdown latches: *

The first is a start signal that prevents any worker from proceeding * until the driver is ready for them to proceed; *
The second is a completion signal that allows the driver to wait * until all workers have completed. *

* *

 * class Driver { // ...
 *   void main() throws InterruptedException {
 *     CountDownLatch startSignal = new CountDownLatch(1);
 *     CountDownLatch doneSignal = new CountDownLatch(N);
 *
 *     for (int i = 0; i < N; ++i) // create and start threads
 *       new Thread(new Worker(startSignal, doneSignal)).start();
 *
 *     doSomethingElse();            // don't let run yet
 *     startSignal.countDown();      // let all threads proceed
 *     doSomethingElse();
 *     doneSignal.await();           // wait for all to finish
 *   }
 * }
 *
 * class Worker implements Runnable {
 *   private final CountDownLatch startSignal;
 *   private final CountDownLatch doneSignal;
 *   Worker(CountDownLatch startSignal, CountDownLatch doneSignal) {
 *      this.startSignal = startSignal;
 *      this.doneSignal = doneSignal;
 *   }
 *   public void run() {
 *      try {
 *        startSignal.await();
 *        doWork();
 *        doneSignal.countDown();
 *      }
 *      catch (InterruptedException ex) {} // return;
 *   }
 *
 *   void doWork() { ... }
 * }
 *
 *

* * @since 1.5 * @spec JSR-166 * @revised $Date: 2003/05/14 21:30:46 $ * @editor $Author: tim $ */ public class CountDownLatch { /** * Constructs a CountDownLatch initialized with the given * count. * * @param count the number of times {@link #countDown} must be invoked * before threads can pass through {@link #await}. * * @throws IllegalArgumentException if count is less than one. */ public CountDownLatch(int count) {} /** * Causes the current thread to wait until the latch has counted down to * zero, unless the thread is {@link Thread#interrupt interrupted}. * *

If the current {@link #getCount count} is zero then this method * returns immediately. *

If the current {@link #getCount count} is greater than zero then * the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of two things happen: *

The count reaches zero due to invocations of the * {@link #countDown} method; or *
Some other thread {@link Thread#interrupt interrupts} the current * thread. *

If the current thread: *

has its interrupted status set on entry to this method; or *
is {@link Thread#interrupt interrupted} while waiting, *

* then {@link InterruptedException} is thrown and the current thread's * interrupted status is cleared. * * @throws InterruptedException if the current thread is interrupted * while waiting. */ public void await() throws InterruptedException {} /** * Causes the current thread to wait until the latch has counted down to * zero, unless the thread is {@link Thread#interrupt interrupted}, * or the specified waiting time elapses. * *

If the current {@link #getCount count} is zero then this method * returns immediately with the value true. * *

If the current {@link #getCount count} is greater than zero then * the current thread becomes disabled for thread scheduling * purposes and lies dormant until one of three things happen: *

The count reaches zero due to invocations of the * {@link #countDown} method; or *
Some other thread {@link Thread#interrupt 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 {@link Thread#interrupt interrupted} while waiting, *

* then {@link InterruptedException} is thrown and the current thread's * interrupted status is cleared. * *

If the specified waiting time elapses then the value false * is returned. * The given waiting time is a best-effort lower bound. If the time is * less than or equal to zero, the method will not wait at all. * * @param timeout the maximum time to wait * @param granularity the time unit of the timeout argument. * @return true if the count reached zero and false * if the waiting time elapsed before the count reached zero. * * @throws InterruptedException if the current thread is interrupted * while waiting. */ public boolean await(long timeout, TimeUnit granularity) throws InterruptedException { return false; } /** * Decrements the count of the latch, releasing all waiting threads if * the count reaches zero. *

If the current {@link #getCount count} is greater than zero then * it is decremented. If the new count is zero then all waiting threads * are re-enabled for thread scheduling purposes. *

If the current {@link #getCount count} equals zero then nothing * happens. */ public void countDown() {} /** * Returns the current count. *

This method is typically used for debugging and testing purposes. * @return the current count. */ public long getCount() { return 0; } }