Add ObjectiveCMarshal.GetOrCreateReferenceTrackingMemory API (#128508)

Fixes #128476

Adds `ObjectiveCMarshal.GetOrCreateReferenceTrackingMemory(object)`
which returns the tagged memory span for an object without creating a
`GCHandle`. This is a more efficient alternative to
`CreateReferenceTrackingHandle` when only the tagged memory is needed
and no reference tracking handle is required at that point in time.

## Changes

- Added public API `ObjectiveCMarshal.
GetOrCreateReferenceTrackingMemory(object)` with full XML documentation
- Mono: stub throwing `NotImplementedException`
- Ref assembly updated
- Tests added to `ObjectiveCMarshalAPI`

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

src/coreclr/System.Private.CoreLib/src/System/Runtime/InteropServices/ObjectiveCMarshal.CoreCLR.cs

@@ -39,6 +39,12 @@ private static partial IntPtr CreateReferenceTrackingHandleInternal(
             out int memInSizeT,
             out IntPtr mem);
 
+        [LibraryImport(RuntimeHelpers.QCall, EntryPoint = "ObjCMarshal_GetOrCreateReferenceTrackingMemory")]
+        private static partial void GetOrCreateReferenceTrackingMemoryInternal(
+            ObjectHandleOnStack obj,
+            out int memInSizeT,
+            out IntPtr mem);
+
         [UnmanagedCallersOnly]
         internal static unsafe void* InvokeUnhandledExceptionPropagation(Exception* pExceptionArg, IntPtr methodDesc, IntPtr* pContext, Exception* pException)
         {

src/coreclr/nativeaot/System.Private.CoreLib/src/System/Runtime/InteropServices/ObjectiveCMarshal.NativeAot.cs

@@ -125,6 +125,16 @@ private static IntPtr CreateReferenceTrackingHandleInternal(
             object obj,
             out int memInSizeT,
             out IntPtr mem)
+        {
+            // Rely on GetOrCreateReferenceTrackingMemoryInternal for state checking.
+            GetOrCreateReferenceTrackingMemoryInternal(obj, out memInSizeT, out mem);
+            return RuntimeImports.RhHandleAllocRefCounted(obj);
+        }
+
+        private static void GetOrCreateReferenceTrackingMemoryInternal(
+            object obj,
+            out int memInSizeT,
+            out IntPtr mem)
         {
             if (!s_initialized)
             {
@@ -139,7 +149,6 @@ private static IntPtr CreateReferenceTrackingHandleInternal(
             var trackerInfo = s_objects.GetOrAdd(obj, static o => new ObjcTrackingInformation());
             trackerInfo.EnsureInitialized(obj);
             trackerInfo.GetTaggedMemory(out memInSizeT, out mem);
-            return RuntimeImports.RhHandleAllocRefCounted(obj);
         }
 
         internal class ObjcTrackingInformation

src/coreclr/vm/interoplibinterface.h

@@ -63,6 +63,11 @@ extern "C" void* QCALLTYPE ObjCMarshal_CreateReferenceTrackingHandle(
     _Out_ int* memInSizeT,
     _Outptr_ void** mem);
 
+extern "C" void QCALLTYPE ObjCMarshal_GetOrCreateReferenceTrackingMemory(
+    _In_ QCall::ObjectHandleOnStack obj,
+    _Out_ int* memInSizeT,
+    _Outptr_ void** mem);
+
 extern "C" BOOL QCALLTYPE ObjCMarshal_TrySetGlobalMessageSendCallback(
     _In_ ObjCMarshalNative::MessageSendFunction msgSendFunction,
     _In_ void* fptr);

src/coreclr/vm/interoplibinterface_objc.cpp

@@ -57,6 +57,39 @@ extern "C" BOOL QCALLTYPE ObjCMarshal_TryInitializeReferenceTracker(
     return success;
 }
 
+namespace
+{
+    void* GetTaggedMemoryForObject(
+        _In_ QCall::ObjectHandleOnStack obj,
+        _Out_ size_t* memInSizeT)
+    {
+        CONTRACTL
+        {
+            THROWS;
+            GC_TRIGGERS;
+            MODE_COOPERATIVE;
+            PRECONDITION(CheckPointer(memInSizeT));
+        }
+        CONTRACTL_END;
+
+        // The reference tracking system must be initialized.
+        if (!g_ReferenceTrackerInitialized)
+            COMPlusThrow(kInvalidOperationException, W("InvalidOperation_ObjectiveCMarshalNotInitialized"));
+
+        // The object's type must be marked appropriately and with a finalizer.
+        if (!obj.Get()->GetMethodTable()->IsTrackedReferenceWithFinalizer())
+            COMPlusThrow(kInvalidOperationException, W("InvalidOperation_ObjectiveCTypeNoFinalizer"));
+
+        // Initialize the syncblock for this instance.
+        SyncBlock* syncBlock = obj.Get()->GetSyncBlock();
+        InteropSyncBlockInfo* interopInfo = syncBlock->GetInteropInfo();
+        void* taggedMemoryLocal = interopInfo->EnsureTaggedMemoryAllocated(memInSizeT);
+        _ASSERTE(taggedMemoryLocal != NULL);
+
+        return taggedMemoryLocal;
+    }
+}
+
 extern "C" void* QCALLTYPE ObjCMarshal_CreateReferenceTrackingHandle(
         _In_ QCall::ObjectHandleOnStack obj,
         _Out_ int* memInSizeT,
@@ -72,44 +105,42 @@ extern "C" void* QCALLTYPE ObjCMarshal_CreateReferenceTrackingHandle(
 
     BEGIN_QCALL;
 
-    // The reference tracking system must be initialized.
-    if (!g_ReferenceTrackerInitialized)
-        COMPlusThrow(kInvalidOperationException, W("InvalidOperation_ObjectiveCMarshalNotInitialized"));
-
     // Switch to Cooperative mode since object references
     // are being manipulated.
-    {
-        GCX_COOP();
+    GCX_COOP();
+    taggedMemoryLocal = GetTaggedMemoryForObject(obj, &memInSizeTLocal);
+    instHandle = GetAppDomain()->CreateTypedHandle(obj.Get(), HNDTYPE_REFCOUNTED);
 
-        struct
-        {
-            OBJECTREF objRef;
-        } gc;
-        gc.objRef = NULL;
-        GCPROTECT_BEGIN(gc);
+    END_QCALL;
 
-        gc.objRef = obj.Get();
+    *memInSizeT = (int)memInSizeTLocal;
+    *mem = taggedMemoryLocal;
+    return (void*)instHandle;
+}
 
-        // The object's type must be marked appropriately and with a finalizer.
-        if (!gc.objRef->GetMethodTable()->IsTrackedReferenceWithFinalizer())
-            COMPlusThrow(kInvalidOperationException, W("InvalidOperation_ObjectiveCTypeNoFinalizer"));
+extern "C" void QCALLTYPE ObjCMarshal_GetOrCreateReferenceTrackingMemory(
+        _In_ QCall::ObjectHandleOnStack obj,
+        _Out_ int* memInSizeT,
+        _Outptr_ void** mem)
+{
+    QCALL_CONTRACT;
+    _ASSERTE(memInSizeT != NULL);
+    _ASSERTE(mem != NULL);
 
-        // Initialize the syncblock for this instance.
-        SyncBlock* syncBlock = gc.objRef->GetSyncBlock();
-        InteropSyncBlockInfo* interopInfo = syncBlock->GetInteropInfo();
-        taggedMemoryLocal = interopInfo->AllocTaggedMemory(&memInSizeTLocal);
-        _ASSERTE(taggedMemoryLocal != NULL);
+    size_t memInSizeTLocal;
+    void* taggedMemoryLocal;
 
-        instHandle = GetAppDomain()->CreateTypedHandle(gc.objRef, HNDTYPE_REFCOUNTED);
+    BEGIN_QCALL;
 
-        GCPROTECT_END();
-    }
+    // Switch to Cooperative mode since object references
+    // are being manipulated.
+    GCX_COOP();
+    taggedMemoryLocal = GetTaggedMemoryForObject(obj, &memInSizeTLocal);
 
     END_QCALL;
 
     *memInSizeT = (int)memInSizeTLocal;
     *mem = taggedMemoryLocal;
-    return (void*)instHandle;
 }
 
 namespace

src/coreclr/vm/qcallentrypoints.cpp

@@ -441,6 +441,7 @@ static const Entry s_QCall[] =
     DllImportEntry(ObjCMarshal_TrySetGlobalMessageSendCallback)
     DllImportEntry(ObjCMarshal_TryInitializeReferenceTracker)
     DllImportEntry(ObjCMarshal_CreateReferenceTrackingHandle)
+    DllImportEntry(ObjCMarshal_GetOrCreateReferenceTrackingMemory)
 #endif
 #if defined(FEATURE_JAVAMARSHAL)
     DllImportEntry(JavaMarshal_Initialize)

src/coreclr/vm/syncblk.h

@@ -331,7 +331,7 @@ class InteropSyncBlockInfo
 #ifdef FEATURE_OBJCMARSHAL
 public:
 #ifndef DACCESS_COMPILE
-    PTR_VOID AllocTaggedMemory(_Out_ size_t* memoryInSizeT)
+    PTR_VOID EnsureTaggedMemoryAllocated(_Out_ size_t* memoryInSizeT)
     {
         LIMITED_METHOD_CONTRACT;
         _ASSERTE(memoryInSizeT != NULL);

src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/ObjectiveC/ObjectiveCMarshal.PlatformNotSupported.cs

@@ -94,6 +94,34 @@ public static GCHandle CreateReferenceTrackingHandle(
             out Span<IntPtr> taggedMemory)
             => throw new PlatformNotSupportedException();
 
+        /// <summary>
+        /// Gets reference tracking memory for the supplied object.
+        /// </summary>
+        /// <param name="obj">The object whose tracking memory to return.</param>
+        /// <returns>A span of tracking memory associated with <paramref name="obj"/>.</returns>
+        /// <exception cref="InvalidOperationException">Thrown if the ObjectiveCMarshal API has not been initialized.</exception>
+        /// <remarks>
+        /// The Initialize() must be called prior to calling this function.
+        ///
+        /// The <paramref name="obj"/> must have a type in its hierarchy marked with
+        /// <see cref="ObjectiveCTrackedTypeAttribute"/>.
+        ///
+        /// The "Is Referenced" callback passed to <see cref="Initialize" />
+        /// will be passed the memory returned from this function.
+        /// The memory it points at is defined by the length in the <see cref="Span{IntPtr}"/> and
+        /// will be zeroed out. It will be available until <paramref name="obj"/> is collected by the GC.
+        /// The returned memory can be used for any purpose by the caller of this function and is usable
+        /// during the "Is Referenced" callback.
+        ///
+        /// Calling this function multiple times with the same <paramref name="obj"/> will
+        /// return the same tracking memory. It is only guaranteed to be zero initialized on
+        /// the first call of this or <see cref="CreateReferenceTrackingHandle" />.
+        ///
+        /// The return value is the same as the tracking memory returned from <see cref="CreateReferenceTrackingHandle" />.
+        /// </remarks>
+        public static Span<IntPtr> GetOrCreateReferenceTrackingMemory(object obj)
+            => throw new PlatformNotSupportedException();
+
         /// <summary>
         /// Objective-C msgSend function override options.
         /// </summary>

src/libraries/System.Private.CoreLib/src/System/Runtime/InteropServices/ObjectiveC/ObjectiveCMarshal.cs

@@ -101,6 +101,8 @@ public static unsafe void Initialize(
         /// return a new handle each time but the same tagged memory will be returned. The
         /// tagged memory is only guaranteed to be zero initialized on the first call.
         ///
+        /// The tagged memory returned is the same as the memory returned from <see cref="GetOrCreateReferenceTrackingMemory" />.
+        ///
         /// The caller is responsible for freeing the returned <see cref="GCHandle"/>.
         /// </remarks>
         public static GCHandle CreateReferenceTrackingHandle(
@@ -126,6 +128,50 @@ public static GCHandle CreateReferenceTrackingHandle(
             return GCHandle.FromIntPtr(refCountHandle);
         }
 
+        /// <summary>
+        /// Gets reference tracking memory for the supplied object.
+        /// </summary>
+        /// <param name="obj">The object whose tracking memory to return.</param>
+        /// <returns>A span of tracking memory associated with <paramref name="obj"/>.</returns>
+        /// <exception cref="InvalidOperationException">Thrown if the ObjectiveCMarshal API has not been initialized.</exception>
+        /// <remarks>
+        /// The Initialize() must be called prior to calling this function.
+        ///
+        /// The <paramref name="obj"/> must have a type in its hierarchy marked with
+        /// <see cref="ObjectiveCTrackedTypeAttribute"/>.
+        ///
+        /// The "Is Referenced" callback passed to <see cref="Initialize" />
+        /// will be passed the memory returned from this function.
+        /// The memory it points at is defined by the length in the <see cref="Span{IntPtr}"/> and
+        /// will be zeroed out. It will be available until <paramref name="obj"/> is collected by the GC.
+        /// The returned memory can be used for any purpose by the caller of this function and usable
+        /// during the "Is Referenced" callback.
+        ///
+        /// Calling this function multiple times with the same <paramref name="obj"/> will
+        /// return the same tracking memory. It is only guaranteed to be zero initialized on
+        /// the first call of this or <see cref="CreateReferenceTrackingHandle" />.
+        ///
+        /// The return value is the same as the tracking memory returned from <see cref="CreateReferenceTrackingHandle" />.
+        /// </remarks>
+        public static Span<IntPtr> GetOrCreateReferenceTrackingMemory(object obj)
+        {
+            ArgumentNullException.ThrowIfNull(obj);
+
+            GetOrCreateReferenceTrackingMemoryInternal(
+#if NATIVEAOT
+                obj,
+#else
+                ObjectHandleOnStack.Create(ref obj),
+#endif
+                out int memInSizeT,
+                out IntPtr mem);
+
+            unsafe
+            {
+                return new Span<IntPtr>(mem.ToPointer(), memInSizeT);
+            }
+        }
+
         /// <summary>
         /// Objective-C msgSend function override options.
         /// </summary>

src/libraries/System.Runtime.InteropServices/ref/System.Runtime.InteropServices.cs

@@ -2448,6 +2448,7 @@ public static unsafe void Initialize(
         public static GCHandle CreateReferenceTrackingHandle(
             object obj,
             out System.Span<System.IntPtr> taggedMemory) => throw null;
+        public static System.Span<System.IntPtr> GetOrCreateReferenceTrackingMemory(object obj) => throw null;
         public enum MessageSendFunction
         {
             MsgSend,

src/mono/System.Private.CoreLib/src/System/Runtime/InteropServices/ObjectiveCMarshal.Mono.cs

@@ -33,5 +33,10 @@ private static IntPtr CreateReferenceTrackingHandleInternal(
             ObjectHandleOnStack obj,
             out int memInSizeT,
             out IntPtr mem) => throw new NotImplementedException();
+
+        private static void GetOrCreateReferenceTrackingMemoryInternal(
+            ObjectHandleOnStack obj,
+            out int memInSizeT,
+            out IntPtr mem) => throw new NotImplementedException();
     }
 }