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.9 by jsr166, Mon Jan 5 09:11:26 2009 UTC vs.
Revision 1.47 by dl, Wed Jul 7 19:52:32 2010 UTC

# Line 7 | Line 7
7   package jsr166y;
8  
9   import java.util.concurrent.*;
10 < import java.util.concurrent.atomic.*;
10 >
11 > import java.util.concurrent.atomic.AtomicReference;
12   import java.util.concurrent.locks.LockSupport;
12 import sun.misc.Unsafe;
13 import java.lang.reflect.*;
13  
14   /**
15 < * A reusable synchronization barrier, similar in functionality to a
15 > * A reusable synchronization barrier, similar in functionality to
16   * {@link java.util.concurrent.CyclicBarrier CyclicBarrier} and
17   * {@link java.util.concurrent.CountDownLatch CountDownLatch}
18   * but supporting more flexible usage.
19   *
20 < * <ul>
21 < *
22 < * <li> The number of parties synchronizing on a phaser may vary over
23 < * time.  A task may register to be a party at any time, and may
24 < * deregister upon arriving at the barrier.  As is the case with most
25 < * basic synchronization constructs, registration and deregistration
26 < * affect only internal counts; they do not establish any further
27 < * internal bookkeeping, so tasks cannot query whether they are
28 < * registered. (However, you can introduce such bookkeeping by
29 < * subclassing this class.)
30 < *
31 < * <li> Each generation has an associated phase value, starting at
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 CyclicBarrier, a Phaser may be repeatedly awaited.
36 < * Method {@code arriveAndAwaitAdvance} has effect analogous to
37 < * {@code CyclicBarrier.await}.  However, Phasers separate two
38 < * aspects of coordination, that may also be invoked independently:
20 > * <p> <b>Registration.</b> Unlike the case for other barriers, the
21 > * number of parties <em>registered</em> to synchronize on a phaser
22 > * may vary over time.  Tasks may be registered at any time (using
23 > * methods {@link #register}, {@link #bulkRegister}, or forms of
24 > * constructors establishing initial numbers of parties), and
25 > * optionally deregistered upon any arrival (using {@link
26 > * #arriveAndDeregister}).  As is the case with most basic
27 > * synchronization constructs, registration and deregistration affect
28 > * only internal counts; they do not establish any further internal
29 > * bookkeeping, so tasks cannot query whether they are registered.
30 > * (However, you can introduce such bookkeeping by subclassing this
31 > * class.)
32 > *
33 > * <p> <b>Synchronization.</b> Like a {@code CyclicBarrier}, a {@code
34 > * Phaser} may be repeatedly awaited.  Method {@link
35 > * #arriveAndAwaitAdvance} has effect analogous to {@link
36 > * java.util.concurrent.CyclicBarrier#await CyclicBarrier.await}. Each
37 > * generation of a {@code Phaser} has an associated phase number. The
38 > * phase number starts at zero, and advances when all parties arrive
39 > * at the barrier, wrapping around to zero after reaching {@code
40 > * Integer.MAX_VALUE}. The use of phase numbers enables independent
41 > * control of actions upon arrival at a barrier and upon awaiting
42 > * others, via two kinds of methods that may be invoked by any
43 > * registered party:
44   *
45   * <ul>
46   *
47 < *   <li> Arriving at a barrier. Methods {@code arrive} and
48 < *       {@code arriveAndDeregister} do not block, but return
49 < *       the phase value current upon entry to the method.
50 < *
51 < *   <li> Awaiting others. Method {@code awaitAdvance} requires an
52 < *       argument indicating the entry phase, and returns when the
53 < *       barrier advances to a new phase.
54 < * </ul>
47 > *   <li> <b>Arrival.</b> Methods {@link #arrive} and
48 > *       {@link #arriveAndDeregister} record arrival at a
49 > *       barrier. These methods do not block, but return an associated
50 > *       <em>arrival phase number</em>; that is, the phase number of
51 > *       the barrier to which the arrival applied. When the final
52 > *       party for a given phase arrives, an optional barrier action
53 > *       is performed and the phase advances.  Barrier actions,
54 > *       performed by the party triggering a phase advance, are
55 > *       arranged by overriding method {@link #onAdvance(int, int)},
56 > *       which also controls termination. Overriding this method is
57 > *       similar to, but more flexible than, providing a barrier
58 > *       action to a {@code CyclicBarrier}.
59 > *
60 > *   <li> <b>Waiting.</b> Method {@link #awaitAdvance} requires an
61 > *       argument indicating an arrival phase number, and returns when
62 > *       the barrier advances to (or is already at) a different phase.
63 > *       Unlike similar constructions using {@code CyclicBarrier},
64 > *       method {@code awaitAdvance} continues to wait even if the
65 > *       waiting thread is interrupted. Interruptible and timeout
66 > *       versions are also available, but exceptions encountered while
67 > *       tasks wait interruptibly or with timeout do not change the
68 > *       state of the barrier. If necessary, you can perform any
69 > *       associated recovery within handlers of those exceptions,
70 > *       often after invoking {@code forceTermination}.  Phasers may
71 > *       also be used by tasks executing in a {@link ForkJoinPool},
72 > *       which will ensure sufficient parallelism to execute tasks
73 > *       when others are blocked waiting for a phase to advance.
74   *
75 + * </ul>
76   *
77 < * <li> Barrier actions, performed by the task triggering a phase
78 < * advance while others may be waiting, are arranged by overriding
79 < * method {@code onAdvance}, that also controls termination.
80 < * Overriding this method may be used to similar but more flexible
81 < * effect as providing a barrier action to a CyclicBarrier.
82 < *
83 < * <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 {@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
77 > * <p> <b>Termination.</b> A {@code Phaser} may enter a
78 > * <em>termination</em> state in which all synchronization methods
79 > * immediately return without updating phaser state or waiting for
80 > * advance, and indicating (via a negative phase value) that execution
81 > * is complete.  Termination is triggered when an invocation of {@code
82 > * onAdvance} returns {@code true}.  As illustrated below, when
83 > * phasers control actions with a fixed number of iterations, it is
84   * often convenient to override this method to cause termination when
85 < * the current phase number reaches a threshold. Method
86 < * {@code forceTermination} is also available to abruptly release
87 < * waiting threads and allow them to terminate.
85 > * the current phase number reaches a threshold. Method {@link
86 > * #forceTermination} is also available to abruptly release waiting
87 > * threads and allow them to terminate.
88   *
89 < * <li> Phasers may be tiered to reduce contention. Phasers with large
89 > * <p> <b>Tiering.</b> Phasers may be <em>tiered</em> (i.e., arranged
90 > * in tree structures) to reduce contention. Phasers with large
91   * numbers of parties that would otherwise experience heavy
92 < * synchronization contention costs may instead be arranged in trees.
93 < * This will typically greatly increase throughput even though it
94 < * incurs somewhat greater per-operation overhead.
95 < *
96 < * <li> By default, {@code awaitAdvance} continues to wait even if
97 < * the waiting thread is interrupted. And unlike the case in
98 < * CyclicBarriers, exceptions encountered while tasks wait
99 < * interruptibly or with timeout do not change the state of the
100 < * barrier. If necessary, you can perform any associated recovery
101 < * within handlers of those exceptions, often after invoking
102 < * {@code forceTermination}.
103 < *
104 < * </ul>
92 > * synchronization contention costs may instead be set up so that
93 > * groups of sub-phasers share a common parent.  This may greatly
94 > * increase throughput even though it incurs greater per-operation
95 > * overhead.
96 > *
97 > * <p><b>Monitoring.</b> While synchronization methods may be invoked
98 > * only by registered parties, the current state of a phaser may be
99 > * monitored by any caller.  At any given moment there are {@link
100 > * #getRegisteredParties} parties in total, of which {@link
101 > * #getArrivedParties} have arrived at the current phase ({@link
102 > * #getPhase}).  When the remaining ({@link #getUnarrivedParties})
103 > * parties arrive, the phase advances.  The values returned by these
104 > * methods may reflect transient states and so are not in general
105 > * useful for synchronization control.  Method {@link #toString}
106 > * returns snapshots of these state queries in a form convenient for
107 > * informal monitoring.
108   *
109   * <p><b>Sample usages:</b>
110   *
111 < * <p>A Phaser may be used instead of a {@code CountDownLatch} to control
112 < * a one-shot action serving a variable number of parties. The typical
113 < * idiom is for the method setting this up to first register, then
114 < * start the actions, then deregister, as in:
115 < *
116 < * <pre>
117 < *  void runTasks(List&lt;Runnable&gt; list) {
118 < *    final Phaser phaser = new Phaser(1); // "1" to register self
119 < *    for (Runnable r : list) {
120 < *      phaser.register();
121 < *      new Thread() {
122 < *        public void run() {
123 < *          phaser.arriveAndAwaitAdvance(); // await all creation
124 < *          r.run();
125 < *          phaser.arriveAndDeregister();   // signal completion
126 < *        }
127 < *      }.start();
111 > * <p>A {@code Phaser} may be used instead of a {@code CountDownLatch}
112 > * to control a one-shot action serving a variable number of
113 > * parties. The typical idiom is for the method setting this up to
114 > * first register, then start the actions, then deregister, as in:
115 > *
116 > *  <pre> {@code
117 > * void runTasks(List<Runnable> tasks) {
118 > *   final Phaser phaser = new Phaser(1); // "1" to register self
119 > *   // create and start threads
120 > *   for (Runnable task : tasks) {
121 > *     phaser.register();
122 > *     new Thread() {
123 > *       public void run() {
124 > *         phaser.arriveAndAwaitAdvance(); // await all creation
125 > *         task.run();
126 > *       }
127 > *     }.start();
128   *   }
129   *
130 < *   doSomethingOnBehalfOfWorkers();
131 < *   phaser.arrive(); // allow threads to start
132 < *   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); // await final completion
113 < * }
114 < * </pre>
130 > *   // allow threads to start and deregister self
131 > *   phaser.arriveAndDeregister();
132 > * }}</pre>
133   *
134   * <p>One way to cause a set of threads to repeatedly perform actions
135   * for a given number of iterations is to override {@code onAdvance}:
136   *
137 < * <pre>
138 < *  void startTasks(List&lt;Runnable&gt; list, final int iterations) {
139 < *    final Phaser phaser = new Phaser() {
140 < *       public boolean onAdvance(int phase, int registeredParties) {
141 < *         return phase &gt;= iterations || registeredParties == 0;
137 > *  <pre> {@code
138 > * void startTasks(List<Runnable> tasks, final int iterations) {
139 > *   final Phaser phaser = new Phaser() {
140 > *     protected boolean onAdvance(int phase, int registeredParties) {
141 > *       return phase >= iterations || registeredParties == 0;
142 > *     }
143 > *   };
144 > *   phaser.register();
145 > *   for (final Runnable task : tasks) {
146 > *     phaser.register();
147 > *     new Thread() {
148 > *       public void run() {
149 > *         do {
150 > *           task.run();
151 > *           phaser.arriveAndAwaitAdvance();
152 > *         } while (!phaser.isTerminated());
153   *       }
154 < *    };
126 < *    phaser.register();
127 < *    for (Runnable r : list) {
128 < *      phaser.register();
129 < *      new Thread() {
130 < *        public void run() {
131 < *           do {
132 < *             r.run();
133 < *             phaser.arriveAndAwaitAdvance();
134 < *           } while(!phaser.isTerminated();
135 < *        }
136 < *      }.start();
154 > *     }.start();
155   *   }
156   *   phaser.arriveAndDeregister(); // deregister self, don't wait
157 < * }
158 < * </pre>
157 > * }}</pre>
158 > *
159 > * If the main task must later await termination, it
160 > * may re-register and then execute a similar loop:
161 > *  <pre> {@code
162 > *   // ...
163 > *   phaser.register();
164 > *   while (!phaser.isTerminated())
165 > *     phaser.arriveAndAwaitAdvance();}</pre>
166 > *
167 > * <p>Related constructions may be used to await particular phase numbers
168 > * in contexts where you are sure that the phase will never wrap around
169 > * {@code Integer.MAX_VALUE}. For example:
170 > *
171 > *  <pre> {@code
172 > * void awaitPhase(Phaser phaser, int phase) {
173 > *   int p = phaser.register(); // assumes caller not already registered
174 > *   while (p < phase) {
175 > *     if (phaser.isTerminated())
176 > *       // ... deal with unexpected termination
177 > *     else
178 > *       p = phaser.arriveAndAwaitAdvance();
179 > *   }
180 > *   phaser.arriveAndDeregister();
181 > * }}</pre>
182 > *
183   *
184 < * <p> To create a set of tasks using a tree of Phasers,
184 > * <p>To create a set of tasks using a tree of phasers,
185   * you could use code of the following form, assuming a
186 < * Task class with a constructor accepting a Phaser that
186 > * Task class with a constructor accepting a phaser that
187   * it registers for upon construction:
188 < * <pre>
189 < *  void build(Task[] actions, int lo, int hi, Phaser b) {
190 < *    int step = (hi - lo) / TASKS_PER_PHASER;
191 < *    if (step &gt; 1) {
192 < *       int i = lo;
193 < *       while (i &lt; hi) {
194 < *         int r = Math.min(i + step, hi);
195 < *         build(actions, i, r, new Phaser(b));
196 < *         i = r;
197 < *       }
198 < *    }
199 < *    else {
200 < *      for (int i = lo; i &lt; hi; ++i)
201 < *        actions[i] = new Task(b);
202 < *        // assumes new Task(b) performs b.register()
203 < *    }
162 < *  }
163 < *  // .. initially called, for n tasks via
164 < *  build(new Task[n], 0, n, new Phaser());
165 < * </pre>
188 > *
189 > *  <pre> {@code
190 > * void build(Task[] actions, int lo, int hi, Phaser ph) {
191 > *   if (hi - lo > TASKS_PER_PHASER) {
192 > *     for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
193 > *       int j = Math.min(i + TASKS_PER_PHASER, hi);
194 > *       build(actions, i, j, new Phaser(ph));
195 > *     }
196 > *   } else {
197 > *     for (int i = lo; i < hi; ++i)
198 > *       actions[i] = new Task(ph);
199 > *       // assumes new Task(ph) performs ph.register()
200 > *   }
201 > * }
202 > * // .. initially called, for n tasks via
203 > * build(new Task[n], 0, n, new Phaser());}</pre>
204   *
205   * The best value of {@code TASKS_PER_PHASER} depends mainly on
206   * expected barrier synchronization rates. A value as low as four may
# Line 173 | Line 211 | import java.lang.reflect.*;
211   *
212   * <p><b>Implementation notes</b>: This implementation restricts the
213   * maximum number of parties to 65535. Attempts to register additional
214 < * parties result in IllegalStateExceptions. However, you can and
214 > * parties result in {@code IllegalStateException}. However, you can and
215   * should create tiered phasers to accommodate arbitrarily large sets
216   * of participants.
217 + *
218 + * @since 1.7
219 + * @author Doug Lea
220   */
221   public class Phaser {
222      /*
# Line 200 | Line 241 | public class Phaser {
241       * and encoding simple, and keeping race windows short.
242       *
243       * Note: there are some cheats in arrive() that rely on unarrived
244 <     * being lowest 16 bits.
244 >     * count being lowest 16 bits.
245       */
246      private volatile long state;
247  
248 <    private static final int ushortBits = 16;
249 <    private static final int ushortMask =  (1 << ushortBits) - 1;
209 <    private static final int phaseMask = 0x7fffffff;
248 >    private static final int ushortMask = 0xffff;
249 >    private static final int phaseMask  = 0x7fffffff;
250  
251      private static int unarrivedOf(long s) {
252 <        return (int)(s & ushortMask);
252 >        return (int) (s & ushortMask);
253      }
254  
255      private static int partiesOf(long s) {
256 <        return (int)(s & (ushortMask << 16)) >>> 16;
256 >        return ((int) s) >>> 16;
257      }
258  
259      private static int phaseOf(long s) {
260 <        return (int)(s >>> 32);
260 >        return (int) (s >>> 32);
261      }
262  
263      private static int arrivedOf(long s) {
# Line 225 | Line 265 | public class Phaser {
265      }
266  
267      private static long stateFor(int phase, int parties, int unarrived) {
268 <        return (((long)phase) << 32) | ((parties << 16) | unarrived);
268 >        return ((((long) phase) << 32) | (((long) parties) << 16) |
269 >                (long) unarrived);
270      }
271  
272      private static long trippedStateFor(int phase, int parties) {
273 <        return (((long)phase) << 32) | ((parties << 16) | parties);
273 >        long lp = (long) parties;
274 >        return (((long) phase) << 32) | (lp << 16) | lp;
275      }
276  
277 <    private static IllegalStateException badBounds(int parties, int unarrived) {
278 <        return new IllegalStateException
279 <            ("Attempt to set " + unarrived +
280 <             " unarrived of " + parties + " parties");
277 >    /**
278 >     * Returns message string for bad bounds exceptions.
279 >     */
280 >    private static String badBounds(int parties, int unarrived) {
281 >        return ("Attempt to set " + unarrived +
282 >                " unarrived of " + parties + " parties");
283      }
284  
285      /**
# Line 244 | Line 288 | public class Phaser {
288      private final Phaser parent;
289  
290      /**
291 <     * The root of Phaser tree. Equals this if not in a tree.  Used to
291 >     * The root of phaser tree. Equals this if not in a tree.  Used to
292       * support faster state push-down.
293       */
294      private final Phaser root;
# Line 252 | Line 296 | public class Phaser {
296      // Wait queues
297  
298      /**
299 <     * Heads of Treiber stacks waiting for nonFJ threads. To eliminate
299 >     * Heads of Treiber stacks for waiting threads. To eliminate
300       * contention while releasing some threads while adding others, we
301       * use two of them, alternating across even and odd phases.
302       */
# Line 260 | Line 304 | public class Phaser {
304      private final AtomicReference<QNode> oddQ  = new AtomicReference<QNode>();
305  
306      private AtomicReference<QNode> queueFor(int phase) {
307 <        return (phase & 1) == 0? evenQ : oddQ;
307 >        return ((phase & 1) == 0) ? evenQ : oddQ;
308      }
309  
310      /**
# Line 268 | Line 312 | public class Phaser {
312       * root if necessary.
313       */
314      private long getReconciledState() {
315 <        return parent == null? state : reconcileState();
315 >        return (parent == null) ? state : reconcileState();
316      }
317  
318      /**
# Line 295 | Line 339 | public class Phaser {
339      }
340  
341      /**
342 <     * Creates a new Phaser without any initially registered parties,
343 <     * initial phase number 0, and no parent.
342 >     * Creates a new phaser without any initially registered parties,
343 >     * initial phase number 0, and no parent. Any thread using this
344 >     * phaser will need to first register for it.
345       */
346      public Phaser() {
347          this(null);
348      }
349  
350      /**
351 <     * Creates a new Phaser with the given numbers of registered
351 >     * Creates a new phaser with the given numbers of registered
352       * unarrived parties, initial phase number 0, and no parent.
353 <     * @param parties the number of parties required to trip barrier.
353 >     *
354 >     * @param parties the number of parties required to trip barrier
355       * @throws IllegalArgumentException if parties less than zero
356 <     * or greater than the maximum number of parties supported.
356 >     * or greater than the maximum number of parties supported
357       */
358      public Phaser(int parties) {
359          this(null, parties);
360      }
361  
362      /**
363 <     * Creates a new Phaser with the given parent, without any
363 >     * Creates a new phaser with the given parent, without any
364       * initially registered parties. If parent is non-null this phaser
365       * is registered with the parent and its initial phase number is
366       * the same as that of parent phaser.
367 <     * @param parent the parent phaser.
367 >     *
368 >     * @param parent the parent phaser
369       */
370      public Phaser(Phaser parent) {
371          int phase = 0;
# Line 333 | Line 380 | public class Phaser {
380      }
381  
382      /**
383 <     * Creates a new Phaser with the given parent and numbers of
384 <     * registered unarrived parties. If parent is non-null this phaser
383 >     * Creates a new phaser with the given parent and numbers of
384 >     * registered unarrived parties. If parent is non-null, this phaser
385       * is registered with the parent and its initial phase number is
386       * the same as that of parent phaser.
387 <     * @param parent the parent phaser.
388 <     * @param parties the number of parties required to trip barrier.
387 >     *
388 >     * @param parent the parent phaser
389 >     * @param parties the number of parties required to trip barrier
390       * @throws IllegalArgumentException if parties less than zero
391 <     * or greater than the maximum number of parties supported.
391 >     * or greater than the maximum number of parties supported
392       */
393      public Phaser(Phaser parent, int parties) {
394          if (parties < 0 || parties > ushortMask)
# Line 358 | Line 406 | public class Phaser {
406  
407      /**
408       * Adds a new unarrived party to this phaser.
409 <     * @return the current barrier phase number upon registration
409 >     *
410 >     * @return the arrival phase number to which this registration applied
411       * @throws IllegalStateException if attempting to register more
412 <     * than the maximum supported number of parties.
412 >     * than the maximum supported number of parties
413       */
414      public int register() {
415          return doRegister(1);
# Line 368 | Line 417 | public class Phaser {
417  
418      /**
419       * Adds the given number of new unarrived parties to this phaser.
420 <     * @param parties the number of parties required to trip barrier.
421 <     * @return the current barrier phase number upon registration
420 >     *
421 >     * @param parties the number of parties required to trip barrier
422 >     * @return the arrival phase number to which this registration applied
423       * @throws IllegalStateException if attempting to register more
424 <     * than the maximum supported number of parties.
424 >     * than the maximum supported number of parties
425       */
426      public int bulkRegister(int parties) {
427          if (parties < 0)
# Line 394 | Line 444 | public class Phaser {
444              if (phase < 0)
445                  break;
446              if (parties > ushortMask || unarrived > ushortMask)
447 <                throw badBounds(parties, unarrived);
447 >                throw new IllegalStateException(badBounds(parties, unarrived));
448              if (phase == phaseOf(root.state) &&
449                  casState(s, stateFor(phase, parties, unarrived)))
450                  break;
# Line 404 | Line 454 | public class Phaser {
454  
455      /**
456       * Arrives at the barrier, but does not wait for others.  (You can
457 <     * in turn wait for others via {@link #awaitAdvance}).
457 >     * in turn wait for others via {@link #awaitAdvance}).  It is an
458 >     * unenforced usage error for an unregistered party to invoke this
459 >     * method.
460       *
461 <     * @return the barrier phase number upon entry to this method, or a
410 <     * negative value if terminated;
461 >     * @return the arrival phase number, or a negative value if terminated
462       * @throws IllegalStateException if not terminated and the number
463 <     * of unarrived parties would become negative.
463 >     * of unarrived parties would become negative
464       */
465      public int arrive() {
466          int phase;
467          for (;;) {
468              long s = state;
469              phase = phaseOf(s);
470 +            if (phase < 0)
471 +                break;
472              int parties = partiesOf(s);
473              int unarrived = unarrivedOf(s) - 1;
474              if (unarrived > 0) {        // Not the last arrival
# Line 427 | Line 480 | public class Phaser {
480                  if (par == null) {      // directly trip
481                      if (casState
482                          (s,
483 <                         trippedStateFor(onAdvance(phase, parties)? -1 :
483 >                         trippedStateFor(onAdvance(phase, parties) ? -1 :
484                                           ((phase + 1) & phaseMask), parties))) {
485                          releaseWaiters(phase);
486                          break;
# Line 441 | Line 494 | public class Phaser {
494                      }
495                  }
496              }
444            else if (phase < 0) // Don't throw exception if terminated
445                break;
497              else if (phase != phaseOf(root.state)) // or if unreconciled
498                  reconcileState();
499              else
500 <                throw badBounds(parties, unarrived);
500 >                throw new IllegalStateException(badBounds(parties, unarrived));
501          }
502          return phase;
503      }
504  
505      /**
506 <     * Arrives at the barrier, and deregisters from it, without
507 <     * waiting for others. Deregistration reduces number of parties
506 >     * Arrives at the barrier and deregisters from it without waiting
507 >     * for others. Deregistration reduces the number of parties
508       * required to trip the barrier in future phases.  If this phaser
509       * has a parent, and deregistration causes this phaser to have
510 <     * zero parties, this phaser is also deregistered from its parent.
510 >     * zero parties, this phaser also arrives at and is deregistered
511 >     * from its parent.  It is an unenforced usage error for an
512 >     * unregistered party to invoke this method.
513       *
514 <     * @return the current barrier phase number upon entry to
462 <     * this method, or a negative value if terminated;
514 >     * @return the arrival phase number, or a negative value if terminated
515       * @throws IllegalStateException if not terminated and the number
516 <     * of registered or unarrived parties would become negative.
516 >     * of registered or unarrived parties would become negative
517       */
518      public int arriveAndDeregister() {
519          // similar code to arrive, but too different to merge
# Line 470 | Line 522 | public class Phaser {
522          for (;;) {
523              long s = state;
524              phase = phaseOf(s);
525 +            if (phase < 0)
526 +                break;
527              int parties = partiesOf(s) - 1;
528              int unarrived = unarrivedOf(s) - 1;
529              if (parties >= 0) {
# Line 488 | Line 542 | public class Phaser {
542                  if (unarrived == 0) {
543                      if (casState
544                          (s,
545 <                         trippedStateFor(onAdvance(phase, parties)? -1 :
545 >                         trippedStateFor(onAdvance(phase, parties) ? -1 :
546                                           ((phase + 1) & phaseMask), parties))) {
547                          releaseWaiters(phase);
548                          break;
549                      }
550                      continue;
551                  }
498                if (phase < 0)
499                    break;
552                  if (par != null && phase != phaseOf(root.state)) {
553                      reconcileState();
554                      continue;
555                  }
556              }
557 <            throw badBounds(parties, unarrived);
557 >            throw new IllegalStateException(badBounds(parties, unarrived));
558          }
559          return phase;
560      }
561  
562      /**
563       * Arrives at the barrier and awaits others. Equivalent in effect
564 <     * to {@code awaitAdvance(arrive())}.  If you instead need to
565 <     * await with interruption of timeout, and/or deregister upon
566 <     * arrival, you can arrange them using analogous constructions.
567 <     * @return the phase on entry to this method
564 >     * to {@code awaitAdvance(arrive())}.  If you need to await with
565 >     * interruption or timeout, you can arrange this with an analogous
566 >     * construction using one of the other forms of the awaitAdvance
567 >     * method.  If instead you need to deregister upon arrival use
568 >     * {@code arriveAndDeregister}. It is an unenforced usage error
569 >     * for an unregistered party to invoke this method.
570 >     *
571 >     * @return the arrival phase number, or a negative number if terminated
572       * @throws IllegalStateException if not terminated and the number
573 <     * of unarrived parties would become negative.
573 >     * of unarrived parties would become negative
574       */
575      public int arriveAndAwaitAdvance() {
576          return awaitAdvance(arrive());
577      }
578  
579      /**
580 <     * Awaits the phase of the barrier to advance from the given
581 <     * value, or returns immediately if argument is negative or this
582 <     * barrier is terminated.
583 <     * @param phase the phase on entry to this method
584 <     * @return the phase on exit from this method
580 >     * Awaits the phase of the barrier to advance from the given phase
581 >     * value, returning immediately if the current phase of the
582 >     * barrier is not equal to the given phase value or this barrier
583 >     * is terminated.  It is an unenforced usage error for an
584 >     * unregistered party to invoke this method.
585 >     *
586 >     * @param phase an arrival phase number, or negative value if
587 >     * terminated; this argument is normally the value returned by a
588 >     * previous call to {@code arrive} or its variants
589 >     * @return the next arrival phase number, or a negative value
590 >     * if terminated or argument is negative
591       */
592      public int awaitAdvance(int phase) {
593          if (phase < 0)
# Line 534 | Line 596 | public class Phaser {
596          int p = phaseOf(s);
597          if (p != phase)
598              return p;
599 <        if (unarrivedOf(s) == 0)
599 >        if (unarrivedOf(s) == 0 && parent != null)
600              parent.awaitAdvance(phase);
601          // Fall here even if parent waited, to reconcile and help release
602          return untimedWait(phase);
603      }
604  
605      /**
606 <     * Awaits the phase of the barrier to advance from the given
607 <     * value, or returns immediately if argument is negative or this
608 <     * barrier is terminated, or throws InterruptedException if
609 <     * interrupted while waiting.
610 <     * @param phase the phase on entry to this method
611 <     * @return the phase on exit from this method
606 >     * Awaits the phase of the barrier to advance from the given phase
607 >     * value, throwing {@code InterruptedException} if interrupted
608 >     * while waiting, or returning immediately if the current phase of
609 >     * the barrier is not equal to the given phase value or this
610 >     * barrier is terminated. It is an unenforced usage error for an
611 >     * unregistered party to invoke this method.
612 >     *
613 >     * @param phase an arrival phase number, or negative value if
614 >     * terminated; this argument is normally the value returned by a
615 >     * previous call to {@code arrive} or its variants
616 >     * @return the next arrival phase number, or a negative value
617 >     * if terminated or argument is negative
618       * @throws InterruptedException if thread interrupted while waiting
619       */
620 <    public int awaitAdvanceInterruptibly(int phase) throws InterruptedException {
620 >    public int awaitAdvanceInterruptibly(int phase)
621 >        throws InterruptedException {
622          if (phase < 0)
623              return phase;
624          long s = getReconciledState();
625          int p = phaseOf(s);
626          if (p != phase)
627              return p;
628 <        if (unarrivedOf(s) != 0)
628 >        if (unarrivedOf(s) == 0 && parent != null)
629              parent.awaitAdvanceInterruptibly(phase);
630          return interruptibleWait(phase);
631      }
632  
633      /**
634 <     * Awaits the phase of the barrier to advance from the given value
635 <     * or the given timeout elapses, or returns immediately if
636 <     * argument is negative or this barrier is terminated.
637 <     * @param phase the phase on entry to this method
638 <     * @return the phase on exit from this method
634 >     * Awaits the phase of the barrier to advance from the given phase
635 >     * value or the given timeout to elapse, throwing {@code
636 >     * InterruptedException} if interrupted while waiting, or
637 >     * returning immediately if the current phase of the barrier is
638 >     * not equal to the given phase value or this barrier is
639 >     * terminated.  It is an unenforced usage error for an
640 >     * unregistered party to invoke this method.
641 >     *
642 >     * @param phase an arrival phase number, or negative value if
643 >     * terminated; this argument is normally the value returned by a
644 >     * previous call to {@code arrive} or its variants
645 >     * @param timeout how long to wait before giving up, in units of
646 >     *        {@code unit}
647 >     * @param unit a {@code TimeUnit} determining how to interpret the
648 >     *        {@code timeout} parameter
649 >     * @return the next arrival phase number, or a negative value
650 >     * if terminated or argument is negative
651       * @throws InterruptedException if thread interrupted while waiting
652       * @throws TimeoutException if timed out while waiting
653       */
654 <    public int awaitAdvanceInterruptibly(int phase, long timeout, TimeUnit unit)
654 >    public int awaitAdvanceInterruptibly(int phase,
655 >                                         long timeout, TimeUnit unit)
656          throws InterruptedException, TimeoutException {
657          if (phase < 0)
658              return phase;
# Line 578 | Line 660 | public class Phaser {
660          int p = phaseOf(s);
661          if (p != phase)
662              return p;
663 <        if (unarrivedOf(s) == 0)
663 >        if (unarrivedOf(s) == 0 && parent != null)
664              parent.awaitAdvanceInterruptibly(phase, timeout, unit);
665          return timedWait(phase, unit.toNanos(timeout));
666      }
# Line 611 | Line 693 | public class Phaser {
693       * Returns the current phase number. The maximum phase number is
694       * {@code Integer.MAX_VALUE}, after which it restarts at
695       * zero. Upon termination, the phase number is negative.
696 +     *
697       * @return the phase number, or a negative value if terminated
698       */
699      public final int getPhase() {
# Line 618 | Line 701 | public class Phaser {
701      }
702  
703      /**
621     * Returns {@code true} if the current phase number equals the given phase.
622     * @param phase the 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;
627    }
628
629    /**
704       * Returns the number of parties registered at this barrier.
705 +     *
706       * @return the number of parties
707       */
708      public int getRegisteredParties() {
# Line 635 | Line 710 | public class Phaser {
710      }
711  
712      /**
713 <     * Returns the number of parties that have arrived at the current
714 <     * phase of this barrier.
713 >     * Returns the number of registered parties that have arrived at
714 >     * the current phase of this barrier.
715 >     *
716       * @return the number of arrived parties
717       */
718      public int getArrivedParties() {
# Line 646 | Line 722 | public class Phaser {
722      /**
723       * Returns the number of registered parties that have not yet
724       * arrived at the current phase of this barrier.
725 +     *
726       * @return the number of unarrived parties
727       */
728      public int getUnarrivedParties() {
# Line 653 | Line 730 | public class Phaser {
730      }
731  
732      /**
733 <     * Returns the parent of this phaser, or null if none.
734 <     * @return the parent of this phaser, or null if none
733 >     * Returns the parent of this phaser, or {@code null} if none.
734 >     *
735 >     * @return the parent of this phaser, or {@code null} if none
736       */
737      public Phaser getParent() {
738          return parent;
# Line 663 | Line 741 | public class Phaser {
741      /**
742       * Returns the root ancestor of this phaser, which is the same as
743       * this phaser if it has no parent.
744 +     *
745       * @return the root ancestor of this phaser
746       */
747      public Phaser getRoot() {
# Line 671 | Line 750 | public class Phaser {
750  
751      /**
752       * Returns {@code true} if this barrier has been terminated.
753 +     *
754       * @return {@code true} if this barrier has been terminated
755       */
756      public boolean isTerminated() {
# Line 678 | Line 758 | public class Phaser {
758      }
759  
760      /**
761 <     * Overridable method to perform an action upon phase advance, and
762 <     * to control termination. This method is invoked whenever the
763 <     * barrier is tripped (and thus all other waiting parties are
764 <     * dormant). If it returns true, then, rather than advance the
765 <     * phase number, this barrier will be set to a final termination
766 <     * state, and subsequent calls to {@code isTerminated} will
767 <     * return true.
761 >     * Overridable method to perform an action upon impending phase
762 >     * advance, and to control termination. This method is invoked
763 >     * upon arrival of the party tripping the barrier (when all other
764 >     * waiting parties are dormant).  If this method returns {@code
765 >     * true}, then, rather than advance the phase number, this barrier
766 >     * will be set to a final termination state, and subsequent calls
767 >     * to {@link #isTerminated} will return true. Any (unchecked)
768 >     * Exception or Error thrown by an invocation of this method is
769 >     * propagated to the party attempting to trip the barrier, in
770 >     * which case no advance occurs.
771 >     *
772 >     * <p>The arguments to this method provide the state of the phaser
773 >     * prevailing for the current transition. (When called from within
774 >     * an implementation of {@code onAdvance} the values returned by
775 >     * methods such as {@code getPhase} may or may not reliably
776 >     * indicate the state to which this transition applies.)
777       *
778 <     * <p> The default version returns true when the number of
778 >     * <p>The default version returns {@code true} when the number of
779       * registered parties is zero. Normally, overrides that arrange
780       * termination for other reasons should also preserve this
781       * property.
782       *
783 <     * <p> You may override this method to perform an action with side
784 <     * effects visible to participating tasks, but it is in general
785 <     * only sensible to do so in designs where all parties register
786 <     * before any arrive, and all {@code awaitAdvance} at each phase.
787 <     * Otherwise, you cannot ensure lack of interference. In
788 <     * particular, this method may be invoked more than once per
789 <     * transition if other parties successfully register while the
790 <     * invocation of this method is in progress, thus postponing the
702 <     * transition until those parties also arrive, re-triggering this
703 <     * method.
783 >     * <p>You may override this method to perform an action with side
784 >     * effects visible to participating tasks, but it is only sensible
785 >     * to do so in designs where all parties register before any
786 >     * arrive, and all {@link #awaitAdvance} at each phase.
787 >     * Otherwise, you cannot ensure lack of interference from other
788 >     * parties during the invocation of this method. Additionally,
789 >     * method {@code onAdvance} may be invoked more than once per
790 >     * transition if registrations are intermixed with arrivals.
791       *
792       * @param phase the phase number on entering the barrier
793       * @param registeredParties the current number of registered parties
# Line 729 | Line 816 | public class Phaser {
816  
817      // methods for waiting
818  
732    /** The number of CPUs, for spin control */
733    static final int NCPUS = Runtime.getRuntime().availableProcessors();
734
819      /**
820 <     * The number of times to spin before blocking in timed waits.
737 <     * The value is empirically derived.
820 >     * Wait nodes for Treiber stack representing wait queue
821       */
822 <    static final int maxTimedSpins = (NCPUS < 2)? 0 : 32;
823 <
824 <    /**
825 <     * The number of times to spin before blocking in untimed waits.
826 <     * This is greater than timed value because untimed waits spin
827 <     * faster since they don't need to check times on each spin.
828 <     */
829 <    static final int maxUntimedSpins = maxTimedSpins * 32;
747 <
748 <    /**
749 <     * The number of nanoseconds for which it is faster to spin
750 <     * rather than to use timed park. A rough estimate suffices.
751 <     */
752 <    static final long spinForTimeoutThreshold = 1000L;
753 <
754 <    /**
755 <     * Wait nodes for Treiber stack representing wait queue for non-FJ
756 <     * tasks.
757 <     */
758 <    static final class QNode {
759 <        QNode next;
822 >    static final class QNode implements ForkJoinPool.ManagedBlocker {
823 >        final Phaser phaser;
824 >        final int phase;
825 >        final long startTime;
826 >        final long nanos;
827 >        final boolean timed;
828 >        final boolean interruptible;
829 >        volatile boolean wasInterrupted = false;
830          volatile Thread thread; // nulled to cancel wait
831 <        QNode() {
831 >        QNode next;
832 >        QNode(Phaser phaser, int phase, boolean interruptible,
833 >              boolean timed, long startTime, long nanos) {
834 >            this.phaser = phaser;
835 >            this.phase = phase;
836 >            this.timed = timed;
837 >            this.interruptible = interruptible;
838 >            this.startTime = startTime;
839 >            this.nanos = nanos;
840              thread = Thread.currentThread();
841          }
842 +        public boolean isReleasable() {
843 +            return (thread == null ||
844 +                    phaser.getPhase() != phase ||
845 +                    (interruptible && wasInterrupted) ||
846 +                    (timed && (nanos - (System.nanoTime() - startTime)) <= 0));
847 +        }
848 +        public boolean block() {
849 +            if (Thread.interrupted()) {
850 +                wasInterrupted = true;
851 +                if (interruptible)
852 +                    return true;
853 +            }
854 +            if (!timed)
855 +                LockSupport.park(this);
856 +            else {
857 +                long waitTime = nanos - (System.nanoTime() - startTime);
858 +                if (waitTime <= 0)
859 +                    return true;
860 +                LockSupport.parkNanos(this, waitTime);
861 +            }
862 +            return isReleasable();
863 +        }
864          void signal() {
865              Thread t = thread;
866              if (t != null) {
# Line 768 | Line 868 | public class Phaser {
868                  LockSupport.unpark(t);
869              }
870          }
871 +        boolean doWait() {
872 +            if (thread != null) {
873 +                try {
874 +                    ForkJoinPool.managedBlock(this);
875 +                } catch (InterruptedException ie) {
876 +                }
877 +            }
878 +            return wasInterrupted;
879 +        }
880 +
881      }
882  
883      /**
884 <     * Removes and signals waiting threads from wait queue
884 >     * Removes and signals waiting threads from wait queue.
885       */
886      private void releaseWaiters(int phase) {
887          AtomicReference<QNode> head = queueFor(phase);
# Line 783 | Line 893 | public class Phaser {
893      }
894  
895      /**
896 +     * Tries to enqueue given node in the appropriate wait queue.
897 +     *
898 +     * @return true if successful
899 +     */
900 +    private boolean tryEnqueue(QNode node) {
901 +        AtomicReference<QNode> head = queueFor(node.phase);
902 +        return head.compareAndSet(node.next = head.get(), node);
903 +    }
904 +
905 +    /**
906       * Enqueues node and waits unless aborted or signalled.
907 +     *
908 +     * @return current phase
909       */
910      private int untimedWait(int phase) {
789        int spins = maxUntimedSpins;
911          QNode node = null;
791        boolean interrupted = false;
912          boolean queued = false;
913 +        boolean interrupted = false;
914          int p;
915          while ((p = getPhase()) == phase) {
916 <            interrupted = Thread.interrupted();
917 <            if (node != null) {
918 <                if (!queued) {
919 <                    AtomicReference<QNode> head = queueFor(phase);
920 <                    queued = head.compareAndSet(node.next = head.get(), node);
921 <                }
801 <                else if (node.thread != null)
802 <                    LockSupport.park(this);
803 <            }
804 <            else if (spins <= 0)
805 <                node = new QNode();
916 >            if (Thread.interrupted())
917 >                interrupted = true;
918 >            else if (node == null)
919 >                node = new QNode(this, phase, false, false, 0, 0);
920 >            else if (!queued)
921 >                queued = tryEnqueue(node);
922              else
923 <                --spins;
923 >                interrupted = node.doWait();
924          }
925          if (node != null)
926              node.thread = null;
927 +        releaseWaiters(phase);
928          if (interrupted)
929              Thread.currentThread().interrupt();
813        releaseWaiters(phase);
930          return p;
931      }
932  
933      /**
934 <     * Messier interruptible version
934 >     * Interruptible version
935 >     * @return current phase
936       */
937      private int interruptibleWait(int phase) throws InterruptedException {
821        int spins = maxUntimedSpins;
938          QNode node = null;
939          boolean queued = false;
940          boolean interrupted = false;
941          int p;
942 <        while ((p = getPhase()) == phase) {
943 <            if (interrupted = Thread.interrupted())
944 <                break;
945 <            if (node != null) {
946 <                if (!queued) {
947 <                    AtomicReference<QNode> head = queueFor(phase);
948 <                    queued = head.compareAndSet(node.next = head.get(), node);
833 <                }
834 <                else if (node.thread != null)
835 <                    LockSupport.park(this);
836 <            }
837 <            else if (spins <= 0)
838 <                node = new QNode();
942 >        while ((p = getPhase()) == phase && !interrupted) {
943 >            if (Thread.interrupted())
944 >                interrupted = true;
945 >            else if (node == null)
946 >                node = new QNode(this, phase, true, false, 0, 0);
947 >            else if (!queued)
948 >                queued = tryEnqueue(node);
949              else
950 <                --spins;
950 >                interrupted = node.doWait();
951          }
952          if (node != null)
953              node.thread = null;
954 +        if (p != phase || (p = getPhase()) != phase)
955 +            releaseWaiters(phase);
956          if (interrupted)
957              throw new InterruptedException();
846        releaseWaiters(phase);
958          return p;
959      }
960  
961      /**
962 <     * Even messier timeout version.
962 >     * Timeout version.
963 >     * @return current phase
964       */
965      private int timedWait(int phase, long nanos)
966          throws InterruptedException, TimeoutException {
967 +        long startTime = System.nanoTime();
968 +        QNode node = null;
969 +        boolean queued = false;
970 +        boolean interrupted = false;
971          int p;
972 <        if ((p = getPhase()) == phase) {
973 <            long lastTime = System.nanoTime();
974 <            int spins = maxTimedSpins;
975 <            QNode node = null;
976 <            boolean queued = false;
977 <            boolean interrupted = false;
978 <            while ((p = getPhase()) == phase) {
979 <                if (interrupted = Thread.interrupted())
980 <                    break;
981 <                long now = System.nanoTime();
982 <                if ((nanos -= now - lastTime) <= 0)
867 <                    break;
868 <                lastTime = now;
869 <                if (node != null) {
870 <                    if (!queued) {
871 <                        AtomicReference<QNode> head = queueFor(phase);
872 <                        queued = head.compareAndSet(node.next = head.get(), node);
873 <                    }
874 <                    else if (node.thread != null &&
875 <                             nanos > spinForTimeoutThreshold) {
876 <                        LockSupport.parkNanos(this, nanos);
877 <                    }
878 <                }
879 <                else if (spins <= 0)
880 <                    node = new QNode();
881 <                else
882 <                    --spins;
883 <            }
884 <            if (node != null)
885 <                node.thread = null;
886 <            if (interrupted)
887 <                throw new InterruptedException();
888 <            if (p == phase && (p = getPhase()) == phase)
889 <                throw new TimeoutException();
972 >        while ((p = getPhase()) == phase && !interrupted) {
973 >            if (Thread.interrupted())
974 >                interrupted = true;
975 >            else if (nanos - (System.nanoTime() - startTime) <= 0)
976 >                break;
977 >            else if (node == null)
978 >                node = new QNode(this, phase, true, true, startTime, nanos);
979 >            else if (!queued)
980 >                queued = tryEnqueue(node);
981 >            else
982 >                interrupted = node.doWait();
983          }
984 <        releaseWaiters(phase);
984 >        if (node != null)
985 >            node.thread = null;
986 >        if (p != phase || (p = getPhase()) != phase)
987 >            releaseWaiters(phase);
988 >        if (interrupted)
989 >            throw new InterruptedException();
990 >        if (p == phase)
991 >            throw new TimeoutException();
992          return p;
993      }
994  
995 <    // Temporary Unsafe mechanics for preliminary release
995 >    // Unsafe mechanics
996  
997 <    static final Unsafe _unsafe;
998 <    static final long stateOffset;
997 >    private static final sun.misc.Unsafe UNSAFE = getUnsafe();
998 >    private static final long stateOffset =
999 >        objectFieldOffset("state", Phaser.class);
1000  
1001 <    static {
1001 >    private final boolean casState(long cmp, long val) {
1002 >        return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val);
1003 >    }
1004 >
1005 >    private static long objectFieldOffset(String field, Class<?> klazz) {
1006          try {
1007 <            if (Phaser.class.getClassLoader() != null) {
1008 <                Field f = Unsafe.class.getDeclaredField("theUnsafe");
1009 <                f.setAccessible(true);
1010 <                _unsafe = (Unsafe)f.get(null);
1011 <            }
1012 <            else
908 <                _unsafe = Unsafe.getUnsafe();
909 <            stateOffset = _unsafe.objectFieldOffset
910 <                (Phaser.class.getDeclaredField("state"));
911 <        } catch (Exception e) {
912 <            throw new RuntimeException("Could not initialize intrinsics", e);
1007 >            return UNSAFE.objectFieldOffset(klazz.getDeclaredField(field));
1008 >        } catch (NoSuchFieldException e) {
1009 >            // Convert Exception to corresponding Error
1010 >            NoSuchFieldError error = new NoSuchFieldError(field);
1011 >            error.initCause(e);
1012 >            throw error;
1013          }
1014      }
1015  
1016 <    final boolean casState(long cmp, long val) {
1017 <        return _unsafe.compareAndSwapLong(this, stateOffset, cmp, val);
1016 >    /**
1017 >     * Returns a sun.misc.Unsafe.  Suitable for use in a 3rd party package.
1018 >     * Replace with a simple call to Unsafe.getUnsafe when integrating
1019 >     * into a jdk.
1020 >     *
1021 >     * @return a sun.misc.Unsafe
1022 >     */
1023 >    private static sun.misc.Unsafe getUnsafe() {
1024 >        try {
1025 >            return sun.misc.Unsafe.getUnsafe();
1026 >        } catch (SecurityException se) {
1027 >            try {
1028 >                return java.security.AccessController.doPrivileged
1029 >                    (new java.security
1030 >                     .PrivilegedExceptionAction<sun.misc.Unsafe>() {
1031 >                        public sun.misc.Unsafe run() throws Exception {
1032 >                            java.lang.reflect.Field f = sun.misc
1033 >                                .Unsafe.class.getDeclaredField("theUnsafe");
1034 >                            f.setAccessible(true);
1035 >                            return (sun.misc.Unsafe) f.get(null);
1036 >                        }});
1037 >            } catch (java.security.PrivilegedActionException e) {
1038 >                throw new RuntimeException("Could not initialize intrinsics",
1039 >                                           e.getCause());
1040 >            }
1041 >        }
1042      }
1043   }

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines