--- jsr166/src/jsr166y/Phaser.java 2009/08/19 17:44:45 1.32 +++ jsr166/src/jsr166y/Phaser.java 2009/08/23 20:12:24 1.36 @@ -19,18 +19,22 @@ import java.util.concurrent.locks.LockSu * *
Sample usages: @@ -95,15 +108,15 @@ import java.util.concurrent.locks.LockSu * first register, then start the actions, then deregister, as in: * *
{@code - * void runTasks(Listlist) { + * void runTasks(List tasks) { * final Phaser phaser = new Phaser(1); // "1" to register self * // create and start threads - * for (Runnable r : list) { + * for (Runnable task : tasks) { * phaser.register(); * new Thread() { * public void run() { * phaser.arriveAndAwaitAdvance(); // await all creation - * r.run(); + * task.run(); * } * }.start(); * } @@ -116,19 +129,19 @@ import java.util.concurrent.locks.LockSu * for a given number of iterations is to override {@code onAdvance}: * * {@code - * void startTasks(Listlist, 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(); * } @@ -366,7 +379,7 @@ public class Phaser { /** * Adds a new unarrived party to this phaser. * - * @return the current barrier phase number upon registration + * @return the arrival phase number to which this registration applied * @throws IllegalStateException if attempting to register more * than the maximum supported number of parties */ @@ -378,7 +391,7 @@ public class Phaser { * Adds the given number of new unarrived parties to this phaser. * * @param parties the number of parties required to trip barrier - * @return the current barrier phase number upon registration + * @return the arrival phase number to which this registration applied * @throws IllegalStateException if attempting to register more * than the maximum supported number of parties */ @@ -415,8 +428,7 @@ public class Phaser { * Arrives at the barrier, but does not wait for others. (You can * in turn wait for others via {@link #awaitAdvance}). * - * @return the barrier phase number upon entry to this method, or a - * negative value if terminated + * @return the arrival phase number, or a negative value if terminated * @throws IllegalStateException if not terminated and the number * of unarrived parties would become negative */ @@ -468,8 +480,7 @@ public class Phaser { * 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 + * @return the arrival phase number, or a negative value if terminated * @throws IllegalStateException if not terminated and the number * of registered or unarrived parties would become negative */ @@ -525,7 +536,7 @@ public class Phaser { * method. If instead you need to deregister upon arrival use * {@code arriveAndDeregister}. * - * @return the phase on entry to this method + * @return the arrival phase number, or a negative number if terminated * @throws IllegalStateException if not terminated and the number * of unarrived parties would become negative */ @@ -539,8 +550,11 @@ public class Phaser { * 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 phase an arrival phase number, or negative value if + * terminated; this argument is normally the value returned by a + * previous call to {@code arrive} or its variants + * @return the next arrival phase number, or a negative value + * if terminated or argument is negative */ public int awaitAdvance(int phase) { if (phase < 0) @@ -562,8 +576,11 @@ public class Phaser { * 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 phase an arrival phase number, or negative value if + * terminated; this argument is normally the value returned by a + * previous call to {@code arrive} or its variants + * @return the next arrival phase number, or a negative value + * if terminated or argument is negative * @throws InterruptedException if thread interrupted while waiting */ public int awaitAdvanceInterruptibly(int phase) @@ -586,12 +603,15 @@ public class Phaser { * 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 + * @param phase an arrival phase number, or negative value if + * terminated; this argument is normally the value returned by a + * previous call to {@code arrive} or its variants * @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 phase on exit from this method + * @return the next arrival phase number, or a negative value + * if terminated or argument is negative * @throws InterruptedException if thread interrupted while waiting * @throws TimeoutException if timed out while waiting */ @@ -654,8 +674,8 @@ public class Phaser { } /** - * Returns the number of parties that have arrived at the current - * phase of this barrier. + * Returns the number of registered parties that have arrived at + * the current phase of this barrier. * * @return the number of arrived parties */