--- jsr166/src/jsr166y/Phaser.java 2009/08/24 18:37:15 1.42 +++ jsr166/src/jsr166y/Phaser.java 2009/08/25 16:32:28 1.44 @@ -188,19 +188,16 @@ import java.util.concurrent.locks.LockSu * Task class with a constructor accepting a phaser that * it registers for upon construction: *
{@code - * void build(Task[] actions, int lo, int hi, Phaser b) { - * int step = (hi - lo) / TASKS_PER_PHASER; - * if (step > 1) { - * int i = lo; - * while (i < hi) { - * int r = Math.min(i + step, hi); - * build(actions, i, r, new Phaser(b)); - * i = r; + * void build(Task[] actions, int lo, int hi, Phaser ph) { + * if (hi - lo > TASKS_PER_PHASER) { + * for (int i = lo; i < hi; i += TASKS_PER_PHASER) { + * int j = Math.min(i + TASKS_PER_PHASER, hi); + * build(actions, i, j, new Phaser(ph)); * } * } else { * for (int i = lo; i < hi; ++i) - * actions[i] = new Task(b); - * // assumes new Task(b) performs b.register() + * actions[i] = new Task(ph); + * // assumes new Task(ph) performs ph.register() * } * } * // .. initially called, for n tasks via @@ -762,16 +759,16 @@ public class Phaser { } /** - * Overridable method to perform an action upon phase advance, and - * to control termination. This method is invoked upon arrival of - * the party tripping the barrier (when all other waiting parties - * are dormant). If this method returns {@code true}, then, - * rather than advance the phase number, this barrier will be set - * to a final termination state, and subsequent calls to {@link - * #isTerminated} will return true. Any (unchecked) Exception or - * Error thrown by an invocation of this method is propagated to - * the party attempting to trip the barrier, in which case no - * advance occurs. + * Overridable method to perform an action upon impending phase + * advance, and to control termination. This method is invoked + * upon arrival of the party tripping the barrier (when all other + * waiting parties are dormant). If this method returns {@code + * true}, then, rather than advance the phase number, this barrier + * will be set to a final termination state, and subsequent calls + * to {@link #isTerminated} will return true. Any (unchecked) + * Exception or Error thrown by an invocation of this method is + * propagated to the party attempting to trip the barrier, in + * which case no advance occurs. * *The arguments to this method provide the state of the phaser * prevailing for the current transition. (When called from within @@ -785,11 +782,12 @@ public class Phaser { * property. * *
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 from other - * parties during the invocation of this method. + * effects visible to participating tasks, but doing so requires + * care: Method {@code onAdvance} may be invoked more than once + * per transition. Further, unless all parties register before + * any arrive, and all {@link #awaitAdvance} at each phase, then + * 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