[API Proposal]: Support for Span<T> and ReadOnlySpan<T> in source-generated marshalling

[jkoritzinsky]

Background and motivation

One of the goals of the source-generated marshalling in .NET 7 is to support modern types at interop boundaries. In particular, there has been significant interest in using Span<T> and ReadOnlySpan<T> at interop boundaries. This API proposal includes a number of different Span-based marshallers. This proposal does not include defining any of these marshaller types as the "default" marshallers for span types; however, we can choose to define some of these as defaults if we so desire.

1. SpanMarshaller<T> and ReadOnlySpanMarshaller<T>. These types marshal the span values in the same style as arrays. However, since the Span types treat an empty span as identical to a null span, these types pass null to native code when an empty span is passed as the managed value.
2. NeverNullSpanMarshaller<T> and NeverNullReadOnlySpanMarshaller<T>. These types marshal the span values similarly to SpanMarshaller<T> and ReadOnlySpanMarshaller<T>, but when an empty or null span is passed as a value, the marshaller passes a non-null value to native code that can be dereferenced but should not be written to. This allows developers to opt-in to similar behavior as arrays (where we don't pass null when the input is an empty array, but instead pass a reference to where the zeroth element would live).

We also propose updating the source generator to recognize a static GetPinnableReference method of the same shape as an extension GetPinnableReference method on the marshaller type that takes the managed type. The marshallers will implement this pattern to provide a faster path for by-value P/Invoke scenarios without requiring them to be specified as the default marshallers for the types.

It seems that we want to make the ReadOnlySpanMarshaller and SpanMarshaller types the default marshallers for their respective types. If we want to do so, then we'll add [NativeMarshalling] attributes to the managed types pointing at these marshallers.

API Proposal

namespace System.Runtime.InteropServices.Marshalling
{
    [CustomTypeMarshaller(typeof(ReadOnlySpan<>), CustomTypeMarshallerKind.LinearCollection, Direction = CustomTypeMarshallerDirection.In, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct ReadOnlySpanMarshaller<T>
    {
        public ReadOnlySpanMarshaller(int sizeOfNativeElement);

        public ReadOnlySpanMarshaller(ReadOnlySpan<T> managed, int sizeOfNativeElement);

        public ReadOnlySpanMarshaller(ReadOnlySpan<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<byte> GetNativeValuesDestination();
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public void FreeNative();
        public static ref T GetPinnableReference(ReadOnlySpan<T> managed);
    }

    [CustomTypeMarshaller(typeof(Span<>), CustomTypeMarshallerKind.LinearCollection, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct SpanMarshaller<T>
    {
        public SpanMarshaller(int sizeOfNativeElement);

        public SpanMarshaller(Span<T> managed, int sizeOfNativeElement);

        public SpanMarshaller(Span<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);


        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<T> GetManagedValuesDestination(int length);
        public Span<byte> GetNativeValuesDestination();
        public ReadOnlySpan<byte> GetNativeValuesSource(int length);
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public void FromNativeValue(byte* value);
        public static ref T GetPinnableReference(Span<T> managed);

        public Span<T> ToManaged();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(Span<>), CustomTypeMarshallerKind.LinearCollection, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct NeverNullSpanMarshaller<T>
    {
        public NeverNullSpanMarshaller(int sizeOfNativeElement);

        public NeverNullSpanMarshaller(Span<T> managed, int sizeOfNativeElement);

        public NeverNullSpanMarshaller(Span<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<T> GetManagedValuesDestination(int length);
        public Span<byte> GetNativeValuesDestination();
        public ReadOnlySpan<byte> GetNativeValuesSource(int length);
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public void FromNativeValue(byte* value);
        public static ref T GetPinnableReference(Span<T> managed);

        public Span<T> ToManaged();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(ReadOnlySpan<>), CustomTypeMarshallerKind.LinearCollection, Direction = CustomTypeMarshallerDirection.In, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct NeverNullReadOnlySpanMarshaller<T>
    {
        public NeverNullReadOnlySpanMarshaller(int sizeOfNativeElement);

        public NeverNullReadOnlySpanMarshaller(ReadOnlySpan<T> managed, int sizeOfNativeElement);

        public NeverNullReadOnlySpanMarshaller(ReadOnlySpan<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<byte> GetNativeValuesDestination();
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public static ref T GetPinnableReference(ReadOnlySpan<T> managed);

        public void FreeNative();
    }
}

API Usage

[LibraryImport("MyNativeLib")]
static partial int SumValues([MarshalUsing(typeof(SpanMarshaller<int>))] Span<int> values, int numValues);

Alternative Designs

No response

Risks

As these are new marshallers, we can choose to use different allocators for the native memory if we so choose. However, if we choose an allocator different from the array marshallers, then we break compatibility between array marshallers and span marshallers in the by-ref case (ref Span<T> vs ref T[]). We could add an additional INativeAllocator interface and implementations for our various allocators, and add a second generic parameter to the span marshallers (and the array marshallers if we desire as they haven't shipped yet in an official release) to allow developers to pass in the allocator to use.

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

One of the goals of the source-generated marshalling in .NET 7 is to support modern types at interop boundaries. In particular, there has been significant interest in using Span<T> and ReadOnlySpan<T> at interop boundaries. This API proposal includes a number of different Span-based marshallers. This proposal does not include defining any of these marshaller types as the "default" marshallers for span types; however, we can choose to define some of these as defaults if we so desire.

1. SpanMarshaller<T> and ReadOnlySpanMarshaller<T>. These types marshal the span values in the same style as arrays. However, since the Span types treat an empty span as identical to a null span, these types pass null to native code when an empty span is passed as the managed value.
2. NeverNullSpanMarshaller<T> and NeverNullReadOnlySpanMarshaller<T>. These types marshal the span values similarly to SpanMarshaller<T> and ReadOnlySpanMarshaller<T>, but when an empty or null span is passed as a value, the marshaller passes a non-null sentinel value to native code. This allows developers to opt-in to similar behavior as arrays (where we don't pass null when the input is an empty array).
3. DirectSpanMarshaller<T>. This marshaller only supports Spans of unmanaged element types. When passing a value from managed to unmanaged, this marshaller behaves the same as SpanMarshaller<T>. When passing a value from unmanaged to managed, this marshaller does not copy memory from native code to managed storage; it creates a span directly over the unmanaged memory. It is then the responsibility of the user to free the memory.

API Proposal

namespace System.Runtime.InteropServices.Marshalling
{
    [CustomTypeMarshaller(typeof(ReadOnlySpan<>), CustomTypeMarshallerKind.LinearCollection, Direction = CustomTypeMarshallerDirection.In, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct ReadOnlySpanMarshaller<T>
    {
        public ReadOnlySpanMarshaller(int sizeOfNativeElement);

        public ReadOnlySpanMarshaller(ReadOnlySpan<T> managed, int sizeOfNativeElement);

        public ReadOnlySpanMarshaller(ReadOnlySpan<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<byte> GetNativeValuesDestination();
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(Span<>), CustomTypeMarshallerKind.LinearCollection, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct SpanMarshaller<T>
    {
        public SpanMarshaller(int sizeOfNativeElement);

        public SpanMarshaller(Span<T> managed, int sizeOfNativeElement);

        public SpanMarshaller(Span<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);


        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<T> GetManagedValuesDestination(int length);
        public Span<byte> GetNativeValuesDestination();
        public ReadOnlySpan<byte> GetNativeValuesSource(int length);
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public void FromNativeValue(byte* value);

        public Span<T> ToManaged();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(Span<>), CustomTypeMarshallerKind.LinearCollection, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct NeverNullSpanMarshaller<T>
    {
        public NeverNullSpanMarshaller(int sizeOfNativeElement);

        public NeverNullSpanMarshaller(Span<T> managed, int sizeOfNativeElement);

        public NeverNullSpanMarshaller(Span<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);


        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<T> GetManagedValuesDestination(int length);
        public Span<byte> GetNativeValuesDestination();
        public ReadOnlySpan<byte> GetNativeValuesSource(int length);
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();
        public void FromNativeValue(byte* value);

        public Span<T> ToManaged();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(ReadOnlySpan<>), CustomTypeMarshallerKind.LinearCollection, Direction = CustomTypeMarshallerDirection.In, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0x200)]
    public unsafe ref struct NeverNullReadOnlySpanMarshaller<T>
    {
        public NeverNullReadOnlySpanMarshaller(int sizeOfNativeElement);

        public NeverNullReadOnlySpanMarshaller(ReadOnlySpan<T> managed, int sizeOfNativeElement);

        public NeverNullReadOnlySpanMarshaller(ReadOnlySpan<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<byte> GetNativeValuesDestination();
        public ref byte GetPinnableReference();
        public byte* ToNativeValue();

        public void FreeNative();
    }

    [CustomTypeMarshaller(typeof(Span<>), CustomTypeMarshallerKind.LinearCollection, Features = CustomTypeMarshallerFeatures.UnmanagedResources | CustomTypeMarshallerFeatures.CallerAllocatedBuffer | CustomTypeMarshallerFeatures.TwoStageMarshalling, BufferSize = 0)]
    public unsafe ref struct DirectSpanMarshaller<T>
        where T : unmanaged
    {
        public DirectSpanMarshaller(int sizeOfNativeElement);

        public DirectSpanMarshaller(Span<T> managed, int sizeOfNativeElement);

        public DirectSpanMarshaller(Span<T> managed, Span<byte> stackSpace, int sizeOfNativeElement);

        public ReadOnlySpan<T> GetManagedValuesSource();
        public Span<T> GetManagedValuesDestination(int length);
        public Span<byte> GetNativeValuesDestination();

        public ReadOnlySpan<byte> GetNativeValuesSource(int length);

        public ref T GetPinnableReference();

        public T* ToNativeValue();

        public void FromNativeValue(T* value);

        public Span<T> ToManaged();

        public void FreeNative();
    }
}

API Usage

[LibraryImport("MyNativeLib")]
static partial int SumValues([MarshalUsing(typeof(SpanMarshaller<int>))] Span<int> values, int numValues);

Alternative Designs

No response

Risks

As these are new marshallers, we can choose to use different allocators for the native memory if we so choose. However, if we choose an allocator different from the array marshallers, then we break compatibility between array marshallers and span marshallers in the by-ref case (ref Span<T> vs ref T[]). We could add an additional INativeAllocator interface and implementations for our various allocators, and add a second generic parameter to the span marshallers (and the array marshallers if we desire as they haven't shipped yet in an official release) to allow developers to pass in the allocator to use.

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

[jkoritzinsky]

For the INativeAllocator concept, here's a sketched-out API proposal if we decide to go that route:

namespace System.Runtime.InteropServices.Marshalling;

public unsafe interface INativeAllocator
{
    static abstract void* Alloc(nuint numBytes);
    static abstract void* AlignedAlloc(nuint numBytes, nuint alignment);
    static abstract void Free(void* ptr);
}

public sealed class CoTaskMemAllocator : INativeAllocator
{
    public static void* Alloc(nuint numBytes);
    public static void* AlignedAlloc(nuint numBytes, nuint alignment);
    public static void Free(void* ptr);
}
public sealed class NativeMemoryAllocator : INativeAllocator
{
    public static void* Alloc(nuint numBytes);
    public static void* AlignedAlloc(nuint numBytes, nuint alignment);
    public static void Free(void* ptr);
}
public sealed class HGlobalAllocator : INativeAllocator
{
    public static void* Alloc(nuint numBytes);
    public static void* AlignedAlloc(nuint numBytes, nuint alignment);
    public static void Free(void* ptr);
}

We could also go an instance route with requiring a default constructor if we think there are any use cases for that (memory pooling?).

[jkotas]

Are there examples of uses for each of these marshallers in our own dotnet/runtime libraries?

[jkotas]

Separately, we should introduce marshallers for marshalling ReadOnlySpan<char> as string. There are multiple examples where such marshaller can be used in our own dotnet/runtime libraries. For example, look for ValueUtf8Converter that is used for marshalling ReadOnlySpan<char> as string in some cases today.

[jkotas]

DirectSpanMarshaller. This marshaller only supports Spans of unmanaged element types. When passing a value from managed to unmanaged, this marshaller behaves the same as SpanMarshaller.

Should this marshaller be the default marshaller for Spans and be special-cased to just pin the array in the case of managed to unmanaged marshalling? Same as how arrays work.

[jkoritzinsky]

The interop layers in the crypto stack could heavily use the SpanMarshaller and ReadOnlySpanMarshaller marshallers for some methods where the length is guaranteed to be non-zero (for example Interop.AndroidCrypto.RsaVerificationPrimitive) and the NeverNull variants where zero-length input is valid (ex. ``Interop.AndroidCrypto.RsaPublicEncrypt). They currently call MemoryMarshal.GetReference` manually.

I don't know of any use cases for DirectSpanMarshaller in dotnet/runtime.

I'm concerned about using DirectSpanMarshaller as the default as the behavior around ownership is very different (ownership of the unmanaged memory passes back to the managed user in ref, out, and return scenarios) and the mechanism to get the pointer to release is very obtuse (Unsafe.AsPointer(ref MemoryMarshal.GetReference(span))).

I like the idea of adding a "ReadOnlySpan<char> as a string" marshaller. That seems very useful! (Maybe we should do one for ReadOnlySpan<byte> as a UTF-8 string as well since C# is adding support for UTF-8 string literals?)

[jkotas]

The interop layers in the crypto stack could heavily use the SpanMarshaller and ReadOnlySpanMarshaller marshallers for some methods where the length is guaranteed to be non-zero (for example Interop.AndroidCrypto.RsaVerificationPrimitive)

Is the ReadOnlySpanMarshaller / SpanMarshaller going to be treated as intrinsic in source generator and compile to just fixed statement without actually instantiating the ReadOnlySpanMarshaller / SpanMarshaller?

Do we have any examples of Span marshalling in dotnet/runtime libraries that is not just a simple pinning and that copies the data over or transfers ownership?

I don't know of any use cases for DirectSpanMarshaller in dotnet/runtime.

It suggests that we may not need it.