Final cleanup for handle encoding

Author: asselyam

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/handles/ObjectHandlesImpl.java

@@ -38,10 +38,7 @@
  * This class implements {@link ObjectHandle word}-sized integer handles that refer to Java objects.
  * {@link #create(Object) Creating}, {@link #get(ObjectHandle) dereferencing} and
  * {@link #destroy(ObjectHandle) destroying} handles is thread-safe and the handles themselves are
- * valid across threads. This class also supports weak handles, with which the referenced object may
- * be garbage-collected, after which {@link #get(ObjectHandle)} returns {@code null}. Still, weak
- * handles must also be {@link #destroyWeak(ObjectHandle) explicitly destroyed} to reclaim their
- * handle value.
+ * valid across threads.
  * <p>
  * The implementation uses a variable number of object arrays, in which each array element
  * represents a handle. The array element's index determines the handle's integer value, and the
@@ -53,8 +50,6 @@
  */
 public final class ObjectHandlesImpl implements ObjectHandles {
 
-    /** Private subclass to distinguish from regular handles to {@link WeakReference} objects. */
-
     private static final int MAX_FIRST_BUCKET_CAPACITY = 1024;
     static { // must be a power of 2 for the arithmetic below to work
         assert Integer.lowestOneBit(MAX_FIRST_BUCKET_CAPACITY) == MAX_FIRST_BUCKET_CAPACITY;

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/jni/JNIObjectHandles.java

@@ -65,7 +65,7 @@
  * </ul>
  */
 public final class JNIObjectHandles {
-    @Fold // replaces with true/false at compile time and removes unnecessary runtime checks
+    @Fold
     static boolean haveAssertions() {
         return RuntimeAssertionsSupport.singleton().desiredAssertionStatus(JNIObjectHandles.class);
     }
@@ -219,6 +219,7 @@ public static void deleteLocalRef(JNIObjectHandle localRef) {
             getOrCreateLocals().delete(decodeLocal(localRef));
         }
     }
+
     // in frames are local handles stored
     public static int pushLocalFrame(int capacity) {
         return getOrCreateLocals().pushFrame(capacity);
@@ -227,6 +228,7 @@ public static int pushLocalFrame(int capacity) {
     public static void popLocalFrame() {
         getExistingLocals().popFrame();
     }
+
     // pops frames down to a specific starting point identified by the int frame
     @Uninterruptible(reason = "Called from uninterruptible code.", mayBeInlined = true)
     public static void popLocalFramesIncluding(int frame) {
@@ -295,6 +297,7 @@ static long computeCurrentGlobalHandleCount() {
 final class JNIGlobalHandles {
     static final SignedWord MIN_VALUE = Word.signed(Long.MIN_VALUE); // -2^63
     static final SignedWord MAX_VALUE = JNIObjectHandles.nullHandle().subtract(1); // -1
+
     static {
         assert JNIObjectHandles.nullHandle().equal(Word.zero());
     }
@@ -311,6 +314,23 @@ final class JNIGlobalHandles {
     // Define the mid-point to split the range in half
     private static final SignedWord HANDLE_RANGE_SPLIT_POINT = Word.signed(1L << 30);
 
+    // Strong global handles will occupy the lower half of the global handles range
+    public static final SignedWord STRONG_GLOBAL_RANGE_MIN = JNIObjectHandles.nullHandle().add(1);
+    ;
+    public static final SignedWord STRONG_GLOBAL_RANGE_MAX = HANDLE_RANGE_SPLIT_POINT.subtract(1);
+
+    // Weak global handles will occupy the upper half of the global handles range
+    public static final SignedWord WEAK_GLOBAL_RANGE_MIN = HANDLE_RANGE_SPLIT_POINT;
+    public static final SignedWord WEAK_GLOBAL_RANGE_MAX = HANDLE_BITS_MASK;
+
+    private static final ObjectHandlesImpl strongGlobalHandles
+            = new ObjectHandlesImpl(STRONG_GLOBAL_RANGE_MIN, STRONG_GLOBAL_RANGE_MAX, JNIObjectHandles.nullHandle());
+    private static final ObjectHandlesImpl weakGlobalHandles
+            = new ObjectHandlesImpl(WEAK_GLOBAL_RANGE_MIN, WEAK_GLOBAL_RANGE_MAX, JNIObjectHandles.nullHandle());
+
+    // Define the mid-point to split the range in half
+    private static final SignedWord HANDLE_RANGE_SPLIT_POINT = Word.signed(1L << 30);
+
     // Strong global handles will occupy the lower half of the global handles range
     public static final SignedWord STRONG_GLOBAL_RANGE_MIN = JNIObjectHandles.nullHandle().add(1);;
     public static final SignedWord STRONG_GLOBAL_RANGE_MAX = HANDLE_RANGE_SPLIT_POINT.subtract(1);
@@ -334,6 +354,19 @@ private static Word isolateHash() {
         return Word.unsigned(isolateHash);
     }
 
+    /**
+     * Encodes a raw {@code ObjectHandle} into a strong {@code JNIObjectHandle}.
+     * * A strong handle guarantees the referenced object remains alive as long as
+     * the handle itself exists.
+     * * The handle is encoded by:
+     * 1. Asserting the handle fits within the available bit range.
+     * 2. Inserting validation bits (derived from the isolate hash) for security.
+     * 3. Setting the Most Significant Bit (MSB, bit 63) to mark it as an encoded handle.
+     * 4. The WEAK_HANDLE_FLAG bit (bit 62) remains 0.
+     *
+     * @param handle The raw, unencoded handle to the Java object.
+     * @return The resulting strong JNI object handle with embedded metadata.
+     */
     private static JNIObjectHandle encodeStrong(ObjectHandle handle) {
         SignedWord h = (Word) handle;
         if (JNIObjectHandles.haveAssertions()) {
@@ -347,34 +380,38 @@ private static JNIObjectHandle encodeStrong(ObjectHandle handle) {
         return (JNIObjectHandle) h;
     }
 
+    /**
+     * Encodes a raw {@code ObjectHandle} into a weak {@code JNIObjectHandle}.
+     * * A weak handle allows the referenced object to be garbage collected even
+     * if the handle exists. The handle will be cleared when the object dies.
+     * * This method calls {@link #encodeStrong(ObjectHandle)} to perform all
+     * common encoding steps, and then explicitly sets the {@code WEAK_HANDLE_FLAG}
+     * bit (bit 62) to mark the handle as weak.
+     *
+     * @param handle The raw, unencoded handle to the Java object.
+     * @return The resulting weak JNI object handle with embedded metadata.
+     */
     private static JNIObjectHandle encodeWeak(ObjectHandle handle) {
-        SignedWord h = (Word) handle;
-        if (JNIObjectHandles.haveAssertions()) {
-            assert h.and(HANDLE_BITS_MASK).equal(h) : "unencoded handle must fit in range";
-            Word v = isolateHash().shiftLeft(VALIDATION_BITS_SHIFT);
-            assert v.and(VALIDATION_BITS_MASK).equal(v) : "validation value must fit in its range";
-            h = h.or(v);
-        }
-        h = h.or(MSB);
-        h = h.or(WEAK_HANDLE_FLAG); // Set bit 62 to mark it as weak
+        SignedWord h = (Word) encodeStrong(handle);
+        h = h.or(WEAK_HANDLE_FLAG);
         assert isInRange((JNIObjectHandle) h);
         return (JNIObjectHandle) h;
     }
 
     private static ObjectHandle decode(JNIObjectHandle handle) {
         assert isInRange(handle);
         assert ((Word) handle).and(VALIDATION_BITS_MASK).unsignedShiftRight(VALIDATION_BITS_SHIFT)
-                        .equal(isolateHash()) : "mismatching validation value -- passed a handle from a different isolate?";
+                .equal(isolateHash()) : "mismatching validation value -- passed a handle from a different isolate?";
         return (ObjectHandle) HANDLE_BITS_MASK.and((Word) handle);
     }
 
     static <T> T getObject(JNIObjectHandle handle) {
         SignedWord handleValue = (Word) handle;
-        if (handleValue.greaterOrEqual(STRONG_GLOBAL_RANGE_MIN) && handleValue.lessOrEqual(STRONG_GLOBAL_RANGE_MAX)) {
+        if ((handleValue.toLong() & WEAK_HANDLE_FLAG.toLong()) == 0) {
             return strongGlobalHandles.get(decode(handle));
         }
 
-        if (handleValue.greaterOrEqual(WEAK_GLOBAL_RANGE_MIN) && handleValue.lessOrEqual(WEAK_GLOBAL_RANGE_MAX)) {
+        if ((handleValue.toLong() & WEAK_HANDLE_FLAG.toLong()) == 1) {
             return weakGlobalHandles.get(decode((handle)));
         }
 
@@ -383,11 +420,11 @@ static <T> T getObject(JNIObjectHandle handle) {
 
     static JNIObjectRefType getHandleType(JNIObjectHandle handle) {
         SignedWord handleValue = (Word) handle;
-        if (handleValue.greaterOrEqual(STRONG_GLOBAL_RANGE_MIN) && handleValue.lessOrEqual(STRONG_GLOBAL_RANGE_MAX)) {
+        if ((handleValue.toLong() & WEAK_HANDLE_FLAG.toLong()) == 0) {
             return JNIObjectRefType.Global;
         }
 
-        if (handleValue.greaterOrEqual(WEAK_GLOBAL_RANGE_MIN) && handleValue.lessOrEqual(WEAK_GLOBAL_RANGE_MAX)) {
+        if ((handleValue.toLong() & WEAK_HANDLE_FLAG.toLong()) == 1) {
             return JNIObjectRefType.WeakGlobal;
         }
         return JNIObjectRefType.Invalid;
@@ -419,7 +456,7 @@ public static long computeCurrentCount() {
  * move and are not garbage-collected, so the handle just contains an object's offset in the image
  * heap. This approach has the major benefit that handles are valid across isolates that are created
  * from the same image, which helps with native code that is unaware of multiple isolates.
- *
+ * <p>
  * Although this type of handle doesn't need explicit management, we still distinguish between
  * local, global and weak-global references by means of a bit pattern in order to comply with the
  * JNI specification (in particular, for function {@code GetObjectRefType}).