--- jsr166/src/jsr166y/Phaser.java 2009/07/26 05:55:34 1.21 +++ jsr166/src/jsr166y/Phaser.java 2009/07/27 21:41:53 1.24 @@ -32,18 +32,19 @@ import java.util.concurrent.locks.LockSu * zero, and advancing when all parties reach the barrier (wrapping * around to zero after reaching {@code Integer.MAX_VALUE}). * - *
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) { @@ -139,9 +140,9 @@ import java.util.concurrent.locks.LockSu * phaser.arriveAndDeregister(); // deregister self, don't wait * }}
To create a set of tasks using a tree of Phasers, + *
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) { @@ -249,7 +250,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; @@ -300,16 +301,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 @@ -321,7 +322,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. @@ -341,7 +342,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. @@ -675,9 +676,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; @@ -706,12 +707,12 @@ 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. @@ -719,7 +720,7 @@ public class Phaser { *
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. + * before any arrive, and all {@link #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 @@ -930,16 +931,47 @@ public class Phaser { return p; } - // Unsafe mechanics for jsr166y 3rd party package. + // Unsafe mechanics + + private static final sun.misc.Unsafe UNSAFE = getUnsafe(); + private static final long stateOffset = + objectFieldOffset("state", Phaser.class); + + private final boolean casState(long cmp, long val) { + return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val); + } + + private static long objectFieldOffset(String field, Class> klazz) { + try { + return UNSAFE.objectFieldOffset(klazz.getDeclaredField(field)); + } catch (NoSuchFieldException e) { + // Convert Exception to corresponding Error + NoSuchFieldError error = new NoSuchFieldError(field); + error.initCause(e); + throw error; + } + } + + /** + * 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
() { + (new java.security + .PrivilegedExceptionAction () { public sun.misc.Unsafe run() throws Exception { - return getUnsafeByReflection(); + 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", @@ -947,31 +979,4 @@ public class Phaser { } } } - - private static sun.misc.Unsafe getUnsafeByReflection() - throws NoSuchFieldException, IllegalAccessException { - java.lang.reflect.Field f = - sun.misc.Unsafe.class.getDeclaredField("theUnsafe"); - f.setAccessible(true); - return (sun.misc.Unsafe) f.get(null); - } - - private static long fieldOffset(String fieldName, Class> klazz) { - try { - return UNSAFE.objectFieldOffset(klazz.getDeclaredField(fieldName)); - } catch (NoSuchFieldException e) { - // Convert Exception to Error - NoSuchFieldError error = new NoSuchFieldError(fieldName); - error.initCause(e); - throw error; - } - } - - private static final sun.misc.Unsafe UNSAFE = getUnsafe(); - private static final long stateOffset = - fieldOffset("state", Phaser.class); - - private final boolean casState(long cmp, long val) { - return UNSAFE.compareAndSwapLong(this, stateOffset, cmp, val); - } }