util/concurrent/CountDownLatch.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;
import java.util.concurrent.locks.*;

/**
 * A synchronization aid that allows one or more threads to wait until
 * a set of operations being performed in other threads completes.
 *
 * <p>A <tt>CountDownLatch</tt> is initialized with a given
 * <em>count</em>.  The {@link #await 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 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}.
 *
 * <p>A <tt>CountDownLatch</tt> is a versatile synchronization tool
 * and can be used for a number of purposes.  A
 * <tt>CountDownLatch</tt> initialized with a count of one serves as a
 * simple on/off latch, or gate: all threads invoking {@link #await await}
 * wait at the gate until it is opened by a thread invoking {@link
 * #countDown}.  A <tt>CountDownLatch</tt> initialized to <em>N</em>
 * can be used to make one thread wait until <em>N</em> threads have
 * completed some action, or some action has been completed N times.
 * <p>A useful property of a <tt>CountDownLatch</tt> is that it
 * doesn't require that threads calling <tt>countDown</tt> wait for
 * the count to reach zero before proceeding, it simply prevents any
 * thread from proceeding past an {@link #await await} until all
 * threads could pass.
 *
 * <p><b>Sample usage:</b> Here is a pair of classes in which a group
 * of worker threads use two countdown latches:
 * <ul>
 * <li>The first is a start signal that prevents any worker from proceeding
 * until the driver is ready for them to proceed;
 * <li>The second is a completion signal that allows the driver to wait
 * until all workers have completed.
 * </ul>
 *
 * <pre>
 * 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() { ... }
 * }
 *
 * </pre>
 *
 * <p>Another typical usage would be to divide a problem into N parts,
 * describe each part with a Runnable that executes that portion and
 * counts down on the latch, and queue all the Runnables to an
 * Executor.  When all sub-parts are complete, the coordinating thread
 * will be able to pass through await.
 *
 * <pre>
 * class Driver2 { // ...
 *   void main() throws InterruptedException {
 *     CountDownLatch doneSignal = new CountDownLatch(N);
 *     Executor e = ...
 *
 *     for (int i = 0; i < N; ++i) // create and start threads
 *       e.execute(new WorkerRunnable(doneSignal, i));
 *
 *     doneSignal.await();           // wait for all to finish
 *   }
 * }
 *
 * class WorkerRunnable implements Runnable {
 *   private final CountDownLatch doneSignal;
 *   private final int i;
 *   Worker(CountDownLatch doneSignal, int i) {
 *      this.doneSignal = doneSignal;
 *      this.i = i;
 *   }
 *   public void run() {
 *      try {
 *        doWork(i);
 *        doneSignal.countDown();
 *      } catch (InterruptedException ex) {} // return;
 *   }
 *
 *   void doWork() { ... }
 * }
 *
 * </pre>
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/08/25 22:28:11 $
 * @editor $Author: dholmes $
 * @author Doug Lea
 */
public class CountDownLatch {
    private final ReentrantLock lock = new ReentrantLock();
    private final Condition zero = lock.newCondition();
    private int count;

    /**
     * Constructs a <tt>CountDownLatch</tt> 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 <tt>count</tt> is less than zero.
     */
    public CountDownLatch(int count) { 
        if (count < 0) throw new IllegalArgumentException("count < 0");
        this.count = count; 
    }

    /**
     * Causes the current thread to wait until the latch has counted down to 
     * zero, unless the thread is {@link Thread#interrupt interrupted}.
     *
     * <p>If the current {@link #getCount count} is zero then this method
     * returns immediately.
     * <p>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:
     * <ul>
     * <li>The count reaches zero due to invocations of the
     * {@link #countDown} method; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread.
     * </ul>
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or 
     * <li>is {@link Thread#interrupt interrupted} while waiting, 
     * </ul>
     * 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 {
        lock.lock();
        try {
            while (count != 0)
                zero.await();
        } finally {
            lock.unlock();
        }
    }


    /**
     * 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.
     *
     * <p>If the current {@link #getCount count} is zero then this method
     * returns immediately with the value <tt>true</tt>.
     *
     * <p>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:
     * <ul>
     * <li>The count reaches zero due to invocations of the
     * {@link #countDown} method; or
     * <li>Some other thread {@link Thread#interrupt interrupts} the current
     * thread; or
     * <li>The specified waiting time elapses.
     * </ul>
     * <p>If the count reaches zero then the method returns with the
     * value <tt>true</tt>.
     * <p>If the current thread:
     * <ul>
     * <li>has its interrupted status set on entry to this method; or 
     * <li>is {@link Thread#interrupt interrupted} while waiting, 
     * </ul>
     * then {@link InterruptedException} is thrown and the current thread's 
     * interrupted status is cleared. 
     *
     * <p>If the specified waiting time elapses then the value <tt>false</tt>
     * is returned.
     * 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 unit the time unit of the <tt>timeout</tt> argument.
     * @return <tt>true</tt> if the count reached zero  and <tt>false</tt>
     * 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 unit) 
        throws InterruptedException {
        long nanos = unit.toNanos(timeout);
        lock.lock();
        try {
            for (;;) {
                if (count == 0)
                    return true;
                nanos = zero.awaitNanos(nanos);
                if (nanos <= 0)
                    return false;
            }
        } finally {
            lock.unlock();
        }
    }


    /**
     * Decrements the count of the latch, releasing all waiting threads if
     * the count reaches zero.
     * <p>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.
     * <p>If the current {@link #getCount count} equals zero then nothing
     * happens.
     */
    public void countDown() {
        lock.lock();
        try {
            if (count > 0 && --count == 0)
                zero.signalAll();
        } finally {
            lock.unlock();
        }
    }

    /**
     * Returns the current count.
     * <p>This method is typically used for debugging and testing purposes.
     * @return the current count.
     */
    public long getCount() {
        lock.lock();
        try {
            return count;
        } finally {
            lock.unlock();
        }
    }
}
Revision:	1.10
Committed:	Tue Aug 26 00:09:18 2003 UTC (20 years, 9 months ago) by dholmes
Branch:	MAIN
Changes since 1.9:	+3 -3 lines
Log Message:	In response to Eamonn's comment that "best effort lower bound" is not defined for waiting times, all such references have been deleted. The preceding text makes it clear that the time must elapse before the method will return, and trying to say anything about the maximum waiting time is pointless. We can still say something to this effect in the package docs if we want.
#	Content
1	/*
2	* Written by Doug Lea with assistance from members of JCP JSR-166
3	* Expert Group and released to the public domain. Use, modify, and
4	* redistribute this code in any way without acknowledgement.
5	*/
6
7	package java.util.concurrent;
8	import java.util.concurrent.locks.*;
9
10	/**
11	* A synchronization aid that allows one or more threads to wait until
12	* a set of operations being performed in other threads completes.
13	*
14	* <p>A <tt>CountDownLatch</tt> is initialized with a given
15	* <em>count</em>. The {@link #await await} methods block until the current
16	* {@link #getCount count} reaches zero due to invocations of the
17	* {@link #countDown} method, after which all waiting threads are
18	* released and any subsequent invocations of {@link #await await} return
19	* immediately. This is a one-shot phenomenon -- the count cannot be
20	* reset. If you need a version that resets the count, consider using
21	* a {@link CyclicBarrier}.
22	*
23	* <p>A <tt>CountDownLatch</tt> is a versatile synchronization tool
24	* and can be used for a number of purposes. A
25	* <tt>CountDownLatch</tt> initialized with a count of one serves as a
26	* simple on/off latch, or gate: all threads invoking {@link #await await}
27	* wait at the gate until it is opened by a thread invoking {@link
28	* #countDown}. A <tt>CountDownLatch</tt> initialized to <em>N</em>
29	* can be used to make one thread wait until <em>N</em> threads have
30	* completed some action, or some action has been completed N times.
31	* <p>A useful property of a <tt>CountDownLatch</tt> is that it
32	* doesn't require that threads calling <tt>countDown</tt> wait for
33	* the count to reach zero before proceeding, it simply prevents any
34	* thread from proceeding past an {@link #await await} until all
35	* threads could pass.
36	*
37	* <p><b>Sample usage:</b> Here is a pair of classes in which a group
38	* of worker threads use two countdown latches:
39	* <ul>
40	* <li>The first is a start signal that prevents any worker from proceeding
41	* until the driver is ready for them to proceed;
42	* <li>The second is a completion signal that allows the driver to wait
43	* until all workers have completed.
44	* </ul>
45	*
46	* <pre>
47	* class Driver { // ...
48	* void main() throws InterruptedException {
49	* CountDownLatch startSignal = new CountDownLatch(1);
50	* CountDownLatch doneSignal = new CountDownLatch(N);
51	*
52	* for (int i = 0; i < N; ++i) // create and start threads
53	* new Thread(new Worker(startSignal, doneSignal)).start();
54	*
55	* doSomethingElse(); // don't let run yet
56	* startSignal.countDown(); // let all threads proceed
57	* doSomethingElse();
58	* doneSignal.await(); // wait for all to finish
59	* }
60	* }
61	*
62	* class Worker implements Runnable {
63	* private final CountDownLatch startSignal;
64	* private final CountDownLatch doneSignal;
65	* Worker(CountDownLatch startSignal, CountDownLatch doneSignal) {
66	* this.startSignal = startSignal;
67	* this.doneSignal = doneSignal;
68	* }
69	* public void run() {
70	* try {
71	* startSignal.await();
72	* doWork();
73	* doneSignal.countDown();
74	* } catch (InterruptedException ex) {} // return;
75	* }
76	*
77	* void doWork() { ... }
78	* }
79	*
80	* </pre>
81	*
82	* <p>Another typical usage would be to divide a problem into N parts,
83	* describe each part with a Runnable that executes that portion and
84	* counts down on the latch, and queue all the Runnables to an
85	* Executor. When all sub-parts are complete, the coordinating thread
86	* will be able to pass through await.
87	*
88	* <pre>
89	* class Driver2 { // ...
90	* void main() throws InterruptedException {
91	* CountDownLatch doneSignal = new CountDownLatch(N);
92	* Executor e = ...
93	*
94	* for (int i = 0; i < N; ++i) // create and start threads
95	* e.execute(new WorkerRunnable(doneSignal, i));
96	*
97	* doneSignal.await(); // wait for all to finish
98	* }
99	* }
100	*
101	* class WorkerRunnable implements Runnable {
102	* private final CountDownLatch doneSignal;
103	* private final int i;
104	* Worker(CountDownLatch doneSignal, int i) {
105	* this.doneSignal = doneSignal;
106	* this.i = i;
107	* }
108	* public void run() {
109	* try {
110	* doWork(i);
111	* doneSignal.countDown();
112	* } catch (InterruptedException ex) {} // return;
113	* }
114	*
115	* void doWork() { ... }
116	* }
117	*
118	* </pre>
119	*
120	* @since 1.5
121	* @spec JSR-166
122	* @revised $Date: 2003/08/25 22:28:11 $
123	* @editor $Author: dholmes $
124	* @author Doug Lea
125	*/
126	public class CountDownLatch {
127	private final ReentrantLock lock = new ReentrantLock();
128	private final Condition zero = lock.newCondition();
129	private int count;
130
131	/**
132	* Constructs a <tt>CountDownLatch</tt> initialized with the given
133	* count.
134	*
135	* @param count the number of times {@link #countDown} must be invoked
136	* before threads can pass through {@link #await}.
137	*
138	* @throws IllegalArgumentException if <tt>count</tt> is less than zero.
139	*/
140	public CountDownLatch(int count) {
141	if (count < 0) throw new IllegalArgumentException("count < 0");
142	this.count = count;
143	}
144
145	/**
146	* Causes the current thread to wait until the latch has counted down to
147	* zero, unless the thread is {@link Thread#interrupt interrupted}.
148	*
149	* <p>If the current {@link #getCount count} is zero then this method
150	* returns immediately.
151	* <p>If the current {@link #getCount count} is greater than zero then
152	* the current thread becomes disabled for thread scheduling
153	* purposes and lies dormant until one of two things happen:
154	* <ul>
155	* <li>The count reaches zero due to invocations of the
156	* {@link #countDown} method; or
157	* <li>Some other thread {@link Thread#interrupt interrupts} the current
158	* thread.
159	* </ul>
160	* <p>If the current thread:
161	* <ul>
162	* <li>has its interrupted status set on entry to this method; or
163	* <li>is {@link Thread#interrupt interrupted} while waiting,
164	* </ul>
165	* then {@link InterruptedException} is thrown and the current thread's
166	* interrupted status is cleared.
167	*
168	* @throws InterruptedException if the current thread is interrupted
169	* while waiting.
170	*/
171	public void await() throws InterruptedException {
172	lock.lock();
173	try {
174	while (count != 0)
175	zero.await();
176	} finally {
177	lock.unlock();
178	}
179	}
180
181
182	/**
183	* Causes the current thread to wait until the latch has counted down to
184	* zero, unless the thread is {@link Thread#interrupt interrupted},
185	* or the specified waiting time elapses.
186	*
187	* <p>If the current {@link #getCount count} is zero then this method
188	* returns immediately with the value <tt>true</tt>.
189	*
190	* <p>If the current {@link #getCount count} is greater than zero then
191	* the current thread becomes disabled for thread scheduling
192	* purposes and lies dormant until one of three things happen:
193	* <ul>
194	* <li>The count reaches zero due to invocations of the
195	* {@link #countDown} method; or
196	* <li>Some other thread {@link Thread#interrupt interrupts} the current
197	* thread; or
198	* <li>The specified waiting time elapses.
199	* </ul>
200	* <p>If the count reaches zero then the method returns with the
201	* value <tt>true</tt>.
202	* <p>If the current thread:
203	* <ul>
204	* <li>has its interrupted status set on entry to this method; or
205	* <li>is {@link Thread#interrupt interrupted} while waiting,
206	* </ul>
207	* then {@link InterruptedException} is thrown and the current thread's
208	* interrupted status is cleared.
209	*
210	* <p>If the specified waiting time elapses then the value <tt>false</tt>
211	* is returned.
212	* If the time is
213	* less than or equal to zero, the method will not wait at all.
214	*
215	* @param timeout the maximum time to wait
216	* @param unit the time unit of the <tt>timeout</tt> argument.
217	* @return <tt>true</tt> if the count reached zero and <tt>false</tt>
218	* if the waiting time elapsed before the count reached zero.
219	*
220	* @throws InterruptedException if the current thread is interrupted
221	* while waiting.
222	*/
223	public boolean await(long timeout, TimeUnit unit)
224	throws InterruptedException {
225	long nanos = unit.toNanos(timeout);
226	lock.lock();
227	try {
228	for (;;) {
229	if (count == 0)
230	return true;
231	nanos = zero.awaitNanos(nanos);
232	if (nanos <= 0)
233	return false;
234	}
235	} finally {
236	lock.unlock();
237	}
238	}
239
240
241
242	/**
243	* Decrements the count of the latch, releasing all waiting threads if
244	* the count reaches zero.
245	* <p>If the current {@link #getCount count} is greater than zero then
246	* it is decremented. If the new count is zero then all waiting threads
247	* are re-enabled for thread scheduling purposes.
248	* <p>If the current {@link #getCount count} equals zero then nothing
249	* happens.
250	*/
251	public void countDown() {
252	lock.lock();
253	try {
254	if (count > 0 && --count == 0)
255	zero.signalAll();
256	} finally {
257	lock.unlock();
258	}
259	}
260
261	/**
262	* Returns the current count.
263	* <p>This method is typically used for debugging and testing purposes.
264	* @return the current count.
265	*/
266	public long getCount() {
267	lock.lock();
268	try {
269	return count;
270	} finally {
271	lock.unlock();
272	}
273	}
274	}