# Phaser

public class **Phaser** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
A reusable synchronization barrier, similar in functionality to
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CyclicBarrier.html` and
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CountDownLatch.html`
but supporting more flexible usage.

**Registration.** Unlike the case for other barriers, the
number of parties *registered* to synchronize on a phaser
may vary over time. Tasks may be registered at any time (using
methods `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#register()`, `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#bulkRegister(int)`, or forms of
constructors establishing initial numbers of parties), and
optionally deregistered upon any arrival (using `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndDeregister()`). As is the case with most basic
synchronization constructs, registration and deregistration affect
only internal counts; they do not establish any further internal
bookkeeping, so tasks cannot query whether they are registered.
(However, you can introduce such bookkeeping by subclassing this
class.)

**Synchronization.** Like a `CyclicBarrier`, a `Phaser` may be repeatedly awaited. Method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndAwaitAdvance()` has effect analogous to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/CyclicBarrier.html#await()`. Each
generation of a phaser has an associated phase number. The phase
number starts at zero, and advances when all parties arrive at the
phaser, wrapping around to zero after reaching `Integer.MAX_VALUE`. The use of phase numbers enables independent
control of actions upon arrival at a phaser and upon awaiting
others, via two kinds of methods that may be invoked by any
registered party:

- **Arrival.** Methods `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arrive()` and `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndDeregister()` record arrival. These methods do not block, but return an associated *arrival phase
  number* ; that is, the phase number of the phaser to which the arrival applied. When the final party for a given phase arrives, an optional action is performed and the phase advances. These actions are performed by the party triggering a phase advance, and are arranged by overriding method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#onAdvance(int,%20int)`, which also controls termination. Overriding this method is similar to, but more flexible than, providing a barrier action to a `CyclicBarrier`.
- **Waiting.** Method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#awaitAdvance(int)` requires an argument indicating an arrival phase number, and returns when the phaser advances to (or is already at) a different phase. Unlike similar constructions using `CyclicBarrier`, method `awaitAdvance` continues to wait even if the waiting thread is interrupted. Interruptible and timeout versions are also available, but exceptions encountered while tasks wait interruptibly or with timeout do not change the state of the phaser. If necessary, you can perform any associated recovery within handlers of those exceptions, often after invoking `forceTermination`. Phasers may also be used by tasks executing in a `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/ForkJoinPool.html`. Progress is ensured if the pool's parallelismLevel can accommodate the maximum number of simultaneously blocked parties.

**Termination.** A phaser may enter a *termination*
state, that may be checked using method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#isTerminated()`. Upon
termination, all synchronization methods immediately return without
waiting for advance, as indicated by a negative return value.
Similarly, attempts to register upon termination have no effect.
Termination is triggered when an invocation of `onAdvance`
returns `true`. The default implementation returns `true` if a deregistration has caused the number of registered
parties to become zero. As illustrated below, when phasers control
actions with a fixed number of iterations, it is often convenient
to override this method to cause termination when the current phase
number reaches a threshold. Method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#forceTermination()` is
also available to abruptly release waiting threads and allow them
to terminate.

**Tiering.** Phasers may be *tiered* (i.e.,
constructed in tree structures) to reduce contention. Phasers with
large numbers of parties that would otherwise experience heavy
synchronization contention costs may instead be set up so that
groups of sub-phasers share a common parent. This may greatly
increase throughput even though it incurs greater per-operation
overhead.

In a tree of tiered phasers, registration and deregistration of
child phasers with their parent are managed automatically.
Whenever the number of registered parties of a child phaser becomes
non-zero (as established in the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(java.util.concurrent.Phaser,%20int)`
constructor, `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#register()`, or `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#bulkRegister(int)`), the
child phaser is registered with its parent. Whenever the number of
registered parties becomes zero as the result of an invocation of
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndDeregister()`, the child phaser is deregistered
from its parent.

**Monitoring.** While synchronization methods may be invoked
only by registered parties, the current state of a phaser may be
monitored by any caller. At any given moment there are `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getRegisteredParties()` parties in total, of which `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getArrivedParties()` have arrived at the current phase (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getPhase()`). When the remaining (`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getUnarrivedParties()`)
parties arrive, the phase advances. The values returned by these
methods may reflect transient states and so are not in general
useful for synchronization control. Method `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#toString()`
returns snapshots of these state queries in a form convenient for
informal monitoring.

**Sample usages:**

A `Phaser` may be used instead of a `CountDownLatch`
to control a one-shot action serving a variable number of parties.
The typical idiom is for the method setting this up to first
register, then start the actions, then deregister, as in:

     void runTasks(List<Runnable> tasks) {
       final Phaser phaser = new Phaser(1); // "1" to register self
       // create and start threads
       for (final Runnable task : tasks) {
         phaser.register();
         new Thread() {
           public void run() {
             phaser.arriveAndAwaitAdvance(); // await all creation
             task.run();
           }
         }.start();
       }

       // allow threads to start and deregister self
       phaser.arriveAndDeregister();
     }

One way to cause a set of threads to repeatedly perform actions
for a given number of iterations is to override `onAdvance`:

     void startTasks(List<Runnable> tasks, final int iterations) {
       final Phaser phaser = new Phaser() {
         protected boolean onAdvance(int phase, int registeredParties) {
           return phase >= iterations || registeredParties == 0;
         }
       };
       phaser.register();
       for (final Runnable task : tasks) {
         phaser.register();
         new Thread() {
           public void run() {
             do {
               task.run();
               phaser.arriveAndAwaitAdvance();
             } while (!phaser.isTerminated());
           }
         }.start();
       }
       phaser.arriveAndDeregister(); // deregister self, don't wait
     }

If the main task must later await termination, it may re-register and then execute a similar loop:

     // ...
       phaser.register();
       while (!phaser.isTerminated())
         phaser.arriveAndAwaitAdvance();

Related constructions may be used to await particular phase numbers
in contexts where you are sure that the phase will never wrap around
`Integer.MAX_VALUE`. For example:

     void awaitPhase(Phaser phaser, int phase) {
       int p = phaser.register(); // assumes caller not already registered
       while (p < phase) {
         if (phaser.isTerminated())
           // ... deal with unexpected termination
         else
           p = phaser.arriveAndAwaitAdvance();
       }
       phaser.arriveAndDeregister();
     }

To create a set of `n` tasks using a tree of phasers, you
could use code of the following form, assuming a Task class with a
constructor accepting a `Phaser` that it registers with upon
construction. After invocation of `build(new Task[n], 0, n,
new Phaser())`, these tasks could then be started, for example by
submitting to a pool:

     void build(Task[] tasks, int lo, int hi, Phaser ph) {
       if (hi - lo > TASKS_PER_PHASER) {
         for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
           int j = Math.min(i + TASKS_PER_PHASER, hi);
           build(tasks, i, j, new Phaser(ph));
         }
       } else {
         for (int i = lo; i < hi; ++i)
           tasks[i] = new Task(ph);
           // assumes new Task(ph) performs ph.register()
       }
     }

The best value of `TASKS_PER_PHASER` depends mainly on expected synchronization rates. A value as low as four may be appropriate for extremely small per-phase task bodies (thus high rates), or up to hundreds for extremely large ones.

**Implementation notes** : This implementation restricts the
maximum number of parties to 65535. Attempts to register additional
parties result in `IllegalStateException`. However, you can and
should create tiered phasers to accommodate arbitrarily large sets
of participants.

### Public Constructor Summary

|---|---|
|   | [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser())() Creates a new phaser with no initially registered parties, no parent, and initial phase number 0. |
|   | [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(int))(int parties) Creates a new phaser with the given number of registered unarrived parties, no parent, and initial phase number 0. |
|   | [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(java.util.concurrent.Phaser))([Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) parent) Equivalent to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(java.util.concurrent.Phaser,%20int)`. |
|   | [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(java.util.concurrent.Phaser,%20int))([Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) parent, int parties) Creates a new phaser with the given parent and number of registered unarrived parties. |

### Public Method Summary

|---|---|
| int | [arrive](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arrive())() Arrives at this phaser, without waiting for others to arrive. |
| int | [arriveAndAwaitAdvance](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndAwaitAdvance())() Arrives at this phaser and awaits others. |
| int | [arriveAndDeregister](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#arriveAndDeregister())() Arrives at this phaser and deregisters from it without waiting for others to arrive. |
| int | [awaitAdvance](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#awaitAdvance(int))(int phase) Awaits the phase of this phaser to advance from the given phase value, returning immediately if the current phase is not equal to the given phase value or this phaser is terminated. |
| int | [awaitAdvanceInterruptibly](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#awaitAdvanceInterruptibly(int))(int phase) Awaits the phase of this phaser to advance from the given phase value, throwing `InterruptedException` if interrupted while waiting, or returning immediately if the current phase is not equal to the given phase value or this phaser is terminated. |
| int | [awaitAdvanceInterruptibly](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#awaitAdvanceInterruptibly(int,%20long,%20java.util.concurrent.TimeUnit))(int phase, long timeout, [TimeUnit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeUnit.html) unit) Awaits the phase of this phaser to advance from the given phase value or the given timeout to elapse, throwing `InterruptedException` if interrupted while waiting, or returning immediately if the current phase is not equal to the given phase value or this phaser is terminated. |
| int | [bulkRegister](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#bulkRegister(int))(int parties) Adds the given number of new unarrived parties to this phaser. |
| void | [forceTermination](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#forceTermination())() Forces this phaser to enter termination state. |
| int | [getArrivedParties](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getArrivedParties())() Returns the number of registered parties that have arrived at the current phase of this phaser. |
| [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) | [getParent](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getParent())() Returns the parent of this phaser, or `null` if none. |
| final int | [getPhase](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getPhase())() Returns the current phase number. |
| int | [getRegisteredParties](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getRegisteredParties())() Returns the number of parties registered at this phaser. |
| [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) | [getRoot](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getRoot())() Returns the root ancestor of this phaser, which is the same as this phaser if it has no parent. |
| int | [getUnarrivedParties](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#getUnarrivedParties())() Returns the number of registered parties that have not yet arrived at the current phase of this phaser. |
| boolean | [isTerminated](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#isTerminated())() Returns `true` if this phaser has been terminated. |
| int | [register](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#register())() Adds a new unarrived party to this phaser. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#toString())() Returns a string identifying this phaser, as well as its state. |

### Protected Method Summary

|---|---|
| boolean | [onAdvance](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#onAdvance(int,%20int))(int phase, int registeredParties) Overridable method to perform an action upon impending phase advance, and to control termination. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Constructors

#### public
**Phaser**
()

Creates a new phaser with no initially registered parties, no
parent, and initial phase number 0. Any thread using this
phaser will need to first register for it.

#### public
**Phaser**
(int parties)

Creates a new phaser with the given number of registered
unarrived parties, no parent, and initial phase number 0.

##### Parameters

| parties | the number of parties required to advance to the next phase |
|---|---|

##### Throws

| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if parties less than zero or greater than the maximum number of parties supported |
|---|---|

#### public
**Phaser**
([Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) parent)

Equivalent to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#Phaser(java.util.concurrent.Phaser,%20int)`.

##### Parameters

| parent | the parent phaser |
|---|---|

#### public
**Phaser**
([Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html) parent, int parties)

Creates a new phaser with the given parent and number of
registered unarrived parties. When the given parent is non-null
and the given number of parties is greater than zero, this
child phaser is registered with its parent.

##### Parameters

| parent | the parent phaser |
| parties | the number of parties required to advance to the next phase |
|---|---|

##### Throws

| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if parties less than zero or greater than the maximum number of parties supported |
|---|---|

## Public Methods

#### public int
**arrive**
()

Arrives at this phaser, without waiting for others to arrive.

It is a usage error for an unregistered party to invoke this
method. However, this error may result in an `IllegalStateException` only upon some subsequent operation on
this phaser, if ever.

##### Returns

- the arrival phase number, or a negative value if terminated

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if not terminated and the number of unarrived parties would become negative |
|---|---|

#### public int
**arriveAndAwaitAdvance**
()

Arrives at this phaser and awaits others. Equivalent in effect
to `awaitAdvance(arrive())`. If you need to await with
interruption or timeout, you can arrange this with an analogous
construction using one of the other forms of the `awaitAdvance` method. If instead you need to deregister upon
arrival, use `awaitAdvance(arriveAndDeregister())`.

It is a usage error for an unregistered party to invoke this
method. However, this error may result in an `IllegalStateException` only upon some subsequent operation on
this phaser, if ever.

##### Returns

- the arrival phase number, or the (negative) {@linkplain #getPhase() current phase} if terminated

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if not terminated and the number of unarrived parties would become negative |
|---|---|

#### public int
**arriveAndDeregister**
()

Arrives at this phaser and deregisters from it without waiting
for others to arrive. Deregistration reduces the number of
parties required to advance in future phases. If this phaser
has a parent, and deregistration causes this phaser to have
zero parties, this phaser is also deregistered from its parent.

It is a usage error for an unregistered party to invoke this
method. However, this error may result in an `IllegalStateException` only upon some subsequent operation on
this phaser, if ever.

##### Returns

- the arrival phase number, or a negative value if terminated

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if not terminated and the number of registered or unarrived parties would become negative |
|---|---|

#### public int
**awaitAdvance**
(int phase)

Awaits the phase of this phaser to advance from the given phase
value, returning immediately if the current phase is not equal
to the given phase value or this phaser is terminated.

##### Parameters

| phase | an arrival phase number, or negative value if terminated; this argument is normally the value returned by a previous call to `arrive` or `arriveAndDeregister`. |
|---|---|

##### Returns

- the next arrival phase number, or the argument if it is negative, or the (negative) {@linkplain #getPhase() current phase} if terminated

#### public int
**awaitAdvanceInterruptibly**
(int phase)

Awaits the phase of this phaser to advance from the given phase
value, throwing `InterruptedException` if interrupted
while waiting, or returning immediately if the current phase is
not equal to the given phase value or this phaser is
terminated.

##### Parameters

| phase | an arrival phase number, or negative value if terminated; this argument is normally the value returned by a previous call to `arrive` or `arriveAndDeregister`. |
|---|---|

##### Returns

- the next arrival phase number, or the argument if it is negative, or the (negative) {@linkplain #getPhase() current phase} if terminated

##### Throws

| [InterruptedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/InterruptedException.html) | if thread interrupted while waiting |
|---|---|

#### public int
**awaitAdvanceInterruptibly**
(int phase, long timeout, [TimeUnit](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeUnit.html) unit)

Awaits the phase of this phaser to advance from the given phase
value or the given timeout to elapse, throwing `InterruptedException` if interrupted while waiting, or
returning immediately if the current phase is not equal to the
given phase value or this phaser is terminated.

##### Parameters

| phase | an arrival phase number, or negative value if terminated; this argument is normally the value returned by a previous call to `arrive` or `arriveAndDeregister`. |
| timeout | how long to wait before giving up, in units of `unit` |
| unit | a `TimeUnit` determining how to interpret the `timeout` parameter |
|---|---|

##### Returns

- the next arrival phase number, or the argument if it is negative, or the (negative) {@linkplain #getPhase() current phase} if terminated

##### Throws

| [InterruptedException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/InterruptedException.html) | if thread interrupted while waiting |
| [TimeoutException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/TimeoutException.html) | if timed out while waiting |
|---|---|

#### public int
**bulkRegister**
(int parties)

Adds the given number of new unarrived parties to this phaser.
If an ongoing invocation of `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#onAdvance(int,%20int)` is in progress,
this method may await its completion before returning. If this
phaser has a parent, and the given number of parties is greater
than zero, and this phaser previously had no registered
parties, this child phaser is also registered with its parent.
If this phaser is terminated, the attempt to register has no
effect, and a negative value is returned.

##### Parameters

| parties | the number of additional parties required to advance to the next phase |
|---|---|

##### Returns

- the arrival phase number to which this registration applied. If this value is negative, then this phaser has terminated, in which case registration has no effect.

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if attempting to register more than the maximum supported number of parties |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if `parties < 0` |
|---|---|

#### public void
**forceTermination**
()

Forces this phaser to enter termination state. Counts of
registered parties are unaffected. If this phaser is a member
of a tiered set of phasers, then all of the phasers in the set
are terminated. If this phaser is already terminated, this
method has no effect. This method may be useful for
coordinating recovery after one or more tasks encounter
unexpected exceptions.

#### public int
**getArrivedParties**
()

Returns the number of registered parties that have arrived at
the current phase of this phaser. If this phaser has terminated,
the returned value is meaningless and arbitrary.

##### Returns

- the number of arrived parties

#### public [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html)
**getParent**
()

Returns the parent of this phaser, or `null` if none.

##### Returns

- the parent of this phaser, or `null` if none

#### public final int
**getPhase**
()

Returns the current phase number. The maximum phase number is
`Integer.MAX_VALUE`, after which it restarts at
zero. Upon termination, the phase number is negative,
in which case the prevailing phase prior to termination
may be obtained via `getPhase() + Integer.MIN_VALUE`.

##### Returns

- the phase number, or a negative value if terminated

#### public int
**getRegisteredParties**
()

Returns the number of parties registered at this phaser.

##### Returns

- the number of parties

#### public [Phaser](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html)
**getRoot**
()

Returns the root ancestor of this phaser, which is the same as
this phaser if it has no parent.

##### Returns

- the root ancestor of this phaser

#### public int
**getUnarrivedParties**
()

Returns the number of registered parties that have not yet
arrived at the current phase of this phaser. If this phaser has
terminated, the returned value is meaningless and arbitrary.

##### Returns

- the number of unarrived parties

#### public boolean
**isTerminated**
()

Returns `true` if this phaser has been terminated.

##### Returns

- `true` if this phaser has been terminated

#### public int
**register**
()

Adds a new unarrived party to this phaser. If an ongoing
invocation of `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#onAdvance(int,%20int)` is in progress, this method
may await its completion before returning. If this phaser has
a parent, and this phaser previously had no registered parties,
this child phaser is also registered with its parent. If
this phaser is terminated, the attempt to register has
no effect, and a negative value is returned.

##### Returns

- the arrival phase number to which this registration applied. If this value is negative, then this phaser has terminated, in which case registration has no effect.

##### Throws

| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if attempting to register more than the maximum supported number of parties |
|---|---|

#### public [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**toString**
()

Returns a string identifying this phaser, as well as its
state. The state, in brackets, includes the String `"phase = "` followed by the phase number, `"parties = "`
followed by the number of registered parties, and `"arrived = "` followed by the number of arrived parties.

##### Returns

- a string identifying this phaser, as well as its state

## Protected Methods

#### protected boolean
**onAdvance**
(int phase, int registeredParties)

Overridable method to perform an action upon impending phase
advance, and to control termination. This method is invoked
upon arrival of the party advancing this phaser (when all other
waiting parties are dormant). If this method returns `true`, this phaser will be set to a final termination state
upon advance, and subsequent calls to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/concurrent/Phaser.html#isTerminated()`
will return true. Any (unchecked) Exception or Error thrown by
an invocation of this method is propagated to the party
attempting to advance this phaser, in which case no advance
occurs.

The arguments to this method provide the state of the phaser
prevailing for the current transition. The effects of invoking
arrival, registration, and waiting methods on this phaser from
within `onAdvance` are unspecified and should not be
relied on.

If this phaser is a member of a tiered set of phasers, then
`onAdvance` is invoked only for its root phaser on each
advance.

To support the most common use cases, the default
implementation of this method returns `true` when the
number of registered parties has become zero as the result of a
party invoking `arriveAndDeregister`. You can disable
this behavior, thus enabling continuation upon future
registrations, by overriding this method to always return
`false`:

     Phaser phaser = new Phaser() {
       protected boolean onAdvance(int phase, int parties) { return false; }
     }

<br />

##### Parameters

| phase | the current phase number on entry to this method, before this phaser is advanced |
| registeredParties | the current number of registered parties |
|---|---|

##### Returns

- `true` if this phaser should terminate