--- jsr166/src/jsr166y/Phaser.java 2009/07/21 18:11:44 1.15 +++ jsr166/src/jsr166y/Phaser.java 2009/08/24 12:49:39 1.40 @@ -7,131 +7,148 @@ package jsr166y; import java.util.concurrent.*; -import java.util.concurrent.atomic.*; + +import java.util.concurrent.atomic.AtomicReference; import java.util.concurrent.locks.LockSupport; -import sun.misc.Unsafe; -import java.lang.reflect.*; /** - * A reusable synchronization barrier, similar in functionality to a + * A reusable synchronization barrier, similar in functionality to * {@link java.util.concurrent.CyclicBarrier CyclicBarrier} and * {@link java.util.concurrent.CountDownLatch CountDownLatch} * 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 {@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: * - *
A Phaser may be used instead of a {@code 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: + *
A {@code Phaser} may be used instead of a {@code 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: * *
{@code - * void runTasks(List* *list) { + * void runTasks(List tasks) { * final Phaser phaser = new Phaser(1); // "1" to register self - * for (Runnable r : list) { + * // create and start threads + * for (Runnable task : tasks) { * phaser.register(); * new Thread() { * public void run() { * phaser.arriveAndAwaitAdvance(); // await all creation - * r.run(); - * phaser.arriveAndDeregister(); // signal completion + * task.run(); * } * }.start(); * } * - * doSomethingOnBehalfOfWorkers(); - * phaser.arrive(); // allow threads to start - * int p = phaser.arriveAndDeregister(); // deregister self ... - * p = phaser.awaitAdvance(p); // ... and await arrival - * otherActions(); // do other things while tasks execute - * phaser.awaitAdvance(p); // await final completion + * // 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 {@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(); * } @@ -140,9 +157,36 @@ import java.lang.reflect.*; * phaser.arriveAndDeregister(); // deregister self, don't wait * }}
To create a set of tasks using a tree of Phasers, + * 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 + * Task class with a constructor accepting a phaser that * it registers for upon construction: *
{@code * void build(Task[] actions, int lo, int hi, Phaser b) { @@ -172,9 +216,12 @@ import java.lang.reflect.*; * *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. + * + * @since 1.7 + * @author Doug Lea */ public class Phaser { /* @@ -208,15 +255,15 @@ public class Phaser { private static final int phaseMask = 0x7fffffff; private static int unarrivedOf(long s) { - return (int)(s & ushortMask); + return (int) (s & ushortMask); } private static int partiesOf(long s) { - return ((int)s) >>> 16; + return ((int) s) >>> 16; } private static int phaseOf(long s) { - return (int)(s >>> 32); + return (int) (s >>> 32); } private static int arrivedOf(long s) { @@ -224,13 +271,13 @@ public class Phaser { } private static long stateFor(int phase, int parties, int unarrived) { - return ((((long)phase) << 32) | (((long)parties) << 16) | - (long)unarrived); + return ((((long) phase) << 32) | (((long) parties) << 16) | + (long) unarrived); } private static long trippedStateFor(int phase, int parties) { - long lp = (long)parties; - return (((long)phase) << 32) | (lp << 16) | lp; + long lp = (long) parties; + return (((long) phase) << 32) | (lp << 16) | lp; } /** @@ -247,7 +294,7 @@ public class Phaser { private final Phaser parent; /** - * The root of Phaser tree. Equals this if not in a tree. Used to + * The root of phaser tree. Equals this if not in a tree. Used to * support faster state push-down. */ private final Phaser root; @@ -263,7 +310,7 @@ public class Phaser { private final AtomicReference
oddQ = new AtomicReference (); private AtomicReference queueFor(int phase) { - return (phase & 1) == 0? evenQ : oddQ; + return ((phase & 1) == 0) ? evenQ : oddQ; } /** @@ -271,7 +318,7 @@ public class Phaser { * root if necessary. */ private long getReconciledState() { - return parent == null? state : reconcileState(); + return (parent == null) ? state : reconcileState(); } /** @@ -298,16 +345,16 @@ public class Phaser { } /** - * Creates a new Phaser without any initially registered parties, + * Creates a new phaser without any initially registered parties, * initial phase number 0, and no parent. Any thread using this - * Phaser will need to first register for it. + * phaser will need to first register for it. */ public Phaser() { this(null); } /** - * Creates a new Phaser with the given numbers of registered + * Creates a new phaser with the given numbers of registered * unarrived parties, initial phase number 0, and no parent. * * @param parties the number of parties required to trip barrier @@ -319,7 +366,7 @@ public class Phaser { } /** - * Creates a new Phaser with the given parent, without any + * Creates a new phaser with the given parent, without any * initially registered parties. If parent is non-null this phaser * is registered with the parent and its initial phase number is * the same as that of parent phaser. @@ -339,7 +386,7 @@ public class Phaser { } /** - * Creates a new Phaser with the given parent and numbers of + * Creates a new phaser with the given parent and numbers of * registered unarrived parties. If parent is non-null, this phaser * is registered with the parent and its initial phase number is * the same as that of parent phaser. @@ -366,7 +413,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 +425,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 +460,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 */ @@ -438,7 +486,7 @@ public class Phaser { if (par == null) { // directly trip if (casState (s, - trippedStateFor(onAdvance(phase, parties)? -1 : + trippedStateFor(onAdvance(phase, parties) ? -1 : ((phase + 1) & phaseMask), parties))) { releaseWaiters(phase); break; @@ -461,14 +509,15 @@ public class Phaser { } /** - * Arrives at the barrier, and deregisters from it, without - * waiting for others. Deregistration reduces number of parties + * Arrives at the barrier and deregisters from it without waiting + * for others. Deregistration reduces the number of parties * 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 is also deregistered from its parent. + * zero parties, this phaser also arrives at and is deregistered + * 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 */ @@ -499,7 +548,7 @@ public class Phaser { if (unarrived == 0) { if (casState (s, - trippedStateFor(onAdvance(phase, parties)? -1 : + trippedStateFor(onAdvance(phase, parties) ? -1 : ((phase + 1) & phaseMask), parties))) { releaseWaiters(phase); break; @@ -518,11 +567,14 @@ public class Phaser { /** * Arrives at the barrier and awaits others. Equivalent in effect - * to {@code awaitAdvance(arrive())}. If you instead need to - * await with interruption of timeout, and/or deregister upon - * arrival, you can arrange them using analogous constructions. + * to {@code 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 + * {@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 */ @@ -531,12 +583,17 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given - * value, or returns immediately if argument is negative or this - * barrier is terminated. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * 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. 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 */ public int awaitAdvance(int phase) { if (phase < 0) @@ -552,13 +609,18 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given - * value, or returns immediately if argument is negative or this - * barrier is terminated, or throws InterruptedException if - * interrupted while waiting. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * Awaits the phase of the barrier to advance from the given phase + * 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) @@ -575,16 +637,28 @@ public class Phaser { } /** - * Awaits the phase of the barrier to advance from the given value - * or the given timeout elapses, or returns immediately if - * argument is negative or this barrier is terminated. - * - * @param phase the phase on entry to this method - * @return the phase on exit from this method + * Awaits the phase of the barrier to advance from the given phase + * 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 */ - public int awaitAdvanceInterruptibly(int phase, long timeout, TimeUnit unit) + public int awaitAdvanceInterruptibly(int phase, + long timeout, TimeUnit unit) throws InterruptedException, TimeoutException { if (phase < 0) return phase; @@ -633,16 +707,6 @@ public class Phaser { } /** - * Returns {@code true} if the current phase number equals the given phase. - * - * @param phase the phase - * @return {@code true} if the current phase number equals the given phase - */ - public final boolean hasPhase(int phase) { - return phaseOf(getReconciledState()) == phase; - } - - /** * Returns the number of parties registered at this barrier. * * @return the number of parties @@ -652,8 +716,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 */ @@ -672,9 +736,9 @@ public class Phaser { } /** - * Returns the parent of this phaser, or null if none. + * Returns the parent of this phaser, or {@code null} if none. * - * @return the parent of this phaser, or null if none + * @return the parent of this phaser, or {@code null} if none */ public Phaser getParent() { return parent; @@ -703,26 +767,22 @@ public class Phaser { * Overridable method to perform an action upon phase advance, and * to control termination. This method is invoked whenever the * barrier is tripped (and thus all other waiting parties are - * dormant). If it returns true, then, rather than advance the - * phase number, this barrier will be set to a final termination - * state, and subsequent calls to {@code isTerminated} will - * return true. + * dormant). If it returns {@code true}, then, rather than advance + * the phase number, this barrier will be set to a final + * termination state, and subsequent calls to {@link #isTerminated} + * will return true. * - * The default version returns true when the number of + *
The default version returns {@code true} when the number of * registered parties is zero. Normally, overrides that arrange * termination for other reasons should also preserve this * property. * - *
You may override this method to perform an action with side + *
You may override this method to perform an action with side * effects visible to participating tasks, but it is in general * only sensible to do so in designs where all parties register - * before any arrive, and all {@code awaitAdvance} at each phase. - * Otherwise, you cannot ensure lack of interference. In - * particular, this method may be invoked more than once per - * transition if other parties successfully register while the - * invocation of this method is in progress, thus postponing the - * transition until those parties also arrive, re-triggering this - * method. + * before any arrive, and all {@link #awaitAdvance} at each phase. + * Otherwise, you cannot ensure lack of interference from other + * parties during the invocation of this method. * * @param phase the phase number on entering the barrier * @param registeredParties the current number of registered parties @@ -927,49 +987,52 @@ public class Phaser { return p; } - // Temporary Unsafe mechanics for preliminary release - private static Unsafe getUnsafe() throws Throwable { - try { - return Unsafe.getUnsafe(); - } catch (SecurityException se) { - try { - return java.security.AccessController.doPrivileged - (new java.security.PrivilegedExceptionAction
() { - public Unsafe run() throws Exception { - return getUnsafePrivileged(); - }}); - } catch (java.security.PrivilegedActionException e) { - throw e.getCause(); - } - } - } + // Unsafe mechanics - private static Unsafe getUnsafePrivileged() - throws NoSuchFieldException, IllegalAccessException { - Field f = Unsafe.class.getDeclaredField("theUnsafe"); - f.setAccessible(true); - return (Unsafe) f.get(null); - } + private static final sun.misc.Unsafe UNSAFE = getUnsafe(); + private static final long stateOffset = + objectFieldOffset("state", Phaser.class); - private static long fieldOffset(String fieldName) - throws NoSuchFieldException { - return UNSAFE.objectFieldOffset - (Phaser.class.getDeclaredField(fieldName)); + private final boolean casState(long cmp, long val) { + return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val); } - static final Unsafe UNSAFE; - static final long stateOffset; - - static { + private static long objectFieldOffset(String field, Class> klazz) { try { - UNSAFE = getUnsafe(); - stateOffset = fieldOffset("state"); - } catch (Throwable e) { - throw new RuntimeException("Could not initialize intrinsics", e); + return UNSAFE.objectFieldOffset(klazz.getDeclaredField(field)); + } catch (NoSuchFieldException e) { + // Convert Exception to corresponding Error + NoSuchFieldError error = new NoSuchFieldError(field); + error.initCause(e); + throw error; } } - final boolean casState(long cmp, long val) { - return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val); + /** + * Returns a sun.misc.Unsafe. Suitable for use in a 3rd party package. + * Replace with a simple call to Unsafe.getUnsafe when integrating + * into a jdk. + * + * @return a sun.misc.Unsafe + */ + private static sun.misc.Unsafe getUnsafe() { + try { + return sun.misc.Unsafe.getUnsafe(); + } catch (SecurityException se) { + try { + return java.security.AccessController.doPrivileged + (new java.security + .PrivilegedExceptionAction () { + public sun.misc.Unsafe run() throws Exception { + java.lang.reflect.Field f = sun.misc + .Unsafe.class.getDeclaredField("theUnsafe"); + f.setAccessible(true); + return (sun.misc.Unsafe) f.get(null); + }}); + } catch (java.security.PrivilegedActionException e) { + throw new RuntimeException("Could not initialize intrinsics", + e.getCause()); + } + } } }