sample/java.util.concurrent.CyclicBarrier.txt

   1 *java.util.concurrent.CyclicBarrier* *CyclicBarrier* A synchronization aid that
   2
   3 public class CyclicBarrier
   4   extends    |java.lang.Object|
   5
   6 |java.util.concurrent.CyclicBarrier_Description|
   7 |java.util.concurrent.CyclicBarrier_Fields|
   8 |java.util.concurrent.CyclicBarrier_Constructors|
   9 |java.util.concurrent.CyclicBarrier_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.CyclicBarrier_Constructors*
  14 |java.util.concurrent.CyclicBarrier(int)|Creates a new CyclicBarrier that will
  15 |java.util.concurrent.CyclicBarrier(int,Runnable)|Creates a new CyclicBarrier t
  16
  17 *java.util.concurrent.CyclicBarrier_Methods*
  18 |java.util.concurrent.CyclicBarrier.await()|Waits until all#getParties partiesh
  19 |java.util.concurrent.CyclicBarrier.await(long,TimeUnit)|Waits until all#getPar
  20 |java.util.concurrent.CyclicBarrier.getNumberWaiting()|Returns the number of pa
  21 |java.util.concurrent.CyclicBarrier.getParties()|Returns the number of parties
  22 |java.util.concurrent.CyclicBarrier.isBroken()|Queries if this barrier is in a
  23 |java.util.concurrent.CyclicBarrier.reset()|Resets the barrier to its initial s
  24
  25 *java.util.concurrent.CyclicBarrier_Description*
  26
  27 A synchronization aid that allows a set of threads to all wait for each other
  28 to reach a common barrier point. CyclicBarriers are useful in programs
  29 involving a fixed sized party of threads that must occasionally wait for each
  30 other. The barrier is called cyclic because it can be re-used after the waiting
  31 threads are released.
  32
  33 A CyclicBarrier supports an optional (|java.lang.Runnable|) command that is run
  34 once per barrier point, after the last thread in the party arrives, but before
  35 any threads are released. This barrier action is useful for updating
  36 shared-state before any of the parties continue.
  37
  38 Sample usage: Here is an example of using a barrier in a parallel decomposition
  39 design:
  40
  41 class Solver { final int N; final float[][] data; final CyclicBarrier barrier;
  42
  43 class Worker implements Runnable { int myRow; Worker(int row) { myRow = row; }
  44 public void run() { while (!done()) { processRow(myRow);
  45
  46 try { barrier.await(); } catch (InterruptedException ex) { return; } catch
  47 (BrokenBarrierException ex) { return; } } } }
  48
  49 public Solver(float[][] matrix) { data = matrix; N = matrix.length; barrier =
  50 new CyclicBarrier(N, new Runnable() { public void run() { mergeRows(...); } });
  51 for (int i = 0; i < N; ++i) new Thread(new Worker(i)).start();
  52
  53 waitUntilDone(); } }
  54
  55 Here, each worker thread processes a row of the matrix then waits at the
  56 barrier until all rows have been processed. When all rows are processed the
  57 supplied (|java.lang.Runnable|) barrier action is executed and merges the rows.
  58 If the merger determines that a solution has been found then done() will return
  59 true and each worker will terminate.
  60
  61 If the barrier action does not rely on the parties being suspended when it is
  62 executed, then any of the threads in the party could execute that action when
  63 it is released. To facilitate this, each invocation of
  64 (|java.util.concurrent.CyclicBarrier|) returns the arrival index of that thread
  65 at the barrier. You can then choose which thread should execute the barrier
  66 action, for example:
  67
  68 if (barrier.await() == 0) { // log the completion of this iteration }
  69
  70 The CyclicBarrier uses an all-or-none breakage model for failed synchronization
  71 attempts: If a thread leaves a barrier point prematurely because of
  72 interruption, failure, or timeout, all other threads waiting at that barrier
  73 point will also leave abnormally via
  74 (|java.util.concurrent.BrokenBarrierException|) (or
  75 (|java.lang.InterruptedException|) if they too were interrupted at about the
  76 same time).
  77
  78 Memory consistency effects: Actions in a thread prior to
  79 callingawait()happen-before actions that are part of the barrier action, which
  80 in turn happen-before actions following a successful return from the
  81 correspondingawait()in other threads.
  82
  83
  84
  85 *java.util.concurrent.CyclicBarrier(int)*
  86
  87 public CyclicBarrier(int parties)
  88
  89 Creates a new CyclicBarrier that will trip when the given number of parties
  90 (threads) are waiting upon it, and does not perform a predefined action when
  91 the barrier is tripped.
  92
  93     parties - the number of threads that must invoke {@link #await} before the barrier is
  94        tripped
  95
  96 *java.util.concurrent.CyclicBarrier(int,Runnable)*
  97
  98 public CyclicBarrier(
  99   int parties,
 100   java.lang.Runnable barrierAction)
 101
 102 Creates a new CyclicBarrier that will trip when the given number of parties
 103 (threads) are waiting upon it, and which will execute the given barrier action
 104 when the barrier is tripped, performed by the last thread entering the barrier.
 105
 106     parties - the number of threads that must invoke {@link #await} before the barrier is
 107        tripped
 108     barrierAction - the command to execute when the barrier is tripped, or {@code null} if there is
 109        no action
 110
 111 *java.util.concurrent.CyclicBarrier.await()*
 112
 113 public int await()
 114   throws |java.util.concurrent.BrokenBarrierException|
 115          |java.lang.InterruptedException|
 116
 117 Waits until all parties(|java.util.concurrent.CyclicBarrier|) have invoked
 118 await on this barrier.
 119
 120 If the current thread is not the last to arrive then it is disabled for thread
 121 scheduling purposes and lies dormant until one of the following things happens:
 122
 123 The last thread arrives; or Some other thread interrupts(|java.lang.Thread|)
 124 the current thread; or Some other thread interrupts(|java.lang.Thread|) one of
 125 the other waiting threads; or Some other thread times out while waiting for
 126 barrier; or Some other thread invokes (|java.util.concurrent.CyclicBarrier|) on
 127 this barrier.
 128
 129 If the current thread:
 130
 131 has its interrupted status set on entry to this method; or is
 132 interrupted(|java.lang.Thread|) while waiting
 133
 134 then (|java.lang.InterruptedException|) is thrown and the current thread's
 135 interrupted status is cleared.
 136
 137 If the barrier is (|java.util.concurrent.CyclicBarrier|) while any thread is
 138 waiting, or if the barrier is broken(|java.util.concurrent.CyclicBarrier|) when
 139 await is invoked, or while any thread is waiting, then
 140 (|java.util.concurrent.BrokenBarrierException|) is thrown.
 141
 142 If any thread is interrupted(|java.lang.Thread|) while waiting, then all other
 143 waiting threads will throw (|java.util.concurrent.BrokenBarrierException|) and
 144 the barrier is placed in the broken state.
 145
 146 If the current thread is the last thread to arrive, and a non-null barrier
 147 action was supplied in the constructor, then the current thread runs the action
 148 before allowing the other threads to continue. If an exception occurs during
 149 the barrier action then that exception will be propagated in the current thread
 150 and the barrier is placed in the broken state.
 151
 152
 153
 154     Returns: the arrival index of the current thread, where index {@link #getParties()} - 1
 155              indicates the first to arrive and zero indicates the last to
 156              arrive
 157
 158 *java.util.concurrent.CyclicBarrier.await(long,TimeUnit)*
 159
 160 public int await(
 161   long timeout,
 162   java.util.concurrent.TimeUnit unit)
 163   throws |java.util.concurrent.BrokenBarrierException|
 164          |java.lang.InterruptedException|
 165          |java.util.concurrent.TimeoutException|
 166
 167 Waits until all parties(|java.util.concurrent.CyclicBarrier|) have invoked
 168 await on this barrier, or the specified waiting time elapses.
 169
 170 If the current thread is not the last to arrive then it is disabled for thread
 171 scheduling purposes and lies dormant until one of the following things happens:
 172
 173 The last thread arrives; or The specified timeout elapses; or Some other thread
 174 interrupts(|java.lang.Thread|) the current thread; or Some other thread
 175 interrupts(|java.lang.Thread|) one of the other waiting threads; or Some other
 176 thread times out while waiting for barrier; or Some other thread invokes
 177 (|java.util.concurrent.CyclicBarrier|) on this barrier.
 178
 179 If the current thread:
 180
 181 has its interrupted status set on entry to this method; or is
 182 interrupted(|java.lang.Thread|) while waiting
 183
 184 then (|java.lang.InterruptedException|) is thrown and the current thread's
 185 interrupted status is cleared.
 186
 187 If the specified waiting time elapses then
 188 (|java.util.concurrent.TimeoutException|) is thrown. If the time is less than
 189 or equal to zero, the method will not wait at all.
 190
 191 If the barrier is (|java.util.concurrent.CyclicBarrier|) while any thread is
 192 waiting, or if the barrier is broken(|java.util.concurrent.CyclicBarrier|) when
 193 await is invoked, or while any thread is waiting, then
 194 (|java.util.concurrent.BrokenBarrierException|) is thrown.
 195
 196 If any thread is interrupted(|java.lang.Thread|) while waiting, then all other
 197 waiting threads will throw (|java.util.concurrent.BrokenBarrierException|) and
 198 the barrier is placed in the broken state.
 199
 200 If the current thread is the last thread to arrive, and a non-null barrier
 201 action was supplied in the constructor, then the current thread runs the action
 202 before allowing the other threads to continue. If an exception occurs during
 203 the barrier action then that exception will be propagated in the current thread
 204 and the barrier is placed in the broken state.
 205
 206
 207     timeout - the time to wait for the barrier
 208     unit - the time unit of the timeout parameter
 209
 210     Returns: the arrival index of the current thread, where index {@link #getParties()} - 1
 211              indicates the first to arrive and zero indicates the last to
 212              arrive
 213
 214 *java.util.concurrent.CyclicBarrier.getNumberWaiting()*
 215
 216 public int getNumberWaiting()
 217
 218 Returns the number of parties currently waiting at the barrier. This method is
 219 primarily useful for debugging and assertions.
 220
 221
 222
 223     Returns: the number of parties currently blocked in {@link #await}
 224
 225 *java.util.concurrent.CyclicBarrier.getParties()*
 226
 227 public int getParties()
 228
 229 Returns the number of parties required to trip this barrier.
 230
 231
 232
 233     Returns: the number of parties required to trip this barrier
 234
 235 *java.util.concurrent.CyclicBarrier.isBroken()*
 236
 237 public boolean isBroken()
 238
 239 Queries if this barrier is in a broken state.
 240
 241
 242
 243     Returns: {@code true} if one or more parties broke out of this barrier due to
 244              interruption or timeout since construction or the last reset, or a
 245              barrier action failed due to an exception; {@code false}
 246              otherwise.
 247
 248 *java.util.concurrent.CyclicBarrier.reset()*
 249
 250 public void reset()
 251
 252 Resets the barrier to its initial state. If any parties are currently waiting
 253 at the barrier, they will return with a
 254 (|java.util.concurrent.BrokenBarrierException|) . Note that resets after a
 255 breakage has occurred for other reasons can be complicated to carry out;
 256 threads need to re-synchronize in some other way, and choose one to perform the
 257 reset. It may be preferable to instead create a new barrier for subsequent use.
 258
 259
 260
 261