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.29 by jsr166, Wed Aug 12 04:02:45 2009 UTC vs.
Revision 1.35 by dl, Sun Aug 23 13:37:08 2009 UTC

# Line 19 | Line 19 | import java.util.concurrent.locks.LockSu
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
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
31   * registered. (However, you can introduce such bookkeeping by
32   * subclassing this class.)
33   *
34   * <li> Each generation has an associated phase value, starting at
35 < * zero, and advancing when all parties reach the barrier (wrapping
36 < * around to zero after reaching {@code Integer.MAX_VALUE}).
35 > * zero, and advancing when all parties arrive at the barrier
36 > * (wrapping around to zero after reaching {@code Integer.MAX_VALUE}).
37   *
38   * <li> Like a {@code CyclicBarrier}, a phaser may be repeatedly
39   * awaited.  Method {@link #arriveAndAwaitAdvance} has effect
# Line 42 | Line 45 | import java.util.concurrent.locks.LockSu
45   *
46   *   <li> Arriving at a barrier. Methods {@link #arrive} and
47   *       {@link #arriveAndDeregister} do not block, but return
48 < *       the phase value current upon entry to the method.
48 > *       an associated <em>arrival phase number</em>;
49 > *       that is, the phase number of the barrier to which the
50 > *       arrival applied.
51   *
52   *   <li> Awaiting others. Method {@link #awaitAdvance} requires an
53 < *       argument indicating the entry phase, and returns when the
54 < *       barrier advances to a new phase.
53 > *       argument indicating an arrival phase number, and returns
54 > *       when the barrier advances to a new phase.
55   * </ul>
56   *
57   *
# Line 95 | Line 100 | import java.util.concurrent.locks.LockSu
100   * first register, then start the actions, then deregister, as in:
101   *
102   *  <pre> {@code
103 < * void runTasks(List<Runnable> list) {
103 > * void runTasks(List<Runnable> tasks) {
104   *   final Phaser phaser = new Phaser(1); // "1" to register self
105   *   // create and start threads
106 < *   for (Runnable r : list) {
106 > *   for (Runnable task : tasks) {
107   *     phaser.register();
108   *     new Thread() {
109   *       public void run() {
110   *         phaser.arriveAndAwaitAdvance(); // await all creation
111 < *         r.run();
111 > *         task.run();
112   *       }
113   *     }.start();
114   *   }
# Line 116 | Line 121 | import java.util.concurrent.locks.LockSu
121   * for a given number of iterations is to override {@code onAdvance}:
122   *
123   *  <pre> {@code
124 < * void startTasks(List<Runnable> list, final int iterations) {
124 > * void startTasks(List<Runnable> tasks, final int iterations) {
125   *   final Phaser phaser = new Phaser() {
126   *     public boolean onAdvance(int phase, int registeredParties) {
127   *       return phase >= iterations || registeredParties == 0;
128   *     }
129   *   };
130   *   phaser.register();
131 < *   for (Runnable r : list) {
131 > *   for (Runnable task : tasks) {
132   *     phaser.register();
133   *     new Thread() {
134   *       public void run() {
135   *         do {
136 < *           r.run();
136 > *           task.run();
137   *           phaser.arriveAndAwaitAdvance();
138   *         } while(!phaser.isTerminated();
139   *       }
# Line 169 | Line 174 | import java.util.concurrent.locks.LockSu
174   *
175   * <p><b>Implementation notes</b>: This implementation restricts the
176   * maximum number of parties to 65535. Attempts to register additional
177 < * parties result in IllegalStateExceptions. However, you can and
177 > * parties result in {@code IllegalStateException}. However, you can and
178   * should create tiered phasers to accommodate arbitrarily large sets
179   * of participants.
180   *
# Line 366 | Line 371 | public class Phaser {
371      /**
372       * Adds a new unarrived party to this phaser.
373       *
374 <     * @return the current barrier phase number upon registration
374 >     * @return the arrival phase number to which this registration applied
375       * @throws IllegalStateException if attempting to register more
376       * than the maximum supported number of parties
377       */
# Line 378 | Line 383 | public class Phaser {
383       * Adds the given number of new unarrived parties to this phaser.
384       *
385       * @param parties the number of parties required to trip barrier
386 <     * @return the current barrier phase number upon registration
386 >     * @return the arrival phase number to which this registration applied
387       * @throws IllegalStateException if attempting to register more
388       * than the maximum supported number of parties
389       */
# Line 415 | Line 420 | public class Phaser {
420       * Arrives at the barrier, but does not wait for others.  (You can
421       * in turn wait for others via {@link #awaitAdvance}).
422       *
423 <     * @return the barrier phase number upon entry to this method, or a
419 <     * negative value if terminated
423 >     * @return the arrival phase number, or a negative value if terminated
424       * @throws IllegalStateException if not terminated and the number
425       * of unarrived parties would become negative
426       */
# Line 468 | Line 472 | public class Phaser {
472       * zero parties, this phaser also arrives at and is deregistered
473       * from its parent.
474       *
475 <     * @return the current barrier phase number upon entry to
472 <     * this method, or a negative value if terminated
475 >     * @return the arrival phase number, or a negative value if terminated
476       * @throws IllegalStateException if not terminated and the number
477       * of registered or unarrived parties would become negative
478       */
# Line 525 | Line 528 | public class Phaser {
528       * method.  If instead you need to deregister upon arrival use
529       * {@code arriveAndDeregister}.
530       *
531 <     * @return the phase on entry to this method
531 >     * @return the arrival phase number, or a negative number if terminated
532       * @throws IllegalStateException if not terminated and the number
533       * of unarrived parties would become negative
534       */
# Line 535 | Line 538 | public class Phaser {
538  
539      /**
540       * Awaits the phase of the barrier to advance from the given phase
541 <     * value, or returns immediately if the current phase of the barrier
542 <     * is not equal to the given phase value or this barrier is
543 <     * terminated.
544 <     *
545 <     * @param phase the phase on entry to this method
546 <     * @return the phase on exit from this method
541 >     * value, returning immediately if the current phase of the
542 >     * barrier is not equal to the given phase value or this barrier
543 >     * is terminated.
544 >     *
545 >     * @param phase an arrival phase number, or negative value if
546 >     * terminated; this argument is normally the value returned by a
547 >     * previous call to {@code arrive} or its variants
548 >     * @return the next arrival phase number, or a negative value
549 >     * if terminated or argument is negative
550       */
551      public int awaitAdvance(int phase) {
552          if (phase < 0)
# Line 556 | Line 562 | public class Phaser {
562      }
563  
564      /**
565 <     * Awaits the phase of the barrier to advance from the given
566 <     * value, or returns immediately if argument is negative or this
567 <     * barrier is terminated, or throws InterruptedException if
568 <     * interrupted while waiting.
569 <     *
570 <     * @param phase the phase on entry to this method
571 <     * @return the phase on exit from this method
565 >     * Awaits the phase of the barrier to advance from the given phase
566 >     * value, throwing {@code InterruptedException} if interrupted while
567 >     * waiting, or returning immediately if the current phase of the
568 >     * barrier is not equal to the given phase value or this barrier
569 >     * is terminated.
570 >     *
571 >     * @param phase an arrival phase number, or negative value if
572 >     * terminated; this argument is normally the value returned by a
573 >     * previous call to {@code arrive} or its variants
574 >     * @return the next arrival phase number, or a negative value
575 >     * if terminated or argument is negative
576       * @throws InterruptedException if thread interrupted while waiting
577       */
578      public int awaitAdvanceInterruptibly(int phase)
# Line 579 | Line 589 | public class Phaser {
589      }
590  
591      /**
592 <     * Awaits the phase of the barrier to advance from the given value
593 <     * or the given timeout elapses, or returns immediately if
594 <     * argument is negative or this barrier is terminated.
595 <     *
596 <     * @param phase the phase on entry to this method
597 <     * @return the phase on exit from this method
592 >     * Awaits the phase of the barrier to advance from the given phase
593 >     * value or the given timeout to elapse, throwing
594 >     * {@code InterruptedException} if interrupted while waiting, or
595 >     * returning immediately if the current phase of the barrier is not
596 >     * equal to the given phase value or this barrier is terminated.
597 >     *
598 >     * @param phase an arrival phase number, or negative value if
599 >     * terminated; this argument is normally the value returned by a
600 >     * previous call to {@code arrive} or its variants
601 >     * @param timeout how long to wait before giving up, in units of
602 >     *        {@code unit}
603 >     * @param unit a {@code TimeUnit} determining how to interpret the
604 >     *        {@code timeout} parameter
605 >     * @return the next arrival phase number, or a negative value
606 >     * if terminated or argument is negative
607       * @throws InterruptedException if thread interrupted while waiting
608       * @throws TimeoutException if timed out while waiting
609       */

Diff Legend

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