{@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();
* }
@@ -140,7 +137,7 @@ import java.util.concurrent.locks.LockSu
* phaser.arriveAndDeregister(); // deregister self, don't wait
* }}
*
- * To create a set of tasks using a tree of phasers, + *
To create a set of tasks using a tree of phasers, * you could use code of the following form, assuming a * Task class with a constructor accepting a phaser that * it registers for upon construction: @@ -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 @@ -712,21 +716,17 @@ public class Phaser { * termination state, and subsequent calls to {@link #isTerminated} * will return true. * - *
The default version returns {@code true} when the number of + *
The default version returns {@code true} when the number of * registered parties is zero. Normally, overrides that arrange * termination for other reasons should also preserve this * property. * - *
You may override this method to perform an action with side + *
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 {@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