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.33 by jsr166, Wed Aug 19 18:00:55 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 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 539 | Line 550 | public class Phaser {
550       * barrier is not equal to the given phase value or this barrier
551       * is terminated.
552       *
553 <     * @param phase the phase on entry to this method
554 <     * @return the phase on exit from this method
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 562 | Line 576 | public class Phaser {
576       * barrier is not equal to the given phase value or this barrier
577       * is terminated.
578       *
579 <     * @param phase the phase on entry to this method
580 <     * @return the phase on exit from this method
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 586 | Line 603 | public class Phaser {
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 the phase on entry to this method
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 phase on exit from this method
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 654 | 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       */

Diff Legend

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