diff --git a/jdk/src/java.base/share/classes/sun/misc/Unsafe.java b/jdk/src/java.base/share/classes/sun/misc/Unsafe.java index 15402d168cd..ef25c517f03 100644 --- a/jdk/src/java.base/share/classes/sun/misc/Unsafe.java +++ b/jdk/src/java.base/share/classes/sun/misc/Unsafe.java @@ -57,31 +57,29 @@ public final class Unsafe { * Provides the caller with the capability of performing unsafe * operations. * - *

The returned Unsafe object should be carefully guarded + *

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. * - *

Most methods in this class are very low-level, and correspond to a + *

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. * - *

Here is a suggested idiom for using unsafe operations: + *

Here is a suggested idiom for using unsafe operations: * - * 

+     * 
 {@code
      * class MyTrustedClass {
      *   private static final Unsafe unsafe = Unsafe.getUnsafe();
      *   ...
      *   private long myCountAddress = ...;
      *   public int getCount() { return unsafe.getByte(myCountAddress); }
-     * }
-     *
+ * }} * - * (It may assist compilers to make the local variable be - * final.) + * (It may assist compilers to make the local variable {@code final}.) * - * @exception SecurityException if a security manager exists and its - * checkPropertiesAccess 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 @@ public final class Unsafe { /** * Fetches a value from a given Java variable. * More specifically, fetches a field or array element within the given - * object o at the given offset, or (if o 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. *

* The results are undefined unless one of the following cases is true: *

*

@@ -162,7 +159,7 @@ public final class Unsafe { * is stored into that variable. *

* The variable must be of the same type as the method - * parameter x. + * parameter {@code x}. * * @param o Java heap object in which the variable resides, if any, else * null @@ -184,9 +181,9 @@ public final class Unsafe { /** * Stores a reference value into a given Java variable. *

- * Unless the reference x 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 o 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 @@ public final class Unsafe { * zero, or does not point into a block obtained from {@link * #allocateMemory}, the results are undefined. * - *

If the native pointer is less than 64 bits wide, it is extended as + *

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 @@ public final class Unsafe { * zero, or does not point into a block obtained from {@link * #allocateMemory}, the results are undefined. * - *

The number of bytes actually written at the target address maybe + *

The number of bytes actually written at the target address may be * determined by consulting {@link #addressSize}. * * @see #getAddress(long) @@ -357,7 +354,7 @@ public final class Unsafe { * (usually zero). This provides a single-register addressing mode, * as discussed in {@link #getInt(Object,long)}. * - *

Equivalent to setMemory(null, address, bytes, value). + *

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 @@ public final class Unsafe { * block. This provides a single-register addressing mode, * as discussed in {@link #getInt(Object,long)}. * - * Equivalent to copyMemory(null, srcAddress, null, destAddress, bytes). + * 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 final class Unsafe { 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 final class Unsafe { 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}. *

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 final class Unsafe { 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}. *

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 final class Unsafe { 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 final class Unsafe { 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 @@ public final class Unsafe { = 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 @@ public final class Unsafe { = 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 final class Unsafe { 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 @@ public final class Unsafe { /// 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 @@ public final class Unsafe { 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. *

* 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 final class Unsafe { */ 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 x if it is currently - * holding expected. - * @return true 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 x if it is currently - * holding expected. - * @return true 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 x if it is currently - * holding expected. - * @return true 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 final class Unsafe { public native void putOrderedLong(Object o, long offset, long x); /** - * Unblock the given thread blocked on park, or, if it is - * not blocked, cause the subsequent call to park 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. * + * @param thread the thread to unpark. */ public native void unpark(Object thread); /** - * Block current thread, returning when a balancing - * unpark occurs, or a balancing unpark 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 unpark 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 @@ public final class Unsafe { /** * 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 nelem samples and - * assigns to the elements of the given loadavg 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 @@ public final class Unsafe { /** * Atomically adds the given value to the current value of a field - * or array element within the given object o - * at the given offset. + * 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 @@ public final class Unsafe { /** * Atomically adds the given value to the current value of a field - * or array element within the given object o - * at the given offset. + * 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 @@ public final class Unsafe { /** * Atomically exchanges the given value with the current value of - * a field or array element within the given object o - * at the given offset. + * 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 @@ public final class Unsafe { /** * Atomically exchanges the given value with the current value of - * a field or array element within the given object o - * at the given offset. + * 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 @@ public final class Unsafe { /** * Atomically exchanges the given reference value with the current * reference value of a field or array element within the given - * object o at the given offset. + * object {@code o} at the given {@code offset}. * * @param o object/array to update the field/element in * @param offset field/element offset