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: |
102 |
|
* } |
103 |
|
* }.start(); |
104 |
|
* } |
105 |
+ |
* |
106 |
+ |
* doSomethingOnBehalfOfWorkers(); |
107 |
|
* phaser.arrive(); // allow threads to start |
108 |
< |
* int p = phaser.arriveAndDeregister(); // deregister self |
108 |
> |
* int p = phaser.arriveAndDeregister(); // deregister self ... |
109 |
> |
* p = phaser.awaitAdvance(p); // ... and await arrival |
110 |
|
* otherActions(); // do other things while tasks execute |
111 |
< |
* phaser.awaitAdvance(p); // wait for all tasks to arrive |
111 |
> |
* phaser.awaitAdvance(p); // await final completion |
112 |
|
* } |
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. |
195 |
|
* However, to efficiently maintain atomicity, these values are |
196 |
|
* packed into a single (atomic) long. Termination uses the sign |
197 |
|
* bit of 32 bit representation of phase, so phase is set to -1 on |
198 |
< |
* termination. Good performace relies on keeping state decoding |
198 |
> |
* termination. Good performance relies on keeping state decoding |
199 |
|
* and encoding simple, and keeping race windows short. |
200 |
|
* |
201 |
|
* Note: there are some cheats in arrive() that rely on unarrived |
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 |
541 |
|
|
542 |
|
/** |
543 |
|
* Awaits the phase of the barrier to advance from the given |
544 |
< |
* value, or returns immediately if argumet is negative or this |
544 |
> |
* value, or returns immediately if argument is negative or this |
545 |
|
* barrier is terminated, or throws InterruptedException if |
546 |
|
* interrupted while waiting. |
547 |
|
* @param phase 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 |