--- jsr166/src/jsr166y/Phaser.java 2009/08/19 15:23:18 1.30 +++ jsr166/src/jsr166y/Phaser.java 2009/08/19 23:05:32 1.34 @@ -95,15 +95,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 +116,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(); * } @@ -169,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. * @@ -540,7 +540,9 @@ public class Phaser { * 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) @@ -557,13 +559,15 @@ public class Phaser { /** * Awaits the phase of the barrier to advance from the given phase - * value, throwing InterruptedException if interrupted while + * 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 + * 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) @@ -581,13 +585,19 @@ public class Phaser { /** * Awaits the phase of the barrier to advance from the given phase - * value or the given timeout elapses, throwing - * 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. + * 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 */