--- jsr166/src/jsr166y/Phaser.java 2009/08/05 00:54:11 1.26 +++ jsr166/src/jsr166y/Phaser.java 2009/08/24 12:15:46 1.39 @@ -12,79 +12,96 @@ 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 while others may be waiting, are arranged by overriding - * method {@link #onAdvance}, that also controls termination. - * Overriding this method may be used to similar but more flexible - * effect as 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 by executing the - * overridable {@code onAdvance} method that is invoked each time the - * barrier is about to be tripped. When a phaser is controlling an - * action 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. + *

    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 ensure lack of starvation when used by ForkJoinTasks. - * - * + * 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}, where {@link #getArrivedParties} have + * arrived at the current phase ({@link #getPhase}). When the + * remaining {@link #getUnarrivedParties}) arrive, the phase + * advances. Method {@link #toString} returns snapshots of these state + * queries in a form convenient for informal monitoring. * *

    Sample usages: * @@ -94,44 +111,40 @@ import java.util.concurrent.locks.LockSu * first register, then start the actions, then deregister, as in: * * 

     {@code
- * void runTasks(List list) {
+ * void runTasks(List tasks) {
  *   final Phaser phaser = new Phaser(1); // "1" to register self
- *   for (Runnable r : list) {
+ *   // create and start threads
+ *   for (Runnable task : tasks) {
  *     phaser.register();
  *     new Thread() {
  *       public void run() {
  *         phaser.arriveAndAwaitAdvance(); // await all creation
- *         r.run();
- *         phaser.arriveAndDeregister();   // signal completion
+ *         task.run();
  *       }
  *     }.start();
  *   }
  *
- *   doSomethingOnBehalfOfWorkers();
- *   phaser.arrive(); // allow threads to start
- *   int p = phaser.arriveAndDeregister(); // deregister self  ...
- *   p = phaser.awaitAdvance(p); // ... and await arrival
- *   otherActions(); // do other things while tasks execute
- *   phaser.awaitAdvance(p); // await final completion
+ *   // allow threads to start and deregister self
+ *   phaser.arriveAndDeregister();
  * }}
    * *

    One way to cause a set of threads to repeatedly perform actions * for a given number of iterations is to override {@code onAdvance}: * * 

     {@code
- * void startTasks(List 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 (Runnable task : tasks) {
  *     phaser.register();
  *     new Thread() {
  *       public void run() {
  *         do {
- *           r.run();
+ *           task.run();
  *           phaser.arriveAndAwaitAdvance();
  *         } while(!phaser.isTerminated();
  *       }
@@ -140,6 +153,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 @@ -172,7 +212,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. * @@ -369,7 +409,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 */ @@ -381,7 +421,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 */ @@ -416,10 +456,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 */ @@ -464,14 +505,15 @@ public class Phaser { } /** - * Arrives at the barrier, and deregisters from it, without - * waiting for others. Deregistration reduces number of parties + * Arrives at the barrier and deregisters from it without waiting + * for others. Deregistration reduces the number of parties * 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 is also deregistered from its parent. + * zero parties, this phaser also arrives at and is deregistered + * 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 */ @@ -521,11 +563,14 @@ public class Phaser { /** * Arrives at the barrier and awaits others. Equivalent in effect - * to {@code awaitAdvance(arrive())}. If you instead need to - * await with interruption of timeout, and/or deregister upon - * arrival, you can arrange them using analogous constructions. + * to {@code awaitAdvance(arrive())}. If you need to await with + * 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}. 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 */ @@ -534,12 +579,17 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given - * value, or returns immediately if argument is negative or this - * barrier is terminated. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * 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. 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 */ public int awaitAdvance(int phase) { if (phase < 0) @@ -555,13 +605,18 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given - * value, or returns immediately if argument is negative or this - * barrier is terminated, or throws InterruptedException if - * interrupted while waiting. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * 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. 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) @@ -578,12 +633,23 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given value - * or the given timeout elapses, or returns immediately if - * argument is negative or this barrier is terminated. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * 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. 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 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 */ @@ -637,16 +703,6 @@ public class Phaser { } /** - * Returns {@code true} if the current phase number equals the given phase. - * - * @param phase the phase - * @return {@code true} if the current phase number equals the given phase - */ - public final boolean hasPhase(int phase) { - return phaseOf(getReconciledState()) == phase; - } - - /** * Returns the number of parties registered at this barrier. * * @return the number of parties @@ -656,8 +712,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 */ @@ -721,12 +777,8 @@ public class Phaser { * 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. In - * particular, this method may be invoked more than once per - * transition if other parties successfully register while the - * invocation of this method is in progress, thus postponing the - * transition until those parties also arrive, re-triggering this - * method. + * Otherwise, 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