[Java.Interop] Add JavaPeerableRegistrationScope

Fixes: #4

Context: #426
Context: a666a6f

Alternate names?

  * JavaScope
  * JavaPeerableCleanupPool
  * JavaPeerCleanup
  * JavaReferenceCleanup
  * JniPeerRegistrationScope

Issue #426 is an idea to implement a *non*-GC-Bridged
`JniRuntime.JniValueManager` type, primarily for use with .NET Core.
This was begun in a666a6f.

What's missing is the answer to a question: what to do about
`JniRuntime.JniValueManager.CollectPeers()`?  With a Mono-style
GC bridge, `CollectPeers()` is `GC.Collect()`.  In a666a6f with
.NET Core, `CollectPeers()` calls `IJavaPeerable.Dispose()` on all
registered instances, which is "extreme".

@jonpryor thought that if there were a *scope-based* way to
selectively control which instances were disposed, that might be
"better" and more understandable.  Plus, this is issue #4!

Which brings us to the background for Issue #4, which touches upon
[bugzilla 25443][0] and [Google issue 37034307][1]: Java.Interop
attempts to provide referential identity for Java objects: if two
separate Java methods invocations return the same Java instance, then
the bindings of those methods should also return the same instance.

This is "fine" on the surface, but has a few related issues:

 1. JNI Global References are a limited resource: Android only allows
    ~52000 JNI Global References to exist, which sounds like a lot,
    but might not be.

 2. Because of (1), it is not uncommon to want to use `using` blocks
    to invoke `IJavaPeerable.Dispose()` to release
    JNI Global References.

 3. However, because of object identity, you could unexpectedly
    introduce *cross-thread sharing* of `IJavaPeerable` instances.
    This might not be at all obvious; for example, in the Android 5
    timeframe, [`Typeface.create()`][2] wouldn't necessarily return
    new Java instances, but may instead return cached instances.

Meaning that this:

	var t1 = new Thread(() => {
	    using var typeface = Typeface.Create("Family", …);
	    // use typeface…
	});
	var t2 = new Thread(() => {
	    using var typeface = Typeface.Create("Family", …);
	    // use typeface…
	});
	t1.Start();
	t2.Start();
	t1.Join();
	t2.Join();

could plausibly result in `ObjectDisposedException`s (or worse), as
the threads could be unexpectedly sharing the same bound instance.

Which *really* means that you can't reliably call `Dispose()`, unless
you *know* you created that instance:

	using var safe      = new Java.Lang.Double(42.0);       // I created this, therefore I control all access and can Dispose() it
	using var unsafe    = Java.Lang.Double.ValueOf(42.0);   // I have no idea who else may be using this instance!

Attempt to address both of these scenarios -- a modicum of .NET Core
support, and additional sanity around JNI Global Reference lifetimes --
by introducing a new `JavaPeerableRegistrationScope` type, which
introduces a scope-based mechanism to control when `IJavaPeerable`
instances are cleaned up:

        public enum JavaPeerableRegistrationScopeCleanup {
            RegisterWithManager,
            Dispose,
            Release,
        }

        public ref struct JavaPeerableRegistrationScope {
            public JavaPeerableRegistrationScope(JavaPeerableRegistrationScopeCleanup cleanup);
            public void Dispose();
        }

`JavaPeerableRegistrationScope` is a [`ref struct`][3], which means
it can only be allocated on the runtime stack, ensuring that cleanup
semantics are *scope* semantics.

TODO: is that actually a good idea?

If a `JavaPeerableRegistrationScope` is created using
`JavaPeerableRegistrationScopeCleanup.RegisterWithManager`, existing
behavior is followed.  This is useful for nested scopes, should
instances need to be registered with `JniRuntime.ValueManager`.

If a `JavaPeerableRegistrationScope` is created using
`JavaPeerableRegistrationScopeCleanup.Dispose` or
`JavaPeerableRegistrationScopeCleanup.Release`, then:

 1. `IJavaPeerable` instances created within the scope are
    "thread-local": they can be *used* by other threads, but
    `JniRuntime.JniValueManager.PeekPeer()` will only find the
    value on the creating thread.

 2. At the end of a `using` block / when
   `JavaPeerableRegistrationScope.Dispose()` is called, all collected
   instances will be `Dispose()`d (with `.Dispose`) or released (with
   `.Release`), and left to the GC to eventually finalize.

For example:

	using (new JavaPeerableRegistrationScope (JavaPeerableRegistrationScopeCleanup.Dispose)) {
	    var singleton = JavaSingleton.Singleton;
	    // use singleton

	    // If other threads attempt to access `JavaSingleton.Singleton`,
	    // they'll create their own peer wrapper
	}
	// `singleton.Dispose()` is called at the end of the `using` block

However, if e.g. the singleton instance is already accessed, then it
won't be added to the registration scope and won't be disposed:

	var singleton = JavaSingleton.Singleton;
	// singleton is registered with the ValueManager

	// later on the same thread or some other threa…
	using (new JavaPeerableRegistrationScope (JavaPeerableRegistrationScopeCleanup.Dispose)) {
	    var anotherSingleton = JavaSingleton.Singleton;
	    // use anotherSingleton…
	}

then `anotherSingleton` will *not* disposed, as it already existed.
*Only newly created instances* are added to the current scope.

By default, only `JavaPeerableRegistrationScopeCleanup.RegisterWithManager`
is supported.  To support the other cleanup modes,
`JniRuntime.JniValueManager.SupportsPeerableRegistrationScopes` must
return `true`, which in turn requires that:

  * `JniRuntime.JniValueManager.AddPeer()` calls
    `TryAddPeerToRegistrationScope()`,
  * `JniRuntime.JniValueManager.RemovePeer()` calls
    `TryRemovePeerFromRegistrationScopes()`
  * `JniRuntime.JniValueManager.PeekPeer()` calls
    `TryPeekPeerFromRegistrationScopes()`.

See `ManagedValueManager` for an example implementation.

Additionally, add the following methods to
`JniRuntime.JniValueManager` to help further assist peer management:

	partial class JniRuntime.JniValueManager {
	    public virtual bool CanCollectPeers { get; }
	    public virtual bool CanReleasePeers { get; }
	    public virtual void ReleasePeers ();
	}

Finally, many of the new members are marked with the
[`[Experimental]` attribute][4], which indicates that an API is
experimental and could change.  In order to use the new APIs,
then the `JI9999` warning must be disabled, e.g. via
[`#pragma warning disable JI9999`][5].  This will allow us to break
API and semantics, should that be necessary.

TODO: docs?

TODO: *nested* scopes, and "bound" vs. "unbound" instance construction
around `JniValueManager.GetValue<T>()` or `.CreateValue<T>()`,
and *why* they should be treated differently.

TODO: Should `CreateValue<T>()` be *removed*?  name implies it always
"creates" a new value, but implementation will return existing instances,
so `GetValue<T>()` alone may be better.  One related difference is that`
`CreateValue<T>()` uses `PeekBoxedObject()`, while `GetValue<T>()` doesn't.
*Should* it?

[0]: https://web.archive.org/web/20211106214514/https://bugzilla.xamarin.com/25/25443/bug.html#c63
[1]: https://issuetracker.google.com/issues/37034307
[2]: https://developer.android.com/reference/android/graphics/Typeface#create(java.lang.String,%20int)
[3]: https://docs.microsoft.com/dotnet/csharp/language-reference/builtin-types/struct#ref-struct
[4]: https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute?view=net-8.0
[5]: https://learn.microsoft.com/dotnet/csharp/language-reference/preprocessor-directives#pragma-warning

Author: jonpryor

src/Java.Interop/Java.Interop/JavaPeerableRegistrationScope.cs

@@ -0,0 +1,35 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Java.Interop {
+	[Experimental ("JI9999")]
+	public enum JavaPeerableRegistrationScopeCleanup {
+		RegisterWithManager,
+		Dispose,
+		Release,
+	}
+
+	[Experimental ("JI9999")]
+	public ref struct JavaPeerableRegistrationScope {
+		PeerableCollection? scope;
+		bool disposed;
+
+		public JavaPeerableRegistrationScope (JavaPeerableRegistrationScopeCleanup cleanup)
+		{
+			scope       = JniEnvironment.CurrentInfo.BeginRegistrationScope (cleanup);
+			disposed    = false;
+		}
+
+		public void Dispose ()
+		{
+			if (disposed) {
+				return;
+			}
+			disposed    = true;
+			JniEnvironment.CurrentInfo.EndRegistrationScope (scope);
+			scope       = null;
+		}
+	}
+}

src/Java.Interop/Java.Interop/JavaProxyObject.cs

@@ -13,7 +13,6 @@ sealed class JavaProxyObject : JavaObject, IEquatable<JavaProxyObject>
 		internal const string JniTypeName = "net/dot/jni/internal/JavaProxyObject";
 
 		static  readonly    JniPeerMembers                                  _members        = new JniPeerMembers (JniTypeName, typeof (JavaProxyObject));
-		static  readonly    ConditionalWeakTable<object, JavaProxyObject>   CachedValues    = new ConditionalWeakTable<object, JavaProxyObject> ();
 
 		[JniAddNativeMethodRegistrationAttribute]
 		static void RegisterNativeMembers (JniNativeMethodRegistrationArguments args)
@@ -29,10 +28,8 @@ public override JniPeerMembers JniPeerMembers {
 			}
 		}
 
-		JavaProxyObject (object value)
+		internal JavaProxyObject (object value)
 		{
-			if (value == null)
-				throw new ArgumentNullException (nameof (value));
 			Value = value;
 		}
 
@@ -57,19 +54,10 @@ public override bool Equals (object? obj)
 			return Value.ToString ();
 		}
 
-		[return: NotNullIfNotNull ("object")]
-		public static JavaProxyObject? GetProxy (object value)
+		protected override void Dispose (bool disposing)
 		{
-			if (value == null)
-				return null;
-
-			lock (CachedValues) {
-				if (CachedValues.TryGetValue (value, out var proxy))
-					return proxy;
-				proxy = new JavaProxyObject (value);
-				CachedValues.Add (value, proxy);
-				return proxy;
-			}
+			base.Dispose (disposing);
+			JniEnvironment.Runtime.ValueManager.RemoveProxy (Value);
 		}
 
 		// TODO: Keep in sync with the code generated by ExportedMemberBuilder

src/Java.Interop/Java.Interop/JniEnvironment.cs

@@ -2,10 +2,13 @@
 
 using System;
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
+using System.Text;
 using System.Threading;
 
 namespace Java.Interop {
@@ -209,6 +212,8 @@ sealed class JniEnvironmentInfo : IDisposable {
 		bool                    disposed;
 		JniRuntime?             runtime;
 
+		List<PeerableCollection?>?          scopes;
+
 		public      int                     LocalReferenceCount     {get; internal set;}
 		public      bool                    WithinNewObjectScope    {get; set;}
 		public      JniRuntime              Runtime {
@@ -243,6 +248,11 @@ public      bool                    IsValid {
 			get {return Runtime != null && environmentPointer != IntPtr.Zero;}
 		}
 
+		public      List<PeerableCollection?>?
+		                                    Scopes => scopes;
+		public      PeerableCollection?     CurrentScope =>
+			scopes == null ? null : scopes [scopes.Count-1];
+
 		public JniEnvironmentInfo ()
 		{
 			Runtime             = JniRuntime.CurrentRuntime;
@@ -293,6 +303,44 @@ public void Dispose ()
 			disposed                = true;
 		}
 
+#pragma warning disable JI9999
+		public PeerableCollection? BeginRegistrationScope (JavaPeerableRegistrationScopeCleanup cleanup)
+		{
+			if (cleanup != JavaPeerableRegistrationScopeCleanup.RegisterWithManager &&
+					!Runtime.ValueManager.SupportsPeerableRegistrationScopes) {
+				throw new NotSupportedException ("Peerable registration scopes are not supported by this runtime.");
+			}
+			scopes ??= new List<PeerableCollection?> ();
+			if (cleanup == JavaPeerableRegistrationScopeCleanup.RegisterWithManager) {
+				scopes.Add (null);
+				return null;
+			}
+			var scope = new PeerableCollection (cleanup);
+			scopes.Add (scope);
+			return scope;
+		}
+
+		public void EndRegistrationScope (PeerableCollection? scope)
+		{
+			Debug.Assert (scopes != null);
+			if (scopes == null) {
+				return;
+			}
+
+			for (int i = scopes.Count; i > 0; --i) {
+				var s = scopes [i - 1];
+				if (s == scope) {
+					scopes.RemoveAt (i - 1);
+					break;
+				}
+			}
+			if (scopes.Count == 0) {
+				scopes = null;
+			}
+			scope?.DisposeScope ();
+		}
+#pragma warning restore JI9999
+
 #if FEATURE_JNIENVIRONMENT_SAFEHANDLES
 		internal    List<List<JniLocalReference>>   LocalReferences = new List<List<JniLocalReference>> () {
 			new List<JniLocalReference> (),
@@ -309,5 +357,82 @@ static unsafe JniEnvironmentInvoker CreateInvoker (IntPtr handle)
 		}
 #endif  // !FEATURE_JNIENVIRONMENT_JI_PINVOKES
 	}
+
+#pragma warning disable JI9999
+	sealed class PeerableCollection : KeyedCollection<int, IJavaPeerable> {
+		public JavaPeerableRegistrationScopeCleanup Cleanup { get; }
+
+		public PeerableCollection (JavaPeerableRegistrationScopeCleanup cleanup)
+		{
+			Cleanup = cleanup;
+		}
+
+		protected override int GetKeyForItem (IJavaPeerable item) => item.JniIdentityHashCode;
+
+		public IJavaPeerable? GetPeerable (JniObjectReference reference, int identityHashCode)
+		{
+			if (!reference.IsValid) {
+				return null;
+			}
+			if (TryGetValue (identityHashCode, out var p) &&
+					JniEnvironment.Types.IsSameObject (reference, p.PeerReference)) {
+				return p;
+			}
+			return null;
+		}
+
+		public void DisposeScope ()
+		{
+			Console.Error.WriteLine ($"# jonp: DisposeScope: {Cleanup}");
+			Debug.Assert (Cleanup != JavaPeerableRegistrationScopeCleanup.RegisterWithManager);
+			switch (Cleanup) {
+				case JavaPeerableRegistrationScopeCleanup.Dispose:
+					List<Exception>?    exceptions = null;
+					foreach (var p in this) {
+						DisposePeer (p, ref exceptions);
+					}
+					Clear ();
+					if (exceptions != null) {
+						throw new AggregateException ("Exceptions while disposing peers.", exceptions);
+					}
+					break;
+				case JavaPeerableRegistrationScopeCleanup.Release:
+					Clear ();
+					break;
+				case JavaPeerableRegistrationScopeCleanup.RegisterWithManager:
+				default:
+					throw new NotSupportedException ($"Unsupported scope cleanup value: {Cleanup}");
+			}
+
+			[SuppressMessage ("Design", "CA1031:Do not catch general exception types",
+					Justification = "Exceptions are bundled into an AggregateException and rethrown")]
+			static void DisposePeer (IJavaPeerable peer, ref List<Exception>? exceptions)
+			{
+				try {
+					Console.Error.WriteLine ($"# jonp: DisposeScope: disposing of: {peer} {peer.PeerReference}");
+					peer.Dispose ();
+				} catch (Exception e) {
+					exceptions ??= new ();
+					exceptions.Add (e);
+					Trace.WriteLine (e);
+				}
+			}
+		}
+
+		public override string ToString ()
+		{
+			var c   = (Collection<IJavaPeerable>) this;
+			var s   = new StringBuilder ();
+			s.Append ("PeerableCollection[").Append (Count).Append ("](");
+			for (int i  = 0; i < Count; ++i ) {
+				s.AppendLine ();
+				var e   = c [i];
+				s.Append ($"  [{i}] hash={e.JniIdentityHashCode} ref={e.PeerReference} type={e.GetType ().ToString ()} value=`{e.ToString ()}`");
+			}
+			s.Append (")");
+			return s.ToString ();
+		}
+	}
+#pragma warning restore JI9999
 }
 

src/Java.Interop/Java.Interop/JniRuntime.JniValueManager.cs

@@ -14,16 +14,41 @@
 
 namespace Java.Interop
 {
+	[Experimental ("JI9999")]
+	[Flags]
+	public enum JniSurfacedPeerLocations {
+		ValueManager    = 1 << 0,
+		CurrentThread   = 1 << 1,
+		AllThreads      = 1 << 2,
+		// Everywhere      = ValueManager | CurrentThread | AllThreads,
+		// Can't add, because PublicAPI analyzers report RS0016 + RS0017
+	}
+
 	public class JniSurfacedPeerInfo {
 
 		public  int                             JniIdentityHashCode     {get; private set;}
 		public  WeakReference<IJavaPeerable>    SurfacedPeer            {get; private set;}
 
+		[Experimental ("JI9999")]
+		public  JniSurfacedPeerLocations        Location                {get; internal set;}
+
 		public JniSurfacedPeerInfo (int jniIdentityHashCode, WeakReference<IJavaPeerable> surfacedPeer)
 		{
 			JniIdentityHashCode     = jniIdentityHashCode;
 			SurfacedPeer            = surfacedPeer;
 		}
+
+		public override string ToString ()
+		{
+#pragma warning disable JI9999
+			if (SurfacedPeer.TryGetTarget (out var target) && target != null) {
+				return $"(JniSurfacedPeerInfo JniIdentityHashCode={JniIdentityHashCode} Location={Location} " +
+					$"SurfacedPeer=({target.GetType ().FullName} {target.PeerReference} {target.ToString ()})" +
+					")";
+			}
+			return $"(JniSurfacedPeerInfo JniIdentityHashCode={JniIdentityHashCode} Location={Location})";
+#pragma warning restore JI9999
+		}
 	}
 
 	partial class JniRuntime
@@ -32,7 +57,7 @@ partial class CreationOptions {
 			public  JniValueManager?        ValueManager                {get; set;}
 		}
 
-		JniValueManager?                    valueManager;
+		internal    JniValueManager?        valueManager;
 		public  JniValueManager             ValueManager                {
 			get => valueManager ?? throw new NotSupportedException ();
 		}
@@ -52,6 +77,8 @@ public abstract partial class JniValueManager : ISetRuntime, IDisposable {
 			internal const DynamicallyAccessedMemberTypes Constructors = DynamicallyAccessedMemberTypes.PublicConstructors | DynamicallyAccessedMemberTypes.NonPublicConstructors;
 			internal const DynamicallyAccessedMemberTypes ConstructorsAndInterfaces = Constructors | DynamicallyAccessedMemberTypes.Interfaces;
 
+			readonly       ConditionalWeakTable<object, JavaProxyObject>   ProxyValues     = new ();
+
 			JniRuntime?             runtime;
 			bool                    disposed;
 			public      JniRuntime  Runtime {
@@ -77,10 +104,19 @@ protected virtual void Dispose (bool disposing)
 				disposed = true;
 			}
 
+			public virtual  bool CanCollectPeers                    => false;
+			public virtual  bool CanReleasePeers                    => false;
+			public virtual  bool SupportsPeerableRegistrationScopes => false;
+
 			public abstract void WaitForGCBridgeProcessing ();
 
 			public abstract void CollectPeers ();
 
+			public virtual void ReleasePeers ()
+			{
+				throw new NotImplementedException ();
+			}
+
 			public abstract void AddPeer (IJavaPeerable value);
 
 			public abstract void RemovePeer (IJavaPeerable value);
@@ -89,6 +125,102 @@ protected virtual void Dispose (bool disposing)
 
 			public abstract List<JniSurfacedPeerInfo>   GetSurfacedPeers ();
 
+			[Experimental ("JI9999")]
+			public List<JniSurfacedPeerInfo> GetRegistrationScopePeers ()
+				=> GetRegistrationScopePeers (JniSurfacedPeerLocations.ValueManager | JniSurfacedPeerLocations.CurrentThread | JniSurfacedPeerLocations.AllThreads);
+
+			[Experimental ("JI9999")]
+			public List<JniSurfacedPeerInfo> GetRegistrationScopePeers (JniSurfacedPeerLocations locations)
+			{
+				List<JniSurfacedPeerInfo>? peers = null;
+				if (locations.HasFlag (JniSurfacedPeerLocations.ValueManager)) {
+					peers = GetSurfacedPeers ();
+					for (int i = 0; i < peers.Count; ++i) {
+						peers [i].Location  = JniSurfacedPeerLocations.ValueManager;
+					}
+				}
+				peers ??= new ();
+				return AddRegistrationScopePeers (peers, locations);
+			}
+
+			[Experimental ("JI9999")]
+			protected List<JniSurfacedPeerInfo> AddRegistrationScopePeers (List<JniSurfacedPeerInfo> peers, JniSurfacedPeerLocations locations)
+			{
+				if (locations.HasFlag (JniSurfacedPeerLocations.CurrentThread)) {
+					AddPeers (JniEnvironment.CurrentInfo.Scopes, JniSurfacedPeerLocations.CurrentThread);
+				}
+				if (locations.HasFlag (JniSurfacedPeerLocations.AllThreads)) {
+					var skipCurrentThread = locations.HasFlag (JniSurfacedPeerLocations.CurrentThread);
+					foreach (var info in JniEnvironment.Info.Values) {
+						if (skipCurrentThread && info == JniEnvironment.CurrentInfo) {
+							continue;
+						}
+						AddPeers (info.Scopes, JniSurfacedPeerLocations.AllThreads);
+					}
+				}
+
+				return peers;
+
+				void AddPeers (List<PeerableCollection?>? scopes, JniSurfacedPeerLocations location)
+				{
+					if (scopes == null)
+						return;
+
+					foreach (var scope in scopes) {
+						if (scope == null) {
+							continue;
+						}
+						foreach (var p in scope) {
+							var info = new JniSurfacedPeerInfo (p.JniIdentityHashCode, CreateWeakReference (p)) {
+								Location    = location,
+							};
+							peers.Add (info);
+						}
+					}
+				}
+			}
+
+			protected static WeakReference<IJavaPeerable> CreateWeakReference (IJavaPeerable peer) =>
+				new WeakReference<IJavaPeerable> (peer, trackResurrection: true);
+
+
+#pragma warning disable JI9999
+			[Experimental ("JI9999")]
+			protected bool TryAddPeerToRegistrationScope (IJavaPeerable value)
+			{
+				var scope   = JniEnvironment.CurrentInfo.CurrentScope;
+				if (scope == null) {
+					return false;
+				}
+				scope.Add (value);
+				return true;
+			}
+
+			[Experimental ("JI9999")]
+			protected bool TryRemovePeerFromRegistrationScopes (IJavaPeerable value)
+			{
+				var scopes  = JniEnvironment.CurrentInfo.Scopes;
+				if (scopes == null) {
+					return false;
+				}
+				for (int i = scopes.Count - 1; i >= 0; --i) {
+					var scope = scopes [i];
+					if (scope == null) {
+						continue;
+					}
+					if (!scope.Contains (value.JniIdentityHashCode)) {
+						continue;
+					}
+					if (scope.TryGetValue (value.JniIdentityHashCode, out var peer) &&
+							object.ReferenceEquals (peer, value)) {
+						scope.Remove (value);
+						return true;
+					}
+				}
+				return false;
+			}
+#pragma warning restore JI9999
+
 			public abstract void ActivatePeer (IJavaPeerable? self, JniObjectReference reference, ConstructorInfo cinfo, object? []? argumentValues);
 
 			public void ConstructPeer (IJavaPeerable peer, ref JniObjectReference reference, JniObjectReferenceOptions options)
@@ -210,6 +342,28 @@ public virtual void DisposePeerUnlessReferenced (IJavaPeerable value)
 
 			public abstract IJavaPeerable? PeekPeer (JniObjectReference reference);
 
+#pragma warning disable JI9999
+			[Experimental ("JI9999")]
+			protected IJavaPeerable? TryPeekPeerFromRegistrationScopes (JniObjectReference reference, int identityHashCode)
+			{
+				var scopes  = JniEnvironment.CurrentInfo.Scopes;
+				if (scopes == null) {
+					return null;
+				}
+				for (int i = scopes.Count - 1; i >= 0; --i) {
+					var scope = scopes [i];
+					if (scope == null) {
+						continue;
+					}
+					var peer    = scope.GetPeerable (reference, identityHashCode);
+					if (peer != null) {
+						return peer;
+					}
+				}
+				return null;
+			}
+#pragma warning restore JI9999
+
 			public object? PeekValue (JniObjectReference reference)
 			{
 				if (disposed)
@@ -712,6 +866,29 @@ protected virtual JniValueMarshaler GetValueMarshalerCore (Type type)
 			{
 				return ProxyValueMarshaler.Instance;
 			}
+
+
+			[return: NotNullIfNotNull ("value")]
+			internal JavaProxyObject? GetProxy (object? value)
+			{
+				if (value == null)
+					return null;
+
+				lock (ProxyValues) {
+					if (ProxyValues.TryGetValue (value, out var proxy))
+						return proxy;
+					proxy = new JavaProxyObject (value);
+					ProxyValues.Add (value, proxy);
+					return proxy;
+				}
+			}
+
+			internal void RemoveProxy (object value)
+			{
+				lock (ProxyValues) {
+					ProxyValues.Remove (value);
+				}
+			}
 		}
 	}
 
@@ -927,8 +1104,8 @@ public override JniValueMarshalerState CreateGenericObjectReferenceArgumentState
 				return new JniValueMarshalerState (s, vm);
 			}
 
-			var p   = JavaProxyObject.GetProxy (value);
-			return new JniValueMarshalerState (p!.PeerReference.NewLocalRef ());
+			var p   = JniRuntime.CurrentRuntime.ValueManager.GetProxy (value);
+			return new JniValueMarshalerState (p.PeerReference.NewLocalRef ());
 		}
 
 		public override void DestroyGenericArgumentState (object? value, ref JniValueMarshalerState state, ParameterAttributes synchronize)

src/Java.Interop/PublicAPI.Unshipped.txt

@@ -1,3 +1,29 @@
 #nullable enable
 static Java.Interop.JavaPeerableExtensions.TryJavaCast<TResult>(this Java.Interop.IJavaPeerable? self, out TResult? result) -> bool
 static Java.Interop.JavaPeerableExtensions.JavaAs<TResult>(this Java.Interop.IJavaPeerable? self) -> TResult?
+Java.Interop.JavaPeerableRegistrationScope
+Java.Interop.JavaPeerableRegistrationScope.JavaPeerableRegistrationScope() -> void
+Java.Interop.JavaPeerableRegistrationScope.JavaPeerableRegistrationScope(Java.Interop.JavaPeerableRegistrationScopeCleanup cleanup) -> void
+Java.Interop.JavaPeerableRegistrationScope.Dispose() -> void
+Java.Interop.JavaPeerableRegistrationScopeCleanup
+Java.Interop.JavaPeerableRegistrationScopeCleanup.Dispose = 1 -> Java.Interop.JavaPeerableRegistrationScopeCleanup
+Java.Interop.JavaPeerableRegistrationScopeCleanup.RegisterWithManager = 0 -> Java.Interop.JavaPeerableRegistrationScopeCleanup
+Java.Interop.JavaPeerableRegistrationScopeCleanup.Release = 2 -> Java.Interop.JavaPeerableRegistrationScopeCleanup
+Java.Interop.JniSurfacedPeerLocations
+Java.Interop.JniSurfacedPeerLocations.AllThreads = 4 -> Java.Interop.JniSurfacedPeerLocations
+Java.Interop.JniSurfacedPeerLocations.CurrentThread = 2 -> Java.Interop.JniSurfacedPeerLocations
+Java.Interop.JniSurfacedPeerLocations.ValueManager = 1 -> Java.Interop.JniSurfacedPeerLocations
+*REMOVED* Java.Interop.JniSurfacedPeerLocations.Everywhere = Java.Interop.JniSurfacedPeerLocations.AllThreads | Java.Interop.JniSurfacedPeerLocations.CurrentThread | Java.Interop.JniSurfacedPeerLocations.ValueManager -> Java.Interop.JniSurfacedPeerLocations
+Java.Interop.JniRuntime.JniValueManager.AddRegistrationScopePeers(System.Collections.Generic.List<Java.Interop.JniSurfacedPeerInfo!>! peers, Java.Interop.JniSurfacedPeerLocations locations) -> System.Collections.Generic.List<Java.Interop.JniSurfacedPeerInfo!>!
+Java.Interop.JniRuntime.JniValueManager.GetRegistrationScopePeers() -> System.Collections.Generic.List<Java.Interop.JniSurfacedPeerInfo!>!
+Java.Interop.JniRuntime.JniValueManager.GetRegistrationScopePeers(Java.Interop.JniSurfacedPeerLocations locations) -> System.Collections.Generic.List<Java.Interop.JniSurfacedPeerInfo!>!
+Java.Interop.JniRuntime.JniValueManager.TryAddPeerToRegistrationScope(Java.Interop.IJavaPeerable! value) -> bool
+Java.Interop.JniRuntime.JniValueManager.TryPeekPeerFromRegistrationScopes(Java.Interop.JniObjectReference reference, int identityHashCode) -> Java.Interop.IJavaPeerable?
+Java.Interop.JniRuntime.JniValueManager.TryRemovePeerFromRegistrationScopes(Java.Interop.IJavaPeerable! value) -> bool
+static Java.Interop.JniRuntime.JniValueManager.CreateWeakReference(Java.Interop.IJavaPeerable! peer) -> System.WeakReference<Java.Interop.IJavaPeerable!>!
+virtual Java.Interop.JniRuntime.JniValueManager.CanCollectPeers.get -> bool
+virtual Java.Interop.JniRuntime.JniValueManager.CanReleasePeers.get -> bool
+virtual Java.Interop.JniRuntime.JniValueManager.ReleasePeers() -> void
+virtual Java.Interop.JniRuntime.JniValueManager.SupportsPeerableRegistrationScopes.get -> bool
+Java.Interop.JniSurfacedPeerInfo.Location.get -> Java.Interop.JniSurfacedPeerLocations
+override Java.Interop.JniSurfacedPeerInfo.ToString() -> string!

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

@@ -19,35 +19,31 @@ public override void WaitForGCBridgeProcessing ()
 		{
 		}
 
+		public override bool CanCollectPeers => false;
+		public override bool CanReleasePeers => true;
+
 		public override void CollectPeers ()
+		{
+			if (RegisteredInstances == null)
+				throw new ObjectDisposedException (nameof (ManagedValueManager));
+
+			throw new NotSupportedException ();
+		}
+
+		public override void ReleasePeers ()
 		{
 			if (RegisteredInstances == null)
 				throw new ObjectDisposedException (nameof (ManagedValueManager));
 
 			var peers = new List<IJavaPeerable> ();
 
 			lock (RegisteredInstances) {
-				foreach (var ps in RegisteredInstances.Values) {
-					foreach (var p in ps) {
-						peers.Add (p);
-					}
-				}
 				RegisteredInstances.Clear ();
 			}
-			List<Exception>? exceptions = null;
-			foreach (var peer in peers) {
-				try {
-					peer.Dispose ();
-				}
-				catch (Exception e) {
-					exceptions = exceptions ?? new List<Exception> ();
-					exceptions.Add (e);
-				}
-			}
-			if (exceptions != null)
-				throw new AggregateException ("Exceptions while collecting peers.", exceptions);
 		}
 
+		public override bool SupportsPeerableRegistrationScopes => true;
+
 		public override void AddPeer (IJavaPeerable value)
 		{
 			if (RegisteredInstances == null)
@@ -64,6 +60,13 @@ public override void AddPeer (IJavaPeerable value)
 				value.SetPeerReference (r.NewGlobalRef ());
 				JniObjectReference.Dispose (ref r, JniObjectReferenceOptions.CopyAndDispose);
 			}
+
+#pragma warning disable JI9999
+			if (TryAddPeerToRegistrationScope (value)) {
+				return;
+			}
+#pragma warning restore JI9999
+
 			int key = value.JniIdentityHashCode;
 			lock (RegisteredInstances) {
 				List<IJavaPeerable>? peers;
@@ -120,9 +123,16 @@ void WarnNotReplacing (int key, IJavaPeerable ignoreValue, IJavaPeerable keepVal
 
 			if (!reference.IsValid)
 				return null;
-
+			
 			int key = GetJniIdentityHashCode (reference);
 
+#pragma warning disable JI9999
+			var peer = TryPeekPeerFromRegistrationScopes (reference, key);
+			if (peer != null) {
+				return peer;
+			}
+#pragma warning restore JI9999
+
 			lock (RegisteredInstances) {
 				List<IJavaPeerable>? peers;
 				if (!RegisteredInstances.TryGetValue (key, out peers))
@@ -147,6 +157,12 @@ public override void RemovePeer (IJavaPeerable value)
 			if (value == null)
 				throw new ArgumentNullException (nameof (value));
 
+#pragma warning disable JI9999
+			if (TryRemovePeerFromRegistrationScopes (value)) {
+				return;
+			}
+#pragma warning restore JI9999
+
 			int key = value.JniIdentityHashCode;
 			lock (RegisteredInstances) {
 				List<IJavaPeerable>? peers;
@@ -248,7 +264,7 @@ public override List<JniSurfacedPeerInfo> GetSurfacedPeers ()
 				var peers = new List<JniSurfacedPeerInfo> (RegisteredInstances.Count);
 				foreach (var e in RegisteredInstances) {
 					foreach (var p in e.Value) {
-						peers.Add (new JniSurfacedPeerInfo (e.Key, new WeakReference<IJavaPeerable> (p)));
+						peers.Add (new JniSurfacedPeerInfo (e.Key, CreateWeakReference (p)));
 					}
 				}
 				return peers;

tests/Java.Interop-Tests/Java.Interop-Tests.csproj

@@ -3,6 +3,8 @@
   <PropertyGroup>
     <TargetFramework>$(DotNetTargetFramework)</TargetFramework>
     <IsPackable>false</IsPackable>
+    <SignAssembly>true</SignAssembly>
+    <AssemblyOriginatorKeyFile>..\..\product.snk</AssemblyOriginatorKeyFile>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <DefineConstants>$(DefineConstants);NO_MARSHAL_MEMBER_BUILDER_SUPPORT;NO_GC_BRIDGE_SUPPORT</DefineConstants>
   </PropertyGroup>
@@ -50,6 +52,7 @@
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\AndroidInterface.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\DesugarAndroidInterface$_CC.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\SelfRegistration.java" />
+    <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\Singleton.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\TestType.java" />
   </ItemGroup>
 

tests/Java.Interop-Tests/Java.Interop/JavaManagedGCBridgeTests.cs

@@ -15,6 +15,9 @@ public class JavaManagedGCBridgeTests : JavaVMFixture {
 		[Test]
 		public void CrossReferences ()
 		{
+			if (!JniEnvironment.Runtime.ValueManager.CanCollectPeers) {
+				Assert.Ignore ();
+			}
 			using (var array = new JavaObjectArray<CrossReferenceBridge> (2)) {
 				WeakReference<CrossReferenceBridge> root = null, child = null;
 				var t = new Thread (() => SetupLinks (array, out root, out child));

tests/Java.Interop-Tests/Java.Interop/JavaObjectTest.cs

@@ -240,7 +240,7 @@ protected override void Dispose (bool disposing)
 	class MyDisposableObject : JavaObject {
 		internal    const   string  JniTypeName = "net/dot/jni/test/MyDisposableObject";
 
-		bool _isDisposed;
+		internal bool _isDisposed;
 
 		public MyDisposableObject ()
 		{

tests/Java.Interop-Tests/Java.Interop/JavaSingleton.cs

@@ -0,0 +1,38 @@
+using System;
+
+using Java.Interop;
+
+namespace Java.InteropTests
+{
+	[JniTypeSignature (JavaSingleton.JniTypeName, GenerateJavaPeer=false)]
+	public sealed class JavaSingleton : JavaObject
+	{
+		internal const string JniTypeName = "net/dot/jni/test/Singleton";
+
+		readonly static JniPeerMembers _members = new JniPeerMembers (JniTypeName, typeof (JavaSingleton));
+
+		public override JniPeerMembers JniPeerMembers {
+			get {return _members;}
+		}
+
+		public  bool    disposed;
+
+		internal JavaSingleton (ref JniObjectReference reference, JniObjectReferenceOptions options)
+			: base (ref reference, options)
+		{
+		}
+
+		protected override void Dispose (bool disposing)
+		{
+			disposed    = disposed || disposing;
+			base.Dispose (disposing);
+		}
+
+		public static unsafe JavaSingleton Singleton {
+			get {
+				var o   = _members.StaticMethods.InvokeObjectMethod ("getSingleton.()Lnet/dot/jni/test/Singleton;", null);
+				return JniEnvironment.Runtime.ValueManager.GetValue<JavaSingleton> (ref o, JniObjectReferenceOptions.CopyAndDispose);
+			}
+		}
+	}
+}

tests/Java.Interop-Tests/Java.Interop/JniRuntimeJniValueManagerContract.cs

@@ -0,0 +1,13 @@
+package net.dot.jni.test;
+
+public final class Singleton {
+
+	static final Singleton singleton = new Singleton ();
+
+	private Singleton() {
+	}
+
+	public static Singleton getSingleton() {
+		return singleton;
+	}
+}