[API Proposal]: Add support for converting to/from IntPtr for some handles

[DaZombieKiller]

Background and motivation

The Type.GetTypeFromHandleUnsafe method allows you to retrieve the Type object associated with a type handle pointer retrieved via RuntimeTypeHandle.Value.

Currently, this API is internal with no public-facing equivalent. This means there is currently no safe way for you to get the original Type or RuntimeTypeHandle value back, leading to the RuntimeTypeHandle.Value property being of little use.

Having a way to retrieve the original Type or RuntimeTypeHandle would also allow the type handle pointer to be used to easily pass types to native code (such as when writing a custom runtime host).

API Proposal

public struct RuntimeTypeHandle
{
+     public static RuntimeTypeHandle FromIntPtr(IntPtr value);
+     public static IntPtr ToIntPtr(RuntimeTypeHandle value);
}

public struct RuntimeFieldHandle
{
+    public static RuntimeFieldHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeFieldHandle value);
}

public struct RuntimeMethodHandle
{
+    public static RuntimeMethodHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeMethodHandle value);
}

API Usage

var api = new NativeAPI
{
    GetTypeHandle      = &GetTypeHandle,
    GetFullTypeName    = &GetFullTypeName,
    GetFunctionPointer = &GetFunctionPointer
};

// This native method may be interested in querying for
// pointers to UnmanagedCallersOnly methods to invoke.
SomeNativeMethod(&api);

[UnmanagedCallersOnly]
static IntPtr GetTypeHandle(IntPtr typeName)
{
    return Type.GetType(Marshal.PtrToStringUni(typeName)).TypeHandle.Value;
}

[UnmanagedCallersOnly]
static IntPtr GetFunctionPointer(IntPtr type, IntPtr methodName)
{
    var type   = Type.GetTypeFromHandle(RuntimeTypeHandle.FromIntPtr(type));
    var method = type.GetMethod(Marshal.PtrToStringUni(methodName), BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
    return method.MethodHandle.GetFunctionPointer();
}

[UnmanagedCallersOnly]
static IntPtr GetFullTypeName(IntPtr type)
{
    return Marshal.StringToHGlobalUni(Type.GetTypeFromHandle(RuntimeTypeHandle.FromIntPtr(type))?.FullName);
}

Alternative Designs

No response

Risks

Being an unmanaged pointer, RuntimeTypeHandle.Value will not keep a collectible type alive. This would need to be clearly called out in documentation and could be a potential problem when the API is not used correctly.

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[tfenise]

I guess the IntPtr value of RuntimeTypeHandle.Value does not keep a collectible type alive, and thus may be invalidated or recycled unexpectedly.

[DaZombieKiller]

I guess the IntPtr value of RuntimeTypeHandle.Value does not keep a collectible type alive, and thus may be invalidated or recycled unexpectedly.

This is a good point, I'll add it to the risks section. It's definitely something that a user of the API would need to be keenly aware of.

[Joe4evr]

🍝 Just throwing this out for consideration: Should the public entrypoint for this API be placed somewhere under S.R.InteropServices (or whatever's more appropriate) instead?

[ghost]

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

Issue Details

---

Background and motivation

The Type.GetTypeFromHandleUnsafe method allows you to retrieve the Type object associated with a type handle pointer retrieved via RuntimeTypeHandle.Value.

Currently, this API is internal with no public-facing equivalent. This means there is currently no safe way for you to get the original Type or RuntimeTypeHandle value back, leading to the RuntimeTypeHandle.Value property being of little use.

Having a way to retrieve the original Type or RuntimeTypeHandle would also allow the type handle pointer to be used to easily pass types to native code (such as when writing a custom runtime host).

API Proposal

namespace System
{
    public abstract partial class Type
    {
        public static Type? GetTypeFromHandleUnsafe(IntPtr handle);
    }
}

API Usage

var api = new NativeAPI
{
    GetTypeHandle      = &GetTypeHandle,
    GetFullTypeName    = &GetFullTypeName,
    GetFunctionPointer = &GetFunctionPointer
};

// This native method may be interested in querying for
// pointers to UnmanagedCallersOnly methods to invoke.
SomeNativeMethod(&api);

[UnmanagedCallersOnly]
static IntPtr GetTypeHandle(IntPtr typeName)
{
    return Type.GetType(Marshal.PtrToStringUni(typeName)).TypeHandle.Value;
}

[UnmanagedCallersOnly]
static IntPtr GetFunctionPointer(IntPtr type, IntPtr methodName)
{
    var type   = Type.GetTypeFromHandleUnsafe(type);
    var method = type.GetMethod(Marshal.PtrToStringUni(methodName), BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
    return method.MethodHandle.GetFunctionPointer();
}

[UnmanagedCallersOnly]
static IntPtr GetFullTypeName(IntPtr type)
{
    return Marshal.StringToHGlobalUni(Type.GetTypeFromHandleUnsafe(type)?.FullName);
}

Alternative Designs

No response

Risks

Being an unmanaged pointer, RuntimeTypeHandle.Value will not keep a collectible type alive. This would need to be clearly called out in documentation and could be a potential problem when the API is not used correctly.

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

[DaZombieKiller]

🍝 Just throwing this out for consideration: Should the public entrypoint for this API be placed somewhere under S.R.InteropServices (or whatever's more appropriate) instead?

That sounds reasonable to me -- Type is extremely discoverable, so it might not be the best location for an API as unsafe as this.

[AaronRobinsonMSFT]

@jkotas or @davidwrighton Can either of you imagine a scenario where the TypeHandle wouldn't be static? Unless unloaded that is. I am trying to determine if there is any chance of the IntPtr value being invalid for any other reason than an unload type. There are a number of places in the runtime that assume a TypeHandle address doesn't move but I'd like to make sure there isn't any potential future scenario where that assumption could be changed.

[jkotas]

It is very likely that every realistic .NET runtime implementation has stable IntPtr (like TypeHandle in CoreCLR) that represents a type and that can be used to implement this marshaling very efficiently. The API contract should not say what this IntPtr actually points to.

In a hypothetical case where .NET runtime implementation does not have natural stable IntPtr that represents a type (e.g. the MethodTables are allocated on GC heap and can move), the API contract can be still maintained by a table on the side.

This API is about marshaling System.Type into IntPtr and back. We have API for the System.Type -> IntPtr direction (RuntimeTypeHandle.Value). We do not have an API for the IntPtr ->System.Type direction and this is proposing to fill this hole. Mono embedding APIs can give you pointer that represents a type and then use this pointer to get back to the type, so an alternative way to look at this request is managed surface feature parity with Mono embedding APIs.

[AaronRobinsonMSFT]

Thoughts on adding this to RuntimeTypeHandle itself. This would follow the GCHandle pattern and developers could then use Type.GetTypeFromHandle() to get back to Type.

public struct RuntimeTypeHandle
{
+     public static RuntimeTypeHandle FromIntPtr(IntPtr value);
}

[jkoritzinsky]

I like putting it on RuntimeTypeHandle personally. It makes it a little harder to find than if it were on System.Type, while still putting it on a related type (and as you mentioned, following the design styles of GCHandle).

[teo-tsirpanis]

I agree, it makes more sense to add it to RuntimeTypeHandle. I don't think of a good place in InteropServices that could fit.

[jkotas]

I agree that RuntimeTypeHandle sounds like a good place for this. If we were to follow the GCHandle pattern, should we add both FromIntPtr and ToIntPtr methods for discoverability?

[AaronRobinsonMSFT]

If we were to follow the GCHandle pattern, should we add both FromIntPtr and ToIntPtr methods for discoverability?

Yep. That makes perfect sense.

@DaZombieKiller I'm going to update the proposal with this approach and then move it to ready for review. Please feel free to push back if you have another opinion.

[DaZombieKiller]

For the sake of parity, it may also be useful to expose APIs for RuntimeMethodHandle and RuntimeFieldHandle, which both also offer IntPtr Value { get; } properties with no way to convert back to a RuntimeMethodHandle/RuntimeFieldHandle.

public struct RuntimeFieldHandle
{
+    public static RuntimeFieldHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeFieldHandle value);
}

public struct RuntimeMethodHandle
{
+    public static RuntimeMethodHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeMethodHandle value);
}

[AaronRobinsonMSFT]

@DaZombieKiller Sure. I'll add that as well.

[terrajobst]

• For consistency, you might want to also add explicit casting operators too, like GCHandle does.

namespace System;

public struct RuntimeTypeHandle
{
    public static RuntimeTypeHandle FromIntPtr(IntPtr value);
    public static IntPtr ToIntPtr(RuntimeTypeHandle value);
}

public struct RuntimeFieldHandle
{
    public static RuntimeFieldHandle FromIntPtr(IntPtr value);
    public static IntPtr ToIntPtr(RuntimeFieldHandle value);
}

public struct RuntimeMethodHandle
{
    public static RuntimeMethodHandle FromIntPtr(IntPtr value);
    public static IntPtr ToIntPtr(RuntimeMethodHandle value);
}

[ghost]

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

Issue Details

---

Background and motivation

The Type.GetTypeFromHandleUnsafe method allows you to retrieve the Type object associated with a type handle pointer retrieved via RuntimeTypeHandle.Value.

Currently, this API is internal with no public-facing equivalent. This means there is currently no safe way for you to get the original Type or RuntimeTypeHandle value back, leading to the RuntimeTypeHandle.Value property being of little use.

Having a way to retrieve the original Type or RuntimeTypeHandle would also allow the type handle pointer to be used to easily pass types to native code (such as when writing a custom runtime host).

API Proposal

public struct RuntimeTypeHandle
{
+     public static RuntimeTypeHandle FromIntPtr(IntPtr value);
+     public static IntPtr ToIntPtr(RuntimeTypeHandle value);
}

public struct RuntimeFieldHandle
{
+    public static RuntimeFieldHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeFieldHandle value);
}

public struct RuntimeMethodHandle
{
+    public static RuntimeMethodHandle FromIntPtr(IntPtr value);
+    public static IntPtr ToIntPtr(RuntimeMethodHandle value);
}

API Usage

var api = new NativeAPI
{
    GetTypeHandle      = &GetTypeHandle,
    GetFullTypeName    = &GetFullTypeName,
    GetFunctionPointer = &GetFunctionPointer
};

// This native method may be interested in querying for
// pointers to UnmanagedCallersOnly methods to invoke.
SomeNativeMethod(&api);

[UnmanagedCallersOnly]
static IntPtr GetTypeHandle(IntPtr typeName)
{
    return Type.GetType(Marshal.PtrToStringUni(typeName)).TypeHandle.Value;
}

[UnmanagedCallersOnly]
static IntPtr GetFunctionPointer(IntPtr type, IntPtr methodName)
{
    var type   = Type.GetTypeFromHandle(RuntimeTypeHandle.FromIntPtr(type));
    var method = type.GetMethod(Marshal.PtrToStringUni(methodName), BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
    return method.MethodHandle.GetFunctionPointer();
}

[UnmanagedCallersOnly]
static IntPtr GetFullTypeName(IntPtr type)
{
    return Marshal.StringToHGlobalUni(Type.GetTypeFromHandle(RuntimeTypeHandle.FromIntPtr(type))?.FullName);
}

Alternative Designs

No response

Risks

Being an unmanaged pointer, RuntimeTypeHandle.Value will not keep a collectible type alive. This would need to be clearly called out in documentation and could be a potential problem when the API is not used correctly.

Author:	DaZombieKiller
Assignees:	-
Labels:	api-approved, area-System.Runtime, in-pr
Milestone:	7.0.0