[Java.Interop] JNI handles are now in a "control block"

Originally from: #1334
Context: dotnet/runtime#114184
Context: dotnet/android#10125
Context: dotnet/android#10125 (comment)

Part of adding a GC bridge to CoreCLR are the new APIs:

	namespace System.Runtime.InteropServices.Java;
	public struct ComponentCrossReference {
	    public nint SourceGroupIndex, DestinationGroupIndex;
	}
	public unsafe struct StronglyConnectedComponent {
	    public nint Count;
	    public IntPtr* Context;
	}
	public static partial class JavaMarshal {
	    public static unsafe void Initialize(
	        delegate* unmanaged<
	            System.IntPtr,                  // sccsLen
	            StronglyConnectedComponent*,    // sccs
	            System.IntPtr,                  // ccrsLen
	            ComponentCrossReference*,       // ccrs
	            void> markCrossReferences);
	    public static GCHandle CreateReferenceTrackingHandle(object obj, IntPtr context);
	    public static IntPtr GetContext(GCHandle obj);
	}

Of note is the "data flow" of `context`:

  * `JavaMarshal.CreateReferenceTrackingHandle()` has a "`context`"
    parameter.

  * The `context` parameter to
    `JavaMarshal.CreateReferenceTrackingHandle()` is the return value
    of `JavaMarshal.GetContext()`

  * The `context` parameter to
    `JavaMarshal.CreateReferenceTrackingHandle()` is stored within
    `StronglyConnectedComponent.Context`.

  * The `markCrossReferences` parameter of `JavaMarshal.Initialize()`
    is called by the GC bridge and given a native array of
    `StronglyConnectedComponent` instances, which contains `Context`.

The short of it is that the proposed GC bridge doesn't contain direct
access to the `IJavaPeerable` instances in play.  Instead, it has
access to "context" which must contain the JNI Object Reference
information that the `markCrossReferences` callback needs access to.

Furthermore, the `context` pointer value *cannot change*, i.e. it
needs to be a native pointer value a'la **malloc**(3), ***not*** a
value which can be moved by the GC.  (The *contents* can change; the
pointer value cannot.))

While we're still prototyping this, what we currently believe we need
is the JNI object reference, JNI object reference type, and (maybe?)
the JNI Weak Global Reference value and "refs added" values.

Update `IJavaPeerable` to add a `JniObjectReferenceControlBlock`
property which can be used as the `context` parameter:

	partial interface IJavaPeerable {
	    IntPtr JniObjectReferenceControlBlock => 0;
	}

This supports usage of:

	IJavaPeerable   value   = …
	GCHandle        handle  = JavaMarshal.CreateReferenceTrackingHandle(
	    value,
	    value.JniObjectReferenceControlBlock
	);

It works!

Build:

	dotnet build -c Release -p:DotNetTargetFramework=net8.0 -t:Prepare
	dotnet build -c Release -p:DotNetTargetFramework=net8.0
	dotnet publish --self-contained -p:UseMonoRuntime=true -p:DotNetTargetFramework=net8.0 \
	  -p:UseAppHost=true -p:ErrorOnDuplicatePublishOutputFiles=false \
	  samples/Hello-Java.Base/Hello-Java.Base.csproj -r osx-x64

Run:

	JAVA_INTEROP_GREF_LOG=g.txt  ./samples/Hello-Java.Base/bin/Release/osx-x64/publish/Hello-Java.Base

`g.txt` contains:

	…
	*take_weak obj=0x10560dc70; handle=0x7f7f42f15148
	+w+ grefc 8 gwrefc 1 obj-handle 0x7f7f42f15148/G -> new-handle 0x7f7f43008401/W from thread '(null)'(1)
	take_weak_global_ref_jni
	-g- grefc 7 gwrefc 1 handle 0x7f7f42f15148/G from thread '(null)'(1)
	take_weak_global_ref_jni
	*try_take_global obj=0x10560dc70 -> wref=0x7f7f43008401 handle=0x0
	-w- grefc 7 gwrefc 0 handle 0x7f7f43008401/W from thread '(null)'(1)
	take_global_ref_jni
	Finalizing PeerReference=0x0/G IdentityHashCode=0x70dea4e Instance=0x59b98e2b Instance.Type=Hello.MyJLO

Implement MonoVM BC Bridge :: Java Marshaling API "thunk"

Commit 9e9daf4 suggested that we could
probably "thunk" the MonoVM API to implement the proposed
Java Bridge API..

Implemented the thunk!

Author: jonpryor

src/Java.Interop/Java.Interop/IJavaPeerable.cs

@@ -37,6 +37,8 @@ public interface IJavaPeerable : IDisposable
 		void    Disposed ();
 		/// <include file="../Documentation/Java.Interop/IJavaPeerable.xml" path="/docs/member[@name='M:Finalized']/*" />
 		void    Finalized ();
+
+		IntPtr  JniObjectReferenceControlBlock  => IntPtr.Zero;
 	}
 }
 

src/Java.Interop/Java.Interop/JavaException.cs

@@ -18,13 +18,7 @@ unsafe public class JavaException : Exception, IJavaPeerable
 		JniObjectReference  reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-		IntPtr                  handle;
-		JniObjectReferenceType  handle_type;
-	#pragma warning disable 0169
-		// Used by JavaInteropGCBridge
-		IntPtr                  weak_handle;
-		int                     refs_added;
-	#pragma warning restore 0169
+		unsafe  JniObjectReferenceControlBlock* jniObjectReferenceControlBlock;
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 
 		protected   static  readonly    JniObjectReference*     InvalidJniObjectReference = null;
@@ -106,7 +100,11 @@ public          JniObjectReference          PeerReference {
 				return reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-				return new JniObjectReference (handle, handle_type);
+				var c = jniObjectReferenceControlBlock;
+				if (c == null) {
+					return default;
+				}
+				return new JniObjectReference (c->handle, (JniObjectReferenceType) c->handle_type);
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 			}
 		}
@@ -137,8 +135,13 @@ protected void SetPeerReference (ref JniObjectReference reference, JniObjectRefe
 			this.reference      = reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-			this.handle         = reference.Handle;
-			this.handle_type    = reference.Type;
+			var c   = jniObjectReferenceControlBlock;
+			if (c == null) {
+				c   = jniObjectReferenceControlBlock    =
+					Java.Interop.JniObjectReferenceControlBlock.Alloc ();
+			}
+			c->handle       = reference.Handle;
+			c->handle_type  = (int) reference.Type;
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 
 			JniObjectReference.Dispose (ref reference, options);
@@ -167,6 +170,9 @@ protected virtual void Dispose (bool disposing)
 			if (inner != null) {
 				inner.Dispose ();
 			}
+#if FEATURE_JNIOBJECTREFERENCE_INTPTRS
+			Java.Interop.JniObjectReferenceControlBlock.Free (ref jniObjectReferenceControlBlock);
+#endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 		}
 
 		public override bool Equals (object? obj)
@@ -282,6 +288,9 @@ void IJavaPeerable.SetPeerReference (JniObjectReference reference)
 		{
 			SetPeerReference (ref reference, JniObjectReferenceOptions.Copy);
 		}
+
+		IntPtr IJavaPeerable.JniObjectReferenceControlBlock =>
+			(IntPtr) jniObjectReferenceControlBlock;
 	}
 }
 

src/Java.Interop/Java.Interop/JavaObject.cs

@@ -25,13 +25,7 @@ unsafe public class JavaObject : IJavaPeerable
 		[NonSerialized] JniObjectReference  reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-		[NonSerialized] IntPtr                  handle;
-		[NonSerialized] JniObjectReferenceType  handle_type;
-	#pragma warning disable 0169
-		// Used by JavaInteropGCBridge
-		[NonSerialized] IntPtr                  weak_handle;
-		[NonSerialized] int                     refs_added;
-	#pragma warning restore 0169
+		unsafe  JniObjectReferenceControlBlock* jniObjectReferenceControlBlock;
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 
 		protected   static  readonly    JniObjectReference*     InvalidJniObjectReference  = null;
@@ -41,13 +35,17 @@ unsafe public class JavaObject : IJavaPeerable
 			JniEnvironment.Runtime.ValueManager.FinalizePeer (this);
 		}
 
-		public          JniObjectReference          PeerReference {
+		public  unsafe  JniObjectReference          PeerReference {
 			get {
 #if FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 				return reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-				return new JniObjectReference (handle, handle_type);
+				var c = jniObjectReferenceControlBlock;
+				if (c == null) {
+					return default;
+				}
+				return new JniObjectReference (c->handle, (JniObjectReferenceType) c->handle_type);
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 			}
 		}
@@ -92,8 +90,13 @@ protected void SetPeerReference (ref JniObjectReference reference, JniObjectRefe
 			this.reference      = reference;
 #endif  // FEATURE_JNIOBJECTREFERENCE_SAFEHANDLES
 #if FEATURE_JNIOBJECTREFERENCE_INTPTRS
-			this.handle         = reference.Handle;
-			this.handle_type    = reference.Type;
+			var c   = jniObjectReferenceControlBlock;
+			if (c == null) {
+				c   = jniObjectReferenceControlBlock    =
+					Java.Interop.JniObjectReferenceControlBlock.Alloc ();
+			}
+			c->handle       = reference.Handle;
+			c->handle_type  = (int) reference.Type;
 #endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 
 			JniObjectReference.Dispose (ref reference, options);
@@ -118,6 +121,9 @@ public virtual void DisposeUnlessReferenced ()
 
 		protected virtual void Dispose (bool disposing)
 		{
+#if FEATURE_JNIOBJECTREFERENCE_INTPTRS
+			Java.Interop.JniObjectReferenceControlBlock.Free (ref jniObjectReferenceControlBlock);
+#endif  // FEATURE_JNIOBJECTREFERENCE_INTPTRS
 		}
 
 		public override bool Equals (object? obj)
@@ -170,6 +176,9 @@ void IJavaPeerable.SetPeerReference (JniObjectReference reference)
 		{
 			SetPeerReference (ref reference, JniObjectReferenceOptions.Copy);
 		}
+
+		IntPtr IJavaPeerable.JniObjectReferenceControlBlock =>
+			(IntPtr) jniObjectReferenceControlBlock;
 	}
 }
 

src/Java.Interop/Java.Interop/JniObjectReferenceControlBlock.cs

@@ -0,0 +1,27 @@
+using System;
+using System.Runtime.InteropServices;
+
+namespace Java.Interop;
+
+internal struct JniObjectReferenceControlBlock {
+	public	IntPtr  handle;
+	public  int     handle_type;
+	public  IntPtr  weak_handle;
+	public  int     refs_added;
+
+	public  static  readonly    int Size    = Marshal.SizeOf<JniObjectReferenceControlBlock>();
+
+	public static unsafe JniObjectReferenceControlBlock* Alloc ()
+	{
+		return (JniObjectReferenceControlBlock*) NativeMemory.AllocZeroed (1, (uint) Size);
+	}
+
+	public static unsafe void Free (ref JniObjectReferenceControlBlock* value)
+	{
+		if (value == null) {
+			return;
+		}
+		NativeMemory.Free (value);
+		value   = null;
+	}
+}

src/Java.Interop/PublicAPI.Unshipped.txt

@@ -11,3 +11,4 @@ Java.Interop.JniRuntime.JniTypeManager.GetInvokerType(System.Type! type) -> Syst
 Java.Interop.JniRuntime.JniValueManager.GetPeer(Java.Interop.JniObjectReference reference, System.Type? targetType = null) -> Java.Interop.IJavaPeerable?
 Java.Interop.JniTypeSignatureAttribute.InvokerType.get -> System.Type?
 Java.Interop.JniTypeSignatureAttribute.InvokerType.set -> void
+Java.Interop.IJavaPeerable.JniObjectReferenceControlBlock.get -> nint

src/Java.Runtime.Environment/Java.Interop/MonoRuntimeValueManager.cs

@@ -415,6 +415,18 @@ partial class JreNativeMethods {
 
 		[DllImport (JavaInteropLib, CallingConvention=CallingConvention.Cdecl)]
 		internal static extern void java_interop_gc_bridge_wait_for_bridge_processing (IntPtr bridge);
+
+		[DllImport (JavaInteropLib, CallingConvention=CallingConvention.Cdecl)]
+		internal static extern unsafe int java_interop_gc_bridge_set_mark_cross_references (
+				IntPtr bridge,
+				delegate* unmanaged[Cdecl]<System.Runtime.InteropServices.Java.MarkCrossReferences*, void> markCrossReferences
+		);
+
+		[DllImport (JavaInteropLib, CallingConvention=CallingConvention.Cdecl)]
+		internal static extern unsafe int java_interop_gc_bridge_release_mark_cross_references_resources (
+				IntPtr bridge,
+				System.Runtime.InteropServices.Java.MarkCrossReferences* crossReferences
+		);
 	}
 
 	sealed class OverrideStackTrace : Exception {