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.27 by dl, Sat Aug 8 19:36:52 2009 UTC vs.
Revision 1.37 by jsr166, Mon Aug 24 00:48:52 2009 UTC

# Line 12 | Line 12 | import java.util.concurrent.atomic.Atomi
12   import java.util.concurrent.locks.LockSupport;
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}).
22 > * <li> The number of parties <em>registered</em> to synchronize on a
23 > * phaser may vary over time.  Tasks may be registered at any time
24 > * (using methods {@link #register}, {@link #bulkRegister}, or forms
25 > * of constructors establishing initial numbers of parties), and may
26 > * optionally be deregistered upon any arrival (using {@link
27 > * #arriveAndDeregister}).  As is the case with most basic
28 > * synchronization constructs, registration and deregistration affect
29 > * only internal counts; they do not establish any further internal
30 > * bookkeeping, so tasks cannot query whether they are registered.
31 > * (However, you can introduce such bookkeeping by subclassing this
32 > * class.)
33 > *
34 > * <li> Each generation has an associated phase number. The phase
35 > * number starts at zero, amd advances when all parties arrive at the
36 > * barrier, wrapping around to zero after reaching {@code
37 > * Integer.MAX_VALUE}.
38   *
39   * <li> Like a {@code CyclicBarrier}, a phaser may be repeatedly
40   * awaited.  Method {@link #arriveAndAwaitAdvance} has effect
# Line 42 | Line 46 | import java.util.concurrent.locks.LockSu
46   *
47   *   <li> Arriving at a barrier. Methods {@link #arrive} and
48   *       {@link #arriveAndDeregister} do not block, but return
49 < *       the phase value current upon entry to the method.
49 > *       an associated <em>arrival phase number</em>;
50 > *       that is, the phase number of the barrier to which the
51 > *       arrival applied.
52   *
53   *   <li> Awaiting others. Method {@link #awaitAdvance} requires an
54 < *       argument indicating the entry phase, and returns when the
55 < *       barrier advances to a new phase.
54 > *       argument indicating an arrival phase number, and returns
55 > *       when the barrier advances to a new phase.
56   * </ul>
57   *
52 – *
58   * <li> Barrier actions, performed by the task triggering a phase
59   * advance, are arranged by overriding method {@link #onAdvance(int,
60   * int)}, which also controls termination. Overriding this method is
# Line 85 | Line 90 | import java.util.concurrent.locks.LockSu
90   * ForkJoinPool}, which will ensure sufficient parallelism to execute
91   * tasks when others are blocked waiting for a phase to advance.
92   *
93 + * <li>The current state of a phaser may be monitored.  At any given
94 + * moment there are {@link #getRegisteredParties}, where {@link
95 + * #getArrivedParties} have arrived at the current phase ({@link
96 + * #getPhase}). When the remaining {@link #getUnarrivedParties})
97 + * arrive, the phase advances. Method {@link #toString} returns
98 + * snapshots of these state queries in a form convenient for
99 + * informal monitoring.
100 + *
101   * </ul>
102   *
103   * <p><b>Sample usages:</b>
# Line 95 | Line 108 | import java.util.concurrent.locks.LockSu
108   * first register, then start the actions, then deregister, as in:
109   *
110   *  <pre> {@code
111 < * void runTasks(List<Runnable> list) {
111 > * void runTasks(List<Runnable> tasks) {
112   *   final Phaser phaser = new Phaser(1); // "1" to register self
113   *   // create and start threads
114 < *   for (Runnable r : list) {
114 > *   for (Runnable task : tasks) {
115   *     phaser.register();
116   *     new Thread() {
117   *       public void run() {
118   *         phaser.arriveAndAwaitAdvance(); // await all creation
119 < *         r.run();
119 > *         task.run();
120   *       }
121   *     }.start();
122   *   }
# Line 116 | Line 129 | import java.util.concurrent.locks.LockSu
129   * for a given number of iterations is to override {@code onAdvance}:
130   *
131   *  <pre> {@code
132 < * void startTasks(List<Runnable> list, final int iterations) {
132 > * void startTasks(List<Runnable> tasks, final int iterations) {
133   *   final Phaser phaser = new Phaser() {
134   *     public boolean onAdvance(int phase, int registeredParties) {
135   *       return phase >= iterations || registeredParties == 0;
136   *     }
137   *   };
138   *   phaser.register();
139 < *   for (Runnable r : list) {
139 > *   for (Runnable task : tasks) {
140   *     phaser.register();
141   *     new Thread() {
142   *       public void run() {
143   *         do {
144 < *           r.run();
144 > *           task.run();
145   *           phaser.arriveAndAwaitAdvance();
146   *         } while(!phaser.isTerminated();
147   *       }
# Line 169 | Line 182 | import java.util.concurrent.locks.LockSu
182   *
183   * <p><b>Implementation notes</b>: This implementation restricts the
184   * maximum number of parties to 65535. Attempts to register additional
185 < * parties result in IllegalStateExceptions. However, you can and
185 > * parties result in {@code IllegalStateException}. However, you can and
186   * should create tiered phasers to accommodate arbitrarily large sets
187   * of participants.
188   *
# Line 366 | Line 379 | public class Phaser {
379      /**
380       * Adds a new unarrived party to this phaser.
381       *
382 <     * @return the current barrier phase number upon registration
382 >     * @return the arrival phase number to which this registration applied
383       * @throws IllegalStateException if attempting to register more
384       * than the maximum supported number of parties
385       */
# Line 378 | Line 391 | public class Phaser {
391       * Adds the given number of new unarrived parties to this phaser.
392       *
393       * @param parties the number of parties required to trip barrier
394 <     * @return the current barrier phase number upon registration
394 >     * @return the arrival phase number to which this registration applied
395       * @throws IllegalStateException if attempting to register more
396       * than the maximum supported number of parties
397       */
# Line 415 | Line 428 | public class Phaser {
428       * Arrives at the barrier, but does not wait for others.  (You can
429       * in turn wait for others via {@link #awaitAdvance}).
430       *
431 <     * @return the barrier phase number upon entry to this method, or a
419 <     * negative value if terminated
431 >     * @return the arrival phase number, or a negative value if terminated
432       * @throws IllegalStateException if not terminated and the number
433       * of unarrived parties would become negative
434       */
# Line 468 | Line 480 | public class Phaser {
480       * zero parties, this phaser also arrives at and is deregistered
481       * from its parent.
482       *
483 <     * @return the current barrier phase number upon entry to
472 <     * this method, or a negative value if terminated
483 >     * @return the arrival phase number, or a negative value if terminated
484       * @throws IllegalStateException if not terminated and the number
485       * of registered or unarrived parties would become negative
486       */
# Line 525 | Line 536 | public class Phaser {
536       * method.  If instead you need to deregister upon arrival use
537       * {@code arriveAndDeregister}.
538       *
539 <     * @return the phase on entry to this method
539 >     * @return the arrival phase number, or a negative number if terminated
540       * @throws IllegalStateException if not terminated and the number
541       * of unarrived parties would become negative
542       */
# Line 535 | Line 546 | public class Phaser {
546  
547      /**
548       * Awaits the phase of the barrier to advance from the given phase
549 <     * value, or returns immediately if current phase of the barrier
550 <     * is not equal to the given phase value or this barrier is
551 <     * terminated.
552 <     *
553 <     * @param phase the phase on entry to this method
554 <     * @return the phase on exit from this method
549 >     * value, returning immediately if the current phase of the
550 >     * barrier is not equal to the given phase value or this barrier
551 >     * is terminated.
552 >     *
553 >     * @param phase an arrival phase number, or negative value if
554 >     * terminated; this argument is normally the value returned by a
555 >     * previous call to {@code arrive} or its variants
556 >     * @return the next arrival phase number, or a negative value
557 >     * if terminated or argument is negative
558       */
559      public int awaitAdvance(int phase) {
560          if (phase < 0)
# Line 556 | Line 570 | public class Phaser {
570      }
571  
572      /**
573 <     * Awaits the phase of the barrier to advance from the given
574 <     * value, or returns immediately if argument is negative or this
575 <     * barrier is terminated, or throws InterruptedException if
576 <     * interrupted while waiting.
577 <     *
578 <     * @param phase the phase on entry to this method
579 <     * @return the phase on exit from this method
573 >     * Awaits the phase of the barrier to advance from the given phase
574 >     * value, throwing {@code InterruptedException} if interrupted while
575 >     * waiting, or returning immediately if the current phase of the
576 >     * barrier is not equal to the given phase value or this barrier
577 >     * is terminated.
578 >     *
579 >     * @param phase an arrival phase number, or negative value if
580 >     * terminated; this argument is normally the value returned by a
581 >     * previous call to {@code arrive} or its variants
582 >     * @return the next arrival phase number, or a negative value
583 >     * if terminated or argument is negative
584       * @throws InterruptedException if thread interrupted while waiting
585       */
586      public int awaitAdvanceInterruptibly(int phase)
# Line 579 | Line 597 | public class Phaser {
597      }
598  
599      /**
600 <     * Awaits the phase of the barrier to advance from the given value
601 <     * or the given timeout elapses, or returns immediately if
602 <     * argument is negative or this barrier is terminated.
603 <     *
604 <     * @param phase the phase on entry to this method
605 <     * @return the phase on exit from this method
600 >     * Awaits the phase of the barrier to advance from the given phase
601 >     * value or the given timeout to elapse, throwing
602 >     * {@code InterruptedException} if interrupted while waiting, or
603 >     * returning immediately if the current phase of the barrier is not
604 >     * equal to the given phase value or this barrier is terminated.
605 >     *
606 >     * @param phase an arrival phase number, or negative value if
607 >     * terminated; this argument is normally the value returned by a
608 >     * previous call to {@code arrive} or its variants
609 >     * @param timeout how long to wait before giving up, in units of
610 >     *        {@code unit}
611 >     * @param unit a {@code TimeUnit} determining how to interpret the
612 >     *        {@code timeout} parameter
613 >     * @return the next arrival phase number, or a negative value
614 >     * if terminated or argument is negative
615       * @throws InterruptedException if thread interrupted while waiting
616       * @throws TimeoutException if timed out while waiting
617       */
# Line 647 | Line 674 | public class Phaser {
674      }
675  
676      /**
677 <     * Returns the number of parties that have arrived at the current
678 <     * phase of this barrier.
677 >     * Returns the number of registered parties that have arrived at
678 >     * the current phase of this barrier.
679       *
680       * @return the number of arrived parties
681       */
# Line 713 | Line 740 | public class Phaser {
740       * only sensible to do so in designs where all parties register
741       * before any arrive, and all {@link #awaitAdvance} at each phase.
742       * Otherwise, you cannot ensure lack of interference from other
743 <     * parties during the the invocation of this method.
743 >     * parties during the invocation of this method.
744       *
745       * @param phase the phase number on entering the barrier
746       * @param registeredParties the current number of registered parties

Diff Legend

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