{@code
- * void runTasks(List list) {
+ * void runTasks(List tasks) {
* final Phaser phaser = new Phaser(1); // "1" to register self
- * for (Runnable r : list) {
+ * // create and start threads
+ * for (Runnable task : tasks) {
* phaser.register();
* new Thread() {
* public void run() {
* phaser.arriveAndAwaitAdvance(); // await all creation
- * r.run();
- * phaser.arriveAndDeregister(); // signal completion
+ * task.run();
* }
* }.start();
* }
*
- * doSomethingOnBehalfOfWorkers();
- * phaser.arrive(); // allow threads to start
- * int p = phaser.arriveAndDeregister(); // deregister self ...
- * p = phaser.awaitAdvance(p); // ... and await arrival
- * otherActions(); // do other things while tasks execute
- * phaser.awaitAdvance(p); // await final completion
+ * // allow threads to start and deregister self
+ * phaser.arriveAndDeregister();
* }}
*
* One way to cause a set of threads to repeatedly perform actions * for a given number of iterations is to override {@code onAdvance}: * *
{@code
- * void startTasks(List list, final int iterations) {
+ * void startTasks(List tasks, final int iterations) {
* final Phaser phaser = new Phaser() {
* public boolean onAdvance(int phase, int registeredParties) {
* return phase >= iterations || registeredParties == 0;
* }
* };
* phaser.register();
- * for (Runnable r : list) {
+ * for (Runnable task : tasks) {
* phaser.register();
* new Thread() {
* public void run() {
* do {
- * r.run();
+ * task.run();
* phaser.arriveAndAwaitAdvance();
* } while(!phaser.isTerminated();
* }
@@ -172,7 +169,7 @@ import java.util.concurrent.locks.LockSu
*
* Implementation notes: This implementation restricts the
* maximum number of parties to 65535. Attempts to register additional
- * parties result in IllegalStateExceptions. However, you can and
+ * parties result in {@code IllegalStateException}. However, you can and
* should create tiered phasers to accommodate arbitrarily large sets
* of participants.
*
@@ -464,11 +461,12 @@ public class Phaser {
}
/**
- * Arrives at the barrier, and deregisters from it, without
- * waiting for others. Deregistration reduces number of parties
+ * Arrives at the barrier and deregisters from it without waiting
+ * for others. Deregistration reduces the number of parties
* required to trip the barrier in future phases. If this phaser
* has a parent, and deregistration causes this phaser to have
- * zero parties, this phaser is also deregistered from its parent.
+ * zero parties, this phaser also arrives at and is deregistered
+ * from its parent.
*
* @return the current barrier phase number upon entry to
* this method, or a negative value if terminated
@@ -521,9 +519,11 @@ public class Phaser {
/**
* Arrives at the barrier and awaits others. Equivalent in effect
- * 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.
+ * to {@code awaitAdvance(arrive())}. If you need to await with
+ * interruption or timeout, you can arrange this with an analogous
+ * construction using one of the other forms of the awaitAdvance
+ * method. If instead you need to deregister upon arrival use
+ * {@code arriveAndDeregister}.
*
* @return the phase on entry to this method
* @throws IllegalStateException if not terminated and the number
@@ -534,12 +534,15 @@ public class Phaser {
}
/**
- * Awaits the phase of the barrier to advance from the given
- * value, or returns immediately if argument is negative or this
- * barrier is terminated.
+ * Awaits the phase of the barrier to advance from the given phase
+ * value, returning immediately if the current phase of the
+ * barrier is not equal to the given phase value or this barrier
+ * is terminated.
*
* @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * @return the current barrier phase number upon exit of
+ * this method, or a negative value if terminated or
+ * argument is negative
*/
public int awaitAdvance(int phase) {
if (phase < 0)
@@ -555,13 +558,16 @@ public class Phaser {
}
/**
- * Awaits the phase of the barrier to advance from the given
- * value, or returns immediately if argument is negative or this
- * barrier is terminated, or throws InterruptedException if
- * interrupted while waiting.
+ * Awaits the phase of the barrier to advance from the given phase
+ * value, throwing {@code InterruptedException} if interrupted while
+ * waiting, or returning immediately if the current phase of the
+ * barrier is not equal to the given phase value or this barrier
+ * is terminated.
*
* @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * @return the current barrier phase number upon exit of
+ * this method, or a negative value if terminated or
+ * argument is negative
* @throws InterruptedException if thread interrupted while waiting
*/
public int awaitAdvanceInterruptibly(int phase)
@@ -578,12 +584,20 @@ public class Phaser {
}
/**
- * Awaits the phase of the barrier to advance from the given value
- * or the given timeout elapses, or returns immediately if
- * argument is negative or this barrier is terminated.
+ * Awaits the phase of the barrier to advance from the given phase
+ * value or the given timeout to elapse, throwing
+ * {@code InterruptedException} if interrupted while waiting, or
+ * returning immediately if the current phase of the barrier is not
+ * equal to the given phase value or this barrier is terminated.
*
* @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * @param timeout how long to wait before giving up, in units of
+ * {@code unit}
+ * @param unit a {@code TimeUnit} determining how to interpret the
+ * {@code timeout} parameter
+ * @return the current barrier phase number upon exit of
+ * this method, or a negative value if terminated or
+ * argument is negative
* @throws InterruptedException if thread interrupted while waiting
* @throws TimeoutException if timed out while waiting
*/
@@ -637,16 +651,6 @@ public class Phaser {
}
/**
- * Returns {@code true} if the current phase number equals the given phase.
- *
- * @param phase the phase
- * @return {@code true} if the current phase number equals the given phase
- */
- public final boolean hasPhase(int phase) {
- return phaseOf(getReconciledState()) == phase;
- }
-
- /**
* Returns the number of parties registered at this barrier.
*
* @return the number of parties
@@ -721,12 +725,8 @@ public class Phaser {
* 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 {@link #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
- * invocation of this method is in progress, thus postponing the
- * transition until those parties also arrive, re-triggering this
- * method.
+ * Otherwise, you cannot ensure lack of interference from other
+ * parties during the invocation of this method.
*
* @param phase the phase number on entering the barrier
* @param registeredParties the current number of registered parties