| 30 |
|
* |
| 31 |
|
* <li> Each generation has an associated phase value, starting at |
| 32 |
|
* zero, and advancing when all parties reach the barrier (wrapping |
| 33 |
< |
* around to zero after reaching <tt>Integer.MAX_VALUE</tt>). |
| 33 |
> |
* around to zero after reaching {@code Integer.MAX_VALUE}). |
| 34 |
|
* |
| 35 |
|
* <li> Like a CyclicBarrier, a Phaser may be repeatedly awaited. |
| 36 |
< |
* Method <tt>arriveAndAwaitAdvance</tt> has effect analogous to |
| 37 |
< |
* <tt>CyclicBarrier.await</tt>. However, Phasers separate two |
| 36 |
> |
* Method {@code arriveAndAwaitAdvance} has effect analogous to |
| 37 |
> |
* {@code CyclicBarrier.await}. However, Phasers separate two |
| 38 |
|
* aspects of coordination, that may also be invoked independently: |
| 39 |
|
* |
| 40 |
|
* <ul> |
| 41 |
|
* |
| 42 |
< |
* <li> Arriving at a barrier. Methods <tt>arrive</tt> and |
| 43 |
< |
* <tt>arriveAndDeregister</tt> do not block, but return |
| 42 |
> |
* <li> Arriving at a barrier. Methods {@code arrive} and |
| 43 |
> |
* {@code arriveAndDeregister} do not block, but return |
| 44 |
|
* the phase value current upon entry to the method. |
| 45 |
|
* |
| 46 |
< |
* <li> Awaiting others. Method <tt>awaitAdvance</tt> requires an |
| 46 |
> |
* <li> Awaiting others. Method {@code awaitAdvance} requires an |
| 47 |
|
* argument indicating the entry phase, and returns when the |
| 48 |
|
* barrier advances to a new phase. |
| 49 |
|
* </ul> |
| 51 |
|
* |
| 52 |
|
* <li> Barrier actions, performed by the task triggering a phase |
| 53 |
|
* advance while others may be waiting, are arranged by overriding |
| 54 |
< |
* method <tt>onAdvance</tt>, that also controls termination. |
| 54 |
> |
* method {@code onAdvance}, that also controls termination. |
| 55 |
|
* Overriding this method may be used to similar but more flexible |
| 56 |
|
* effect as providing a barrier action to a CyclicBarrier. |
| 57 |
|
* |
| 58 |
|
* <li> Phasers may enter a <em>termination</em> state in which all |
| 59 |
|
* await actions immediately return, indicating (via a negative phase |
| 60 |
|
* value) that execution is complete. Termination is triggered by |
| 61 |
< |
* executing the overridable <tt>onAdvance</tt> method that is invoked |
| 61 |
> |
* executing the overridable {@code onAdvance} method that is invoked |
| 62 |
|
* each time the barrier is about to be tripped. When a Phaser is |
| 63 |
|
* controlling an action with a fixed number of iterations, it is |
| 64 |
|
* often convenient to override this method to cause termination when |
| 65 |
|
* the current phase number reaches a threshold. Method |
| 66 |
< |
* <tt>forceTermination</tt> is also available to abruptly release |
| 66 |
> |
* {@code forceTermination} is also available to abruptly release |
| 67 |
|
* waiting threads and allow them to terminate. |
| 68 |
|
* |
| 69 |
|
* <li> Phasers may be tiered to reduce contention. Phasers with large |
| 72 |
|
* This will typically greatly increase throughput even though it |
| 73 |
|
* incurs somewhat greater per-operation overhead. |
| 74 |
|
* |
| 75 |
< |
* <li> By default, <tt>awaitAdvance</tt> continues to wait even if |
| 75 |
> |
* <li> By default, {@code awaitAdvance} continues to wait even if |
| 76 |
|
* the waiting thread is interrupted. And unlike the case in |
| 77 |
|
* CyclicBarriers, exceptions encountered while tasks wait |
| 78 |
|
* interruptibly or with timeout do not change the state of the |
| 79 |
|
* barrier. If necessary, you can perform any associated recovery |
| 80 |
|
* within handlers of those exceptions, often after invoking |
| 81 |
< |
* <tt>forceTermination</tt>. |
| 81 |
> |
* {@code forceTermination}. |
| 82 |
|
* |
| 83 |
|
* </ul> |
| 84 |
|
* |
| 85 |
|
* <p><b>Sample usages:</b> |
| 86 |
|
* |
| 87 |
< |
* <p>A Phaser may be used instead of a <tt>CountdownLatch</tt> to control |
| 87 |
> |
* <p>A Phaser may be used instead of a {@code CountdownLatch} to control |
| 88 |
|
* a one-shot action serving a variable number of parties. The typical |
| 89 |
|
* idiom is for the method setting this up to first register, then |
| 90 |
|
* start the actions, then deregister, as in: |
| 113 |
|
* </pre> |
| 114 |
|
* |
| 115 |
|
* <p>One way to cause a set of threads to repeatedly perform actions |
| 116 |
< |
* for a given number of iterations is to override <tt>onAdvance</tt>: |
| 116 |
> |
* for a given number of iterations is to override {@code onAdvance}: |
| 117 |
|
* |
| 118 |
|
* <pre> |
| 119 |
|
* void startTasks(List<Runnable> list, final int iterations) { |
| 163 |
|
* build(new Task[n], 0, n, new Phaser()); |
| 164 |
|
* </pre> |
| 165 |
|
* |
| 166 |
< |
* The best value of <tt>TASKS_PER_PHASER</tt> depends mainly on |
| 166 |
> |
* The best value of {@code TASKS_PER_PHASER} depends mainly on |
| 167 |
|
* expected barrier synchronization rates. A value as low as four may |
| 168 |
|
* be appropriate for extremely small per-barrier task bodies (thus |
| 169 |
|
* high rates), or up to hundreds for extremely large ones. |
| 508 |
|
|
| 509 |
|
/** |
| 510 |
|
* Arrives at the barrier and awaits others. Equivalent in effect |
| 511 |
< |
* to <tt>awaitAdvance(arrive())</tt>. If you instead need to |
| 511 |
> |
* to {@code awaitAdvance(arrive())}. If you instead need to |
| 512 |
|
* await with interruption of timeout, and/or deregister upon |
| 513 |
|
* arrival, you can arrange them using analogous constructions. |
| 514 |
|
* @return the phase on entry to this method |
| 608 |
|
|
| 609 |
|
/** |
| 610 |
|
* Returns the current phase number. The maximum phase number is |
| 611 |
< |
* <tt>Integer.MAX_VALUE</tt>, after which it restarts at |
| 611 |
> |
* {@code Integer.MAX_VALUE}, after which it restarts at |
| 612 |
|
* zero. Upon termination, the phase number is negative. |
| 613 |
|
* @return the phase number, or a negative value if terminated |
| 614 |
|
*/ |
| 682 |
|
* barrier is tripped (and thus all other waiting parties are |
| 683 |
|
* dormant). If it returns true, then, rather than advance the |
| 684 |
|
* phase number, this barrier will be set to a final termination |
| 685 |
< |
* state, and subsequent calls to <tt>isTerminated</tt> will |
| 685 |
> |
* state, and subsequent calls to {@code isTerminated} will |
| 686 |
|
* return true. |
| 687 |
|
* |
| 688 |
|
* <p> The default version returns true when the number of |
| 693 |
|
* <p> You may override this method to perform an action with side |
| 694 |
|
* effects visible to participating tasks, but it is in general |
| 695 |
|
* only sensible to do so in designs where all parties register |
| 696 |
< |
* before any arrive, and all <tt>awaitAdvance</tt> at each phase. |
| 696 |
> |
* before any arrive, and all {@code awaitAdvance} at each phase. |
| 697 |
|
* Otherwise, you cannot ensure lack of interference. In |
| 698 |
|
* particular, this method may be invoked more than once per |
| 699 |
|
* transition if other parties successfully register while the |
