Module jdk.unsupported
Package sun.misc

Class Unsafe


  • public final class Unsafe
extends Object
    A collection of methods for performing low-level, unsafe operations. Although the class and all methods are public, use of this class is limited because only trusted code can obtain instances of it. Note: It is the resposibility of the caller to make sure arguments are checked before methods of this class are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!
    See Also:
    getUnsafe()

    • Field Detail

      • ARRAY_BOOLEAN_BASE_OFFSET

        public static final int ARRAY_BOOLEAN_BASE_OFFSET
        The value of arrayBaseOffset(boolean[].class)

      • ARRAY_BYTE_BASE_OFFSET

        public static final int ARRAY_BYTE_BASE_OFFSET
        The value of arrayBaseOffset(byte[].class)

      • ARRAY_SHORT_BASE_OFFSET

        public static final int ARRAY_SHORT_BASE_OFFSET
        The value of arrayBaseOffset(short[].class)

      • ARRAY_CHAR_BASE_OFFSET

        public static final int ARRAY_CHAR_BASE_OFFSET
        The value of arrayBaseOffset(char[].class)

      • ARRAY_INT_BASE_OFFSET

        public static final int ARRAY_INT_BASE_OFFSET
        The value of arrayBaseOffset(int[].class)

      • ARRAY_LONG_BASE_OFFSET

        public static final int ARRAY_LONG_BASE_OFFSET
        The value of arrayBaseOffset(long[].class)

      • ARRAY_FLOAT_BASE_OFFSET

        public static final int ARRAY_FLOAT_BASE_OFFSET
        The value of arrayBaseOffset(float[].class)

      • ARRAY_DOUBLE_BASE_OFFSET

        public static final int ARRAY_DOUBLE_BASE_OFFSET
        The value of arrayBaseOffset(double[].class)

      • ARRAY_OBJECT_BASE_OFFSET

        public static final int ARRAY_OBJECT_BASE_OFFSET
        The value of arrayBaseOffset(Object[].class)

      • ARRAY_BOOLEAN_INDEX_SCALE

        public static final int ARRAY_BOOLEAN_INDEX_SCALE
        The value of arrayIndexScale(boolean[].class)

      • ARRAY_BYTE_INDEX_SCALE

        public static final int ARRAY_BYTE_INDEX_SCALE
        The value of arrayIndexScale(byte[].class)

      • ARRAY_SHORT_INDEX_SCALE

        public static final int ARRAY_SHORT_INDEX_SCALE
        The value of arrayIndexScale(short[].class)

      • ARRAY_CHAR_INDEX_SCALE

        public static final int ARRAY_CHAR_INDEX_SCALE
        The value of arrayIndexScale(char[].class)

      • ARRAY_INT_INDEX_SCALE

        public static final int ARRAY_INT_INDEX_SCALE
        The value of arrayIndexScale(int[].class)

      • ARRAY_LONG_INDEX_SCALE

        public static final int ARRAY_LONG_INDEX_SCALE
        The value of arrayIndexScale(long[].class)

      • ARRAY_FLOAT_INDEX_SCALE

        public static final int ARRAY_FLOAT_INDEX_SCALE
        The value of arrayIndexScale(float[].class)

      • ARRAY_DOUBLE_INDEX_SCALE

        public static final int ARRAY_DOUBLE_INDEX_SCALE
        The value of arrayIndexScale(double[].class)

      • ARRAY_OBJECT_INDEX_SCALE

        public static final int ARRAY_OBJECT_INDEX_SCALE
        The value of arrayIndexScale(Object[].class)

      • ADDRESS_SIZE

        public static final int ADDRESS_SIZE
        The value of addressSize()

    • Method Detail

      • getUnsafe

        public static Unsafe getUnsafe()
        Provides the caller with the capability of performing unsafe operations.

        The returned 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 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: 

         
 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 final.)
        Throws:
        SecurityException - if the class loader of the caller class is not in the system domain in which all permissions are granted.

      • getInt

        public int getInt(Object o,
                  long offset)
        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.

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

        If one of the above cases is true, the call references a specific Java variable (field or array element). However, the results are undefined if that variable is not in fact of the type returned by this method.

        This method refers to a variable by means of two parameters, and so it provides (in effect) a double-register addressing mode for Java variables. When the object reference is null, this method uses its offset as an absolute address. This is similar in operation to methods such as getInt(long), which provide (in effect) a single-register addressing mode for non-Java variables. However, because Java variables may have a different layout in memory from non-Java variables, programmers should not assume that these two addressing modes are ever equivalent. Also, programmers should remember that offsets from the double-register addressing mode cannot be portably confused with longs used in the single-register addressing mode.

        Parameters:
        o - Java heap object in which the variable resides, if any, else null
        offset - indication of where the variable resides in a Java heap object, if any, else a memory address locating the variable statically
        Returns:
        the value fetched from the indicated Java variable
        Throws:
        RuntimeException - No defined exceptions are thrown, not even NullPointerException

      • putInt

        public void putInt(Object o,
                   long offset,
                   int x)
        Stores a value into a given Java variable.

        The first two parameters are interpreted exactly as with getInt(Object, long) to refer to a specific Java variable (field or array element). The given value is stored into that variable.

        The variable must be of the same type as the method parameter x.

        Parameters:
        o - Java heap object in which the variable resides, if any, else null
        offset - indication of where the variable resides in a Java heap object, if any, else a memory address locating the variable statically
        x - the value to store into the indicated Java variable
        Throws:
        RuntimeException - No defined exceptions are thrown, not even NullPointerException

      • putObject

        public void putObject(Object o,
                      long offset,
                      Object x)
        Stores a reference value into a given Java variable.

        Unless the reference x being stored is either null or matches the field type, the results are undefined. If the reference o is non-null, card marks or other store barriers for that object (if the VM requires them) are updated.

        See Also:
        putInt(Object, long, int)

      • getByte

        public byte getByte(long address)
        Fetches a value from a given memory address. If the address is zero, or does not point into a block obtained from allocateMemory(long), the results are undefined.
        See Also:
        allocateMemory(long)

      • putByte

        public void putByte(long address,
                    byte x)
        Stores a value into a given memory address. If the address is zero, or does not point into a block obtained from allocateMemory(long), the results are undefined.
        See Also:
        getByte(long)

      • getShort

        public short getShort(long address)
        See Also:
        getByte(long)

      • getChar

        public char getChar(long address)
        See Also:
        getByte(long)

      • getInt

        public int getInt(long address)
        See Also:
        getByte(long)

      • getLong

        public long getLong(long address)
        See Also:
        getByte(long)

      • getFloat

        public float getFloat(long address)
        See Also:
        getByte(long)

      • getDouble

        public double getDouble(long address)
        See Also:
        getByte(long)

      • getAddress

        public long getAddress(long address)
        Fetches a native pointer from a given memory address. If the address is zero, or does not point into a block obtained from allocateMemory(long), the results are undefined.

        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 may be determined by consulting addressSize().

        See Also:
        allocateMemory(long)

      • putAddress

        public void putAddress(long address,
                       long x)
        Stores a native pointer into a given memory address. If the address is zero, or does not point into a block obtained from allocateMemory(long), the results are undefined.

        The number of bytes actually written at the target address may be determined by consulting addressSize().

        See Also:
        getAddress(long)

      • allocateMemory

        public long allocateMemory(long bytes)
        Allocates a new block of native memory, of the given size in bytes. The contents of the memory are uninitialized; they will generally be garbage. The resulting native pointer will never be zero, and will be aligned for all value types. Dispose of this memory by calling freeMemory(long), or resize it with reallocateMemory(long, long). Note: It is the resposibility of the caller to make sure arguments are checked before the methods are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!
        Throws:
        RuntimeException - if the size is negative or too large for the native size_t type
        OutOfMemoryError - if the allocation is refused by the system
        See Also:
        getByte(long), putByte(long, byte)

      • reallocateMemory

        public long reallocateMemory(long address,
                             long bytes)
        Resizes a new block of native memory, to the given size in bytes. The contents of the new block past the size of the old block are uninitialized; they will generally be garbage. The resulting native pointer will be zero if and only if the requested size is zero. The resulting native pointer will be aligned for all value types. Dispose of this memory by calling freeMemory(long), or resize it with reallocateMemory(long, long). The address passed to this method may be null, in which case an allocation will be performed. Note: It is the resposibility of the caller to make sure arguments are checked before the methods are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!
        Throws:
        RuntimeException - if the size is negative or too large for the native size_t type
        OutOfMemoryError - if the allocation is refused by the system
        See Also:
        allocateMemory(long)

      • setMemory

        public void setMemory(Object o,
                      long offset,
                      long bytes,
                      byte value)
        Sets all bytes in a given block of memory to a fixed value (usually zero).

        This method determines a block's base address by means of two parameters, and so it provides (in effect) a double-register addressing mode, as discussed in getInt(Object,long). When the object reference is null, the offset supplies an absolute base address.

        The stores are in coherent (atomic) units of a size determined by the address and length parameters. If the effective address and length are all even modulo 8, the stores take place in 'long' units. If the effective address and length are (resp.) even modulo 4 or 2, the stores take place in units of 'int' or 'short'. Note: It is the resposibility of the caller to make sure arguments are checked before the methods are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!

        Throws:
        RuntimeException - if any of the arguments is invalid
        Since:
        1.7

      • setMemory

        public void setMemory(long address,
                      long bytes,
                      byte value)
        Sets all bytes in a given block of memory to a fixed value (usually zero). This provides a single-register addressing mode, as discussed in getInt(Object,long).

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

      • copyMemory

        public void copyMemory(Object srcBase,
                       long srcOffset,
                       Object destBase,
                       long destOffset,
                       long bytes)
        Sets all bytes in a given block of memory to a copy of another block.

        This method determines each block's base address by means of two parameters, and so it provides (in effect) a double-register addressing mode, as discussed in getInt(Object,long). When the object reference is null, the offset supplies an absolute base address.

        The transfers are in coherent (atomic) units of a size determined by the address and length parameters. If the effective addresses and length are all even modulo 8, the transfer takes place in 'long' units. If the effective addresses and length are (resp.) even modulo 4 or 2, the transfer takes place in units of 'int' or 'short'. Note: It is the resposibility of the caller to make sure arguments are checked before the methods are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!

        Throws:
        RuntimeException - if any of the arguments is invalid
        Since:
        1.7

      • copyMemory

        public void copyMemory(long srcAddress,
                       long destAddress,
                       long bytes)
        Sets all bytes in a given block of memory to a copy of another block. This provides a single-register addressing mode, as discussed in getInt(Object,long). Equivalent to copyMemory(null, srcAddress, null, destAddress, bytes).

      • freeMemory

        public void freeMemory(long address)
        Disposes of a block of native memory, as obtained from allocateMemory(long) or reallocateMemory(long, long). The address passed to this method may be null, in which case no action is taken. Note: It is the resposibility of the caller to make sure arguments are checked before the methods are called. While some rudimentary checks are performed on the input, the checks are best effort and when performance is an overriding priority, as when methods of this class are optimized by the runtime compiler, some or all checks (if any) may be elided. Hence, the caller must not rely on the checks and corresponding exceptions!
        Throws:
        RuntimeException - if any of the arguments is invalid
        See Also:
        allocateMemory(long)

      • objectFieldOffset

        public long objectFieldOffset(Field f)
        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.

        Any given field will always have the same offset and base, and no two distinct fields of the same class will ever have the same offset and base.

        As of 1.4.1, offsets for fields are represented as long values, although the Sun JVM does not use the most significant 32 bits. However, JVM implementations which store static fields at absolute addresses can use long offsets and null base pointers to express the field locations in a form usable by getInt(Object,long). Therefore, code which will be ported to such JVMs on 64-bit platforms must preserve all bits of static field offsets.

        See Also:
        getInt(Object, long)

      • staticFieldOffset

        public long staticFieldOffset(Field f)
        Reports the location of a given static field, in conjunction with staticFieldBase(java.lang.reflect.Field).

        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.

        Any given field will always have the same offset, and no two distinct fields of the same class will ever have the same offset.

        As of 1.4.1, offsets for fields are represented as long values, although the Sun JVM does not use the most significant 32 bits. It is hard to imagine a JVM technology which needs more than a few bits to encode an offset within a non-array object, However, for consistency with other methods in this class, this method reports its result as a long value.

        See Also:
        getInt(Object, long)

      • staticFieldBase

        public Object staticFieldBase(Field f)
        Reports the location of a given static field, in conjunction with staticFieldOffset(java.lang.reflect.Field).

        Fetch the base "Object", if any, with which static fields of the given class can be accessed via methods like getInt(Object, long). This value may be null. This value may refer to an object which is a "cookie", not guaranteed to be a real Object, and it should not be used in any way except as argument to the get and put routines in this class.

      • shouldBeInitialized

        public boolean shouldBeInitialized(Class<?> c)
        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.
        Returns:
        false only if a call to ensureClassInitialized would have no effect

      • ensureClassInitialized

        public void ensureClassInitialized(Class<?> c)
        Ensures the given class has been initialized. This is often needed in conjunction with obtaining the static field base of a class.

      • arrayBaseOffset

        public int arrayBaseOffset(Class<?> arrayClass)
        Reports the offset of the first element in the storage allocation of a given array class. If arrayIndexScale(java.lang.Class<?>) 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 given class.
        See Also:
        getInt(Object, long), putInt(Object, long, int)

      • addressSize

        public int addressSize()
        Reports the size in bytes of a native pointer, as stored via putAddress(long, long). 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.

      • pageSize

        public int pageSize()
        Reports the size in bytes of a native memory page (whatever that is). This value will always be a power of two.

      • defineClass

        public Class<?> defineClass(String name,
                            byte[] b,
                            int off,
                            int len,
                            ClassLoader loader,
                            ProtectionDomain protectionDomain)
        Tells the VM to define a class, without security checks. By default, the class loader and protection domain come from the caller's class.

      • defineAnonymousClass

        public Class<?> defineAnonymousClass(Class<?> hostClass,
                                     byte[] data,
                                     Object[] cpPatches)
        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:

        • Integer, Long, Float, Double: the corresponding wrapper object type from java.lang
        • Utf8: a string (must have suitable syntax if used as signature or name)
        • Class: any java.lang.Class object
        • String: any object (not just a java.lang.String)
        • InterfaceMethodRef: (NYI) a method handle to invoke on that call site's arguments
        Parameters:
        hostClass - context for linkage, access control, protection domain, and class loader
        data - bytes of a class file
        cpPatches - where non-null entries exist, they replace corresponding CP entries in data

      • throwException

        public void throwException(Throwable ee)
        Throws the exception without telling the verifier.

      • compareAndSwapObject

        public final boolean compareAndSwapObject(Object o,
                                          long offset,
                                          Object expected,
                                          Object x)
        Atomically updates Java variable to x if it is currently holding expected.

        This operation has memory semantics of a volatile read and write. Corresponds to C11 atomic_compare_exchange_strong.

        Returns:
        true if successful

      • compareAndSwapInt

        public final boolean compareAndSwapInt(Object o,
                                       long offset,
                                       int expected,
                                       int x)
        Atomically updates Java variable to x if it is currently holding expected.

        This operation has memory semantics of a volatile read and write. Corresponds to C11 atomic_compare_exchange_strong.

        Returns:
        true if successful

      • compareAndSwapLong

        public final boolean compareAndSwapLong(Object o,
                                        long offset,
                                        long expected,
                                        long x)
        Atomically updates Java variable to x if it is currently holding expected.

        This operation has memory semantics of a volatile read and write. Corresponds to C11 atomic_compare_exchange_strong.

        Returns:
        true if successful

      • getObjectVolatile

        public Object getObjectVolatile(Object o,
                                long offset)
        Fetches a reference value from a given Java variable, with volatile load semantics. Otherwise identical to getObject(Object, long)

      • putObjectVolatile

        public void putObjectVolatile(Object o,
                              long offset,
                              Object x)
        Stores a reference value into a given Java variable, with volatile store semantics. Otherwise identical to putObject(Object, long, Object)

      • putOrderedObject

        public void putOrderedObject(Object o,
                             long offset,
                             Object x)
        Version of putObjectVolatile(Object, long, Object) that does not guarantee immediate visibility of the store to other threads. This method is generally only useful if the underlying field is a Java volatile (or if an array cell, one that is otherwise only accessed using volatile accesses). Corresponds to C11 atomic_store_explicit(..., memory_order_release).

      • unpark

        public void unpark(Object thread)
        Unblocks the given thread blocked on park, or, if it is not blocked, causes the subsequent call to 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.
        Parameters:
        thread - the thread to unpark.

      • park

        public void park(boolean isAbsolute,
                 long time)
        Blocks current thread, returning when a balancing unpark occurs, or a balancing 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 elsewhere.

      • getLoadAverage

        public int getLoadAverage(double[] loadavg,
                          int nelems)
        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. The system imposes a maximum of 3 samples, representing averages over the last 1, 5, and 15 minutes, respectively.
        Parameters:
        loadavg - an array of double of size nelems
        nelems - the number of samples to be retrieved and must be 1 to 3.
        Returns:
        the number of samples actually retrieved; or -1 if the load average is unobtainable.

      • getAndAddInt

        public final int getAndAddInt(Object o,
                              long offset,
                              int delta)
        Atomically adds the given value to the current value of a field or array element within the given object o at the given offset.
        Parameters:
        o - object/array to update the field/element in
        offset - field/element offset
        delta - the value to add
        Returns:
        the previous value
        Since:
        1.8

      • getAndAddLong

        public final long getAndAddLong(Object o,
                                long offset,
                                long delta)
        Atomically adds the given value to the current value of a field or array element within the given object o at the given offset.
        Parameters:
        o - object/array to update the field/element in
        offset - field/element offset
        delta - the value to add
        Returns:
        the previous value
        Since:
        1.8

      • getAndSetInt

        public final int getAndSetInt(Object o,
                              long offset,
                              int newValue)
        Atomically exchanges the given value with the current value of a field or array element within the given object o at the given offset.
        Parameters:
        o - object/array to update the field/element in
        offset - field/element offset
        newValue - new value
        Returns:
        the previous value
        Since:
        1.8

      • getAndSetLong

        public final long getAndSetLong(Object o,
                                long offset,
                                long newValue)
        Atomically exchanges the given value with the current value of a field or array element within the given object o at the given offset.
        Parameters:
        o - object/array to update the field/element in
        offset - field/element offset
        newValue - new value
        Returns:
        the previous value
        Since:
        1.8

      • getAndSetObject

        public final Object getAndSetObject(Object o,
                                    long offset,
                                    Object newValue)
        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.
        Parameters:
        o - object/array to update the field/element in
        offset - field/element offset
        newValue - new value
        Returns:
        the previous value
        Since:
        1.8

      • loadFence

        public void loadFence()
        Ensures that loads before the fence will not be reordered with loads and stores after the fence; a "LoadLoad plus LoadStore barrier". Corresponds to C11 atomic_thread_fence(memory_order_acquire) (an "acquire fence"). A pure LoadLoad fence is not provided, since the addition of LoadStore is almost always desired, and most current hardware instructions that provide a LoadLoad barrier also provide a LoadStore barrier for free.
        Since:
        1.8

      • storeFence

        public void storeFence()
        Ensures that loads and stores before the fence will not be reordered with stores after the fence; a "StoreStore plus LoadStore barrier". Corresponds to C11 atomic_thread_fence(memory_order_release) (a "release fence"). A pure StoreStore fence is not provided, since the addition of LoadStore is almost always desired, and most current hardware instructions that provide a StoreStore barrier also provide a LoadStore barrier for free.
        Since:
        1.8

      • fullFence

        public void fullFence()
        Ensures that loads and stores before the fence will not be reordered with loads and stores after the fence. Implies the effects of both loadFence() and storeFence(), and in addition, the effect of a StoreLoad barrier. Corresponds to C11 atomic_thread_fence(memory_order_seq_cst).
        Since:
        1.8