From 4535f67d050656b673e4d05101a3213f5dcc97f2 Mon Sep 17 00:00:00 2001 From: Doug Lea Date: Fri, 28 Jun 2013 12:12:37 +0100 Subject: [PATCH] 8019377: Sync j.u.c locks and atomic from 166 to tl Reviewed-by: chegar --- .../util/concurrent/atomic/AtomicBoolean.java | 10 +- .../util/concurrent/atomic/AtomicInteger.java | 20 ++-- .../concurrent/atomic/AtomicIntegerArray.java | 11 ++- .../atomic/AtomicIntegerFieldUpdater.java | 27 +++--- .../util/concurrent/atomic/AtomicLong.java | 20 ++-- .../concurrent/atomic/AtomicLongArray.java | 10 +- .../atomic/AtomicLongFieldUpdater.java | 32 ++++--- .../atomic/AtomicMarkableReference.java | 12 +-- .../concurrent/atomic/AtomicReference.java | 10 +- .../atomic/AtomicReferenceArray.java | 24 +++-- .../atomic/AtomicReferenceFieldUpdater.java | 39 ++++---- .../atomic/AtomicStampedReference.java | 12 +-- .../concurrent/atomic/DoubleAccumulator.java | 6 +- .../util/concurrent/atomic/DoubleAdder.java | 2 +- .../concurrent/atomic/LongAccumulator.java | 2 + .../util/concurrent/atomic/Striped64.java | 21 ++-- .../util/concurrent/atomic/package-info.java | 32 +++---- .../locks/AbstractOwnableSynchronizer.java | 20 ++-- .../locks/AbstractQueuedLongSynchronizer.java | 57 ++++++----- .../locks/AbstractQueuedSynchronizer.java | 95 +++++++++---------- .../java/util/concurrent/locks/Condition.java | 2 +- .../java/util/concurrent/locks/Lock.java | 8 +- .../util/concurrent/locks/LockSupport.java | 8 +- .../util/concurrent/locks/ReadWriteLock.java | 12 +-- .../util/concurrent/locks/ReentrantLock.java | 24 +++-- .../util/concurrent/locks/StampedLock.java | 19 ++-- 26 files changed, 267 insertions(+), 268 deletions(-) diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicBoolean.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicBoolean.java index 04bc975f9c8..bb2dd42e730 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicBoolean.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicBoolean.java @@ -92,7 +92,7 @@ public class AtomicBoolean implements java.io.Serializable { * * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(boolean expect, boolean update) { @@ -105,13 +105,13 @@ public class AtomicBoolean implements java.io.Serializable { * Atomically sets the value to the given updated value * if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public boolean weakCompareAndSet(boolean expect, boolean update) { int e = expect ? 1 : 0; diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java index 8fed658a54c..c67e42f3bf1 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicInteger.java @@ -126,7 +126,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(int expect, int update) { @@ -137,13 +137,13 @@ public class AtomicInteger extends Number implements java.io.Serializable { * Atomically sets the value to the given updated value * if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(int expect, int update) { return unsafe.compareAndSwapInt(this, valueOffset, expect, update); @@ -155,7 +155,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * @return the previous value */ public final int getAndIncrement() { - return getAndAdd(1); + return unsafe.getAndAddInt(this, valueOffset, 1); } /** @@ -164,7 +164,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * @return the previous value */ public final int getAndDecrement() { - return getAndAdd(-1); + return unsafe.getAndAddInt(this, valueOffset, -1); } /** @@ -183,7 +183,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * @return the updated value */ public final int incrementAndGet() { - return getAndAdd(1) + 1; + return unsafe.getAndAddInt(this, valueOffset, 1) + 1; } /** @@ -192,7 +192,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * @return the updated value */ public final int decrementAndGet() { - return getAndAdd(-1) - 1; + return unsafe.getAndAddInt(this, valueOffset, -1) - 1; } /** @@ -202,7 +202,7 @@ public class AtomicInteger extends Number implements java.io.Serializable { * @return the updated value */ public final int addAndGet(int delta) { - return getAndAdd(delta) + delta; + return unsafe.getAndAddInt(this, valueOffset, delta) + delta; } /** diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java index 7c259fee06f..3cbf3f4b446 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java @@ -157,7 +157,7 @@ public class AtomicIntegerArray implements java.io.Serializable { * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(int i, int expect, int update) { @@ -172,14 +172,14 @@ public class AtomicIntegerArray implements java.io.Serializable { * Atomically sets the element at position {@code i} to the given * updated value if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(int i, int expect, int update) { return compareAndSet(i, expect, update); @@ -247,6 +247,7 @@ public class AtomicIntegerArray implements java.io.Serializable { return getAndAdd(i, delta) + delta; } + /** * Atomically updates the element at index {@code i} with the results * of applying the given function, returning the previous value. The diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java index e761b6ec73d..af72a4755d4 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java @@ -37,14 +37,13 @@ package java.util.concurrent.atomic; import java.util.function.IntUnaryOperator; import java.util.function.IntBinaryOperator; import sun.misc.Unsafe; -import sun.reflect.CallerSensitive; -import sun.reflect.Reflection; - import java.lang.reflect.Field; import java.lang.reflect.Modifier; import java.security.AccessController; import java.security.PrivilegedExceptionAction; import java.security.PrivilegedActionException; +import sun.reflect.CallerSensitive; +import sun.reflect.Reflection; /** * A reflection-based utility that enables atomic updates to @@ -81,8 +80,10 @@ public abstract class AtomicIntegerFieldUpdater { * access control */ @CallerSensitive - public static AtomicIntegerFieldUpdater newUpdater(Class tclass, String fieldName) { - return new AtomicIntegerFieldUpdaterImpl(tclass, fieldName, Reflection.getCallerClass()); + public static AtomicIntegerFieldUpdater newUpdater(Class tclass, + String fieldName) { + return new AtomicIntegerFieldUpdaterImpl + (tclass, fieldName, Reflection.getCallerClass()); } /** @@ -101,7 +102,7 @@ public abstract class AtomicIntegerFieldUpdater { * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful * @throws ClassCastException if {@code obj} is not an instance * of the class possessing the field established in the constructor */ @@ -114,14 +115,14 @@ public abstract class AtomicIntegerFieldUpdater { * other calls to {@code compareAndSet} and {@code set}, but not * necessarily with respect to other changes in the field. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful * @throws ClassCastException if {@code obj} is not an instance * of the class possessing the field established in the constructor */ @@ -363,7 +364,8 @@ public abstract class AtomicIntegerFieldUpdater { /** * Standard hotspot implementation using intrinsics */ - private static class AtomicIntegerFieldUpdaterImpl extends AtomicIntegerFieldUpdater { + private static class AtomicIntegerFieldUpdaterImpl + extends AtomicIntegerFieldUpdater { private static final Unsafe unsafe = Unsafe.getUnsafe(); private final long offset; private final Class tclass; @@ -371,8 +373,7 @@ public abstract class AtomicIntegerFieldUpdater { AtomicIntegerFieldUpdaterImpl(final Class tclass, final String fieldName, - final Class caller) - { + final Class caller) { final Field field; final int modifiers; try { diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLong.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLong.java index 35af7759ac7..85ea910a96c 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLong.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLong.java @@ -140,7 +140,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(long expect, long update) { @@ -151,13 +151,13 @@ public class AtomicLong extends Number implements java.io.Serializable { * Atomically sets the value to the given updated value * if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(long expect, long update) { return unsafe.compareAndSwapLong(this, valueOffset, expect, update); @@ -169,7 +169,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * @return the previous value */ public final long getAndIncrement() { - return getAndAdd(1); + return unsafe.getAndAddLong(this, valueOffset, 1L); } /** @@ -178,7 +178,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * @return the previous value */ public final long getAndDecrement() { - return getAndAdd(-1); + return unsafe.getAndAddLong(this, valueOffset, -1L); } /** @@ -197,7 +197,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * @return the updated value */ public final long incrementAndGet() { - return getAndAdd(1) + 1; + return unsafe.getAndAddLong(this, valueOffset, 1L) + 1L; } /** @@ -206,7 +206,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * @return the updated value */ public final long decrementAndGet() { - return getAndAdd(-1) - 1; + return unsafe.getAndAddLong(this, valueOffset, -1L) - 1L; } /** @@ -216,7 +216,7 @@ public class AtomicLong extends Number implements java.io.Serializable { * @return the updated value */ public final long addAndGet(long delta) { - return getAndAdd(delta) + delta; + return unsafe.getAndAddLong(this, valueOffset, delta) + delta; } /** diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongArray.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongArray.java index 216479abeca..bf7aa6ecca8 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongArray.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongArray.java @@ -156,7 +156,7 @@ public class AtomicLongArray implements java.io.Serializable { * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(int i, long expect, long update) { @@ -171,14 +171,14 @@ public class AtomicLongArray implements java.io.Serializable { * Atomically sets the element at position {@code i} to the given * updated value if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(int i, long expect, long update) { return compareAndSet(i, expect, update); diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java index 7ac0e73d601..9a298d64931 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java @@ -37,14 +37,13 @@ package java.util.concurrent.atomic; import java.util.function.LongUnaryOperator; import java.util.function.LongBinaryOperator; import sun.misc.Unsafe; -import sun.reflect.CallerSensitive; -import sun.reflect.Reflection; - import java.lang.reflect.Field; import java.lang.reflect.Modifier; import java.security.AccessController; import java.security.PrivilegedExceptionAction; import java.security.PrivilegedActionException; +import sun.reflect.CallerSensitive; +import sun.reflect.Reflection; /** * A reflection-based utility that enables atomic updates to @@ -71,17 +70,18 @@ public abstract class AtomicLongFieldUpdater { * generic types match. * * @param tclass the class of the objects holding the field - * @param fieldName the name of the field to be updated. + * @param fieldName the name of the field to be updated * @return the updater * @throws IllegalArgumentException if the field is not a - * volatile long type. + * volatile long type * @throws RuntimeException with a nested reflection-based * exception if the class does not hold field or is the wrong type, * or the field is inaccessible to the caller according to Java language * access control */ @CallerSensitive - public static AtomicLongFieldUpdater newUpdater(Class tclass, String fieldName) { + public static AtomicLongFieldUpdater newUpdater(Class tclass, + String fieldName) { Class caller = Reflection.getCallerClass(); if (AtomicLong.VM_SUPPORTS_LONG_CAS) return new CASUpdater(tclass, fieldName, caller); @@ -105,9 +105,9 @@ public abstract class AtomicLongFieldUpdater { * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful * @throws ClassCastException if {@code obj} is not an instance - * of the class possessing the field established in the constructor. + * of the class possessing the field established in the constructor */ public abstract boolean compareAndSet(T obj, long expect, long update); @@ -118,16 +118,16 @@ public abstract class AtomicLongFieldUpdater { * other calls to {@code compareAndSet} and {@code set}, but not * necessarily with respect to other changes in the field. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful * @throws ClassCastException if {@code obj} is not an instance - * of the class possessing the field established in the constructor. + * of the class possessing the field established in the constructor */ public abstract boolean weakCompareAndSet(T obj, long expect, long update); @@ -370,7 +370,8 @@ public abstract class AtomicLongFieldUpdater { private final Class tclass; private final Class cclass; - CASUpdater(final Class tclass, final String fieldName, final Class caller) { + CASUpdater(final Class tclass, final String fieldName, + final Class caller) { final Field field; final int modifiers; try { @@ -493,7 +494,8 @@ public abstract class AtomicLongFieldUpdater { private final Class tclass; private final Class cclass; - LockedUpdater(final Class tclass, final String fieldName, final Class caller) { + LockedUpdater(final Class tclass, final String fieldName, + final Class caller) { Field field = null; int modifiers = 0; try { diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicMarkableReference.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicMarkableReference.java index b1dc71dfdce..f7becccb13a 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicMarkableReference.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicMarkableReference.java @@ -112,15 +112,15 @@ public class AtomicMarkableReference { * current reference is {@code ==} to the expected reference * and the current mark is equal to the expected mark. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expectedReference the expected value of the reference * @param newReference the new value for the reference * @param expectedMark the expected value of the mark * @param newMark the new value for the mark - * @return true if successful + * @return {@code true} if successful */ public boolean weakCompareAndSet(V expectedReference, V newReference, @@ -140,7 +140,7 @@ public class AtomicMarkableReference { * @param newReference the new value for the reference * @param expectedMark the expected value of the mark * @param newMark the new value for the mark - * @return true if successful + * @return {@code true} if successful */ public boolean compareAndSet(V expectedReference, V newReference, @@ -178,7 +178,7 @@ public class AtomicMarkableReference { * * @param expectedReference the expected value of the reference * @param newMark the new value for the mark - * @return true if successful + * @return {@code true} if successful */ public boolean attemptMark(V expectedReference, boolean newMark) { Pair current = pair; diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReference.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReference.java index ddce0734300..04fbe52effa 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReference.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReference.java @@ -109,7 +109,7 @@ public class AtomicReference implements java.io.Serializable { * if the current value {@code ==} the expected value. * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(V expect, V update) { @@ -120,13 +120,13 @@ public class AtomicReference implements java.io.Serializable { * Atomically sets the value to the given updated value * if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(V expect, V update) { return unsafe.compareAndSwapObject(this, valueOffset, expect, update); diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java index f8787ba1d40..4500bdf2fcb 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java @@ -34,10 +34,9 @@ */ package java.util.concurrent.atomic; - -import java.util.Arrays; import java.util.function.UnaryOperator; import java.util.function.BinaryOperator; +import java.util.Arrays; import java.lang.reflect.Array; import sun.misc.Unsafe; @@ -60,19 +59,18 @@ public class AtomicReferenceArray implements java.io.Serializable { private final Object[] array; // must have exact type Object[] static { - int scale; try { unsafe = Unsafe.getUnsafe(); arrayFieldOffset = unsafe.objectFieldOffset (AtomicReferenceArray.class.getDeclaredField("array")); base = unsafe.arrayBaseOffset(Object[].class); - scale = unsafe.arrayIndexScale(Object[].class); + int scale = unsafe.arrayIndexScale(Object[].class); + if ((scale & (scale - 1)) != 0) + throw new Error("data type scale not a power of two"); + shift = 31 - Integer.numberOfLeadingZeros(scale); } catch (Exception e) { throw new Error(e); } - if ((scale & (scale - 1)) != 0) - throw new Error("data type scale not a power of two"); - shift = 31 - Integer.numberOfLeadingZeros(scale); } private long checkedByteOffset(int i) { @@ -173,7 +171,7 @@ public class AtomicReferenceArray implements java.io.Serializable { * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that + * @return {@code true} if successful. False return indicates that * the actual value was not equal to the expected value. */ public final boolean compareAndSet(int i, E expect, E update) { @@ -188,20 +186,20 @@ public class AtomicReferenceArray implements java.io.Serializable { * Atomically sets the element at position {@code i} to the given * updated value if the current value {@code ==} the expected value. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param i the index * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public final boolean weakCompareAndSet(int i, E expect, E update) { return compareAndSet(i, expect, update); } - /** + /** * Atomically updates the element at index {@code i} with the results * of applying the given function, returning the previous value. The * function should be side-effect-free, since it may be re-applied diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java index 2cd0e1df369..901b71c9d2b 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java @@ -37,14 +37,13 @@ package java.util.concurrent.atomic; import java.util.function.UnaryOperator; import java.util.function.BinaryOperator; import sun.misc.Unsafe; -import sun.reflect.CallerSensitive; -import sun.reflect.Reflection; - import java.lang.reflect.Field; import java.lang.reflect.Modifier; import java.security.AccessController; import java.security.PrivilegedExceptionAction; import java.security.PrivilegedActionException; +import sun.reflect.CallerSensitive; +import sun.reflect.Reflection; /** * A reflection-based utility that enables atomic updates to @@ -82,29 +81,30 @@ import java.security.PrivilegedActionException; * @param The type of the object holding the updatable field * @param The type of the field */ -public abstract class AtomicReferenceFieldUpdater { +public abstract class AtomicReferenceFieldUpdater { /** * Creates and returns an updater for objects with the given field. * The Class arguments are needed to check that reflective types and * generic types match. * - * @param tclass the class of the objects holding the field. + * @param tclass the class of the objects holding the field * @param vclass the class of the field - * @param fieldName the name of the field to be updated. + * @param fieldName the name of the field to be updated * @return the updater - * @throws IllegalArgumentException if the field is not a volatile reference type. + * @throws ClassCastException if the field is of the wrong type + * @throws IllegalArgumentException if the field is not volatile * @throws RuntimeException with a nested reflection-based * exception if the class does not hold field or is the wrong type, * or the field is inaccessible to the caller according to Java language * access control */ @CallerSensitive - public static AtomicReferenceFieldUpdater newUpdater(Class tclass, Class vclass, String fieldName) { - return new AtomicReferenceFieldUpdaterImpl(tclass, - vclass, - fieldName, - Reflection.getCallerClass()); + public static AtomicReferenceFieldUpdater newUpdater(Class tclass, + Class vclass, + String fieldName) { + return new AtomicReferenceFieldUpdaterImpl + (tclass, vclass, fieldName, Reflection.getCallerClass()); } /** @@ -123,7 +123,7 @@ public abstract class AtomicReferenceFieldUpdater { * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public abstract boolean compareAndSet(T obj, V expect, V update); @@ -134,14 +134,14 @@ public abstract class AtomicReferenceFieldUpdater { * other calls to {@code compareAndSet} and {@code set}, but not * necessarily with respect to other changes in the field. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param obj An object whose field to conditionally set * @param expect the expected value * @param update the new value - * @return true if successful + * @return {@code true} if successful */ public abstract boolean weakCompareAndSet(T obj, V expect, V update); @@ -301,10 +301,9 @@ public abstract class AtomicReferenceFieldUpdater { */ AtomicReferenceFieldUpdaterImpl(final Class tclass, - Class vclass, + final Class vclass, final String fieldName, - final Class caller) - { + final Class caller) { final Field field; final Class fieldClass; final int modifiers; diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicStampedReference.java b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicStampedReference.java index 5f8f1a03db9..56feb2febe7 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/AtomicStampedReference.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/AtomicStampedReference.java @@ -112,15 +112,15 @@ public class AtomicStampedReference { * current reference is {@code ==} to the expected reference * and the current stamp is equal to the expected stamp. * - *

May fail spuriously - * and does not provide ordering guarantees, so is only rarely an - * appropriate alternative to {@code compareAndSet}. + *

May fail + * spuriously and does not provide ordering guarantees, so is + * only rarely an appropriate alternative to {@code compareAndSet}. * * @param expectedReference the expected value of the reference * @param newReference the new value for the reference * @param expectedStamp the expected value of the stamp * @param newStamp the new value for the stamp - * @return true if successful + * @return {@code true} if successful */ public boolean weakCompareAndSet(V expectedReference, V newReference, @@ -140,7 +140,7 @@ public class AtomicStampedReference { * @param newReference the new value for the reference * @param expectedStamp the expected value of the stamp * @param newStamp the new value for the stamp - * @return true if successful + * @return {@code true} if successful */ public boolean compareAndSet(V expectedReference, V newReference, @@ -178,7 +178,7 @@ public class AtomicStampedReference { * * @param expectedReference the expected value of the reference * @param newStamp the new value for the stamp - * @return true if successful + * @return {@code true} if successful */ public boolean attemptStamp(V expectedReference, int newStamp) { Pair current = pair; diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java b/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java index 277f185f869..841f6477d46 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAccumulator.java @@ -65,7 +65,7 @@ import java.util.function.DoubleBinaryOperator; *

Class {@link DoubleAdder} provides analogs of the functionality * of this class for the common special case of maintaining sums. The * call {@code new DoubleAdder()} is equivalent to {@code new - * DoubleAccumulator((x, y) -> x + y, 0.0}. + * DoubleAccumulator((x, y) -> x + y, 0.0)}. * *

This class extends {@link Number}, but does not define * methods such as {@code equals}, {@code hashCode} and {@code @@ -84,11 +84,13 @@ public class DoubleAccumulator extends Striped64 implements Serializable { /** * Creates a new instance using the given accumulator function * and identity element. + * @param accumulatorFunction a side-effect-free function of two arguments + * @param identity identity (initial value) for the accumulator function */ public DoubleAccumulator(DoubleBinaryOperator accumulatorFunction, double identity) { this.function = accumulatorFunction; - base = this.identity = Double.doubleToRawLongBits(identity); + base = this.identity = Double.doubleToRawLongBits(identity); } /** diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAdder.java b/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAdder.java index 30ff552747d..2db7ca89c59 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAdder.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/DoubleAdder.java @@ -63,7 +63,7 @@ import java.io.Serializable; public class DoubleAdder extends Striped64 implements Serializable { private static final long serialVersionUID = 7249069246863182397L; - /** + /* * Note that we must use "long" for underlying representations, * because there is no compareAndSet for double, due to the fact * that the bitwise equals used in any CAS implementation is not diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/LongAccumulator.java b/jdk/src/share/classes/java/util/concurrent/atomic/LongAccumulator.java index bfddcd3dcbd..1289e6b52cf 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/LongAccumulator.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/LongAccumulator.java @@ -86,6 +86,8 @@ public class LongAccumulator extends Striped64 implements Serializable { /** * Creates a new instance using the given accumulator function * and identity element. + * @param accumulatorFunction a side-effect-free function of two arguments + * @param identity identity (initial value) for the accumulator function */ public LongAccumulator(LongBinaryOperator accumulatorFunction, long identity) { diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/Striped64.java b/jdk/src/share/classes/java/util/concurrent/atomic/Striped64.java index 708b4c2574f..16dcb4da6cc 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/Striped64.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/Striped64.java @@ -52,13 +52,13 @@ abstract class Striped64 extends Number { * accessed directly by subclasses. * * Table entries are of class Cell; a variant of AtomicLong padded - * to reduce cache contention on most processors. Padding is - * overkill for most Atomics because they are usually irregularly - * scattered in memory and thus don't interfere much with each - * other. But Atomic objects residing in arrays will tend to be - * placed adjacent to each other, and so will most often share - * cache lines (with a huge negative performance impact) without - * this precaution. + * (via @sun.misc.Contended) to reduce cache contention. Padding + * is overkill for most Atomics because they are usually + * irregularly scattered in memory and thus don't interfere much + * with each other. But Atomic objects residing in arrays will + * tend to be placed adjacent to each other, and so will most + * often share cache lines (with a huge negative performance + * impact) without this precaution. * * In part because Cells are relatively large, we avoid creating * them until they are needed. When there is no contention, all @@ -112,18 +112,13 @@ abstract class Striped64 extends Number { /** * Padded variant of AtomicLong supporting only raw accesses plus CAS. - * The value field is placed between pads, hoping that the JVM doesn't - * reorder them. * * JVM intrinsics note: It would be possible to use a release-only * form of CAS here, if it were provided. */ - static final class Cell { - volatile long p0, p1, p2, p3, p4, p5, p6; + @sun.misc.Contended static final class Cell { volatile long value; - volatile long q0, q1, q2, q3, q4, q5, q6; Cell(long x) { value = x; } - final boolean cas(long cmp, long val) { return UNSAFE.compareAndSwapLong(this, valueOffset, cmp, val); } diff --git a/jdk/src/share/classes/java/util/concurrent/atomic/package-info.java b/jdk/src/share/classes/java/util/concurrent/atomic/package-info.java index 5cc25956255..ce497eb53b9 100644 --- a/jdk/src/share/classes/java/util/concurrent/atomic/package-info.java +++ b/jdk/src/share/classes/java/util/concurrent/atomic/package-info.java @@ -84,19 +84,18 @@ * write your utility method as follows: * 

 {@code
  * long getAndTransform(AtomicLong var) {
- *   while (true) {
- *     long current = var.get();
- *     long next = transform(current);
- *     if (var.compareAndSet(current, next))
- *         return current;
- *         // return next; for transformAndGet
- *   }
+ *   long prev, next;
+ *   do {
+ *     prev = var.get();
+ *     next = transform(prev);
+ *   } while (!var.compareAndSet(prev, next));
+ *   return prev; // return next; for transformAndGet
  * }}
* *

The memory effects for accesses and updates of atomics generally * follow the rules for volatiles, as stated in - * - * The Java Language Specification, Third Edition (17.4 Memory Model): + * + * The Java Language Specification (17.4 Memory Model): * *

    * @@ -152,13 +151,12 @@ * semantics for their array elements, which is not supported for * ordinary arrays. * - * - *

    The atomic classes also support method {@code weakCompareAndSet}, - * which has limited applicability. On some platforms, the weak version - * may be more efficient than {@code compareAndSet} in the normal case, - * but differs in that any given invocation of the - * {@code weakCompareAndSet} method may return {@code false} - * spuriously (that is, for no apparent reason). A + *

    The atomic classes also support method + * {@code weakCompareAndSet}, which has limited applicability. On some + * platforms, the weak version may be more efficient than {@code + * compareAndSet} in the normal case, but differs in that any given + * invocation of the {@code weakCompareAndSet} method may return {@code + * false} spuriously (that is, for no apparent reason). A * {@code false} return means only that the operation may be retried if * desired, relying on the guarantee that repeated invocation when the * variable holds {@code expectedValue} and no other thread is also @@ -194,7 +192,7 @@ * *

    Atomic classes are not general purpose replacements for * {@code java.lang.Integer} and related classes. They do not - * define methods such as {@code hashCode} and + * define methods such as {@code equals}, {@code hashCode} and * {@code compareTo}. (Because atomic variables are expected to be * mutated, they are poor choices for hash table keys.) Additionally, * classes are provided only for those types that are commonly useful in diff --git a/jdk/src/share/classes/java/util/concurrent/locks/AbstractOwnableSynchronizer.java b/jdk/src/share/classes/java/util/concurrent/locks/AbstractOwnableSynchronizer.java index 39a51e5a90c..30dec97a6e0 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/AbstractOwnableSynchronizer.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/AbstractOwnableSynchronizer.java @@ -39,7 +39,7 @@ package java.util.concurrent.locks; * A synchronizer that may be exclusively owned by a thread. This * class provides a basis for creating locks and related synchronizers * that may entail a notion of ownership. The - * AbstractOwnableSynchronizer class itself does not manage or + * {@code AbstractOwnableSynchronizer} class itself does not manage or * use this information. However, subclasses and tools may use * appropriately maintained values to help control and monitor access * and provide diagnostics. @@ -64,20 +64,20 @@ public abstract class AbstractOwnableSynchronizer private transient Thread exclusiveOwnerThread; /** - * Sets the thread that currently owns exclusive access. A - * null argument indicates that no thread owns access. + * Sets the thread that currently owns exclusive access. + * A {@code null} argument indicates that no thread owns access. * This method does not otherwise impose any synchronization or - * volatile field accesses. + * {@code volatile} field accesses. + * @param thread the owner thread */ - protected final void setExclusiveOwnerThread(Thread t) { - exclusiveOwnerThread = t; + protected final void setExclusiveOwnerThread(Thread thread) { + exclusiveOwnerThread = thread; } /** - * Returns the thread last set by - * setExclusiveOwnerThread, or null if never - * set. This method does not otherwise impose any synchronization - * or volatile field accesses. + * Returns the thread last set by {@code setExclusiveOwnerThread}, + * or {@code null} if never set. This method does not otherwise + * impose any synchronization or {@code volatile} field accesses. * @return the owner thread */ protected final Thread getExclusiveOwnerThread() { diff --git a/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedLongSynchronizer.java b/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedLongSynchronizer.java index 46ad577cf10..4d885f44376 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedLongSynchronizer.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedLongSynchronizer.java @@ -42,11 +42,11 @@ import sun.misc.Unsafe; /** * A version of {@link AbstractQueuedSynchronizer} in - * which synchronization state is maintained as a long. + * which synchronization state is maintained as a {@code long}. * This class has exactly the same structure, properties, and methods - * as AbstractQueuedSynchronizer with the exception + * as {@code AbstractQueuedSynchronizer} with the exception * that all state-related parameters and results are defined - * as long rather than int. This class + * as {@code long} rather than {@code int}. This class * may be useful when creating synchronizers such as * multilevel locks and barriers that require * 64 bits of state. @@ -71,7 +71,7 @@ public abstract class AbstractQueuedLongSynchronizer */ /** - * Creates a new AbstractQueuedLongSynchronizer instance + * Creates a new {@code AbstractQueuedLongSynchronizer} instance * with initial synchronization state of zero. */ protected AbstractQueuedLongSynchronizer() { } @@ -104,7 +104,7 @@ public abstract class AbstractQueuedLongSynchronizer * *

    Insertion into a CLH queue requires only a single atomic * operation on "tail", so there is a simple atomic point of - * demarcation from unqueued to queued. Similarly, dequeing + * demarcation from unqueued to queued. Similarly, dequeuing * involves only updating the "head". However, it takes a bit * more work for nodes to determine who their successors are, * in part to deal with possible cancellation due to timeouts @@ -211,7 +211,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Link to predecessor node that current node/thread relies on - * for checking waitStatus. Assigned during enqueing, and nulled + * for checking waitStatus. Assigned during enqueuing, and nulled * out (for sake of GC) only upon dequeuing. Also, upon * cancellation of a predecessor, we short-circuit while * finding a non-cancelled one, which will always exist @@ -256,7 +256,7 @@ public abstract class AbstractQueuedLongSynchronizer Node nextWaiter; /** - * Returns true if node is waiting in shared mode + * Returns true if node is waiting in shared mode. */ final boolean isShared() { return nextWaiter == SHARED; @@ -312,7 +312,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Returns the current value of synchronization state. - * This operation has memory semantics of a volatile read. + * This operation has memory semantics of a {@code volatile} read. * @return current state value */ protected final long getState() { @@ -321,7 +321,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Sets the value of synchronization state. - * This operation has memory semantics of a volatile write. + * This operation has memory semantics of a {@code volatile} write. * @param newState the new state value */ protected final void setState(long newState) { @@ -331,12 +331,12 @@ public abstract class AbstractQueuedLongSynchronizer /** * Atomically sets synchronization state to the given updated * value if the current state value equals the expected value. - * This operation has memory semantics of a volatile read + * This operation has memory semantics of a {@code volatile} read * and write. * * @param expect the expected value * @param update the new value - * @return true if successful. False return indicates that the actual + * @return {@code true} if successful. False return indicates that the actual * value was not equal to the expected value. */ protected final boolean compareAndSetState(long expect, long update) { @@ -441,7 +441,7 @@ public abstract class AbstractQueuedLongSynchronizer } /** - * Release action for shared mode -- signal successor and ensure + * Release action for shared mode -- signals successor and ensures * propagation. (Note: For exclusive mode, release just amounts * to calling unparkSuccessor of head if it needs signal.) */ @@ -562,7 +562,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Checks and updates status for a node that failed to acquire. * Returns true if thread should block. This is the main signal - * control in all acquire loops. Requires that pred == node.prev + * control in all acquire loops. Requires that pred == node.prev. * * @param pred node's predecessor holding status * @param node the node @@ -1066,7 +1066,7 @@ public abstract class AbstractQueuedLongSynchronizer * thread is queued, possibly repeatedly blocking and unblocking, * invoking {@link #tryAcquireShared} until success or the thread * is interrupted. - * @param arg the acquire argument + * @param arg the acquire argument. * This value is conveyed to {@link #tryAcquireShared} but is * otherwise uninterpreted and can represent anything * you like. @@ -1441,7 +1441,7 @@ public abstract class AbstractQueuedLongSynchronizer * Returns true if successful. * @param node the node * @return true if successfully transferred (else the node was - * cancelled before signal). + * cancelled before signal) */ final boolean transferForSignal(Node node) { /* @@ -1464,11 +1464,10 @@ public abstract class AbstractQueuedLongSynchronizer } /** - * Transfers node, if necessary, to sync queue after a cancelled - * wait. Returns true if thread was cancelled before being - * signalled. - * @param current the waiting thread - * @param node its node + * Transfers node, if necessary, to sync queue after a cancelled wait. + * Returns true if thread was cancelled before being signalled. + * + * @param node the node * @return true if cancelled before the node was signalled */ final boolean transferAfterCancelledWait(Node node) { @@ -1516,7 +1515,7 @@ public abstract class AbstractQueuedLongSynchronizer * uses this synchronizer as its lock. * * @param condition the condition - * @return true if owned + * @return {@code true} if owned * @throws NullPointerException if the condition is null */ public final boolean owns(ConditionObject condition) { @@ -1526,13 +1525,13 @@ public abstract class AbstractQueuedLongSynchronizer /** * Queries whether any threads are waiting on the given condition * associated with this synchronizer. Note that because timeouts - * and interrupts may occur at any time, a true return - * does not guarantee that a future signal will awaken + * and interrupts may occur at any time, a {@code true} return + * does not guarantee that a future {@code signal} will awaken * any threads. This method is designed primarily for use in * monitoring of the system state. * * @param condition the condition - * @return true if there are any waiting threads + * @return {@code true} if there are any waiting threads * @throws IllegalMonitorStateException if exclusive synchronization * is not held * @throws IllegalArgumentException if the given condition is @@ -1599,7 +1598,7 @@ public abstract class AbstractQueuedLongSynchronizer * and Condition users. Exported versions of this class will in * general need to be accompanied by documentation describing * condition semantics that rely on those of the associated - * AbstractQueuedLongSynchronizer. + * {@code AbstractQueuedLongSynchronizer}. * *

    This class is Serializable, but all fields are transient, * so deserialized conditions have no waiters. @@ -1614,7 +1613,7 @@ public abstract class AbstractQueuedLongSynchronizer private transient Node lastWaiter; /** - * Creates a new ConditionObject instance. + * Creates a new {@code ConditionObject} instance. */ public ConditionObject() { } @@ -1967,7 +1966,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Queries whether any threads are waiting on this condition. - * Implements {@link AbstractQueuedLongSynchronizer#hasWaiters}. + * Implements {@link AbstractQueuedLongSynchronizer#hasWaiters(ConditionObject)}. * * @return {@code true} if there are any waiting threads * @throws IllegalMonitorStateException if {@link #isHeldExclusively} @@ -1986,7 +1985,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Returns an estimate of the number of threads waiting on * this condition. - * Implements {@link AbstractQueuedLongSynchronizer#getWaitQueueLength}. + * Implements {@link AbstractQueuedLongSynchronizer#getWaitQueueLength(ConditionObject)}. * * @return the estimated number of waiting threads * @throws IllegalMonitorStateException if {@link #isHeldExclusively} @@ -2006,7 +2005,7 @@ public abstract class AbstractQueuedLongSynchronizer /** * Returns a collection containing those threads that may be * waiting on this Condition. - * Implements {@link AbstractQueuedLongSynchronizer#getWaitingThreads}. + * Implements {@link AbstractQueuedLongSynchronizer#getWaitingThreads(ConditionObject)}. * * @return the collection of threads * @throws IllegalMonitorStateException if {@link #isHeldExclusively} diff --git a/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedSynchronizer.java b/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedSynchronizer.java index 6f39256c0d6..f0bdeb9030e 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedSynchronizer.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/AbstractQueuedSynchronizer.java @@ -45,12 +45,12 @@ import sun.misc.Unsafe; * synchronizers (semaphores, events, etc) that rely on * first-in-first-out (FIFO) wait queues. This class is designed to * be a useful basis for most kinds of synchronizers that rely on a - * single atomic int value to represent state. Subclasses + * single atomic {@code int} value to represent state. Subclasses * must define the protected methods that change this state, and which * define what that state means in terms of this object being acquired * or released. Given these, the other methods in this class carry * out all queuing and blocking mechanics. Subclasses can maintain - * other state fields, but only the atomically updated int + * other state fields, but only the atomically updated {@code int} * value manipulated using methods {@link #getState}, {@link * #setState} and {@link #compareAndSetState} is tracked with respect * to synchronization. @@ -58,7 +58,7 @@ import sun.misc.Unsafe; *

    Subclasses should be defined as non-public internal helper * classes that are used to implement the synchronization properties * of their enclosing class. Class - * AbstractQueuedSynchronizer does not implement any + * {@code AbstractQueuedSynchronizer} does not implement any * synchronization interface. Instead it defines methods such as * {@link #acquireInterruptibly} that can be invoked as * appropriate by concrete locks and related synchronizers to @@ -85,7 +85,7 @@ import sun.misc.Unsafe; * invoked with the current {@link #getState} value fully releases * this object, and {@link #acquire}, given this saved state value, * eventually restores this object to its previous acquired state. No - * AbstractQueuedSynchronizer method otherwise creates such a + * {@code AbstractQueuedSynchronizer} method otherwise creates such a * condition, so if this constraint cannot be met, do not use it. The * behavior of {@link ConditionObject} depends of course on the * semantics of its synchronizer implementation. @@ -93,13 +93,13 @@ import sun.misc.Unsafe; *

    This class provides inspection, instrumentation, and monitoring * methods for the internal queue, as well as similar methods for * condition objects. These can be exported as desired into classes - * using an AbstractQueuedSynchronizer for their + * using an {@code AbstractQueuedSynchronizer} for their * synchronization mechanics. * *

    Serialization of this class stores only the underlying atomic * integer maintaining state, so deserialized objects have empty * thread queues. Typical subclasses requiring serializability will - * define a readObject method that restores this to a known + * define a {@code readObject} method that restores this to a known * initial state upon deserialization. * *

    Usage

    @@ -115,14 +115,14 @@ import sun.misc.Unsafe; *
  • {@link #tryAcquireShared} *
  • {@link #tryReleaseShared} *
  • {@link #isHeldExclusively} - *
+ * * * Each of these methods by default throws {@link * UnsupportedOperationException}. Implementations of these methods * must be internally thread-safe, and should in general be short and * not block. Defining these methods is the only supported * means of using this class. All other methods are declared - * final because they cannot be independently varied. + * {@code final} because they cannot be independently varied. * *

You may also find the inherited methods from {@link * AbstractOwnableSynchronizer} useful to keep track of the thread @@ -148,16 +148,16 @@ import sun.misc.Unsafe; * * (Shared mode is similar but may involve cascading signals.) * - *

Because checks in acquire are invoked before + *

Because checks in acquire are invoked before * enqueuing, a newly acquiring thread may barge ahead of * others that are blocked and queued. However, you can, if desired, - * define tryAcquire and/or tryAcquireShared to + * define {@code tryAcquire} and/or {@code tryAcquireShared} to * disable barging by internally invoking one or more of the inspection * methods, thereby providing a fair FIFO acquisition order. - * In particular, most fair synchronizers can define tryAcquire - * to return false if {@link #hasQueuedPredecessors} (a method + * In particular, most fair synchronizers can define {@code tryAcquire} + * to return {@code false} if {@link #hasQueuedPredecessors} (a method * specifically designed to be used by fair synchronizers) returns - * true. Other variations are possible. + * {@code true}. Other variations are possible. * *

Throughput and scalability are generally highest for the * default barging (also known as greedy, @@ -167,7 +167,7 @@ import sun.misc.Unsafe; * threads, and each recontention has an unbiased chance to succeed * against incoming threads. Also, while acquires do not * "spin" in the usual sense, they may perform multiple - * invocations of tryAcquire interspersed with other + * invocations of {@code tryAcquire} interspersed with other * computations before blocking. This gives most of the benefits of * spins when exclusive synchronization is only briefly held, without * most of the liabilities when it isn't. If so desired, you can @@ -178,7 +178,7 @@ import sun.misc.Unsafe; * *

This class provides an efficient and scalable basis for * synchronization in part by specializing its range of use to - * synchronizers that can rely on int state, acquire, and + * synchronizers that can rely on {@code int} state, acquire, and * release parameters, and an internal FIFO wait queue. When this does * not suffice, you can build synchronizers from a lower level using * {@link java.util.concurrent.atomic atomic} classes, your own custom @@ -200,12 +200,12 @@ import sun.misc.Unsafe; * * // Our internal helper class * private static class Sync extends AbstractQueuedSynchronizer { - * // Report whether in locked state + * // Reports whether in locked state * protected boolean isHeldExclusively() { * return getState() == 1; * } * - * // Acquire the lock if state is zero + * // Acquires the lock if state is zero * public boolean tryAcquire(int acquires) { * assert acquires == 1; // Otherwise unused * if (compareAndSetState(0, 1)) { @@ -215,7 +215,7 @@ import sun.misc.Unsafe; * return false; * } * - * // Release the lock by setting state to zero + * // Releases the lock by setting state to zero * protected boolean tryRelease(int releases) { * assert releases == 1; // Otherwise unused * if (getState() == 0) throw new IllegalMonitorStateException(); @@ -224,10 +224,10 @@ import sun.misc.Unsafe; * return true; * } * - * // Provide a Condition + * // Provides a Condition * Condition newCondition() { return new ConditionObject(); } * - * // Deserialize properly + * // Deserializes properly * private void readObject(ObjectInputStream s) * throws IOException, ClassNotFoundException { * s.defaultReadObject(); @@ -255,8 +255,8 @@ import sun.misc.Unsafe; * *

Here is a latch class that is like a * {@link java.util.concurrent.CountDownLatch CountDownLatch} - * except that it only requires a single signal to - * fire. Because a latch is non-exclusive, it uses the shared + * except that it only requires a single {@code signal} to + * fire. Because a latch is non-exclusive, it uses the {@code shared} * acquire and release methods. * * 

 {@code
@@ -293,7 +293,7 @@ public abstract class AbstractQueuedSynchronizer
     private static final long serialVersionUID = 7373984972572414691L;
 
     /**
-     * Creates a new AbstractQueuedSynchronizer instance
+     * Creates a new {@code AbstractQueuedSynchronizer} instance
      * with initial synchronization state of zero.
      */
     protected AbstractQueuedSynchronizer() { }
@@ -326,7 +326,7 @@ public abstract class AbstractQueuedSynchronizer
      *
      * 
Insertion into a CLH queue requires only a single atomic
      * operation on "tail", so there is a simple atomic point of
-     * demarcation from unqueued to queued. Similarly, dequeing
+     * demarcation from unqueued to queued. Similarly, dequeuing
      * involves only updating the "head". However, it takes a bit
      * more work for nodes to determine who their successors are,
      * in part to deal with possible cancellation due to timeouts
@@ -433,7 +433,7 @@ public abstract class AbstractQueuedSynchronizer
 
         /**
          * Link to predecessor node that current node/thread relies on
-         * for checking waitStatus. Assigned during enqueing, and nulled
+         * for checking waitStatus. Assigned during enqueuing, and nulled
          * out (for sake of GC) only upon dequeuing.  Also, upon
          * cancellation of a predecessor, we short-circuit while
          * finding a non-cancelled one, which will always exist
@@ -478,7 +478,7 @@ public abstract class AbstractQueuedSynchronizer
         Node nextWaiter;
 
         /**
-         * Returns true if node is waiting in shared mode
+         * Returns true if node is waiting in shared mode.
          */
         final boolean isShared() {
             return nextWaiter == SHARED;
@@ -534,7 +534,7 @@ public abstract class AbstractQueuedSynchronizer
 
     /**
      * Returns the current value of synchronization state.
-     * This operation has memory semantics of a volatile read.
+     * This operation has memory semantics of a {@code volatile} read.
      * @return current state value
      */
     protected final int getState() {
@@ -543,7 +543,7 @@ public abstract class AbstractQueuedSynchronizer
 
     /**
      * Sets the value of synchronization state.
-     * This operation has memory semantics of a volatile write.
+     * This operation has memory semantics of a {@code volatile} write.
      * @param newState the new state value
      */
     protected final void setState(int newState) {
@@ -553,12 +553,12 @@ public abstract class AbstractQueuedSynchronizer
     /**
      * Atomically sets synchronization state to the given updated
      * value if the current state value equals the expected value.
-     * This operation has memory semantics of a volatile read
+     * This operation has memory semantics of a {@code volatile} read
      * and write.
      *
      * @param expect the expected value
      * @param update the new value
-     * @return true if successful. False return indicates that the actual
+     * @return {@code true} if successful. False return indicates that the actual
      *         value was not equal to the expected value.
      */
     protected final boolean compareAndSetState(int expect, int update) {
@@ -663,7 +663,7 @@ public abstract class AbstractQueuedSynchronizer
     }
 
     /**
-     * Release action for shared mode -- signal successor and ensure
+     * Release action for shared mode -- signals successor and ensures
      * propagation. (Note: For exclusive mode, release just amounts
      * to calling unparkSuccessor of head if it needs signal.)
      */
@@ -784,7 +784,7 @@ public abstract class AbstractQueuedSynchronizer
     /**
      * Checks and updates status for a node that failed to acquire.
      * Returns true if thread should block. This is the main signal
-     * control in all acquire loops.  Requires that pred == node.prev
+     * control in all acquire loops.  Requires that pred == node.prev.
      *
      * @param pred node's predecessor holding status
      * @param node the node
@@ -1288,7 +1288,7 @@ public abstract class AbstractQueuedSynchronizer
      * thread is queued, possibly repeatedly blocking and unblocking,
      * invoking {@link #tryAcquireShared} until success or the thread
      * is interrupted.
-     * @param arg the acquire argument
+     * @param arg the acquire argument.
      * This value is conveyed to {@link #tryAcquireShared} but is
      * otherwise uninterpreted and can represent anything
      * you like.
@@ -1663,7 +1663,7 @@ public abstract class AbstractQueuedSynchronizer
      * Returns true if successful.
      * @param node the node
      * @return true if successfully transferred (else the node was
-     * cancelled before signal).
+     * cancelled before signal)
      */
     final boolean transferForSignal(Node node) {
         /*
@@ -1686,11 +1686,10 @@ public abstract class AbstractQueuedSynchronizer
     }
 
     /**
-     * Transfers node, if necessary, to sync queue after a cancelled
-     * wait. Returns true if thread was cancelled before being
-     * signalled.
-     * @param current the waiting thread
-     * @param node its node
+     * Transfers node, if necessary, to sync queue after a cancelled wait.
+     * Returns true if thread was cancelled before being signalled.
+     *
+     * @param node the node
      * @return true if cancelled before the node was signalled
      */
     final boolean transferAfterCancelledWait(Node node) {
@@ -1738,7 +1737,7 @@ public abstract class AbstractQueuedSynchronizer
      * uses this synchronizer as its lock.
      *
      * @param condition the condition
-     * @return true if owned
+     * @return {@code true} if owned
      * @throws NullPointerException if the condition is null
      */
     public final boolean owns(ConditionObject condition) {
@@ -1748,13 +1747,13 @@ public abstract class AbstractQueuedSynchronizer
     /**
      * Queries whether any threads are waiting on the given condition
      * associated with this synchronizer. Note that because timeouts
-     * and interrupts may occur at any time, a true return
-     * does not guarantee that a future signal will awaken
+     * and interrupts may occur at any time, a {@code true} return
+     * does not guarantee that a future {@code signal} will awaken
      * any threads.  This method is designed primarily for use in
      * monitoring of the system state.
      *
      * @param condition the condition
-     * @return true if there are any waiting threads
+     * @return {@code true} if there are any waiting threads
      * @throws IllegalMonitorStateException if exclusive synchronization
      *         is not held
      * @throws IllegalArgumentException if the given condition is
@@ -1821,7 +1820,7 @@ public abstract class AbstractQueuedSynchronizer
      * and Condition users. Exported versions of this class will in
      * general need to be accompanied by documentation describing
      * condition semantics that rely on those of the associated
-     * AbstractQueuedSynchronizer.
+     * {@code AbstractQueuedSynchronizer}.
      *
      * 
This class is Serializable, but all fields are transient,
      * so deserialized conditions have no waiters.
@@ -1834,7 +1833,7 @@ public abstract class AbstractQueuedSynchronizer
         private transient Node lastWaiter;
 
         /**
-         * Creates a new ConditionObject instance.
+         * Creates a new {@code ConditionObject} instance.
          */
         public ConditionObject() { }
 
@@ -2187,7 +2186,7 @@ public abstract class AbstractQueuedSynchronizer
 
         /**
          * Queries whether any threads are waiting on this condition.
-         * Implements {@link AbstractQueuedSynchronizer#hasWaiters}.
+         * Implements {@link AbstractQueuedSynchronizer#hasWaiters(ConditionObject)}.
          *
          * @return {@code true} if there are any waiting threads
          * @throws IllegalMonitorStateException if {@link #isHeldExclusively}
@@ -2206,7 +2205,7 @@ public abstract class AbstractQueuedSynchronizer
         /**
          * Returns an estimate of the number of threads waiting on
          * this condition.
-         * Implements {@link AbstractQueuedSynchronizer#getWaitQueueLength}.
+         * Implements {@link AbstractQueuedSynchronizer#getWaitQueueLength(ConditionObject)}.
          *
          * @return the estimated number of waiting threads
          * @throws IllegalMonitorStateException if {@link #isHeldExclusively}
@@ -2226,7 +2225,7 @@ public abstract class AbstractQueuedSynchronizer
         /**
          * Returns a collection containing those threads that may be
          * waiting on this Condition.
-         * Implements {@link AbstractQueuedSynchronizer#getWaitingThreads}.
+         * Implements {@link AbstractQueuedSynchronizer#getWaitingThreads(ConditionObject)}.
          *
          * @return the collection of threads
          * @throws IllegalMonitorStateException if {@link #isHeldExclusively}
diff --git a/jdk/src/share/classes/java/util/concurrent/locks/Condition.java b/jdk/src/share/classes/java/util/concurrent/locks/Condition.java
index 02cbee904bc..06fb8f1cf02 100644
--- a/jdk/src/share/classes/java/util/concurrent/locks/Condition.java
+++ b/jdk/src/share/classes/java/util/concurrent/locks/Condition.java
@@ -324,7 +324,7 @@ public interface Condition {
      *   }
      * }}
* - *

Design note: This method requires a nanosecond argument so + *

Design note: This method requires a nanosecond argument so * as to avoid truncation errors in reporting remaining times. * Such precision loss would make it difficult for programmers to * ensure that total waiting times are not systematically shorter diff --git a/jdk/src/share/classes/java/util/concurrent/locks/Lock.java b/jdk/src/share/classes/java/util/concurrent/locks/Lock.java index d9ae1bcc4ed..371a6c7c13a 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/Lock.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/Lock.java @@ -121,8 +121,8 @@ import java.util.concurrent.TimeUnit; *

All {@code Lock} implementations must enforce the same * memory synchronization semantics as provided by the built-in monitor * lock, as described in - * - * The Java Language Specification, Third Edition (17.4 Memory Model): + * + * The Java Language Specification (17.4 Memory Model): *

    *
  • A successful {@code lock} operation has the same memory * synchronization effects as a successful Lock action. @@ -136,7 +136,7 @@ import java.util.concurrent.TimeUnit; * *

    Implementation Considerations

    * - *

    The three forms of lock acquisition (interruptible, + *

    The three forms of lock acquisition (interruptible, * non-interruptible, and timed) may differ in their performance * characteristics, ordering guarantees, or other implementation * qualities. Further, the ability to interrupt the ongoing @@ -227,7 +227,7 @@ public interface Lock { * * @throws InterruptedException if the current thread is * interrupted while acquiring the lock (and interruption - * of lock acquisition is supported). + * of lock acquisition is supported) */ void lockInterruptibly() throws InterruptedException; diff --git a/jdk/src/share/classes/java/util/concurrent/locks/LockSupport.java b/jdk/src/share/classes/java/util/concurrent/locks/LockSupport.java index 20abfacc3c8..46a0ab597c8 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/LockSupport.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/LockSupport.java @@ -67,10 +67,10 @@ import sun.misc.Unsafe; * {@code blocker} object parameter. This object is recorded while * the thread is blocked to permit monitoring and diagnostic tools to * identify the reasons that threads are blocked. (Such tools may - * access blockers using method {@link #getBlocker}.) The use of these - * forms rather than the original forms without this parameter is - * strongly encouraged. The normal argument to supply as a - * {@code blocker} within a lock implementation is {@code this}. + * access blockers using method {@link #getBlocker(Thread)}.) + * The use of these forms rather than the original forms without this + * parameter is strongly encouraged. The normal argument to supply as + * a {@code blocker} within a lock implementation is {@code this}. * *

    These methods are designed to be used as tools for creating * higher-level synchronization utilities, and are not in themselves diff --git a/jdk/src/share/classes/java/util/concurrent/locks/ReadWriteLock.java b/jdk/src/share/classes/java/util/concurrent/locks/ReadWriteLock.java index fd6632b0b57..40b0f344238 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/ReadWriteLock.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/ReadWriteLock.java @@ -36,16 +36,16 @@ package java.util.concurrent.locks; /** - * A ReadWriteLock maintains a pair of associated {@link + * A {@code ReadWriteLock} maintains a pair of associated {@link * Lock locks}, one for read-only operations and one for writing. * The {@link #readLock read lock} may be held simultaneously by * multiple reader threads, so long as there are no writers. The * {@link #writeLock write lock} is exclusive. * - *

    All ReadWriteLock implementations must guarantee that - * the memory synchronization effects of writeLock operations + *

    All {@code ReadWriteLock} implementations must guarantee that + * the memory synchronization effects of {@code writeLock} operations * (as specified in the {@link Lock} interface) also hold with respect - * to the associated readLock. That is, a thread successfully + * to the associated {@code readLock}. That is, a thread successfully * acquiring the read lock will see all updates made upon previous * release of the write lock. * @@ -120,14 +120,14 @@ public interface ReadWriteLock { /** * Returns the lock used for reading. * - * @return the lock used for reading. + * @return the lock used for reading */ Lock readLock(); /** * Returns the lock used for writing. * - * @return the lock used for writing. + * @return the lock used for writing */ Lock writeLock(); } diff --git a/jdk/src/share/classes/java/util/concurrent/locks/ReentrantLock.java b/jdk/src/share/classes/java/util/concurrent/locks/ReentrantLock.java index 5ca1335aaf6..06c7e61ab65 100644 --- a/jdk/src/share/classes/java/util/concurrent/locks/ReentrantLock.java +++ b/jdk/src/share/classes/java/util/concurrent/locks/ReentrantLock.java @@ -64,7 +64,7 @@ import java.util.Collection; * fair lock may obtain it multiple times in succession while other * active threads are not progressing and not currently holding the * lock. - * Also note that the untimed {@link #tryLock() tryLock} method does not + * Also note that the untimed {@link #tryLock()} method does not * honor the fairness setting. It will succeed if the lock * is available even if other threads are waiting. * @@ -88,10 +88,9 @@ import java.util.Collection; * }} * *

    In addition to implementing the {@link Lock} interface, this - * class defines methods {@code isLocked} and - * {@code getLockQueueLength}, as well as some associated - * {@code protected} access methods that may be useful for - * instrumentation and monitoring. + * class defines a number of {@code public} and {@code protected} + * methods for inspecting the state of the lock. Some of these + * methods are only useful for instrumentation and monitoring. * *

    Serialization of this class behaves in the same way as built-in * locks: a deserialized lock is in the unlocked state, regardless of @@ -124,9 +123,8 @@ public class ReentrantLock implements Lock, java.io.Serializable { abstract void lock(); /** - * Performs non-fair tryLock. tryAcquire is - * implemented in subclasses, but both need nonfair - * try for trylock method. + * Performs non-fair tryLock. tryAcquire is implemented in + * subclasses, but both need nonfair try for trylock method. */ final boolean nonfairTryAcquire(int acquires) { final Thread current = Thread.currentThread(); @@ -353,7 +351,7 @@ public class ReentrantLock implements Lock, java.io.Serializable { * {@link #tryLock(long, TimeUnit) tryLock(0, TimeUnit.SECONDS) } * which is almost equivalent (it also detects interruption). * - *

    If the current thread already holds this lock then the hold + *

    If the current thread already holds this lock then the hold * count is incremented by one and the method returns {@code true}. * *

    If the lock is held by another thread then this method will return @@ -538,10 +536,10 @@ public class ReentrantLock implements Lock, java.io.Serializable { /** * Queries if this lock is held by the current thread. * - *

    Analogous to the {@link Thread#holdsLock} method for built-in - * monitor locks, this method is typically used for debugging and - * testing. For example, a method that should only be called while - * a lock is held can assert that this is the case: + *

    Analogous to the {@link Thread#holdsLock(Object)} method for + * built-in monitor locks, this method is typically used for + * debugging and testing. For example, a method that should only be + * called while a lock is held can assert that this is the case: * * 

     {@code
      * class X {
diff --git a/jdk/src/share/classes/java/util/concurrent/locks/StampedLock.java b/jdk/src/share/classes/java/util/concurrent/locks/StampedLock.java
index 0ca43f630f7..1506e5a4e46 100644
--- a/jdk/src/share/classes/java/util/concurrent/locks/StampedLock.java
+++ b/jdk/src/share/classes/java/util/concurrent/locks/StampedLock.java
@@ -366,6 +366,8 @@ public class StampedLock implements java.io.Serializable {
      * Behavior under timeout and interruption matches that specified
      * for method {@link Lock#tryLock(long,TimeUnit)}.
      *
+     * @param time the maximum time to wait for the lock
+     * @param unit the time unit of the {@code time} argument
      * @return a stamp that can be used to unlock or convert mode,
      * or zero if the lock is not available
      * @throws InterruptedException if the current thread is interrupted
@@ -445,6 +447,8 @@ public class StampedLock implements java.io.Serializable {
      * Behavior under timeout and interruption matches that specified
      * for method {@link Lock#tryLock(long,TimeUnit)}.
      *
+     * @param time the maximum time to wait for the lock
+     * @param unit the time unit of the {@code time} argument
      * @return a stamp that can be used to unlock or convert mode,
      * or zero if the lock is not available
      * @throws InterruptedException if the current thread is interrupted
@@ -510,7 +514,8 @@ public class StampedLock implements java.io.Serializable {
      * obtained from {@link #tryOptimisticRead} or a locking method
      * for this lock has no defined effect or result.
      *
-     * @return true if the lock has not been exclusively acquired
+     * @param stamp a stamp
+     * @return {@code true} if the lock has not been exclusively acquired
      * since issuance of the given stamp; else false
      */
     public boolean validate(long stamp) {
@@ -723,7 +728,7 @@ public class StampedLock implements java.io.Serializable {
      * stamp value. This method may be useful for recovery after
      * errors.
      *
-     * @return true if the lock was held, else false
+     * @return {@code true} if the lock was held, else false
      */
     public boolean tryUnlockWrite() {
         long s; WNode h;
@@ -741,7 +746,7 @@ public class StampedLock implements java.io.Serializable {
      * requiring a stamp value. This method may be useful for recovery
      * after errors.
      *
-     * @return true if the read lock was held, else false
+     * @return {@code true} if the read lock was held, else false
      */
     public boolean tryUnlockRead() {
         long s, m; WNode h;
@@ -773,18 +778,18 @@ public class StampedLock implements java.io.Serializable {
     }
 
     /**
-     * Returns true if the lock is currently held exclusively.
+     * Returns {@code true} if the lock is currently held exclusively.
      *
-     * @return true if the lock is currently held exclusively
+     * @return {@code true} if the lock is currently held exclusively
      */
     public boolean isWriteLocked() {
         return (state & WBIT) != 0L;
     }
 
     /**
-     * Returns true if the lock is currently held non-exclusively.
+     * Returns {@code true} if the lock is currently held non-exclusively.
      *
-     * @return true if the lock is currently held non-exclusively
+     * @return {@code true} if the lock is currently held non-exclusively
      */
     public boolean isReadLocked() {
         return (state & RBITS) != 0L;