util/concurrent/Phaser.java

49  * number of parties <em>registered</em> to synchronize on a phaser
65  * generation of a phaser has an associated phase number. The phase
67  * phaser, wrapping around to zero after reaching {@code
69  * control of actions upon arrival at a phaser and upon awaiting
78  *       number</em>; that is, the phase number of the phaser to which
90  *       the phaser advances to (or is already at) a different phase.
96  *       state of the phaser. If necessary, you can perform any
106  * <p><b>Termination.</b> A phaser may enter a <em>termination</em>
131  * Whenever the number of registered parties of a child phaser becomes
134  * child phaser is registered with its parent.  Whenever the number of
136  * {@link #arriveAndDeregister}, the child phaser is deregistered
140  * only by registered parties, the current state of a phaser may be
179  *   Phaser phaser = new Phaser() {
184  *   phaser.register();
186  *     phaser.register();
190  *         phaser.arriveAndAwaitAdvance();
191  *       } while (!phaser.isTerminated());
195  *   phaser.arriveAndDeregister();
202  *   phaser.register();
203  *   while (!phaser.isTerminated())
204  *     phaser.arriveAndAwaitAdvance();}</pre>
211  * void awaitPhase(Phaser phaser, int phase) {
212  *   int p = phaser.register(); // assumes caller not already registered
214  *     if (phaser.isTerminated())
217  *       p = phaser.arriveAndAwaitAdvance();
219  *   phaser.arriveAndDeregister();
272      * Except that a phaser with no registered parties is
282      * registration of a sub-phaser (i.e., one with a non-null
330      * The parent of this phaser, or null if none.
335      * The root of phaser tree. Equals this if not in a tree.
499      * Creates a new phaser with no initially registered parties, no
501      * phaser will need to first register for it.
508      * Creates a new phaser with the given number of registered
523      * @param parent the parent phaser
530      * Creates a new phaser with the given parent and number of
533      * child phaser is registered with its parent.
535      * @param parent the parent phaser
566      * Adds a new unarrived party to this phaser.  If an ongoing
568      * may await its completion before returning.  If this phaser has
569      * a parent, and this phaser previously had no registered parties,
570      * this child phaser is also registered with its parent. If
571      * this phaser is terminated, the attempt to register has
575      * applied.  If this value is negative, then this phaser has
585      * Adds the given number of new unarrived parties to this phaser.
588      * phaser has a parent, and the given number of parties is greater
589      * than zero, and this phaser previously had no registered
590      * parties, this child phaser is also registered with its parent.
591      * If this phaser is terminated, the attempt to register has no
597      * applied.  If this value is negative, then this phaser has
612      * Arrives at this phaser, without waiting for others to arrive.
617      * this phaser, if ever.
628      * Arrives at this phaser and deregisters from it without waiting
630      * parties required to advance in future phases.  If this phaser
631      * has a parent, and deregistration causes this phaser to have
632      * zero parties, this phaser is also deregistered from its parent.
637      * this phaser, if ever.
648      * Arrives at this phaser and awaits others. Equivalent in effect
658      * this phaser, if ever.
701      * Awaits the phase of this phaser to advance from the given phase
703      * to the given phase value or this phaser is terminated.
724      * Awaits the phase of this phaser to advance from the given phase
727      * not equal to the given phase value or this phaser is
755      * Awaits the phase of this phaser to advance from the given phase
759      * given phase value or this phaser is terminated.
795      * Forces this phaser to enter termination state.  Counts of
796      * registered parties are unaffected.  If this phaser is a member
798      * are terminated.  If this phaser is already terminated, this
831      * Returns the number of parties registered at this phaser.
841      * the current phase of this phaser. If this phaser has terminated,
852      * arrived at the current phase of this phaser. If this phaser has
862      * Returns the parent of this phaser, or {@code null} if none.
864      * @return the parent of this phaser, or {@code null} if none
871      * Returns the root ancestor of this phaser, which is the same as
872      * this phaser if it has no parent.
874      * @return the root ancestor of this phaser
881      * Returns {@code true} if this phaser has been terminated.
883      * @return {@code true} if this phaser has been terminated
892      * upon arrival of the party advancing this phaser (when all other
894      * true}, this phaser will be set to a final termination state
898      * attempting to advance this phaser, in which case no advance
901      * <p>The arguments to this method provide the state of the phaser
903      * arrival, registration, and waiting methods on this phaser from
907      * <p>If this phaser is a member of a tiered set of phasers, then
908      * {@code onAdvance} is invoked only for its root phaser on each
920      * Phaser phaser = new Phaser() {
925      * before this phaser is advanced
927      * @return {@code true} if this phaser should terminate
934      * Returns a string identifying this phaser, as well as its
940      * @return a string identifying this phaser, as well as its state
1017      * Call only on root phaser.
1080         final Phaser phaser;
1090         QNode(Phaser phaser, int phase, boolean interruptible,
1092             this.phaser = phaser;
1104             if (phaser.getPhase() != phase) {