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.11 by jsr166, Thu Mar 19 04:49:44 2009 UTC vs.
Revision 1.15 by jsr166, Tue Jul 21 18:11:44 2009 UTC

# Line 93 | Line 93 | import java.lang.reflect.*;
93   * idiom is for the method setting this up to first register, then
94   * start the actions, then deregister, as in:
95   *
96 < * <pre>
97 < *  void runTasks(List&lt;Runnable&gt; list) {
98 < *    final Phaser phaser = new Phaser(1); // "1" to register self
99 < *    for (Runnable r : list) {
100 < *      phaser.register();
101 < *      new Thread() {
102 < *        public void run() {
103 < *          phaser.arriveAndAwaitAdvance(); // await all creation
104 < *          r.run();
105 < *          phaser.arriveAndDeregister();   // signal completion
106 < *        }
107 < *      }.start();
96 > *  <pre> {@code
97 > * void runTasks(List<Runnable> list) {
98 > *   final Phaser phaser = new Phaser(1); // "1" to register self
99 > *   for (Runnable r : list) {
100 > *     phaser.register();
101 > *     new Thread() {
102 > *       public void run() {
103 > *         phaser.arriveAndAwaitAdvance(); // await all creation
104 > *         r.run();
105 > *         phaser.arriveAndDeregister();   // signal completion
106 > *       }
107 > *     }.start();
108   *   }
109   *
110   *   doSomethingOnBehalfOfWorkers();
# Line 113 | Line 113 | import java.lang.reflect.*;
113   *   p = phaser.awaitAdvance(p); // ... and await arrival
114   *   otherActions(); // do other things while tasks execute
115   *   phaser.awaitAdvance(p); // await final completion
116 < * }
117 < * </pre>
116 > * }}</pre>
117   *
118   * <p>One way to cause a set of threads to repeatedly perform actions
119   * for a given number of iterations is to override {@code onAdvance}:
120   *
121 < * <pre>
122 < *  void startTasks(List&lt;Runnable&gt; list, final int iterations) {
123 < *    final Phaser phaser = new Phaser() {
124 < *       public boolean onAdvance(int phase, int registeredParties) {
125 < *         return phase &gt;= iterations || registeredParties == 0;
121 > *  <pre> {@code
122 > * void startTasks(List<Runnable> list, final int iterations) {
123 > *   final Phaser phaser = new Phaser() {
124 > *     public boolean onAdvance(int phase, int registeredParties) {
125 > *       return phase >= iterations || registeredParties == 0;
126 > *     }
127 > *   };
128 > *   phaser.register();
129 > *   for (Runnable r : list) {
130 > *     phaser.register();
131 > *     new Thread() {
132 > *       public void run() {
133 > *         do {
134 > *           r.run();
135 > *           phaser.arriveAndAwaitAdvance();
136 > *         } while(!phaser.isTerminated();
137   *       }
138 < *    };
129 < *    phaser.register();
130 < *    for (Runnable r : list) {
131 < *      phaser.register();
132 < *      new Thread() {
133 < *        public void run() {
134 < *           do {
135 < *             r.run();
136 < *             phaser.arriveAndAwaitAdvance();
137 < *           } while(!phaser.isTerminated();
138 < *        }
139 < *      }.start();
138 > *     }.start();
139   *   }
140   *   phaser.arriveAndDeregister(); // deregister self, don't wait
141 < * }
143 < * </pre>
141 > * }}</pre>
142   *
143   * <p> To create a set of tasks using a tree of Phasers,
144   * you could use code of the following form, assuming a
145   * Task class with a constructor accepting a Phaser that
146   * it registers for upon construction:
147 < * <pre>
148 < *  void build(Task[] actions, int lo, int hi, Phaser b) {
149 < *    int step = (hi - lo) / TASKS_PER_PHASER;
150 < *    if (step &gt; 1) {
151 < *       int i = lo;
152 < *       while (i &lt; hi) {
153 < *         int r = Math.min(i + step, hi);
154 < *         build(actions, i, r, new Phaser(b));
155 < *         i = r;
156 < *       }
157 < *    }
158 < *    else {
159 < *      for (int i = lo; i &lt; hi; ++i)
160 < *        actions[i] = new Task(b);
161 < *        // assumes new Task(b) performs b.register()
162 < *    }
163 < *  }
164 < *  // .. initially called, for n tasks via
167 < *  build(new Task[n], 0, n, new Phaser());
168 < * </pre>
147 > *  <pre> {@code
148 > * void build(Task[] actions, int lo, int hi, Phaser b) {
149 > *   int step = (hi - lo) / TASKS_PER_PHASER;
150 > *   if (step > 1) {
151 > *     int i = lo;
152 > *     while (i < hi) {
153 > *       int r = Math.min(i + step, hi);
154 > *       build(actions, i, r, new Phaser(b));
155 > *       i = r;
156 > *     }
157 > *   } else {
158 > *     for (int i = lo; i < hi; ++i)
159 > *       actions[i] = new Task(b);
160 > *       // 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());}</pre>
165   *
166   * The best value of {@code TASKS_PER_PHASER} depends mainly on
167   * expected barrier synchronization rates. A value as low as four may
# Line 238 | Line 234 | public class Phaser {
234      }
235  
236      /**
237 <     * Returns message string for bad bounds exceptions
237 >     * Returns message string for bad bounds exceptions.
238       */
239      private static String badBounds(int parties, int unarrived) {
240          return ("Attempt to set " + unarrived +
# Line 313 | Line 309 | public class Phaser {
309      /**
310       * Creates a new Phaser with the given numbers of registered
311       * unarrived parties, initial phase number 0, and no parent.
312 <     * @param parties the number of parties required to trip barrier.
312 >     *
313 >     * @param parties the number of parties required to trip barrier
314       * @throws IllegalArgumentException if parties less than zero
315 <     * or greater than the maximum number of parties supported.
315 >     * or greater than the maximum number of parties supported
316       */
317      public Phaser(int parties) {
318          this(null, parties);
# Line 326 | Line 323 | public class Phaser {
323       * initially registered parties. If parent is non-null this phaser
324       * is registered with the parent and its initial phase number is
325       * the same as that of parent phaser.
326 <     * @param parent the parent phaser.
326 >     *
327 >     * @param parent the parent phaser
328       */
329      public Phaser(Phaser parent) {
330          int phase = 0;
# Line 342 | Line 340 | public class Phaser {
340  
341      /**
342       * Creates a new Phaser with the given parent and numbers of
343 <     * registered unarrived parties. If parent is non-null this phaser
343 >     * registered unarrived parties. If parent is non-null, this phaser
344       * is registered with the parent and its initial phase number is
345       * the same as that of parent phaser.
346 <     * @param parent the parent phaser.
347 <     * @param parties the number of parties required to trip barrier.
346 >     *
347 >     * @param parent the parent phaser
348 >     * @param parties the number of parties required to trip barrier
349       * @throws IllegalArgumentException if parties less than zero
350 <     * or greater than the maximum number of parties supported.
350 >     * or greater than the maximum number of parties supported
351       */
352      public Phaser(Phaser parent, int parties) {
353          if (parties < 0 || parties > ushortMask)
# Line 366 | Line 365 | public class Phaser {
365  
366      /**
367       * Adds a new unarrived party to this phaser.
368 +     *
369       * @return the current barrier phase number upon registration
370       * @throws IllegalStateException if attempting to register more
371 <     * than the maximum supported number of parties.
371 >     * than the maximum supported number of parties
372       */
373      public int register() {
374          return doRegister(1);
# Line 376 | Line 376 | public class Phaser {
376  
377      /**
378       * Adds the given number of new unarrived parties to this phaser.
379 <     * @param parties the number of parties required to trip barrier.
379 >     *
380 >     * @param parties the number of parties required to trip barrier
381       * @return the current barrier phase number upon registration
382       * @throws IllegalStateException if attempting to register more
383 <     * than the maximum supported number of parties.
383 >     * than the maximum supported number of parties
384       */
385      public int bulkRegister(int parties) {
386          if (parties < 0)
# Line 399 | Line 400 | public class Phaser {
400              phase = phaseOf(s);
401              int unarrived = unarrivedOf(s) + registrations;
402              int parties = partiesOf(s) + registrations;
403 <            if (phase < 0)
403 >            if (phase < 0)
404                  break;
405              if (parties > ushortMask || unarrived > ushortMask)
406                  throw new IllegalStateException(badBounds(parties, unarrived));
# Line 415 | Line 416 | public class Phaser {
416       * in turn wait for others via {@link #awaitAdvance}).
417       *
418       * @return the barrier phase number upon entry to this method, or a
419 <     * negative value if terminated;
419 >     * negative value if terminated
420       * @throws IllegalStateException if not terminated and the number
421 <     * of unarrived parties would become negative.
421 >     * of unarrived parties would become negative
422       */
423      public int arrive() {
424          int phase;
# Line 467 | Line 468 | public class Phaser {
468       * zero parties, this phaser is also deregistered from its parent.
469       *
470       * @return the current barrier phase number upon entry to
471 <     * this method, or a negative value if terminated;
471 >     * this method, or a negative value if terminated
472       * @throws IllegalStateException if not terminated and the number
473 <     * of registered or unarrived parties would become negative.
473 >     * of registered or unarrived parties would become negative
474       */
475      public int arriveAndDeregister() {
476          // similar code to arrive, but too different to merge
# Line 520 | Line 521 | public class Phaser {
521       * to {@code awaitAdvance(arrive())}.  If you instead need to
522       * await with interruption of timeout, and/or deregister upon
523       * arrival, you can arrange them using analogous constructions.
524 +     *
525       * @return the phase on entry to this method
526       * @throws IllegalStateException if not terminated and the number
527 <     * of unarrived parties would become negative.
527 >     * of unarrived parties would become negative
528       */
529      public int arriveAndAwaitAdvance() {
530          return awaitAdvance(arrive());
# Line 532 | Line 534 | public class Phaser {
534       * Awaits the phase of the barrier to advance from the given
535       * value, or returns immediately if argument is negative or this
536       * barrier is terminated.
537 +     *
538       * @param phase the phase on entry to this method
539       * @return the phase on exit from this method
540       */
# Line 553 | Line 556 | public class Phaser {
556       * value, or returns immediately if argument is negative or this
557       * barrier is terminated, or throws InterruptedException if
558       * interrupted while waiting.
559 +     *
560       * @param phase the phase on entry to this method
561       * @return the phase on exit from this method
562       * @throws InterruptedException if thread interrupted while waiting
563       */
564 <    public int awaitAdvanceInterruptibly(int phase)
564 >    public int awaitAdvanceInterruptibly(int phase)
565          throws InterruptedException {
566          if (phase < 0)
567              return phase;
# Line 574 | Line 578 | public class Phaser {
578       * Awaits the phase of the barrier to advance from the given value
579       * or the given timeout elapses, or returns immediately if
580       * argument is negative or this barrier is terminated.
581 +     *
582       * @param phase the phase on entry to this method
583       * @return the phase on exit from this method
584       * @throws InterruptedException if thread interrupted while waiting
# Line 620 | Line 625 | public class Phaser {
625       * Returns the current phase number. The maximum phase number is
626       * {@code Integer.MAX_VALUE}, after which it restarts at
627       * zero. Upon termination, the phase number is negative.
628 +     *
629       * @return the phase number, or a negative value if terminated
630       */
631      public final int getPhase() {
# Line 628 | Line 634 | public class Phaser {
634  
635      /**
636       * Returns {@code true} if the current phase number equals the given phase.
637 +     *
638       * @param phase the phase
639       * @return {@code true} if the current phase number equals the given phase
640       */
# Line 637 | Line 644 | public class Phaser {
644  
645      /**
646       * Returns the number of parties registered at this barrier.
647 +     *
648       * @return the number of parties
649       */
650      public int getRegisteredParties() {
# Line 646 | Line 654 | public class Phaser {
654      /**
655       * Returns the number of parties that have arrived at the current
656       * phase of this barrier.
657 +     *
658       * @return the number of arrived parties
659       */
660      public int getArrivedParties() {
# Line 655 | Line 664 | public class Phaser {
664      /**
665       * Returns the number of registered parties that have not yet
666       * arrived at the current phase of this barrier.
667 +     *
668       * @return the number of unarrived parties
669       */
670      public int getUnarrivedParties() {
# Line 663 | Line 673 | public class Phaser {
673  
674      /**
675       * Returns the parent of this phaser, or null if none.
676 +     *
677       * @return the parent of this phaser, or null if none
678       */
679      public Phaser getParent() {
# Line 672 | Line 683 | public class Phaser {
683      /**
684       * Returns the root ancestor of this phaser, which is the same as
685       * this phaser if it has no parent.
686 +     *
687       * @return the root ancestor of this phaser
688       */
689      public Phaser getRoot() {
# Line 680 | Line 692 | public class Phaser {
692  
693      /**
694       * Returns {@code true} if this barrier has been terminated.
695 +     *
696       * @return {@code true} if this barrier has been terminated
697       */
698      public boolean isTerminated() {
# Line 795 | Line 808 | public class Phaser {
808                  try {
809                      ForkJoinPool.managedBlock(this, false);
810                  } catch (InterruptedException ie) {
811 <                }
811 >                }
812              }
813              return wasInterrupted;
814          }
# Line 803 | Line 816 | public class Phaser {
816      }
817  
818      /**
819 <     * Removes and signals waiting threads from wait queue
819 >     * Removes and signals waiting threads from wait queue.
820       */
821      private void releaseWaiters(int phase) {
822          AtomicReference<QNode> head = queueFor(phase);
# Line 815 | Line 828 | public class Phaser {
828      }
829  
830      /**
831 <     * Tries to enqueue given node in the appropriate wait queue
831 >     * Tries to enqueue given node in the appropriate wait queue.
832 >     *
833       * @return true if successful
834       */
835      private boolean tryEnqueue(QNode node) {
# Line 825 | Line 839 | public class Phaser {
839  
840      /**
841       * Enqueues node and waits unless aborted or signalled.
842 +     *
843       * @return current phase
844       */
845      private int untimedWait(int phase) {
# Line 933 | Line 948 | public class Phaser {
948              throws NoSuchFieldException, IllegalAccessException {
949          Field f = Unsafe.class.getDeclaredField("theUnsafe");
950          f.setAccessible(true);
951 <        return (Unsafe)f.get(null);
951 >        return (Unsafe) f.get(null);
952      }
953  
954      private static long fieldOffset(String fieldName)
955              throws NoSuchFieldException {
956 <        return _unsafe.objectFieldOffset
956 >        return UNSAFE.objectFieldOffset
957              (Phaser.class.getDeclaredField(fieldName));
958      }
959  
960 <    static final Unsafe _unsafe;
960 >    static final Unsafe UNSAFE;
961      static final long stateOffset;
962  
963      static {
964          try {
965 <            _unsafe = getUnsafe();
965 >            UNSAFE = getUnsafe();
966              stateOffset = fieldOffset("state");
967 <        } catch (Exception e) {
967 >        } catch (Throwable e) {
968              throw new RuntimeException("Could not initialize intrinsics", e);
969          }
970      }
971  
972      final boolean casState(long cmp, long val) {
973 <        return _unsafe.compareAndSwapLong(this, stateOffset, cmp, val);
973 >        return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val);
974      }
975   }

Diff Legend

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