GH-33856: [C#] Implement C Data Interface for C#

csharp/src/Apache.Arrow/Arrays/ArrowArrayFactory.cs

@@ -25,6 +25,8 @@ public static IArrowArray BuildArray(ArrayData data)
         {
             switch (data.DataType.TypeId)
             {
+                case ArrowTypeId.Null:
+                    return new NullArray(data);
                 case ArrowTypeId.Boolean:
                     return new BooleanArray(data);
                 case ArrowTypeId.UInt8:

csharp/src/Apache.Arrow/Arrays/NullArray.cs

@@ -0,0 +1,42 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License.  You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Apache.Arrow.Types;
+
+namespace Apache.Arrow
+{
+    public class NullArray : IArrowArray
+    {
+        public ArrayData Data { get; }
+
+        public NullArray(ArrayData data)
+        {
+            data.EnsureDataType(ArrowTypeId.Null);
+            data.EnsureBufferCount(0);
+        }
+
+        public int Length => Data.Length;
+
+        public int Offset => Data.Offset;
+
+        public int NullCount => Data.NullCount;
+
+        public void Dispose() { }
+        public bool IsNull(int index) => true;
+        public bool IsValid(int index) => false;
+
+        public void Accept(IArrowArrayVisitor visitor) => throw new System.NotImplementedException();
+    }
+}

csharp/src/Apache.Arrow/ArrowBuffer.cs

@@ -72,5 +72,24 @@ public void Dispose()
         {
             _memoryOwner?.Dispose();
         }
+
+        internal bool TryExport(ExportedAllocationOwner newOwner, out IntPtr ptr)
+        {
+            if (_memoryOwner == null && IsEmpty)
+            {
+                ptr = IntPtr.Zero;
+                return true;
+            }
+
+            if (_memoryOwner is IOwnableAllocation ownable && ownable.TryAcquire(out ptr, out int offset, out int length))
+            {
+                newOwner.Acquire(ptr, offset, length);
+                ptr += offset;
+                return true;
+            }
+
+            ptr = IntPtr.Zero;
+            return false;
+        }
     }
 }

csharp/src/Apache.Arrow/C/CArrowArray.cs

@@ -0,0 +1,84 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+using System;
+using System.Runtime.InteropServices;
+
+namespace Apache.Arrow.C
+{
+    /// <summary>
+    /// An Arrow C Data Interface Schema, which represents the data in an exported array or record batch.
+    /// </summary>
+    /// <remarks>
+    /// This is used to export <see cref="RecordBatch"/> or <see cref="IArrowArray"/> to other languages. It matches
+    /// the layout of the ArrowArray struct described in https://github.com/apache/arrow/blob/main/cpp/src/arrow/c/abi.h.
+    /// </remarks>
+    [StructLayout(LayoutKind.Sequential)]
+    public unsafe struct CArrowArray
+    {
+        public long length;
+        public long null_count;
+        public long offset;
+        public long n_buffers;
+        public long n_children;
+        public byte** buffers;
+        public CArrowArray** children;
+        public CArrowArray* dictionary;
+        public delegate* unmanaged[Stdcall]<CArrowArray*, void> release;
+        public void* private_data;
+
+        /// <summary>
+        /// Allocate and zero-initialize an unmanaged pointer of this type.
+        /// </summary>
+        /// <remarks>
+        /// This pointer must later be freed by <see cref="Free"/>.
+        /// </remarks>
+        public static CArrowArray* Create()
+        {
+            var ptr = (CArrowArray*)Marshal.AllocHGlobal(sizeof(CArrowArray));
+
+            ptr->length = 0;
+            ptr->n_buffers = 0;
+            ptr->offset = 0;
+            ptr->buffers = null;
+            ptr->n_children = 0;
+            ptr->children = null;
+            ptr->dictionary = null;
+            ptr->null_count = 0;
+            ptr->release = null;
+            ptr->private_data = null;
+
+            return ptr;
+        }
+
+        /// <summary>
+        /// Free a pointer that was allocated in <see cref="Create"/>.
+        /// </summary>
+        /// <remarks>
+        /// Do not call this on a pointer that was allocated elsewhere.
+        /// </remarks>
+        public static void Free(CArrowArray* schema)
+        {
+            if (schema->release != null)
+            {
+                // Call release if not already called.
+                schema->release(schema);
+            }
+            Marshal.FreeHGlobal((IntPtr)schema);
+        }
+    }
+}

csharp/src/Apache.Arrow/C/CArrowArrayExporter.cs

@@ -0,0 +1,210 @@
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License.  You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+
+using System;
+using System.Runtime.InteropServices;
+using Apache.Arrow.Memory;
+
+namespace Apache.Arrow.C
+{
+    public static class CArrowArrayExporter
+    {
+        private unsafe delegate void ReleaseArrowArray(CArrowArray* cArray);
+
+        /// <summary>
+        /// Export an <see cref="IArrowArray"/> to a <see cref="CArrowArray"/>. Whether or not the
+        /// export succeeds, the original array becomes invalid. Clone an array to continue using it
+        /// after a copy has been exported.
+        /// </summary>
+        /// <param name="array">The array to export</param>
+        /// <param name="cArray">An allocated but uninitialized CArrowArray pointer.</param>
+        /// <example>
+        /// <code>
+        /// CArrowArray* exportPtr = CArrowArray.Create();
+        /// CArrowArrayExporter.ExportArray(array, exportPtr);
+        /// foreign_import_function(exportPtr);
+        /// </code>
+        /// </example>
+        public static unsafe void ExportArray(IArrowArray array, CArrowArray* cArray)
+        {
+            if (array == null)
+            {
+                throw new ArgumentNullException(nameof(array));
+            }
+            if (cArray == null)
+            {
+                throw new ArgumentNullException(nameof(cArray));
+            }
+            if (cArray->release != null)
+            {
+                throw new ArgumentException("Cannot export array to a struct that is already initialized.", nameof(cArray));
+            }
+
+            ExportedAllocationOwner allocationOwner = new ExportedAllocationOwner();
+            try
+            {
+                ConvertArray(allocationOwner, array.Data, cArray);
+                cArray->release = (delegate* unmanaged[Stdcall]<CArrowArray*, void>)Marshal.GetFunctionPointerForDelegate<ReleaseArrowArray>(ReleaseArray);
+                cArray->private_data = FromDisposable(allocationOwner);
+                allocationOwner = null;
+            }
+            finally
+            {
+                allocationOwner?.Dispose();
+            }
+        }
+
+        /// <summary>
+        /// Export a <see cref="RecordBatch"/> to a <see cref="CArrowArray"/>. Whether or not the
+        /// export succeeds, the original record batch becomes invalid. Clone the batch to continue using it
+        /// after a copy has been exported.
+        /// </summary>
+        /// <param name="batch">The record batch to export</param>
+        /// <param name="cArray">An allocated but uninitialized CArrowArray pointer.</param>
+        /// <example>
+        /// <code>
+        /// CArrowArray* exportPtr = CArrowArray.Create();
+        /// CArrowArrayExporter.ExportRecordBatch(batch, exportPtr);
+        /// foreign_import_function(exportPtr);
+        /// </code>
+        /// </example>
+        public static unsafe void ExportRecordBatch(RecordBatch batch, CArrowArray* cArray)
+        {
+            if (batch == null)
+            {
+                throw new ArgumentNullException(nameof(batch));
+            }
+            if (cArray == null)
+            {
+                throw new ArgumentNullException(nameof(cArray));
+            }
+            if (cArray->release != null)
+            {
+                throw new ArgumentException("Cannot export array to a struct that is already initialized.", nameof(cArray));
+            }
+
+            ExportedAllocationOwner allocationOwner = new ExportedAllocationOwner();
+            try
+            {
+                ConvertRecordBatch(allocationOwner, batch, cArray);
+                cArray->release = (delegate* unmanaged[Stdcall]<CArrowArray*, void>)Marshal.GetFunctionPointerForDelegate<ReleaseArrowArray>(ReleaseArray);
+                cArray->private_data = FromDisposable(allocationOwner);
+                allocationOwner = null;
+            }
+            finally
+            {
+                allocationOwner?.Dispose();
+            }
+        }
+
+        private unsafe static void ConvertArray(ExportedAllocationOwner sharedOwner, ArrayData array, CArrowArray* cArray)
+        {
+            cArray->length = array.Length;
+            cArray->offset = array.Offset;
+            cArray->null_count = array.NullCount;
+            cArray->release = (delegate* unmanaged[Stdcall]<CArrowArray*, void>)Marshal.GetFunctionPointerForDelegate<ReleaseArrowArray>(ReleaseArray);
+            cArray->private_data = null;
+
+            cArray->n_buffers = array.Buffers?.Length ?? 0;
+            cArray->buffers = null;
+            if (cArray->n_buffers > 0)
+            {
+                cArray->buffers = (byte**)Marshal.AllocCoTaskMem(array.Buffers.Length * IntPtr.Size);
+                for (int i = 0; i < array.Buffers.Length; i++)
+                {
+                    ArrowBuffer buffer = array.Buffers[i];
+                    IntPtr ptr;
+                    if (!buffer.TryExport(sharedOwner, out ptr))
+                    {
+                        throw new NotSupportedException(); // TODO
+                    }
+                    cArray->buffers[i] = (byte*)ptr;
+                }
+            }
+
+            cArray->n_children = array.Children?.Length ?? 0;
+            cArray->children = null;
+            if (cArray->n_children > 0)
+            {
+                cArray->children = (CArrowArray**)Marshal.AllocCoTaskMem(IntPtr.Size * array.Children.Length);
+                for (int i = 0; i < array.Children.Length; i++)
+                {
+                    cArray->children[i] = CArrowArray.Create();
+                    ConvertArray(sharedOwner, array.Children[i], cArray->children[i]);
+                }
+            }
+
+            cArray->dictionary = null;
+            if (array.Dictionary != null)
+            {
+                cArray->dictionary = CArrowArray.Create();
+                ConvertArray(sharedOwner, array.Dictionary, cArray->dictionary);
+            }
+        }
+
+        private unsafe static void ConvertRecordBatch(ExportedAllocationOwner sharedOwner, RecordBatch batch, CArrowArray* cArray)
+        {
+            cArray->length = batch.Length;
+            cArray->offset = 0;
+            cArray->null_count = 0;
+            cArray->release = (delegate* unmanaged[Stdcall]<CArrowArray*, void>)Marshal.GetFunctionPointerForDelegate<ReleaseArrowArray>(ReleaseArray);
+            cArray->private_data = null;
+
+            cArray->n_buffers = 1;
+            cArray->buffers = (byte**)Marshal.AllocCoTaskMem(IntPtr.Size);
+
+            cArray->n_children = batch.ColumnCount;
+            cArray->children = null;
+            if (cArray->n_children > 0)
+            {
+                cArray->children = (CArrowArray**)Marshal.AllocCoTaskMem(IntPtr.Size * batch.ColumnCount);
+                int i = 0;
+                foreach (IArrowArray child in batch.Arrays)
+                {
+                    cArray->children[i] = CArrowArray.Create();
+                    ConvertArray(sharedOwner, child.Data, cArray->children[i]);
+                    i++;
+                }
+            }
+
+            cArray->dictionary = null;
+        }
+
+        private unsafe static void ReleaseArray(CArrowArray* cArray)
+        {
+            if (cArray->private_data != null)
+            {
+                Dispose(&cArray->private_data);
+            }
+            cArray->private_data = null;
+            cArray->release = null;
+        }
+
+        private unsafe static void* FromDisposable(IDisposable disposable)
+        {
+            GCHandle gch = GCHandle.Alloc(disposable);
+            return (void*)GCHandle.ToIntPtr(gch);
+        }
+
+        private unsafe static void Dispose(void** ptr)
+        {
+            GCHandle gch = GCHandle.FromIntPtr((IntPtr)(*ptr));
+            ((IDisposable)gch.Target).Dispose();
+            gch.Free();
+            *ptr = null;
+        }
+    }
+}