8074577: Modernize Unsafe internal javadoc
Use modern javadoc style Reviewed-by: jrose
This commit is contained in:
Martin Buchholz
parent
f245610f7f
commit
f825d1ff35
@ -57,31 +57,29 @@ public final class Unsafe {
|
||||
* 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 be
|
||||
* <code>final</code>.)
|
||||
* (It may assist compilers to make the local variable {@code final}.)
|
||||
*
|
||||
* @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 @@ public final class Unsafe {
|
||||
/**
|
||||
* 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 @@ public final class Unsafe {
|
||||
* 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 @@ public final class Unsafe {
|
||||
/**
|
||||
* 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 @@ public final class Unsafe {
|
||||
* 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 @@ public final class Unsafe {
|
||||
* 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 @@ public final class Unsafe {
|
||||
* (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 @@ public final class Unsafe {
|
||||
* 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 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}.
|
||||
* <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 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}.
|
||||
* <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 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.
|
||||
* <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 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 <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 final class Unsafe {
|
||||
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.
|
||||
*
|
||||
* @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 @@ 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 <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 @@ public final class Unsafe {
|
||||
|
||||
/**
|
||||
* 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 @@ public final class Unsafe {
|
||||
|
||||
/**
|
||||
* 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 @@ public final class Unsafe {
|
||||
|
||||
/**
|
||||
* 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 @@ public final class Unsafe {
|
||||
|
||||
/**
|
||||
* 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 @@ 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 <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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user