--- jsr166/src/jsr166y/Phaser.java 2009/08/23 13:37:08 1.35 +++ jsr166/src/jsr166y/Phaser.java 2009/08/24 15:42:51 1.41 @@ -12,85 +12,100 @@ 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. * - * * - *
  • Barrier actions, performed by the task triggering a phase - * advance, are arranged by overriding method {@link #onAdvance(int, - * int)}, which also controls termination. Overriding this method is - * similar to, but more flexible than, providing a barrier action to a - * {@code CyclicBarrier}. - * - *
  • Phasers may enter a termination state in which all - * actions 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}. When a phaser is - * controlling an action with a fixed number of iterations, it is + *

    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. * - *

  • Phasers may be tiered to reduce contention. Phasers with large + *

    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. - * - *

  • By default, {@code awaitAdvance} continues to wait even if - * the waiting thread is interrupted. And unlike the case in - * {@code CyclicBarrier}, exceptions encountered while tasks wait - * interruptibly or with timeout do not change the state of the - * barrier. If necessary, you can perform any associated recovery - * within handlers of those exceptions, often after invoking - * {@code forceTermination}. - * - *
  • Phasers may be used to coordinate tasks executing in a {@link - * ForkJoinPool}, which will ensure sufficient parallelism to execute - * tasks when others are blocked waiting for a phase to advance. - * - * + * synchronization contention costs may instead be set up so that + * groups of sub-phasers share a common parent. This may greatly + * increase throughput even though it incurs 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; thus, this value is always + * greater than zero if there are any registered parties. 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: * @@ -123,7 +138,7 @@ import java.util.concurrent.locks.LockSu * 

     {@code
  * 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;
  *     }
  *   };
@@ -142,6 +157,33 @@ import java.util.concurrent.locks.LockSu
  *   phaser.arriveAndDeregister(); // deregister self, don't wait
  * }}
    * + * If the main task must later await termination, it + * may re-register and then execute a similar loop: + * 
     {@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 @@ -208,7 +250,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; @@ -418,7 +459,9 @@ 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 arrival phase number, or a negative value if terminated * @throws IllegalStateException if not terminated and the number @@ -470,7 +513,8 @@ 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 arrival phase number, or a negative value if terminated * @throws IllegalStateException if not terminated and the number @@ -526,7 +570,8 @@ 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 arrival phase number, or a negative number if terminated * @throws IllegalStateException if not terminated and the number @@ -540,7 +585,8 @@ 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 an arrival phase number, or negative value if * terminated; this argument is normally the value returned by a @@ -563,10 +609,11 @@ 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. + * 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 @@ -590,10 +637,12 @@ 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. + * 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 @@ -666,8 +715,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 */