Class UnsafeUtil

java.lang.Object
cloud.opencode.base.core.reflect.UnsafeUtil
public final class UnsafeUtil extends Object
Unsafe Utility Class - Modern low-level operations utility 底层操作工具类 - 现代化的底层操作封装

Provides modern alternatives to sun.misc.Unsafe using VarHandle and FFM API where possible.

尽可能使用 VarHandle 和 FFM API 提供 sun.misc.Unsafe 的现代替代方案。

Features | 主要功能:

  • CAS operations via VarHandle (no warnings) - 通过 VarHandle 实现 CAS 操作 (无警告)
  • Volatile field access via VarHandle - 通过 VarHandle 实现 volatile 字段访问
  • Direct memory via FFM API (Java 22+) or Unsafe (Java 21) - 通过 FFM API 或 Unsafe 实现直接内存
  • Instance allocation without constructor - 无构造器实例分配

Memory Backend Selection | 内存后端选择:

  • Java 22+: Uses Foreign Function & Memory API (no deprecation warnings)
  • Java 21: Falls back to sun.misc.Unsafe (with deprecation warnings)

Usage Examples | 使用示例:

// CAS operation with VarHandle (recommended, no warnings)
VarHandle vh = UnsafeUtil.findVarHandle(MyClass.class, "value", int.class);
UnsafeUtil.compareAndSetInt(vh, obj, 0, 1);

// Legacy offset-based API (backward compatible)
long offset = UnsafeUtil.objectFieldOffset(MyClass.class, "value");
UnsafeUtil.compareAndSwapInt(obj, offset, 0, 1);

// Direct memory (uses FFM on Java 22+, Unsafe on Java 21)
long addr = UnsafeUtil.allocateMemory(1024);
UnsafeUtil.putInt(addr, 42);
UnsafeUtil.freeMemory(addr);

// Check which backend is being used
System.out.println("Using FFM: " + UnsafeUtil.isUsingFFM());

Security | 安全性:

  • Thread-safe: Yes, uses ConcurrentHashMap for allocations - 线程安全: 是，使用ConcurrentHashMap管理分配
  • Null-safe: No, null arguments throw exceptions - 空值安全: 否，null参数抛出异常
  • Direct memory access requires careful lifecycle management - 直接内存访问需要仔细的生命周期管理
  • Prefers FFM API on Java 22+ over deprecated sun.misc.Unsafe - Java 22+上优先使用FFM API

Performance | 性能特性:

  • Time complexity: O(1) per operation - 每次操作 O(1)
  • Space complexity: O(1) - O(1)
Since:
JDK 25, opencode-base-core V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • isUsingFFM

      public static boolean isUsingFFM()
      Checks if FFM API is being used 检查是否正在使用 FFM API

    • getMemoryBackendName

      public static String getMemoryBackendName()
      Gets the name of the current memory backend 获取当前使用的内存后端名称

    • getJavaVersion

      public static int getJavaVersion()
      Gets the current Java version 获取当前 Java 版本

    • findVarHandle

      public static VarHandle findVarHandle(Class<?> clazz, String fieldName, Class<?> fieldType)
      Gets the VarHandle for a field 获取字段的 VarHandle

    • findStaticVarHandle

      public static VarHandle findStaticVarHandle(Class<?> clazz, String fieldName, Class<?> fieldType)
      Gets the VarHandle for a static field 获取静态字段的 VarHandle

    • arrayVarHandle

      public static VarHandle arrayVarHandle(Class<?> arrayClass)
      Gets the VarHandle for an array 获取数组的 VarHandle

    • compareAndSetInt

      public static boolean compareAndSetInt(VarHandle vh, Object obj, int expect, int update)
      CAS sets int value (new API, no warnings) CAS 设置 int 值 (新 API，无警告)

    • compareAndSetLong

      public static boolean compareAndSetLong(VarHandle vh, Object obj, long expect, long update)
      CAS sets long value (new API, no warnings) CAS 设置 long 值 (新 API，无警告)

    • compareAndSetObject

      public static boolean compareAndSetObject(VarHandle vh, Object obj, Object expect, Object update)
      CAS sets object reference (new API, no warnings) CAS 设置对象引用 (新 API，无警告)

    • compareAndSetArrayInt

      public static boolean compareAndSetArrayInt(int[] array, int index, int expect, int update)
      CAS sets array element int CAS 设置数组元素 int

    • compareAndSetArrayLong

      public static boolean compareAndSetArrayLong(long[] array, int index, long expect, long update)
      CAS sets array element long CAS 设置数组元素 long

    • compareAndSetArrayObject

      public static boolean compareAndSetArrayObject(Object[] array, int index, Object expect, Object update)
      CAS sets array element Object CAS 设置数组元素 Object

    • getIntVolatile

      public static int getIntVolatile(VarHandle vh, Object obj)
      Gets int field value (volatile, new API) 获取 int 字段值 (volatile，新 API)

    • putIntVolatile

      public static void putIntVolatile(VarHandle vh, Object obj, int value)
      Sets int field value (volatile, new API) 设置 int 字段值 (volatile，新 API)

    • getLongVolatile

      public static long getLongVolatile(VarHandle vh, Object obj)
      Gets long field value (volatile, new API) 获取 long 字段值 (volatile，新 API)

    • putLongVolatile

      public static void putLongVolatile(VarHandle vh, Object obj, long value)
      Sets long field value (volatile, new API) 设置 long 字段值 (volatile，新 API)

    • getObjectVolatile

      public static Object getObjectVolatile(VarHandle vh, Object obj)
      Gets object reference (volatile, new API) 获取对象引用 (volatile，新 API)

    • putObjectVolatile

      public static void putObjectVolatile(VarHandle vh, Object obj, Object value)
      Sets object reference (volatile, new API) 设置对象引用 (volatile，新 API)

    • arrayBaseOffset

      public static int arrayBaseOffset(Class<?> arrayClass)
      Gets the array base offset 获取数组基础偏移量

    • arrayIndexScale

      public static int arrayIndexScale(Class<?> arrayClass)
      Gets the array element scale factor 获取数组元素缩放因子

    • isAvailable

      public static boolean isAvailable()
      Checks if Unsafe is available 检查 Unsafe 是否可用

    • getUnsafe

      public static Object getUnsafe()
      Gets the Unsafe instance 获取 Unsafe 实例

    • allocateInstance

      public static <T> T allocateInstance(Class<T> clazz)
      Allocates an instance (without calling constructor) 分配实例（不调用构造器）

    • throwException

      public static void throwException(Throwable t)
      Throws an exception (unchecked) - uses sneaky throw, no Unsafe needed 抛出异常（不检查）- 使用 sneaky throw，无需 Unsafe

    • pageSize

      public static int pageSize()
      Gets the page size 获取页大小

    • objectFieldOffset

      @Deprecated public static long objectFieldOffset(Class<?> clazz, String fieldName)
      Deprecated.
      使用 findVarHandle(Class, String, Class) 代替
      Gets the field offset (legacy API compatible) 获取字段偏移量 (兼容旧 API)

    • objectFieldOffset

      @Deprecated public static long objectFieldOffset(Field field)
      Deprecated.
      使用 findVarHandle(Class, String, Class) 代替
      Gets the field offset (legacy API compatible) 获取字段偏移量 (兼容旧 API)

    • staticFieldOffset

      @Deprecated public static long staticFieldOffset(Field field)
      Deprecated.
      使用 findStaticVarHandle(Class, String, Class) 代替
      Gets the static field offset (legacy API compatible) 获取静态字段偏移量 (兼容旧 API)

    • compareAndSwapInt

      @Deprecated public static boolean compareAndSwapInt(Object obj, long offset, int expect, int update)
      Deprecated.
      使用 compareAndSetInt(VarHandle, Object, int, int) 代替
      CAS sets int value (legacy API compatible) CAS 设置 int 值 (兼容旧 API)

    • compareAndSwapLong

      @Deprecated public static boolean compareAndSwapLong(Object obj, long offset, long expect, long update)
      Deprecated.
      使用 compareAndSetLong(VarHandle, Object, long, long) 代替
      CAS sets long value (legacy API compatible) CAS 设置 long 值 (兼容旧 API)

    • compareAndSwapObject

      @Deprecated public static boolean compareAndSwapObject(Object obj, long offset, Object expect, Object update)
      Deprecated.
      使用 compareAndSetObject(VarHandle, Object, Object, Object) 代替
      CAS sets object reference (legacy API compatible) CAS 设置对象引用 (兼容旧 API)

    • getIntVolatile

      @Deprecated public static int getIntVolatile(Object obj, long offset)
      Deprecated.
      使用 getIntVolatile(VarHandle, Object) 代替
      Gets object int field value (legacy API compatible) 获取对象的 int 字段值 (兼容旧 API)

    • putIntVolatile

      @Deprecated public static void putIntVolatile(Object obj, long offset, int value)
      Deprecated.
      使用 putIntVolatile(VarHandle, Object, int) 代替
      Sets object int field value (legacy API compatible) 设置对象的 int 字段值 (兼容旧 API)

    • getLongVolatile

      @Deprecated public static long getLongVolatile(Object obj, long offset)
      Deprecated.
      使用 getLongVolatile(VarHandle, Object) 代替
      Gets object long field value (legacy API compatible) 获取对象的 long 字段值 (兼容旧 API)

    • putLongVolatile

      @Deprecated public static void putLongVolatile(Object obj, long offset, long value)
      Deprecated.
      使用 putLongVolatile(VarHandle, Object, long) 代替
      Sets object long field value (legacy API compatible) 设置对象的 long 字段值 (兼容旧 API)

    • getObjectVolatile

      @Deprecated public static Object getObjectVolatile(Object obj, long offset)
      Deprecated.
      使用 getObjectVolatile(VarHandle, Object) 代替
      Gets object reference field value (legacy API compatible) 获取对象的引用字段值 (兼容旧 API)

    • putObjectVolatile

      @Deprecated public static void putObjectVolatile(Object obj, long offset, Object value)
      Deprecated.
      使用 putObjectVolatile(VarHandle, Object, Object) 代替
      Sets object reference field value (legacy API compatible) 设置对象的引用字段值 (兼容旧 API)

    • allocateMemory

      public static long allocateMemory(long bytes)
      Allocates direct memory 分配直接内存

      Java 22+: 使用 FFM API (无警告)

      Java 21: 使用 Unsafe (有弃用警告)

    • reallocateMemory

      public static long reallocateMemory(long address, long bytes)
      Reallocates direct memory 重新分配直接内存

      注意: FFM API 不支持 realloc，会分配新内存并复制数据

    • freeMemory

      public static void freeMemory(long address)
      Frees direct memory 释放直接内存

      FFM: 内存由 Arena 管理，此方法仅移除跟踪

      Unsafe: 显式释放内存

    • setMemory

      public static void setMemory(long address, long bytes, byte value)
      Sets memory value 设置内存值

    • copyMemory

      public static void copyMemory(long srcAddress, long destAddress, long bytes)
      Copies memory 复制内存

    • putByte

      public static void putByte(long address, byte value)
      Writes a byte to memory 写入 byte 到内存

    • getByte

      public static byte getByte(long address)
      Reads a byte from memory 从内存读取 byte

    • putShort

      public static void putShort(long address, short value)
      Writes a short to memory 写入 short 到内存

    • getShort

      public static short getShort(long address)
      Reads a short from memory 从内存读取 short

    • putInt

      public static void putInt(long address, int value)
      Writes an int to memory 写入 int 到内存

    • getInt

      public static int getInt(long address)
      Reads an int from memory 从内存读取 int

    • putLong

      public static void putLong(long address, long value)
      Writes a long to memory 写入 long 到内存

    • getLong

      public static long getLong(long address)
      Reads a long from memory 从内存读取 long

    • putFloat

      public static void putFloat(long address, float value)
      Writes a float to memory 写入 float 到内存

    • getFloat

      public static float getFloat(long address)
      Reads a float from memory 从内存读取 float

    • putDouble

      public static void putDouble(long address, double value)
      Writes a double to memory 写入 double 到内存

    • getDouble

      public static double getDouble(long address)
      Reads a double from memory 从内存读取 double