--- jsr166/src/jsr166y/Phaser.java 2009/08/19 17:44:45 1.32 +++ jsr166/src/jsr166y/Phaser.java 2009/08/25 16:50:24 1.45 @@ -12,80 +12,99 @@ import java.util.concurrent.atomic.Atomi import java.util.concurrent.locks.LockSupport; /** - * A reusable synchronization barrier, similar in functionality to a + * A reusable synchronization barrier, similar in functionality to * {@link java.util.concurrent.CyclicBarrier CyclicBarrier} and * {@link java.util.concurrent.CountDownLatch CountDownLatch} * but supporting more flexible usage. * - *
Registration. Unlike the case for other barriers, the + * number of parties registered to synchronize on a phaser + * may vary over time. Tasks may be registered at any time (using + * methods {@link #register}, {@link #bulkRegister}, or forms of + * constructors establishing initial numbers of parties), and + * optionally deregistered upon any arrival (using {@link + * #arriveAndDeregister}). As is the case with most basic + * synchronization constructs, registration and deregistration affect + * only internal counts; they do not establish any further internal + * bookkeeping, so tasks cannot query whether they are registered. + * (However, you can introduce such bookkeeping by subclassing this + * class.) + * + *
Synchronization. Like a {@code CyclicBarrier}, a {@code + * Phaser} may be repeatedly awaited. Method {@link + * #arriveAndAwaitAdvance} has effect analogous to {@link + * java.util.concurrent.CyclicBarrier#await CyclicBarrier.await}. Each + * generation of a {@code Phaser} has an associated phase number. The + * phase number starts at zero, and advances when all parties arrive + * at the barrier, wrapping around to zero after reaching {@code + * Integer.MAX_VALUE}. The use of phase numbers enables independent + * control of actions upon arrival at a barrier and upon awaiting + * others, via two kinds of methods that may be invoked by any + * registered party: * *
Termination. A {@code Phaser} may enter a + * termination state in which all synchronization methods + * immediately return without updating phaser state or waiting for + * advance, and indicating (via a negative phase value) that execution + * is complete. Termination is triggered when an invocation of {@code + * onAdvance} returns {@code true}. As illustrated below, when + * phasers control actions with a fixed number of iterations, it is * often convenient to override this method to cause termination when * the current phase number reaches a threshold. Method {@link * #forceTermination} is also available to abruptly release waiting * threads and allow them to terminate. * - *
Tiering. Phasers may be tiered (i.e., arranged + * in tree structures) to reduce contention. Phasers with large * numbers of parties that would otherwise experience heavy - * synchronization contention costs may instead be arranged in trees. - * This will typically greatly increase throughput even though it - * incurs somewhat greater per-operation overhead. - * - *
Monitoring. While synchronization methods may be invoked + * only by registered parties, the current state of a phaser may be + * monitored by any caller. At any given moment there are {@link + * #getRegisteredParties} parties in total, of which {@link + * #getArrivedParties} have arrived at the current phase ({@link + * #getPhase}). When the remaining ({@link #getUnarrivedParties}) + * parties arrive, the phase advances. The values returned by these + * methods may reflect transient states and so are not in general + * useful for synchronization control. Method {@link #toString} + * returns snapshots of these state queries in a form convenient for + * informal monitoring. * *
Sample usages: * @@ -95,15 +114,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,45 +135,68 @@ import java.util.concurrent.locks.LockSu * for a given number of iterations is to override {@code onAdvance}: * * {@code - * void startTasks(List* + * If the main task must later await termination, it + * may re-register and then execute a similar loop: + *list, final int iterations) { + * void startTasks(List tasks, final int iterations) { * final Phaser phaser = new Phaser() { - * public boolean onAdvance(int phase, int registeredParties) { + * protected boolean onAdvance(int phase, int registeredParties) { * return phase >= iterations || registeredParties == 0; * } * }; * phaser.register(); - * for (Runnable r : list) { + * for (final Runnable task : tasks) { * phaser.register(); * new Thread() { * public void run() { * do { - * r.run(); + * task.run(); * phaser.arriveAndAwaitAdvance(); - * } while(!phaser.isTerminated(); + * } while (!phaser.isTerminated()); * } * }.start(); * } * phaser.arriveAndDeregister(); // deregister self, don't wait * }} {@code + * // ... + * phaser.register(); + * while (!phaser.isTerminated()) + * phaser.arriveAndAwaitAdvance();}+ * + *Related constructions may be used to await particular phase numbers + * in contexts where you are sure that the phase will never wrap around + * {@code Integer.MAX_VALUE}. For example: + * + *
{@code + * void awaitPhase(Phaser phaser, int phase) { + * int p = phaser.register(); // assumes caller not already registered + * while (p < phase) { + * if (phaser.isTerminated()) + * // ... deal with unexpected termination + * else + * p = phaser.arriveAndAwaitAdvance(); + * } + * phaser.arriveAndDeregister(); + * }}+ * + * *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: + * *
{@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 @@ -203,7 +245,6 @@ public class Phaser { */ private volatile long state; - private static final int ushortBits = 16; private static final int ushortMask = 0xffff; private static final int phaseMask = 0x7fffffff; @@ -366,7 +407,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 +419,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 */ @@ -413,10 +454,11 @@ public class Phaser { /** * Arrives at the barrier, but does not wait for others. (You can - * in turn wait for others via {@link #awaitAdvance}). + * in turn wait for others via {@link #awaitAdvance}). It is an + * unenforced usage error for an unregistered party to invoke this + * method. * - * @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 */ @@ -466,10 +508,10 @@ public class Phaser { * 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 also arrives at and is deregistered - * from its parent. + * from its parent. It is an unenforced usage error for an + * unregistered party to invoke this method. * - * @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 */ @@ -523,9 +565,10 @@ public class Phaser { * 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}. + * {@code arriveAndDeregister}. It is an unenforced usage error + * for an unregistered party to invoke this method. * - * @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 */ @@ -537,10 +580,14 @@ public class Phaser { * 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. + * is terminated. It is an unenforced usage error for an + * unregistered party to invoke this method. * - * @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) @@ -557,13 +604,17 @@ public class Phaser { /** * 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 + * 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. It is an unenforced usage error for an + * unregistered party to invoke 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) @@ -581,17 +632,22 @@ public class Phaser { /** * 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 + * 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. It is an unenforced usage error for an + * unregistered party to invoke 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 +710,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 */ @@ -702,13 +758,22 @@ public class Phaser { } /** - * Overridable method to perform an action upon phase advance, and - * to control termination. This method is invoked whenever the - * barrier is tripped (and thus all other waiting parties are - * dormant). If it 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. + * 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 + * an implementation of {@code onAdvance} the values returned by + * methods such as {@code getPhase} may or may not reliably + * indicate the state to which this transition applies.) * *
The default version returns {@code true} when the number of * registered parties is zero. Normally, overrides that arrange @@ -716,11 +781,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