[API Proposal]: Transparent layout support for value types.

[MichalPetryka]

Background and motivation

Wrapper structs with a single field are popular in many codebases, for SIMD, generics and interop purposes. A common issue with them is that such wrapper types either cause less optimal calling conventions in the 1st case, have issues around wrapping managed types in 2nd, or are not guaranteed to match ABI wise for 3rd.

As such, I'd like to propose exposing support for user defineable value types that guarantee to match the ABI properties of the type they wrap.

This would be enforced both in managed and native calls and would potentially also impact how the JIT treats them for promotion and such.

The runtime would throw TypeLoadException if such type contains more than 1 field.

This was previously discussed in #100896 and was left for future discussion AFAIU.

This is already internally implemented in a limited capacity for CLong`CULong\NFloat`, with public API those could be switched to it from special handling.

For prior art on this, Rust provides this with #[repr(transparent)].

cc @tannergooding @jkoritzinsky @jkotas as you were all involved in previous discussions on this.

API Proposal

namespace System.Runtime.InteropServices;

public enum ExtendedLayoutKind
{
+    Transparent
}

API Usage

// non interop
[ExtendedLayout(ExtendedLayoutKind.Transparent)]
public readonly struct CustomVector
{
    public readonly Vector128<float> Vector;
}

public static void Method(CustomVector v)
{
    // passed via SIMD reg, not stack like normal struct.
}

[ExtendedLayout(ExtendedLayoutKind.Transparent)]
public readonly struct EquatableWrapper<T> : IEquatable<EquatableWrapper<T>>
{
    public readonly T Value;

    public EquatableWrapper(T value) => Value = value;

    public bool Equals(EquatableWrapper<T> other) => EqualityComparer<T>.Default.Equals(Value, other.Value);
    // rest of IEquatable
}

// layouts guaranteed to match
Unsafe.BitCast<ReadOnlySpan<object>, ReadOnlySpan<EquatableWrapper<object>>>(a).Contains(new EquatableWrapper<object>(o))

// interop
[ExtendedLayout(ExtendedLayoutKind.Transparent)]
public readonly struct Handle
{
    public readonly void* Value;
}

// guaranteed to be safe
[DllImport("Kernel32")]
public static extern int CloseHandle(Handle handle);

Alternative Designs

For interop purposes this can be solved with custom LibraryImport marshallers but that doesn't help with blittable PInvokes, function pointers and non interop uses.

Risks

No response

[dotnet-policy-service]

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

[jkotas]

This would be enforced both in managed and native calls

If we do this, it should be strictly about interop and unmanaged calling convention and avoiding the source generated boilerplate.

If the managed calling convention for structs with single field is leaving a perf on the table on architectures where we care about perf, we should fix the managed calling convention. I do not want to see endless stream of micro-optimizations that add this attribute to all structs with a single field.

[hamarb123]

I agree with the above proposal & have a few spots I'd replace [InlineArray(1)] with - just want to point out some issues with the example usage:

• Unsafe.BitCast<ReadOnlySpan<object>, ReadOnlySpan<EquatableWrapper<object>>> this is not the correct way to do this (it is UB), you should be using MemoryMarshal.CreateSpan(ref Unsafe.As<object, EquatableWrapper<object>>(ref MemoryMarshal.GetReference(x)), x.Length) - we could get a safe wrapper that does this specifically for when T == T (up to transparent wrappers) (and throws otherwise) to reduce unsafe in existing code (such as what I have in some stuff) also potentially, in a similar vein to the proposed inline array one.
• In my cases, I usually have a custom Equals/CompareTo/etc. impl that is non-standard, and this is the most optimal way to do it in these cases as it gets stuff inlined (in some cases - some of the APIs expose a non-boxed T comparer parameter, but not all do & that's only relevant for MemoryExtensions cases). For the default impl., it is generally unnecessary (for MemoryExtensions in particular).

[MichalPetryka]

If the managed calling convention for structs with single field is leaving a perf on table on architectures where we care about perf, we should fix the managed calling convention. I do not want to see endless stream of micro-optimizations that add this attribute to all structs with a single field.

AFAIR @tannergooding on multiple occasions said that we don't want to differ between managed and unmanaged calling convention unless absolutely necessary.

[tannergooding]

The consideration is that drastically deviating can trivially hurt perf, especially around interop or suspension points due to shuffling data back and forth

Deviating on whether a given value is passed by register vs implicit byref is normally not such a case due to how slots are allocated

It’s the same reason allowing the managed ABI to always pass SIMD values in register would be “ok” (ie using vectorcall), because it doesn’t fundamentally conflict with the current volatile vs non-volatile sets; nor does it interfere with how registers are “allocated”

[tannergooding]

I agree with Jan that we want to fix the managed ABI where appropriate, that is a general win and we don’t want to see wrapper structs or other things common in .NET annotated with this

I then do still think transparent structs are beneficial for interop and avoiding the complexities of marshaling for something that is very common and useful, especially given the prevalence of typedefs and safety such wrappers can provide. We already hVe some semblance of this support for clong and nfloat anyways, covering both integer and float wrappers, so the JIT support to treat it as the single field it contains when doing interop shouldn’t be overly complex (while still trivially working with disabled marshaling)

[MichalPetryka]

I'm fine with the runtime automatically passing the structs more optimally but the layout guarantee for no padding in memory when wrapping other types would be useful still (ie case 2 here).

[tannergooding]

Can you be more explicit about that case 2? Are you specifically referring to a struct wrapping a managed reference field and it potentially allowing padding, so it not being the same as InlineArray(1)

[MichalPetryka]

Can you be more explicit about that case 2? Are you specifically referring to a struct wrapping a managed reference field and it potentially allowing padding, so it not being the same as InlineArray(1)

Yeah, AFAIR it's currently not guaranteed that sizeof(Wrapper<T>) == sizeof(T).