[Swift Bindings] Implement Swift native handle as SafeHandle

[kotlarmilos]

Description

To ensure thread safety and delegate Swift handle release to the native handler, SwiftHandle implements SafeHandle for a native Swift handle. Frozen structs that require memory management contain a TypeBuffer struct is passed at the P/Invoke boundary, while a corresponding SwiftHandle performs C# reference counting for the type.

Swift frozen structs that require memory management are projected as C# classes:

class SwiftStruct
{
        [StructLayout(LayoutKind.Sequential, Size = 12)]
        public unsafe struct TypeBuffer
        {
           ...
        }
        private TypeBuffer _buffer;
        public SwiftHandle Payload => _payload;
}

Swift non-frozen structs that require memory management are projected as C# classes:

class SwiftStruct
{
        public SwiftHandle Payload => _payload;
}

When Dispose is called on these types, _payload.Dispose is invoked, which calls the ValueWitnessTable->Destroy function to free native resource.

Changes

• Implemented SwiftHandle as SafeHandle

• Added reference counting around P/Invoke calls using DangerousAddRef and DangerousRelease

  • Instance methods retain and release the internal SwiftHandle _payload
  • For frozen struct arguments, explicit retain/release is performed
  • For non-frozen struct arguments, SwiftHandle is passed at the P/Invoke boundary with internal retain/release; the .NET runtime automatically manages reference counting at P/Invoke boundary
  • For generic arguments, a local Swift copy is made, so no C# retain/release is performed

• Updated MarshalToSwift and MarshalFromSwift to reflect the new SwiftHandle implementation

• MarshalToSwift updated to check for buffer overruns

• Removed the explicit Destroy call from the type's Dispose method

• Ensured SwiftHandle release resources by calling _metadata.ValueWitnessTable->Destroy only after all references are released

• Updated manual bindings to reflect the SwiftHandle implementation

Out of scope

Structs projected as C# classes do not require explicit Dispose methods or finalizers, since the GC can call Dispose of the SafeHandle when the object is collected. Projecting frozen value types as structs is a UX decision and will not be made in this PR.

Fixes #3018 #2975 #2974 #2851

[Copilot]

Copilot reviewed 31 out of 31 changed files in this pull request and generated 1 comment.

[AaronRobinsonMSFT]

This looks good. I'd update the PayloadBuffer as suggested in a comment and then LGTM.

Thanks!