sample/java.util.concurrent.CountDownLatch.txt

   1 *java.util.concurrent.CountDownLatch* *CountDownLatch* A synchronization aid tha
   2
   3 public class CountDownLatch
   4   extends    |java.lang.Object|
   5
   6 |java.util.concurrent.CountDownLatch_Description|
   7 |java.util.concurrent.CountDownLatch_Fields|
   8 |java.util.concurrent.CountDownLatch_Constructors|
   9 |java.util.concurrent.CountDownLatch_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.CountDownLatch_Constructors*
  14 |java.util.concurrent.CountDownLatch(int)|Constructs aCountDownLatchinitialized
  15
  16 *java.util.concurrent.CountDownLatch_Methods*
  17 |java.util.concurrent.CountDownLatch.await()|Causes the current thread to wait
  18 |java.util.concurrent.CountDownLatch.await(long,TimeUnit)|Causes the current th
  19 |java.util.concurrent.CountDownLatch.countDown()|Decrements the count of the la
  20 |java.util.concurrent.CountDownLatch.getCount()|Returns the current count.
  21 |java.util.concurrent.CountDownLatch.toString()|Returns a string identifying th
  22
  23 *java.util.concurrent.CountDownLatch_Description*
  24
  25 A synchronization aid that allows one or more threads to wait until a set of
  26 operations being performed in other threads completes.
  27
  28 ACountDownLatchis initialized with a given count. The
  29 await(|java.util.concurrent.CountDownLatch|) methods block until the current
  30 count reaches zero due to invocations of the
  31 (|java.util.concurrent.CountDownLatch|) method, after which all waiting threads
  32 are released and any subsequent invocations of
  33 await(|java.util.concurrent.CountDownLatch|) return immediately. This is a
  34 one-shot phenomenon -- the count cannot be reset. If you need a version that
  35 resets the count, consider using a (|java.util.concurrent.CyclicBarrier|) .
  36
  37 ACountDownLatchis a versatile synchronization tool and can be used for a number
  38 of purposes. ACountDownLatchinitialized with a count of one serves as a simple
  39 on/off latch, or gate: all threads invoking
  40 await(|java.util.concurrent.CountDownLatch|) wait at the gate until it is
  41 opened by a thread invoking (|java.util.concurrent.CountDownLatch|) .
  42 ACountDownLatchinitialized to N can be used to make one thread wait until N
  43 threads have completed some action, or some action has been completed N times.
  44
  45 A useful property of aCountDownLatchis that it doesn't require that threads
  46 callingcountDownwait for the count to reach zero before proceeding, it simply
  47 prevents any thread from proceeding past an
  48 await(|java.util.concurrent.CountDownLatch|) until all threads could pass.
  49
  50 Sample usage: Here is a pair of classes in which a group of worker threads use
  51 two countdown latches:
  52
  53 The first is a start signal that prevents any worker from proceeding until the
  54 driver is ready for them to proceed; The second is a completion signal that
  55 allows the driver to wait until all workers have completed.
  56
  57
  58
  59 class Driver { // ... void main() throws InterruptedException { CountDownLatch
  60 startSignal = new CountDownLatch(1); CountDownLatch doneSignal = new
  61 CountDownLatch(N);
  62
  63 for (int i = 0; i Another typical usage would be to divide a problem into N
  64 parts, describe each part with a Runnable that executes that portion and counts
  65 down on the latch, and queue all the Runnables to an Executor. When all
  66 sub-parts are complete, the coordinating thread will be able to pass through
  67 await. (When threads must repeatedly count down in this way, instead use a
  68 (|java.util.concurrent.CyclicBarrier|) .)
  69
  70
  71
  72 class Driver2 { // ... void main() throws InterruptedException { CountDownLatch
  73 doneSignal = new CountDownLatch(N); Executor e = ...
  74
  75 for (int i = 0; i Memory consistency effects: Actions in a thread prior to
  76 callingcountDown()happen-before actions following a successful return from a
  77 correspondingawait()in another thread.
  78
  79
  80
  81 *java.util.concurrent.CountDownLatch(int)*
  82
  83 public CountDownLatch(int count)
  84
  85 Constructs aCountDownLatchinitialized with the given count.
  86
  87     count - the number of times {@link #countDown} must be invoked before threads can pass
  88        through {@link #await}
  89
  90 *java.util.concurrent.CountDownLatch.await()*
  91
  92 public void await()
  93   throws |java.lang.InterruptedException|
  94
  95 Causes the current thread to wait until the latch has counted down to zero,
  96 unless the thread is interrupted(|java.lang.Thread|) .
  97
  98 If the current count is zero then this method returns immediately.
  99
 100 If the current count is greater than zero then the current thread becomes
 101 disabled for thread scheduling purposes and lies dormant until one of two
 102 things happen:
 103
 104 The count reaches zero due to invocations of the
 105 (|java.util.concurrent.CountDownLatch|) method; or Some other thread
 106 interrupts(|java.lang.Thread|) the current thread.
 107
 108 If the current thread:
 109
 110 has its interrupted status set on entry to this method; or is
 111 interrupted(|java.lang.Thread|) while waiting,
 112
 113 then (|java.lang.InterruptedException|) is thrown and the current thread's
 114 interrupted status is cleared.
 115
 116
 117
 118 *java.util.concurrent.CountDownLatch.await(long,TimeUnit)*
 119
 120 public boolean await(
 121   long timeout,
 122   java.util.concurrent.TimeUnit unit)
 123   throws |java.lang.InterruptedException|
 124
 125 Causes the current thread to wait until the latch has counted down to zero,
 126 unless the thread is interrupted(|java.lang.Thread|) , or the specified waiting
 127 time elapses.
 128
 129 If the current count is zero then this method returns immediately with the
 130 valuetrue.
 131
 132 If the current count is greater than zero then the current thread becomes
 133 disabled for thread scheduling purposes and lies dormant until one of three
 134 things happen:
 135
 136 The count reaches zero due to invocations of the
 137 (|java.util.concurrent.CountDownLatch|) method; or Some other thread
 138 interrupts(|java.lang.Thread|) the current thread; or The specified waiting
 139 time elapses.
 140
 141 If the count reaches zero then the method returns with the valuetrue.
 142
 143 If the current thread:
 144
 145 has its interrupted status set on entry to this method; or is
 146 interrupted(|java.lang.Thread|) while waiting,
 147
 148 then (|java.lang.InterruptedException|) is thrown and the current thread's
 149 interrupted status is cleared.
 150
 151 If the specified waiting time elapses then the valuefalseis returned. If the
 152 time is less than or equal to zero, the method will not wait at all.
 153
 154
 155     timeout - the maximum time to wait
 156     unit - the time unit of the {@code timeout} argument
 157
 158     Returns: {@code true} if the count reached zero and {@code false} if the waiting time
 159              elapsed before the count reached zero
 160
 161 *java.util.concurrent.CountDownLatch.countDown()*
 162
 163 public void countDown()
 164
 165 Decrements the count of the latch, releasing all waiting threads if the count
 166 reaches zero.
 167
 168 If the current count is greater than zero then it is decremented. If the new
 169 count is zero then all waiting threads are re-enabled for thread scheduling
 170 purposes.
 171
 172 If the current count equals zero then nothing happens.
 173
 174
 175
 176 *java.util.concurrent.CountDownLatch.getCount()*
 177
 178 public long getCount()
 179
 180 Returns the current count.
 181
 182 This method is typically used for debugging and testing purposes.
 183
 184
 185
 186     Returns: the current count
 187
 188 *java.util.concurrent.CountDownLatch.toString()*
 189
 190 public |java.lang.String| toString()
 191
 192 Returns a string identifying this latch, as well as its state. The state, in
 193 brackets, includes the String"Count ="followed by the current count.
 194
 195
 196
 197     Returns: a string identifying this latch, as well as its state
 198
 199