--- a/jdk/src/java.base/share/classes/sun/misc/Unsafe.java Tue Mar 10 14:20:06 2015 -0700
+++ b/jdk/src/java.base/share/classes/sun/misc/Unsafe.java Wed Mar 04 17:35:40 2015 -0800
@@ -57,31 +57,29 @@
* Provides the caller with the capability of performing unsafe
* operations.
*
- * <p> The returned <code>Unsafe</code> object should be carefully guarded
+ * <p>The returned {@code Unsafe} object should be carefully guarded
* by the caller, since it can be used to read and write data at arbitrary
* memory addresses. It must never be passed to untrusted code.
*
- * <p> Most methods in this class are very low-level, and correspond to a
+ * <p>Most methods in this class are very low-level, and correspond to a
* small number of hardware instructions (on typical machines). Compilers
* are encouraged to optimize these methods accordingly.
*
- * <p> Here is a suggested idiom for using unsafe operations:
+ * <p>Here is a suggested idiom for using unsafe operations:
*
- * <blockquote><pre>
+ * <pre> {@code
* class MyTrustedClass {
* private static final Unsafe unsafe = Unsafe.getUnsafe();
* ...
* private long myCountAddress = ...;
* public int getCount() { return unsafe.getByte(myCountAddress); }
- * }
- * </pre></blockquote>
+ * }}</pre>
+ *
+ * (It may assist compilers to make the local variable {@code final}.)
*
- * (It may assist compilers to make the local variable be
- * <code>final</code>.)
- *
- * @exception SecurityException if a security manager exists and its
- * <code>checkPropertiesAccess</code> method doesn't allow
- * access to the system properties.
+ * @throws SecurityException if a security manager exists and its
+ * {@code checkPropertiesAccess} method doesn't allow
+ * access to the system properties.
*/
@CallerSensitive
public static Unsafe getUnsafe() {
@@ -100,28 +98,27 @@
/**
* Fetches a value from a given Java variable.
* More specifically, fetches a field or array element within the given
- * object <code>o</code> at the given offset, or (if <code>o</code> is
- * null) from the memory address whose numerical value is the given
- * offset.
+ * object {@code o} at the given offset, or (if {@code o} is null)
+ * from the memory address whose numerical value is the given offset.
* <p>
* The results are undefined unless one of the following cases is true:
* <ul>
* <li>The offset was obtained from {@link #objectFieldOffset} on
* the {@link java.lang.reflect.Field} of some Java field and the object
- * referred to by <code>o</code> is of a class compatible with that
+ * referred to by {@code o} is of a class compatible with that
* field's class.
*
- * <li>The offset and object reference <code>o</code> (either null or
+ * <li>The offset and object reference {@code o} (either null or
* non-null) were both obtained via {@link #staticFieldOffset}
* and {@link #staticFieldBase} (respectively) from the
* reflective {@link Field} representation of some Java field.
*
- * <li>The object referred to by <code>o</code> is an array, and the offset
- * is an integer of the form <code>B+N*S</code>, where <code>N</code> is
- * a valid index into the array, and <code>B</code> and <code>S</code> are
+ * <li>The object referred to by {@code o} is an array, and the offset
+ * is an integer of the form {@code B+N*S}, where {@code N} is
+ * a valid index into the array, and {@code B} and {@code S} are
* the values obtained by {@link #arrayBaseOffset} and {@link
* #arrayIndexScale} (respectively) from the array's class. The value
- * referred to is the <code>N</code><em>th</em> element of the array.
+ * referred to is the {@code N}<em>th</em> element of the array.
*
* </ul>
* <p>
@@ -162,7 +159,7 @@
* is stored into that variable.
* <p>
* The variable must be of the same type as the method
- * parameter <code>x</code>.
+ * parameter {@code x}.
*
* @param o Java heap object in which the variable resides, if any, else
* null
@@ -184,9 +181,9 @@
/**
* Stores a reference value into a given Java variable.
* <p>
- * Unless the reference <code>x</code> being stored is either null
+ * Unless the reference {@code x} being stored is either null
* or matches the field type, the results are undefined.
- * If the reference <code>o</code> is non-null, car marks or
+ * If the reference {@code o} is non-null, car marks or
* other store barriers for that object (if the VM requires them)
* are updated.
* @see #putInt(Object, long, int)
@@ -272,11 +269,11 @@
* zero, or does not point into a block obtained from {@link
* #allocateMemory}, the results are undefined.
*
- * <p> If the native pointer is less than 64 bits wide, it is extended as
+ * <p>If the native pointer is less than 64 bits wide, it is extended as
* an unsigned number to a Java long. The pointer may be indexed by any
* given byte offset, simply by adding that offset (as a simple integer) to
* the long representing the pointer. The number of bytes actually read
- * from the target address maybe determined by consulting {@link
+ * from the target address may be determined by consulting {@link
* #addressSize}.
*
* @see #allocateMemory
@@ -288,7 +285,7 @@
* zero, or does not point into a block obtained from {@link
* #allocateMemory}, the results are undefined.
*
- * <p> The number of bytes actually written at the target address maybe
+ * <p>The number of bytes actually written at the target address may be
* determined by consulting {@link #addressSize}.
*
* @see #getAddress(long)
@@ -357,7 +354,7 @@
* (usually zero). This provides a <em>single-register</em> addressing mode,
* as discussed in {@link #getInt(Object,long)}.
*
- * <p>Equivalent to <code>setMemory(null, address, bytes, value)</code>.
+ * <p>Equivalent to {@code setMemory(null, address, bytes, value)}.
*/
public void setMemory(long address, long bytes, byte value) {
setMemory(null, address, bytes, value);
@@ -388,7 +385,7 @@
* block. This provides a <em>single-register</em> addressing mode,
* as discussed in {@link #getInt(Object,long)}.
*
- * Equivalent to <code>copyMemory(null, srcAddress, null, destAddress, bytes)</code>.
+ * Equivalent to {@code copyMemory(null, srcAddress, null, destAddress, bytes)}.
*/
public void copyMemory(long srcAddress, long destAddress, long bytes) {
copyMemory(null, srcAddress, null, destAddress, bytes);
@@ -413,7 +410,7 @@
public static final int INVALID_FIELD_OFFSET = -1;
/**
- * Report the location of a given field in the storage allocation of its
+ * Reports the location of a given field in the storage allocation of its
* class. Do not expect to perform any sort of arithmetic on this offset;
* it is just a cookie which is passed to the unsafe heap memory accessors.
*
@@ -433,7 +430,7 @@
public native long objectFieldOffset(Field f);
/**
- * Report the location of a given static field, in conjunction with {@link
+ * Reports the location of a given static field, in conjunction with {@link
* #staticFieldBase}.
* <p>Do not expect to perform any sort of arithmetic on this offset;
* it is just a cookie which is passed to the unsafe heap memory accessors.
@@ -452,7 +449,7 @@
public native long staticFieldOffset(Field f);
/**
- * Report the location of a given static field, in conjunction with {@link
+ * Reports the location of a given static field, in conjunction with {@link
* #staticFieldOffset}.
* <p>Fetch the base "Object", if any, with which static fields of the
* given class can be accessed via methods like {@link #getInt(Object,
@@ -464,7 +461,7 @@
public native Object staticFieldBase(Field f);
/**
- * Detect if the given class may need to be initialized. This is often
+ * Detects if the given class may need to be initialized. This is often
* needed in conjunction with obtaining the static field base of a
* class.
* @return false only if a call to {@code ensureClassInitialized} would have no effect
@@ -472,14 +469,14 @@
public native boolean shouldBeInitialized(Class<?> c);
/**
- * Ensure the given class has been initialized. This is often
+ * Ensures the given class has been initialized. This is often
* needed in conjunction with obtaining the static field base of a
* class.
*/
public native void ensureClassInitialized(Class<?> c);
/**
- * Report the offset of the first element in the storage allocation of a
+ * Reports the offset of the first element in the storage allocation of a
* given array class. If {@link #arrayIndexScale} returns a non-zero value
* for the same class, you may use that scale factor, together with this
* base offset, to form new offsets to access elements of arrays of the
@@ -527,7 +524,7 @@
= theUnsafe.arrayBaseOffset(Object[].class);
/**
- * Report the scale factor for addressing elements in the storage
+ * Reports the scale factor for addressing elements in the storage
* allocation of a given array class. However, arrays of "narrow" types
* will generally not work properly with accessors like {@link
* #getByte(Object, long)}, so the scale factor for such classes is reported
@@ -576,7 +573,7 @@
= theUnsafe.arrayIndexScale(Object[].class);
/**
- * Report the size in bytes of a native pointer, as stored via {@link
+ * Reports the size in bytes of a native pointer, as stored via {@link
* #putAddress}. This value will be either 4 or 8. Note that the sizes of
* other primitive types (as stored in native memory blocks) is determined
* fully by their information content.
@@ -587,7 +584,7 @@
public static final int ADDRESS_SIZE = theUnsafe.addressSize();
/**
- * Report the size in bytes of a native memory page (whatever that is).
+ * Reports the size in bytes of a native memory page (whatever that is).
* This value will always be a power of two.
*/
public native int pageSize();
@@ -596,7 +593,7 @@
/// random trusted operations from JNI:
/**
- * Tell the VM to define a class, without security checks. By default, the
+ * Tells the VM to define a class, without security checks. By default, the
* class loader and protection domain come from the caller's class.
*/
public native Class<?> defineClass(String name, byte[] b, int off, int len,
@@ -604,7 +601,7 @@
ProtectionDomain protectionDomain);
/**
- * Define a class but do not make it known to the class loader or system dictionary.
+ * Defines a class but does not make it known to the class loader or system dictionary.
* <p>
* For each CP entry, the corresponding CP patch must either be null or have
* the a format that matches its tag:
@@ -621,38 +618,38 @@
*/
public native Class<?> defineAnonymousClass(Class<?> hostClass, byte[] data, Object[] cpPatches);
-
- /** Allocate an instance but do not run any constructor.
- Initializes the class if it has not yet been. */
+ /**
+ * Allocates an instance but does not run any constructor.
+ * Initializes the class if it has not yet been.
+ */
public native Object allocateInstance(Class<?> cls)
throws InstantiationException;
- /** Throw the exception without telling the verifier. */
+ /** Throws the exception without telling the verifier. */
public native void throwException(Throwable ee);
-
/**
- * Atomically update Java variable to <tt>x</tt> if it is currently
- * holding <tt>expected</tt>.
- * @return <tt>true</tt> if successful
+ * Atomically updates Java variable to {@code x} if it is currently
+ * holding {@code expected}.
+ * @return {@code true} if successful
*/
public final native boolean compareAndSwapObject(Object o, long offset,
Object expected,
Object x);
/**
- * Atomically update Java variable to <tt>x</tt> if it is currently
- * holding <tt>expected</tt>.
- * @return <tt>true</tt> if successful
+ * Atomically updates Java variable to {@code x} if it is currently
+ * holding {@code expected}.
+ * @return {@code true} if successful
*/
public final native boolean compareAndSwapInt(Object o, long offset,
int expected,
int x);
/**
- * Atomically update Java variable to <tt>x</tt> if it is currently
- * holding <tt>expected</tt>.
- * @return <tt>true</tt> if successful
+ * Atomically updates Java variable to {@code x} if it is currently
+ * holding {@code expected}.
+ * @return {@code true} if successful
*/
public final native boolean compareAndSwapLong(Object o, long offset,
long expected,
@@ -736,28 +733,28 @@
public native void putOrderedLong(Object o, long offset, long x);
/**
- * Unblock the given thread blocked on <tt>park</tt>, or, if it is
- * not blocked, cause the subsequent call to <tt>park</tt> not to
+ * Unblocks the given thread blocked on {@code park}, or, if it is
+ * not blocked, causes the subsequent call to {@code park} not to
* block. Note: this operation is "unsafe" solely because the
* caller must somehow ensure that the thread has not been
* destroyed. Nothing special is usually required to ensure this
* when called from Java (in which there will ordinarily be a live
* reference to the thread) but this is not nearly-automatically
* so when calling from native code.
+ *
* @param thread the thread to unpark.
- *
*/
public native void unpark(Object thread);
/**
- * Block current thread, returning when a balancing
- * <tt>unpark</tt> occurs, or a balancing <tt>unpark</tt> has
+ * Blocks current thread, returning when a balancing
+ * {@code unpark} occurs, or a balancing {@code unpark} has
* already occurred, or the thread is interrupted, or, if not
* absolute and time is not zero, the given time nanoseconds have
* elapsed, or if absolute, the given deadline in milliseconds
* since Epoch has passed, or spuriously (i.e., returning for no
* "reason"). Note: This operation is in the Unsafe class only
- * because <tt>unpark</tt> is, so it would be strange to place it
+ * because {@code unpark} is, so it would be strange to place it
* elsewhere.
*/
public native void park(boolean isAbsolute, long time);
@@ -765,8 +762,8 @@
/**
* Gets the load average in the system run queue assigned
* to the available processors averaged over various periods of time.
- * This method retrieves the given <tt>nelem</tt> samples and
- * assigns to the elements of the given <tt>loadavg</tt> array.
+ * This method retrieves the given {@code nelem} samples and
+ * assigns to the elements of the given {@code loadavg} array.
* The system imposes a maximum of 3 samples, representing
* averages over the last 1, 5, and 15 minutes, respectively.
*
@@ -784,8 +781,8 @@
/**
* Atomically adds the given value to the current value of a field
- * or array element within the given object <code>o</code>
- * at the given <code>offset</code>.
+ * or array element within the given object {@code o}
+ * at the given {@code offset}.
*
* @param o object/array to update the field/element in
* @param offset field/element offset
@@ -803,8 +800,8 @@
/**
* Atomically adds the given value to the current value of a field
- * or array element within the given object <code>o</code>
- * at the given <code>offset</code>.
+ * or array element within the given object {@code o}
+ * at the given {@code offset}.
*
* @param o object/array to update the field/element in
* @param offset field/element offset
@@ -822,8 +819,8 @@
/**
* Atomically exchanges the given value with the current value of
- * a field or array element within the given object <code>o</code>
- * at the given <code>offset</code>.
+ * a field or array element within the given object {@code o}
+ * at the given {@code offset}.
*
* @param o object/array to update the field/element in
* @param offset field/element offset
@@ -841,8 +838,8 @@
/**
* Atomically exchanges the given value with the current value of
- * a field or array element within the given object <code>o</code>
- * at the given <code>offset</code>.
+ * a field or array element within the given object {@code o}
+ * at the given {@code offset}.
*
* @param o object/array to update the field/element in
* @param offset field/element offset
@@ -861,7 +858,7 @@
/**
* Atomically exchanges the given reference value with the current
* reference value of a field or array element within the given
- * object <code>o</code> at the given <code>offset</code>.
+ * object {@code o} at the given {@code offset}.
*
* @param o object/array to update the field/element in
* @param offset field/element offset