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 {@link #register}, {@link #bulkRegister}, or forms of + * constructors establishing initial numbers of parties), and + * optionally deregistered upon any arrival (using {@link + * #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 {@code CyclicBarrier}, a {@code + * Phaser} may be repeatedly awaited. Method {@link + * #arriveAndAwaitAdvance} has effect analogous to {@link + * java.util.concurrent.CyclicBarrier#await CyclicBarrier.await}. Each + * generation of a {@code Phaser} has an associated phase number. The + * phase number starts at zero, and advances when all parties arrive + * at the barrier, wrapping around to zero after reaching {@code + * Integer.MAX_VALUE}. The use of phase numbers enables independent + * control of actions upon arrival at a barrier and upon awaiting + * others, via two kinds of methods that may be invoked by any + * registered party: * *
Termination. A {@code Phaser} may enter a + * termination state in which all synchronization methods + * immediately return without updating phaser state or waiting for + * advance, and indicating (via a negative phase value) that execution + * is complete. Termination is triggered when an invocation of {@code + * onAdvance} returns {@code true}. 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 {@link * #forceTermination} is also available to abruptly release waiting * threads and allow them to terminate. * - *
Tiering. Phasers may be tiered (i.e., arranged + * in tree structures) to reduce contention. Phasers with large * numbers of parties that would otherwise experience heavy - * synchronization contention costs may instead be arranged in trees. - * This will typically greatly increase throughput even though it - * incurs somewhat greater per-operation overhead. - * - *
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 {@link + * #getRegisteredParties} parties in total, of which {@link + * #getArrivedParties} have arrived at the current phase ({@link + * #getPhase}). When the remaining ({@link #getUnarrivedParties}) + * parties arrive, the phase advances; thus, this value is always + * greater than zero if there are any registered parties. The values + * returned by these methods may reflect transient states and so are + * not in general useful for synchronization control. Method {@link + * #toString} returns snapshots of these state queries in a form + * convenient for informal monitoring. * *
Sample usages: * @@ -95,15 +115,15 @@ import java.util.concurrent.locks.LockSu * first register, then start the actions, then deregister, as in: * *
{@code
- * void runTasks(List list) {
+ * void runTasks(List tasks) {
* final Phaser phaser = new Phaser(1); // "1" to register self
* // create and start threads
- * for (Runnable r : list) {
+ * for (Runnable task : tasks) {
* phaser.register();
* new Thread() {
* public void run() {
* phaser.arriveAndAwaitAdvance(); // await all creation
- * r.run();
+ * task.run();
* }
* }.start();
* }
@@ -116,19 +136,19 @@ import java.util.concurrent.locks.LockSu
* for a given number of iterations is to override {@code onAdvance}:
*
* {@code
- * void startTasks(List list, final int iterations) {
+ * void startTasks(List tasks, final int iterations) {
* final Phaser phaser = new Phaser() {
- * public boolean onAdvance(int phase, int registeredParties) {
+ * protected boolean onAdvance(int phase, int registeredParties) {
* return phase >= iterations || registeredParties == 0;
* }
* };
* phaser.register();
- * for (Runnable r : list) {
+ * for (Runnable task : tasks) {
* phaser.register();
* new Thread() {
* public void run() {
* do {
- * r.run();
+ * task.run();
* phaser.arriveAndAwaitAdvance();
* } while(!phaser.isTerminated();
* }
@@ -137,6 +157,33 @@ import java.util.concurrent.locks.LockSu
* 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:
+ * {@code
+ * // ...
+ * 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
+ * {@code Integer.MAX_VALUE}. For example:
+ *
+ * {@code
+ * 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 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
@@ -169,7 +216,7 @@ import java.util.concurrent.locks.LockSu
*
*
Implementation notes: This implementation restricts the
* maximum number of parties to 65535. Attempts to register additional
- * parties result in IllegalStateExceptions. However, you can and
+ * parties result in {@code IllegalStateException}. However, you can and
* should create tiered phasers to accommodate arbitrarily large sets
* of participants.
*
@@ -203,7 +250,6 @@ public class Phaser {
*/
private volatile long state;
- private static final int ushortBits = 16;
private static final int ushortMask = 0xffff;
private static final int phaseMask = 0x7fffffff;
@@ -366,7 +412,7 @@ public class Phaser {
/**
* Adds a new unarrived party to this phaser.
*
- * @return the current barrier phase number upon registration
+ * @return the arrival phase number to which this registration applied
* @throws IllegalStateException if attempting to register more
* than the maximum supported number of parties
*/
@@ -378,7 +424,7 @@ public class Phaser {
* Adds the given number of new unarrived parties to this phaser.
*
* @param parties the number of parties required to trip barrier
- * @return the current barrier phase number upon registration
+ * @return the arrival phase number to which this registration applied
* @throws IllegalStateException if attempting to register more
* than the maximum supported number of parties
*/
@@ -413,10 +459,11 @@ public class Phaser {
/**
* Arrives at the barrier, but does not wait for others. (You can
- * in turn wait for others via {@link #awaitAdvance}).
+ * in turn wait for others via {@link #awaitAdvance}). It is an
+ * unenforced usage error for an unregistered party to invoke this
+ * method.
*
- * @return the barrier phase number upon entry to this method, or a
- * negative value if terminated
+ * @return the arrival phase number, or a negative value if terminated
* @throws IllegalStateException if not terminated and the number
* of unarrived parties would become negative
*/
@@ -466,10 +513,10 @@ public class Phaser {
* required to trip the barrier in future phases. If this phaser
* has a parent, and deregistration causes this phaser to have
* zero parties, this phaser also arrives at and is deregistered
- * from its parent.
+ * from its parent. It is an unenforced usage error for an
+ * unregistered party to invoke this method.
*
- * @return the current barrier phase number upon entry to
- * this method, or a negative value if terminated
+ * @return the arrival phase number, or a negative value if terminated
* @throws IllegalStateException if not terminated and the number
* of registered or unarrived parties would become negative
*/
@@ -523,9 +570,10 @@ public class Phaser {
* 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
- * {@code arriveAndDeregister}.
+ * {@code arriveAndDeregister}. It is an unenforced usage error
+ * for an unregistered party to invoke this method.
*
- * @return the phase on entry to this method
+ * @return the arrival phase number, or a negative number if terminated
* @throws IllegalStateException if not terminated and the number
* of unarrived parties would become negative
*/
@@ -537,10 +585,14 @@ public class Phaser {
* Awaits the phase of the barrier to advance from the given phase
* value, returning immediately if the current phase of the
* barrier is not equal to the given phase value or this barrier
- * is terminated.
+ * is terminated. It is an unenforced usage error for an
+ * unregistered party to invoke this method.
*
- * @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * @param phase an arrival phase number, or negative value if
+ * terminated; this argument is normally the value returned by a
+ * previous call to {@code arrive} or its variants
+ * @return the next arrival phase number, or a negative value
+ * if terminated or argument is negative
*/
public int awaitAdvance(int phase) {
if (phase < 0)
@@ -557,13 +609,17 @@ public class Phaser {
/**
* Awaits the phase of the barrier to advance from the given phase
- * value, throwing InterruptedException if interrupted while
- * waiting, or returning immediately if the current phase of the
- * barrier is not equal to the given phase value or this barrier
- * is terminated
- *
- * @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * value, throwing {@code InterruptedException} if interrupted
+ * while waiting, or returning immediately if the current phase of
+ * the barrier is not equal to the given phase value or this
+ * barrier is terminated. It is an unenforced usage error for an
+ * unregistered party to invoke this method.
+ *
+ * @param phase an arrival phase number, or negative value if
+ * terminated; this argument is normally the value returned by a
+ * previous call to {@code arrive} or its variants
+ * @return the next arrival phase number, or a negative value
+ * if terminated or argument is negative
* @throws InterruptedException if thread interrupted while waiting
*/
public int awaitAdvanceInterruptibly(int phase)
@@ -581,13 +637,22 @@ public class Phaser {
/**
* Awaits the phase of the barrier to advance from the given phase
- * value or the given timeout elapses, throwing
- * InterruptedException if interrupted while waiting, or returning
- * immediately if the current phase of the barrier is not equal to
- * the given phase value or this barrier is terminated.
- *
- * @param phase the phase on entry to this method
- * @return the phase on exit from this method
+ * value or the given timeout to elapse, throwing {@code
+ * InterruptedException} if interrupted while waiting, or
+ * returning immediately if the current phase of the barrier is
+ * not equal to the given phase value or this barrier is
+ * terminated. It is an unenforced usage error for an
+ * unregistered party to invoke this method.
+ *
+ * @param phase an arrival phase number, or negative value if
+ * terminated; this argument is normally the value returned by a
+ * previous call to {@code arrive} or its variants
+ * @param timeout how long to wait before giving up, in units of
+ * {@code unit}
+ * @param unit a {@code TimeUnit} determining how to interpret the
+ * {@code timeout} parameter
+ * @return the next arrival phase number, or a negative value
+ * if terminated or argument is negative
* @throws InterruptedException if thread interrupted while waiting
* @throws TimeoutException if timed out while waiting
*/
@@ -650,8 +715,8 @@ public class Phaser {
}
/**
- * Returns the number of parties that have arrived at the current
- * phase of this barrier.
+ * Returns the number of registered parties that have arrived at
+ * the current phase of this barrier.
*
* @return the number of arrived parties
*/