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.44 by dl, Tue Aug 25 16:32:28 2009 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 (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();
166 > * }</pre>
167 > *
168 > * Related constructions may be used to await particular phase numbers
169 > * in contexts where you are sure that the phase will never wrap around
170 > * {@code Integer.MAX_VALUE}. For example:
171 > *
172 > * <pre> {@code
173 > *   void awaitPhase(Phaser phaser, int phase) {
174 > *     int p = phaser.register(); // assumes caller not already registered
175 > *     while (p < phase) {
176 > *       if (phaser.isTerminated())
177 > *         // ... deal with unexpected termination
178 > *       else
179 > *         p = phaser.arriveAndAwaitAdvance();
180 > *     }
181 > *     phaser.arriveAndDeregister();
182 > *   }
183 > * }</pre>
184 > *
185   *
186 < * <p> To create a set of tasks using a tree of Phasers,
186 > * <p>To create a set of tasks using a tree of phasers,
187   * you could use code of the following form, assuming a
188 < * Task class with a constructor accepting a Phaser that
188 > * Task class with a constructor accepting a phaser that
189   * it registers for upon construction:
190 < * <pre>
191 < *  void build(Task[] actions, int lo, int hi, Phaser b) {
192 < *    int step = (hi - lo) / TASKS_PER_PHASER;
193 < *    if (step &gt; 1) {
194 < *       int i = lo;
195 < *       while (i &lt; hi) {
196 < *         int r = Math.min(i + step, hi);
197 < *         build(actions, i, r, new Phaser(b));
198 < *         i = r;
199 < *       }
200 < *    }
201 < *    else {
202 < *      for (int i = lo; i &lt; hi; ++i)
203 < *        actions[i] = new Task(b);
204 < *        // assumes new Task(b) performs b.register()
161 < *    }
162 < *  }
163 < *  // .. initially called, for n tasks via
164 < *  build(new Task[n], 0, n, new Phaser());
165 < * </pre>
190 > *  <pre> {@code
191 > * void build(Task[] actions, int lo, int hi, Phaser ph) {
192 > *   if (hi - lo > TASKS_PER_PHASER) {
193 > *     for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
194 > *       int j = Math.min(i + TASKS_PER_PHASER, hi);
195 > *       build(actions, i, j, new Phaser(ph));
196 > *     }
197 > *   } else {
198 > *     for (int i = lo; i < hi; ++i)
199 > *       actions[i] = new Task(ph);
200 > *       // assumes new Task(ph) performs ph.register()
201 > *   }
202 > * }
203 > * // .. initially called, for n tasks via
204 > * build(new Task[n], 0, n, new Phaser());}</pre>
205   *
206   * The best value of {@code TASKS_PER_PHASER} depends mainly on
207   * expected barrier synchronization rates. A value as low as four may
# Line 173 | Line 212 | import java.lang.reflect.*;
212   *
213   * <p><b>Implementation notes</b>: This implementation restricts the
214   * maximum number of parties to 65535. Attempts to register additional
215 < * parties result in IllegalStateExceptions. However, you can and
215 > * parties result in {@code IllegalStateException}. However, you can and
216   * should create tiered phasers to accommodate arbitrarily large sets
217   * of participants.
218 + *
219 + * @since 1.7
220 + * @author Doug Lea
221   */
222   public class Phaser {
223      /*
# Line 200 | Line 242 | public class Phaser {
242       * and encoding simple, and keeping race windows short.
243       *
244       * Note: there are some cheats in arrive() that rely on unarrived
245 <     * being lowest 16 bits.
245 >     * count being lowest 16 bits.
246       */
247      private volatile long state;
248  
249 <    private static final int ushortBits = 16;
250 <    private static final int ushortMask =  (1 << ushortBits) - 1;
209 <    private static final int phaseMask = 0x7fffffff;
249 >    private static final int ushortMask = 0xffff;
250 >    private static final int phaseMask  = 0x7fffffff;
251  
252      private static int unarrivedOf(long s) {
253 <        return (int)(s & ushortMask);
253 >        return (int) (s & ushortMask);
254      }
255  
256      private static int partiesOf(long s) {
257 <        return (int)(s & (ushortMask << 16)) >>> 16;
257 >        return ((int) s) >>> 16;
258      }
259  
260      private static int phaseOf(long s) {
261 <        return (int)(s >>> 32);
261 >        return (int) (s >>> 32);
262      }
263  
264      private static int arrivedOf(long s) {
# Line 225 | Line 266 | public class Phaser {
266      }
267  
268      private static long stateFor(int phase, int parties, int unarrived) {
269 <        return (((long)phase) << 32) | ((parties << 16) | unarrived);
269 >        return ((((long) phase) << 32) | (((long) parties) << 16) |
270 >                (long) unarrived);
271      }
272  
273      private static long trippedStateFor(int phase, int parties) {
274 <        return (((long)phase) << 32) | ((parties << 16) | parties);
274 >        long lp = (long) parties;
275 >        return (((long) phase) << 32) | (lp << 16) | lp;
276      }
277  
278 <    private static IllegalStateException badBounds(int parties, int unarrived) {
279 <        return new IllegalStateException
280 <            ("Attempt to set " + unarrived +
281 <             " unarrived of " + parties + " parties");
278 >    /**
279 >     * Returns message string for bad bounds exceptions.
280 >     */
281 >    private static String badBounds(int parties, int unarrived) {
282 >        return ("Attempt to set " + unarrived +
283 >                " unarrived of " + parties + " parties");
284      }
285  
286      /**
# Line 244 | Line 289 | public class Phaser {
289      private final Phaser parent;
290  
291      /**
292 <     * The root of Phaser tree. Equals this if not in a tree.  Used to
292 >     * The root of phaser tree. Equals this if not in a tree.  Used to
293       * support faster state push-down.
294       */
295      private final Phaser root;
# Line 252 | Line 297 | public class Phaser {
297      // Wait queues
298  
299      /**
300 <     * Heads of Treiber stacks waiting for nonFJ threads. To eliminate
300 >     * Heads of Treiber stacks for waiting threads. To eliminate
301       * contention while releasing some threads while adding others, we
302       * use two of them, alternating across even and odd phases.
303       */
# Line 260 | Line 305 | public class Phaser {
305      private final AtomicReference<QNode> oddQ  = new AtomicReference<QNode>();
306  
307      private AtomicReference<QNode> queueFor(int phase) {
308 <        return (phase & 1) == 0? evenQ : oddQ;
308 >        return ((phase & 1) == 0) ? evenQ : oddQ;
309      }
310  
311      /**
# Line 268 | Line 313 | public class Phaser {
313       * root if necessary.
314       */
315      private long getReconciledState() {
316 <        return parent == null? state : reconcileState();
316 >        return (parent == null) ? state : reconcileState();
317      }
318  
319      /**
# Line 295 | Line 340 | public class Phaser {
340      }
341  
342      /**
343 <     * Creates a new Phaser without any initially registered parties,
344 <     * initial phase number 0, and no parent.
343 >     * Creates a new phaser without any initially registered parties,
344 >     * initial phase number 0, and no parent. Any thread using this
345 >     * phaser will need to first register for it.
346       */
347      public Phaser() {
348          this(null);
349      }
350  
351      /**
352 <     * Creates a new Phaser with the given numbers of registered
352 >     * Creates a new phaser with the given numbers of registered
353       * unarrived parties, initial phase number 0, and no parent.
354 <     * @param parties the number of parties required to trip barrier.
354 >     *
355 >     * @param parties the number of parties required to trip barrier
356       * @throws IllegalArgumentException if parties less than zero
357 <     * or greater than the maximum number of parties supported.
357 >     * or greater than the maximum number of parties supported
358       */
359      public Phaser(int parties) {
360          this(null, parties);
361      }
362  
363      /**
364 <     * Creates a new Phaser with the given parent, without any
364 >     * Creates a new phaser with the given parent, without any
365       * initially registered parties. If parent is non-null this phaser
366       * is registered with the parent and its initial phase number is
367       * the same as that of parent phaser.
368 <     * @param parent the parent phaser.
368 >     *
369 >     * @param parent the parent phaser
370       */
371      public Phaser(Phaser parent) {
372          int phase = 0;
# Line 333 | Line 381 | public class Phaser {
381      }
382  
383      /**
384 <     * Creates a new Phaser with the given parent and numbers of
385 <     * registered unarrived parties. If parent is non-null this phaser
384 >     * Creates a new phaser with the given parent and numbers of
385 >     * registered unarrived parties. If parent is non-null, this phaser
386       * is registered with the parent and its initial phase number is
387       * the same as that of parent phaser.
388 <     * @param parent the parent phaser.
389 <     * @param parties the number of parties required to trip barrier.
388 >     *
389 >     * @param parent the parent phaser
390 >     * @param parties the number of parties required to trip barrier
391       * @throws IllegalArgumentException if parties less than zero
392 <     * or greater than the maximum number of parties supported.
392 >     * or greater than the maximum number of parties supported
393       */
394      public Phaser(Phaser parent, int parties) {
395          if (parties < 0 || parties > ushortMask)
# Line 358 | Line 407 | public class Phaser {
407  
408      /**
409       * Adds a new unarrived party to this phaser.
410 <     * @return the current barrier phase number upon registration
410 >     *
411 >     * @return the arrival phase number to which this registration applied
412       * @throws IllegalStateException if attempting to register more
413 <     * than the maximum supported number of parties.
413 >     * than the maximum supported number of parties
414       */
415      public int register() {
416          return doRegister(1);
# Line 368 | Line 418 | public class Phaser {
418  
419      /**
420       * Adds the given number of new unarrived parties to this phaser.
421 <     * @param parties the number of parties required to trip barrier.
422 <     * @return the current barrier phase number upon registration
421 >     *
422 >     * @param parties the number of parties required to trip barrier
423 >     * @return the arrival phase number to which this registration applied
424       * @throws IllegalStateException if attempting to register more
425 <     * than the maximum supported number of parties.
425 >     * than the maximum supported number of parties
426       */
427      public int bulkRegister(int parties) {
428          if (parties < 0)
# Line 394 | Line 445 | public class Phaser {
445              if (phase < 0)
446                  break;
447              if (parties > ushortMask || unarrived > ushortMask)
448 <                throw badBounds(parties, unarrived);
448 >                throw new IllegalStateException(badBounds(parties, unarrived));
449              if (phase == phaseOf(root.state) &&
450                  casState(s, stateFor(phase, parties, unarrived)))
451                  break;
# Line 404 | Line 455 | public class Phaser {
455  
456      /**
457       * Arrives at the barrier, but does not wait for others.  (You can
458 <     * in turn wait for others via {@link #awaitAdvance}).
458 >     * in turn wait for others via {@link #awaitAdvance}).  It is an
459 >     * unenforced usage error for an unregistered party to invoke this
460 >     * method.
461       *
462 <     * @return the barrier phase number upon entry to this method, or a
410 <     * negative value if terminated;
462 >     * @return the arrival phase number, or a negative value if terminated
463       * @throws IllegalStateException if not terminated and the number
464 <     * of unarrived parties would become negative.
464 >     * of unarrived parties would become negative
465       */
466      public int arrive() {
467          int phase;
468          for (;;) {
469              long s = state;
470              phase = phaseOf(s);
471 +            if (phase < 0)
472 +                break;
473              int parties = partiesOf(s);
474              int unarrived = unarrivedOf(s) - 1;
475              if (unarrived > 0) {        // Not the last arrival
# Line 427 | Line 481 | public class Phaser {
481                  if (par == null) {      // directly trip
482                      if (casState
483                          (s,
484 <                         trippedStateFor(onAdvance(phase, parties)? -1 :
484 >                         trippedStateFor(onAdvance(phase, parties) ? -1 :
485                                           ((phase + 1) & phaseMask), parties))) {
486                          releaseWaiters(phase);
487                          break;
# Line 441 | Line 495 | public class Phaser {
495                      }
496                  }
497              }
444            else if (phase < 0) // Don't throw exception if terminated
445                break;
498              else if (phase != phaseOf(root.state)) // or if unreconciled
499                  reconcileState();
500              else
501 <                throw badBounds(parties, unarrived);
501 >                throw new IllegalStateException(badBounds(parties, unarrived));
502          }
503          return phase;
504      }
505  
506      /**
507 <     * Arrives at the barrier, and deregisters from it, without
508 <     * waiting for others. Deregistration reduces number of parties
507 >     * Arrives at the barrier and deregisters from it without waiting
508 >     * for others. Deregistration reduces the number of parties
509       * required to trip the barrier in future phases.  If this phaser
510       * has a parent, and deregistration causes this phaser to have
511 <     * zero parties, this phaser is also deregistered from its parent.
511 >     * zero parties, this phaser also arrives at and is deregistered
512 >     * from its parent.  It is an unenforced usage error for an
513 >     * unregistered party to invoke this method.
514       *
515 <     * @return the current barrier phase number upon entry to
462 <     * this method, or a negative value if terminated;
515 >     * @return the arrival phase number, or a negative value if terminated
516       * @throws IllegalStateException if not terminated and the number
517 <     * of registered or unarrived parties would become negative.
517 >     * of registered or unarrived parties would become negative
518       */
519      public int arriveAndDeregister() {
520          // similar code to arrive, but too different to merge
# Line 470 | Line 523 | public class Phaser {
523          for (;;) {
524              long s = state;
525              phase = phaseOf(s);
526 +            if (phase < 0)
527 +                break;
528              int parties = partiesOf(s) - 1;
529              int unarrived = unarrivedOf(s) - 1;
530              if (parties >= 0) {
# Line 488 | Line 543 | public class Phaser {
543                  if (unarrived == 0) {
544                      if (casState
545                          (s,
546 <                         trippedStateFor(onAdvance(phase, parties)? -1 :
546 >                         trippedStateFor(onAdvance(phase, parties) ? -1 :
547                                           ((phase + 1) & phaseMask), parties))) {
548                          releaseWaiters(phase);
549                          break;
550                      }
551                      continue;
552                  }
498                if (phase < 0)
499                    break;
553                  if (par != null && phase != phaseOf(root.state)) {
554                      reconcileState();
555                      continue;
556                  }
557              }
558 <            throw badBounds(parties, unarrived);
558 >            throw new IllegalStateException(badBounds(parties, unarrived));
559          }
560          return phase;
561      }
562  
563      /**
564       * Arrives at the barrier and awaits others. Equivalent in effect
565 <     * to {@code awaitAdvance(arrive())}.  If you instead need to
566 <     * await with interruption of timeout, and/or deregister upon
567 <     * arrival, you can arrange them using analogous constructions.
568 <     * @return the phase on entry to this method
565 >     * to {@code awaitAdvance(arrive())}.  If you need to await with
566 >     * interruption or timeout, you can arrange this with an analogous
567 >     * construction using one of the other forms of the awaitAdvance
568 >     * method.  If instead you need to deregister upon arrival use
569 >     * {@code arriveAndDeregister}. It is an unenforced usage error
570 >     * for an unregistered party to invoke this method.
571 >     *
572 >     * @return the arrival phase number, or a negative number if terminated
573       * @throws IllegalStateException if not terminated and the number
574 <     * of unarrived parties would become negative.
574 >     * of unarrived parties would become negative
575       */
576      public int arriveAndAwaitAdvance() {
577          return awaitAdvance(arrive());
578      }
579  
580      /**
581 <     * Awaits the phase of the barrier to advance from the given
582 <     * value, or returns immediately if argument is negative or this
583 <     * barrier is terminated.
584 <     * @param phase the phase on entry to this method
585 <     * @return the phase on exit from this method
581 >     * Awaits the phase of the barrier to advance from the given phase
582 >     * value, returning immediately if the current phase of the
583 >     * barrier is not equal to the given phase value or this barrier
584 >     * is terminated.  It is an unenforced usage error for an
585 >     * unregistered party to invoke this method.
586 >     *
587 >     * @param phase an arrival phase number, or negative value if
588 >     * terminated; this argument is normally the value returned by a
589 >     * previous call to {@code arrive} or its variants
590 >     * @return the next arrival phase number, or a negative value
591 >     * if terminated or argument is negative
592       */
593      public int awaitAdvance(int phase) {
594          if (phase < 0)
# Line 534 | Line 597 | public class Phaser {
597          int p = phaseOf(s);
598          if (p != phase)
599              return p;
600 <        if (unarrivedOf(s) == 0)
600 >        if (unarrivedOf(s) == 0 && parent != null)
601              parent.awaitAdvance(phase);
602          // Fall here even if parent waited, to reconcile and help release
603          return untimedWait(phase);
604      }
605  
606      /**
607 <     * Awaits the phase of the barrier to advance from the given
608 <     * value, or returns immediately if argument is negative or this
609 <     * barrier is terminated, or throws InterruptedException if
610 <     * interrupted while waiting.
611 <     * @param phase the phase on entry to this method
612 <     * @return the phase on exit from this method
607 >     * Awaits the phase of the barrier to advance from the given phase
608 >     * value, throwing {@code InterruptedException} if interrupted
609 >     * while waiting, or returning immediately if the current phase of
610 >     * the barrier is not equal to the given phase value or this
611 >     * barrier is terminated. It is an unenforced usage error for an
612 >     * unregistered party to invoke this method.
613 >     *
614 >     * @param phase an arrival phase number, or negative value if
615 >     * terminated; this argument is normally the value returned by a
616 >     * previous call to {@code arrive} or its variants
617 >     * @return the next arrival phase number, or a negative value
618 >     * if terminated or argument is negative
619       * @throws InterruptedException if thread interrupted while waiting
620       */
621 <    public int awaitAdvanceInterruptibly(int phase) throws InterruptedException {
621 >    public int awaitAdvanceInterruptibly(int phase)
622 >        throws InterruptedException {
623          if (phase < 0)
624              return phase;
625          long s = getReconciledState();
626          int p = phaseOf(s);
627          if (p != phase)
628              return p;
629 <        if (unarrivedOf(s) != 0)
629 >        if (unarrivedOf(s) == 0 && parent != null)
630              parent.awaitAdvanceInterruptibly(phase);
631          return interruptibleWait(phase);
632      }
633  
634      /**
635 <     * Awaits the phase of the barrier to advance from the given value
636 <     * or the given timeout elapses, or returns immediately if
637 <     * argument is negative or this barrier is terminated.
638 <     * @param phase the phase on entry to this method
639 <     * @return the phase on exit from this method
635 >     * Awaits the phase of the barrier to advance from the given phase
636 >     * value or the given timeout to elapse, throwing {@code
637 >     * InterruptedException} if interrupted while waiting, or
638 >     * returning immediately if the current phase of the barrier is
639 >     * not equal to the given phase value or this barrier is
640 >     * terminated.  It is an unenforced usage error for an
641 >     * unregistered party to invoke this method.
642 >     *
643 >     * @param phase an arrival phase number, or negative value if
644 >     * terminated; this argument is normally the value returned by a
645 >     * previous call to {@code arrive} or its variants
646 >     * @param timeout how long to wait before giving up, in units of
647 >     *        {@code unit}
648 >     * @param unit a {@code TimeUnit} determining how to interpret the
649 >     *        {@code timeout} parameter
650 >     * @return the next arrival phase number, or a negative value
651 >     * if terminated or argument is negative
652       * @throws InterruptedException if thread interrupted while waiting
653       * @throws TimeoutException if timed out while waiting
654       */
655 <    public int awaitAdvanceInterruptibly(int phase, long timeout, TimeUnit unit)
655 >    public int awaitAdvanceInterruptibly(int phase,
656 >                                         long timeout, TimeUnit unit)
657          throws InterruptedException, TimeoutException {
658          if (phase < 0)
659              return phase;
# Line 578 | Line 661 | public class Phaser {
661          int p = phaseOf(s);
662          if (p != phase)
663              return p;
664 <        if (unarrivedOf(s) == 0)
664 >        if (unarrivedOf(s) == 0 && parent != null)
665              parent.awaitAdvanceInterruptibly(phase, timeout, unit);
666          return timedWait(phase, unit.toNanos(timeout));
667      }
# Line 611 | Line 694 | public class Phaser {
694       * Returns the current phase number. The maximum phase number is
695       * {@code Integer.MAX_VALUE}, after which it restarts at
696       * zero. Upon termination, the phase number is negative.
697 +     *
698       * @return the phase number, or a negative value if terminated
699       */
700      public final int getPhase() {
# Line 618 | Line 702 | public class Phaser {
702      }
703  
704      /**
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    /**
705       * Returns the number of parties registered at this barrier.
706 +     *
707       * @return the number of parties
708       */
709      public int getRegisteredParties() {
# Line 635 | Line 711 | public class Phaser {
711      }
712  
713      /**
714 <     * Returns the number of parties that have arrived at the current
715 <     * phase of this barrier.
714 >     * Returns the number of registered parties that have arrived at
715 >     * the current phase of this barrier.
716 >     *
717       * @return the number of arrived parties
718       */
719      public int getArrivedParties() {
# Line 646 | Line 723 | public class Phaser {
723      /**
724       * Returns the number of registered parties that have not yet
725       * arrived at the current phase of this barrier.
726 +     *
727       * @return the number of unarrived parties
728       */
729      public int getUnarrivedParties() {
# Line 653 | Line 731 | public class Phaser {
731      }
732  
733      /**
734 <     * Returns the parent of this phaser, or null if none.
735 <     * @return the parent of this phaser, or null if none
734 >     * Returns the parent of this phaser, or {@code null} if none.
735 >     *
736 >     * @return the parent of this phaser, or {@code null} if none
737       */
738      public Phaser getParent() {
739          return parent;
# Line 663 | Line 742 | public class Phaser {
742      /**
743       * Returns the root ancestor of this phaser, which is the same as
744       * this phaser if it has no parent.
745 +     *
746       * @return the root ancestor of this phaser
747       */
748      public Phaser getRoot() {
# Line 671 | Line 751 | public class Phaser {
751  
752      /**
753       * Returns {@code true} if this barrier has been terminated.
754 +     *
755       * @return {@code true} if this barrier has been terminated
756       */
757      public boolean isTerminated() {
# Line 678 | Line 759 | public class Phaser {
759      }
760  
761      /**
762 <     * Overridable method to perform an action upon phase advance, and
763 <     * to control termination. This method is invoked whenever the
764 <     * barrier is tripped (and thus all other waiting parties are
765 <     * dormant). If it returns true, then, rather than advance the
766 <     * phase number, this barrier will be set to a final termination
767 <     * state, and subsequent calls to {@code isTerminated} will
768 <     * return true.
762 >     * Overridable method to perform an action upon impending phase
763 >     * advance, and to control termination. This method is invoked
764 >     * upon arrival of the party tripping the barrier (when all other
765 >     * waiting parties are dormant).  If this method returns {@code
766 >     * true}, then, rather than advance the phase number, this barrier
767 >     * will be set to a final termination state, and subsequent calls
768 >     * to {@link #isTerminated} will return true. Any (unchecked)
769 >     * Exception or Error thrown by an invocation of this method is
770 >     * propagated to the party attempting to trip the barrier, in
771 >     * which case no advance occurs.
772 >     *
773 >     * <p>The arguments to this method provide the state of the phaser
774 >     * prevailing for the current transition. (When called from within
775 >     * an implementation of {@code onAdvance} the values returned by
776 >     * methods such as {@code getPhase} may or may not reliably
777 >     * indicate the state to which this transition applies.)
778       *
779 <     * <p> The default version returns true when the number of
779 >     * <p>The default version returns {@code true} when the number of
780       * registered parties is zero. Normally, overrides that arrange
781       * termination for other reasons should also preserve this
782       * property.
783       *
784 <     * <p> You may override this method to perform an action with side
785 <     * effects visible to participating tasks, but it is in general
786 <     * only sensible to do so in designs where all parties register
787 <     * before any arrive, and all {@code awaitAdvance} at each phase.
788 <     * Otherwise, you cannot ensure lack of interference. In
789 <     * particular, this method may be invoked more than once per
790 <     * transition if other parties successfully register while the
701 <     * invocation of this method is in progress, thus postponing the
702 <     * transition until those parties also arrive, re-triggering this
703 <     * method.
784 >     * <p>You may override this method to perform an action with side
785 >     * effects visible to participating tasks, but doing so requires
786 >     * care: Method {@code onAdvance} may be invoked more than once
787 >     * per transition.  Further, unless all parties register before
788 >     * any arrive, and all {@link #awaitAdvance} at each phase, then
789 >     * you cannot ensure lack of interference from other parties
790 >     * during the invocation of this method.
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
735    /**
736     * The number of times to spin before blocking in timed waits.
737     * The value is empirically derived.
738     */
739    static final int maxTimedSpins = (NCPUS < 2)? 0 : 32;
740
741    /**
742     * The number of times to spin before blocking in untimed waits.
743     * This is greater than timed value because untimed waits spin
744     * faster since they don't need to check times on each spin.
745     */
746    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
819      /**
820 <     * Wait nodes for Treiber stack representing wait queue for non-FJ
756 <     * tasks.
820 >     * Wait nodes for Treiber stack representing wait queue
821       */
822 <    static final class QNode {
823 <        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, false);
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