Sample usages: * - *
A Phaser may be used instead of a CountdownLatch to control + *
A Phaser may be used instead of a {@code CountDownLatch} to control * a one-shot action serving a variable number of parties. The typical * idiom is for the method setting this up to first register, then * start the actions, then deregister, as in: @@ -102,15 +103,18 @@ import java.lang.reflect.*; * } * }.start(); * } + * + * doSomethingOnBehalfOfWorkers(); * phaser.arrive(); // allow threads to start - * int p = phaser.arriveAndDeregister(); // deregister self + * int p = phaser.arriveAndDeregister(); // deregister self ... + * p = phaser.awaitAdvance(p); // ... and await arrival * otherActions(); // do other things while tasks execute - * phaser.awaitAdvance(p); // wait for all tasks to arrive + * phaser.awaitAdvance(p); // await final completion * } * * *
One way to cause a set of threads to repeatedly perform actions - * for a given number of iterations is to override onAdvance: + * for a given number of iterations is to override {@code onAdvance}: * *
* void startTasks(List<Runnable> list, final int iterations) {
@@ -160,7 +164,7 @@ import java.lang.reflect.*;
* build(new Task[n], 0, n, new Phaser());
*
*
- * The best value of TASKS_PER_PHASER depends mainly on
+ * The best value of {@code TASKS_PER_PHASER} depends mainly on
* expected barrier synchronization rates. A value as low as four may
* be appropriate for extremely small per-barrier task bodies (thus
* high rates), or up to hundreds for extremely large ones.
@@ -192,7 +196,7 @@ public class Phaser {
* However, to efficiently maintain atomicity, these values are
* packed into a single (atomic) long. Termination uses the sign
* bit of 32 bit representation of phase, so phase is set to -1 on
- * termination. Good performace relies on keeping state decoding
+ * termination. Good performance relies on keeping state decoding
* and encoding simple, and keeping race windows short.
*
* Note: there are some cheats in arrive() that rely on unarrived
@@ -505,7 +509,7 @@ public class Phaser {
/**
* Arrives at the barrier and awaits others. Equivalent in effect
- * to awaitAdvance(arrive()). If you instead need to
+ * to {@code awaitAdvance(arrive())}. If you instead need to
* await with interruption of timeout, and/or deregister upon
* arrival, you can arrange them using analogous constructions.
* @return the phase on entry to this method
@@ -538,7 +542,7 @@ public class Phaser {
/**
* Awaits the phase of the barrier to advance from the given
- * value, or returns immediately if argumet is negative or this
+ * value, or returns immediately if argument is negative or this
* barrier is terminated, or throws InterruptedException if
* interrupted while waiting.
* @param phase the phase on entry to this method
@@ -605,7 +609,7 @@ public class Phaser {
/**
* Returns the current phase number. The maximum phase number is
- * Integer.MAX_VALUE, after which it restarts at
+ * {@code Integer.MAX_VALUE}, after which it restarts at
* zero. Upon termination, the phase number is negative.
* @return the phase number, or a negative value if terminated
*/
@@ -614,9 +618,9 @@ public class Phaser {
}
/**
- * Returns true if the current phase number equals the given phase.
+ * Returns {@code true} if the current phase number equals the given phase.
* @param phase the phase
- * @return true if the current phase number equals the given phase.
+ * @return {@code true} if the current phase number equals the given phase
*/
public final boolean hasPhase(int phase) {
return phaseOf(getReconciledState()) == phase;
@@ -650,7 +654,7 @@ public class Phaser {
/**
* Returns the parent of this phaser, or null if none.
- * @return the parent of this phaser, or null if none.
+ * @return the parent of this phaser, or null if none
*/
public Phaser getParent() {
return parent;
@@ -659,15 +663,15 @@ public class Phaser {
/**
* Returns the root ancestor of this phaser, which is the same as
* this phaser if it has no parent.
- * @return the root ancestor of this phaser.
+ * @return the root ancestor of this phaser
*/
public Phaser getRoot() {
return root;
}
/**
- * Returns true if this barrier has been terminated.
- * @return true if this barrier has been terminated
+ * Returns {@code true} if this barrier has been terminated.
+ * @return {@code true} if this barrier has been terminated
*/
public boolean isTerminated() {
return getPhase() < 0;
@@ -679,7 +683,7 @@ public class Phaser {
* barrier is tripped (and thus all other waiting parties are
* dormant). If it returns true, then, rather than advance the
* phase number, this barrier will be set to a final termination
- * state, and subsequent calls to isTerminated will
+ * state, and subsequent calls to {@code isTerminated} will
* return true.
*
* The default version returns true when the number of @@ -690,7 +694,7 @@ public class Phaser { *
You may override this method to perform an action with side * effects visible to participating tasks, but it is in general * only sensible to do so in designs where all parties register - * before any arrive, and all awaitAdvance at each phase. + * before any arrive, and all {@code awaitAdvance} at each phase. * Otherwise, you cannot ensure lack of interference. In * particular, this method may be invoked more than once per * transition if other parties successfully register while the @@ -699,9 +703,8 @@ public class Phaser { * method. * * @param phase the phase number on entering the barrier - * @param registeredParties the current number of registered - * parties. - * @return true if this barrier should terminate + * @param registeredParties the current number of registered parties + * @return {@code true} if this barrier should terminate */ protected boolean onAdvance(int phase, int registeredParties) { return registeredParties <= 0; @@ -710,15 +713,18 @@ public class Phaser { /** * Returns a string identifying this phaser, as well as its * state. The state, in brackets, includes the String {@code - * "phase ="} followed by the phase number, {@code "parties ="} + * "phase = "} followed by the phase number, {@code "parties = "} * followed by the number of registered parties, and {@code - * "arrived ="} followed by the number of arrived parties + * "arrived = "} followed by the number of arrived parties. * * @return a string identifying this barrier, as well as its state */ public String toString() { long s = getReconciledState(); - return super.toString() + "[phase = " + phaseOf(s) + " parties = " + partiesOf(s) + " arrived = " + arrivedOf(s) + "]"; + return super.toString() + + "[phase = " + phaseOf(s) + + " parties = " + partiesOf(s) + + " arrived = " + arrivedOf(s) + "]"; } // methods for waiting