stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8074577: Modernize Unsafe internal javadoc

Browse Source 
Use modern javadoc style

Reviewed-by: jrose
This commit is contained in:
Martin Buchholz 2015-03-04 17:35:40 -08:00
parent f245610f7f
commit f825d1ff35
1 changed files with 67 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
jdk/src/java.base/share/classes/sun/misc/Unsafe.java
View File

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