Introduce `SwiftSelf<T>` and `SwiftIndirectResult` to represent Swift structs and enums in C#

[kotlarmilos]

Background and Motivation

The Swift programming language handles the lifetime of structs and enums differently than .NET. When mapping Swift structs and enums to C# in library evolution mode, frozen Swift structs are directly mapped to C# structs with identical field layouts, while non-frozen Swift structs are mapped to C# classes. To support the projection tooling (#95638) for handling these cases, we need to introduce additional runtime support related to passing and returning structs.

The proposal is to update the built-in support for the Swift ABI and introduce a new Swift-specific type result buffer access mechanism.

Proposed API

According to the Swift calling convention, structs are lowered into a sequence of primitives. If the number of primitives is 4 or less, the struct is passed by value via registers. Otherwise, it is passed by reference in the call context register. The proposal would be to change SwiftSelf to be generic so that a user can pass SwiftSelf<T> for a frozen struct type T which then is either enregistered into multiple registers or passed by reference in the call context register.

Additionally, for Swift functions returning non-frozen structs that are projected into C# classes, it is necessary to load return buffer with a memory address. The proposal would be to add a new Swift type SwiftIndirectResult that would provide access to the return buffer register.

Based on the this, we want to update SwiftSelf to handle frozen structs and add a new Swift type to handle returning non-frozen structs.

namespace System.Runtime.InteropServices.Swift
{
-     public readonly unsafe struct SwiftSelf
+    public readonly struct SwiftSelf<T> where T: unmanaged
     {
-         public SwiftSelf(void* value)
+         public SwiftSelf<T>(T value)
         {
             Value = value;
         }

-         public void* Value { get; }
+         public T Value { get; }
     }
+
+     public readonly unsafe struct SwiftIndirectResult
+     {
+         public SwiftIndirectResult(void* value)
+         {
+             Value = value;
+         }
+
+         public void* Value { get; }
+     }
+ }

Usage Examples

This API would be used by the projection tooling. The SwiftSelf<T> is needed when calling non-mutating instance methods on frozen structs to ensure the correct passing of the value type.

using System;
using System.Runtime.InteropServices;
using System.Runtime.InteropServices.Swift;

public struct Point
{
    public double X { get; }
    public double Y { get; }

    public Point(double x, double y)
    {
        X = x;
        Y = y;
    }

    public double DistanceToOrigin()
    {
        var swiftSelf = new SwiftSelf<Point>(this);
        return distanceFromOrigin(swiftSelf);
    }

    [UnmanagedCallConv(CallConvs = new Type[] { typeof(CallConvSwift) })]
    [DllImport("libSwiftPoint.dylib")]
    private static extern double distanceFromOrigin(SwiftSelf<Point> point);
}

The SwiftIndirectResult is required to enable the tooling to invoke functions that return non-frozen structs. The runtime will load the return buffer prior to the call based on the SwiftIndirectResult value. For simplicity, the class does not implement the IDisposable interface.

using System;
using System.Runtime.InteropServices;
using System.Runtime.InteropServices.Swift;

public class Point
{
    private void* _payload;
    private static readonly int _payloadSize = /* Metadata information from value witness table */;

    public Point(double x, double y)
    {
        _payload = Marshal.AllocHGlobal(_payloadSize).ToPointer();
        try
        {
            PIfunc_init(x, y, new SwiftIndirectResult(_payload));
        }
        catch
        {
            Marshal.FreeHGlobal(new IntPtr(payload));
            throw;
        }
    }

    ~Point()
    {
        if (_payload != null)
        {
            Marshal.FreeHGlobal(_payload);
            _payload = IntPtr.Zero;
        }
    }

    private Point(void* payload)
    {
        _payload = payload;
    }

    public static Point CreateWithMagnitudeAndAngle(double magnitude, double angle)
    {
        void* payload = Marshal.AllocHGlobal(_payloadSize).ToPointer();
        try
        {
            PIfunc_createFromMagnitudeAndAngle(magnitude, angle, new SwiftIndirectResult(payload));
            return new Point(payload);
        }
        catch
        {
            Marshal.FreeHGlobal(new IntPtr(payload));
            throw;
        }
    }

    [UnmanagedCallConv(CallConvs = new Type[] { typeof(CallConvSwift) })]
    [DllImport("libSwiftPoint.dylib", EntryPoint = "PIfunc_init")]
    private static extern void PIfunc_init(double x, double y, SwiftIndirectResult payload);

    [UnmanagedCallConv(CallConvs = new Type[] { typeof(CallConvSwift) })]
    [DllImport("libSwiftPoint.dylib")]
    private static extern void PIfunc_createFromMagnitudeAndAngle(double magnitude, double angle, SwiftIndirectResult payload);
}

Please review the proposal and suggest any updates or changes.

/cc: @dotnet/jit-contrib @dotnet/interop-contrib

[dotnet-policy-service]

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

[lambdageek]

For simplicity, the class does not implement the IDisposable interface.

This confused me. What you mean is the example with the Point class doesn't use IDisposable ? Not that you considered proposing that SwiftIndirectResult should implement IDisposable and decided against it, right?

---

void* payload = Marshal.AllocHGlobal(_payloadSize).ToPointer();
       try
       {
           PIfunc_createFromMagnitudeAndAngle(magnitude, angle, new SwiftIndirectResult(payload));
           return new Point(payload);
       }
       catch
       {
           Marshal.FreeHGlobal(new IntPtr(payload));
          throw;
       }

there's a typo here, right? you mean try/finally, not try/catch ? I misunderstood the example. Sorry.

[DaZombieKiller]

there's a typo here, right? you mean try/finally, not try/catch ?

That would free the memory held by the Point instance that gets returned. I believe the code is using try/catch to prevent a memory leak in the event of PIfunc_createFromMagnitudeAndAngle or the Point constructor throwing, because payload would be left dangling otherwise.

[kotlarmilos]

This confused me. What you mean is the example with the Point class doesn't use IDisposable ? Not that you considered proposing that SwiftIndirectResult should implement IDisposable and decided against it, right?

This proposal does not address any memory management concerns. The Point class can be implemented as IDisposable, but it is not the primary focus of this proposal. For memory management details see dotnet/designs#312.

there's a typo here, right? you mean try/finally, not try/catch ?

The catch block should release memory if the initializer on the Swift side throws an exception.

[stephen-hawley]

swift trivia - it is impossible for a swift init to throw unless it explicitly declares that it does so and even then exceptions in swift are quite different from "normal" exceptions.

Just so I understand - SwiftIndirectResult represents a return value, correct? Does it get handled "out of band" in that it isn't an actual argument, so its position in the pinvoke signature doesn't actually matter?

It might be useful to have an actual void * return value on that constructor so that the difference between a normal constructor and a failable constructor is minor.

example:

public struct WashingMachine {
    // a substantial payload
    public init?(String variety) {
        if (!GlobalInventory.HasVariety (variety)
            return nil
        // initialize the payload
    }
}

In this case you would want to be able to write something like this:

    _payload = Marshal.AllocHGlobal(_payloadSize).ToPointer();
    var result = PIfunc_init((SwiftString)"Bosch", new SwiftIndirectResult(payload));
    if (_payload != result) {
        Marshal.FreeHGlobal(new IntPtr(_payload));
        _payload = null;
        // handle however we feel best.
    }

[kotlarmilos]

Just so I understand - SwiftIndirectResult represents a return value, correct? Does it get handled "out of band" in that it isn't an actual argument, so its position in the pinvoke signature doesn't actually matter?

It represents a value that is stored in the return buffer and it will be handled in a similar way to SwiftSelf. The position in the signature doesn't matter, but for simplicity, we may decide to impose certain positional limitations.

It might be useful to have an actual void * return value on that constructor so that the difference between a normal constructor and a failable constructor is minor.

Can we utilize SwiftError in this case?

    _payload = Marshal.AllocHGlobal(_payloadSize).ToPointer();
    var swifterror = new SwiftError();
    var result = PIfunc_init((SwiftString)"Bosch", new SwiftIndirectResult(payload), ref swifterror);
    if (swifterror.Value != null) {
        Marshal.FreeHGlobal(new IntPtr(_payload));
        _payload = null;
        // handle however we feel best.
    }

Edit: The above can work only for throwing constructor, not failable constructor.

[jakobbotsch]

From what I see from some examples, it looks like failable initializers are modelled as functions that return optional values in Swift. The projection tooling will need to model it similarly.

https://godbolt.org/z/3jhn7vqsT

I think we should make it illegal to have anything but a void return in signatures that include SwiftIndirectResult. These functions don't return in the normal way.

[kotlarmilos]

From what I see from some examples, it looks like failable initializers are modelled as functions that return optional values in Swift. The projection tooling will need to model it similarly.

Ok. Does this imply that functions returning optional value types always pass results by reference, even though they fit into the lowering sequence?

[jakobbotsch]

From what I see from some examples, it looks like failable initializers are modelled as functions that return optional values in Swift. The projection tooling will need to model it similarly.

Ok. Does this imply that functions returning optional value types always pass results by reference, even though they fit into the lowering sequence?

No -- take a look at the Failable3 example in that godbolt link -- its init? returns in registers.