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.4 by dl, Sat Sep 6 13:19:17 2008 UTC vs.
Revision 1.9 by jsr166, Mon Jan 5 09:11:26 2009 UTC

# Line 5 | Line 5
5   */
6  
7   package jsr166y;
8 +
9   import java.util.concurrent.*;
10   import java.util.concurrent.atomic.*;
11   import java.util.concurrent.locks.LockSupport;
# Line 13 | Line 14 | import java.lang.reflect.*;
14  
15   /**
16   * A reusable synchronization barrier, similar in functionality to a
17 < * {@link java.util.concurrent.CyclicBarrier} and {@link
18 < * java.util.concurrent.CountDownLatch} but supporting more flexible
19 < * usage.
17 > * {@link java.util.concurrent.CyclicBarrier CyclicBarrier} and
18 > * {@link java.util.concurrent.CountDownLatch CountDownLatch}
19 > * but supporting more flexible usage.
20   *
21   * <ul>
22   *
# Line 25 | Line 26 | import java.lang.reflect.*;
26   * basic synchronization constructs, registration and deregistration
27   * affect only internal counts; they do not establish any further
28   * internal bookkeeping, so tasks cannot query whether they are
29 < * registered. (However, you can introduce such bookkeeping in by
29 > * registered. (However, you can introduce such bookkeeping by
30   * subclassing this class.)
31   *
32   * <li> Each generation has an associated phase value, starting at
33   * zero, and advancing when all parties reach the barrier (wrapping
34 < * around to zero after reaching <tt>Integer.MAX_VALUE</tt>).
34 > * around to zero after reaching {@code Integer.MAX_VALUE}).
35   *
36   * <li> Like a CyclicBarrier, a Phaser may be repeatedly awaited.
37 < * Method <tt>arriveAndAwaitAdvance</tt> has effect analogous to
38 < * <tt>CyclicBarrier.await</tt>.  However, Phasers separate two
37 > * Method {@code arriveAndAwaitAdvance} has effect analogous to
38 > * {@code CyclicBarrier.await}.  However, Phasers separate two
39   * aspects of coordination, that may also be invoked independently:
40   *
41   * <ul>
42   *
43 < *   <li> Arriving at a barrier. Methods <tt>arrive</tt> and
44 < *       <tt>arriveAndDeregister</tt> do not block, but return
43 > *   <li> Arriving at a barrier. Methods {@code arrive} and
44 > *       {@code arriveAndDeregister} do not block, but return
45   *       the phase value current upon entry to the method.
46   *
47 < *   <li> Awaiting others. Method <tt>awaitAdvance</tt> requires an
47 > *   <li> Awaiting others. Method {@code awaitAdvance} requires an
48   *       argument indicating the entry phase, and returns when the
49   *       barrier advances to a new phase.
50   * </ul>
# Line 51 | Line 52 | import java.lang.reflect.*;
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 <tt>onAdvance</tt>, that also controls termination.
56 < * Overriding this method may be used to similar but more flecible
55 > * method {@code 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 CyclicBarrier.
58   *
59   * <li> Phasers may enter a <em>termination</em> state in which all
60   * await actions immediately return, indicating (via a negative phase
61   * value) that execution is complete.  Termination is triggered by
62 < * executing the overridable <tt>onAdvance</tt> method that is invoked
62 > * executing the overridable {@code onAdvance} method that is invoked
63   * each time the barrier is about to be tripped. 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
67 < * <tt>forceTermination</tt> is also available to abruptly release
67 > * {@code forceTermination} is also available to abruptly release
68   * waiting threads and allow them to terminate.
69   *
70   * <li> Phasers may be tiered to reduce contention. Phasers with large
# Line 72 | Line 73 | import java.lang.reflect.*;
73   * This will typically greatly increase throughput even though it
74   * incurs somewhat greater per-operation overhead.
75   *
76 < * <li> By default, <tt>awaitAdvance</tt> continues to wait even if
76 > * <li> By default, {@code awaitAdvance} continues to wait even if
77   * the waiting thread is interrupted. And unlike the case in
78   * CyclicBarriers, exceptions encountered while tasks wait
79   * interruptibly or with timeout do not change the state of the
80   * barrier. If necessary, you can perform any associated recovery
81   * within handlers of those exceptions, often after invoking
82 < * <tt>forceTermination</tt>.
82 > * {@code forceTermination}.
83   *
84   * </ul>
85   *
86   * <p><b>Sample usages:</b>
87   *
88 < * <p>A Phaser may be used instead of a <tt>CountdownLatch</tt> to control
88 > * <p>A Phaser may be used instead of a {@code CountDownLatch} to control
89   * a one-shot action serving a variable number of parties. The typical
90   * idiom is for the method setting this up to first register, then
91   * start the actions, then deregister, as in:
# Line 102 | Line 103 | import java.lang.reflect.*;
103   *        }
104   *      }.start();
105   *   }
106 + *
107 + *   doSomethingOnBehalfOfWorkers();
108   *   phaser.arrive(); // allow threads to start
109 < *   int p = phaser.arriveAndDeregister(); // deregister self
109 > *   int p = phaser.arriveAndDeregister(); // deregister self  ...
110 > *   p = phaser.awaitAdvance(p); // ... and await arrival
111   *   otherActions(); // do other things while tasks execute
112 < *   phaser.awaitAdvance(p); // wait for all tasks to arrive
112 > *   phaser.awaitAdvance(p); // await final completion
113   * }
114   * </pre>
115   *
116   * <p>One way to cause a set of threads to repeatedly perform actions
117 < * for a given number of iterations is to override <tt>onAdvance</tt>:
117 > * for a given number of iterations is to override {@code onAdvance}:
118   *
119   * <pre>
120   *  void startTasks(List&lt;Runnable&gt; list, final int iterations) {
# Line 160 | Line 164 | import java.lang.reflect.*;
164   *  build(new Task[n], 0, n, new Phaser());
165   * </pre>
166   *
167 < * The best value of <tt>TASKS_PER_PHASER</tt> depends mainly on
167 > * The best value of {@code TASKS_PER_PHASER} depends mainly on
168   * expected barrier synchronization rates. A value as low as four may
169   * be appropriate for extremely small per-barrier task bodies (thus
170   * high rates), or up to hundreds for extremely large ones.
# Line 192 | Line 196 | public class Phaser {
196       * However, to efficiently maintain atomicity, these values are
197       * packed into a single (atomic) long. Termination uses the sign
198       * bit of 32 bit representation of phase, so phase is set to -1 on
199 <     * termination. Good performace relies on keeping state decoding
199 >     * termination. Good performance relies on keeping state decoding
200       * and encoding simple, and keeping race windows short.
201       *
202       * Note: there are some cheats in arrive() that rely on unarrived
# Line 505 | Line 509 | public class Phaser {
509  
510      /**
511       * Arrives at the barrier and awaits others. Equivalent in effect
512 <     * to <tt>awaitAdvance(arrive())</tt>.  If you instead need to
512 >     * to {@code awaitAdvance(arrive())}.  If you instead need to
513       * await with interruption of timeout, and/or deregister upon
514       * arrival, you can arrange them using analogous constructions.
515       * @return the phase on entry to this method
# Line 538 | Line 542 | public class Phaser {
542  
543      /**
544       * Awaits the phase of the barrier to advance from the given
545 <     * value, or returns immediately if argumet is negative or this
545 >     * value, or returns immediately if argument is negative or this
546       * barrier is terminated, or throws InterruptedException if
547       * interrupted while waiting.
548       * @param phase the phase on entry to this method
# Line 605 | Line 609 | public class Phaser {
609  
610      /**
611       * Returns the current phase number. The maximum phase number is
612 <     * <tt>Integer.MAX_VALUE</tt>, after which it restarts at
612 >     * {@code Integer.MAX_VALUE}, after which it restarts at
613       * zero. Upon termination, the phase number is negative.
614       * @return the phase number, or a negative value if terminated
615       */
# Line 614 | Line 618 | public class Phaser {
618      }
619  
620      /**
621 <     * Returns true if the current phase number equals the given phase.
621 >     * Returns {@code true} if the current phase number equals the given phase.
622       * @param phase the phase
623 <     * @return true if the current phase number equals the given phase.
623 >     * @return {@code true} if the current phase number equals the given phase
624       */
625      public final boolean hasPhase(int phase) {
626          return phaseOf(getReconciledState()) == phase;
# Line 650 | Line 654 | public class Phaser {
654  
655      /**
656       * Returns the parent of this phaser, or null if none.
657 <     * @return the parent of this phaser, or null if none.
657 >     * @return the parent of this phaser, or null if none
658       */
659      public Phaser getParent() {
660          return parent;
# Line 659 | Line 663 | public class Phaser {
663      /**
664       * Returns the root ancestor of this phaser, which is the same as
665       * this phaser if it has no parent.
666 <     * @return the root ancestor of this phaser.
666 >     * @return the root ancestor of this phaser
667       */
668      public Phaser getRoot() {
669          return root;
670      }
671  
672      /**
673 <     * Returns true if this barrier has been terminated.
674 <     * @return true if this barrier has been terminated
673 >     * Returns {@code true} if this barrier has been terminated.
674 >     * @return {@code true} if this barrier has been terminated
675       */
676      public boolean isTerminated() {
677          return getPhase() < 0;
# Line 679 | Line 683 | public class Phaser {
683       * barrier is tripped (and thus all other waiting parties are
684       * dormant). If it returns true, then, rather than advance the
685       * phase number, this barrier will be set to a final termination
686 <     * state, and subsequent calls to <tt>isTerminated</tt> will
686 >     * state, and subsequent calls to {@code isTerminated} will
687       * return true.
688       *
689       * <p> The default version returns true when the number of
# Line 690 | Line 694 | public class Phaser {
694       * <p> You may override this method to perform an action with side
695       * effects visible to participating tasks, but it is in general
696       * only sensible to do so in designs where all parties register
697 <     * before any arrive, and all <tt>awaitAdvance</tt> at each phase.
697 >     * before any arrive, and all {@code awaitAdvance} at each phase.
698       * Otherwise, you cannot ensure lack of interference. In
699       * particular, this method may be invoked more than once per
700       * transition if other parties successfully register while the
# Line 699 | Line 703 | public class Phaser {
703       * method.
704       *
705       * @param phase the phase number on entering the barrier
706 <     * @param registeredParties the current number of registered
707 <     * parties.
704 <     * @return true if this barrier should terminate
706 >     * @param registeredParties the current number of registered parties
707 >     * @return {@code true} if this barrier should terminate
708       */
709      protected boolean onAdvance(int phase, int registeredParties) {
710          return registeredParties <= 0;
# Line 710 | Line 713 | public class Phaser {
713      /**
714       * Returns a string identifying this phaser, as well as its
715       * state.  The state, in brackets, includes the String {@code
716 <     * "phase ="} followed by the phase number, {@code "parties ="}
716 >     * "phase = "} followed by the phase number, {@code "parties = "}
717       * followed by the number of registered parties, and {@code
718 <     * "arrived ="} followed by the number of arrived parties
718 >     * "arrived = "} followed by the number of arrived parties.
719       *
720       * @return a string identifying this barrier, as well as its state
721       */
722      public String toString() {
723          long s = getReconciledState();
724 <        return super.toString() + "[phase = " + phaseOf(s) + " parties = " + partiesOf(s) + " arrived = " + arrivedOf(s) + "]";
724 >        return super.toString() +
725 >            "[phase = " + phaseOf(s) +
726 >            " parties = " + partiesOf(s) +
727 >            " arrived = " + arrivedOf(s) + "]";
728      }
729  
730      // methods for waiting

Diff Legend

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