[API Proposal]: GCHandle<T> (like GCHandle, but this time it's great™️)

[Sergio0694]

This API proposal is extracted from #94113 (comment) and supersedes/fixes:

• [API Proposal]: GCHandle.GetTargetUnsafe() with no handle validation #94113
• Add Dispose/IDisposable to GCHandle #54792
• Add Dispose/IDisposable to GCHandle #54792 (comment)

Overview

The GCHandle type currently has a number of issues/inefficiencies, that are impossible to completely fix without introducing some (major) breaking changes, which could cause all sorts of problems for people having a dependency on the current behaviors. It would be beneficial to instead add a new handle type, which solves all of these problems from the start:

• Unnecessary validation check (null check) when getting/setting targets
• Pin flag removal every time the handle target is resolved
• Interlocked operation from Free
• Not implementing IDisposable

We have a reference implementation which can be a starting point for this.

cc. @jkotas @AaronRobinsonMSFT @tannergooding

API Proposal

namespace System.Runtime.InteropServices;

public struct GCHandle<T> : System.IDisposable
    where T : class
{
    public GCHandle(T? value, GCHandleType type = GCHandleType.Normal);

    public readonly bool IsAllocated { get; }
    public T? Target { readonly get; set; }

    public static GCHandle<T> FromIntPtr(IntPtr value);
    public static IntPtr ToIntPtr(GCHandle<T> value);

    public void Dispose();
}

public struct PinnedGCHandle<T> : System.IDisposable
    where T : class
{
    public PinnedGCHandle(T? value);

    public readonly bool IsAllocated { get; }
    public T? Target { readonly get; set; }

    public static PinnedGCHandle<T> FromIntPtr(IntPtr value);
    public static IntPtr ToIntPtr(PinnedGCHandle<T> value);

    public void Dispose();
}

public static class GCHandleExtensions
{
    public static T* AddrOfArrayData<T>(this PinnedGCHandle<T[]> handle);
    public static char* AddrOfStringData(this PinnedGCHandle<string> handle);
}

Additional caveats

• Calling Target on a handle that's not allocated will throw NullReferenceException
• Calling AddrOf* on a handle that's not allocated will throw NullReferenceException
• Calling AddrOf* when the target is null will return a null pointer
• Converting between the two handles via FromIntPtr/ToIntPtr if the handle type is mismatched is undefined behavior
• Dispose is not thread safe (but still no-op after the first call, just not in a thread-safe manner)

API Usage

Same as GCHandle, really:

// In a constructor (or wherever)
this.handle = new GCHandle<MyObject>(myObj);

// Later on
MyObject? target = this.handle.Target;

Alternative Designs

The alternative would be to change GCHandle, but as mentioned, it seems impossible to fix all issues with back-compat.

Risks

Not really any risk, since this would be a brand new type.

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

This API proposal is extracted from #94113 (comment) and supersedes/fixes:

• [API Proposal]: GCHandle.GetTargetUnsafe() with no handle validation #94113
• Add Dispose/IDisposable to GCHandle #54792
• Add Dispose/IDisposable to GCHandle #54792 (comment)

Overview

The GCHandle type currently has a number of issues/inefficiencies, that are impossible to completely fix without introducing some (major) breaking changes, which could cause all sorts of problems for people having a dependency on the current behaviors. It would be beneficial to instead add a new handle type, which solves all of these problems from the start:

• Unnecessary validation check (null check) when getting/setting targets
• Pin flag removal every time the handle target is resolved
• Interlocked operation from Free
• Not implementing IDisposable

We have a reference implementation which can be a starting point for this.

cc. @jkotas @AaronRobinsonMSFT @tannergooding

API Proposal

namespace System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct UnsafeGCHandle : System.IDisposable
{
    public static UnsafeGCHandle Alloc(object? value, GCHandleType type = GCHandleType.Normal);

    public readonly bool IsAllocated { get; }
    public object? Target { readonly get; set; }

    public readonly unsafe IntPtr GetAddrOfPinnedObject();
    public void Dispose();
}

Open questions

• I'm assuming that the Target getter can be updated to just do *(object*)_handle, hence being as fast as possible already (ie. not needing that internal call that GCHandle has in its current implementation). If that's the case, then there's no need to add a separate GetTargetUnsafe() method — Target would already be as fast as it can be from the start.
• Should we consider using "better" names, since this is a new API? For instance:
  • The Alloc abbreviation is against the naming convention. Should it be Allocate? Or maybe Create?
  • Same for GetAddrOfPinnedObject(), should it be GetAddressOfPinnedObject()? Or maybe just PinnedObjectAddress?
• Since we said the type should implement IDisposable, I've just added Dispose(). Do we also want a Free() method?

API Usage

Same as GCHandle, really:

// In a constructor (or wherever)
this.handle = UnsafeGCHandle.Alloc(myObj);

// Later on
object? target = this.handle.Target();

Alternative Designs

The alternative would be to change GCHandle, but as mentioned, it seems impossible to fix all issues with back-compat.

Risks

Not really any risk, since this would be a brand new type.

Author:	Sergio0694
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

Tagging subscribers to this area: @dotnet/interop-contrib
See info in area-owners.md if you want to be subscribed.

Issue Details

---

This API proposal is extracted from #94113 (comment) and supersedes/fixes:

• [API Proposal]: GCHandle.GetTargetUnsafe() with no handle validation #94113
• Add Dispose/IDisposable to GCHandle #54792
• Add Dispose/IDisposable to GCHandle #54792 (comment)

Overview

The GCHandle type currently has a number of issues/inefficiencies, that are impossible to completely fix without introducing some (major) breaking changes, which could cause all sorts of problems for people having a dependency on the current behaviors. It would be beneficial to instead add a new handle type, which solves all of these problems from the start:

• Unnecessary validation check (null check) when getting/setting targets
• Pin flag removal every time the handle target is resolved
• Interlocked operation from Free
• Not implementing IDisposable

We have a reference implementation which can be a starting point for this.

cc. @jkotas @AaronRobinsonMSFT @tannergooding

API Proposal

namespace System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct UnsafeGCHandle : System.IDisposable
{
    public static UnsafeGCHandle Alloc(object? value, GCHandleType type = GCHandleType.Normal);

    public readonly bool IsAllocated { get; }
    public object? Target { readonly get; set; }

    public readonly unsafe IntPtr GetAddrOfPinnedObject();
    public void Dispose();
}

Open questions

• I'm assuming that the Target getter can be updated to just do *(object*)_handle, hence being as fast as possible already (ie. not needing that internal call that GCHandle has in its current implementation). If that's the case, then there's no need to add a separate GetTargetUnsafe() method — Target would already be as fast as it can be from the start.
• Should we consider using "better" names, since this is a new API? For instance:
  • The Alloc abbreviation is against the naming convention. Should it be Allocate? Or maybe Create?
  • Same for GetAddrOfPinnedObject(), should it be GetAddressOfPinnedObject()? Or maybe just PinnedObjectAddress?
• Since we said the type should implement IDisposable, I've just added Dispose(). Do we also want a Free() method?

API Usage

Same as GCHandle, really:

// In a constructor (or wherever)
this.handle = UnsafeGCHandle.Alloc(myObj);

// Later on
object? target = this.handle.Target();

Alternative Designs

The alternative would be to change GCHandle, but as mentioned, it seems impossible to fix all issues with back-compat.

Risks

Not really any risk, since this would be a brand new type.

Author:	Sergio0694
Assignees:	-
Labels:	api-suggestion, area-System.Runtime.InteropServices, untriaged
Milestone:	-

[jkotas]

• [StructLayout(LayoutKind.Sequential)]

Unnecessary.

• The Alloc abbreviation is against the naming convention. Should it be Allocate? Or maybe Create?

It should be a constructor (same as what we have done for DependentHandle).

• GetAddrOfPinnedObject

This method needs to do several checks against the type of the object. It may be better to have GetAddrOfPinnedArray and GetAddrOfPinnedString to go with the spirit of maximally unsafe type.

• Keep FromIntPtr/ToIntPtr?

[Sergio0694]

Updated the proposal integrating your suggestions 🙂

For GetAddrOfPinnedArray, I take it we want to keep that abbreviation for historic reasons?
If not, should we maybe consider naming those methods eg. GetAddressOfPinnedArray or something?

Any thoughts on whether we can just make Target free (*(object*)_handle in release), or if we need GetTargetUnsafe()?
From our previous conversation it seems to me we should be able to just make that faster? But just double checking 😄

[jkotas]

should we maybe consider naming those methods eg. GetAddressOfPinnedArray or something?

I assume that this API would be a shorthand for Unsafe.AsPointer(ref MemoryMarshal.GetArrayDataReference<T>(Unsafe.As<T[]>(handle.Target))), so maybe GetArrayDataAsPointer? Also, make it return a pointer?

Any thoughts on whether we can just make Target free ((object)_handle in release),

Yes. I think the idea is that this is maximally unsafe type.

[tannergooding]

Also, make it return a pointer?

Should From/ToIntPtr then be FromPointer and take void* instead?

Yes. I think the idea is that this is maximally unsafe type.

Given we have and allow object* now, and this is "maximally unsafe". Do we even need a type? Could this just be a pair of APIs on System.Runtime.CompilerServices.Unsafe? Something like:

public static object* CreateGCHandle(object? value, GCHandleType type = GCHandleType.Normal);
public static void DisposeGCHandle(object* value);

Given these two APIs, a user could trivially create their own unsafe wrapper with whatever name they wanted. They could still convert to and store it as IntPtr or a GCHandle or ...

[Sergio0694]

I was first a bit skeptical of going as far as exposing object* APIs, but (from Discord) Tanner did make a good point that just convinced me: if you're authoring some native object (eg. say a COM one) and eg. wanted some handle for a CoreWindow object (just to name any type you might need), would it be "better" to have an UnsafeGCHandle field, or literally just a CoreWindow* field? And the latter does kinda seem more explicit/intuitive in a way. And we'd just need two new APIs 😄

I'm not sure they belong on Unsafe though. Perhaps:

namespace System.Runtime.InteropServices;

public struct GCHandle
{
    public static object* CreateUnsafe(object? value, GCHandleType type = GCHandleType.Normal);
    public static void DisposeUnsafe(object* value);
}

?

Eg. in ComputeSharp I have this field. Would certainly be much more readable if it could just be Globals*.
And it also wouldn't need any additional Unsafe.As<Globals>(handle.Target!) clunkyness.

Additional benefit: after you initially cast the pointer type, you can also preserve nullability annotations.
Eg. you could have a SomeObject* field, or a SomeObject?* field to inform the rest of your code.

[tannergooding]

Noting that using object* does limit the implementations the GC could give for the type. It might not be valid on all runtimes. But, it was a passing idea in my head, so I thought I'd share.

Alternative names than UnsafeGCHandle would also include ObjectHandle or some variant thereof. These could likewise just be *Unsafe variants on GCHandle itself. CreateUnsafe, GetTargetUnsafe, etc. There are pros and cons to all of these, of course.