util/concurrent/CountDownLatch.java

package java.util.concurrent;

/**
 * A <tt>CountDownLatch</tt> allows one set of threads to wait until
 * the actions of another set of threads allow the first set to proceed.
 * <p>A <tt>CountDownLatch</tt> is initialized with a given <em>count</em>. 
 * 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}.
 *
 * <p>A <tt>CountDownLatch</tt> is a versatile synchronization tool
 * and can be used for a number of purposes. 
 * A <tt>CountDownLatch</tt> 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 <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.
 * A useful property of a <tt>CountDownLatch</tt> 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.
 *
 * <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>
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/01/30 22:12:13 $
 * @editor $Author: dholmes $
 */
public class CountDownLatch {

    /**
     * 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 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}.
     *
     * <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 {}

    /**
     * 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.
     * 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 <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 granularity) 
        throws InterruptedException {
        return false;
    }


    /**
     * 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() {}

    /**
     * Returns the current count.
     * <p>This method is typically used for debugging and testing purposes.
     * @return the current count.
     */
    public long getCount() {
        return 0;
    }
}
Revision:	1.1
Committed:	Wed May 14 21:30:46 2003 UTC (21 years ago) by tim
Branch:	MAIN
Log Message:	Moved main source rooted at . to ./src/main Moved test source rooted at ./etc/testcases to ./src/test
#	User	Rev	Content
1	tim	1.1	package java.util.concurrent;
2
3			/**
4			* A <tt>CountDownLatch</tt> allows one set of threads to wait until
5			* the actions of another set of threads allow the first set to proceed.
6			* <p>A <tt>CountDownLatch</tt> is initialized with a given <em>count</em>.
7			* The {@link #await} methods block until the current {@link #getCount count}
8			* reaches zero due to invocations of the {@link #countDown} method,
9			* after which all waiting threads are
10			* released and any subsequent invocations of {@link #await} return
11			* immediately. This is a one-shot phenomenon -- the count
12			* cannot be reset. If you need a version that resets the count,
13			* consider using a {@link CyclicBarrier}.
14			*
15			* <p>A <tt>CountDownLatch</tt> is a versatile synchronization tool
16			* and can be used for a number of purposes.
17			* A <tt>CountDownLatch</tt> initialized to one serves as a simple on/off
18			* latch, or gate: all threads invoking {@link #await} wait at the gate until
19			* it is opened by a thread invoking {@link #countDown}.
20			* A <tt>CountDownLatch</tt> initialized to <em>N</em> can be used to make
21			* one thread wait until <em>N</em> threads have completed some action.
22			* A useful property of a <tt>CountDownLatch</tt> is that it doesn't
23			* require that all threads wait before any can proceed, it simply
24			* prevents any thread from proceeding past the {@link #await wait} until
25			* all threads could pass.
26			*
27			* <p><b>Sample usage:</b> Here is a pair of classes in which a group
28			* of worker threads use two countdown latches:
29			* <ul>
30			* <li> The first is a start signal that prevents any worker from proceeding
31			* until the driver is ready for them to proceed;
32			* <li> The second is a completion signal that allows the driver to wait
33			* until all workers have completed.
34			* </ul>
35			*
36			* <pre>
37			* class Driver { // ...
38			* void main() throws InterruptedException {
39			* CountDownLatch startSignal = new CountDownLatch(1);
40			* CountDownLatch doneSignal = new CountDownLatch(N);
41			*
42			* for (int i = 0; i < N; ++i) // create and start threads
43			* new Thread(new Worker(startSignal, doneSignal)).start();
44			*
45			* doSomethingElse(); // don't let run yet
46			* startSignal.countDown(); // let all threads proceed
47			* doSomethingElse();
48			* doneSignal.await(); // wait for all to finish
49			* }
50			* }
51			*
52			* class Worker implements Runnable {
53			* private final CountDownLatch startSignal;
54			* private final CountDownLatch doneSignal;
55			* Worker(CountDownLatch startSignal, CountDownLatch doneSignal) {
56			* this.startSignal = startSignal;
57			* this.doneSignal = doneSignal;
58			* }
59			* public void run() {
60			* try {
61			* startSignal.await();
62			* doWork();
63			* doneSignal.countDown();
64			* }
65			* catch (InterruptedException ex) {} // return;
66			* }
67			*
68			* void doWork() { ... }
69			* }
70			*
71			* </pre>
72			*
73			* @since 1.5
74			* @spec JSR-166
75			* @revised $Date: 2003/01/30 22:12:13 $
76			* @editor $Author: dholmes $
77			*/
78			public class CountDownLatch {
79
80			/**
81			* Constructs a <tt>CountDownLatch</tt> initialized with the given
82			* count.
83			*
84			* @param count the number of times {@link #countDown} must be invoked
85			* before threads can pass through {@link #await}.
86			*
87			* @throws IllegalArgumentException if <tt>count</tt> is less than one.
88			*/
89			public CountDownLatch(int count) {}
90
91			/**
92			* Causes the current thread to wait until the latch has counted down to
93			* zero, unless the thread is {@link Thread#interrupt interrupted}.
94			*
95			* <p>If the current {@link #getCount count} is zero then this method
96			* returns immediately.
97			* <p>If the current {@link #getCount count} is greater than zero then
98			* the current thread becomes disabled for thread scheduling
99			* purposes and lies dormant until one of two things happen:
100			* <ul>
101			* <li> The count reaches zero due to invocations of the
102			* {@link #countDown} method; or
103			* <li> Some other thread {@link Thread#interrupt interrupts} the current
104			* thread.
105			* </ul>
106			* <p>If the current thread:
107			* <ul>
108			* <li>has its interrupted status set on entry to this method; or
109			* <li>is {@link Thread#interrupt interrupted} while waiting,
110			* </ul>
111			* then {@link InterruptedException} is thrown and the current thread's
112			* interrupted status is cleared.
113			*
114			* @throws InterruptedException if the current thread is interrupted
115			* while waiting.
116			*/
117			public void await() throws InterruptedException {}
118
119			/**
120			* Causes the current thread to wait until the latch has counted down to
121			* zero, unless the thread is {@link Thread#interrupt interrupted},
122			* or the specified waiting time elapses.
123			*
124			* <p>If the current {@link #getCount count} is zero then this method
125			* returns immediately with the value <tt>true</tt>.
126			*
127			* <p>If the current {@link #getCount count} is greater than zero then
128			* the current thread becomes disabled for thread scheduling
129			* purposes and lies dormant until one of three things happen:
130			* <ul>
131			* <li>The count reaches zero due to invocations of the
132			* {@link #countDown} method; or
133			* <li>Some other thread {@link Thread#interrupt interrupts} the current
134			* thread; or
135			* <li>The specified waiting time elapses.
136			* </ul>
137			* <p>If the count reaches zero then the method returns with the
138			* value <tt>true</tt>.
139			* <p>If the current thread:
140			* <ul>
141			* <li>has its interrupted status set on entry to this method; or
142			* <li>is {@link Thread#interrupt interrupted} while waiting,
143			* </ul>
144			* then {@link InterruptedException} is thrown and the current thread's
145			* interrupted status is cleared.
146			*
147			* <p>If the specified waiting time elapses then the value <tt>false</tt>
148			* is returned.
149			* The given waiting time is a best-effort lower bound. If the time is
150			* less than or equal to zero, the method will not wait at all.
151			*
152			* @param timeout the maximum time to wait
153			* @param granularity the time unit of the <tt>timeout</tt> argument.
154			* @return <tt>true</tt> if the count reached zero and <tt>false</tt>
155			* if the waiting time elapsed before the count reached zero.
156			*
157			* @throws InterruptedException if the current thread is interrupted
158			* while waiting.
159			*/
160			public boolean await(long timeout, TimeUnit granularity)
161			throws InterruptedException {
162			return false;
163			}
164
165
166			/**
167			* Decrements the count of the latch, releasing all waiting threads if
168			* the count reaches zero.
169			* <p>If the current {@link #getCount count} is greater than zero then
170			* it is decremented. If the new count is zero then all waiting threads
171			* are re-enabled for thread scheduling purposes.
172			* <p>If the current {@link #getCount count} equals zero then nothing
173			* happens.
174			*/
175			public void countDown() {}
176
177			/**
178			* Returns the current count.
179			* <p>This method is typically used for debugging and testing purposes.
180			* @return the current count.
181			*/
182			public long getCount() {
183			return 0;
184			}
185			}