[API Proposal]: Reflection introspection support for FunctionPointer

[steveharter]

Background and motivation

This is the proposed API to support introspection of Function Pointers (delegate*) based on the user story, original issue and function pointer design. In summary, when function pointers were added in 5.0 the corresponding support for reflection was not added which resulted in an IntPtr being returned as the type when using typeof or reflection. This feature changes that to now return System.Type which then allows access to function pointer metadata including the calling convention, return type and parameters. This is a breaking change.

UPDATE: the original approved API for .NET 7 was not implemented due to concerns with breaking scenarios with managed C++ and adding unnecessary runtime overhead. This .NET 8 proposal changes the design to return "modified types" that expose custom modifiers on function pointers instead of exposing them on runtime-based types.

Corresponding support will also be added to MetadataLoadContext. The inbox version will have full support but the netstandard version, for simplicity, will throw NotSupportedException for the new members that return new types (since they are not in netstandard). For members that don't return new types, it will be possible to use reflection to invoke them.

This API issue is focused on introspection; the links above have additional features that can be layered on this including support for IL Emit.

API Proposal

namespace System
{
    public abstract class Type
    {
+       public virtual bool IsFunctionPointer { get; }
+       public virtual bool IsUnmanagedFunctionPointer { get; }

        // These throw InvalidOperationException if IsFunctionPointer = false:
+       public virtual Type GetFunctionPointerReturnType();
+       public virtual Type[] GetFunctionPointerParameterTypes();

        // These require a "modified type" to return custom modifier types:
+       public virtual Type[] GetRequiredCustomModifiers();
+       public virtual Type[] GetOptionalCustomModifiers();
+       public virtual Type[] GetFunctionPointerCallingConventions(); // Throws if IsFunctionPointer = false
    }
}

// Return a "modified type" from a field, property or parameter if its type is a:
// - Function pointer type
// - Pointer or array since they may reference a function pointer
// - Parameter or return type from a function pointer
namespace System.Reflection
{
    public abstract class FieldInfo
    {
+       public virtual Type GetModifiedFieldType() => throw new NotSupportedException();
    }

    public abstract class PropertyInfo
    {
+       public virtual Type GetModifiedPropertyType() => throw new NotSupportedException();
    }

    public abstract class ParameterInfo
    {
+       public virtual Type GetModifiedParameterType() => throw new NotSupportedException();
    }
}

A modified type's UnderlyingSystemType property returns the unmodified type and all members on a modified forward to that except:

• GetRequiredCustomModifiers()
• GetOptionalCustomModifiers()
• GetFunctionPointerCallingConventions()
• GetFunctionPointerParameterTypes()
• GetFunctionPointerReturnType()

which instead return the information kept on the modified type.

API Usage

See the design referenced above. Here's some short examples:

Type type = typeof(delegate*<int, bool>);
bool b = type.IsFunctionPointer(); // true
string s = type.ToString(); // "System.Boolean(System.Int32)"
Type returnType = type.GetFunctionPointerReturnType(); // System.Boolean
Type param1Type = type.GetFunctionPointerParameterTypes()[0]; // System.Int32

FieldInfo fieldInfo = typeof(Util).GetField("_field")!;
bool isUnmanaged = fieldInfo.FieldType.IsUnmanagedFunctionPointer; // true

// Get the modified type in order to obtain the custom modifiers
Type modifiedType = fieldInfo.GetModifiedFieldType();

// Get the unmanaged calling conventions
type = modifiedType.GetFunctionPointerCallingConventions()[0]; // CallConvCdecl

// Get the first custom modifier from the first parameter
type = modifiedType.GetFunctionPointerParameterTypes()[0].GetRequiredCustomModifiers()[0]; // OutAttribute

unsafe public class Util
{
    public delegate* unmanaged[CDecl]<out bool, void>; _field;
}

Risks

The breaking change nature of not returning IntPtr any longer.

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

Issue Details

---

Background and motivation

This is the proposed API to support introspection of Function Pointers (delegate*) based on the user story and original issue.

In summary, when function pointers were added in 5.0 the corresponding support for reflection was not added which resulted in an IntPtr being returned as the type when using typeof or reflection. This feature changes that to now return System.Type which then allows access to function pointer metadata including the calling convention, return type and parameters. This is a breaking change.

Corresponding support will also be added to MetadataLoadContext. The v7 version will have full support but the netstandard version, for simplicity, will likely throw NotSupportedException like it does today since there are new types and new System.Type members not exposed in netstandard.

This API issue is focused on introspection. Once this is in we can consider:

• Support invoke such as by adding a DynamicInvoke(), by returning a bound Delegate or by returning a bound MethodInfo.
• Being able to box for invoke parameter support. This means supporting the existing reflection invoke APIs by allowing a previously created IntPtr (by casting the function pointer) to be passed to a method that has a strongly-typed function pointer type argument, where it is unwound. This would be similar to how value type pointers (e.g. int*) can be passed as a boxed IntPtr (or System.Reflection.Pointer) to such methods.
  • Note that at runtime, outside of reflection, function pointers are still passed as either the strongly-typed pointer itself, a void* pointer or an IntPtr. This API issue does not expose a unified type+value class such as System.Reflection.Pointer although it could be added later.
• Emit APIs to create a function pointer.

API Proposal

namespace System.Reflection
{
    // A function pointer is a stand-alone signature, meaning it does not have an independent,
    // reusable declaration like a Delegate.
+   public abstract class FunctionPointerInfo
+   {
+       internal FunctionPointerInfo(); // prevent external derivation
+
+       public abstract CallingConvention CallingConvention { get; }
+       public abstract ParameterInfo ReturnParameter { get; }
+       public abstract Type UnderlyingType { get; }
+       public abstract ReadOnlySpan<ParameterInfo> GetParameters();

        // Although each function pointer declaration will be its own instance (pending possible caching strategy)
        // we support Equals to compare against them.
+       public abstract bool Equals(object? obj);
+       public abstract int GetHashCode();
+       public abstract string? ToString();

        // Future invoke and MemberInfo scenarios:
        // public abstract unsafe object? DynamicInvoke(void* pfnTarget, params object?[]? args);
        // public abstract unsafe Delegate CreateDelegate(void* pfnTarget, Type delegateType);
+    }

    public class Type
    {
+       public virtual bool IsFunctionPointer { get; }

        // Throws InvalidOperationException if IsFunctionPointer is false.
+       public virtual FunctionPointerInfo GetFunctionPointerInfo();

        // Note that IsPointer will return 'false' for function pointers.
        public virtual bool IsPointer { get; }
    }

    // We are not re-using this as it exposes "Any". Ideally this could have been called "AnyManaged"
    // in which case we may have extended it.
    // Currently used in limited scenarios on MethodBase primarily to filter via GetMethods() and GetConstructor()
    [Flags]
    public enum CallingConventions
    {
        Standard = 0x1,
        VarArgs = 0x2,
        Any = 0x3,
        HasThis = 0x20,
        ExplicitThis = 0x40, // would be set for function pointers
    }

    // New CallingConvention that matches System.Reflection.Metadata.SignatureCallingConvention except uses Managed\Unmanaged prefixes
+   public enum CallingConvention : byte
+   {
+       Managed = 0,
+       UnmanagedCdecl = 1,
+       UnmanagedStdCall = 2,
+       UnmanagedThisCall = 3,
+       UnmanagedFastCall = 4,
+       ManagedVarArgs = 5, // not supported with function pointers
+       Unmanaged = 9,
+   }
}

API Usage

using System.Reflection;

namespace ConsoleApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            // typeof:
            Type type = typeof(delegate*<void>);
            bool b = type.IsFunctionPointer(); // true
            FunctionPointerInfo fpi = Type.GetFunctionPointerInfo();
            string s = fpi.ToString(); // "void ()" (actual is TBD, but will list all parameters if there any)
            Type returnType = fpi.ReturnParameter.ParameterType; // System.Void

            // Also works with reflection:
            MethodInfo method = typeof(Util).GetMethod(nameof(Util.GetLog), BindingFlags.Public | BindingFlags.Instance)!;
            type = method.ReturnType;
            b = type.IsFunctionPointer(); // true
            fpi = Type.GetFunctionPointerInfo();
        }
    }

    unsafe public class Util
    {
        public static void Log() { Console.WriteLine("Log"); }

        public delegate*<void> GetLog()
        {
            return &Log;
        }
    }
}

Alternative Designs

• A new MethodInfo-derived type.
• A new System.Type-derived type.
• A new System.Reflection.FunctionPointer type similar to System.Reflection.Pointer. This is still possible if we want to wrap the type and value together.

Risks

The breaking change.

Author:	steveharter
Assignees:	steveharter
Labels:	api-suggestion, area-System.Reflection, breaking-change
Milestone:	7.0.0

[AaronRobinsonMSFT]

public abstract CallingConvention CallingConvention { get; }

Instead of reusing that enum, which has aged poorly, I would follow the pattern established by UnmanagedCallersOnlyAttribute.CallConvs and UnmanagedCallConvsAttribute.

[teo-tsirpanis]

• Perhaps we need a way to create FunctionPointerInfo members at runtime, like a FunctionPointerInfo.Create static method.
• Type.GetFunctionPointerInfo() could return null if the FPI does not exist, requiring one call and zero potential exceptions, removing the need for Type.IsFunctionPointer, and matching MethodBase.GetMethodBody()'s shape.

[jkotas]

Type.GetFunctionPointerInfo() could return null if the FPI does not exist,

If it does exist, it would end up allocating FunctionPointerInfo instance that the caller may not be interested at all. I think there is a value in having IsFunctionPointer method that just returns bool.

[MichalStrehovsky]

What's the motivation behind FunctionPointerInfo? There's no GenericParameterInfo, ArrayInfo, PointerInfo, ByReferenceInfo, or GenericInstanceInfo - the properties/methods that are only relevant for pareterized types/generic instances are dumped directly onto System.Type. It's up to the caller to decide whether the properties/methods make sense to call for a given System.Type instance.

Function pointers are constructed types like any other constructed type - why do we shape the reflection API differently?

[svick]

@MichalStrehovsky

the properties/methods that are only relevant for pareterized types/generic instances are dumped directly onto System.Type

Personally, I dislike that design: it makes it harder to discover which members you need or to ensure you're using them correctly. To me, this proposal looks good, since it clearly separates the concept of function pointers from the rest of the API surface, while not being too out of place regarding the existing API (unlike e.g. a new System.Type-derived type).

So I see it as a question of choosing something that's better in isolation, but less consistent versus choosing something worse on its own, but more consistent.

[MichalStrehovsky]

I'm not a fan of that design either but it has advantages in some cases. E.g. if I want a Type that tweaks one of the properties of an existing type, I would use a System.Refection.TypeDelegator and override that one property. It's unclear how TypeDelegator fits with FunctionPointerInfo. E.g. if I want the exact same function pointer type but with a different calling convention.

The reflection stack is built around dumping everything onto System.Type.

[steveharter]

What's the motivation behind FunctionPointerInfo? There's no GenericParameterInfo, ArrayInfo, PointerInfo, ByReferenceInfo, or GenericInstanceInfo - the properties/methods that are only relevant for pareterized types/generic instances are dumped directly onto System.Type. It's up to the caller to decide whether the properties/methods make sense to call for a given System.Type instance.
Function pointers are constructed types like any other constructed type - why do we shape the reflection API differently?

Function pointers are more like methods and have more metadata than generics, arrays, existing pointer, etc so instead of adding directly to Type some options considered:

1. Provide a new stand-alone FunctionPointerInfo type
2. Extend MethodInfo - e.g. FunctionPointerInfo : MethodInfo.
3. Extend MemberInfo - e.g. FunctionPointerInfo : MemberInfo.
4. Extend Type with inheritance FunctionPointerType : Type

The stand-alone option has the least friction and doesn't pollute Type.

We may also want to add DynamicInvoke() capabilities, so having a separate type would also be used for that.

[steveharter]

It's unclear how TypeDelegator fits with FunctionPointerInfo. E.g. if I want the exact same function pointer type but with a different calling convention.

Yes thanks to support that we would need to add a Type.GetFunctionPointerInfoImpl(...) similar to Type.GetMethodInfoImpl().