ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166y/Phaser.java
(Generate patch)

Comparing jsr166/src/jsr166y/Phaser.java (file contents):
Revision 1.25 by jsr166, Sun Aug 2 17:02:06 2009 UTC vs.
Revision 1.33 by jsr166, Wed Aug 19 18:00:55 2009 UTC

# Line 32 | Line 32 | import java.util.concurrent.locks.LockSu
32   * zero, and advancing when all parties reach the barrier (wrapping
33   * around to zero after reaching {@code Integer.MAX_VALUE}).
34   *
35 < * <li> Like a {@code CyclicBarrier}, a Phaser may be repeatedly
35 > * <li> Like a {@code CyclicBarrier}, a phaser may be repeatedly
36   * awaited.  Method {@link #arriveAndAwaitAdvance} has effect
37   * analogous to {@link java.util.concurrent.CyclicBarrier#await
38   * CyclicBarrier.await}.  However, phasers separate two aspects of
39 < * coordination, that may also be invoked independently:
39 > * coordination, which may also be invoked independently:
40   *
41   * <ul>
42   *
# Line 51 | Line 51 | import java.util.concurrent.locks.LockSu
51   *
52   *
53   * <li> Barrier actions, performed by the task triggering a phase
54 < * advance while others may be waiting, are arranged by overriding
55 < * method {@link #onAdvance}, that also controls termination.
56 < * Overriding this method may be used to similar but more flexible
57 < * effect as providing a barrier action to a {@code CyclicBarrier}.
54 > * advance, are arranged by overriding method {@link #onAdvance(int,
55 > * int)}, which also controls termination. Overriding this method is
56 > * similar to, but more flexible than, providing a barrier action to a
57 > * {@code CyclicBarrier}.
58   *
59   * <li> Phasers may enter a <em>termination</em> state in which all
60   * actions immediately return without updating phaser state or waiting
61   * for advance, and indicating (via a negative phase value) that
62 < * execution is complete.  Termination is triggered by executing the
63 < * overridable {@code onAdvance} method that is invoked each time the
64 < * barrier is about to be tripped. When a phaser is controlling an
65 < * action with a fixed number of iterations, it is often convenient to
66 < * override this method to cause termination when the current phase
67 < * number reaches a threshold. Method {@link #forceTermination} is also
68 < * available to abruptly release waiting threads and allow them to
69 < * terminate.
62 > * execution is complete.  Termination is triggered when an invocation
63 > * of {@code onAdvance} returns {@code true}.  When a phaser is
64 > * controlling an action with a fixed number of iterations, it is
65 > * often convenient to override this method to cause termination when
66 > * the current phase number reaches a threshold. Method {@link
67 > * #forceTermination} is also available to abruptly release waiting
68 > * threads and allow them to terminate.
69   *
70   * <li> Phasers may be tiered to reduce contention. Phasers with large
71   * numbers of parties that would otherwise experience heavy
# Line 82 | Line 81 | import java.util.concurrent.locks.LockSu
81   * within handlers of those exceptions, often after invoking
82   * {@code forceTermination}.
83   *
84 < * <li>Phasers ensure lack of starvation when used by ForkJoinTasks.
84 > * <li>Phasers may be used to coordinate tasks executing in a {@link
85 > * ForkJoinPool}, which will ensure sufficient parallelism to execute
86 > * tasks when others are blocked waiting for a phase to advance.
87   *
88   * </ul>
89   *
# Line 94 | Line 95 | import java.util.concurrent.locks.LockSu
95   * first register, then start the actions, then deregister, as in:
96   *
97   *  <pre> {@code
98 < * void runTasks(List<Runnable> list) {
98 > * void runTasks(List<Runnable> tasks) {
99   *   final Phaser phaser = new Phaser(1); // "1" to register self
100 < *   for (Runnable r : list) {
100 > *   // create and start threads
101 > *   for (Runnable task : tasks) {
102   *     phaser.register();
103   *     new Thread() {
104   *       public void run() {
105   *         phaser.arriveAndAwaitAdvance(); // await all creation
106 < *         r.run();
105 < *         phaser.arriveAndDeregister();   // signal completion
106 > *         task.run();
107   *       }
108   *     }.start();
109   *   }
110   *
111 < *   doSomethingOnBehalfOfWorkers();
112 < *   phaser.arrive(); // allow threads to start
112 < *   int p = phaser.arriveAndDeregister(); // deregister self  ...
113 < *   p = phaser.awaitAdvance(p); // ... and await arrival
114 < *   otherActions(); // do other things while tasks execute
115 < *   phaser.awaitAdvance(p); // await final completion
111 > *   // allow threads to start and deregister self
112 > *   phaser.arriveAndDeregister();
113   * }}</pre>
114   *
115   * <p>One way to cause a set of threads to repeatedly perform actions
116   * for a given number of iterations is to override {@code onAdvance}:
117   *
118   *  <pre> {@code
119 < * void startTasks(List<Runnable> list, final int iterations) {
119 > * void startTasks(List<Runnable> tasks, final int iterations) {
120   *   final Phaser phaser = new Phaser() {
121   *     public boolean onAdvance(int phase, int registeredParties) {
122   *       return phase >= iterations || registeredParties == 0;
123   *     }
124   *   };
125   *   phaser.register();
126 < *   for (Runnable r : list) {
126 > *   for (Runnable task : tasks) {
127   *     phaser.register();
128   *     new Thread() {
129   *       public void run() {
130   *         do {
131 < *           r.run();
131 > *           task.run();
132   *           phaser.arriveAndAwaitAdvance();
133   *         } while(!phaser.isTerminated();
134   *       }
# Line 172 | Line 169 | import java.util.concurrent.locks.LockSu
169   *
170   * <p><b>Implementation notes</b>: This implementation restricts the
171   * maximum number of parties to 65535. Attempts to register additional
172 < * parties result in IllegalStateExceptions. However, you can and
172 > * parties result in {@code IllegalStateException}. However, you can and
173   * should create tiered phasers to accommodate arbitrarily large sets
174   * of participants.
175   *
# Line 464 | Line 461 | public class Phaser {
461      }
462  
463      /**
464 <     * Arrives at the barrier, and deregisters from it, without
465 <     * waiting for others. Deregistration reduces number of parties
464 >     * Arrives at the barrier and deregisters from it without waiting
465 >     * for others. Deregistration reduces the number of parties
466       * required to trip the barrier in future phases.  If this phaser
467       * has a parent, and deregistration causes this phaser to have
468 <     * zero parties, this phaser is also deregistered from its parent.
468 >     * zero parties, this phaser also arrives at and is deregistered
469 >     * from its parent.
470       *
471       * @return the current barrier phase number upon entry to
472       * this method, or a negative value if terminated
# Line 521 | Line 519 | public class Phaser {
519  
520      /**
521       * Arrives at the barrier and awaits others. Equivalent in effect
522 <     * to {@code awaitAdvance(arrive())}.  If you instead need to
523 <     * await with interruption of timeout, and/or deregister upon
524 <     * arrival, you can arrange them using analogous constructions.
522 >     * to {@code awaitAdvance(arrive())}.  If you need to await with
523 >     * interruption or timeout, you can arrange this with an analogous
524 >     * construction using one of the other forms of the awaitAdvance
525 >     * method.  If instead you need to deregister upon arrival use
526 >     * {@code arriveAndDeregister}.
527       *
528       * @return the phase on entry to this method
529       * @throws IllegalStateException if not terminated and the number
# Line 534 | Line 534 | public class Phaser {
534      }
535  
536      /**
537 <     * Awaits the phase of the barrier to advance from the given
538 <     * value, or returns immediately if argument is negative or this
539 <     * barrier is terminated.
537 >     * Awaits the phase of the barrier to advance from the given phase
538 >     * value, returning immediately if the current phase of the
539 >     * barrier is not equal to the given phase value or this barrier
540 >     * is terminated.
541       *
542       * @param phase the phase on entry to this method
543       * @return the phase on exit from this method
# Line 555 | Line 556 | public class Phaser {
556      }
557  
558      /**
559 <     * Awaits the phase of the barrier to advance from the given
560 <     * value, or returns immediately if argument is negative or this
561 <     * barrier is terminated, or throws InterruptedException if
562 <     * interrupted while waiting.
559 >     * Awaits the phase of the barrier to advance from the given phase
560 >     * value, throwing {@code InterruptedException} if interrupted while
561 >     * waiting, or returning immediately if the current phase of the
562 >     * barrier is not equal to the given phase value or this barrier
563 >     * is terminated.
564       *
565       * @param phase the phase on entry to this method
566       * @return the phase on exit from this method
# Line 578 | Line 580 | public class Phaser {
580      }
581  
582      /**
583 <     * Awaits the phase of the barrier to advance from the given value
584 <     * or the given timeout elapses, or returns immediately if
585 <     * argument is negative or this barrier is terminated.
583 >     * Awaits the phase of the barrier to advance from the given phase
584 >     * value or the given timeout to elapse, throwing
585 >     * {@code InterruptedException} if interrupted while waiting, or
586 >     * returning immediately if the current phase of the barrier is not
587 >     * equal to the given phase value or this barrier is terminated.
588       *
589       * @param phase the phase on entry to this method
590 +     * @param timeout how long to wait before giving up, in units of
591 +     *        {@code unit}
592 +     * @param unit a {@code TimeUnit} determining how to interpret the
593 +     *        {@code timeout} parameter
594       * @return the phase on exit from this method
595       * @throws InterruptedException if thread interrupted while waiting
596       * @throws TimeoutException if timed out while waiting
# Line 637 | Line 645 | public class Phaser {
645      }
646  
647      /**
640 –     * Returns {@code true} if the current phase number equals the given phase.
641 –     *
642 –     * @param phase the phase
643 –     * @return {@code true} if the current phase number equals the given phase
644 –     */
645 –    public final boolean hasPhase(int phase) {
646 –        return phaseOf(getReconciledState()) == phase;
647 –    }
648 –
649 –    /**
648       * Returns the number of parties registered at this barrier.
649       *
650       * @return the number of parties
# Line 721 | Line 719 | public class Phaser {
719       * effects visible to participating tasks, but it is in general
720       * only sensible to do so in designs where all parties register
721       * before any arrive, and all {@link #awaitAdvance} at each phase.
722 <     * Otherwise, you cannot ensure lack of interference. In
723 <     * particular, this method may be invoked more than once per
726 <     * transition if other parties successfully register while the
727 <     * invocation of this method is in progress, thus postponing the
728 <     * transition until those parties also arrive, re-triggering this
729 <     * method.
722 >     * Otherwise, you cannot ensure lack of interference from other
723 >     * parties during the invocation of this method.
724       *
725       * @param phase the phase number on entering the barrier
726       * @param registeredParties the current number of registered parties

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines