5 |
|
*/ |
6 |
|
|
7 |
|
package jsr166y; |
8 |
+ |
|
9 |
|
import java.util.concurrent.*; |
10 |
|
import java.util.concurrent.atomic.*; |
11 |
|
import java.util.concurrent.locks.LockSupport; |
14 |
|
|
15 |
|
/** |
16 |
|
* A reusable synchronization barrier, similar in functionality to a |
17 |
< |
* {@link java.util.concurrent.CyclicBarrier} and {@link |
18 |
< |
* java.util.concurrent.CountDownLatch} but supporting more flexible |
19 |
< |
* usage. |
17 |
> |
* {@link java.util.concurrent.CyclicBarrier CyclicBarrier} and |
18 |
> |
* {@link java.util.concurrent.CountDownLatch CountDownLatch} |
19 |
> |
* but supporting more flexible usage. |
20 |
|
* |
21 |
|
* <ul> |
22 |
|
* |
26 |
|
* basic synchronization constructs, registration and deregistration |
27 |
|
* affect only internal counts; they do not establish any further |
28 |
|
* internal bookkeeping, so tasks cannot query whether they are |
29 |
< |
* registered. (However, you can introduce such bookkeeping in by |
29 |
> |
* registered. (However, you can introduce such bookkeeping by |
30 |
|
* subclassing this class.) |
31 |
|
* |
32 |
|
* <li> Each generation has an associated phase value, starting at |
33 |
|
* zero, and advancing when all parties reach the barrier (wrapping |
34 |
< |
* around to zero after reaching <tt>Integer.MAX_VALUE</tt>). |
34 |
> |
* around to zero after reaching {@code Integer.MAX_VALUE}). |
35 |
|
* |
36 |
|
* <li> Like a CyclicBarrier, a Phaser may be repeatedly awaited. |
37 |
< |
* Method <tt>arriveAndAwaitAdvance</tt> has effect analogous to |
38 |
< |
* <tt>CyclicBarrier.await</tt>. However, Phasers separate two |
37 |
> |
* Method {@code arriveAndAwaitAdvance} has effect analogous to |
38 |
> |
* {@code CyclicBarrier.await}. However, Phasers separate two |
39 |
|
* aspects of coordination, that may also be invoked independently: |
40 |
|
* |
41 |
|
* <ul> |
42 |
|
* |
43 |
< |
* <li> Arriving at a barrier. Methods <tt>arrive</tt> and |
44 |
< |
* <tt>arriveAndDeregister</tt> do not block, but return |
43 |
> |
* <li> Arriving at a barrier. Methods {@code arrive} and |
44 |
> |
* {@code arriveAndDeregister} do not block, but return |
45 |
|
* the phase value current upon entry to the method. |
46 |
|
* |
47 |
< |
* <li> Awaiting others. Method <tt>awaitAdvance</tt> requires an |
47 |
> |
* <li> Awaiting others. Method {@code awaitAdvance} requires an |
48 |
|
* argument indicating the entry phase, and returns when the |
49 |
|
* barrier advances to a new phase. |
50 |
|
* </ul> |
52 |
|
* |
53 |
|
* <li> Barrier actions, performed by the task triggering a phase |
54 |
|
* advance while others may be waiting, are arranged by overriding |
55 |
< |
* method <tt>onAdvance</tt>, that also controls termination. |
55 |
> |
* method {@code onAdvance}, that also controls termination. |
56 |
|
* Overriding this method may be used to similar but more flexible |
57 |
|
* effect as providing a barrier action to a CyclicBarrier. |
58 |
|
* |
59 |
|
* <li> Phasers may enter a <em>termination</em> state in which all |
60 |
|
* await actions immediately return, indicating (via a negative phase |
61 |
|
* value) that execution is complete. Termination is triggered by |
62 |
< |
* executing the overridable <tt>onAdvance</tt> method that is invoked |
62 |
> |
* executing the overridable {@code onAdvance} method that is invoked |
63 |
|
* each time the barrier is about to be tripped. When a Phaser is |
64 |
|
* controlling an action with a fixed number of iterations, it is |
65 |
|
* often convenient to override this method to cause termination when |
66 |
|
* the current phase number reaches a threshold. Method |
67 |
< |
* <tt>forceTermination</tt> is also available to abruptly release |
67 |
> |
* {@code forceTermination} is also available to abruptly release |
68 |
|
* waiting threads and allow them to terminate. |
69 |
|
* |
70 |
|
* <li> Phasers may be tiered to reduce contention. Phasers with large |
73 |
|
* This will typically greatly increase throughput even though it |
74 |
|
* incurs somewhat greater per-operation overhead. |
75 |
|
* |
76 |
< |
* <li> By default, <tt>awaitAdvance</tt> continues to wait even if |
76 |
> |
* <li> By default, {@code awaitAdvance} continues to wait even if |
77 |
|
* the waiting thread is interrupted. And unlike the case in |
78 |
|
* CyclicBarriers, exceptions encountered while tasks wait |
79 |
|
* interruptibly or with timeout do not change the state of the |
80 |
|
* barrier. If necessary, you can perform any associated recovery |
81 |
|
* within handlers of those exceptions, often after invoking |
82 |
< |
* <tt>forceTermination</tt>. |
82 |
> |
* {@code forceTermination}. |
83 |
|
* |
84 |
|
* </ul> |
85 |
|
* |
86 |
|
* <p><b>Sample usages:</b> |
87 |
|
* |
88 |
< |
* <p>A Phaser may be used instead of a <tt>CountdownLatch</tt> to control |
88 |
> |
* <p>A Phaser may be used instead of a {@code CountDownLatch} to control |
89 |
|
* a one-shot action serving a variable number of parties. The typical |
90 |
|
* idiom is for the method setting this up to first register, then |
91 |
|
* start the actions, then deregister, as in: |
103 |
|
* } |
104 |
|
* }.start(); |
105 |
|
* } |
106 |
+ |
* |
107 |
+ |
* doSomethingOnBehalfOfWorkers(); |
108 |
|
* phaser.arrive(); // allow threads to start |
109 |
< |
* int p = phaser.arriveAndDeregister(); // deregister self |
109 |
> |
* int p = phaser.arriveAndDeregister(); // deregister self ... |
110 |
> |
* p = phaser.awaitAdvance(p); // ... and await arrival |
111 |
|
* otherActions(); // do other things while tasks execute |
112 |
< |
* phaser.awaitAdvance(p); // wait for all tasks to arrive |
112 |
> |
* phaser.awaitAdvance(p); // await final completion |
113 |
|
* } |
114 |
|
* </pre> |
115 |
|
* |
116 |
|
* <p>One way to cause a set of threads to repeatedly perform actions |
117 |
< |
* for a given number of iterations is to override <tt>onAdvance</tt>: |
117 |
> |
* for a given number of iterations is to override {@code onAdvance}: |
118 |
|
* |
119 |
|
* <pre> |
120 |
|
* void startTasks(List<Runnable> list, final int iterations) { |
164 |
|
* build(new Task[n], 0, n, new Phaser()); |
165 |
|
* </pre> |
166 |
|
* |
167 |
< |
* The best value of <tt>TASKS_PER_PHASER</tt> depends mainly on |
167 |
> |
* The best value of {@code TASKS_PER_PHASER} depends mainly on |
168 |
|
* expected barrier synchronization rates. A value as low as four may |
169 |
|
* be appropriate for extremely small per-barrier task bodies (thus |
170 |
|
* high rates), or up to hundreds for extremely large ones. |
196 |
|
* However, to efficiently maintain atomicity, these values are |
197 |
|
* packed into a single (atomic) long. Termination uses the sign |
198 |
|
* bit of 32 bit representation of phase, so phase is set to -1 on |
199 |
< |
* termination. Good performace relies on keeping state decoding |
199 |
> |
* termination. Good performance relies on keeping state decoding |
200 |
|
* and encoding simple, and keeping race windows short. |
201 |
|
* |
202 |
|
* Note: there are some cheats in arrive() that rely on unarrived |
509 |
|
|
510 |
|
/** |
511 |
|
* Arrives at the barrier and awaits others. Equivalent in effect |
512 |
< |
* to <tt>awaitAdvance(arrive())</tt>. If you instead need to |
512 |
> |
* to {@code awaitAdvance(arrive())}. If you instead need to |
513 |
|
* await with interruption of timeout, and/or deregister upon |
514 |
|
* arrival, you can arrange them using analogous constructions. |
515 |
|
* @return the phase on entry to this method |
542 |
|
|
543 |
|
/** |
544 |
|
* Awaits the phase of the barrier to advance from the given |
545 |
< |
* value, or returns immediately if argumet is negative or this |
545 |
> |
* value, or returns immediately if argument is negative or this |
546 |
|
* barrier is terminated, or throws InterruptedException if |
547 |
|
* interrupted while waiting. |
548 |
|
* @param phase the phase on entry to this method |
609 |
|
|
610 |
|
/** |
611 |
|
* Returns the current phase number. The maximum phase number is |
612 |
< |
* <tt>Integer.MAX_VALUE</tt>, after which it restarts at |
612 |
> |
* {@code Integer.MAX_VALUE}, after which it restarts at |
613 |
|
* zero. Upon termination, the phase number is negative. |
614 |
|
* @return the phase number, or a negative value if terminated |
615 |
|
*/ |
618 |
|
} |
619 |
|
|
620 |
|
/** |
621 |
< |
* Returns true if the current phase number equals the given phase. |
621 |
> |
* Returns {@code true} if the current phase number equals the given phase. |
622 |
|
* @param phase the phase |
623 |
< |
* @return true if the current phase number equals the given phase. |
623 |
> |
* @return {@code true} if the current phase number equals the given phase |
624 |
|
*/ |
625 |
|
public final boolean hasPhase(int phase) { |
626 |
|
return phaseOf(getReconciledState()) == phase; |
654 |
|
|
655 |
|
/** |
656 |
|
* Returns the parent of this phaser, or null if none. |
657 |
< |
* @return the parent of this phaser, or null if none. |
657 |
> |
* @return the parent of this phaser, or null if none |
658 |
|
*/ |
659 |
|
public Phaser getParent() { |
660 |
|
return parent; |
663 |
|
/** |
664 |
|
* Returns the root ancestor of this phaser, which is the same as |
665 |
|
* this phaser if it has no parent. |
666 |
< |
* @return the root ancestor of this phaser. |
666 |
> |
* @return the root ancestor of this phaser |
667 |
|
*/ |
668 |
|
public Phaser getRoot() { |
669 |
|
return root; |
670 |
|
} |
671 |
|
|
672 |
|
/** |
673 |
< |
* Returns true if this barrier has been terminated. |
674 |
< |
* @return true if this barrier has been terminated |
673 |
> |
* Returns {@code true} if this barrier has been terminated. |
674 |
> |
* @return {@code true} if this barrier has been terminated |
675 |
|
*/ |
676 |
|
public boolean isTerminated() { |
677 |
|
return getPhase() < 0; |
683 |
|
* barrier is tripped (and thus all other waiting parties are |
684 |
|
* dormant). If it returns true, then, rather than advance the |
685 |
|
* phase number, this barrier will be set to a final termination |
686 |
< |
* state, and subsequent calls to <tt>isTerminated</tt> will |
686 |
> |
* state, and subsequent calls to {@code isTerminated} will |
687 |
|
* return true. |
688 |
|
* |
689 |
|
* <p> The default version returns true when the number of |
694 |
|
* <p> You may override this method to perform an action with side |
695 |
|
* effects visible to participating tasks, but it is in general |
696 |
|
* only sensible to do so in designs where all parties register |
697 |
< |
* before any arrive, and all <tt>awaitAdvance</tt> at each phase. |
697 |
> |
* before any arrive, and all {@code awaitAdvance} at each phase. |
698 |
|
* Otherwise, you cannot ensure lack of interference. In |
699 |
|
* particular, this method may be invoked more than once per |
700 |
|
* transition if other parties successfully register while the |
703 |
|
* method. |
704 |
|
* |
705 |
|
* @param phase the phase number on entering the barrier |
706 |
< |
* @param registeredParties the current number of registered |
707 |
< |
* parties. |
704 |
< |
* @return true if this barrier should terminate |
706 |
> |
* @param registeredParties the current number of registered parties |
707 |
> |
* @return {@code true} if this barrier should terminate |
708 |
|
*/ |
709 |
|
protected boolean onAdvance(int phase, int registeredParties) { |
710 |
|
return registeredParties <= 0; |
713 |
|
/** |
714 |
|
* Returns a string identifying this phaser, as well as its |
715 |
|
* state. The state, in brackets, includes the String {@code |
716 |
< |
* "phase ="} followed by the phase number, {@code "parties ="} |
716 |
> |
* "phase = "} followed by the phase number, {@code "parties = "} |
717 |
|
* followed by the number of registered parties, and {@code |
718 |
< |
* "arrived ="} followed by the number of arrived parties |
718 |
> |
* "arrived = "} followed by the number of arrived parties. |
719 |
|
* |
720 |
|
* @return a string identifying this barrier, as well as its state |
721 |
|
*/ |
722 |
|
public String toString() { |
723 |
|
long s = getReconciledState(); |
724 |
< |
return super.toString() + "[phase = " + phaseOf(s) + " parties = " + partiesOf(s) + " arrived = " + arrivedOf(s) + "]"; |
724 |
> |
return super.toString() + |
725 |
> |
"[phase = " + phaseOf(s) + |
726 |
> |
" parties = " + partiesOf(s) + |
727 |
> |
" arrived = " + arrivedOf(s) + "]"; |
728 |
|
} |
729 |
|
|
730 |
|
// methods for waiting |