Introduce ByRefLikeReferenceUnsafe and use it in generated code

By it's nature Unsafe methods are not a part of the "client" API,
so we just provide it on a side and should no longer hide methods/constructors
from user. Also unsafe API is internal on the original class, so it's not immediately
visible to the users.

Author: zvirja

ref/Castle.Core-net8.0.cs

@@ -2424,13 +2424,20 @@ public virtual bool ShouldInterceptMethod(System.Type type, System.Reflection.Me
     }
     public class ByRefLikeReference
     {
-        [System.CLSCompliant(false)]
-        public ByRefLikeReference(System.Type type, void* ptr, bool valueIsScoped) { }
         public bool ValueIsScoped { get; }
+    }
+    public static class ByRefLikeReferenceUnsafe
+    {
+        [System.CLSCompliant(false)]
+        public static unsafe Castle.DynamicProxy.ByRefLikeReference CreateByRefLikeReferenceUntyped(System.Type type, void* ptr, bool valueIsScoped) { }
         [System.CLSCompliant(false)]
-        public unsafe void* GetPtr(System.Type checkType) { }
+        public static unsafe Castle.DynamicProxy.ReadOnlySpanReference<T> CreateReadOnlySpanReference<T>(System.Type type, void* ptr, bool valueIsScoped) { }
         [System.CLSCompliant(false)]
-        public unsafe void Invalidate(void* checkPtr) { }
+        public static unsafe Castle.DynamicProxy.SpanReference<T> CreateSpanReference<T>(System.Type type, void* ptr, bool valueIsScoped) { }
+        [System.CLSCompliant(false)]
+        public static unsafe void DisposeReference(Castle.DynamicProxy.ByRefLikeReference reference, void* expectedPtr) { }
+        [System.CLSCompliant(false)]
+        public static unsafe void* GetRawPtr(Castle.DynamicProxy.ByRefLikeReference reference, System.Type expectedType) { }
     }
     public class CustomAttributeInfo : System.IEquatable<Castle.DynamicProxy.CustomAttributeInfo>
     {
@@ -2702,8 +2709,6 @@ public static bool IsProxyType(System.Type type) { }
     }
     public class ReadOnlySpanReference<T> : Castle.DynamicProxy.ByRefLikeReference
     {
-        [System.CLSCompliant(false)]
-        public ReadOnlySpanReference(System.Type type, void* ptr, bool valueIsScoped) { }
         public System.ReadOnlySpan<T> GetValue() { }
         public void SetValue(Castle.DynamicProxy.ReadOnlySpanReference<T>.ValueGetter valueGetter) { }
         public void UseValue(Castle.DynamicProxy.ReadOnlySpanReference<T>.ValueConsumer valueConsumer) { }
@@ -2714,8 +2719,6 @@ public TResult UseValue<TResult>(Castle.DynamicProxy.ReadOnlySpanReference<T>.Va
     }
     public class SpanReference<T> : Castle.DynamicProxy.ByRefLikeReference
     {
-        [System.CLSCompliant(false)]
-        public SpanReference(System.Type type, void* ptr, bool valueIsScoped) { }
         public System.Span<T> GetValue() { }
         public void SetValue(Castle.DynamicProxy.SpanReference<T>.ValueGetter valueGetter) { }
         public void UseValue(Castle.DynamicProxy.SpanReference<T>.ValueConsumer valueConsumer) { }

ref/Castle.Core-net9.0.cs

@@ -2424,19 +2424,27 @@ public virtual bool ShouldInterceptMethod(System.Type type, System.Reflection.Me
     }
     public class ByRefLikeReference
     {
-        [System.CLSCompliant(false)]
-        public ByRefLikeReference(System.Type type, void* ptr, bool valueIsScoped) { }
         public bool ValueIsScoped { get; }
+    }
+    public static class ByRefLikeReferenceUnsafe
+    {
+        [System.CLSCompliant(false)]
+        public static unsafe Castle.DynamicProxy.ByRefLikeReference<TByRefLike> CreateByRefLikeReference<TByRefLike>(System.Type type, void* ptr, bool valueIsScoped)
+            where TByRefLike :  struct { }
+        [System.CLSCompliant(false)]
+        public static unsafe Castle.DynamicProxy.ByRefLikeReference CreateByRefLikeReferenceUntyped(System.Type type, void* ptr, bool valueIsScoped) { }
+        [System.CLSCompliant(false)]
+        public static unsafe Castle.DynamicProxy.ReadOnlySpanReference<T> CreateReadOnlySpanReference<T>(System.Type type, void* ptr, bool valueIsScoped) { }
+        [System.CLSCompliant(false)]
+        public static unsafe Castle.DynamicProxy.SpanReference<T> CreateSpanReference<T>(System.Type type, void* ptr, bool valueIsScoped) { }
         [System.CLSCompliant(false)]
-        public unsafe void* GetPtr(System.Type checkType) { }
+        public static unsafe void DisposeReference(Castle.DynamicProxy.ByRefLikeReference reference, void* expectedPtr) { }
         [System.CLSCompliant(false)]
-        public unsafe void Invalidate(void* checkPtr) { }
+        public static unsafe void* GetRawPtr(Castle.DynamicProxy.ByRefLikeReference reference, System.Type expectedType) { }
     }
     public class ByRefLikeReference<TByRefLike> : Castle.DynamicProxy.ByRefLikeReference
         where TByRefLike :  struct
     {
-        [System.CLSCompliant(false)]
-        public ByRefLikeReference(System.Type type, void* ptr, bool valueIsScoped) { }
         public TByRefLike GetValue() { }
         public void SetValue(Castle.DynamicProxy.ByRefLikeReference<TByRefLike>.ValueGetter valueGetter) { }
         public void UseValue(Castle.DynamicProxy.ByRefLikeReference<TByRefLike>.ValueConsumer valueConsumer) { }
@@ -2723,16 +2731,8 @@ public static bool IsAccessible(System.Reflection.MethodBase method, [System.Dia
         public static bool IsProxy(object? instance) { }
         public static bool IsProxyType(System.Type type) { }
     }
-    public class ReadOnlySpanReference<T> : Castle.DynamicProxy.ByRefLikeReference<System.ReadOnlySpan<T>>
-    {
-        [System.CLSCompliant(false)]
-        public ReadOnlySpanReference(System.Type type, void* ptr, bool valueIsScoped) { }
-    }
-    public class SpanReference<T> : Castle.DynamicProxy.ByRefLikeReference<System.Span<T>>
-    {
-        [System.CLSCompliant(false)]
-        public SpanReference(System.Type type, void* ptr, bool valueIsScoped) { }
-    }
+    public class ReadOnlySpanReference<T> : Castle.DynamicProxy.ByRefLikeReference<System.ReadOnlySpan<T>> { }
+    public class SpanReference<T> : Castle.DynamicProxy.ByRefLikeReference<System.Span<T>> { }
     public class StandardInterceptor : Castle.DynamicProxy.IInterceptor
     {
         public StandardInterceptor() { }

src/Castle.Core.Tests/DynamicProxy.Tests/ByRefLikeSupport/ByRefLikeReferenceTestCase.cs

@@ -63,32 +63,32 @@ public unsafe void Ctor_preserves_value_is_scoped_value(bool valueIsScoped)
 		}
 
 		[Test]
-		public unsafe void Invalidate_throws_if_address_mismatch()
+		public unsafe void Dispose_throws_if_address_mismatch()
 		{
 			ReadOnlySpan<char> local = default;
 			var reference = new ByRefLikeReference(typeof(ReadOnlySpan<char>), &local, false);
 			Assert.Throws<InvalidOperationException>(() =>
 			{
 				ReadOnlySpan<char> otherLocal = default;
-				reference.Invalidate(&otherLocal);
+				reference.Dispose(&otherLocal);
 			});
 		}
 
 		[Test]
-		public unsafe void Invalidate_succeeds_if_address_match()
+		public unsafe void Dispose_succeeds_if_address_match()
 		{
 			ReadOnlySpan<char> local = default;
 			var reference = new ByRefLikeReference(typeof(ReadOnlySpan<char>), &local, false);
-			reference.Invalidate(&local);
+			reference.Dispose(&local);
 		}
 
 		[Test]
-		public unsafe void Invalidate_throws_when_access_from_other_thread()
+		public unsafe void Dispose_throws_when_access_from_other_thread()
 		{
 			ReadOnlySpan<char> local = default;
 			var reference = new ByRefLikeReference(typeof(ReadOnlySpan<char>), &local, false);
 			var address = reference.GetPtr(typeof(ReadOnlySpan<char>));
-			var task = Task.Run(() => reference.Invalidate(address));
+			var task = Task.Run(() => reference.Dispose(address));
 			var msg = Assert.Throws<InvalidOperationException>(() => task.GetAwaiter().GetResult()).Message;
 			StringAssert.Contains("thread", msg);
 		}
@@ -111,11 +111,11 @@ public unsafe void GetPtr_returns_ctor_address_if_type_match()
 		}
 
 		[Test]
-		public unsafe void GetPtr_throws_after_Invalidate()
+		public unsafe void GetPtr_throws_after_Dispose()
 		{
 			ReadOnlySpan<char> local = default;
 			var reference = new ByRefLikeReference(typeof(ReadOnlySpan<char>), &local, false);
-			reference.Invalidate(&local);
+			reference.Dispose(&local);
 			Assert.Throws<ObjectDisposedException>(() => reference.GetPtr(typeof(ReadOnlySpan<char>)));
 		}
 

src/Castle.Core/DynamicProxy/ByRefLikeReference.cs

@@ -20,7 +20,6 @@
 namespace Castle.DynamicProxy
 {
 	using System;
-	using System.ComponentModel;
 	using System.Diagnostics;
 	using System.Diagnostics.CodeAnalysis;
 	using System.Threading;
@@ -42,45 +41,43 @@ namespace Castle.DynamicProxy
 	//
 	// *) Unmanaged pointers can be safe when used to reference stack-allocated objects. However, that is only true
 	//    when they point into "live" stack frames. That is, they MUST NOT reference parameters or local variables
-	//    of methods that have already finished executing. This is why we have the `ByRefLikeReference.Invalidate` method:
+	//    of methods that have already finished executing. This is why we have the `ByRefLikeReference.Dispose` method:
 	//    DynamicProxy (or whatever else instantiated a `ByRefLikeReference` object to point at a method parameter or local
 	//    variable) must invoke this method before said method returns (or tail-calls).
 	//
-	// *) The `checkType` / `checkPtr` arguments of `GetPtr` or `Invalidate`, respectively, have two purposes:
+	// *) The `checkType` / `checkPtr` arguments of `GetPtr` or `Dispose`, respectively, have two purposes:
 	//
 	//     1. DynamicProxy, or whatever else instantiated a `ByRefLikeReference`, is expected to know at all times what
 	//        exactly each instance references. These parameters make it harder for anyone to use the type directly
 	//        if they didn't also instantiate it themselves.
 	//
-	//     2. `checkPtr` of `Invalidate` attempts to prevent re-use of a referenced storage location for another
+	//     2. `checkPtr` of `Dispose` attempts to prevent re-use of a referenced storage location for another
 	//        similarly-typed local variable by the JIT. DynamicProxy typically instantiates `ByRefLikeReference` instances
-	//        at the start of intercepted method bodies, and it invokes `Invalidate` at the very end, meaning that
+	//        at the start of intercepted method bodies, and it invokes `Dispose` at the very end, meaning that
 	//        the address of the local/parameter is taken at each method boundary, meaning that static analysis should
 	//        never during the whole method see the local/parameter as "no longer in use". (This may be a little
 	//        paranoid, since the CoreCLR JIT probably exempts so-called "address-exposed" locals from reuse anyway.)
 	//
 	// *) We track if each reference represents scoped value. Scoped values usually represent data living on stack only,
-	//    so we should apply more strict rules on how we expose the value.
-	//    Dynamic generator analyzes method signature and provides the correct value for us.
+	//    so we should apply more strict rules on how we expose the value. Otherwise, we could have use-after-free scenario,
+	//    which could lead to stack corruption and weird behavior.
+	//    Dynamic generator analyzes method signature and provides the correct value.
 	//
 	// *) We always return a copy of the original value and never expose the value by reference.
-	//    This is important to make sure that we prevent scenario of `ref struct` interior mutability
-	//    and providing a potential way to leak scoped values out of their lifetime scope.
+	//    This is important to make sure that we prevent possibility `ref struct` interior mutability (as copy will be changed)
+	//    and close a possibility to leak scoped values out of their lifetime scope by storing them inside another `ref struct`.
 	//
 	// *) The SetValue() function uses delegate to get the value. This is required to make sure that local variables
-	//    or variables with scoped visibility are not promoted outside their lifetime.
+	//    or variables with scoped visibility could never be promoted outside their lifetime.
 	//    When we have delegate, we could only use heap-backed values and compiler will enforce the safety for us.
 	//
 	// *) Finally, we allow accessing reference data from the owning thread only to avoid all possible concurrency-related issues.
+	//    Otherwise, it's very easy to have use-after-free scenario, as other thread could access value after function exit.
 	//
 	// As far as I can reason, `ByRefLikeReference` et al. should be safe to use IFF they are never copied out from an
 	// `IInvocation`, and IFF DynamicProxy succeeds in destructing them and erasing them from the `IInvocation` right
 	// before the intercepted method finishes executing.
 
-	/// <summary>
-	///   Do not use! This type should only be used by DynamicProxy internals.
-	/// </summary>
-	[EditorBrowsable(EditorBrowsableState.Never)]
 	public unsafe class ByRefLikeReference
 	{
 		[DebuggerBrowsable(DebuggerBrowsableState.Never)]
@@ -92,13 +89,8 @@ public unsafe class ByRefLikeReference
 		private Thread ownerThread;
 
 		public bool ValueIsScoped { get; }
-		
-		/// <summary>
-		///   Do not use! This constructor should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
+
+		internal ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
 		{
 			if (type.IsByRefLikeSafe() == false)
 			{
@@ -116,12 +108,7 @@ public ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
 			this.ownerThread = Thread.CurrentThread;
 		}
 
-		/// <summary>
-		///   Do not use! This method should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public void* GetPtr(Type checkType)
+		internal void* GetPtr(Type checkType)
 		{
 			AssertCurrentThread();
 
@@ -132,24 +119,19 @@ public ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
 
 			if (this.ptr == null)
 			{
-				throw new ObjectDisposedException("This reference was already invalidated");
+				throw new ObjectDisposedException("This reference was already disposed");
 			}
 
 			return this.ptr;
 		}
 
-		/// <summary>
-		///   Do not use! This method should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public void Invalidate(void* checkPtr)
+		internal void Dispose(void* checkPtr)
 		{
 			AssertCurrentThread();
 
 			if (this.ptr == null || this.ptr != checkPtr)
 			{
-				throw new InvalidOperationException($"BUG: Pointer mismatch on reference invalidation. Expected: {(nint)checkPtr:X16}, Actual: {(nint)this.ptr:X16}");
+				throw new InvalidOperationException($"BUG: Pointer mismatch on reference disposal. Expected: {(nint)checkPtr:X16}, Actual: {(nint)this.ptr:X16}");
 			}
 
 			this.ptr = null;
@@ -183,12 +165,7 @@ private void AssertCurrentThread()
 	public unsafe class ByRefLikeReference<TByRefLike> : ByRefLikeReference
 		where TByRefLike : struct, allows ref struct
 	{
-		/// <summary>
-		///   Do not use! This constructor should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
+		internal ByRefLikeReference(Type type, void* ptr, bool valueIsScoped)
 			: base(type, ptr, valueIsScoped)
 		{
 			if (type != typeof(TByRefLike))
@@ -259,12 +236,7 @@ public unsafe class ReadOnlySpanReference<T>
 		: ByRefLikeReference
 #endif
 	{
-		/// <summary>
-		///   Do not use! This constructor should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public ReadOnlySpanReference(Type type, void* ptr, bool valueIsScoped)
+		internal ReadOnlySpanReference(Type type, void* ptr, bool valueIsScoped)
 			: base(type, ptr, valueIsScoped)
 		{
 			if (type != typeof(ReadOnlySpan<T>))
@@ -336,12 +308,7 @@ public unsafe class SpanReference<T>
 		: ByRefLikeReference
 #endif
 	{
-		/// <summary>
-		///   Do not use! This constructor should only be called by DynamicProxy internals.
-		/// </summary>
-		[CLSCompliant(false)]
-		[EditorBrowsable(EditorBrowsableState.Never)]
-		public SpanReference(Type type, void* ptr, bool valueIsScoped)
+		internal SpanReference(Type type, void* ptr, bool valueIsScoped)
 			: base(type, ptr, valueIsScoped)
 		{
 			if (type != typeof(Span<T>))

src/Castle.Core/DynamicProxy/ByRefLikeReferenceUnsafe.cs

@@ -0,0 +1,75 @@
+// Copyright 2004-2026 Castle Project - http://www.castleproject.org/
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#if FEATURE_BYREFLIKE
+#nullable enable
+
+namespace Castle.DynamicProxy;
+
+using System;
+
+/// <summary>
+/// Collection of methods to perform unsafe manipulations on <see cref="ByRefLikeReference"/> instances.
+/// Usage could lead to memory safe issues, so be careful when using it
+/// </summary>
+public static class ByRefLikeReferenceUnsafe
+{
+	[CLSCompliant(false)]
+	public static unsafe ByRefLikeReference CreateByRefLikeReferenceUntyped(Type type, void* ptr, bool valueIsScoped)
+	{
+		return new ByRefLikeReference(type, ptr, valueIsScoped);
+	}
+	
+#if NET9_0_OR_GREATER
+	
+	[CLSCompliant(false)]
+	public static unsafe ByRefLikeReference<TByRefLike> CreateByRefLikeReference<TByRefLike>(Type type, void* ptr, bool valueIsScoped)
+		where TByRefLike : struct, allows ref struct
+	{
+		return new ByRefLikeReference<TByRefLike>(type, ptr, valueIsScoped);
+	}
+#endif
+	
+	[CLSCompliant(false)]
+	public static unsafe ReadOnlySpanReference<T> CreateReadOnlySpanReference<T>(Type type, void* ptr, bool valueIsScoped)
+	{
+		return new ReadOnlySpanReference<T>(type, ptr, valueIsScoped);
+	}
+
+	[CLSCompliant(false)]
+	public static unsafe SpanReference<T> CreateSpanReference<T>(Type type, void* ptr, bool valueIsScoped)
+	{
+		return new SpanReference<T>(type, ptr, valueIsScoped);
+	}
+	
+	/// <summary>
+	/// Returns raw pointer held by the <paramref name="reference"/>.
+	/// </summary>
+	[CLSCompliant(false)]
+	public static unsafe void* GetRawPtr(ByRefLikeReference reference, Type expectedType)
+	{
+		return reference.GetPtr(expectedType);
+	}
+	
+	/// <summary>
+	/// Disposes <paramref name="reference"/>, so that underlying value can no longer be used
+	/// </summary>
+	[CLSCompliant(false)]
+	public static unsafe void DisposeReference(ByRefLikeReference reference, void* expectedPtr)
+	{
+		reference.Dispose(expectedPtr);
+	}
+}
+
+#endif

src/Castle.Core/DynamicProxy/Generators/Emitters/SimpleAST/ConvertArgumentFromObjectExpression.cs

@@ -50,7 +50,7 @@ public void Emit(ILGenerator gen)
 				{
 					gen.Emit(OpCodes.Ldtoken, dereferencedArgumentType);
 					gen.Emit(OpCodes.Call, TypeMethods.GetTypeFromHandle);
-					gen.Emit(OpCodes.Call, ByRefLikeReferenceMethods.GetPtr);
+					gen.Emit(OpCodes.Call, ByRefLikeReferenceUnsafeMethods.GetRawPtr);
 					gen.Emit(OpCodes.Ldobj, dereferencedArgumentType);
 				}
 				else