This implements #284 (#285)

* This implements #284
Removed `ref struct` restriction on DIBuilder

* DIBuilders is now a class with an unowned alias interface `IDIBuilder`
* Applied LazyEncodedString in  some more places to enable use of utf8 literals to provide pre-encoded literal strings

* Removed infinite recursion in implicit operator
- VS IDE hides stack overflow errors and make it look like things all passed unless you look very carefully for it.
    - A crash in the tests should show up as a total fail of the tests, but it doesn't. It just shows up as a count of errors that is easily overlooked.

Author: smaillet

IgnoredWords.dic

@@ -86,6 +86,7 @@ malloc
 marshallers
 marshalling
 memcopy
+memcpy
 metadata
 Mips
 msbuild

src/Interop/Ubiquity.NET.Llvm.Interop/ABI/libllvm-c/MetadataBindings.cs

@@ -220,7 +220,7 @@ public static partial class MetadataBindings
 
         [MethodImpl( MethodImplOptions.AggressiveInlining )]
         public static LLVMMetadataRef LibLLVMDIBuilderCreateTempFunctionFwdDecl(
-            LLVMDIBuilderRef D,
+            LLVMDIBuilderRefAlias D,
             LLVMMetadataRef Scope,
             LazyEncodedString Name,
             LazyEncodedString LinkageName,
@@ -255,7 +255,7 @@ bool isOptimized
         [LibraryImport( LibraryName )]
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
         private static unsafe partial LLVMMetadataRef LibLLVMDIBuilderCreateTempFunctionFwdDecl(
-            LLVMDIBuilderRef D,
+            LLVMDIBuilderRefAlias D,
             LLVMMetadataRef Scope,
             LazyEncodedString Name, nuint NameLen,
             LazyEncodedString LinkageName, nuint LinkageNameLen,
@@ -271,7 +271,7 @@ private static unsafe partial LLVMMetadataRef LibLLVMDIBuilderCreateTempFunction
 
         [LibraryImport( LibraryName )]
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]
-        public static unsafe partial void LibLLVMDIBuilderFinalizeSubProgram( LLVMDIBuilderRef dref, LLVMMetadataRef subProgram );
+        public static unsafe partial void LibLLVMDIBuilderFinalizeSubProgram( LLVMDIBuilderRefAlias dref, LLVMMetadataRef subProgram );
 
         [LibraryImport( LibraryName )]
         [UnmanagedCallConv( CallConvs = [ typeof( CallConvCdecl ) ] )]

src/Interop/Ubiquity.NET.Llvm.Interop/ABI/llvm-c/DebugInfo.cs

@@ -0,0 +1,58 @@
+// -----------------------------------------------------------------------
+// <copyright file="LLVMDiBuilderRefAlias.cs" company="Ubiquity.NET Contributors">
+// Copyright (c) Ubiquity.NET Contributors. All rights reserved.
+// </copyright>
+// -----------------------------------------------------------------------
+
+namespace Ubiquity.NET.Llvm.Interop
+{
+    /// <summary>Simple type safe handle to wrap an opaque pointer</summary>
+    /// <remarks>
+    /// This is a specialized form of an alias, it is NOT inherent in the LLVM APIs
+    /// as no LLVM objects own a DIBuilder, but many consumers will. This allows for
+    /// consistency in the ownership consideration of a given DIBuilder instance.
+    /// </remarks>
+    [NativeMarshalling(typeof(ContextHandleMarshaller<LLVMDIBuilderRefAlias>))]
+    public readonly record struct LLVMDIBuilderRefAlias
+        : IContextHandle<LLVMDIBuilderRefAlias>
+    {
+        /// <summary>Gets a value indicating whether this handle is a <see langword="null"/> value</summary>
+        public bool IsNull => Handle == nint.Zero;
+
+        /// <summary>Gets the handle as an <see cref="nint"/> suitable for passing to native code</summary>
+        /// <returns>The handle as an <see cref="nint"/></returns>
+        public nint DangerousGetHandle() => Handle;
+
+        public IntPtr ToIntPtr() => Handle;
+
+        /// <summary>Interface defined factory for an instance of <see cref="LLVMDIBuilderRefAlias"/></summary>
+        /// <param name="abiValue">Native ABI value of the handle</param>
+        /// <returns>Type specific wrapper around the native ABI handle</returns>
+        public static LLVMDIBuilderRefAlias FromABI(nint abiValue) => new(abiValue);
+
+        /// <summary>Gets a zero (<see langword="null"/>) value handle</summary>
+        public static LLVMDIBuilderRefAlias Zero => FromABI(nint.Zero);
+
+        /// <summary>Gets the handle as an <see cref="nint"/> suitable for passing to native code</summary>
+        /// <param name="value">Handle to convert</param>
+        /// <returns>The handle as an <see cref="nint"/></returns>
+        public static implicit operator nint(LLVMDIBuilderRefAlias value) => value.Handle;
+
+        public static LLVMDIBuilderRefAlias From( LLVMDIBuilderRefAlias self )
+        {
+            self.ThrowIfInvalid();
+            return FromABI(self.DangerousGetHandle());
+        }
+
+        // define implicit conversion from an OWNED value
+        [SuppressMessage( "Usage", "CA2225:Operator overloads have named alternates", Justification = "Exists, tooling is too stupid to see it" )]
+        public static implicit operator LLVMDIBuilderRefAlias( LLVMDIBuilderRef other ) => FromABI( other.DangerousGetHandle() );
+
+        private LLVMDIBuilderRefAlias( nint p )
+        {
+            Handle = p;
+        }
+
+        private readonly nint Handle;
+    }
+}

src/Interop/Ubiquity.NET.Llvm.Interop/LLVMDiBuilderRefAlias.cs

@@ -89,10 +89,10 @@ public static void Main( string[] args )
 
             #region CreatingBasicTypesWithDebugInfo
             // Create basic types used in this compilation
-            var i32 = new DebugBasicType( module.Context.Int32Type, in diBuilder, "int", DiTypeKind.Signed );
-            var f32 = new DebugBasicType( module.Context.FloatType, in diBuilder, "float", DiTypeKind.Float );
+            var i32 = new DebugBasicType( module.Context.Int32Type, diBuilder, "int", DiTypeKind.Signed );
+            var f32 = new DebugBasicType( module.Context.FloatType, diBuilder, "float", DiTypeKind.Float );
             var voidType = DebugType.Create( module.Context.VoidType, (DIType?)null );
-            var i32Array_0_32 = i32.CreateArrayType( in diBuilder, 0, 32 );
+            var i32Array_0_32 = i32.CreateArrayType( diBuilder, 0, 32 );
             #endregion
 
             #region CreatingStructureTypes
@@ -104,7 +104,7 @@ public static void Main( string[] args )
                     new( 2, "c", diFile, 5, i32Array_0_32 ),
                 };
 
-            var fooType = new DebugStructType( in diBuilder, "struct.foo", compilationUnit, "foo", diFile, 1, DebugInfoFlags.None, fooBody );
+            var fooType = new DebugStructType( diBuilder, "struct.foo", compilationUnit, "foo", diFile, 1, DebugInfoFlags.None, fooBody );
             #endregion
 
             #region CreatingGlobalsAndMetadata
@@ -133,17 +133,17 @@ public static void Main( string[] args )
             #region CreatingQualifiedTypes
             // create types for function args
             var constFoo = diBuilder.CreateQualifiedType( fooType.DebugInfoType, QualifiedTypeTag.Const );
-            var fooPtr = new DebugPointerType( fooType, in diBuilder );
+            var fooPtr = new DebugPointerType( fooType, diBuilder );
             #endregion
 
             // Create the functions
             // NOTE: The declaration ordering is reversed from that of the sample code file (test.c)
             //       However, this is what Clang ends up doing for some reason so it is
             //       replicated here to aid in comparing the generated LL files.
-            Function doCopyFunc = DeclareDoCopyFunc( in diBuilder, diFile, voidType, abiAttributes );
-            Function copyFunc = DeclareCopyFunc(targetABI, in diBuilder, diFile, voidType, constFoo, fooPtr, abiAttributes );
+            Function doCopyFunc = DeclareDoCopyFunc( diBuilder, diFile, voidType, abiAttributes );
+            Function copyFunc = DeclareCopyFunc(targetABI, diBuilder, diFile, voidType, constFoo, fooPtr, abiAttributes );
 
-            CreateCopyFunctionBody( in diBuilder, copyFunc, diFile, fooType, fooPtr, constFoo );
+            CreateCopyFunctionBody( diBuilder, copyFunc, diFile, fooType, fooPtr, constFoo );
             CreateDoCopyFunctionBody( module, doCopyFunc, fooType, bar, baz, copyFunc );
 
             // finalize the debug information
@@ -185,16 +185,16 @@ private static void ShowUsage( )
 
         #region FunctionDeclarations
         private static Function DeclareDoCopyFunc(
-            ref readonly DIBuilder diBuilder,
+            DIBuilder diBuilder,
             DIFile diFile,
             IDebugType<ITypeRef, DIType> voidType,
             IEnumerable<AttributeValue> abiAttributes
             )
         {
             var module = diBuilder.OwningModule;
-            var doCopySig = module.Context.CreateFunctionType( in diBuilder, voidType );
+            var doCopySig = module.Context.CreateFunctionType( diBuilder, voidType );
 
-            var doCopyFunc = module.CreateFunction( in diBuilder
+            var doCopyFunc = module.CreateFunction( diBuilder
                                                   , scope: diFile
                                                   , name: "DoCopy"
                                                   , linkageName: null
@@ -212,7 +212,7 @@ IEnumerable<AttributeValue> abiAttributes
         }
 
         private static Function DeclareCopyFunc( ITargetABI abi
-                                               , ref readonly DIBuilder diBuilder
+                                               , DIBuilder diBuilder
                                                , DIFile diFile
                                                , IDebugType<ITypeRef, DIType> voidType
                                                , DIDerivedType constFoo
@@ -230,13 +230,13 @@ private static Function DeclareCopyFunc( ITargetABI abi
             // To get the correct debug info signature this inserts an
             // explicit DebugType<> that overrides the default behavior
             // to pair the LLVM pointer type with the original source type.
-            var copySig = module.Context.CreateFunctionType( in diBuilder
+            var copySig = module.Context.CreateFunctionType( diBuilder
                                                            , voidType
                                                            , DebugType.Create( fooPtr, constFoo )
                                                            , fooPtr
                                                            );
 
-            var copyFunc = module.CreateFunction( in diBuilder
+            var copyFunc = module.CreateFunction( diBuilder
                                                 , scope: diFile
                                                 , name: "copy"
                                                 , linkageName: null
@@ -268,7 +268,7 @@ private static void AddModuleFlags( ITargetABI abi, Module module, ILibLlvm libr
         }
         #endregion
 
-        private static void CreateCopyFunctionBody( ref readonly DIBuilder diBuilder
+        private static void CreateCopyFunctionBody( DIBuilder diBuilder
                                                   , Function copyFunc
                                                   , DIFile diFile
                                                   , ITypeRef foo