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.12 by jsr166, Thu Mar 19 05:10:42 2009 UTC vs.
Revision 1.16 by jsr166, Wed Jul 22 01:36:51 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 179 | Line 175 | import java.lang.reflect.*;
175   * parties result in IllegalStateExceptions. However, you can and
176   * should create tiered phasers to accommodate arbitrarily large sets
177   * of participants.
178 + *
179 + * @since 1.7
180 + * @author Doug Lea
181   */
182   public class Phaser {
183      /*
# Line 238 | Line 237 | public class Phaser {
237      }
238  
239      /**
240 <     * Returns message string for bad bounds exceptions
240 >     * Returns message string for bad bounds exceptions.
241       */
242      private static String badBounds(int parties, int unarrived) {
243          return ("Attempt to set " + unarrived +
# Line 313 | Line 312 | public class Phaser {
312      /**
313       * Creates a new Phaser with the given numbers of registered
314       * unarrived parties, initial phase number 0, and no parent.
315 <     * @param parties the number of parties required to trip barrier.
315 >     *
316 >     * @param parties the number of parties required to trip barrier
317       * @throws IllegalArgumentException if parties less than zero
318 <     * or greater than the maximum number of parties supported.
318 >     * or greater than the maximum number of parties supported
319       */
320      public Phaser(int parties) {
321          this(null, parties);
# Line 326 | Line 326 | public class Phaser {
326       * initially registered parties. If parent is non-null this phaser
327       * is registered with the parent and its initial phase number is
328       * the same as that of parent phaser.
329 <     * @param parent the parent phaser.
329 >     *
330 >     * @param parent the parent phaser
331       */
332      public Phaser(Phaser parent) {
333          int phase = 0;
# Line 342 | Line 343 | public class Phaser {
343  
344      /**
345       * Creates a new Phaser with the given parent and numbers of
346 <     * registered unarrived parties. If parent is non-null this phaser
346 >     * registered unarrived parties. If parent is non-null, this phaser
347       * is registered with the parent and its initial phase number is
348       * the same as that of parent phaser.
349 <     * @param parent the parent phaser.
350 <     * @param parties the number of parties required to trip barrier.
349 >     *
350 >     * @param parent the parent phaser
351 >     * @param parties the number of parties required to trip barrier
352       * @throws IllegalArgumentException if parties less than zero
353 <     * or greater than the maximum number of parties supported.
353 >     * or greater than the maximum number of parties supported
354       */
355      public Phaser(Phaser parent, int parties) {
356          if (parties < 0 || parties > ushortMask)
# Line 366 | Line 368 | public class Phaser {
368  
369      /**
370       * Adds a new unarrived party to this phaser.
371 +     *
372       * @return the current barrier phase number upon registration
373       * @throws IllegalStateException if attempting to register more
374 <     * than the maximum supported number of parties.
374 >     * than the maximum supported number of parties
375       */
376      public int register() {
377          return doRegister(1);
# Line 376 | Line 379 | public class Phaser {
379  
380      /**
381       * Adds the given number of new unarrived parties to this phaser.
382 <     * @param parties the number of parties required to trip barrier.
382 >     *
383 >     * @param parties the number of parties required to trip barrier
384       * @return the current barrier phase number upon registration
385       * @throws IllegalStateException if attempting to register more
386 <     * than the maximum supported number of parties.
386 >     * than the maximum supported number of parties
387       */
388      public int bulkRegister(int parties) {
389          if (parties < 0)
# Line 415 | Line 419 | public class Phaser {
419       * in turn wait for others via {@link #awaitAdvance}).
420       *
421       * @return the barrier phase number upon entry to this method, or a
422 <     * negative value if terminated;
422 >     * negative value if terminated
423       * @throws IllegalStateException if not terminated and the number
424 <     * of unarrived parties would become negative.
424 >     * of unarrived parties would become negative
425       */
426      public int arrive() {
427          int phase;
# Line 467 | Line 471 | public class Phaser {
471       * zero parties, this phaser is also deregistered from its parent.
472       *
473       * @return the current barrier phase number upon entry to
474 <     * this method, or a negative value if terminated;
474 >     * this method, or a negative value if terminated
475       * @throws IllegalStateException if not terminated and the number
476 <     * of registered or unarrived parties would become negative.
476 >     * of registered or unarrived parties would become negative
477       */
478      public int arriveAndDeregister() {
479          // similar code to arrive, but too different to merge
# Line 520 | Line 524 | public class Phaser {
524       * to {@code awaitAdvance(arrive())}.  If you instead need to
525       * await with interruption of timeout, and/or deregister upon
526       * arrival, you can arrange them using analogous constructions.
527 +     *
528       * @return the phase on entry to this method
529       * @throws IllegalStateException if not terminated and the number
530 <     * of unarrived parties would become negative.
530 >     * of unarrived parties would become negative
531       */
532      public int arriveAndAwaitAdvance() {
533          return awaitAdvance(arrive());
# Line 532 | Line 537 | public class Phaser {
537       * Awaits the phase of the barrier to advance from the given
538       * value, or returns immediately if argument is negative or this
539       * barrier is terminated.
540 +     *
541       * @param phase the phase on entry to this method
542       * @return the phase on exit from this method
543       */
# Line 553 | Line 559 | public class Phaser {
559       * value, or returns immediately if argument is negative or this
560       * barrier is terminated, or throws InterruptedException if
561       * interrupted while waiting.
562 +     *
563       * @param phase the phase on entry to this method
564       * @return the phase on exit from this method
565       * @throws InterruptedException if thread interrupted while waiting
# Line 574 | Line 581 | public class Phaser {
581       * Awaits the phase of the barrier to advance from the given value
582       * or the given timeout elapses, or returns immediately if
583       * argument is negative or this barrier is terminated.
584 +     *
585       * @param phase the phase on entry to this method
586       * @return the phase on exit from this method
587       * @throws InterruptedException if thread interrupted while waiting
# Line 620 | Line 628 | public class Phaser {
628       * Returns the current phase number. The maximum phase number is
629       * {@code Integer.MAX_VALUE}, after which it restarts at
630       * zero. Upon termination, the phase number is negative.
631 +     *
632       * @return the phase number, or a negative value if terminated
633       */
634      public final int getPhase() {
# Line 628 | Line 637 | public class Phaser {
637  
638      /**
639       * Returns {@code true} if the current phase number equals the given phase.
640 +     *
641       * @param phase the phase
642       * @return {@code true} if the current phase number equals the given phase
643       */
# Line 637 | Line 647 | public class Phaser {
647  
648      /**
649       * Returns the number of parties registered at this barrier.
650 +     *
651       * @return the number of parties
652       */
653      public int getRegisteredParties() {
# Line 646 | Line 657 | public class Phaser {
657      /**
658       * Returns the number of parties that have arrived at the current
659       * phase of this barrier.
660 +     *
661       * @return the number of arrived parties
662       */
663      public int getArrivedParties() {
# Line 655 | Line 667 | public class Phaser {
667      /**
668       * Returns the number of registered parties that have not yet
669       * arrived at the current phase of this barrier.
670 +     *
671       * @return the number of unarrived parties
672       */
673      public int getUnarrivedParties() {
# Line 663 | Line 676 | public class Phaser {
676  
677      /**
678       * Returns the parent of this phaser, or null if none.
679 +     *
680       * @return the parent of this phaser, or null if none
681       */
682      public Phaser getParent() {
# Line 672 | Line 686 | public class Phaser {
686      /**
687       * Returns the root ancestor of this phaser, which is the same as
688       * this phaser if it has no parent.
689 +     *
690       * @return the root ancestor of this phaser
691       */
692      public Phaser getRoot() {
# Line 680 | Line 695 | public class Phaser {
695  
696      /**
697       * Returns {@code true} if this barrier has been terminated.
698 +     *
699       * @return {@code true} if this barrier has been terminated
700       */
701      public boolean isTerminated() {
# Line 803 | Line 819 | public class Phaser {
819      }
820  
821      /**
822 <     * Removes and signals waiting threads from wait queue
822 >     * Removes and signals waiting threads from wait queue.
823       */
824      private void releaseWaiters(int phase) {
825          AtomicReference<QNode> head = queueFor(phase);
# Line 815 | Line 831 | public class Phaser {
831      }
832  
833      /**
834 <     * Tries to enqueue given node in the appropriate wait queue
834 >     * Tries to enqueue given node in the appropriate wait queue.
835 >     *
836       * @return true if successful
837       */
838      private boolean tryEnqueue(QNode node) {
# Line 825 | Line 842 | public class Phaser {
842  
843      /**
844       * Enqueues node and waits unless aborted or signalled.
845 +     *
846       * @return current phase
847       */
848      private int untimedWait(int phase) {
# Line 938 | Line 956 | public class Phaser {
956  
957      private static long fieldOffset(String fieldName)
958              throws NoSuchFieldException {
959 <        return _unsafe.objectFieldOffset
959 >        return UNSAFE.objectFieldOffset
960              (Phaser.class.getDeclaredField(fieldName));
961      }
962  
963 <    static final Unsafe _unsafe;
963 >    static final Unsafe UNSAFE;
964      static final long stateOffset;
965  
966      static {
967          try {
968 <            _unsafe = getUnsafe();
968 >            UNSAFE = getUnsafe();
969              stateOffset = fieldOffset("state");
970          } catch (Throwable e) {
971              throw new RuntimeException("Could not initialize intrinsics", e);
# Line 955 | Line 973 | public class Phaser {
973      }
974  
975      final boolean casState(long cmp, long val) {
976 <        return _unsafe.compareAndSwapLong(this, stateOffset, cmp, val);
976 >        return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val);
977      }
978   }

Diff Legend

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