[API Proposal]: RuntimeHelpers.Box to create a box around a dynamically-typed byref

[jkoritzinsky]

Background and motivation

In interop scenarios where we have unbounded generic APIs that can take blittable or non-blittable types, we can end up in a scenario where we have a generic type T that has a corresponding type TAbi. However, there is no way to represent TAbi as a generic argument, so we have a mechanism to retrieve it as a System.Type instance. This allows us to still reason about the type.

If we want to do anything with the type though (like copy values around, go from a pointer into a buffer to a managed representation of it), we end up needing to use the APIs on System.Runtime.InteropServices.Marshal that take a System.Type, which are slow and not AOT-compatible.

We hit this scenario in CsWinRT when we are trying to marshal from WinRT a T[] where T is non-blittable. Today CsWinRT uses the APIs on Marshal even though the type will always be blittable as there's no alternative APIs.

API Proposal

namespace System.Runtime.CompilerServices;

public static class RuntimeHelpers
{
+    public object? Box(ref byte target, RuntimeTypeHandle type);
}

API Usage

int length = ...;
IntPtr data = ...;
if (data == IntPtr.Zero)
{
    return null;
}
var array = new T[length];
var data = (byte*)data.ToPointer();
var abi_element_size = Marshal.SizeOf(AbiType); // #97344 API would go here to get rid of the remaining usage of Marshal.SizeOf
for (int i = 0; i < abi.length; i++)
{
    array[i] = Marshaler<T>.FromAbi(RuntimeHelpers.Box(ref *data, AbiType.TypeHandle));
    data += abi_element_size;
}
return array;

Alternative Designs

Mentioned below in the collapsable section.

Risks

Minimal risk.

Previous Proposal

API Proposal

namespace System;

public ref struct TypedReference
{
+    public TypedReference(ref byte target, RuntimeTypeHandle type);
}

API Usage

int length = ...;
IntPtr data = ...;
if (data == IntPtr.Zero)
{
    return null;
}
var array = new T[length];
var data = (byte*)data.ToPointer();
var abi_element_size = Marshal.SizeOf(AbiType); // #97344 API would go here to get rid of the remaining usage of Marshal.SizeOf
for (int i = 0; i < abi.length; i++)
{
    var abi_element_ref = new TypedReference(ref *data, AbiType.TypeHandle);
    array[i] = Marshaler<T>.FromAbi(abi_element_ref.ToObject());
    data += abi_element_size;
}
return array;

Alternative Designs

We could provide another API on RuntimeHelpers to read and box an unmanaged value-type from a buffer, or even provide a higher level API over a ReadOnlySpan<byte>, like a MemoryMarshal.Read(ref ReadOnlySpan<byte>, System.Type) method.

We could make this method a static method with an Unsafe suffix to further describe its unsafeness.

Risks

System.TypedReference is a rarely used type. There may be issues in the runtime implementations around supporting it.

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

In interop scenarios where we have unbounded generic APIs that can take blittable or non-blittable types, we can end up in a scenario where we have a generic type T that has a corresponding type TAbi. However, there is no way to represent TAbi as a generic argument, so we have a mechanism to retrieve it as a System.Type instance. This allows us to still reason about the type.

If we want to do any thing with the type though (like copy values around, go from a pointer into a buffer to a managed representation of it), we end up needing to use the APIs on System.Runtime.InteropServices.Marshal that take a System.Type, which are slow and not AOT-compatible.

We hit this scenario in CsWinRT when we are trying to marshal from WinRT a T[] where T is non-blittable. Today CsWinRT uses the APIs on Marshal even though the type will always be blittable as there's no alternative APIs.

.NET already has a mechanism to represent a byref with a dynamically-determined type: System.TypedReference. However, there's no way to construct one currently from a byref and a type. This API proposal provides a constructor to create such a TypedReference.

API Proposal

namespace System;

public ref struct TypedReference
{
+    public TypedReference(ref byte target, RuntimeTypeHandle type);
}

API Usage

int length = ...;
IntPtr data = ...;
if (data == IntPtr.Zero)
{
    return null;
}
var array = new T[length];
var data = (byte*)data.ToPointer();
var abi_element_size = Marshal.SizeOf(AbiType); // TODO: another API proposal to remove this usage of Marshal.SizeOf
for (int i = 0; i < abi.length; i++)
{
    var abi_element_ref = new TypedReference(ref *data, AbiType.TypeHandle);
    array[i] = Marshaler<T>.FromAbi(abi_element_ref.ToObject());
    data += abi_element_size;
}
return array;

Alternative Designs

We could provide another API on RuntimeHelpers to read and box an unmanaged value-type from a buffer, or even provide a higher level API over a ReadOnlySpan<byte>, like a MemoryMarshal.Read(ref ReadOnlySpan<byte>, System.Type) method.

We could make this method a static method with an Unsafe suffix to further describe its unsafeness.

Risks

System.TypedReference is a rarely used type. There may be issues in the runtime implementations around supporting it.

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

[jkotas]

We could make this method a static method with an Unsafe suffix to further describe its unsafeness.

We typically deal with this problem by adding the method somewhere under System.Runtime.InteropServices or System.Runtime.CompilerServices namespace (for example, MemoryMarshal.CreateReadOnlySpan).

Should we introduce unsafe getter for the byref as well while we are on it?

[Sergio0694]

"Should we introduce unsafe getter for the byref as well while we are on it?"

Would that be the same as __refvalue? As in, would the idea just be that it'd be documented (but no new functionality)?

"We typically deal with this problem by adding the method somewhere under System.Runtime.InteropServices or System.Runtime.CompilerServices namespace (for example, MemoryMarshal.CreateReadOnlySpan)."

Something like this?

namespace System.Runtime.CompilerServices;

public static class RuntimeHelpers
{
    public static TypedReference CreateTypedReferenceUnsafe(ref byte target, RuntimeTypeHandle type);
    public static ref byte GetValueRefUnsafe(TypedReference reference);
}

[Sergio0694]

Random idea: would it perhaps make sense to add a TypedReferenceMarshal class instead?
To kinda group the methods and do what we already did for eg. CollectionsMarshal, ImmutableCollectionsMarshal?

Ie.

namespace System.Runtime.InteropServices;

public static class TypedReferenceMarshal
{
    public static TypedReference CreateTypedReference(ref byte target, RuntimeTypeHandle type);
    public static ref byte GetValueRef(TypedReference reference);
}

[jkotas]

"Should we introduce unsafe getter for the byref as well while we are on it?"

Would that be the same as __refvalue? As in, would the idea just be that it'd be documented (but no new functionality)?

It would not be the same. __refvalue is safe. It takes the target type statically and validates it. We have #26186 about adding safe ref accessors on TypedRefence. We may want to look at them together with this one to ensure consistency.

public static TypedReference CreateTypedReferenceUnsafe(ref byte target, RuntimeTypeHandle type);
public static ref byte GetValueRefUnsafe(TypedReference reference);

We do not use Unsafe suffixes in unsafe namespaces.

would it perhaps make sense to add a TypedReferenceMarshal class instead?

This is a question for API review discussion. When there is a choice, we typically avoid introducing a new type with just a few members and add the methods to the existing type instead. For example, MemoryMarshal would be a fine place for these two methods. There are two overloads of MemoryMarshal.GetArrayDataReference and these methods are very similar.

[MichalStrehovsky]

Unfortunately this API will require Roslyn work first - we cannot have APIs that return TypedReference due to the type's special snowflake status within the compiler (any method that returns TypedReference runs into CS1599).

[Sergio0694]

Well that's quite unfortunate and seems like it'd make this feature much less cheap than expected 🥲
Could we just sidestep the whole issue and just add an API for what we actually need to do? That is:

namespace System.Runtime.CompilerServices;

public static class RuntimeHelpers
{
    public static object? CreateObjectUnsafe(ref byte target, RuntimeTypeHandle type);
}

Like, the whole reason we needed a TypedReference was only so we could then use TypedReference.ToObject on it, but especially if that complicates things and needs language support too, perhaps we could just not surface it in our API shape at all?

[AaronRobinsonMSFT]

Could we just sidestep the whole issue and just add an API for what we actually need to do?

Is the expectation here that target is an existing block of memory that contains a previously allocated managed object? The example above makes it seem like one has a blob of raw bytes and wants it massaged into a managed object (class or value type), is that the case?

[Sergio0694]

"The example above makes it seem like one has a blob of raw bytes and wants it massaged into a managed object (class or value type), is that the case?"

Yup that's correct! The pointer points to some memory (managed or native, could be either) holding the data for a given ABI-type-for-T value. We need to read that and create a boxed object of type ABI-type-for-T, which we can then pass to that Marshaler<T>.FromAbi method, which will convert that to the right T value. Those FromAbi will usually just do something like (ABI-type-for-T)box and then create a T instance from it with the right (generated) marshalling between the two,

So eg. in the example Jeremy posted, we'd use the API like this:

for (int i = 0; i < abi.length; i++)
{
    array[i] = Marshaler<T>.FromAbi(RuntimeHelpers.CreateObjectUnsafe(ref *data, AbiType.TypeHandle);
    data += abi_element_size;
}

[AaronRobinsonMSFT]

olding the data for a given ABI-type-for-T value.

Alright. Based on this statement then, my next assumption would be the memory itself could either be unmanaged (on the native heap) or managed (on the GC heap, pinned of course), but contained no managed references. For example, the following would be an ABI type:

// Unmanaged according to C# language rules
struct ABIType
{
    public int* Data;
    public int Len;
}

Where as the following would not:

// Managed according to C# language rules
struct NotABIType
{
    public int[] Data;
}

[jkotas]

I would expect RuntimeHelpers.CreateObjectUnsafe to behave exactly same as the IL box instruction, except that the type is specified as an argument instead of statically. It has very similar shape as #97344. #97344 is about providing API that behaves exactly same as the IL sizeof instruction, except that the type is specified as an argument instead of statically.