From 7162ad61b58ef3494139b52c5c574ae401753d54 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 01/15] Make ExtensionTypeRegistry.Clone copy-on-write Clone now shares the definitions with the original registry and copies them only when either registry is next modified. Taking a snapshot, as every ArrowContext does of the default registry, therefore costs almost nothing, and a snapshot never observes later changes to the registry it was taken from. Each registry has its own lock object, since the dictionary it guards can now be replaced. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ExtensionTypeRegistry.cs | 61 +++++-- .../ExtensionTypeRegistryTests.cs | 172 ++++++++++++++++++ 2 files changed, 219 insertions(+), 14 deletions(-) create mode 100644 test/Apache.Arrow.Tests/ExtensionTypeRegistryTests.cs diff --git a/src/Apache.Arrow/ExtensionTypeRegistry.cs b/src/Apache.Arrow/ExtensionTypeRegistry.cs index b9737e39..c7603854 100644 --- a/src/Apache.Arrow/ExtensionTypeRegistry.cs +++ b/src/Apache.Arrow/ExtensionTypeRegistry.cs @@ -32,7 +32,16 @@ public class ExtensionTypeRegistry /// public static ExtensionTypeRegistry Default => s_default; - private readonly Dictionary _definitions; + // Guards _definitions and _shared. A separate object is needed because copy-on-write + // replaces the dictionary, so it cannot serve as its own lock. + private readonly object _lock = new object(); + + private Dictionary _definitions; + + // True when _definitions may also be referenced by a clone (or by the registry this + // one was cloned from). A shared dictionary is never modified: whichever registry + // mutates first copies it, so every registry sees the contents it had when cloned. + private bool _shared; public ExtensionTypeRegistry() { @@ -41,7 +50,8 @@ public ExtensionTypeRegistry() private ExtensionTypeRegistry(Dictionary definitions) { - _definitions = new Dictionary(definitions); + _definitions = definitions; + _shared = true; } /// @@ -50,9 +60,9 @@ private ExtensionTypeRegistry(Dictionary definition public void Register(ExtensionDefinition definition) { if (definition == null) throw new ArgumentNullException(nameof(definition)); - lock (_definitions) + lock (_lock) { - _definitions[definition.ExtensionName] = definition; + GetWritableDefinitions()[definition.ExtensionName] = definition; } } @@ -63,14 +73,15 @@ public void Register(ExtensionDefinition definition) public IDisposable RegisterTemporary(ExtensionDefinition definition) { if (definition == null) throw new ArgumentNullException(nameof(definition)); - lock (_definitions) + lock (_lock) { - if (!_definitions.TryGetValue(definition.ExtensionName, out ExtensionDefinition previousDefinition)) + Dictionary definitions = GetWritableDefinitions(); + if (!definitions.TryGetValue(definition.ExtensionName, out ExtensionDefinition previousDefinition)) { previousDefinition = null; } IDisposable scope = new Registration(this, definition.ExtensionName, previousDefinition); - _definitions[definition.ExtensionName] = definition; + definitions[definition.ExtensionName] = definition; return scope; } } @@ -81,9 +92,9 @@ public IDisposable RegisterTemporary(ExtensionDefinition definition) public void Unregister(ExtensionDefinition definition) { if (definition == null) throw new ArgumentNullException(nameof(definition)); - lock (_definitions) + lock (_lock) { - _definitions.Remove(definition.ExtensionName); + GetWritableDefinitions().Remove(definition.ExtensionName); } } @@ -92,7 +103,7 @@ public void Unregister(ExtensionDefinition definition) /// public bool TryGetDefinition(string extensionName, out ExtensionDefinition definition) { - lock (_definitions) + lock (_lock) { return _definitions.TryGetValue(extensionName, out definition); } @@ -101,14 +112,35 @@ public bool TryGetDefinition(string extensionName, out ExtensionDefinition defin /// /// Create a snapshot copy of this registry. /// + /// + /// The snapshot reflects this registry's contents at the time of the call; later changes + /// to either registry do not affect the other. The copy is made lazily, by whichever + /// registry is modified first, so cloning a registry that is never modified is cheap. + /// public ExtensionTypeRegistry Clone() { - lock (_definitions) + lock (_lock) { + _shared = true; return new ExtensionTypeRegistry(_definitions); } } + /// + /// Returns a dictionary that only this registry references, copying a shared one first. + /// Must be called while holding . + /// + private Dictionary GetWritableDefinitions() + { + if (_shared) + { + _definitions = new Dictionary(_definitions); + _shared = false; + } + + return _definitions; + } + sealed class Registration : IDisposable { private readonly ExtensionTypeRegistry _registry; @@ -127,15 +159,16 @@ public Registration( public void Dispose() { - lock (_registry._definitions) + lock (_registry._lock) { + Dictionary definitions = _registry.GetWritableDefinitions(); if (_previousDefinition == null) { - _registry._definitions.Remove(_extensionName); + definitions.Remove(_extensionName); } else { - _registry._definitions[_previousDefinition.ExtensionName] = _previousDefinition; + definitions[_previousDefinition.ExtensionName] = _previousDefinition; } } } diff --git a/test/Apache.Arrow.Tests/ExtensionTypeRegistryTests.cs b/test/Apache.Arrow.Tests/ExtensionTypeRegistryTests.cs new file mode 100644 index 00000000..4344d468 --- /dev/null +++ b/test/Apache.Arrow.Tests/ExtensionTypeRegistryTests.cs @@ -0,0 +1,172 @@ +// 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.Threading.Tasks; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Tests that produces a snapshot: it shares storage + /// until one side is modified, but neither side ever observes the other's later changes. + /// + public class ExtensionTypeRegistryTests + { + [Fact] + public void CloneIsUnaffectedByLaterChangesToOriginal() + { + TestDefinition kept = new TestDefinition("kept"); + TestDefinition removed = new TestDefinition("removed"); + TestDefinition added = new TestDefinition("added"); + ExtensionTypeRegistry original = new ExtensionTypeRegistry(); + original.Register(kept); + original.Register(removed); + + ExtensionTypeRegistry clone = original.Clone(); + original.Unregister(removed); + original.Register(added); + original.Register(new TestDefinition("kept")); + + Assert.Same(kept, Get(clone, "kept")); + Assert.Same(removed, Get(clone, "removed")); + Assert.Null(Get(clone, "added")); + } + + [Fact] + public void OriginalIsUnaffectedByChangesToClone() + { + TestDefinition definition = new TestDefinition("a"); + ExtensionTypeRegistry original = new ExtensionTypeRegistry(); + original.Register(definition); + + ExtensionTypeRegistry clone = original.Clone(); + clone.Unregister(definition); + clone.Register(new TestDefinition("b")); + + Assert.Same(definition, Get(original, "a")); + Assert.Null(Get(original, "b")); + } + + [Fact] + public void ClonesOfClonesAreIndependent() + { + ExtensionTypeRegistry original = new ExtensionTypeRegistry(); + original.Register(new TestDefinition("a")); + ExtensionTypeRegistry first = original.Clone(); + ExtensionTypeRegistry second = first.Clone(); + + first.Register(new TestDefinition("first")); + second.Register(new TestDefinition("second")); + original.Register(new TestDefinition("original")); + + Assert.NotNull(Get(first, "first")); + Assert.Null(Get(first, "second")); + Assert.Null(Get(first, "original")); + Assert.NotNull(Get(second, "second")); + Assert.Null(Get(second, "first")); + Assert.Null(Get(original, "first")); + Assert.Null(Get(original, "second")); + Assert.NotNull(Get(second, "a")); + } + + [Fact] + public void TemporaryRegistrationAcrossCloneRestoresOnlyItsOwnRegistry() + { + TestDefinition permanent = new TestDefinition("x"); + TestDefinition temporary = new TestDefinition("x"); + ExtensionTypeRegistry original = new ExtensionTypeRegistry(); + original.Register(permanent); + + IDisposable scope = original.RegisterTemporary(temporary); + ExtensionTypeRegistry clone = original.Clone(); + scope.Dispose(); + + Assert.Same(permanent, Get(original, "x")); + Assert.Same(temporary, Get(clone, "x")); + } + + [Fact] + public void ContextSnapshotsDefaultRegistryAtConstruction() + { + string name = "snapshot-" + Guid.NewGuid(); + TestDefinition before = new TestDefinition(name + "-before"); + TestDefinition after = new TestDefinition(name + "-after"); + ExtensionTypeRegistry.Default.Register(before); + try + { + ArrowContext context = new ArrowContext(); + + ExtensionTypeRegistry.Default.Unregister(before); + ExtensionTypeRegistry.Default.Register(after); + + // The context sees Default as it was when the context was created. + Assert.Same(before, Get(context.ExtensionRegistry, before.ExtensionName)); + Assert.Null(Get(context.ExtensionRegistry, after.ExtensionName)); + } + finally + { + ExtensionTypeRegistry.Default.Unregister(before); + ExtensionTypeRegistry.Default.Unregister(after); + } + } + + [Fact] + public void ConcurrentClonesAndRegistrationsAreSafe() + { + ExtensionTypeRegistry original = new ExtensionTypeRegistry(); + + Parallel.For(0, 2000, i => + { + if (i % 2 == 0) + { + original.Register(new TestDefinition("d" + i)); + } + else + { + ExtensionTypeRegistry clone = original.Clone(); + clone.Register(new TestDefinition("c" + i)); + Assert.NotNull(Get(clone, "c" + i)); + } + }); + + for (int i = 0; i < 2000; i += 2) + { + Assert.NotNull(Get(original, "d" + i)); + } + for (int i = 1; i < 2000; i += 2) + { + Assert.Null(Get(original, "c" + i)); + } + } + + private static ExtensionDefinition Get(ExtensionTypeRegistry registry, string name) => + registry.TryGetDefinition(name, out ExtensionDefinition definition) ? definition : null; + + private sealed class TestDefinition : ExtensionDefinition + { + public TestDefinition(string name) => ExtensionName = name; + + public override string ExtensionName { get; } + + public override bool TryCreateType(IArrowType storageType, string metadata, out ExtensionType type) + { + type = null; + return false; + } + } + } +} From 1d20aababb8e19706c69607759c2eff57e9faaea Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 02/15] Add opt-in allocators with explicit lifetimes Adds MemoryAllocator.Lifetime, which says what happens to a buffer that is never disposed, and three allocators that users can opt into: - ManagedMemoryAllocator: plain managed arrays. Spans keep their memory alive and disposal releases nothing, which avoids the hazard in #397 without requiring disposal. - PooledManagedAllocator: managed arrays kept for reuse, bounded by PooledManagedAllocatorOptions (largest pooled size, arrays per size, total bytes), with an option to poison disposed buffers so that use after disposal is visible. - CallerOwnedNativeAllocator: aligned native memory with no finalizer (NativeMemory on .NET 6+). Buffers must be disposed. SharedMemoryHandle keeps its finalizer for allocators whose lifetime is Finalized, so the default allocator and existing custom allocators behave as before; other lifetimes opt out of release by collection. Also adds a virtual MemoryAllocator.Resize, and fixes #50: NativeMemoryAllocator now removes exactly the memory pressure it added when its alignment is not the default. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/Memory/AllocationLifetime.cs | 65 ++++ .../Memory/CallerOwnedNativeAllocator.cs | 134 ++++++++ .../Memory/ManagedMemoryAllocator.cs | 70 ++++ src/Apache.Arrow/Memory/MemoryAllocator.cs | 48 +++ .../Memory/NativeMemoryAllocator.cs | 38 ++- .../Memory/PooledManagedAllocator.cs | 299 ++++++++++++++++++ .../Memory/PooledManagedAllocatorOptions.cs | 77 +++++ src/Apache.Arrow/Memory/SharedMemoryHandle.cs | 11 + src/Apache.Arrow/Memory/SharedMemoryOwner.cs | 11 + 9 files changed, 748 insertions(+), 5 deletions(-) create mode 100644 src/Apache.Arrow/Memory/AllocationLifetime.cs create mode 100644 src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs create mode 100644 src/Apache.Arrow/Memory/ManagedMemoryAllocator.cs create mode 100644 src/Apache.Arrow/Memory/PooledManagedAllocator.cs create mode 100644 src/Apache.Arrow/Memory/PooledManagedAllocatorOptions.cs diff --git a/src/Apache.Arrow/Memory/AllocationLifetime.cs b/src/Apache.Arrow/Memory/AllocationLifetime.cs new file mode 100644 index 00000000..a9071973 --- /dev/null +++ b/src/Apache.Arrow/Memory/AllocationLifetime.cs @@ -0,0 +1,65 @@ +// 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. + +namespace Apache.Arrow.Memory +{ + /// + /// Describes what happens to a buffer produced by a + /// if the consumer never disposes it. + /// + /// + /// + /// This describes a correctness contract, not a performance strategy. Disposing a + /// buffer is always at least as fast as not disposing it, whatever the value here. + /// + /// + /// Whatever the lifetime, a span over a buffer must not be used after the buffer is + /// disposed: disposal may free the memory or make it available for reuse. The values + /// here describe only what happens to a buffer that is never disposed. + /// + /// + public enum AllocationLifetime + { + /// + /// Memory is reclaimed by the garbage collector, so disposal is optional. A span over + /// a buffer that has not been disposed keeps the memory alive while the span is in use. + /// + /// + /// An allocator that pools memory makes a disposed buffer's memory available to later + /// allocations, so using a span after disposal can read or overwrite another buffer's + /// data. does not pool, so with it a span stays + /// valid even after disposal. + /// + GarbageCollected, + + /// + /// Memory is leaked unless the consumer disposes the buffer. A span over the buffer + /// is valid until disposal, and is never invalidated by garbage collection. + /// + CallerOwned, + + /// + /// Memory is reclaimed by a finalizer. Disposal is optional, but a span over the + /// buffer does not keep it alive, so the memory may be freed while the span is + /// still in use. + /// + /// + /// Provided for compatibility with the historical behaviour of + /// . See + /// https://github.com/apache/arrow-dotnet/issues/397. + /// + Finalized, + } +} diff --git a/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs new file mode 100644 index 00000000..a34fe6d4 --- /dev/null +++ b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs @@ -0,0 +1,134 @@ +// 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.Buffers; +using System.Runtime.InteropServices; +using System.Threading; + +namespace Apache.Arrow.Memory +{ + /// + /// Allocates aligned native memory that the caller is responsible for releasing. + /// + /// + /// + /// Unlike , buffers from this allocator have no + /// finalizer. Memory is released only by disposal, so it can never be freed while a + /// span over it is still in use, and no GC memory pressure is reported because the + /// garbage collector plays no part in reclaiming it. + /// + /// + /// The corresponding obligation is that a buffer which is never disposed is leaked for + /// the lifetime of the process. Use this allocator when buffers need a stable, aligned + /// address — interop and explicitly aligned paths — and disposal can be guaranteed. + /// + /// + public sealed unsafe class CallerOwnedNativeAllocator : MemoryAllocator + { + public CallerOwnedNativeAllocator(int alignment = DefaultAlignment) + : base(alignment) + { + if (alignment <= 0 || (alignment & (alignment - 1)) != 0) + { + throw new ArgumentOutOfRangeException(nameof(alignment), "Alignment must be a positive power of two."); + } + } + + public override AllocationLifetime Lifetime => AllocationLifetime.CallerOwned; + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { +#if NET6_0_OR_GREATER + int offset = 0; + void* ptr = NativeMemory.AlignedAlloc((nuint)length, (nuint)Alignment); + if (ptr == null) + { + throw new OutOfMemoryException($"NativeMemory.AlignedAlloc({length}, {Alignment}) returned null."); + } +#else + void* ptr = AlignedNative.AlignedAlloc(length, Alignment, out int offset); +#endif + new Span((byte*)ptr + offset, length).Clear(); + + bytesAllocated = length + Alignment; + return new CallerOwnedMemoryManager(ptr, offset, length); + } + + /// + /// A over native memory with no finalizer, so that + /// reachability never determines when the memory is freed (CA2015). + /// + private sealed class CallerOwnedMemoryManager : MemoryManager + { + private readonly int _offset; + private readonly int _length; + private IntPtr _ptr; + + public CallerOwnedMemoryManager(void* ptr, int offset, int length) + { + _ptr = (IntPtr)ptr; + _offset = offset; + _length = length; + } + + public override Span GetSpan() + { + IntPtr ptr = Volatile.Read(ref _ptr); + if (ptr == IntPtr.Zero) + { + throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); + } + + return new Span((byte*)ptr + _offset, _length); + } + + public override MemoryHandle Pin(int elementIndex = 0) + { + if (elementIndex < 0 || elementIndex > _length) + { + throw new ArgumentOutOfRangeException(nameof(elementIndex)); + } + + IntPtr ptr = Volatile.Read(ref _ptr); + if (ptr == IntPtr.Zero) + { + throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); + } + + // Native memory does not move, so there is nothing to pin; the handle + // holds a reference to this manager so the memory stays reachable. + return new MemoryHandle((byte*)ptr + _offset + elementIndex, default, this); + } + + public override void Unpin() + { + } + + protected override void Dispose(bool disposing) + { + IntPtr ptr = Interlocked.Exchange(ref _ptr, IntPtr.Zero); + if (ptr != IntPtr.Zero) + { +#if NET6_0_OR_GREATER + NativeMemory.AlignedFree((void*)ptr); +#else + AlignedNative.AlignedFree((void*)ptr); +#endif + } + } + } + } +} diff --git a/src/Apache.Arrow/Memory/ManagedMemoryAllocator.cs b/src/Apache.Arrow/Memory/ManagedMemoryAllocator.cs new file mode 100644 index 00000000..79a1c3b3 --- /dev/null +++ b/src/Apache.Arrow/Memory/ManagedMemoryAllocator.cs @@ -0,0 +1,70 @@ +// 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.Buffers; + +namespace Apache.Arrow.Memory +{ + /// + /// Allocates plain managed arrays, with no pooling. + /// + /// + /// + /// This is the simplest allocator to use safely. Buffers are reclaimed by the garbage + /// collector, a span over a buffer keeps its array alive while the span is in use, and + /// disposal releases nothing, so even a span used after its buffer has been disposed still + /// sees that buffer's data. It avoids the hazard described in + /// https://github.com/apache/arrow-dotnet/issues/397 without requiring disposal. + /// + /// + /// The costs are those of ordinary managed allocation: every buffer is a new array, arrays + /// of 85,000 bytes or more are allocated on the large object heap, and memory is aligned + /// only to the pointer size rather than to the 64 bytes the Arrow format recommends. Use + /// to reuse arrays, at the price of having to stop + /// using a buffer's spans once it is disposed. + /// + /// + public sealed class ManagedMemoryAllocator : MemoryAllocator + { + /// + /// The instance used as temporary memory by builders that are not given an allocator. + /// + internal static readonly ManagedMemoryAllocator Instance = new ManagedMemoryAllocator(); + + public ManagedMemoryAllocator() + : base(IntPtr.Size) + { + } + + public override AllocationLifetime Lifetime => AllocationLifetime.GarbageCollected; + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + bytesAllocated = length; + return new ArrayOwner(new byte[length]); + } + + private sealed class ArrayOwner : IMemoryOwner + { + public ArrayOwner(byte[] array) => Memory = array; + + public Memory Memory { get; private set; } + + // The array is collected by the GC; disposal only stops further use of this owner. + public void Dispose() => Memory = Memory.Empty; + } + } +} diff --git a/src/Apache.Arrow/Memory/MemoryAllocator.cs b/src/Apache.Arrow/Memory/MemoryAllocator.cs index 44df09be..69d8e998 100644 --- a/src/Apache.Arrow/Memory/MemoryAllocator.cs +++ b/src/Apache.Arrow/Memory/MemoryAllocator.cs @@ -25,8 +25,23 @@ public abstract class MemoryAllocator private static IMemoryOwner NullMemoryOwner { get; } = new NullMemoryOwner(); + /// + /// The allocator used wherever none is passed explicitly: a + /// with the default alignment. It cannot be replaced; to use a different allocator, pass + /// it to the builder, reader, writer or operation that allocates. + /// public static Lazy Default { get; } = new Lazy(BuildDefault, true); + /// + /// Describes what happens to buffers from this allocator that are never disposed. + /// + /// + /// Defaults to so that allocators written + /// against earlier versions of this type continue to describe themselves + /// conservatively. Implementations should override this. + /// + public virtual AllocationLifetime Lifetime => AllocationLifetime.Finalized; + public class Stats { private long _bytesAllocated; @@ -71,6 +86,39 @@ public IMemoryOwner Allocate(int length) return memoryOwner; } + /// + /// Returns a buffer of bytes containing the contents of + /// , and releases . + /// + /// + /// The default implementation allocates, copies and releases. Allocators backed by a + /// native heap that supports reallocation can override this to grow in place. This + /// exists so that buffer builders can grow through the allocator rather than + /// allocating managed scratch space that the allocator never sees. + /// + public virtual IMemoryOwner Resize(IMemoryOwner owner, int newLength) + { + if (owner == null) + { + throw new ArgumentNullException(nameof(owner)); + } + + if (newLength < 0) + { + throw new ArgumentOutOfRangeException(nameof(newLength)); + } + + IMemoryOwner resized = Allocate(newLength); + int copyLength = Math.Min(owner.Memory.Length, newLength); + if (copyLength > 0) + { + owner.Memory.Slice(0, copyLength).CopyTo(resized.Memory); + } + + owner.Dispose(); + return resized; + } + private static MemoryAllocator BuildDefault() { return new NativeMemoryAllocator(DefaultAlignment); diff --git a/src/Apache.Arrow/Memory/NativeMemoryAllocator.cs b/src/Apache.Arrow/Memory/NativeMemoryAllocator.cs index bbe934c4..ebb56efa 100644 --- a/src/Apache.Arrow/Memory/NativeMemoryAllocator.cs +++ b/src/Apache.Arrow/Memory/NativeMemoryAllocator.cs @@ -21,10 +21,32 @@ namespace Apache.Arrow.Memory { public class NativeMemoryAllocator : MemoryAllocator { - internal static readonly INativeAllocationOwner ExclusiveOwner = new NativeAllocationOwner(); + internal static readonly INativeAllocationOwner ExclusiveOwner = new NativeAllocationOwner(DefaultAlignment); + + // Releases memory and removes exactly the pressure that was added for it, which includes + // this allocator's alignment padding (https://github.com/apache/arrow-dotnet/issues/50). + private readonly NativeAllocationOwner _owner; public NativeMemoryAllocator(int alignment = DefaultAlignment) - : base(alignment) { } + : base(alignment) + { + _owner = alignment == DefaultAlignment + ? (NativeAllocationOwner)ExclusiveOwner + : new NativeAllocationOwner(alignment); + } + + /// The number of bytes of memory pressure reported for an allocation. + internal static int PressureBytes(int length, int alignment) => length + alignment; + + internal int ReleasedPressureBytes(int length) => _owner.PressureBytes(length); + + /// + /// Buffers from this allocator are released by 's + /// finalizer when they are not disposed, which means a span over one of them can be + /// invalidated while still in use. See + /// https://github.com/apache/arrow-dotnet/issues/397. + /// + public override AllocationLifetime Lifetime => AllocationLifetime.Finalized; protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) { @@ -38,9 +60,9 @@ protected override IMemoryOwner AllocateInternal(int length, out int bytes int size = length + Alignment; IntPtr ptr = Marshal.AllocHGlobal(size); int offset = (int)(Alignment - (ptr.ToInt64() & (Alignment - 1))); - var manager = new NativeMemoryManager(ptr, offset, length); + var manager = new NativeMemoryManager(_owner, ptr, offset, length); - bytesAllocated = (length + Alignment); + bytesAllocated = PressureBytes(length, Alignment); GC.AddMemoryPressure(bytesAllocated); @@ -52,10 +74,16 @@ protected override IMemoryOwner AllocateInternal(int length, out int bytes private sealed class NativeAllocationOwner : INativeAllocationOwner { + private readonly int _alignment; + + public NativeAllocationOwner(int alignment) => _alignment = alignment; + + public int PressureBytes(int length) => NativeMemoryAllocator.PressureBytes(length, _alignment); + public void Release(IntPtr ptr, int offset, int length) { Marshal.FreeHGlobal(ptr); - GC.RemoveMemoryPressure(length + DefaultAlignment); // See https://github.com/apache/arrow-dotnet/issues/50 + GC.RemoveMemoryPressure(PressureBytes(length)); } } } diff --git a/src/Apache.Arrow/Memory/PooledManagedAllocator.cs b/src/Apache.Arrow/Memory/PooledManagedAllocator.cs new file mode 100644 index 00000000..f2b7a932 --- /dev/null +++ b/src/Apache.Arrow/Memory/PooledManagedAllocator.cs @@ -0,0 +1,299 @@ +// 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.Buffers; +using System.Threading; + +namespace Apache.Arrow.Memory +{ + /// + /// Allocates buffers from the garbage-collected heap, keeping disposed buffers' arrays for + /// reuse so that allocating repeatedly does not have to create new arrays. + /// + /// + /// + /// A span over a buffer from this allocator keeps its array alive, so a buffer that is never + /// disposed is simply collected, and disposal is optional. But disposal hands the array back + /// for reuse: a span used after its buffer was disposed can read or overwrite the data of + /// whichever buffer reuses the array. If that contract is a concern, use + /// , which never reuses arrays, or set + /// to make such bugs visible. + /// + /// + /// How much memory is kept for reuse is bounded by ; + /// allocations larger than are not + /// pooled. Memory is aligned only to the pointer size, and may be moved by the garbage + /// collector; code that needs a stable, 64-byte-aligned address should pin the memory or use + /// . + /// + /// + public sealed class PooledManagedAllocator : MemoryAllocator + { + /// The largest allocation that can be configured to be pooled: 1 GiB. + internal const int LargestPoolableLength = 1 << 30; + + private const int MinimumArrayLength = 16; + private const byte PoisonByte = 0xDE; + + private readonly int _maxPooledLength; + private readonly long _maxRetainedBytes; + private readonly bool _poison; + private readonly Bucket[] _buckets; + private long _retainedBytes; + + public PooledManagedAllocator() + : this(new PooledManagedAllocatorOptions()) + { + } + + public PooledManagedAllocator(PooledManagedAllocatorOptions options) + : base(IntPtr.Size) + { + if (options == null) + { + throw new ArgumentNullException(nameof(options)); + } + + options.Validate(); + _maxPooledLength = options.MaxPooledLength; + _maxRetainedBytes = options.MaxRetainedBytes; + _poison = options.PoisonDisposedBuffers; + + // One bucket per power-of-two size from MinimumArrayLength up to the size that holds + // the largest pooled allocation. No bucket allocates anything until it is used. + int bucketCount = _maxPooledLength == 0 ? 0 : BucketIndex(_maxPooledLength) + 1; + _buckets = new Bucket[bucketCount]; + for (int i = 0; i < bucketCount; i++) + { + _buckets[i] = new Bucket(MinimumArrayLength << i, options.MaxArraysPerSize); + } + } + + public override AllocationLifetime Lifetime => AllocationLifetime.GarbageCollected; + + /// The number of bytes currently held for reuse. + internal long RetainedBytes => Interlocked.Read(ref _retainedBytes); + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + byte[] buffer = Rent(length, out bool reused); + + // A reused array holds an earlier buffer's data, and Arrow buffers are expected to + // start zeroed. A new array is zeroed already. + if (reused) + { + new Span(buffer, 0, length).Clear(); + } + + bytesAllocated = length; + return new PooledMemoryOwner(this, buffer, length); + } + + /// + /// Grows or shrinks a buffer, zeroing only the region past the copied data. The base + /// implementation zeroes the whole new buffer and then copies over most of it, which + /// doubles the write traffic on append-heavy paths. + /// + public override IMemoryOwner Resize(IMemoryOwner owner, int newLength) + { + if (owner == null) + { + throw new ArgumentNullException(nameof(owner)); + } + + if (newLength < 0) + { + throw new ArgumentOutOfRangeException(nameof(newLength)); + } + + if (newLength == 0) + { + owner.Dispose(); + return Allocate(0); + } + + byte[] buffer = Rent(newLength, out bool reused); + ReadOnlyMemory existing = owner.Memory; + int copyLength = Math.Min(existing.Length, newLength); + + if (copyLength > 0) + { + existing.Slice(0, copyLength).CopyTo(new Memory(buffer, 0, copyLength)); + } + + if (reused) + { + new Span(buffer, copyLength, newLength - copyLength).Clear(); + } + + owner.Dispose(); + Statistics.Allocate(newLength); + return new PooledMemoryOwner(this, buffer, newLength); + } + + private byte[] Rent(int length, out bool reused) + { + if (length > _maxPooledLength) + { + reused = false; + return new byte[length]; + } + + Bucket bucket = _buckets[BucketIndex(length)]; + byte[] buffer = bucket.TryTake(); + if (buffer != null) + { + Interlocked.Add(ref _retainedBytes, -buffer.Length); + reused = true; + return buffer; + } + + reused = false; + return new byte[bucket.ArrayLength]; + } + + private void Return(byte[] buffer) + { + if (_poison) + { + buffer.AsSpan().Fill(PoisonByte); + } + + // Only arrays of exactly a bucket's size are pooled; anything else (including + // allocations too large to pool) is left for the garbage collector. The size check + // must come first: BucketIndex is only defined up to the largest bucket's size. + int length = buffer.Length; + if (_buckets.Length == 0 || length > _buckets[_buckets.Length - 1].ArrayLength) + { + return; + } + + int index = BucketIndex(length); + if (_buckets[index].ArrayLength != length) + { + return; + } + + // Reserve room under the byte limit before pooling, and give it back if the array + // is not kept after all. + if (Interlocked.Add(ref _retainedBytes, length) > _maxRetainedBytes || !_buckets[index].TryAdd(buffer)) + { + Interlocked.Add(ref _retainedBytes, -length); + } + } + + /// + /// The index of the smallest bucket whose arrays hold bytes. + /// Only valid for lengths up to . + /// + private static int BucketIndex(int length) + { + int index = 0; + int size = MinimumArrayLength; + while (size < length) + { + size <<= 1; + index++; + } + + return index; + } + + /// A bounded stack of arrays of one size. + private sealed class Bucket + { + private readonly byte[][] _arrays; + private int _count; + + public Bucket(int arrayLength, int capacity) + { + ArrayLength = arrayLength; + _arrays = new byte[capacity][]; + } + + public int ArrayLength { get; } + + public byte[] TryTake() + { + lock (_arrays) + { + if (_count == 0) + { + return null; + } + + byte[] array = _arrays[--_count]; + _arrays[_count] = null; + return array; + } + } + + public bool TryAdd(byte[] array) + { + lock (_arrays) + { + if (_count == _arrays.Length) + { + return false; + } + + _arrays[_count++] = array; + return true; + } + } + } + + private sealed class PooledMemoryOwner : IMemoryOwner + { + private readonly PooledManagedAllocator _allocator; + private readonly int _length; + private byte[] _buffer; + + public PooledMemoryOwner(PooledManagedAllocator allocator, byte[] buffer, int length) + { + _allocator = allocator; + _buffer = buffer; + _length = length; + } + + public Memory Memory + { + get + { + byte[] buffer = Volatile.Read(ref _buffer); + if (buffer == null) + { + throw new ObjectDisposedException(nameof(PooledMemoryOwner)); + } + + // Pooled arrays are a power of two in size, so usually larger than asked for. + return new Memory(buffer, 0, _length); + } + } + + // No finalizer. An undisposed buffer is collected by the GC like any other array; + // it is simply not returned to the pool. + public void Dispose() + { + byte[] buffer = Interlocked.Exchange(ref _buffer, null); + if (buffer != null) + { + _allocator.Return(buffer); + } + } + } + } +} diff --git a/src/Apache.Arrow/Memory/PooledManagedAllocatorOptions.cs b/src/Apache.Arrow/Memory/PooledManagedAllocatorOptions.cs new file mode 100644 index 00000000..c5972c56 --- /dev/null +++ b/src/Apache.Arrow/Memory/PooledManagedAllocatorOptions.cs @@ -0,0 +1,77 @@ +// 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; + +namespace Apache.Arrow.Memory +{ + /// + /// Controls how much memory a keeps for reuse. + /// + /// + /// The pool keeps arrays in sizes that are powers of two. With the defaults it holds at most + /// 16 arrays of each size up to 1 MiB, which bounds the memory it retains to about 32 MiB. + /// Larger allocations are not pooled: they get a new array, which is collected normally once + /// it is no longer used. + /// + public sealed class PooledManagedAllocatorOptions + { + public const int DefaultMaxPooledLength = 1024 * 1024; + public const int DefaultMaxArraysPerSize = 16; + + /// + /// The largest allocation, in bytes, that is served from the pool. Larger allocations + /// get a new, unpooled array. + /// + public int MaxPooledLength { get; set; } = DefaultMaxPooledLength; + + /// + /// The most arrays of any one size that the pool keeps for reuse. + /// + public int MaxArraysPerSize { get; set; } = DefaultMaxArraysPerSize; + + /// + /// The most bytes the pool keeps for reuse, across all sizes. Unlimited by default, since + /// and already bound it. + /// + public long MaxRetainedBytes { get; set; } = long.MaxValue; + + /// + /// Overwrites each buffer with a recognizable pattern (0xDE) when it is disposed. This + /// makes a span that is wrongly used after its buffer was disposed read obvious garbage, + /// rather than data that looks plausible. Intended for finding such bugs; off by default. + /// + public bool PoisonDisposedBuffers { get; set; } + + internal void Validate() + { + if (MaxPooledLength < 0 || MaxPooledLength > PooledManagedAllocator.LargestPoolableLength) + { + throw new ArgumentOutOfRangeException(nameof(MaxPooledLength), + $"Must be between 0 and {PooledManagedAllocator.LargestPoolableLength}."); + } + + if (MaxArraysPerSize < 0) + { + throw new ArgumentOutOfRangeException(nameof(MaxArraysPerSize), "Must not be negative."); + } + + if (MaxRetainedBytes < 0) + { + throw new ArgumentOutOfRangeException(nameof(MaxRetainedBytes), "Must not be negative."); + } + } + } +} diff --git a/src/Apache.Arrow/Memory/SharedMemoryHandle.cs b/src/Apache.Arrow/Memory/SharedMemoryHandle.cs index be2e14dc..c5a146d5 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryHandle.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryHandle.cs @@ -25,6 +25,13 @@ internal sealed class SharedMemoryHandle : IMemoryOwner public SharedMemoryHandle(SharedMemoryOwner owner) { _owner = owner ?? throw new ArgumentNullException(nameof(owner)); + + if (!owner.FinalizeWhenUnreachable) + { + // The memory came from an allocator whose Lifetime is not Finalized, which + // opts out of release by collection: see the finalizer below. + GC.SuppressFinalize(this); + } } public Memory Memory => _owner.Memory; @@ -40,6 +47,10 @@ public void Dispose() GC.SuppressFinalize(this); } + // Releases buffers that were never disposed, as it always has. Doing so lets the GC + // decide when memory is freed or recycled, which can invalidate a span that is still in + // use (https://github.com/apache/arrow-dotnet/issues/397), so allocators can opt out by + // reporting a Lifetime other than Finalized; existing allocators keep this behaviour. ~SharedMemoryHandle() { Release(); diff --git a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs index 522d5e23..718a5ba8 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs @@ -26,7 +26,13 @@ internal sealed class SharedMemoryOwner private int _refCount; public SharedMemoryOwner(IMemoryOwner inner) + : this(inner, finalizeWhenUnreachable: true) { + } + + public SharedMemoryOwner(IMemoryOwner inner, bool finalizeWhenUnreachable) + { + FinalizeWhenUnreachable = finalizeWhenUnreachable; _inner = inner ?? throw new ArgumentNullException(nameof(inner)); _memory = inner.Memory; _refCount = 1; @@ -34,6 +40,11 @@ public SharedMemoryOwner(IMemoryOwner inner) public Memory Memory => _memory; + /// + /// Whether handles to this memory release it from a finalizer when they are not disposed. + /// + public bool FinalizeWhenUnreachable { get; } + public SharedMemoryHandle Retain() { while (true) From 4bc49458cc87f44d30f8beddba9cadebd2a29f26 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 03/15] Let builders allocate through an allocator and hand over their memory A builder given an allocator grows its working memory in that allocator and hands it to the array it builds instead of copying it, so a builder created with its final capacity allocates exactly once. A builder given no allocator behaves exactly as before: it grows in managed memory and copies once into MemoryAllocator.Default when built. - Buffer and array builders take an optional allocator; constructors that already shipped are unchanged. Fixed-width builders also get capacity constructors and GetSpan/Advance for writing values in bulk. - Array builders are now IDisposable, which matters only for caller-owned allocators. - Child builders, the RecordBatch column helpers, Clone, the run-end concatenation path and variant shredding all build in the allocator their result belongs to. - The validity bitmap of a primitive builder is created only when the first null is appended. - Fixes the builder factory ignoring a timestamp element type's unit and time zone. Co-Authored-By: Claude Opus 5.5 --- .../Shredding/ShreddedVariantArrayBuilder.cs | 44 +- .../Arrays/ArrayDataConcatenator.cs | 10 +- .../Arrays/ArrowArrayBuilderFactory.cs | 77 +-- src/Apache.Arrow/Arrays/BinaryArray.cs | 48 +- src/Apache.Arrow/Arrays/BinaryViewArray.cs | 48 +- src/Apache.Arrow/Arrays/Bool8Array.cs | 17 + src/Apache.Arrow/Arrays/BooleanArray.cs | 42 +- src/Apache.Arrow/Arrays/Date32Array.cs | 17 + src/Apache.Arrow/Arrays/Date64Array.cs | 17 + src/Apache.Arrow/Arrays/Decimal128Array.cs | 15 + src/Apache.Arrow/Arrays/Decimal256Array.cs | 15 + src/Apache.Arrow/Arrays/Decimal32Array.cs | 15 + src/Apache.Arrow/Arrays/Decimal64Array.cs | 15 + .../Arrays/DelegatingArrayBuilder.cs | 24 +- src/Apache.Arrow/Arrays/DoubleArray.cs | 17 + src/Apache.Arrow/Arrays/DurationArray.cs | 16 + .../Arrays/FixedSizeBinaryArray.cs | 34 +- src/Apache.Arrow/Arrays/FixedSizeListArray.cs | 63 ++- src/Apache.Arrow/Arrays/FloatArray.cs | 17 + src/Apache.Arrow/Arrays/GuidArray.cs | 13 + src/Apache.Arrow/Arrays/HalfFloatArray.cs | 17 + src/Apache.Arrow/Arrays/Int16Array.cs | 17 + src/Apache.Arrow/Arrays/Int32Array.cs | 17 + src/Apache.Arrow/Arrays/Int64Array.cs | 17 + src/Apache.Arrow/Arrays/Int8Array.cs | 17 + src/Apache.Arrow/Arrays/IntervalArray.cs | 49 ++ src/Apache.Arrow/Arrays/LargeBinaryArray.cs | 48 +- src/Apache.Arrow/Arrays/LargeListArray.cs | 64 ++- src/Apache.Arrow/Arrays/LargeListViewArray.cs | 67 ++- src/Apache.Arrow/Arrays/LargeStringArray.cs | 11 + src/Apache.Arrow/Arrays/ListArray.cs | 64 ++- src/Apache.Arrow/Arrays/ListViewArray.cs | 67 ++- src/Apache.Arrow/Arrays/MapArray.cs | 49 +- .../Arrays/PrimitiveArrayBuilder.cs | 178 ++++++- src/Apache.Arrow/Arrays/StringArray.cs | 11 + src/Apache.Arrow/Arrays/StringViewArray.cs | 11 + src/Apache.Arrow/Arrays/Time32Array.cs | 19 + src/Apache.Arrow/Arrays/Time64Array.cs | 19 + src/Apache.Arrow/Arrays/TimestampArray.cs | 23 + .../Arrays/TimestampWithOffsetArray.cs | 46 +- src/Apache.Arrow/Arrays/UInt16Array.cs | 17 + src/Apache.Arrow/Arrays/UInt32Array.cs | 17 + src/Apache.Arrow/Arrays/UInt64Array.cs | 17 + src/Apache.Arrow/Arrays/UInt8Array.cs | 17 + src/Apache.Arrow/Arrays/VariantArray.cs | 52 +- src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs | 86 +++- src/Apache.Arrow/ArrowBuffer.Builder.cs | 144 +++++- src/Apache.Arrow/ArrowBuffer.cs | 24 +- src/Apache.Arrow/Memory/BuilderMemory.cs | 267 ++++++++++ src/Apache.Arrow/Memory/SlicedMemoryOwner.cs | 44 ++ src/Apache.Arrow/RecordBatch.Builder.cs | 78 +-- test/Apache.Arrow.Tests/AllocatorTests.cs | 483 ++++++++++++++++++ .../ArrowArrayConcatenatorTests.cs | 6 +- .../BuilderHandOverTests.cs | 431 ++++++++++++++++ .../DefaultAllocationBehaviorTests.cs | 196 +++++++ 55 files changed, 3011 insertions(+), 243 deletions(-) create mode 100644 src/Apache.Arrow/Memory/BuilderMemory.cs create mode 100644 src/Apache.Arrow/Memory/SlicedMemoryOwner.cs create mode 100644 test/Apache.Arrow.Tests/AllocatorTests.cs create mode 100644 test/Apache.Arrow.Tests/BuilderHandOverTests.cs create mode 100644 test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs diff --git a/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs b/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs index 3428fa18..8b8143d3 100644 --- a/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs +++ b/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs @@ -83,7 +83,7 @@ public static VariantArray Build( // metadata column: emit the shared bytes once per row. (A dictionary-encoded // or run-end-encoded representation would compress this; VariantArray's reader // already handles those, but for simplicity we emit the plain binary form.) - BinaryArray.Builder metadataBuilder = new BinaryArray.Builder(); + using BinaryArray.Builder metadataBuilder = new BinaryArray.Builder(BinaryType.Default, allocator); for (int i = 0; i < rowCount; i++) { metadataBuilder.Append((ReadOnlySpan)metadata); @@ -125,7 +125,7 @@ public static VariantArray Build( private static BinaryArray BuildBinaryColumn(IReadOnlyList rows, MemoryAllocator allocator) { - BinaryArray.Builder b = new BinaryArray.Builder(); + using BinaryArray.Builder b = new BinaryArray.Builder(BinaryType.Default, allocator); foreach (ShredResult r in rows) { if (r.Value == null) b.AppendNull(); @@ -189,9 +189,9 @@ private static ListArray BuildArrayTyped( { int rowCount = typedValues.Count; List flatElements = new List(); - ArrowBuffer.Builder offsets = new ArrowBuffer.Builder(); + using ArrowBuffer.Builder offsets = new ArrowBuffer.Builder(0, allocator); offsets.Append(0); - ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(); + using ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(0, allocator); int nullCount = 0; foreach (object tv in typedValues) @@ -246,7 +246,7 @@ private static StructArray BuildElementGroupArray( } // Outer slot validity: non-null iff the slot isn't "missing" (both columns null). - ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(); + using ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(0, allocator); int nullCount = 0; foreach (ShredResult r in results) { @@ -272,7 +272,7 @@ private static IArrowArray BuildPrimitiveTyped( { case ShredType.Boolean: { - BooleanArray.Builder b = new BooleanArray.Builder(); + using BooleanArray.Builder b = new BooleanArray.Builder(allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((bool)v); @@ -281,7 +281,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Int8: { - Int8Array.Builder b = new Int8Array.Builder(); + using Int8Array.Builder b = new Int8Array.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((sbyte)v); @@ -290,7 +290,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Int16: { - Int16Array.Builder b = new Int16Array.Builder(); + using Int16Array.Builder b = new Int16Array.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((short)v); @@ -299,7 +299,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Int32: { - Int32Array.Builder b = new Int32Array.Builder(); + using Int32Array.Builder b = new Int32Array.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((int)v); @@ -308,7 +308,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Int64: { - Int64Array.Builder b = new Int64Array.Builder(); + using Int64Array.Builder b = new Int64Array.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((long)v); @@ -317,7 +317,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Float: { - FloatArray.Builder b = new FloatArray.Builder(); + using FloatArray.Builder b = new FloatArray.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((float)v); @@ -326,7 +326,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Double: { - DoubleArray.Builder b = new DoubleArray.Builder(); + using DoubleArray.Builder b = new DoubleArray.Builder(0, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((double)v); @@ -351,7 +351,7 @@ private static IArrowArray BuildPrimitiveTyped( return BuildTime64(typedValues, allocator); case ShredType.String: { - StringArray.Builder b = new StringArray.Builder(); + using StringArray.Builder b = new StringArray.Builder(allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((string)v); @@ -360,7 +360,7 @@ private static IArrowArray BuildPrimitiveTyped( } case ShredType.Binary: { - BinaryArray.Builder b = new BinaryArray.Builder(); + using BinaryArray.Builder b = new BinaryArray.Builder(BinaryType.Default, allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((ReadOnlySpan)(byte[])v); @@ -401,8 +401,8 @@ private static Time64Array BuildTime64(IList typedValues, MemoryAllocato private static (ArrowBuffer values, ArrowBuffer nullBitmap, int nullCount) BuildLongBuffers( IList typedValues, MemoryAllocator allocator) { - ArrowBuffer.Builder values = new ArrowBuffer.Builder(typedValues.Count); - ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(typedValues.Count); + using ArrowBuffer.Builder values = new ArrowBuffer.Builder(typedValues.Count, allocator); + using ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(typedValues.Count, allocator); int nullCount = 0; foreach (object v in typedValues) { @@ -425,8 +425,8 @@ private static (ArrowBuffer values, ArrowBuffer nullBitmap, int nullCount) Build private static (ArrowBuffer values, ArrowBuffer nullBitmap, int nullCount) BuildIntBuffers( IList typedValues, MemoryAllocator allocator) { - ArrowBuffer.Builder values = new ArrowBuffer.Builder(typedValues.Count); - ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(typedValues.Count); + using ArrowBuffer.Builder values = new ArrowBuffer.Builder(typedValues.Count, allocator); + using ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(typedValues.Count, allocator); int nullCount = 0; foreach (object v in typedValues) { @@ -465,7 +465,7 @@ private static Decimal128Array BuildDecimalArray( } } - Decimal128Array.Builder b = new Decimal128Array.Builder(new Decimal128Type(precision, scale)); + using Decimal128Array.Builder b = new Decimal128Array.Builder(new Decimal128Type(precision, scale), allocator); foreach (object v in typedValues) { if (v == null) b.AppendNull(); else b.Append((decimal)v); @@ -483,8 +483,8 @@ private static FixedSizeBinaryArray BuildUuidArray( { FixedSizeBinaryType type = new FixedSizeBinaryType(16); int rowCount = typedValues.Count; - ArrowBuffer.Builder values = new ArrowBuffer.Builder(rowCount * 16); - ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(rowCount); + using ArrowBuffer.Builder values = new ArrowBuffer.Builder(rowCount * 16, allocator); + using ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(rowCount, allocator); int nullCount = 0; byte[] scratch = new byte[16]; @@ -529,7 +529,7 @@ private static ArrowBuffer BuildNullBitmap( IList items, Func isValid, int rowCount, MemoryAllocator allocator, out int nullCount) { - ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(rowCount); + using ArrowBuffer.BitmapBuilder bitmap = new ArrowBuffer.BitmapBuilder(rowCount, allocator); int nulls = 0; for (int i = 0; i < rowCount; i++) { diff --git a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs index 88385cc5..49fb9a56 100644 --- a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs +++ b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs @@ -611,9 +611,9 @@ public void Visit(RunEndEncodedType type) switch (runEndsTypeId) { - case ArrowTypeId.Int16: int16Builder = new ArrowBuffer.Builder(); break; - case ArrowTypeId.Int32: int32Builder = new ArrowBuffer.Builder(); break; - case ArrowTypeId.Int64: int64Builder = new ArrowBuffer.Builder(); break; + case ArrowTypeId.Int16: int16Builder = new ArrowBuffer.Builder(0, _allocator); break; + case ArrowTypeId.Int32: int32Builder = new ArrowBuffer.Builder(0, _allocator); break; + case ArrowTypeId.Int64: int64Builder = new ArrowBuffer.Builder(0, _allocator); break; } long baseOffset = 0; @@ -705,6 +705,10 @@ public void Visit(RunEndEncodedType type) _ => int64Builder.Build(_allocator), }; + int16Builder?.Dispose(); + int32Builder?.Dispose(); + int64Builder?.Dispose(); + ArrayData runEndsResult = new ArrayData( type.RunEndsDataType, physicalRunCount, 0, 0, new[] { ArrowBuffer.Empty, runEndsValueBuffer }); diff --git a/src/Apache.Arrow/Arrays/ArrowArrayBuilderFactory.cs b/src/Apache.Arrow/Arrays/ArrowArrayBuilderFactory.cs index ec0206a3..f619e49a 100644 --- a/src/Apache.Arrow/Arrays/ArrowArrayBuilderFactory.cs +++ b/src/Apache.Arrow/Arrays/ArrowArrayBuilderFactory.cs @@ -14,97 +14,98 @@ // limitations under the License. using System; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow { static class ArrowArrayBuilderFactory { - internal static IArrowArrayBuilder> Build(IArrowType dataType) + internal static IArrowArrayBuilder> Build(IArrowType dataType, MemoryAllocator allocator) { switch (dataType.TypeId) { case ArrowTypeId.Boolean: - return new BooleanArray.Builder(); + return new BooleanArray.Builder(allocator); case ArrowTypeId.UInt8: - return new UInt8Array.Builder(); + return new UInt8Array.Builder(0, allocator); case ArrowTypeId.Int8: - return new Int8Array.Builder(); + return new Int8Array.Builder(0, allocator); case ArrowTypeId.UInt16: - return new UInt16Array.Builder(); + return new UInt16Array.Builder(0, allocator); case ArrowTypeId.Int16: - return new Int16Array.Builder(); + return new Int16Array.Builder(0, allocator); case ArrowTypeId.UInt32: - return new UInt32Array.Builder(); + return new UInt32Array.Builder(0, allocator); case ArrowTypeId.Int32: - return new Int32Array.Builder(); + return new Int32Array.Builder(0, allocator); case ArrowTypeId.UInt64: - return new UInt64Array.Builder(); + return new UInt64Array.Builder(0, allocator); case ArrowTypeId.Int64: - return new Int64Array.Builder(); + return new Int64Array.Builder(0, allocator); case ArrowTypeId.HalfFloat: #if NET5_0_OR_GREATER - return new HalfFloatArray.Builder(); + return new HalfFloatArray.Builder(0, allocator); #else throw new NotSupportedException("Half-float arrays are not supported by this target framework."); #endif case ArrowTypeId.Float: - return new FloatArray.Builder(); + return new FloatArray.Builder(0, allocator); case ArrowTypeId.Double: - return new DoubleArray.Builder(); + return new DoubleArray.Builder(0, allocator); case ArrowTypeId.String: - return new StringArray.Builder(); + return new StringArray.Builder(allocator); case ArrowTypeId.StringView: - return new StringViewArray.Builder(); + return new StringViewArray.Builder(allocator); case ArrowTypeId.Binary: - return new BinaryArray.Builder(); + return new BinaryArray.Builder(BinaryType.Default, allocator); case ArrowTypeId.BinaryView: - return new BinaryViewArray.Builder(); + return new BinaryViewArray.Builder(BinaryViewType.Default, allocator); case ArrowTypeId.Timestamp: - return new TimestampArray.Builder(); + return new TimestampArray.Builder((TimestampType)dataType, 0, allocator); case ArrowTypeId.Date64: - return new Date64Array.Builder(); + return new Date64Array.Builder(0, allocator); case ArrowTypeId.Date32: - return new Date32Array.Builder(); + return new Date32Array.Builder(0, allocator); case ArrowTypeId.Time32: - return new Time32Array.Builder(dataType as Time32Type); + return new Time32Array.Builder(dataType as Time32Type, 0, allocator); case ArrowTypeId.Time64: - return new Time64Array.Builder(dataType as Time64Type); + return new Time64Array.Builder(dataType as Time64Type, 0, allocator); case ArrowTypeId.Duration: - return new DurationArray.Builder(dataType as DurationType); + return new DurationArray.Builder(dataType as DurationType, 0, allocator); case ArrowTypeId.List: - return new ListArray.Builder(dataType as ListType); + return new ListArray.Builder(dataType as ListType, allocator); case ArrowTypeId.ListView: - return new ListViewArray.Builder(dataType as ListViewType); + return new ListViewArray.Builder(dataType as ListViewType, allocator); case ArrowTypeId.FixedSizeList: - return new FixedSizeListArray.Builder(dataType as FixedSizeListType); + return new FixedSizeListArray.Builder(dataType as FixedSizeListType, allocator); case ArrowTypeId.Decimal32: - return new Decimal32Array.Builder(dataType as Decimal32Type); + return new Decimal32Array.Builder(dataType as Decimal32Type, allocator); case ArrowTypeId.Decimal64: - return new Decimal64Array.Builder(dataType as Decimal64Type); + return new Decimal64Array.Builder(dataType as Decimal64Type, allocator); case ArrowTypeId.Decimal128: - return new Decimal128Array.Builder(dataType as Decimal128Type); + return new Decimal128Array.Builder(dataType as Decimal128Type, allocator); case ArrowTypeId.Decimal256: - return new Decimal256Array.Builder(dataType as Decimal256Type); + return new Decimal256Array.Builder(dataType as Decimal256Type, allocator); case ArrowTypeId.Interval: var intervalType = (IntervalType)dataType; return intervalType.Unit switch { - IntervalUnit.YearMonth => new YearMonthIntervalArray.Builder(), - IntervalUnit.DayTime => new DayTimeIntervalArray.Builder(), - IntervalUnit.MonthDayNanosecond => new MonthDayNanosecondIntervalArray.Builder(), + IntervalUnit.YearMonth => new YearMonthIntervalArray.Builder(0, allocator), + IntervalUnit.DayTime => new DayTimeIntervalArray.Builder(0, allocator), + IntervalUnit.MonthDayNanosecond => new MonthDayNanosecondIntervalArray.Builder(0, allocator), _ => throw new ArgumentOutOfRangeException($"unsupported interval unit <{intervalType.Unit}>") }; case ArrowTypeId.LargeBinary: - return new LargeBinaryArray.Builder(); + return new LargeBinaryArray.Builder(LargeBinaryType.Default, allocator); case ArrowTypeId.LargeString: - return new LargeStringArray.Builder(); + return new LargeStringArray.Builder(allocator); case ArrowTypeId.LargeList: - return new LargeListArray.Builder(dataType as LargeListType); + return new LargeListArray.Builder(dataType as LargeListType, allocator); case ArrowTypeId.LargeListView: - return new LargeListViewArray.Builder(dataType as LargeListViewType); + return new LargeListViewArray.Builder(dataType as LargeListViewType, allocator); case ArrowTypeId.Map: - return new MapArray.Builder(dataType as MapType); + return new MapArray.Builder(dataType as MapType, allocator); case ArrowTypeId.Struct: case ArrowTypeId.Union: case ArrowTypeId.Dictionary: diff --git a/src/Apache.Arrow/Arrays/BinaryArray.cs b/src/Apache.Arrow/Arrays/BinaryArray.cs index 74c45f05..2f5cca11 100644 --- a/src/Apache.Arrow/Arrays/BinaryArray.cs +++ b/src/Apache.Arrow/Arrays/BinaryArray.cs @@ -29,6 +29,17 @@ public class Builder : BuilderBase public Builder() : base(BinaryType.Default) { } public Builder(IArrowType dataType) : base(dataType) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// The binary type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType dataType, MemoryAllocator allocator) : base(dataType, allocator) { } + protected override BinaryArray Build(ArrayData data) { return new BinaryArray(data); @@ -49,7 +60,7 @@ public BinaryArray(ArrowTypeId typeId, ArrayData data) data.EnsureBufferCount(3); } - public abstract class BuilderBase : IArrowArrayBuilder + public abstract class BuilderBase : IArrowArrayBuilder, IDisposable where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { @@ -63,11 +74,16 @@ public abstract class BuilderBase : IArrowArrayBuilder(); - ValueBuffer = new ArrowBuffer.Builder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + ValueOffsets = new ArrowBuffer.Builder(0, allocator); + ValueBuffer = new ArrowBuffer.Builder(0, allocator); + ValidityBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); // From the docs: // @@ -126,6 +142,30 @@ protected void AdvanceValueBuffer(int count) /// public int Length => ValueOffsets.Length - 1; + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + ValueOffsets.Dispose(); + ValueBuffer.Dispose(); + ValidityBuffer.Dispose(); + } + } + /// /// Build an Arrow array from the appended contents so far. /// diff --git a/src/Apache.Arrow/Arrays/BinaryViewArray.cs b/src/Apache.Arrow/Arrays/BinaryViewArray.cs index 35001309..03679da5 100644 --- a/src/Apache.Arrow/Arrays/BinaryViewArray.cs +++ b/src/Apache.Arrow/Arrays/BinaryViewArray.cs @@ -30,6 +30,17 @@ public class Builder : BuilderBase public Builder() : base(BinaryViewType.Default) { } public Builder(IArrowType dataType) : base(dataType) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// The binary type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType dataType, MemoryAllocator allocator) : base(dataType, allocator) { } + protected override BinaryViewArray Build(ArrayData data) { return new BinaryViewArray(data); @@ -50,7 +61,7 @@ public BinaryViewArray(ArrowTypeId typeId, ArrayData data) data.EnsureVariadicBufferCount(2); } - public abstract class BuilderBase : IArrowArrayBuilder + public abstract class BuilderBase : IArrowArrayBuilder, IDisposable where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { @@ -62,11 +73,16 @@ public abstract class BuilderBase : IArrowArrayBuilder this.ValidityBuffer.UnsetBitCount; protected BuilderBase(IArrowType dataType) + : this(dataType, null) + { + } + + protected BuilderBase(IArrowType dataType, MemoryAllocator allocator) { DataType = dataType; - BinaryViews = new ArrowBuffer.Builder(); - ValueBuffer = new ArrowBuffer.Builder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + BinaryViews = new ArrowBuffer.Builder(0, allocator); + ValueBuffer = new ArrowBuffer.Builder(0, allocator); + ValidityBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); } protected abstract TArray Build(ArrayData data); @@ -76,6 +92,30 @@ protected BuilderBase(IArrowType dataType) /// public int Length => BinaryViews.Length; + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + BinaryViews.Dispose(); + ValueBuffer.Dispose(); + ValidityBuffer.Dispose(); + } + } + /// /// Build an Arrow array from the appended contents so far. /// diff --git a/src/Apache.Arrow/Arrays/Bool8Array.cs b/src/Apache.Arrow/Arrays/Bool8Array.cs index 4038fb2d..4617229d 100644 --- a/src/Apache.Arrow/Arrays/Bool8Array.cs +++ b/src/Apache.Arrow/Arrays/Bool8Array.cs @@ -17,6 +17,7 @@ using System.Collections; using System.Collections.Generic; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -78,6 +79,22 @@ public Bool8Array(IArrowArray storage) : base(Bool8Type.Default, storage) { } public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override Bool8Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/BooleanArray.cs b/src/Apache.Arrow/Arrays/BooleanArray.cs index 32824a18..c1062354 100644 --- a/src/Apache.Arrow/Arrays/BooleanArray.cs +++ b/src/Apache.Arrow/Arrays/BooleanArray.cs @@ -23,7 +23,7 @@ namespace Apache.Arrow { public class BooleanArray : Array, IReadOnlyList, ICollection { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { private ArrowBuffer.BitmapBuilder ValueBuffer { get; } private ArrowBuffer.BitmapBuilder ValidityBuffer { get; } @@ -33,9 +33,22 @@ public class Builder : IArrowArrayBuilder public int NullCount => ValidityBuffer.UnsetBitCount; public Builder() + : this(null) { - ValueBuffer = new ArrowBuffer.BitmapBuilder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) + { + ValueBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); + ValidityBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); } public Builder Append(bool value) @@ -74,6 +87,29 @@ public Builder AppendNull() return NullableAppend(null); } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + ValueBuffer.Dispose(); + ValidityBuffer.Dispose(); + } + } + public BooleanArray Build(MemoryAllocator allocator = default) { ArrowBuffer validityBuffer = NullCount > 0 diff --git a/src/Apache.Arrow/Arrays/Date32Array.cs b/src/Apache.Arrow/Arrays/Date32Array.cs index 8094b5d0..ea411afa 100644 --- a/src/Apache.Arrow/Arrays/Date32Array.cs +++ b/src/Apache.Arrow/Arrays/Date32Array.cs @@ -15,6 +15,7 @@ using System; using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -40,6 +41,10 @@ public class Builder : DateArrayBuilder { private class DateBuilder : PrimitiveArrayBuilder { + public DateBuilder() { } + + public DateBuilder(int capacity, MemoryAllocator allocator) : base(capacity, allocator) { } + protected override Date32Array Build(ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => new(valueBuffer, nullBitmapBuffer, length, nullCount, offset); @@ -50,6 +55,18 @@ protected override Date32Array Build(ArrowBuffer valueBuffer, ArrowBuffer nullBi /// public Builder() : base(new DateBuilder()) { } + /// + /// Construct a new instance of the class with room for + /// values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(new DateBuilder(capacity, allocator)) { } + protected override int Convert(DateTime dateTime) { return (int)(dateTime.Date - _epochDate).TotalDays; diff --git a/src/Apache.Arrow/Arrays/Date64Array.cs b/src/Apache.Arrow/Arrays/Date64Array.cs index 1124d84e..61d9aa3c 100644 --- a/src/Apache.Arrow/Arrays/Date64Array.cs +++ b/src/Apache.Arrow/Arrays/Date64Array.cs @@ -15,6 +15,7 @@ using System; using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -45,6 +46,10 @@ public class Builder : DateArrayBuilder { private class DateBuilder : PrimitiveArrayBuilder { + public DateBuilder() { } + + public DateBuilder(int capacity, MemoryAllocator allocator) : base(capacity, allocator) { } + protected override Date64Array Build(ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => new(valueBuffer, nullBitmapBuffer, length, nullCount, offset); @@ -55,6 +60,18 @@ protected override Date64Array Build(ArrowBuffer valueBuffer, ArrowBuffer nullBi /// public Builder() : base(new DateBuilder()) { } + /// + /// Construct a new instance of the class with room for + /// values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(new DateBuilder(capacity, allocator)) { } + protected override long Convert(DateTime dateTime) { var dateTimeOffset = new DateTimeOffset( diff --git a/src/Apache.Arrow/Arrays/Decimal128Array.cs b/src/Apache.Arrow/Arrays/Decimal128Array.cs index 433b907f..f7017c21 100644 --- a/src/Apache.Arrow/Arrays/Decimal128Array.cs +++ b/src/Apache.Arrow/Arrays/Decimal128Array.cs @@ -19,6 +19,7 @@ using System.Data.SqlTypes; using System.Diagnostics; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -32,6 +33,20 @@ public Builder(Decimal128Type type) : base(type, 16) DataType = type; } + /// + /// Creates a builder whose working memory comes from . + /// + /// The decimal type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Decimal128Type type, MemoryAllocator allocator) : base(type, 16, allocator) + { + DataType = type; + } + protected new Decimal128Type DataType { get; } protected override Decimal128Array Build(ArrayData data) diff --git a/src/Apache.Arrow/Arrays/Decimal256Array.cs b/src/Apache.Arrow/Arrays/Decimal256Array.cs index 24c9573e..81970db9 100644 --- a/src/Apache.Arrow/Arrays/Decimal256Array.cs +++ b/src/Apache.Arrow/Arrays/Decimal256Array.cs @@ -21,6 +21,7 @@ using System.Data.SqlTypes; using System.Diagnostics; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -34,6 +35,20 @@ public Builder(Decimal256Type type) : base(type, 32) DataType = type; } + /// + /// Creates a builder whose working memory comes from . + /// + /// The decimal type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Decimal256Type type, MemoryAllocator allocator) : base(type, 32, allocator) + { + DataType = type; + } + protected new Decimal256Type DataType { get; } protected override Decimal256Array Build(ArrayData data) diff --git a/src/Apache.Arrow/Arrays/Decimal32Array.cs b/src/Apache.Arrow/Arrays/Decimal32Array.cs index 1f499074..014a0252 100644 --- a/src/Apache.Arrow/Arrays/Decimal32Array.cs +++ b/src/Apache.Arrow/Arrays/Decimal32Array.cs @@ -18,6 +18,7 @@ using System.Collections.Generic; using System.Diagnostics; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -31,6 +32,20 @@ public Builder(Decimal32Type type) : base(type, 4) DataType = type; } + /// + /// Creates a builder whose working memory comes from . + /// + /// The decimal type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Decimal32Type type, MemoryAllocator allocator) : base(type, 4, allocator) + { + DataType = type; + } + protected new Decimal32Type DataType { get; } protected override Decimal32Array Build(ArrayData data) diff --git a/src/Apache.Arrow/Arrays/Decimal64Array.cs b/src/Apache.Arrow/Arrays/Decimal64Array.cs index 101f842a..de911385 100644 --- a/src/Apache.Arrow/Arrays/Decimal64Array.cs +++ b/src/Apache.Arrow/Arrays/Decimal64Array.cs @@ -18,6 +18,7 @@ using System.Collections.Generic; using System.Diagnostics; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -31,6 +32,20 @@ public Builder(Decimal64Type type) : base(type, 8) DataType = type; } + /// + /// Creates a builder whose working memory comes from . + /// + /// The decimal type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Decimal64Type type, MemoryAllocator allocator) : base(type, 8, allocator) + { + DataType = type; + } + protected new Decimal64Type DataType { get; } protected override Decimal64Array Build(ArrayData data) diff --git a/src/Apache.Arrow/Arrays/DelegatingArrayBuilder.cs b/src/Apache.Arrow/Arrays/DelegatingArrayBuilder.cs index fdfad2c1..a7fd68c9 100644 --- a/src/Apache.Arrow/Arrays/DelegatingArrayBuilder.cs +++ b/src/Apache.Arrow/Arrays/DelegatingArrayBuilder.cs @@ -29,7 +29,7 @@ namespace Apache.Arrow /// Type of item accepted by inner array builder. /// Type of array produced by this (and the inner) builder. /// Type of builder (see Curiously-Recurring Template Pattern). - public abstract class DelegatingArrayBuilder : IArrowArrayBuilder + public abstract class DelegatingArrayBuilder : IArrowArrayBuilder, IDisposable where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { @@ -52,6 +52,28 @@ protected DelegatingArrayBuilder(IArrowArrayBuilder + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (InnerBuilder as IDisposable)?.Dispose(); + } + } + /// /// Build an Arrow Array from the appended contents so far. /// diff --git a/src/Apache.Arrow/Arrays/DoubleArray.cs b/src/Apache.Arrow/Arrays/DoubleArray.cs index 25c782a2..242b7033 100644 --- a/src/Apache.Arrow/Arrays/DoubleArray.cs +++ b/src/Apache.Arrow/Arrays/DoubleArray.cs @@ -13,6 +13,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -21,6 +22,22 @@ public class DoubleArray : PrimitiveArray { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override DoubleArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/DurationArray.cs b/src/Apache.Arrow/Arrays/DurationArray.cs index 32d35d99..68275a9e 100644 --- a/src/Apache.Arrow/Arrays/DurationArray.cs +++ b/src/Apache.Arrow/Arrays/DurationArray.cs @@ -16,6 +16,7 @@ using System; using System.Collections; using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -31,6 +32,21 @@ public Builder(DurationType dataType) DataType = dataType; } + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(DurationType dataType, int capacity, MemoryAllocator allocator = null) + : base(capacity, allocator) + { + DataType = dataType; + } + protected override DurationArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs b/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs index c67a2774..78cc311c 100644 --- a/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs +++ b/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs @@ -84,7 +84,7 @@ IEnumerator IEnumerable.GetEnumerator() IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)this).GetEnumerator(); - public abstract class BuilderBase : IArrowArrayBuilder + public abstract class BuilderBase : IArrowArrayBuilder, IDisposable where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { @@ -98,11 +98,39 @@ public abstract class BuilderBase : IArrowArrayBuilder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + ValueBuffer = new ArrowBuffer.Builder(0, allocator); + ValidityBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); + } + + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + ValueBuffer.Dispose(); + ValidityBuffer.Dispose(); + } } public TArray Build(MemoryAllocator allocator = default) diff --git a/src/Apache.Arrow/Arrays/FixedSizeListArray.cs b/src/Apache.Arrow/Arrays/FixedSizeListArray.cs index bb395a3c..7d5d68e2 100644 --- a/src/Apache.Arrow/Arrays/FixedSizeListArray.cs +++ b/src/Apache.Arrow/Arrays/FixedSizeListArray.cs @@ -21,7 +21,7 @@ namespace Apache.Arrow { public class FixedSizeListArray : Array { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> ValueBuilder { get; } @@ -35,18 +35,46 @@ public class Builder : IArrowArrayBuilder private int ExpectedValueLength => Length * DataType.ListSize; - public Builder(IArrowType valueDataType, int listSize) : this(new FixedSizeListType(valueDataType, listSize)) + public Builder(IArrowType valueDataType, int listSize) : this(new FixedSizeListType(valueDataType, listSize), null) { } - public Builder(Field valueField, int listSize) : this(new FixedSizeListType(valueField, listSize)) + /// + /// Creates a builder whose working memory comes from . + /// + /// The type of the list elements. + /// The number of elements in each list. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType valueDataType, int listSize, MemoryAllocator allocator) : this(new FixedSizeListType(valueDataType, listSize), allocator) + { + } + + public Builder(Field valueField, int listSize) : this(new FixedSizeListType(valueField, listSize), null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The field describing the list elements. + /// The number of elements in each list. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Field valueField, int listSize, MemoryAllocator allocator) : this(new FixedSizeListType(valueField, listSize), allocator) { } - internal Builder(FixedSizeListType dataType) + internal Builder(FixedSizeListType dataType, MemoryAllocator allocator) { - ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = dataType; } @@ -81,6 +109,29 @@ public Builder AppendNull() return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ValueBuilder as IDisposable)?.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public FixedSizeListArray Build(MemoryAllocator allocator = default) { ValidateChildLength(); diff --git a/src/Apache.Arrow/Arrays/FloatArray.cs b/src/Apache.Arrow/Arrays/FloatArray.cs index 4a7770b6..e893ca24 100644 --- a/src/Apache.Arrow/Arrays/FloatArray.cs +++ b/src/Apache.Arrow/Arrays/FloatArray.cs @@ -13,6 +13,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -21,6 +22,22 @@ public class FloatArray : PrimitiveArray { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override FloatArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/GuidArray.cs b/src/Apache.Arrow/Arrays/GuidArray.cs index b5cbfc1e..348247ed 100644 --- a/src/Apache.Arrow/Arrays/GuidArray.cs +++ b/src/Apache.Arrow/Arrays/GuidArray.cs @@ -17,6 +17,7 @@ using System.Collections; using System.Collections.Generic; using Apache.Arrow.Arrays; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -84,6 +85,18 @@ public Builder() : base(GuidType.Default.StorageType, GuidType.ByteWidth) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) : base(GuidType.Default.StorageType, GuidType.ByteWidth, allocator) + { + } + protected override GuidArray Build(ArrayData data) { return new GuidArray(GuidType.Default, new FixedSizeBinaryArray(data)); diff --git a/src/Apache.Arrow/Arrays/HalfFloatArray.cs b/src/Apache.Arrow/Arrays/HalfFloatArray.cs index 97ef9924..d53bd059 100644 --- a/src/Apache.Arrow/Arrays/HalfFloatArray.cs +++ b/src/Apache.Arrow/Arrays/HalfFloatArray.cs @@ -14,6 +14,7 @@ // limitations under the License. using System; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class HalfFloatArray : PrimitiveArray { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override HalfFloatArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/Int16Array.cs b/src/Apache.Arrow/Arrays/Int16Array.cs index 03c612e1..efec006a 100644 --- a/src/Apache.Arrow/Arrays/Int16Array.cs +++ b/src/Apache.Arrow/Arrays/Int16Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class Int16Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override Int16Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/Int32Array.cs b/src/Apache.Arrow/Arrays/Int32Array.cs index f75a43fd..6613700b 100644 --- a/src/Apache.Arrow/Arrays/Int32Array.cs +++ b/src/Apache.Arrow/Arrays/Int32Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class Int32Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override Int32Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/Int64Array.cs b/src/Apache.Arrow/Arrays/Int64Array.cs index 8d80469b..f3fbfe4c 100644 --- a/src/Apache.Arrow/Arrays/Int64Array.cs +++ b/src/Apache.Arrow/Arrays/Int64Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class Int64Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override Int64Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/Int8Array.cs b/src/Apache.Arrow/Arrays/Int8Array.cs index a7d80663..679bbc0c 100644 --- a/src/Apache.Arrow/Arrays/Int8Array.cs +++ b/src/Apache.Arrow/Arrays/Int8Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class Int8Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override Int8Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/IntervalArray.cs b/src/Apache.Arrow/Arrays/IntervalArray.cs index 753ac9aa..5a0d14bb 100644 --- a/src/Apache.Arrow/Arrays/IntervalArray.cs +++ b/src/Apache.Arrow/Arrays/IntervalArray.cs @@ -14,6 +14,7 @@ // limitations under the License. using System; +using Apache.Arrow.Memory; using Apache.Arrow.Scalars; using Apache.Arrow.Types; @@ -67,6 +68,22 @@ public sealed class YearMonthIntervalArray : IntervalArray { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override YearMonthIntervalArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => @@ -92,6 +109,22 @@ public sealed class DayTimeIntervalArray : IntervalArray { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override DayTimeIntervalArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => @@ -117,6 +150,22 @@ public sealed class MonthDayNanosecondIntervalArray : IntervalArray { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override MonthDayNanosecondIntervalArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/LargeBinaryArray.cs b/src/Apache.Arrow/Arrays/LargeBinaryArray.cs index 960f60bb..f2ef3dc9 100644 --- a/src/Apache.Arrow/Arrays/LargeBinaryArray.cs +++ b/src/Apache.Arrow/Arrays/LargeBinaryArray.cs @@ -29,13 +29,24 @@ public class Builder : BuilderBase public Builder() : base(LargeBinaryType.Default) { } public Builder(IArrowType dataType) : base(dataType) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// The binary type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType dataType, MemoryAllocator allocator) : base(dataType, allocator) { } + protected override LargeBinaryArray Build(ArrayData data) { return new LargeBinaryArray(data); } } - public abstract class BuilderBase : IArrowArrayBuilder + public abstract class BuilderBase : IArrowArrayBuilder, IDisposable where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { @@ -48,11 +59,16 @@ public abstract class BuilderBase : IArrowArrayBuilder this.ValidityBuffer.UnsetBitCount; protected BuilderBase(IArrowType dataType) + : this(dataType, null) + { + } + + protected BuilderBase(IArrowType dataType, MemoryAllocator allocator) { DataType = dataType; - ValueOffsets = new ArrowBuffer.Builder(); - ValueBuffer = new ArrowBuffer.Builder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + ValueOffsets = new ArrowBuffer.Builder(0, allocator); + ValueBuffer = new ArrowBuffer.Builder(0, allocator); + ValidityBuffer = new ArrowBuffer.BitmapBuilder(0, allocator); ValueOffsets.Append(this.Offset); } @@ -60,6 +76,30 @@ protected BuilderBase(IArrowType dataType) public int Length => ValueOffsets.Length - 1; + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + ValueOffsets.Dispose(); + ValueBuffer.Dispose(); + ValidityBuffer.Dispose(); + } + } + public TArray Build(MemoryAllocator allocator = default) { var bufs = new[] diff --git a/src/Apache.Arrow/Arrays/LargeListArray.cs b/src/Apache.Arrow/Arrays/LargeListArray.cs index 4cc58747..96c77c75 100644 --- a/src/Apache.Arrow/Arrays/LargeListArray.cs +++ b/src/Apache.Arrow/Arrays/LargeListArray.cs @@ -21,7 +21,7 @@ namespace Apache.Arrow { public class LargeListArray : Array { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> ValueBuilder { get; } @@ -35,19 +35,45 @@ public class Builder : IArrowArrayBuilder private IArrowType DataType { get; } - public Builder(IArrowType valueDataType) : this(new LargeListType(valueDataType)) + public Builder(IArrowType valueDataType) : this(new LargeListType(valueDataType), null) { } - public Builder(Field valueField) : this(new LargeListType(valueField)) + /// + /// Creates a builder whose working memory comes from . + /// + /// The type of the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType valueDataType, MemoryAllocator allocator) : this(new LargeListType(valueDataType), allocator) { } - internal Builder(LargeListType dataType) + public Builder(Field valueField) : this(new LargeListType(valueField), null) { - ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType); - ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The field describing the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Field valueField, MemoryAllocator allocator) : this(new LargeListType(valueField), allocator) + { + } + + internal Builder(LargeListType dataType, MemoryAllocator allocator) + { + ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType, allocator); + ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(0, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = dataType; } @@ -68,6 +94,30 @@ public Builder AppendNull() return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public LargeListArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(ValueBuilder.Length); diff --git a/src/Apache.Arrow/Arrays/LargeListViewArray.cs b/src/Apache.Arrow/Arrays/LargeListViewArray.cs index 7e832588..a482dcd4 100644 --- a/src/Apache.Arrow/Arrays/LargeListViewArray.cs +++ b/src/Apache.Arrow/Arrays/LargeListViewArray.cs @@ -21,7 +21,7 @@ namespace Apache.Arrow { public class LargeListViewArray : Array { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> ValueBuilder { get; } @@ -39,20 +39,46 @@ public class Builder : IArrowArrayBuilder private int Start { get; set; } - public Builder(IArrowType valueDataType) : this(new LargeListViewType(valueDataType)) + public Builder(IArrowType valueDataType) : this(new LargeListViewType(valueDataType), null) { } - public Builder(Field valueField) : this(new LargeListViewType(valueField)) + /// + /// Creates a builder whose working memory comes from . + /// + /// The type of the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType valueDataType, MemoryAllocator allocator) : this(new LargeListViewType(valueDataType), allocator) + { + } + + public Builder(Field valueField) : this(new LargeListViewType(valueField), null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The field describing the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Field valueField, MemoryAllocator allocator) : this(new LargeListViewType(valueField), allocator) { } - internal Builder(LargeListViewType dataType) + internal Builder(LargeListViewType dataType, MemoryAllocator allocator) { - ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType); - ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(); - SizesBufferBuilder = new ArrowBuffer.Builder(); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType, allocator); + ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(0, allocator); + SizesBufferBuilder = new ArrowBuffer.Builder(0, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = dataType; Start = -1; } @@ -95,6 +121,31 @@ private void AppendPrevious() Start = ValueBuilder.Length; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + SizesBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public LargeListViewArray Build(MemoryAllocator allocator = default) { AppendPrevious(); diff --git a/src/Apache.Arrow/Arrays/LargeStringArray.cs b/src/Apache.Arrow/Arrays/LargeStringArray.cs index f27d9527..a321a869 100644 --- a/src/Apache.Arrow/Arrays/LargeStringArray.cs +++ b/src/Apache.Arrow/Arrays/LargeStringArray.cs @@ -18,6 +18,7 @@ using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow; @@ -30,6 +31,16 @@ public class LargeStringArray : LargeBinaryArray, IReadOnlyList, ICollec { public Builder() : base(LargeStringType.Default) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) : base(LargeStringType.Default, allocator) { } + protected override LargeStringArray Build(ArrayData data) { return new LargeStringArray(data); diff --git a/src/Apache.Arrow/Arrays/ListArray.cs b/src/Apache.Arrow/Arrays/ListArray.cs index 49f3dcb0..28a4707e 100644 --- a/src/Apache.Arrow/Arrays/ListArray.cs +++ b/src/Apache.Arrow/Arrays/ListArray.cs @@ -21,7 +21,7 @@ namespace Apache.Arrow { public class ListArray : Array { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> ValueBuilder { get; } @@ -35,19 +35,45 @@ public class Builder : IArrowArrayBuilder private IArrowType DataType { get; } - public Builder(IArrowType valueDataType) : this(new ListType(valueDataType)) + public Builder(IArrowType valueDataType) : this(new ListType(valueDataType), null) { } - public Builder(Field valueField) : this(new ListType(valueField)) + /// + /// Creates a builder whose working memory comes from . + /// + /// The type of the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType valueDataType, MemoryAllocator allocator) : this(new ListType(valueDataType), allocator) + { + } + + public Builder(Field valueField) : this(new ListType(valueField), null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The field describing the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Field valueField, MemoryAllocator allocator) : this(new ListType(valueField), allocator) { } - internal Builder(ListType dataType) + internal Builder(ListType dataType, MemoryAllocator allocator) { - ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType); - ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType, allocator); + ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(0, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = dataType; } @@ -75,6 +101,30 @@ public Builder AppendNull() return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public ListArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(ValueBuilder.Length); diff --git a/src/Apache.Arrow/Arrays/ListViewArray.cs b/src/Apache.Arrow/Arrays/ListViewArray.cs index 2c50e413..4da3e5bd 100644 --- a/src/Apache.Arrow/Arrays/ListViewArray.cs +++ b/src/Apache.Arrow/Arrays/ListViewArray.cs @@ -21,7 +21,7 @@ namespace Apache.Arrow { public class ListViewArray : Array { - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> ValueBuilder { get; } @@ -39,20 +39,46 @@ public class Builder : IArrowArrayBuilder private int Start { get; set; } - public Builder(IArrowType valueDataType) : this(new ListViewType(valueDataType)) + public Builder(IArrowType valueDataType) : this(new ListViewType(valueDataType), null) { } - public Builder(Field valueField) : this(new ListViewType(valueField)) + /// + /// Creates a builder whose working memory comes from . + /// + /// The type of the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(IArrowType valueDataType, MemoryAllocator allocator) : this(new ListViewType(valueDataType), allocator) + { + } + + public Builder(Field valueField) : this(new ListViewType(valueField), null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The field describing the list elements. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Field valueField, MemoryAllocator allocator) : this(new ListViewType(valueField), allocator) { } - internal Builder(ListViewType dataType) + internal Builder(ListViewType dataType, MemoryAllocator allocator) { - ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType); - ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(); - SizesBufferBuilder = new ArrowBuffer.Builder(); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + ValueBuilder = ArrowArrayBuilderFactory.Build(dataType.ValueDataType, allocator); + ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(0, allocator); + SizesBufferBuilder = new ArrowBuffer.Builder(0, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = dataType; Start = -1; } @@ -96,6 +122,31 @@ private void AppendPrevious() Start = ValueBuilder.Length; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + SizesBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public ListViewArray Build(MemoryAllocator allocator = default) { AppendPrevious(); diff --git a/src/Apache.Arrow/Arrays/MapArray.cs b/src/Apache.Arrow/Arrays/MapArray.cs index baff2008..9d77ff61 100644 --- a/src/Apache.Arrow/Arrays/MapArray.cs +++ b/src/Apache.Arrow/Arrays/MapArray.cs @@ -23,7 +23,7 @@ namespace Apache.Arrow public class MapArray : ListArray // MapArray = ListArray(StructArray("key", "value")) { // Same as ListArray.Builder, but with KeyBuilder - public new class Builder : IArrowArrayBuilder + public new class Builder : IArrowArrayBuilder, IDisposable { public IArrowArrayBuilder> KeyBuilder { get; } public IArrowArrayBuilder> ValueBuilder { get; } @@ -39,11 +39,25 @@ public class MapArray : ListArray // MapArray = ListArray(StructArray("key", "va public MapType DataType { get; } public Builder(MapType type) + : this(type, null) { - KeyBuilder = ArrowArrayBuilderFactory.Build(type.KeyField.DataType); - ValueBuilder = ArrowArrayBuilderFactory.Build(type.ValueField.DataType); - ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(); - ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(); + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The map type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MapType type, MemoryAllocator allocator) + { + KeyBuilder = ArrowArrayBuilderFactory.Build(type.KeyField.DataType, allocator); + ValueBuilder = ArrowArrayBuilderFactory.Build(type.ValueField.DataType, allocator); + ValueOffsetsBufferBuilder = new ArrowBuffer.Builder(0, allocator); + ValidityBufferBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); DataType = type; } @@ -71,6 +85,31 @@ public Builder AppendNull() return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (KeyBuilder as IDisposable)?.Dispose(); + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } + public MapArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(KeyBuilder.Length); diff --git a/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs b/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs index ffda77df..27225714 100644 --- a/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs +++ b/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs @@ -20,7 +20,7 @@ namespace Apache.Arrow { - public abstract class PrimitiveArrayBuilder : IArrowArrayBuilder + public abstract class PrimitiveArrayBuilder : IArrowArrayBuilder, IDisposable where TTo : struct where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder @@ -35,6 +35,28 @@ public PrimitiveArrayBuilder(IArrowArrayBuilder + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (ArrayBuilder as IDisposable)?.Dispose(); + } + } + public TArray Build(MemoryAllocator allocator = default) => ArrayBuilder.Build(allocator); public TBuilder Append(TFrom value) @@ -98,42 +120,94 @@ public TBuilder Clear() protected abstract TTo ConvertTo(TFrom value); } - public abstract class PrimitiveArrayBuilder : IArrowArrayBuilder + public abstract class PrimitiveArrayBuilder : IArrowArrayBuilder, IDisposable where T : struct where TArray : IArrowArray where TBuilder : class, IArrowArrayBuilder { + // Created when the first null is appended. Until then every element is valid, which + // is what an empty validity buffer means, so arrays without nulls never allocate one. + private ArrowBuffer.BitmapBuilder _validity; + + // Kept so that a bitmap created later uses the same allocator as the values. May be + // null, which means managed working memory copied into the default allocator on Build. + private readonly MemoryAllocator _allocator; + protected TBuilder Instance => this as TBuilder; protected ArrowBuffer.Builder ValueBuffer { get; } - protected ArrowBuffer.BitmapBuilder ValidityBuffer { get; } + + /// + /// The validity bitmap. Reading this creates the bitmap if no null has been appended + /// yet, marking every element so far as valid. + /// + protected ArrowBuffer.BitmapBuilder ValidityBuffer => _validity ??= CreateValidityBuffer(); public int Length => ValueBuffer.Length; - protected int NullCount => ValidityBuffer.UnsetBitCount; + protected int NullCount => _validity?.UnsetBitCount ?? 0; + + // The initial capacity builders have always had, matching ArrowBuffer.Builder. + private const int DefaultCapacity = 8; + // The smallest bitmap to create, in bits: BitmapBuilder's own default. Sizing the bitmap + // only to the value capacity would start it at a single byte and make it grow repeatedly. + private const int MinimumValidityCapacity = 64; + + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// public PrimitiveArrayBuilder() + : this(DefaultCapacity, null) { - ValueBuffer = new ArrowBuffer.Builder(); - ValidityBuffer = new ArrowBuffer.BitmapBuilder(); + } + + /// + /// Creates a builder with room for values. A builder given + /// its final length allocates once, and that memory becomes the built array's memory. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + protected PrimitiveArrayBuilder(int capacity, MemoryAllocator allocator = null) + { + if (capacity < 0) + { + throw new ArgumentOutOfRangeException(nameof(capacity)); + } + + _allocator = allocator; + ValueBuffer = new ArrowBuffer.Builder(capacity, _allocator); } public TBuilder Resize(int length) { + if (length > ValueBuffer.Length) + { + // Elements added by growing are null, so the bitmap is needed to record that. + ValidityBuffer.Resize(length); + } + else + { + _validity?.Resize(length); + } + ValueBuffer.Resize(length); - ValidityBuffer.Resize(length); return Instance; } public TBuilder Reserve(int capacity) { ValueBuffer.Reserve(capacity); - ValidityBuffer.Reserve(capacity); + _validity?.Reserve(capacity); return Instance; } public TBuilder Append(T value) { ValueBuffer.Append(value); - ValidityBuffer.Append(true); + _validity?.Append(true); return Instance; } @@ -142,10 +216,8 @@ public TBuilder Append(T? value) => public TBuilder Append(ReadOnlySpan span) { - int len = ValueBuffer.Length; ValueBuffer.Append(span); - int additionalBitsCount = ValueBuffer.Length - len; - ValidityBuffer.AppendRange(true, additionalBitsCount); + _validity?.AppendRange(true, span.Length); return Instance; } @@ -153,8 +225,7 @@ public TBuilder AppendRange(IEnumerable values) { int len = ValueBuffer.Length; ValueBuffer.AppendRange(values); - var additionalBitsCount = ValueBuffer.Length - len; - ValidityBuffer.AppendRange(true, additionalBitsCount); + _validity?.AppendRange(true, ValueBuffer.Length - len); return Instance; } @@ -165,33 +236,82 @@ public TBuilder AppendNull() return Instance; } + /// + /// Returns a span of exactly values just past the end of the + /// builder, for writing values directly. Call afterwards to + /// append the values written. + /// + /// + /// The span's initial contents are unspecified; write every value that will be + /// advanced over. The span is invalidated by any other call on the builder. + /// + public Span GetSpan(int count) => ValueBuffer.GetSpan(count); + + /// + /// Appends non-null values previously written to the span + /// returned by . + /// + public TBuilder Advance(int count) + { + ValueBuffer.Advance(count); + _validity?.AppendRange(true, count); + return Instance; + } + public TBuilder Clear() { ValueBuffer.Clear(); - ValidityBuffer.Clear(); + _validity?.Clear(); return Instance; } public TBuilder Set(int index, T value) { + CheckIndex(index); ValueBuffer.Span[index] = value; - ValidityBuffer.Set(index, true); + _validity?.Set(index, true); return Instance; } public TBuilder Swap(int i, int j) { - T x = ValueBuffer.Span[i]; - ValueBuffer.Span[i] = ValueBuffer.Span[j]; - ValueBuffer.Span[j] = x; - ValidityBuffer.Swap(i, j); + CheckIndex(i); + CheckIndex(j); + Span values = ValueBuffer.Span; + T x = values[i]; + values[i] = values[j]; + values[j] = x; + _validity?.Swap(i, j); return Instance; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + ValueBuffer.Dispose(); + _validity?.Dispose(); + } + } + public TArray Build(MemoryAllocator allocator = default) { ArrowBuffer validityBuffer = NullCount > 0 - ? ValidityBuffer.Build(allocator) + ? _validity.Build(allocator) : ArrowBuffer.Empty; return Build( @@ -202,5 +322,21 @@ public TArray Build(MemoryAllocator allocator = default) protected abstract TArray Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset); + + private ArrowBuffer.BitmapBuilder CreateValidityBuffer() + { + ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder( + Math.Max(ValueBuffer.Capacity, MinimumValidityCapacity), _allocator); + validity.AppendRange(true, ValueBuffer.Length); + return validity; + } + + private void CheckIndex(int index) + { + if ((uint)index >= (uint)ValueBuffer.Length) + { + throw new ArgumentOutOfRangeException(nameof(index)); + } + } } } diff --git a/src/Apache.Arrow/Arrays/StringArray.cs b/src/Apache.Arrow/Arrays/StringArray.cs index 8975fdcc..2899b6f0 100644 --- a/src/Apache.Arrow/Arrays/StringArray.cs +++ b/src/Apache.Arrow/Arrays/StringArray.cs @@ -18,6 +18,7 @@ using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -32,6 +33,16 @@ public class StringArray : BinaryArray, IReadOnlyList, ICollection + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) : base(StringType.Default, allocator) { } + protected override StringArray Build(ArrayData data) { return new StringArray(data); diff --git a/src/Apache.Arrow/Arrays/StringViewArray.cs b/src/Apache.Arrow/Arrays/StringViewArray.cs index 5c464849..05e761b3 100644 --- a/src/Apache.Arrow/Arrays/StringViewArray.cs +++ b/src/Apache.Arrow/Arrays/StringViewArray.cs @@ -18,6 +18,7 @@ using System.Collections.Generic; using System.Runtime.InteropServices; using System.Text; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -30,6 +31,16 @@ public class StringViewArray : BinaryViewArray, IReadOnlyList { public Builder() : base(StringViewType.Default) { } + /// + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) : base(StringViewType.Default, allocator) { } + protected override StringViewArray Build(ArrayData data) { return new StringViewArray(data); diff --git a/src/Apache.Arrow/Arrays/Time32Array.cs b/src/Apache.Arrow/Arrays/Time32Array.cs index 4313fefe..d8d3e8e2 100644 --- a/src/Apache.Arrow/Arrays/Time32Array.cs +++ b/src/Apache.Arrow/Arrays/Time32Array.cs @@ -16,6 +16,7 @@ using System; using System.Collections.Generic; using System.IO; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -40,6 +41,9 @@ private class TimeBuilder : PrimitiveArrayBuilder public TimeBuilder(Time32Type dataType) => DataType = dataType; + public TimeBuilder(Time32Type dataType, int capacity, MemoryAllocator allocator) + : base(capacity, allocator) => DataType = dataType; + protected override Time32Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => @@ -60,6 +64,21 @@ public Builder(Time32Type type) { } + /// + /// Construct a new instance of the class with room for + /// values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Time32Type type, int capacity, MemoryAllocator allocator = null) + : base(new TimeBuilder(type, capacity, allocator)) + { + } + #if NET6_0_OR_GREATER protected override int Convert(TimeOnly time) { diff --git a/src/Apache.Arrow/Arrays/Time64Array.cs b/src/Apache.Arrow/Arrays/Time64Array.cs index b9bb12ee..934df256 100644 --- a/src/Apache.Arrow/Arrays/Time64Array.cs +++ b/src/Apache.Arrow/Arrays/Time64Array.cs @@ -16,6 +16,7 @@ using System; using System.Collections.Generic; using System.IO; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -40,6 +41,9 @@ private class TimeBuilder : PrimitiveArrayBuilder DataType = dataType; + public TimeBuilder(Time64Type dataType, int capacity, MemoryAllocator allocator) + : base(capacity, allocator) => DataType = dataType; + protected override Time64Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => @@ -60,6 +64,21 @@ public Builder(Time64Type type) { } + /// + /// Construct a new instance of the class with room for + /// values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(Time64Type type, int capacity, MemoryAllocator allocator = null) + : base(new TimeBuilder(type, capacity, allocator)) + { + } + #if NET6_0_OR_GREATER protected override long Convert(TimeOnly time) { diff --git a/src/Apache.Arrow/Arrays/TimestampArray.cs b/src/Apache.Arrow/Arrays/TimestampArray.cs index f62c4228..4daa9b07 100644 --- a/src/Apache.Arrow/Arrays/TimestampArray.cs +++ b/src/Apache.Arrow/Arrays/TimestampArray.cs @@ -17,6 +17,7 @@ using System.Collections.Generic; using System.Diagnostics; using System.IO; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -34,6 +35,12 @@ internal TimestampBuilder(TimestampType type) DataType = type ?? throw new ArgumentNullException(nameof(type)); } + internal TimestampBuilder(TimestampType type, int capacity, MemoryAllocator allocator) + : base(capacity, allocator) + { + DataType = type ?? throw new ArgumentNullException(nameof(type)); + } + protected TimestampType DataType { get; } protected override TimestampArray Build( @@ -63,6 +70,22 @@ public Builder(TimestampType type) DataType = type; } + /// + /// Construct a new instance of the class with room for + /// values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(TimestampType type, int capacity, MemoryAllocator allocator = null) + : base(new TimestampBuilder(type, capacity, allocator)) + { + DataType = type; + } + protected override long ConvertTo(DateTimeOffset value) { // We must return the absolute time since the UNIX epoch while diff --git a/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs b/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs index 136710a4..2376132d 100644 --- a/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs +++ b/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs @@ -197,7 +197,7 @@ public TimestampWithOffsetArray(TimestampWithOffsetType type, IArrowArray storag /// /// Builder for . /// - public class Builder : IArrowArrayBuilder + public class Builder : IArrowArrayBuilder, IDisposable { private static readonly DateTimeOffset s_nullPlaceholder = new DateTimeOffset(1970, 1, 1, 0, 0, 0, TimeSpan.Zero); @@ -213,11 +213,25 @@ public Builder(TimeUnit unit = TimeUnit.Microsecond) } public Builder(TimestampWithOffsetType type) + : this(type, null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// The timestamp-with-offset type to build. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(TimestampWithOffsetType type, MemoryAllocator allocator) { _type = type ?? throw new ArgumentNullException(nameof(type)); - _timestampBuilder = new TimestampArray.Builder(type.Unit, "UTC"); - _offsetBuilder = new Int16Array.Builder(); - _validityBuilder = new ArrowBuffer.BitmapBuilder(); + _timestampBuilder = new TimestampArray.Builder(new TimestampType(type.Unit, "UTC"), 0, allocator); + _offsetBuilder = new Int16Array.Builder(0, allocator); + _validityBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); } public int Length => _validityBuilder.Length; @@ -278,6 +292,30 @@ public Builder AppendRange(IEnumerable values) return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + _timestampBuilder.Dispose(); + _offsetBuilder.Dispose(); + _validityBuilder.Dispose(); + } + } + public Builder Reserve(int capacity) { _timestampBuilder.Reserve(capacity); diff --git a/src/Apache.Arrow/Arrays/UInt16Array.cs b/src/Apache.Arrow/Arrays/UInt16Array.cs index ae68a83c..8541db04 100644 --- a/src/Apache.Arrow/Arrays/UInt16Array.cs +++ b/src/Apache.Arrow/Arrays/UInt16Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class UInt16Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override UInt16Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/UInt32Array.cs b/src/Apache.Arrow/Arrays/UInt32Array.cs index 402434ea..70c7bddd 100644 --- a/src/Apache.Arrow/Arrays/UInt32Array.cs +++ b/src/Apache.Arrow/Arrays/UInt32Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class UInt32Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override UInt32Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/UInt64Array.cs b/src/Apache.Arrow/Arrays/UInt64Array.cs index 8ef4cb89..749981e6 100644 --- a/src/Apache.Arrow/Arrays/UInt64Array.cs +++ b/src/Apache.Arrow/Arrays/UInt64Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class UInt64Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override UInt64Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/UInt8Array.cs b/src/Apache.Arrow/Arrays/UInt8Array.cs index c4339329..0399543d 100644 --- a/src/Apache.Arrow/Arrays/UInt8Array.cs +++ b/src/Apache.Arrow/Arrays/UInt8Array.cs @@ -14,6 +14,7 @@ // limitations under the License. using System.Collections.Generic; +using Apache.Arrow.Memory; using Apache.Arrow.Types; namespace Apache.Arrow @@ -22,6 +23,22 @@ public class UInt8Array : PrimitiveArray, IIndexes { public class Builder : PrimitiveArrayBuilder { + /// + /// Creates a builder with room for a few values, which grows as values are appended. + /// + public Builder() { } + + /// + /// Creates a builder with room for values. + /// + /// Number of values to allocate room for. + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(int capacity, MemoryAllocator allocator = null) : base(capacity, allocator) { } + protected override UInt8Array Build( ArrowBuffer valueBuffer, ArrowBuffer nullBitmapBuffer, int length, int nullCount, int offset) => diff --git a/src/Apache.Arrow/Arrays/VariantArray.cs b/src/Apache.Arrow/Arrays/VariantArray.cs index 071b7347..cdb3568f 100644 --- a/src/Apache.Arrow/Arrays/VariantArray.cs +++ b/src/Apache.Arrow/Arrays/VariantArray.cs @@ -376,11 +376,11 @@ public SimpleIndexes(int length) /// /// Builder for constructing instances. /// - public class Builder + public class Builder : IDisposable { - private readonly BinaryArray.Builder _metadataBuilder = new BinaryArray.Builder(); - private readonly BinaryArray.Builder _valueBuilder = new BinaryArray.Builder(); - private readonly ArrowBuffer.BitmapBuilder _validityBuilder = new ArrowBuffer.BitmapBuilder(); + private readonly BinaryArray.Builder _metadataBuilder; + private readonly BinaryArray.Builder _valueBuilder; + private readonly ArrowBuffer.BitmapBuilder _validityBuilder; private readonly VariantBuilder _encoder = new VariantBuilder(); private int _length; private int _nullCount; @@ -390,6 +390,26 @@ public class Builder private static readonly Lazy<(byte[] Metadata, byte[] Value)> NullPlaceholder = new Lazy<(byte[], byte[])>(() => new VariantBuilder().Encode(VariantValue.Null)); + public Builder() + : this(null) + { + } + + /// + /// Creates a builder whose working memory comes from . + /// + /// + /// Allocator for the builder's working memory, which usually becomes the built array's + /// memory. When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public Builder(MemoryAllocator allocator) + { + _metadataBuilder = new BinaryArray.Builder(BinaryType.Default, allocator); + _valueBuilder = new BinaryArray.Builder(BinaryType.Default, allocator); + _validityBuilder = new ArrowBuffer.BitmapBuilder(0, allocator); + } + /// /// Gets the number of elements appended so far. /// @@ -478,6 +498,30 @@ public Builder AppendRange(IEnumerable values) return this; } + /// + /// Releases the builder's working memory. Arrays already built are unaffected. + /// + /// + /// Disposal is required only when the working memory comes from an allocator whose + /// is ; + /// otherwise it only releases memory sooner. + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + _metadataBuilder.Dispose(); + _valueBuilder.Dispose(); + _validityBuilder.Dispose(); + } + } + /// /// Builds the from appended values. /// diff --git a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index 6983af3a..98d724e6 100644 --- a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs +++ b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs @@ -26,14 +26,16 @@ public partial struct ArrowBuffer /// The class is a complement to /// and is designed for boolean fields, which are efficiently bit-packed into byte-aligned memory. /// - public class BitmapBuilder + public class BitmapBuilder : IDisposable { private const int DefaultBitCapacity = 64; + private readonly BuilderMemory _buffer; + /// /// Gets the number of bits that can be contained in the memory allocated by the current instance. /// - public int Capacity { get; private set; } + public int Capacity => _buffer.Capacity * 8; /// /// Gets the number of bits currently appended. @@ -43,7 +45,12 @@ public class BitmapBuilder /// /// Gets the raw byte memory underpinning the builder. /// - public Memory Memory { get; private set; } + /// + /// If this memory was handed to a buffer by , + /// reading this property first copies it, so that writes through the result can + /// never modify that buffer. + /// + public Memory Memory => _buffer.Memory; /// /// Gets the span of (bit-packed byte) memory underpinning the builder. @@ -65,9 +72,28 @@ public class BitmapBuilder /// /// Number of bits of initial capacity to reserve. public BitmapBuilder(int capacity = DefaultBitCapacity) + : this(capacity, null) { - Memory = new byte[BitUtility.ByteCount(capacity)]; - Capacity = capacity; + } + + /// + /// Creates an instance of the class. + /// + /// Number of bits of initial capacity to reserve. + /// + /// Allocator used for the builder's working memory, which by default also becomes + /// the memory of the buffer that returns. + /// When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + public BitmapBuilder(int capacity, MemoryAllocator allocator) + { + if (capacity < 0) + { + throw new ArgumentOutOfRangeException(nameof(capacity)); + } + + _buffer = new BuilderMemory(allocator, BitUtility.ByteCount(capacity)); } /// @@ -270,7 +296,7 @@ public BitmapBuilder Resize(int capacity) /// Returns the builder (for fluent-style composition). public BitmapBuilder Clear() { - Span.Fill(default); + _buffer.Reset(); Length = 0; SetBitCount = 0; return this; @@ -279,15 +305,23 @@ public BitmapBuilder Clear() /// /// Build an Arrow buffer from the appended contents so far. /// + /// + /// If the builder was created with an allocator, and is + /// null or that same allocator, the builder's working memory usually becomes the + /// buffer's memory, with no allocation or copy. Otherwise the contents are copied into + /// , or into when it is + /// null. After a hand-over the builder stays usable: it copies the contents back into + /// memory of its own the next time it is written to, and discards + /// them without copying. + /// /// Optional memory allocator. /// Returns an object. public ArrowBuffer Build(MemoryAllocator allocator = default) { - int bufferLength = checked((int)BitUtility.RoundUpToMultipleOf64(Memory.Length)); - var memoryAllocator = allocator ?? MemoryAllocator.Default.Value; - var memoryOwner = memoryAllocator.Allocate(bufferLength); - Memory.Slice(0, Memory.Length).CopyTo(memoryOwner.Memory); - return new ArrowBuffer(memoryOwner); + // Without an allocator, keep the historical buffer length, which covers the whole + // working memory rather than just the bytes the bits need. + int usedBytes = _buffer.CanHandOver ? BitUtility.ByteCount(Length) : _buffer.Capacity; + return _buffer.Build(usedBytes, 64, allocator); } private void CheckIndex(int index) @@ -310,22 +344,28 @@ private void EnsureCapacity(int requiredCapacity) // TODO: specifiable growth strategy // Double the length of the in-memory array, or use the byte count of the capacity, whichever is // greater. - int byteCount = Math.Max(BitUtility.ByteCount(requiredCapacity), Memory.Length * 2); - Reallocate(byteCount); - Capacity = byteCount * 8; + int byteCount = Math.Max(BitUtility.ByteCount(requiredCapacity), _buffer.Capacity * 2); + + // Grow through the allocator so that the builder's working memory is + // visible to it. Newly added bytes are zeroed, which the bitmap relies on. + _buffer.Grow(byteCount); } } - private void Reallocate(int numBytes) + /// + /// Releases the builder's working memory. + /// + /// + /// Disposal is required only when the working memory came from an allocator whose + /// is + /// ; otherwise it merely returns the + /// memory for reuse. + /// + public void Dispose() { - if (numBytes != 0) - { - Debug.Assert(numBytes > Memory.Length); - var memory = new Memory(new byte[numBytes]); - Memory.CopyTo(memory); - - Memory = memory; - } + _buffer.Dispose(); + Length = 0; + SetBitCount = 0; } } } diff --git a/src/Apache.Arrow/ArrowBuffer.Builder.cs b/src/Apache.Arrow/ArrowBuffer.Builder.cs index 39a50dcc..9fa0988a 100644 --- a/src/Apache.Arrow/ArrowBuffer.Builder.cs +++ b/src/Apache.Arrow/ArrowBuffer.Builder.cs @@ -14,7 +14,6 @@ // limitations under the License. using System; -using System.Buffers; using System.Collections.Generic; using System.Runtime.CompilerServices; using Apache.Arrow.Memory; @@ -32,17 +31,25 @@ public partial struct ArrowBuffer /// instead. /// /// Value-type of item to build into a buffer. - public class Builder + public class Builder : IDisposable where T : struct { private const int DefaultCapacity = 8; - private readonly int _size; + private readonly BuilderMemory _buffer; + + // Unsafe.SizeOf() is a JIT-time constant, so dividing by it compiles to a shift. + // A field holding the same value would cost an integer divide on every append. + private static int Size + { + [MethodImpl(MethodImplOptions.AggressiveInlining)] + get => Unsafe.SizeOf(); + } /// /// Gets the number of items that can be contained in the memory allocated by the current instance. /// - public int Capacity => Memory.Length / _size; + public int Capacity => _buffer.Capacity / Size; /// /// Gets the number of items currently appended. @@ -52,7 +59,12 @@ public class Builder /// /// Gets the raw byte memory underpinning the builder. /// - public Memory Memory { get; private set; } + /// + /// If this memory was handed to a buffer by , + /// reading this property first copies it, so that writes through the result can + /// never modify that buffer. + /// + public Memory Memory => _buffer.Memory; /// /// Gets the span of memory underpinning the builder. @@ -68,6 +80,26 @@ public Span Span /// /// Number of items of initial capacity to reserve. public Builder(int capacity = DefaultCapacity) + : this(capacity, null) + { + } + + /// + /// Creates an instance of the class. + /// + /// Number of items of initial capacity to reserve. + /// + /// Allocator used for the builder's working memory, which by default also becomes + /// the memory of the buffer that returns. + /// When null, the builder works in managed memory and copies + /// what it builds into , as builders always have. + /// + /// + /// When an allocator is given, capacity is rounded up so that the working memory is a + /// multiple of 64 bytes. A builder created with enough capacity for all of its items + /// therefore allocates exactly once. + /// + public Builder(int capacity, MemoryAllocator allocator) { // Using `bool` as the template argument, if used in an unrestricted fashion, would result in a buffer // with inappropriate contents being produced. Because C# does not support template specialisation, @@ -81,9 +113,12 @@ public Builder(int capacity = DefaultCapacity) $"instead"); } - _size = Unsafe.SizeOf(); + if (capacity < 0) + { + throw new ArgumentOutOfRangeException(nameof(capacity)); + } - Memory = new byte[capacity * _size]; + _buffer = new BuilderMemory(allocator, checked(capacity * Size)); Length = 0; } @@ -166,6 +201,50 @@ public Builder Reserve(int additionalCapacity) return this; } + /// + /// Returns a span of exactly items just past the end of the + /// appended contents, growing the buffer if needed. Call + /// afterwards to append the items written. + /// + /// + /// The span's initial contents are unspecified; write every item that will be + /// advanced over. The span is invalidated by any other call on the builder. + /// + /// Number of items to be written. + public Span GetSpan(int count) + { + if (count < 0) + { + ThrowArgumentOutOfRange(nameof(count)); + } + + EnsureAdditionalCapacity(count); + return Span.Slice(Length, count); + } + + /// + /// Appends items previously written to the span returned by + /// . + /// + /// Number of items written. + /// Returns the builder (for fluent-style composition). + public Builder Advance(int count) + { + // Unsigned comparison covers count < 0 as well. + if ((uint)count > (uint)(Capacity - Length)) + { + ThrowArgumentOutOfRange(nameof(count)); + } + + Length += count; + return this; + } + + // Kept out of line so that the methods that throw stay small enough to inline. + [MethodImpl(MethodImplOptions.NoInlining)] + private static void ThrowArgumentOutOfRange(string paramName) => + throw new ArgumentOutOfRangeException(paramName); + /// /// Resize the buffer to a given size. /// @@ -198,7 +277,7 @@ public Builder Resize(int capacity) /// Returns the builder (for fluent-style composition). public Builder Clear() { - Span.Fill(default); + _buffer.Reset(); Length = 0; return this; } @@ -206,6 +285,16 @@ public Builder Clear() /// /// Build an Arrow buffer from the appended contents so far. /// + /// + /// If the builder was created with an allocator, and is + /// null or that same allocator, the builder's working memory usually becomes the + /// buffer's memory, with no allocation or copy. Otherwise the contents are copied into + /// , or into when it is + /// null. After a hand-over the builder stays usable: it copies the contents back into + /// memory of its own the next time it is written to, and discards + /// them without copying. Building again without writing returns a buffer that shares + /// the same memory. + /// /// Optional memory allocator. /// Returns an object. public ArrowBuffer Build(MemoryAllocator allocator = default) @@ -220,14 +309,7 @@ public ArrowBuffer Build(MemoryAllocator allocator = default) /// Returns an object. internal ArrowBuffer Build(int byteSize, MemoryAllocator allocator = default) { - int currentBytesLength = Length * _size; - int bufferLength = checked((int)BitUtility.RoundUpToMultiplePowerOfTwo(currentBytesLength, byteSize)); - - MemoryAllocator memoryAllocator = allocator ?? MemoryAllocator.Default.Value; - IMemoryOwner memoryOwner = memoryAllocator.Allocate(bufferLength); - Memory.Slice(0, currentBytesLength).CopyTo(memoryOwner.Memory); - - return new ArrowBuffer(memoryOwner); + return _buffer.Build(Length * Size, byteSize, allocator); } private void EnsureAdditionalCapacity(int additionalCapacity) @@ -242,22 +324,30 @@ private void EnsureCapacity(int requiredCapacity) // TODO: specifiable growth strategy // Double the length of the in-memory array, or use the byte count of the capacity, whichever is // greater. - int capacity = Math.Max(requiredCapacity * _size, Memory.Length * 2); - Reallocate(capacity); + int capacity = Math.Max(checked(requiredCapacity * Size), _buffer.Capacity * 2); + + // Grow through the allocator so that the builder's working memory is + // visible to it, and so that allocators able to grow in place can do so. + _buffer.Grow(capacity); } } - private void Reallocate(int numBytes) + /// + /// Releases the builder's working memory. + /// + /// + /// Disposal is required only when the working memory came from an allocator whose + /// is + /// ; otherwise it merely returns the + /// memory for reuse. Buffers already produced by + /// are unaffected: if one of them holds the builder's memory, disposal only drops the + /// builder's reference to it. + /// + public void Dispose() { - if (numBytes != 0) - { - var memory = new Memory(new byte[numBytes]); - Memory.Slice(0, Length * _size).CopyTo(memory); - - Memory = memory; - } + _buffer.Dispose(); + Length = 0; } - } } diff --git a/src/Apache.Arrow/ArrowBuffer.cs b/src/Apache.Arrow/ArrowBuffer.cs index c2f531f3..83e599bd 100644 --- a/src/Apache.Arrow/ArrowBuffer.cs +++ b/src/Apache.Arrow/ArrowBuffer.cs @@ -34,8 +34,20 @@ public ArrowBuffer(ReadOnlyMemory data) } internal ArrowBuffer(IMemoryOwner memoryOwner) + : this(memoryOwner, AllocationLifetime.Finalized) { - _handle = new SharedMemoryHandle(new SharedMemoryOwner(memoryOwner)); + } + + /// The owner of the buffer's memory. + /// + /// The of the allocator the memory came from. Only + /// memory is released by a finalizer when the + /// buffer is not disposed, as all buffers have been historically; other lifetimes opt out, + /// so that collection can never release memory a span is still using. + /// + internal ArrowBuffer(IMemoryOwner memoryOwner, AllocationLifetime lifetime) + { + _handle = new SharedMemoryHandle(new SharedMemoryOwner(memoryOwner, finalizeWhenUnreachable: lifetime == AllocationLifetime.Finalized)); _memory = Memory.Empty; } @@ -81,9 +93,13 @@ public ArrowBuffer Retain() public ArrowBuffer Clone(MemoryAllocator allocator = default) { - return Span.Length == 0 ? Empty : new Builder(Span.Length) - .Append(Span) - .Build(allocator); + if (Span.Length == 0) + { + return Empty; + } + + using Builder builder = new Builder(Span.Length, allocator); + return builder.Append(Span).Build(allocator); } public bool Equals(ArrowBuffer other) diff --git a/src/Apache.Arrow/Memory/BuilderMemory.cs b/src/Apache.Arrow/Memory/BuilderMemory.cs new file mode 100644 index 00000000..83d1c506 --- /dev/null +++ b/src/Apache.Arrow/Memory/BuilderMemory.cs @@ -0,0 +1,267 @@ +// 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.Buffers; + +namespace Apache.Arrow.Memory +{ + /// + /// The working memory of a buffer builder. + /// + /// + /// + /// Working memory grows in a temporary allocator and the built buffer belongs to a + /// long-term one. When the two are the same allocator, the working memory can be + /// handed to the built buffer instead of being copied; otherwise building copies it. + /// + /// + /// A builder given no allocator uses managed memory as its temporary allocator and + /// as its long-term one, exactly reproducing how + /// builders have always behaved: growth never touches native memory, and building makes a + /// single native allocation of the exact size. Passing an allocator opts into the hand-over. + /// + /// + /// After a hand-over the builder no longer owns writable memory. It keeps a retained + /// reference to the built buffer so that its contents stay readable, and copies them into + /// fresh working memory the first time the builder is written to again. Code that builds + /// once and discards the builder therefore allocates once; code that keeps appending after + /// a build pays one copy, which is what every build cost before. + /// + /// + /// When it can hand over, working memory is always a multiple of + /// bytes, so that a builder created with the right capacity never has to grow to pad its + /// result. + /// + /// + internal sealed class BuilderMemory : IDisposable + { + internal const int Padding = 64; + + /// + /// Hand over only when at most this fraction of the working memory would be unused + /// (1/2). Doubling growth means this almost always holds; it rules out handing a large + /// reservation to a small array, which would hold the slack for the array's lifetime. + /// + private const int MaxSlackDivisor = 2; + + private readonly MemoryAllocator _temporary; + private readonly MemoryAllocator _longTerm; + private readonly bool _canHandOver; + + // Exactly one of these is in use: _owner/_memory while the builder owns its working + // memory, _shared after that memory has been handed to a built buffer. Both are empty + // after disposal. + private IMemoryOwner _owner; + private Memory _memory; + private ArrowBuffer _shared; + private bool _isShared; + + /// + /// The allocator for both working memory and built buffers, or null for managed + /// working memory copied into when built. + /// + /// Initial capacity in bytes. + public BuilderMemory(MemoryAllocator allocator, int capacityBytes) + : this(allocator ?? ManagedMemoryAllocator.Instance, allocator ?? MemoryAllocator.Default.Value, capacityBytes) + { + } + + private BuilderMemory(MemoryAllocator temporary, MemoryAllocator longTerm, int capacityBytes) + { + if (capacityBytes < 0) + { + throw new ArgumentOutOfRangeException(nameof(capacityBytes)); + } + + _temporary = temporary; + _longTerm = longTerm; + _canHandOver = ReferenceEquals(temporary, longTerm); + _owner = _temporary.Allocate(RoundUp(capacityBytes)); + _memory = _owner.Memory; + } + + /// + /// Whether built buffers can take over the working memory. When false, the builder + /// behaves exactly as builders always have. + /// + public bool CanHandOver => _canHandOver; + + /// + /// Size of the working memory in bytes. Reading this never copies. + /// + public int Capacity => _isShared ? _shared.Length : _memory.Length; + + /// + /// The writable working memory. If it has been handed to a built buffer, the contents + /// are first copied into memory the builder owns, so writes never reach that buffer. + /// + public Memory Memory + { + get + { + if (_isShared) + { + Detach(_shared.Length); + } + + return _memory; + } + } + + /// + /// Grows the working memory to at least , preserving + /// its contents and zeroing the added region. + /// + public void Grow(int capacityBytes) + { + int rounded = RoundUp(capacityBytes); + if (rounded <= Capacity) + { + return; + } + + if (_isShared) + { + Detach(rounded); + return; + } + + ThrowIfDisposed(); + _owner = _temporary.Resize(_owner, rounded); + _memory = _owner.Memory; + } + + /// + /// Zeroes the working memory, keeping its capacity. Discards rather than copies memory + /// that was handed to a built buffer, so clearing a builder after a build is cheap. + /// + public void Reset() + { + if (_isShared) + { + int capacity = _shared.Length; + ReleaseShared(); + _owner = _temporary.Allocate(capacity); + _memory = _owner.Memory; + return; + } + + _memory.Span.Clear(); + } + + /// + /// Builds a buffer holding the first bytes, zero-padded to + /// a multiple of . + /// + /// + /// Allocator that should own the result; null means this builder's long-term + /// allocator. The working memory is handed over only when that is also the temporary + /// allocator; otherwise the data is copied. + /// + public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) + { + int padded = checked((int)BitUtility.RoundUpToMultiplePowerOfTwo(usedBytes, byteSize)); + MemoryAllocator destination = target ?? _longTerm; + bool handOver = _canHandOver && ReferenceEquals(destination, _temporary); + + if (_isShared) + { + // Built again without being written to: share the same memory. + if (handOver && padded == _shared.Length) + { + return _shared.Retain(); + } + + return Copy(_shared.Span, usedBytes, padded, destination); + } + + ThrowIfDisposed(); + + if (!handOver || padded == 0 || padded > _memory.Length || + _memory.Length - padded > _memory.Length / MaxSlackDivisor) + { + return Copy(_memory.Span, usedBytes, padded, destination); + } + + // The bytes between the data and the padding boundary may hold values left behind + // by a Resize or a Set, which the copying path would have left as zero. + _memory.Span.Slice(usedBytes, padded - usedBytes).Clear(); + + IMemoryOwner owner = padded == _memory.Length + ? _owner + : new SlicedMemoryOwner(_owner, padded); + + ArrowBuffer result = new ArrowBuffer(owner, _temporary.Lifetime); + _shared = result.Retain(); + _isShared = true; + _owner = null; + _memory = Memory.Empty; + + return result; + } + + public void Dispose() + { + if (_isShared) + { + ReleaseShared(); + return; + } + + IMemoryOwner owner = _owner; + _owner = null; + _memory = Memory.Empty; + owner?.Dispose(); + } + + private void Detach(int capacityBytes) + { + IMemoryOwner owner = _temporary.Allocate(capacityBytes); + _shared.Span.CopyTo(owner.Memory.Span); + ReleaseShared(); + _owner = owner; + _memory = owner.Memory; + } + + private void ReleaseShared() + { + ArrowBuffer shared = _shared; + _shared = default; + _isShared = false; + shared.Dispose(); + } + + private static ArrowBuffer Copy(ReadOnlySpan source, int usedBytes, int padded, MemoryAllocator allocator) + { + IMemoryOwner owner = allocator.Allocate(padded); + source.Slice(0, usedBytes).CopyTo(owner.Memory.Span); + return new ArrowBuffer(owner, allocator.Lifetime); + } + + private void ThrowIfDisposed() + { + if (_owner == null) + { + throw new ObjectDisposedException(nameof(ArrowBuffer.Builder)); + } + } + + // Only memory that may be handed over needs padding; otherwise allocate exactly what + // was asked for, as builders always have. + private int RoundUp(int bytes) => + _canHandOver ? checked((int)BitUtility.RoundUpToMultipleOf64(bytes)) : bytes; + } +} diff --git a/src/Apache.Arrow/Memory/SlicedMemoryOwner.cs b/src/Apache.Arrow/Memory/SlicedMemoryOwner.cs new file mode 100644 index 00000000..c5cd7335 --- /dev/null +++ b/src/Apache.Arrow/Memory/SlicedMemoryOwner.cs @@ -0,0 +1,44 @@ +// 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.Buffers; + +namespace Apache.Arrow.Memory +{ + /// + /// Exposes a prefix of another owner's memory without copying it. + /// + /// + /// Used when a builder hands its working memory to an : growth is + /// geometric, so the working buffer is usually larger than the array needs, and the buffer + /// must report only the bytes that belong to it. + /// + internal sealed class SlicedMemoryOwner : IMemoryOwner + { + private readonly IMemoryOwner _inner; + private readonly int _length; + + public SlicedMemoryOwner(IMemoryOwner inner, int length) + { + _inner = inner ?? throw new ArgumentNullException(nameof(inner)); + _length = length; + } + + public Memory Memory => _inner.Memory.Slice(0, _length); + + public void Dispose() => _inner.Dispose(); + } +} diff --git a/src/Apache.Arrow/RecordBatch.Builder.cs b/src/Apache.Arrow/RecordBatch.Builder.cs index 0e881f04..958300f9 100644 --- a/src/Apache.Arrow/RecordBatch.Builder.cs +++ b/src/Apache.Arrow/RecordBatch.Builder.cs @@ -33,66 +33,74 @@ internal ArrayBuilder(MemoryAllocator allocator) _allocator = allocator; } - public BooleanArray Boolean(Action action) => Build(new BooleanArray.Builder(), action); - public Int8Array Int8(Action action) => Build(new Int8Array.Builder(), action); - public Int16Array Int16(Action action) => Build(new Int16Array.Builder(), action); - public Int32Array Int32(Action action) => Build(new Int32Array.Builder(), action); - public Int64Array Int64(Action action) => Build(new Int64Array.Builder(), action); - public UInt8Array UInt8(Action action) => Build(new UInt8Array.Builder(), action); - public UInt16Array UInt16(Action action) => Build(new UInt16Array.Builder(), action); - public UInt32Array UInt32(Action action) => Build(new UInt32Array.Builder(), action); - public UInt64Array UInt64(Action action) => Build(new UInt64Array.Builder(), action); + public BooleanArray Boolean(Action action) => Build(new BooleanArray.Builder(_allocator), action); + public Int8Array Int8(Action action) => Build(new Int8Array.Builder(0, _allocator), action); + public Int16Array Int16(Action action) => Build(new Int16Array.Builder(0, _allocator), action); + public Int32Array Int32(Action action) => Build(new Int32Array.Builder(0, _allocator), action); + public Int64Array Int64(Action action) => Build(new Int64Array.Builder(0, _allocator), action); + public UInt8Array UInt8(Action action) => Build(new UInt8Array.Builder(0, _allocator), action); + public UInt16Array UInt16(Action action) => Build(new UInt16Array.Builder(0, _allocator), action); + public UInt32Array UInt32(Action action) => Build(new UInt32Array.Builder(0, _allocator), action); + public UInt64Array UInt64(Action action) => Build(new UInt64Array.Builder(0, _allocator), action); #if NET5_0_OR_GREATER - public HalfFloatArray HalfFloat(Action action) => Build(new HalfFloatArray.Builder(), action); + public HalfFloatArray HalfFloat(Action action) => Build(new HalfFloatArray.Builder(0, _allocator), action); #endif - public FloatArray Float(Action action) => Build(new FloatArray.Builder(), action); - public DoubleArray Double(Action action) => Build(new DoubleArray.Builder(), action); + public FloatArray Float(Action action) => Build(new FloatArray.Builder(0, _allocator), action); + public DoubleArray Double(Action action) => Build(new DoubleArray.Builder(0, _allocator), action); public Decimal32Array Decimal32(Decimal32Type type, Action action) => Build( - new Decimal32Array.Builder(type), action); + new Decimal32Array.Builder(type, _allocator), action); public Decimal64Array Decimal64(Decimal64Type type, Action action) => Build( - new Decimal64Array.Builder(type), action); + new Decimal64Array.Builder(type, _allocator), action); public Decimal128Array Decimal128(Decimal128Type type, Action action) => Build( - new Decimal128Array.Builder(type), action); + new Decimal128Array.Builder(type, _allocator), action); public Decimal256Array Decimal256(Decimal256Type type, Action action) => Build( - new Decimal256Array.Builder(type), action); - public Date32Array Date32(Action action) => Build(new Date32Array.Builder(), action); - public Date64Array Date64(Action action) => Build(new Date64Array.Builder(), action); - public Time32Array Time32(Action action) => Build(new Time32Array.Builder(), action); + new Decimal256Array.Builder(type, _allocator), action); + public Date32Array Date32(Action action) => Build(new Date32Array.Builder(0, _allocator), action); + public Date64Array Date64(Action action) => Build(new Date64Array.Builder(0, _allocator), action); + public Time32Array Time32(Action action) => Build(new Time32Array.Builder(Time32Type.Default, 0, _allocator), action); public Time32Array Time32(Time32Type type, Action action) => Build( - new Time32Array.Builder(type), action); - public Time64Array Time64(Action action) => Build(new Time64Array.Builder(), action); + new Time32Array.Builder(type, 0, _allocator), action); + public Time64Array Time64(Action action) => Build(new Time64Array.Builder(Time64Type.Default, 0, _allocator), action); public Time64Array Time64(Time64Type type, Action action) => Build( - new Time64Array.Builder(type), action); + new Time64Array.Builder(type, 0, _allocator), action); public DurationArray Duration(DurationType type, Action action) => - Build(new DurationArray.Builder(type), action); - public BinaryArray Binary(Action action) => Build(new BinaryArray.Builder(), action); - public StringArray String(Action action) => Build(new StringArray.Builder(), action); - public TimestampArray Timestamp(Action action) => Build(new TimestampArray.Builder(), action); + Build(new DurationArray.Builder(type, 0, _allocator), action); + public BinaryArray Binary(Action action) => Build(new BinaryArray.Builder(BinaryType.Default, _allocator), action); + public StringArray String(Action action) => Build(new StringArray.Builder(_allocator), action); + public TimestampArray Timestamp(Action action) => Build(new TimestampArray.Builder(TimestampType.Default, 0, _allocator), action); public TimestampArray Timestamp(TimestampType type, Action action) => Build( - new TimestampArray.Builder(type), action); + new TimestampArray.Builder(type, 0, _allocator), action); public TimestampArray Timestamp(TimeUnit unit, TimeZoneInfo timezone, Action action) => Build( - new TimestampArray.Builder(new TimestampType(unit, timezone)), action); + new TimestampArray.Builder(new TimestampType(unit, timezone), 0, _allocator), action); private TArray Build(TArrayBuilder builder, Action action) where TArray : IArrowArray where TArrayBuilder : IArrowArrayBuilder { - if (action == null) + try { - return default; - } + if (action == null) + { + return default; + } - action(builder); + action(builder); - return builder.Build(_allocator); + return builder.Build(_allocator); + } + finally + { + // The built array owns its memory; this releases only the builder's. + (builder as IDisposable)?.Dispose(); + } } } @@ -105,7 +113,9 @@ public class Builder public Builder(MemoryAllocator allocator = default) { - _allocator = allocator ?? MemoryAllocator.Default.Value; + // Kept as given: a null allocator gives the column builders managed working memory + // and copies the built arrays into MemoryAllocator.Default, as it always has. + _allocator = allocator; _arrayBuilder = new ArrayBuilder(_allocator); _schemaBuilder = new Schema.Builder(); _arrays = new List(); diff --git a/test/Apache.Arrow.Tests/AllocatorTests.cs b/test/Apache.Arrow.Tests/AllocatorTests.cs new file mode 100644 index 00000000..e9796e4f --- /dev/null +++ b/test/Apache.Arrow.Tests/AllocatorTests.cs @@ -0,0 +1,483 @@ +// 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.Buffers; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; +using System.Threading.Tasks; +using Apache.Arrow.Memory; +using Xunit; + +namespace Apache.Arrow.Tests +{ + public class AllocatorTests + { + private const int Elements = 4096; + + [Fact] + public void LifetimeDescribesEachAllocator() + { + Assert.Equal(AllocationLifetime.GarbageCollected, new PooledManagedAllocator().Lifetime); + Assert.Equal(AllocationLifetime.GarbageCollected, new ManagedMemoryAllocator().Lifetime); + Assert.Equal(AllocationLifetime.CallerOwned, new CallerOwnedNativeAllocator().Lifetime); + Assert.Equal(AllocationLifetime.Finalized, new NativeMemoryAllocator().Lifetime); + } + + [Fact] + public void DefaultAllocatorIsUnchanged() + { + // Out-of-the-box behaviour: anything not given an allocator uses native memory. + Assert.IsType(MemoryAllocator.Default.Value); + } + + [Theory] + [MemberData(nameof(Allocators))] + public void AllocatesZeroedMemory(MemoryAllocator allocator) + { + using (IMemoryOwner owner = allocator.Allocate(1024)) + { + Assert.Equal(1024, owner.Memory.Length); + ReadOnlySpan span = owner.Memory.Span; + for (int i = 0; i < span.Length; i++) + { + Assert.Equal(0, span[i]); + } + } + } + + [Theory] + [MemberData(nameof(Allocators))] + public void RoundTripsDataThroughBuilders(MemoryAllocator allocator) + { + Int32Array array = BuildInt32Array(allocator, Elements); + + Assert.Equal(Elements, array.Length); + for (int i = 0; i < Elements; i++) + { + Assert.Equal(i, array.GetValue(i)); + } + } + + [Theory] + [MemberData(nameof(Allocators))] + public void DoubleDisposeIsSafe(MemoryAllocator allocator) + { + IMemoryOwner owner = allocator.Allocate(256); + owner.Dispose(); + owner.Dispose(); + } + + [Theory] + [MemberData(nameof(Allocators))] + public void ResizePreservesContents(MemoryAllocator allocator) + { + IMemoryOwner owner = allocator.Allocate(128); + for (int i = 0; i < 128; i++) + { + owner.Memory.Span[i] = (byte)(i & 0xFF); + } + + IMemoryOwner resized = allocator.Resize(owner, 512); + try + { + Assert.Equal(512, resized.Memory.Length); + ReadOnlySpan span = resized.Memory.Span; + for (int i = 0; i < 128; i++) + { + Assert.Equal((byte)(i & 0xFF), span[i]); + } + + // Newly grown region must be zeroed. + for (int i = 128; i < 512; i++) + { + Assert.Equal(0, span[i]); + } + } + finally + { + resized.Dispose(); + } + } + + /// + /// The regression test for https://github.com/apache/arrow-dotnet/issues/397: a span + /// taken from a buffer must stay valid across a collection even when nothing else + /// references the array it came from. + /// + [Theory] + [MemberData(nameof(Allocators))] + public void SpansSurviveCollectionWithoutKeepAlive(MemoryAllocator allocator) + { + AssertSpanSurvivesCollection(allocator); + } + + [MethodImpl(MethodImplOptions.NoInlining)] + private static void AssertSpanSurvivesCollection(MemoryAllocator allocator) + { + Int32Array array = BuildInt32Array(allocator, Elements); + ReadOnlySpan values = array.Values; + + // Drop the only strong reference to the array before reading the span. + array = null; + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + + for (int i = 0; i < Elements; i++) + { + Assert.Equal(i, values[i]); + } + } + + [Fact] + public void PooledAllocatorReusesBuffers() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + IMemoryOwner first = allocator.Allocate(64 * 1024); + byte[] firstArray = GetBackingArray(first); + first.Dispose(); + + IMemoryOwner second = allocator.Allocate(64 * 1024); + byte[] secondArray = GetBackingArray(second); + second.Dispose(); + + Assert.Same(firstArray, secondArray); + } + + [Fact] + public void PooledAllocatorZeroesReusedBuffers() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + IMemoryOwner first = allocator.Allocate(4096); + first.Memory.Span.Fill(0xFF); + first.Dispose(); + + using (IMemoryOwner second = allocator.Allocate(4096)) + { + ReadOnlySpan span = second.Memory.Span; + for (int i = 0; i < span.Length; i++) + { + Assert.Equal(0, span[i]); + } + } + } + + [Fact] + public void CallerOwnedAllocatorHonoursAlignment() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(alignment: 64); + + using (IMemoryOwner owner = allocator.Allocate(1000)) + { + using (MemoryHandle handle = owner.Memory.Pin()) + { + unsafe + { + Assert.Equal(0, (long)handle.Pointer % 64); + } + } + } + } + + [Fact] + public void CallerOwnedAllocatorRejectsNonPowerOfTwoAlignment() + { + Assert.Throws(() => new CallerOwnedNativeAllocator(alignment: 48)); + } + + [Fact] + public void BuilderAllocatorBacksTheBuiltArray() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + Int32Array array = BuildInt32Array(allocator, 128); + + Assert.True(allocator.Statistics.Allocations > 0); + Assert.True(MemoryMarshal.TryGetArray(array.ValueBuffer.Memory, out ArraySegment _)); + } + + [Fact] + public void BuilderWorkingMemoryComesFromAllocator() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + using (ArrowBuffer.Builder builder = new ArrowBuffer.Builder(4, allocator)) + { + long initialAllocations = allocator.Statistics.Allocations; + Assert.Equal(1, initialAllocations); + + // Force several growth steps. + for (int i = 0; i < 4096; i++) + { + builder.Append(i); + } + + // Growth now goes through the allocator instead of `new byte[]`. + Assert.True(allocator.Statistics.Allocations > initialAllocations); + } + } + + [Fact] + public void BitmapBuilderWorkingMemoryComesFromAllocator() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + using (ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(8, allocator)) + { + long initialAllocations = allocator.Statistics.Allocations; + + for (int i = 0; i < 4096; i++) + { + builder.Append(i % 3 == 0); + } + + Assert.True(allocator.Statistics.Allocations > initialAllocations); + Assert.Equal(4096, builder.Length); + } + } + + [Fact] + public void BitmapBuilderGrowthZeroesNewBytes() + { + // The bitmap relies on grown regions being zero, so Resize must not leave garbage. + using (ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(8, new PooledManagedAllocator())) + { + for (int i = 0; i < 4096; i++) + { + builder.Append(false); + } + + Assert.Equal(0, builder.SetBitCount); + ReadOnlySpan span = builder.Span; + for (int i = 0; i < span.Length; i++) + { + Assert.Equal(0, span[i]); + } + } + } + + [Fact] + public void DisposingBuilderReturnsWorkingMemoryToPool() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + ArrowBuffer.Builder first = new ArrowBuffer.Builder(64 * 1024, allocator); + byte[] firstArray = GetBackingArray(first.Memory); + first.Dispose(); + + ArrowBuffer.Builder second = new ArrowBuffer.Builder(64 * 1024, allocator); + byte[] secondArray = GetBackingArray(second.Memory); + second.Dispose(); + + Assert.Same(firstArray, secondArray); + } + + [Fact] + public void BuiltBufferOutlivesBuilderDisposal() + { + // Build() usually hands the builder's working memory to the buffer, so disposing + // the builder must release only its own reference, not the buffer's memory. + ArrowBuffer buffer; + using (ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, new PooledManagedAllocator())) + { + for (int i = 0; i < 512; i++) + { + builder.Append(i); + } + + buffer = builder.Build(); + } + + ReadOnlySpan values = buffer.Span.CastTo(); + for (int i = 0; i < 512; i++) + { + Assert.Equal(i, values[i]); + } + } + + [Fact] + public void ManagedAllocatorSpansStayValidAfterDisposal() + { + IMemoryOwner owner = new ManagedMemoryAllocator().Allocate(16); + Span span = owner.Memory.Span; + span[0] = 42; + + owner.Dispose(); + + // Nothing is reused, so even a span used after disposal still sees its own data. + Assert.Equal(42, span[0]); + Assert.True(owner.Memory.IsEmpty); + } + + [Fact] + public void PooledAllocatorDoesNotPoolLargeAllocations() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + int large = PooledManagedAllocatorOptions.DefaultMaxPooledLength + 1; + + IMemoryOwner first = allocator.Allocate(large); + byte[] firstArray = GetBackingArray(first); + first.Dispose(); + + IMemoryOwner second = allocator.Allocate(large); + Assert.NotSame(firstArray, GetBackingArray(second)); + Assert.Equal(0, allocator.RetainedBytes); + second.Dispose(); + } + + [Fact] + public void PooledAllocatorKeepsAtMostMaxArraysPerSize() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { MaxArraysPerSize = 2 }); + + IMemoryOwner[] owners = { allocator.Allocate(1000), allocator.Allocate(1000), allocator.Allocate(1000) }; + foreach (IMemoryOwner owner in owners) + { + owner.Dispose(); + } + + Assert.Equal(2 * 1024, allocator.RetainedBytes); + } + + [Fact] + public void PooledAllocatorHonoursMaxRetainedBytes() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { MaxRetainedBytes = 3000 }); + + IMemoryOwner[] owners = { allocator.Allocate(1000), allocator.Allocate(1000), allocator.Allocate(1000) }; + foreach (IMemoryOwner owner in owners) + { + owner.Dispose(); + } + + // Each 1000-byte allocation is a 1024-byte array; a third would exceed the limit. + Assert.Equal(2 * 1024, allocator.RetainedBytes); + } + + [Fact] + public void PooledAllocatorStopsRetainingArraysWhenTheyAreReused() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(); + + allocator.Allocate(1000).Dispose(); + Assert.Equal(1024, allocator.RetainedBytes); + + using IMemoryOwner reused = allocator.Allocate(600); + Assert.Equal(0, allocator.RetainedBytes); + } + + [Fact] + public void PooledAllocatorCanPoisonDisposedBuffers() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + + IMemoryOwner owner = allocator.Allocate(100); + owner.Memory.Span.Fill(1); + byte[] array = GetBackingArray(owner); + owner.Dispose(); + + // A span wrongly used after disposal would now see the poison pattern... + Assert.All(array, b => Assert.Equal(0xDE, b)); + + // ...while the next buffer to reuse the array still starts zeroed. + using IMemoryOwner next = allocator.Allocate(100); + Assert.Same(array, GetBackingArray(next)); + Assert.All(next.Memory.ToArray(), b => Assert.Equal(0, b)); + } + + [Fact] + public void PooledAllocatorPoolingCanBeDisabled() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { MaxPooledLength = 0 }); + + allocator.Allocate(100).Dispose(); + + Assert.Equal(0, allocator.RetainedBytes); + } + + [Theory] + [InlineData(-1, 1, 0)] + [InlineData((1 << 30) + 1, 1, 0)] + [InlineData(1024, -1, 0)] + [InlineData(1024, 1, -1)] + public void PooledAllocatorRejectsInvalidOptions(int maxPooledLength, int maxArraysPerSize, long maxRetainedBytes) + { + PooledManagedAllocatorOptions options = new PooledManagedAllocatorOptions + { + MaxPooledLength = maxPooledLength, + MaxArraysPerSize = maxArraysPerSize, + MaxRetainedBytes = maxRetainedBytes, + }; + + Assert.Throws(() => new PooledManagedAllocator(options)); + } + + [Fact] + public void PooledAllocatorIsSafeUnderConcurrentUse() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { MaxArraysPerSize = 4 }); + + Parallel.For(0, 4000, i => + { + int length = 16 << (i % 12); + using IMemoryOwner owner = allocator.Allocate(length); + Span span = owner.Memory.Span; + Assert.Equal(length, span.Length); + Assert.Equal(0, span[length - 1]); + span.Fill(0xFF); + }); + + // At most four arrays of each of the twelve sizes used. + long bound = 0; + for (int i = 0; i < 12; i++) + { + bound += 4L * (16 << i); + } + Assert.InRange(allocator.RetainedBytes, 0, bound); + } + + public static TheoryData Allocators => new TheoryData + { + new PooledManagedAllocator(), + new CallerOwnedNativeAllocator(), + new ManagedMemoryAllocator(), + }; + + private static Int32Array BuildInt32Array(MemoryAllocator allocator, int count) + { + using Int32Array.Builder builder = new Int32Array.Builder(0, allocator); + for (int i = 0; i < count; i++) + { + builder.Append(i); + } + + return builder.Build(); + } + + private static byte[] GetBackingArray(IMemoryOwner owner) + { + return GetBackingArray(owner.Memory); + } + + private static byte[] GetBackingArray(ReadOnlyMemory memory) + { + Assert.True(MemoryMarshal.TryGetArray(memory, out ArraySegment segment)); + return segment.Array; + } + } +} diff --git a/test/Apache.Arrow.Tests/ArrowArrayConcatenatorTests.cs b/test/Apache.Arrow.Tests/ArrowArrayConcatenatorTests.cs index f5b798a3..d4741521 100644 --- a/test/Apache.Arrow.Tests/ArrowArrayConcatenatorTests.cs +++ b/test/Apache.Arrow.Tests/ArrowArrayConcatenatorTests.cs @@ -1251,7 +1251,7 @@ private void GenerateTestData( where TArrayBuilder : IArrowArrayBuilder where TArray : IArrowArray { - var resultBuilder = (TArrayBuilder)ArrowArrayBuilderFactory.Build(type); + var resultBuilder = (TArrayBuilder)ArrowArrayBuilderFactory.Build(type, allocator: null); if (initAction != null) { initAction(resultBuilder, _resultTotalElementCount); @@ -1264,7 +1264,7 @@ private void GenerateTestData( for (int i = 0; i < _baseDataListCount; i++) { List dataList = _baseData[i]; - var builder = (TArrayBuilder)ArrowArrayBuilderFactory.Build(type); + var builder = (TArrayBuilder)ArrowArrayBuilderFactory.Build(type, allocator: null); if (initAction != null) { initAction(builder, dataList.Count); @@ -1688,7 +1688,7 @@ private static string[] DictionaryStrings(DictionaryArray array) private static FixedSizeListArray BuildFixedSizeListArray(int listSize, int[] flatValues) { var type = new FixedSizeListType(Int32Type.Default, listSize); - var builder = new FixedSizeListArray.Builder(type); + var builder = new FixedSizeListArray.Builder(type, allocator: null); int listCount = flatValues.Length / listSize; var valueBuilder = (Int32Array.Builder)builder.ValueBuilder; for (int i = 0; i < listCount; i++) diff --git a/test/Apache.Arrow.Tests/BuilderHandOverTests.cs b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs new file mode 100644 index 00000000..f22a8c8b --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs @@ -0,0 +1,431 @@ +// 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.CompilerServices; +using System.Runtime.InteropServices; +using Apache.Arrow.Memory; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Tests that buffer builders hand their working memory to the buffer they build instead + /// of copying it, and that doing so never lets a later write reach a built buffer. + /// + public class BuilderHandOverTests + { + [Fact] + public void BuilderWithFinalCapacityAllocatesOnce() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(100, allocator); + + for (int i = 0; i < 100; i++) + { + builder.Append(i); + } + + ref byte working = ref MemoryMarshal.GetReference(builder.Memory.Span); + using ArrowBuffer buffer = builder.Build(); + + Assert.Equal(1, allocator.Statistics.Allocations); + Assert.True(Unsafe.AreSame(ref working, ref MemoryMarshal.GetReference(buffer.Span))); + Assert.Equal(448, buffer.Length); // 400 bytes padded to a multiple of 64 + AssertSequence(buffer, 100); + } + + [Fact] + public void PaddingIsZeroedEvenIfWorkingMemoryWasWritten() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + + // Resize exposes the region; shrinking back leaves the values behind in working memory. + builder.Resize(16); + builder.Span.Fill(-1); + builder.Resize(2); + + using ArrowBuffer buffer = builder.Build(); + + ReadOnlySpan values = buffer.Span.CastTo(); + Assert.Equal(-1, values[0]); + Assert.Equal(-1, values[1]); + for (int i = 2; i < values.Length; i++) + { + Assert.Equal(0, values[i]); + } + } + + [Fact] + public void AppendingAfterBuildDoesNotModifyBuiltBuffer() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + builder.Append(1).Append(2); + + using ArrowBuffer first = builder.Build(); + builder.Append(3); + builder.Span[0] = 100; + using ArrowBuffer second = builder.Build(); + + Assert.Equal(new[] { 1, 2 }, first.Span.CastTo().Slice(0, 2).ToArray()); + Assert.Equal(new[] { 100, 2, 3 }, second.Span.CastTo().Slice(0, 3).ToArray()); + Assert.Equal(0, first.Span.CastTo()[2]); + } + + [Fact] + public void WritingThroughSpanAfterBuildDoesNotModifyBuiltBuffer() + { + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, new CallerOwnedNativeAllocator()); + builder.Append(7); + + using ArrowBuffer buffer = builder.Build(); + builder.Span[0] = 8; + + Assert.Equal(7, buffer.Span.CastTo()[0]); + } + + [Fact] + public void ClearAfterBuildDiscardsWithoutCopying() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + builder.Append(1).Append(2); + + using ArrowBuffer first = builder.Build(); + builder.Clear(); + builder.Append(5); + using ArrowBuffer second = builder.Build(); + + // One allocation for the first build's memory and one fresh one after Clear. + Assert.Equal(2, allocator.Statistics.Allocations); + Assert.Equal(new[] { 1, 2 }, first.Span.CastTo().Slice(0, 2).ToArray()); + Assert.Equal(new[] { 5, 0 }, second.Span.CastTo().Slice(0, 2).ToArray()); + } + + [Fact] + public void BuildingTwiceWithoutWritingSharesMemory() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + builder.Append(42); + + ArrowBuffer first = builder.Build(); + ArrowBuffer second = builder.Build(); + + Assert.Equal(1, allocator.Statistics.Allocations); + Assert.True(Unsafe.AreSame( + ref MemoryMarshal.GetReference(first.Span), + ref MemoryMarshal.GetReference(second.Span))); + + // Each holder releases its own reference; the memory survives until the last. + first.Dispose(); + builder.Dispose(); + Assert.Equal(42, second.Span.CastTo()[0]); + second.Dispose(); + } + + [Fact] + public void BuiltBufferSurvivesBuilderDisposal() + { + ArrowBuffer.Builder builder = new ArrowBuffer.Builder(64, new CallerOwnedNativeAllocator()); + for (int i = 0; i < 64; i++) + { + builder.Append(i); + } + + using ArrowBuffer buffer = builder.Build(); + builder.Dispose(); + + AssertSequence(buffer, 64); + } + + [Fact] + public void DisposingBuiltBufferLeavesBuilderReadable() + { + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, new CallerOwnedNativeAllocator()); + builder.Append(1).Append(2); + + builder.Build().Dispose(); + builder.Append(3); + + Assert.Equal(new[] { 1, 2, 3 }, builder.Span.Slice(0, 3).ToArray()); + } + + [Fact] + public void DifferentAllocatorForcesCopy() + { + CallerOwnedNativeAllocator working = new CallerOwnedNativeAllocator(); + CallerOwnedNativeAllocator target = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, working); + builder.Append(1); + + ref byte workingRef = ref MemoryMarshal.GetReference(builder.Memory.Span); + using ArrowBuffer buffer = builder.Build(target); + + Assert.Equal(1, target.Statistics.Allocations); + Assert.False(Unsafe.AreSame(ref workingRef, ref MemoryMarshal.GetReference(buffer.Span))); + + // The builder kept its working memory, so writing to it costs nothing. + builder.Append(2); + Assert.Equal(1, working.Statistics.Allocations); + } + + [Fact] + public void LargeReservationForSmallBufferIsCopied() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(1024, allocator); + builder.Append(1); + + using ArrowBuffer buffer = builder.Build(); + + Assert.Equal(2, allocator.Statistics.Allocations); + Assert.Equal(64, buffer.Length); + } + + [Fact] + public void GrowingBuilderHandsOverItsFinalBuffer() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, allocator); + for (int i = 0; i < 1000; i++) + { + builder.Append(i); + } + + long allocationsBeforeBuild = allocator.Statistics.Allocations; + using ArrowBuffer buffer = builder.Build(); + + Assert.Equal(allocationsBeforeBuild, allocator.Statistics.Allocations); + AssertSequence(buffer, 1000); + } + + [Fact] + public void BitmapBuilderHandsOverAndIsolatesLaterWrites() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(64, allocator); + builder.Append(true).Append(false).Append(true); + + using ArrowBuffer buffer = builder.Build(); + Assert.Equal(1, allocator.Statistics.Allocations); + + builder.Set(1); + builder.Toggle(0); + + Assert.Equal(0b101, buffer.Span[0]); + Assert.Equal(0b110, builder.Span[0]); + Assert.Equal(2, builder.SetBitCount); + } + + [Fact] + public void ArrayBuilderCanBeReusedAfterBuild() + { + Int32Array.Builder builder = new Int32Array.Builder(); + builder.Append(1).AppendNull().Append(3); + + Int32Array first = builder.Build(); + builder.Append(4).Set(0, 10); + Int32Array second = builder.Build(); + builder.Clear().Append(99); + Int32Array third = builder.Build(); + + Assert.Equal(new int?[] { 1, null, 3 }, ToArray(first)); + Assert.Equal(new int?[] { 10, null, 3, 4 }, ToArray(second)); + Assert.Equal(new int?[] { 99 }, ToArray(third)); + } + + [Fact] + public void CloneAllocatesOnce() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using ArrowBuffer source = new ArrowBuffer(new byte[] { 1, 2, 3 }); + + using ArrowBuffer clone = source.Clone(allocator); + + // Clone builds in the target allocator, so its working memory becomes the clone. + Assert.Equal(1, allocator.Statistics.Allocations); + Assert.Equal(new byte[] { 1, 2, 3 }, clone.Span.Slice(0, 3).ToArray()); + } + + private static void AssertSequence(ArrowBuffer buffer, int count) + { + ReadOnlySpan values = buffer.Span.CastTo(); + for (int i = 0; i < count; i++) + { + Assert.Equal(i, values[i]); + } + } + + private static int?[] ToArray(Int32Array array) + { + int?[] result = new int?[array.Length]; + for (int i = 0; i < array.Length; i++) + { + result[i] = array.GetValue(i); + } + return result; + } + } + + /// + /// Tests that the fixed-width array builders allocate once when given their final length, + /// counting allocations through the allocator each builder is given. + /// + public class ArrayBuilderSingleAllocationTests + { + [Fact] + public void CapacityConstructorWithGetSpanAllocatesOnce() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using Int32Array.Builder builder = new Int32Array.Builder(100, allocator); + Span span = builder.GetSpan(100); + Assert.Equal(100, span.Length); + for (int i = 0; i < span.Length; i++) + { + span[i] = i; + } + + using Int32Array array = builder.Advance(100).Build(); + + Assert.Equal(1, allocator.Statistics.Allocations); + Assert.Equal(100, array.Length); + Assert.Equal(0, array.NullCount); + Assert.True(array.NullBitmapBuffer.IsEmpty); + Assert.Equal(99, array.GetValue(99)); + } + + [Fact] + public void ZeroCapacityThenReserveAllocatesOnce() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using Int64Array.Builder builder = new Int64Array.Builder(0, allocator); + Assert.Equal(0, allocator.Statistics.Allocations); + + builder.Reserve(100); + for (long i = 0; i < 100; i++) + { + builder.Append(i); + } + + using Int64Array array = builder.Build(); + + Assert.Equal(1, allocator.Statistics.Allocations); + Assert.Equal(99L, array.GetValue(99)); + } + + [Fact] + public void TypedBuildersBuildFromTheirAllocator() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + + using TimestampArray.Builder timestampBuilder = new TimestampArray.Builder(TimestampType.Default, 16, allocator); + using Date32Array.Builder dateBuilder = new Date32Array.Builder(16, allocator); + using Time64Array.Builder timeBuilder = new Time64Array.Builder(Time64Type.Default, 16, allocator); + using DurationArray.Builder durationBuilder = new DurationArray.Builder(DurationType.Millisecond, 16, allocator); + using DayTimeIntervalArray.Builder intervalBuilder = new DayTimeIntervalArray.Builder(16, allocator); + + using TimestampArray timestamps = timestampBuilder.Append(DateTimeOffset.FromUnixTimeMilliseconds(1000)).Build(); + using Date32Array dates = dateBuilder.Append(new DateTime(2000, 1, 1)).Build(); + using Time64Array times = timeBuilder.Append(5).Build(); + using DurationArray durations = durationBuilder.Append(7).Build(); + using DayTimeIntervalArray intervals = intervalBuilder.Append(new Scalars.DayTimeInterval(1, 2)).Build(); + + Assert.Equal(5, allocator.Statistics.Allocations); + Assert.Equal(DateTimeOffset.FromUnixTimeMilliseconds(1000), timestamps.GetTimestamp(0)); + Assert.Equal(new DateTime(2000, 1, 1), dates.GetDateTime(0)); + Assert.Equal(5L, times.GetValue(0)); + Assert.Equal(7L, durations.GetValue(0)); + } + + [Fact] + public void FirstNullCreatesBitmapWithEarlierValuesValid() + { + Int32Array array = new Int32Array.Builder() + .Append(1) + .Append(2) + .AppendNull() + .Append(4) + .Build(); + + Assert.Equal(1, array.NullCount); + Assert.Equal(new int?[] { 1, 2, null, 4 }, ToArray(array)); + } + + [Fact] + public void AdvanceAfterNullMarksValuesValid() + { + Int32Array.Builder builder = new Int32Array.Builder(); + builder.AppendNull(); + Span span = builder.GetSpan(2); + span[0] = 10; + span[1] = 11; + builder.Advance(2); + + Assert.Equal(new int?[] { null, 10, 11 }, ToArray(builder.Build())); + } + + [Fact] + public void GrowingResizeStillAddsNulls() + { + Int32Array array = new Int32Array.Builder().Resize(3).Set(1, 5).Build(); + + Assert.Equal(new int?[] { null, 5, null }, ToArray(array)); + } + + [Fact] + public void SetAndSwapRejectIndexesPastLength() + { + Int32Array.Builder builder = new Int32Array.Builder(16).Append(1); + + Assert.Throws(() => builder.Set(1, 5)); + Assert.Throws(() => builder.Swap(0, 1)); + } + + [Fact] + public void AdvancePastCapacityThrows() + { + Int32Array.Builder builder = new Int32Array.Builder(); + builder.GetSpan(4); + + Assert.Throws(() => builder.Advance(1000)); + Assert.Throws(() => builder.Advance(-1)); + } + + [Fact] + public void ExplicitAllocatorIsUsedForValuesAndBitmap() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + using Int32Array.Builder builder = new Int32Array.Builder(16, allocator); + using Int32Array array = builder.Append(1).AppendNull().Build(); + + Assert.Equal(2, allocator.Statistics.Allocations); // values and bitmap + Assert.Equal(1, array.NullCount); + } + + private static int?[] ToArray(Int32Array array) + { + int?[] result = new int?[array.Length]; + for (int i = 0; i < array.Length; i++) + { + result[i] = array.GetValue(i); + } + return result; + } + } +} diff --git a/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs b/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs new file mode 100644 index 00000000..e85cd9d8 --- /dev/null +++ b/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs @@ -0,0 +1,196 @@ +// 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.Buffers; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; +using System.Threading; +using Apache.Arrow.Memory; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Tests that code which does not pass an allocator keeps its historical behaviour, and that + /// the new behaviours are opt-in, chosen by passing an allocator. + /// + public class DefaultAllocationBehaviorTests + { + [Fact] + public void BuilderWithoutAllocatorGrowsInManagedMemory() + { + ArrowBuffer.Builder builder = new ArrowBuffer.Builder(); + for (int i = 0; i < 1000; i++) + { + builder.Append(i); + } + + Assert.True(MemoryMarshal.TryGetArray(builder.Memory, out _), "Working memory should be a managed array."); + } + + [Fact] + public void BuilderWithoutAllocatorCopiesExactlyIntoTheDefaultAllocator() + { + ArrowBuffer.Builder builder = new ArrowBuffer.Builder(); + for (int i = 0; i < 1000; i++) + { + builder.Append(i); + } + + ArrowBuffer buffer = builder.Build(); + + // One native allocation of exactly the padded length: no slack is kept. + Assert.True(MemoryMarshal.TryGetMemoryManager(buffer.Memory, out NativeMemoryManager manager)); + Assert.Equal(4032, buffer.Length); + Assert.Equal(4032, manager.Memory.Length); + + // The builder keeps its own memory, as it always has. + builder.Span[0] = -1; + Assert.Equal(0, buffer.Span.CastTo()[0]); + } + + [Fact] + public void BuilderWithoutAllocatorKeepsExactCapacity() + { + Assert.Equal(1, new ArrowBuffer.Builder(1).Capacity); + Assert.Equal(8, new ArrowBuffer.Builder().Capacity); + } + + [Fact] + public void BitmapBuilderWithoutAllocatorKeepsItsHistoricalBufferLength() + { + // Historically the built bitmap covered all of the working memory. + ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(1024); + builder.Append(true); + + Assert.Equal(128, builder.Build().Length); + } + + [Fact] + public void ArrayBuilderWithoutAllocatorBuildsIntoTheDefaultAllocator() + { + Int32Array array = new Int32Array.Builder().Append(1).AppendNull().Append(3).Build(); + + Assert.True(MemoryMarshal.TryGetMemoryManager(array.ValueBuffer.Memory, out NativeMemoryManager _)); + Assert.True(MemoryMarshal.TryGetMemoryManager(array.NullBitmapBuffer.Memory, out NativeMemoryManager _)); + } + + [Fact] + public void UndisposedBuffersFromFinalizedAllocatorsAreReleasedByCollection() + { + // The historical behaviour, kept for any allocator whose Lifetime is Finalized, + // including custom allocators that rely on it. + CountingAllocator allocator = new CountingAllocator(AllocationLifetime.Finalized); + BuildAndAbandon(allocator); + + Collect(); + + Assert.Equal(0, allocator.LiveAllocations); + } + + [Theory] + [InlineData(AllocationLifetime.CallerOwned)] + [InlineData(AllocationLifetime.GarbageCollected)] + public void OtherLifetimesOptOutOfReleaseByCollection(AllocationLifetime lifetime) + { + // Release by collection is what lets a span outlive its memory (issue #397), so + // allocators with other lifetimes opt out of it. + CountingAllocator allocator = new CountingAllocator(lifetime); + BuildAndAbandon(allocator); + + Collect(); + + Assert.Equal(1, allocator.LiveAllocations); + } + + [Theory] + [InlineData(MemoryAllocator.DefaultAlignment)] + [InlineData(128)] + [InlineData(256)] + public void NativeAllocatorRemovesTheMemoryPressureItAdds(int alignment) + { + // https://github.com/apache/arrow-dotnet/issues/50 + NativeMemoryAllocator allocator = new NativeMemoryAllocator(alignment); + allocator.Allocate(10).Dispose(); + + Assert.Equal(10 + alignment, allocator.Statistics.BytesAllocated); + Assert.Equal(10 + alignment, allocator.ReleasedPressureBytes(10)); + } + + /// + /// Builds a buffer that is never disposed and that nothing references afterwards. The + /// builder is disposed, so only the buffer's own handle holds the allocation. + /// + [MethodImpl(MethodImplOptions.NoInlining)] + private static void BuildAndAbandon(MemoryAllocator allocator) + { + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + builder.Append(1).Build(); + } + + private static void Collect() + { + GC.Collect(); + GC.WaitForPendingFinalizers(); + GC.Collect(); + } + + /// + /// An allocator over managed arrays that reports a chosen lifetime and counts allocations + /// not yet released. Its owners have no finalizer, so only the buffer handle can release + /// an allocation that is never disposed. + /// + private sealed class CountingAllocator : MemoryAllocator + { + private int _live; + + public CountingAllocator(AllocationLifetime lifetime) => Lifetime = lifetime; + + public override AllocationLifetime Lifetime { get; } + + public int LiveAllocations => Volatile.Read(ref _live); + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + Interlocked.Increment(ref _live); + bytesAllocated = length; + return new Owner(this, new byte[length]); + } + + private sealed class Owner : IMemoryOwner + { + private readonly CountingAllocator _allocator; + private byte[] _buffer; + + public Owner(CountingAllocator allocator, byte[] buffer) + { + _allocator = allocator; + _buffer = buffer; + } + + public Memory Memory => _buffer ?? throw new ObjectDisposedException(nameof(Owner)); + + public void Dispose() + { + if (Interlocked.Exchange(ref _buffer, null) != null) + { + Interlocked.Decrement(ref _allocator._live); + } + } + } + } + } +} From 57ffbfbb91b1128788ffab56a04600515142e2dc Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 04/15] Accept ArrowContext in IPC writers and keep record batches alive while writing - ArrowStreamWriter and ArrowFileWriter get constructors taking an ArrowContext. A compression codec factory in IpcOptions still takes precedence; the context's is a fallback. - The in-memory stream reader now uses the context's allocator, and delta dictionaries keep the historical behaviour when no allocator was given. - Buffers the writer and decompressor allocate carry their allocator's lifetime. - Fixes a use-after-free reported on #397: the writer now keeps the record batch alive until its buffers have been written, so a collection during the write cannot free them. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ArrowContext.cs | 15 + src/Apache.Arrow/Ipc/ArrowFileWriter.cs | 30 +- .../Ipc/ArrowMemoryReaderImplementation.cs | 7 +- .../Ipc/ArrowReaderImplementation.cs | 7 +- src/Apache.Arrow/Ipc/ArrowStreamReader.cs | 2 +- src/Apache.Arrow/Ipc/ArrowStreamWriter.cs | 60 ++- .../Ipc/DecompressingBufferCreator.cs | 2 +- .../BuilderDisposalTests.cs | 497 ++++++++++++++++++ 8 files changed, 607 insertions(+), 13 deletions(-) create mode 100644 test/Apache.Arrow.Tests/BuilderDisposalTests.cs diff --git a/src/Apache.Arrow/ArrowContext.cs b/src/Apache.Arrow/ArrowContext.cs index 88358959..9ad1a100 100644 --- a/src/Apache.Arrow/ArrowContext.cs +++ b/src/Apache.Arrow/ArrowContext.cs @@ -24,8 +24,23 @@ namespace Apache.Arrow /// public class ArrowContext { + /// + /// The allocator for memory allocated by operations given this context. null means + /// . + /// public MemoryAllocator Allocator { get; } + + /// + /// The compression codec factory used to decompress when reading, and to compress when + /// writing if the passed to the writer do not specify one. + /// public ICompressionCodecFactory CompressionCodecFactory { get; } + + /// + /// The extension type registry. When none is passed to the constructor, this is a snapshot + /// of as it was when the context was created; + /// taking the snapshot is cheap, as the registries share storage until either changes. + /// public ExtensionTypeRegistry ExtensionRegistry { get; } public ArrowContext( diff --git a/src/Apache.Arrow/Ipc/ArrowFileWriter.cs b/src/Apache.Arrow/Ipc/ArrowFileWriter.cs index cfdf2269..38958c38 100644 --- a/src/Apache.Arrow/Ipc/ArrowFileWriter.cs +++ b/src/Apache.Arrow/Ipc/ArrowFileWriter.cs @@ -49,7 +49,35 @@ public ArrowFileWriter(Stream stream, Schema schema, bool leaveOpen, IpcOptions } public ArrowFileWriter(Stream stream, Schema schema, bool leaveOpen, IpcOptions options, MemoryAllocator allocator) - : base(stream, schema, leaveOpen, options, allocator) + : this(stream, schema, leaveOpen, options, allocator, fallbackCompressionCodecFactory: null) + { + } + + /// + /// Creates a writer that takes its allocator and compression codec factory from + /// . + /// + /// + /// Supplies the allocator for the writer's temporary buffers, and the compression codec + /// factory used when does not specify one. + /// + /// The stream to write to; must be writable. + /// The schema of the record batches to be written. + /// Whether to leave open when the writer is disposed. + /// IPC options; null uses . + public ArrowFileWriter(ArrowContext context, Stream stream, Schema schema, bool leaveOpen = false, IpcOptions options = null) + : this(stream, schema, leaveOpen, options, RequireContext(context).Allocator, context.CompressionCodecFactory) + { + } + + private ArrowFileWriter( + Stream stream, + Schema schema, + bool leaveOpen, + IpcOptions options, + MemoryAllocator allocator, + ICompressionCodecFactory fallbackCompressionCodecFactory) + : base(stream, schema, leaveOpen, options, allocator, fallbackCompressionCodecFactory) { if (!stream.CanWrite) { diff --git a/src/Apache.Arrow/Ipc/ArrowMemoryReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowMemoryReaderImplementation.cs index cdf17fa9..da8084e8 100644 --- a/src/Apache.Arrow/Ipc/ArrowMemoryReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowMemoryReaderImplementation.cs @@ -19,6 +19,7 @@ using System.Threading; using System.Threading.Tasks; using Apache.Arrow.Flatbuf; +using Apache.Arrow.Memory; using Google.FlatBuffers; namespace Apache.Arrow.Ipc @@ -29,12 +30,12 @@ internal sealed class ArrowMemoryReaderImplementation : ArrowReaderImplementatio private int _bufferPosition; public ArrowMemoryReaderImplementation(ReadOnlyMemory buffer, ICompressionCodecFactory compressionCodecFactory) - : this(buffer, compressionCodecFactory, null) + : this(buffer, allocator: null, compressionCodecFactory, null) { } - public ArrowMemoryReaderImplementation(ReadOnlyMemory buffer, ICompressionCodecFactory compressionCodecFactory, ExtensionTypeRegistry extensionRegistry) - : base(null, compressionCodecFactory, extensionRegistry) + public ArrowMemoryReaderImplementation(ReadOnlyMemory buffer, MemoryAllocator allocator, ICompressionCodecFactory compressionCodecFactory, ExtensionTypeRegistry extensionRegistry) + : base(allocator, compressionCodecFactory, extensionRegistry) { _buffer = buffer; } diff --git a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs index 45fd7920..10fbc8e3 100644 --- a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs @@ -47,6 +47,10 @@ public Schema Schema private protected DictionaryMemo _dictionaryMemo; private protected DictionaryMemo DictionaryMemo => _dictionaryMemo ??= new DictionaryMemo(); private protected readonly MemoryAllocator _allocator; + + // The allocator exactly as given, possibly null, for operations that build arrays: + // those keep their historical behaviour when no allocator was passed. + private readonly MemoryAllocator _requestedAllocator; private readonly ICompressionCodecFactory _compressionCodecFactory; private protected readonly ExtensionTypeRegistry _extensionRegistry; private protected Schema _schema; @@ -60,6 +64,7 @@ private protected ArrowReaderImplementation(MemoryAllocator allocator, ICompress private protected ArrowReaderImplementation(MemoryAllocator allocator, ICompressionCodecFactory compressionCodecFactory, ExtensionTypeRegistry extensionRegistry) { + _requestedAllocator = allocator; _allocator = allocator ?? MemoryAllocator.Default.Value; _compressionCodecFactory = compressionCodecFactory; _extensionRegistry = extensionRegistry ?? ExtensionTypeRegistry.Default; @@ -209,7 +214,7 @@ private void ReadDictionaryBatch( if (dictionaryBatch.IsDelta) { - DictionaryMemo.AddDeltaDictionary(id, arrays[0], _allocator); + DictionaryMemo.AddDeltaDictionary(id, arrays[0], _requestedAllocator); } else { diff --git a/src/Apache.Arrow/Ipc/ArrowStreamReader.cs b/src/Apache.Arrow/Ipc/ArrowStreamReader.cs index bdc1fb7f..78182cbb 100644 --- a/src/Apache.Arrow/Ipc/ArrowStreamReader.cs +++ b/src/Apache.Arrow/Ipc/ArrowStreamReader.cs @@ -97,7 +97,7 @@ public ArrowStreamReader(ArrowContext context, ReadOnlyMemory buffer) if (context == null) throw new ArgumentNullException(nameof(context)); - _implementation = new ArrowMemoryReaderImplementation(buffer, context.CompressionCodecFactory, context.ExtensionRegistry); + _implementation = new ArrowMemoryReaderImplementation(buffer, context.Allocator, context.CompressionCodecFactory, context.ExtensionRegistry); } private protected ArrowStreamReader(ArrowReaderImplementation implementation) diff --git a/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs b/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs index aa63985e..f5418ab5 100644 --- a/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs +++ b/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs @@ -425,7 +425,7 @@ private ArrowBuffer GetZeroBasedValueOffsets(ArrowBuffer valueOffsetsBuffer, int newValueOffsets[i] = originalOffsets[i] - firstOffset; } - return new ArrowBuffer(newValueOffsetsBuffer); + return new ArrowBuffer(newValueOffsetsBuffer, _allocator.Lifetime); } else if (valueOffsetsBuffer.Length > requiredBytes) { @@ -457,7 +457,7 @@ private ArrowBuffer GetZeroBasedLongValueOffsets(ArrowBuffer valueOffsetsBuffer, { newValueOffsets[i] = originalOffsets[i] - firstOffset; } - return new ArrowBuffer(newValueOffsetsBuffer); + return new ArrowBuffer(newValueOffsetsBuffer, _allocator.Lifetime); } else if (valueOffsetsBuffer.Length > requiredBytes) { @@ -526,7 +526,7 @@ private ArrowBuffer GetZeroBasedLongValueOffsets(ArrowBuffer valueOffsetsBuffer, newOffsets[i] = offsets[i] - minOffset; } - return (new ArrowBuffer(newOffsetsBuffer), minOffset, maxEnd); + return (new ArrowBuffer(newOffsetsBuffer, _allocator.Lifetime), minOffset, maxEnd); } private (ArrowBuffer Buffer, long minOffset, long maxEnd) GetZeroBasedLargeListViewOffsets(LargeListViewArray array) @@ -577,7 +577,7 @@ private ArrowBuffer GetZeroBasedLongValueOffsets(ArrowBuffer valueOffsetsBuffer, newOffsets[i] = offsets[i] - minOffset; } - return (new ArrowBuffer(newOffsetsBuffer), minOffset, maxEnd); + return (new ArrowBuffer(newOffsetsBuffer, _allocator.Lifetime), minOffset, maxEnd); } private Buffer CreateBitmapBuffer(ArrowBuffer buffer, int offset, int length, bool locallyOwned) @@ -739,6 +739,7 @@ public void Visit(IArrowArray array) private readonly bool _leaveOpen; private readonly IpcOptions _options; private readonly MemoryAllocator _allocator; + private readonly ICompressionCodecFactory _compressionCodecFactory; // Fallback for compression codec, not implementing TryCompress. // Reuse a single memory stream for writing compressed private readonly MemoryStream _fallbackCompressionStream = new MemoryStream(); @@ -768,6 +769,34 @@ public ArrowStreamWriter(Stream baseStream, Schema schema, bool leaveOpen, IpcOp } public ArrowStreamWriter(Stream baseStream, Schema schema, bool leaveOpen, IpcOptions options, MemoryAllocator allocator) + : this(baseStream, schema, leaveOpen, options, allocator, fallbackCompressionCodecFactory: null) + { + } + + /// + /// Creates a writer that takes its allocator and compression codec factory from + /// . + /// + /// + /// Supplies the allocator for the writer's temporary buffers, and the compression codec + /// factory used when does not specify one. + /// + /// The stream to write to. + /// The schema of the record batches to be written. + /// Whether to leave open when the writer is disposed. + /// IPC options; null uses . + public ArrowStreamWriter(ArrowContext context, Stream baseStream, Schema schema, bool leaveOpen = false, IpcOptions options = null) + : this(baseStream, schema, leaveOpen, options, RequireContext(context).Allocator, context.CompressionCodecFactory) + { + } + + private protected ArrowStreamWriter( + Stream baseStream, + Schema schema, + bool leaveOpen, + IpcOptions options, + MemoryAllocator allocator, + ICompressionCodecFactory fallbackCompressionCodecFactory) { BaseStream = baseStream ?? throw new ArgumentNullException(nameof(baseStream)); Schema = schema ?? throw new ArgumentNullException(nameof(schema)); @@ -780,7 +809,11 @@ public ArrowStreamWriter(Stream baseStream, Schema schema, bool leaveOpen, IpcOp _fieldTypeBuilder = new ArrowTypeFlatbufferBuilder(Builder); _options = options ?? IpcOptions.Default; - if (_options.CompressionCodec.HasValue && _options.CompressionCodecFactory == null) + // A factory in the options wins; the context's is only a fallback, so that callers + // never need to modify (possibly shared) IpcOptions to use a context. + _compressionCodecFactory = _options.CompressionCodecFactory ?? fallbackCompressionCodecFactory; + + if (_options.CompressionCodec.HasValue && _compressionCodecFactory == null) { throw new ArgumentException( $"A {nameof(_options.CompressionCodecFactory)} must be provided when a {nameof(_options.CompressionCodec)} is specified", @@ -788,6 +821,9 @@ public ArrowStreamWriter(Stream baseStream, Schema schema, bool leaveOpen, IpcOp } } + private protected static ArrowContext RequireContext(ArrowContext context) => + context ?? throw new ArgumentNullException(nameof(context)); + private Offset GetBodyCompression() { if (_options.CompressionCodec == null) @@ -854,6 +890,12 @@ private protected void WriteRecordBatchInternal(RecordBatch recordBatch, IReadOn long bufferLength = WriteBufferData(recordBatchBuilder.Buffers); + // The buffers just written are views of recordBatch's memory, so it must stay + // reachable until they have been copied out. Otherwise, once its last other use above + // has passed, a collection during the write can finalize the batch's buffers and free + // that memory while it is being read (https://github.com/apache/arrow-dotnet/issues/397). + GC.KeepAlive(recordBatch); + FinishedWritingRecordBatch(bufferLength, metadataLength); } @@ -907,6 +949,12 @@ private protected async Task WriteRecordBatchInternalAsync(RecordBatch recordBat long bufferLength = await WriteBufferDataAsync(recordBatchBuilder.Buffers, cancellationToken).ConfigureAwait(false); + // The buffers just written are views of recordBatch's memory, so it must stay + // reachable until they have been copied out. Otherwise, once its last other use above + // has passed, a collection during the write can finalize the batch's buffers and free + // that memory while it is being read (https://github.com/apache/arrow-dotnet/issues/397). + GC.KeepAlive(recordBatch); + FinishedWritingRecordBatch(bufferLength, metadataLength); } @@ -983,7 +1031,7 @@ private Tuple Pre // CompressionCodec can be disposed after all data is visited by the builder, // and doesn't need to be alive for the full lifetime of the ArrowRecordBatchFlatBufferBuilder using var compressionCodec = _options.CompressionCodec.HasValue - ? _options.CompressionCodecFactory.CreateCodec(_options.CompressionCodec.Value, _options.CompressionLevel) + ? _compressionCodecFactory.CreateCodec(_options.CompressionCodec.Value, _options.CompressionLevel) : null; var recordBatchBuilder = new ArrowRecordBatchFlatBufferBuilder(compressionCodec, _allocator, _fallbackCompressionStream); diff --git a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs index dd8654ad..eff39e5a 100644 --- a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs +++ b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs @@ -58,7 +58,7 @@ public ArrowBuffer CreateBuffer(ReadOnlyMemory source) throw new Exception($"Expected to decompress {uncompressedLength} bytes, but got {decompressedLength} bytes"); } - return new ArrowBuffer(outputData); + return new ArrowBuffer(outputData, _allocator.Lifetime); } public void Dispose() diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs new file mode 100644 index 00000000..63507cab --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -0,0 +1,497 @@ +// 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.Buffers; +using System.Collections.Generic; +using System.IO; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; +using System.Threading; +using Apache.Arrow.Ipc; +using Apache.Arrow.Memory; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Tests that an explicitly passed allocator controls allocation exactly: every buffer of the + /// result comes from it, and disposing the builders, arrays, readers and writers involved + /// releases everything it handed out. This is what makes caller-owned allocators usable. + /// + public class BuilderDisposalTests + { + [Fact] + public void PrimitiveBuilderAndArrayReleaseEverything() + { + Run(allocator => + { + Int32Array array; + using (Int32Array.Builder builder = new Int32Array.Builder(0, allocator)) + { + array = builder.Append(1).AppendNull().Append(3).Build(); + } + + allocator.AssertOwns(array); + Assert.Equal(3, array.GetValue(2)); + array.Dispose(); + }); + } + + [Fact] + public void BuilderCanBeDisposedBeforeOrAfterArray() + { + Run(allocator => + { + Int64Array.Builder builder = new Int64Array.Builder(8, allocator).Append(1).Append(2); + Int64Array array = builder.Build(); + + array.Dispose(); + Assert.True(allocator.LiveAllocations > 0, "The builder still holds the shared memory."); + builder.Dispose(); + }); + } + + [Fact] + public void WrappedBuilderReleasesInnerBuilder() + { + Run(allocator => + { + using TimestampArray.Builder builder = new TimestampArray.Builder(TimestampType.Default, 4, allocator); + using TimestampArray array = builder.Append(DateTimeOffset.FromUnixTimeMilliseconds(0)).Build(); + allocator.AssertOwns(array); + }); + } + + [Fact] + public void StringBuilderUsesItsAllocator() + { + Run(allocator => + { + using StringArray.Builder builder = new StringArray.Builder(allocator); + using StringArray array = builder.Append("a").AppendNull().Append("bcd").Build(); + allocator.AssertOwns(array); + Assert.Equal("bcd", array.GetString(2)); + }); + } + + [Fact] + public void BooleanBuilderUsesItsAllocator() + { + Run(allocator => + { + using BooleanArray.Builder builder = new BooleanArray.Builder(allocator); + using BooleanArray array = builder.Append(true).AppendNull().Build(); + allocator.AssertOwns(array); + }); + } + + [Fact] + public void DecimalBuilderUsesItsAllocator() + { + Run(allocator => + { + using Decimal128Array.Builder builder = new Decimal128Array.Builder(new Decimal128Type(10, 2), allocator); + using Decimal128Array array = builder.Append(1.25m).AppendNull().Build(); + allocator.AssertOwns(array); + }); + } + + [Fact] + public void ListBuilderPassesItsAllocatorToItsChild() + { + Run(allocator => + { + using ListArray.Builder builder = new ListArray.Builder(Int32Type.Default, allocator); + Int32Array.Builder values = (Int32Array.Builder)builder.ValueBuilder; + builder.Append(); + values.Append(1).Append(2); + builder.AppendNull(); + + using ListArray array = builder.Build(); + allocator.AssertOwns(array); + Assert.Equal(2, array.GetValueLength(0)); + }); + } + + [Fact] + public void MapBuilderPassesItsAllocatorToItsChildren() + { + Run(allocator => + { + using MapArray.Builder builder = new MapArray.Builder(new MapType(StringType.Default, Int32Type.Default), allocator); + builder.Append(); + ((StringArray.Builder)builder.KeyBuilder).Append("k"); + ((Int32Array.Builder)builder.ValueBuilder).Append(1); + + using MapArray array = builder.Build(); + allocator.AssertOwns(array); + }); + } + + [Fact] + public void ListOfTimestampsKeepsTheElementType() + { + // The builder factory used to ignore a timestamp element type's unit and time zone. + TimestampType elementType = new TimestampType(TimeUnit.Microsecond, "UTC"); + using ListArray.Builder builder = new ListArray.Builder(elementType); + builder.Append(); + ((TimestampArray.Builder)builder.ValueBuilder).Append(DateTimeOffset.FromUnixTimeMilliseconds(1)); + + using ListArray array = builder.Build(); + + TimestampType actual = Assert.IsType(array.Values.Data.DataType); + Assert.Equal(TimeUnit.Microsecond, actual.Unit); + Assert.Equal("UTC", actual.Timezone); + } + + [Fact] + public void RecordBatchColumnHelpersUseTheBatchAllocator() + { + Run(allocator => + { + using RecordBatch batch = new RecordBatch.Builder(allocator) + .Append("ints", false, col => col.Int32(b => b.Append(1).Append(2))) + .Append("strings", true, col => col.String(b => b.Append("x").AppendNull())) + .Append("times", true, col => col.Timestamp(b => b.Append(DateTimeOffset.FromUnixTimeMilliseconds(5)))) + .Build(); + + allocator.AssertOwns(batch); + Assert.Equal(2, batch.Length); + }); + } + + [Fact] + public void ConcatenationUsesItsAllocator() + { + Run(allocator => + { + using Int32Array.Builder firstBuilder = new Int32Array.Builder(0, allocator); + using Int32Array.Builder secondBuilder = new Int32Array.Builder(0, allocator); + using Int32Array first = firstBuilder.Append(1).AppendNull().Build(); + using Int32Array second = secondBuilder.Append(3).Build(); + + using IArrowArray result = ArrowArrayConcatenator.Concatenate(new IArrowArray[] { first, second }, allocator); + allocator.AssertOwns(result); + Assert.Equal(3, result.Length); + }); + } + + [Fact] + public void CloneUsesItsAllocator() + { + Run(allocator => + { + using ArrowBuffer source = new ArrowBuffer(new byte[] { 1, 2, 3 }); + using ArrowBuffer clone = source.Clone(allocator); + allocator.AssertOwns(clone); + Assert.Equal(3, clone.Span[2]); + }); + } + + [Fact] + public void RecordBatchCloneUsesItsAllocator() + { + using RecordBatch original = new RecordBatch.Builder() + .Append("ints", false, col => col.Int32(b => b.Append(1).AppendNull())) + .Append("strings", true, col => col.String(b => b.Append("x"))) + .Build(); + + Run(allocator => + { + using RecordBatch clone = original.Clone(allocator); + allocator.AssertOwns(clone); + }); + } + + [Theory] + [InlineData(false, false)] + [InlineData(false, true)] + [InlineData(true, false)] + [InlineData(true, true)] + public void IpcContextsControlReadAndWriteAllocations(bool fileFormat, bool compress) + { + using RecordBatch original = new RecordBatch.Builder() + .Append("ints", false, col => col.Int32(b => b.Append(1).Append(2).Append(3))) + .Append("strings", true, col => col.String(b => b.Append("x").AppendNull().Append("yz"))) + .Build(); + + IpcOptions options = compress ? new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame } : null; + MemoryStream stream = new MemoryStream(); + + // The codec factory comes from the context, not the options: the writer falls back to it. + Run(writeAllocator => + { + ArrowContext context = new ArrowContext(writeAllocator, new PassThroughCodecFactory()); + using ArrowStreamWriter writer = fileFormat + ? new ArrowFileWriter(context, stream, original.Schema, leaveOpen: true, options) + : new ArrowStreamWriter(context, stream, original.Schema, leaveOpen: true, options); + writer.WriteRecordBatch(original); + writer.WriteEnd(); + }, expectAllocations: compress); + + Run(readAllocator => + { + ArrowContext context = new ArrowContext(readAllocator, new PassThroughCodecFactory()); + + // Wrapping the MemoryStream stops the reader from slicing its buffer directly, + // so that message bodies are read into memory from the context's allocator. + stream.Position = 0; + using Stream wrapped = new BufferedStream(stream); + using ArrowStreamReader reader = fileFormat + ? new ArrowFileReader(context, wrapped, leaveOpen: true) + : new ArrowStreamReader(context, wrapped, leaveOpen: true); + using RecordBatch batch = reader.ReadNextRecordBatch(); + + readAllocator.AssertOwns(batch); + Assert.Equal(3, batch.Length); + Assert.Equal("yz", ((StringArray)batch.Column(1)).GetString(2)); + }); + } + + [Fact] + public void InMemoryReaderUsesContextAllocatorForDecompression() + { + using RecordBatch original = new RecordBatch.Builder() + .Append("ints", false, col => col.Int32(b => b.Append(1).Append(2))) + .Build(); + + MemoryStream stream = new MemoryStream(); + IpcOptions options = new IpcOptions + { + CompressionCodec = CompressionCodecType.Lz4Frame, + CompressionCodecFactory = new PassThroughCodecFactory(), + }; + using (ArrowStreamWriter writer = new ArrowStreamWriter(stream, original.Schema, leaveOpen: true, options)) + { + writer.WriteRecordBatch(original); + writer.WriteEnd(); + } + + Run(allocator => + { + ArrowContext context = new ArrowContext(allocator, new PassThroughCodecFactory()); + using ArrowStreamReader reader = new ArrowStreamReader(context, new ReadOnlyMemory(stream.ToArray())); + using RecordBatch batch = reader.ReadNextRecordBatch(); + + allocator.AssertOwns(batch); + Assert.Equal(2, ((Int32Array)batch.Column(0)).GetValue(1)); + }); + } + + [Fact] + public void CodecFactoryInOptionsTakesPrecedenceOverContext() + { + PassThroughCodecFactory fromOptions = new PassThroughCodecFactory(); + PassThroughCodecFactory fromContext = new PassThroughCodecFactory(); + using RecordBatch batch = new RecordBatch.Builder() + .Append("ints", false, col => col.Int32(b => b.Append(1))) + .Build(); + + IpcOptions options = new IpcOptions + { + CompressionCodec = CompressionCodecType.Lz4Frame, + CompressionCodecFactory = fromOptions, + }; + using (ArrowStreamWriter writer = new ArrowStreamWriter( + new ArrowContext(compressionCodecFactory: fromContext), new MemoryStream(), batch.Schema, options: options)) + { + writer.WriteRecordBatch(batch); + } + + Assert.True(fromOptions.CodecsCreated > 0); + Assert.Equal(0, fromContext.CodecsCreated); + } + + [Fact] + public void WriterWithoutAnyCodecFactoryStillRejectsCompression() + { + Schema schema = new Schema.Builder().Field(f => f.Name("x").DataType(Int32Type.Default)).Build(); + IpcOptions options = new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame }; + + Assert.Throws(() => new ArrowStreamWriter(new ArrowContext(), new MemoryStream(), schema, options: options)); + } + + [Fact] + public void WriterContextConstructorsRejectNullContext() + { + Schema schema = new Schema.Builder().Field(f => f.Name("x").DataType(Int32Type.Default)).Build(); + + Assert.Throws(() => new ArrowStreamWriter((ArrowContext)null, new MemoryStream(), schema)); + Assert.Throws(() => new ArrowFileWriter((ArrowContext)null, new MemoryStream(), schema)); + } + + /// + /// Runs with a fresh caller-owned allocator, then asserts that it + /// was used and that every allocation it handed out has been released. + /// + private static void Run(Action test, bool expectAllocations = true) + { + TrackingAllocator allocator = new TrackingAllocator(); + test(allocator); + + if (expectAllocations) + { + Assert.True(allocator.Statistics.Allocations > 0, "The test should have allocated."); + } + Assert.Equal(0, allocator.LiveAllocations); + } + + /// + /// A caller-owned allocator that records the arrays it hands out and counts those not yet + /// released. Its memory is managed, so a leak fails the test rather than the process. + /// + private sealed class TrackingAllocator : MemoryAllocator + { + private readonly HashSet _handedOut = new HashSet(ReferenceComparer.Instance); + private int _live; + + public int LiveAllocations => Volatile.Read(ref _live); + + public override AllocationLifetime Lifetime => AllocationLifetime.CallerOwned; + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + byte[] buffer = new byte[length]; + lock (_handedOut) + { + _handedOut.Add(buffer); + } + Interlocked.Increment(ref _live); + bytesAllocated = length; + return new Owner(this, buffer); + } + + public void AssertOwns(RecordBatch batch) + { + for (int i = 0; i < batch.ColumnCount; i++) + { + AssertOwns(batch.Column(i)); + } + } + + public void AssertOwns(IArrowArray array) => AssertOwns(array.Data); + + public void AssertOwns(ArrayData data) + { + foreach (ArrowBuffer buffer in data.Buffers) + { + AssertOwns(buffer); + } + foreach (ArrayData child in data.Children ?? System.Array.Empty()) + { + AssertOwns(child); + } + } + + public void AssertOwns(ArrowBuffer buffer) + { + if (buffer.IsEmpty) + { + return; + } + + Assert.True(MemoryMarshal.TryGetArray(buffer.Memory, out ArraySegment segment), + "Buffer memory is not from this allocator (it is not a managed array)."); + lock (_handedOut) + { + Assert.True(_handedOut.Contains(segment.Array), "Buffer memory is not from this allocator."); + } + } + + private sealed class Owner : IMemoryOwner + { + private readonly TrackingAllocator _allocator; + private byte[] _buffer; + + public Owner(TrackingAllocator allocator, byte[] buffer) + { + _allocator = allocator; + _buffer = buffer; + } + + public Memory Memory => + _buffer ?? throw new ObjectDisposedException(nameof(Owner)); + + public void Dispose() + { + if (Interlocked.Exchange(ref _buffer, null) != null) + { + Interlocked.Decrement(ref _allocator._live); + } + } + } + } + + private sealed class ReferenceComparer : IEqualityComparer + { + public static readonly ReferenceComparer Instance = new ReferenceComparer(); + + public bool Equals(byte[] x, byte[] y) => ReferenceEquals(x, y); + + public int GetHashCode(byte[] obj) => RuntimeHelpers.GetHashCode(obj); + } + + /// + /// A "compression" codec that copies its input unchanged, so that tests can exercise the + /// compressed IPC code paths without a dependency on a real codec. + /// + private sealed class PassThroughCodecFactory : ICompressionCodecFactory + { + private int _codecsCreated; + + public int CodecsCreated => Volatile.Read(ref _codecsCreated); + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) + { + Interlocked.Increment(ref _codecsCreated); + return new PassThroughCodec(); + } + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, int? compressionLevel) => + CreateCodec(compressionCodecType); + } + + private sealed class PassThroughCodec : ITryCompressionCodec + { + public int Decompress(ReadOnlyMemory source, Memory destination) + { + source.CopyTo(destination); + return source.Length; + } + + public void Compress(ReadOnlyMemory source, Stream destination) => + destination.Write(source.ToArray(), 0, source.Length); + + public bool TryCompress(ReadOnlyMemory source, Memory destination, out int bytesWritten) + { + if (source.Length > destination.Length) + { + bytesWritten = 0; + return false; + } + + source.CopyTo(destination); + bytesWritten = source.Length; + return true; + } + + public void Dispose() + { + } + } + } +} From cb472a4cad62bfcb0c28f35392a9e2630cf7daef Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 05/15] Pass ArrowContext through Flight clients, servers and streams - FlightServer and FlightSqlServer accept a context, which reaches every reader and writer the server creates, including when the server is created by dependency injection. - FlightClient gets a (CallInvoker, ArrowContext) constructor marked [ActivatorUtilitiesConstructor], so Grpc.Net.ClientFactory can still create clients and passes them any ArrowContext registered for dependency injection. This adds a dependency on Microsoft.Extensions.DependencyInjection.Abstractions. - Flight writers use the context's allocator. - Fixes schema decoding in Flight readers, FlightInfo and FlightClient.GetSchema always using the default extension type registry. Co-Authored-By: Claude Opus 5.5 --- Directory.Packages.props | 1 + .../FlightSqlServer.cs | 14 ++ .../Apache.Arrow.Flight.csproj | 2 + .../Client/FlightClient.cs | 45 +++- .../FlightClientRecordBatchStreamWriter.cs | 2 +- src/Apache.Arrow.Flight/FlightInfo.cs | 4 +- .../FlightRecordBatchStreamWriter.cs | 6 +- .../Internal/FlightDataStream.cs | 4 +- .../Internal/FlightMessageSerializer.cs | 8 +- .../RecordBatchReaderImplementation.cs | 2 +- .../Server/FlightServer.cs | 27 +++ .../FlightServerRecordBatchStreamReader.cs | 13 +- .../FlightServerRecordBatchStreamWriter.cs | 18 +- .../Internal/FlightServerImplementation.cs | 8 +- .../TestFlightServer.cs | 5 +- .../FlightContextTests.cs | 226 ++++++++++++++++++ .../TestWebFactory.cs | 10 +- 17 files changed, 360 insertions(+), 35 deletions(-) create mode 100644 test/Apache.Arrow.Flight.Tests/FlightContextTests.cs diff --git a/Directory.Packages.props b/Directory.Packages.props index 9bc98e93..1e02ec60 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -33,6 +33,7 @@ + diff --git a/src/Apache.Arrow.Flight.Sql/FlightSqlServer.cs b/src/Apache.Arrow.Flight.Sql/FlightSqlServer.cs index f2862996..a301c03e 100644 --- a/src/Apache.Arrow.Flight.Sql/FlightSqlServer.cs +++ b/src/Apache.Arrow.Flight.Sql/FlightSqlServer.cs @@ -211,6 +211,20 @@ public static Schema GetTableSchema(bool includeTableSchemaField) } protected FlightSqlServer(ILoggerFactory? factory = null) + : this(context: null, factory) + { + } + + /// + /// Creates a server whose record-batch readers and writers use . + /// + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// + /// Creates the logger for the server; null disables logging. + protected FlightSqlServer(ArrowContext? context, ILoggerFactory? factory) + : base(context) { Logger = factory?.CreateLogger(typeof(FlightSqlServer)); } diff --git a/src/Apache.Arrow.Flight/Apache.Arrow.Flight.csproj b/src/Apache.Arrow.Flight/Apache.Arrow.Flight.csproj index de5d495c..6c3cf694 100644 --- a/src/Apache.Arrow.Flight/Apache.Arrow.Flight.csproj +++ b/src/Apache.Arrow.Flight/Apache.Arrow.Flight.csproj @@ -9,6 +9,8 @@ + + diff --git a/src/Apache.Arrow.Flight/Client/FlightClient.cs b/src/Apache.Arrow.Flight/Client/FlightClient.cs index 67049c89..ef4bb3af 100644 --- a/src/Apache.Arrow.Flight/Client/FlightClient.cs +++ b/src/Apache.Arrow.Flight/Client/FlightClient.cs @@ -19,6 +19,7 @@ using Apache.Arrow.Flight.Protocol; using Apache.Arrow.Flight.Server.Internal; using Grpc.Core; +using Microsoft.Extensions.DependencyInjection; namespace Apache.Arrow.Flight.Client { @@ -30,10 +31,18 @@ public class FlightClient private readonly ArrowContext _context; public FlightClient(ChannelBase grpcChannel) - : this(grpcChannel, null) + : this(grpcChannel, context: null) { } + /// + /// Creates a client whose record-batch readers and writers use . + /// + /// The gRPC channel to the Flight server. + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// public FlightClient(ChannelBase grpcChannel, ArrowContext context) { _client = new FlightService.FlightServiceClient(grpcChannel); @@ -41,11 +50,26 @@ public FlightClient(ChannelBase grpcChannel, ArrowContext context) } public FlightClient(CallInvoker callInvoker) - : this(callInvoker, null) + : this(callInvoker, context: null) { } - private FlightClient(CallInvoker callInvoker, ArrowContext context) + /// + /// Creates a client whose record-batch readers and writers use . + /// + /// + /// Grpc.Net.ClientFactory creates clients through ActivatorUtilities, passing a + /// . With two constructors accepting one it could not choose, so + /// this one is marked as the constructor to use. A client created that way gets the + /// registered for dependency injection, if there is one. + /// + /// The gRPC call invoker for the Flight server. + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// + [ActivatorUtilitiesConstructor] + public FlightClient(CallInvoker callInvoker, ArrowContext context = null) { _client = new FlightService.FlightServiceClient(callInvoker); _context = context; @@ -55,8 +79,7 @@ private FlightClient(CallInvoker callInvoker, ArrowContext context) /// Creates a from a with an . /// /// - /// A factory method is used instead of a constructor overload so that dependency injection - /// (e.g. Grpc.Net.ClientFactory) can still resolve the single-argument constructor unambiguously. + /// Equivalent to . /// /// The to use for gRPC calls /// The carrying the compression codec factory and other reader configuration @@ -78,7 +101,7 @@ public AsyncServerStreamingCall ListFlights(FlightCriteria criteria, } var response = _client.ListFlights(criteria.ToProtocol(), headers, deadline, cancellationToken); - var convertStream = new StreamReader(response.ResponseStream, inFlight => new FlightInfo(inFlight)); + var convertStream = new StreamReader(response.ResponseStream, inFlight => new FlightInfo(inFlight, _context?.ExtensionRegistry)); return new AsyncServerStreamingCall(convertStream, response.ResponseHeadersAsync, response.GetStatus, response.GetTrailers, response.Dispose); } @@ -119,7 +142,7 @@ public AsyncUnaryCall GetInfo(FlightDescriptor flightDescriptor, Met var flightInfo = flightInfoResult .ResponseAsync - .ContinueWith(async flightInfo => new FlightInfo(await flightInfo.ConfigureAwait(false))) + .ContinueWith(async flightInfo => new FlightInfo(await flightInfo.ConfigureAwait(false), _context?.ExtensionRegistry)) .Unwrap(); return new AsyncUnaryCall( @@ -166,7 +189,7 @@ public Task StartPut(FlightDescriptor flig public FlightRecordBatchDuplexStreamingCall StartPut(FlightDescriptor flightDescriptor, Metadata headers, System.DateTime? deadline, CancellationToken cancellationToken = default) { var channels = _client.DoPut(headers, deadline, cancellationToken); - var requestStream = new FlightClientRecordBatchStreamWriter(channels.RequestStream, flightDescriptor); + var requestStream = new FlightClientRecordBatchStreamWriter(channels.RequestStream, flightDescriptor, _context); var readStream = new StreamReader(channels.ResponseStream, putResult => new FlightPutResult(putResult)); return new FlightRecordBatchDuplexStreamingCall( requestStream, @@ -191,7 +214,7 @@ public FlightRecordBatchDuplexStreamingCall StartPut(FlightDescriptor flightDesc public async Task StartPut(FlightDescriptor flightDescriptor, Schema schema, Metadata headers, System.DateTime? deadline, CancellationToken cancellationToken = default) { var channels = _client.DoPut(headers, deadline, cancellationToken); - var requestStream = new FlightClientRecordBatchStreamWriter(channels.RequestStream, flightDescriptor); + var requestStream = new FlightClientRecordBatchStreamWriter(channels.RequestStream, flightDescriptor, _context); var readStream = new StreamReader(channels.ResponseStream, putResult => new FlightPutResult(putResult)); var streamingCall = new FlightRecordBatchDuplexStreamingCall( requestStream, @@ -233,7 +256,7 @@ public FlightRecordBatchExchangeCall DoExchange(FlightDescriptor flightDescripto public FlightRecordBatchExchangeCall DoExchange(FlightDescriptor flightDescriptor, Metadata headers, System.DateTime? deadline, CancellationToken cancellationToken = default) { var channel = _client.DoExchange(headers, deadline, cancellationToken); - var requestStream = new FlightClientRecordBatchStreamWriter(channel.RequestStream, flightDescriptor); + var requestStream = new FlightClientRecordBatchStreamWriter(channel.RequestStream, flightDescriptor, _context); var responseStream = new FlightClientRecordBatchStreamReader(channel.ResponseStream, _context); var call = new FlightRecordBatchExchangeCall( requestStream, @@ -269,7 +292,7 @@ public AsyncUnaryCall GetSchema(FlightDescriptor flightDescriptor, Metad var schema = schemaResult .ResponseAsync - .ContinueWith(async schema => FlightMessageSerializer.DecodeSchema((await schemaResult.ResponseAsync.ConfigureAwait(false)).Schema.Memory)) + .ContinueWith(async schema => FlightMessageSerializer.DecodeSchema((await schemaResult.ResponseAsync.ConfigureAwait(false)).Schema.Memory, _context?.ExtensionRegistry)) .Unwrap(); return new AsyncUnaryCall( diff --git a/src/Apache.Arrow.Flight/Client/FlightClientRecordBatchStreamWriter.cs b/src/Apache.Arrow.Flight/Client/FlightClientRecordBatchStreamWriter.cs index 88c5ee88..e74a0652 100644 --- a/src/Apache.Arrow.Flight/Client/FlightClientRecordBatchStreamWriter.cs +++ b/src/Apache.Arrow.Flight/Client/FlightClientRecordBatchStreamWriter.cs @@ -27,7 +27,7 @@ public class FlightClientRecordBatchStreamWriter : FlightRecordBatchStreamWriter { private readonly IClientStreamWriter _clientStreamWriter; private bool _completed = false; - internal FlightClientRecordBatchStreamWriter(IClientStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor) : base(clientStreamWriter, flightDescriptor) + internal FlightClientRecordBatchStreamWriter(IClientStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor, ArrowContext context) : base(clientStreamWriter, flightDescriptor, context) { _clientStreamWriter = clientStreamWriter; } diff --git a/src/Apache.Arrow.Flight/FlightInfo.cs b/src/Apache.Arrow.Flight/FlightInfo.cs index 17286ee9..db5b4b77 100644 --- a/src/Apache.Arrow.Flight/FlightInfo.cs +++ b/src/Apache.Arrow.Flight/FlightInfo.cs @@ -24,9 +24,9 @@ namespace Apache.Arrow.Flight { public class FlightInfo { - internal FlightInfo(Protocol.FlightInfo flightInfo) + internal FlightInfo(Protocol.FlightInfo flightInfo, ExtensionTypeRegistry extensionRegistry = null) { - Schema = flightInfo.Schema?.Length > 0 ? FlightMessageSerializer.DecodeSchema(flightInfo.Schema.Memory) : null; + Schema = flightInfo.Schema?.Length > 0 ? FlightMessageSerializer.DecodeSchema(flightInfo.Schema.Memory, extensionRegistry) : null; Descriptor = new FlightDescriptor(flightInfo.FlightDescriptor); var endpoints = new List(); diff --git a/src/Apache.Arrow.Flight/FlightRecordBatchStreamWriter.cs b/src/Apache.Arrow.Flight/FlightRecordBatchStreamWriter.cs index 711fa4aa..21af3898 100644 --- a/src/Apache.Arrow.Flight/FlightRecordBatchStreamWriter.cs +++ b/src/Apache.Arrow.Flight/FlightRecordBatchStreamWriter.cs @@ -29,11 +29,13 @@ public abstract class FlightRecordBatchStreamWriter : IAsyncStreamWriter _clientStreamWriter; private readonly FlightDescriptor _flightDescriptor; + private readonly ArrowContext _context; private bool _disposed; - private protected FlightRecordBatchStreamWriter(IAsyncStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor) + private protected FlightRecordBatchStreamWriter(IAsyncStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor, ArrowContext context) { + _context = context; _clientStreamWriter = clientStreamWriter; _flightDescriptor = flightDescriptor; } @@ -52,7 +54,7 @@ public async Task SetupStream(Schema schema) { throw new InvalidOperationException("Flight data stream is already set"); } - _flightDataStream = new FlightDataStream(_clientStreamWriter, _flightDescriptor, schema); + _flightDataStream = new FlightDataStream(_clientStreamWriter, _flightDescriptor, schema, _context); await _flightDataStream.SendSchema().ConfigureAwait(false); } diff --git a/src/Apache.Arrow.Flight/Internal/FlightDataStream.cs b/src/Apache.Arrow.Flight/Internal/FlightDataStream.cs index 46a7ac20..0e5b76eb 100644 --- a/src/Apache.Arrow.Flight/Internal/FlightDataStream.cs +++ b/src/Apache.Arrow.Flight/Internal/FlightDataStream.cs @@ -37,8 +37,8 @@ internal class FlightDataStream : ArrowStreamWriter private readonly IAsyncStreamWriter _clientStreamWriter; private Protocol.FlightData _currentFlightData; - public FlightDataStream(IAsyncStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor, Schema schema) - : base(new MemoryStream(), schema) + public FlightDataStream(IAsyncStreamWriter clientStreamWriter, FlightDescriptor flightDescriptor, Schema schema, ArrowContext context) + : base(new MemoryStream(), schema, leaveOpen: false, options: null, context?.Allocator, context?.CompressionCodecFactory) { _clientStreamWriter = clientStreamWriter; _flightDescriptor = flightDescriptor; diff --git a/src/Apache.Arrow.Flight/Internal/FlightMessageSerializer.cs b/src/Apache.Arrow.Flight/Internal/FlightMessageSerializer.cs index b0f53778..9cf3768f 100644 --- a/src/Apache.Arrow.Flight/Internal/FlightMessageSerializer.cs +++ b/src/Apache.Arrow.Flight/Internal/FlightMessageSerializer.cs @@ -25,7 +25,7 @@ namespace Apache.Arrow.Flight { internal static class FlightMessageSerializer { - public static Schema DecodeSchema(ReadOnlyMemory buffer) + public static Schema DecodeSchema(ReadOnlyMemory buffer, ExtensionTypeRegistry extensionRegistry = null) { if (buffer.IsEmpty) return null; int bufferPosition = 0; @@ -47,15 +47,15 @@ public static Schema DecodeSchema(ReadOnlyMemory buffer) ByteBuffer schemaBuffer = ArrowReaderImplementation.CreateByteBuffer(buffer.Slice(bufferPosition)); //DictionaryBatch not supported for now DictionaryMemo dictionaryMemo = null; - var schema = MessageSerializer.GetSchema(ArrowReaderImplementation.ReadMessage(schemaBuffer), ref dictionaryMemo); + var schema = MessageSerializer.GetSchema(ArrowReaderImplementation.ReadMessage(schemaBuffer), ref dictionaryMemo, extensionRegistry ?? ExtensionTypeRegistry.Default); return schema; } - internal static Schema DecodeSchema(ByteBuffer schemaBuffer) + internal static Schema DecodeSchema(ByteBuffer schemaBuffer, ExtensionTypeRegistry extensionRegistry = null) { //DictionaryBatch not supported for now DictionaryMemo dictionaryMemo = null; - var schema = MessageSerializer.GetSchema(ArrowReaderImplementation.ReadMessage(schemaBuffer), ref dictionaryMemo); + var schema = MessageSerializer.GetSchema(ArrowReaderImplementation.ReadMessage(schemaBuffer), ref dictionaryMemo, extensionRegistry ?? ExtensionTypeRegistry.Default); return schema; } } diff --git a/src/Apache.Arrow.Flight/Internal/RecordBatchReaderImplementation.cs b/src/Apache.Arrow.Flight/Internal/RecordBatchReaderImplementation.cs index bb4aba7e..14eb6c26 100644 --- a/src/Apache.Arrow.Flight/Internal/RecordBatchReaderImplementation.cs +++ b/src/Apache.Arrow.Flight/Internal/RecordBatchReaderImplementation.cs @@ -103,7 +103,7 @@ public override async ValueTask ReadSchemaAsync(CancellationToken cancel switch (message.HeaderType) { case MessageHeader.Schema: - _schema = FlightMessageSerializer.DecodeSchema(message.ByteBuffer); + _schema = FlightMessageSerializer.DecodeSchema(message.ByteBuffer, _extensionRegistry); break; default: throw new Exception($"Expected schema as the first message, but got: {message.HeaderType.ToString()}"); diff --git a/src/Apache.Arrow.Flight/Server/FlightServer.cs b/src/Apache.Arrow.Flight/Server/FlightServer.cs index b2e521ad..4b715943 100644 --- a/src/Apache.Arrow.Flight/Server/FlightServer.cs +++ b/src/Apache.Arrow.Flight/Server/FlightServer.cs @@ -21,6 +21,33 @@ namespace Apache.Arrow.Flight.Server { public abstract class FlightServer { + protected FlightServer() + : this(context: null) + { + } + + /// + /// Creates a server whose record-batch readers and writers use . + /// + /// + /// This applies however the server is hosted, including when it is created by dependency + /// injection: the derived server receives the context in its own constructor and passes it on. + /// + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// + protected FlightServer(ArrowContext context) + { + Context = context; + } + + /// + /// The context used for the record batches this server reads and writes, or null + /// for the defaults. + /// + public ArrowContext Context { get; } + public virtual Task DoPut(FlightServerRecordBatchStreamReader requestStream, IAsyncStreamWriter responseStream, ServerCallContext context) { throw new NotImplementedException(); diff --git a/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamReader.cs b/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamReader.cs index fb54058b..4e4d9550 100644 --- a/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamReader.cs +++ b/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamReader.cs @@ -22,11 +22,20 @@ namespace Apache.Arrow.Flight.Server public class FlightServerRecordBatchStreamReader : FlightRecordBatchStreamReader { public FlightServerRecordBatchStreamReader(IAsyncStreamReader flightDataStream) - : this(flightDataStream, null) + : this(flightDataStream, context: null) { } - public FlightServerRecordBatchStreamReader(IAsyncStreamReader flightDataStream, ArrowContext context) : base(new StreamReader(flightDataStream, data => data.ToProtocol()), context) + /// + /// Creates a reader that decodes record batches using . + /// + /// The stream of Flight data to read. + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// + public FlightServerRecordBatchStreamReader(IAsyncStreamReader flightDataStream, ArrowContext context) + : base(new StreamReader(flightDataStream, data => data.ToProtocol()), context) { } diff --git a/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamWriter.cs b/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamWriter.cs index b7533ef0..88e1872a 100644 --- a/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamWriter.cs +++ b/src/Apache.Arrow.Flight/Server/FlightServerRecordBatchStreamWriter.cs @@ -20,11 +20,25 @@ namespace Apache.Arrow.Flight.Server { public class FlightServerRecordBatchStreamWriter : FlightRecordBatchStreamWriter, IServerStreamWriter { - public FlightServerRecordBatchStreamWriter(IServerStreamWriter clientStreamWriter) : base(new StreamWriter(clientStreamWriter, data => new FlightData(data)), null) + public FlightServerRecordBatchStreamWriter(IServerStreamWriter clientStreamWriter) + : this(clientStreamWriter, context: null) { } - internal FlightServerRecordBatchStreamWriter(IServerStreamWriter clientStreamWriter) : base(clientStreamWriter, null) + /// + /// Creates a writer that encodes record batches using . + /// + /// The stream to write Flight data to. + /// + /// Supplies the allocator, compression codec factory and extension type registry; null + /// uses the defaults. + /// + public FlightServerRecordBatchStreamWriter(IServerStreamWriter clientStreamWriter, ArrowContext context) + : base(new StreamWriter(clientStreamWriter, data => new FlightData(data)), null, context) + { + } + + internal FlightServerRecordBatchStreamWriter(IServerStreamWriter clientStreamWriter, ArrowContext context) : base(clientStreamWriter, null, context) { } } diff --git a/src/Apache.Arrow.Flight/Server/Internal/FlightServerImplementation.cs b/src/Apache.Arrow.Flight/Server/Internal/FlightServerImplementation.cs index 8bf47f96..e2aeed54 100644 --- a/src/Apache.Arrow.Flight/Server/Internal/FlightServerImplementation.cs +++ b/src/Apache.Arrow.Flight/Server/Internal/FlightServerImplementation.cs @@ -34,7 +34,7 @@ public FlightServerImplementation(FlightServer flightServer) public override async Task DoPut(IAsyncStreamReader requestStream, IServerStreamWriter responseStream, ServerCallContext context) { - var readStream = new FlightServerRecordBatchStreamReader(requestStream); + var readStream = new FlightServerRecordBatchStreamReader(requestStream, _flightServer.Context); var writeStream = new StreamWriter(responseStream, putResult => putResult.ToProtocol()); await _flightServer.DoPut(readStream, writeStream, context).ConfigureAwait(false); @@ -43,7 +43,7 @@ public override async Task DoPut(IAsyncStreamReader request public override Task DoGet(Protocol.Ticket request, IServerStreamWriter responseStream, ServerCallContext context) { var flightTicket = new FlightTicket(request.Ticket_); - var flightServerRecordBatchStreamWriter = new FlightServerRecordBatchStreamWriter(responseStream); + var flightServerRecordBatchStreamWriter = new FlightServerRecordBatchStreamWriter(responseStream, _flightServer.Context); return _flightServer.DoGet(flightTicket, flightServerRecordBatchStreamWriter, context); } @@ -84,8 +84,8 @@ public override async Task GetSchema(Protocol.FlightDescriptor req public override Task DoExchange(IAsyncStreamReader requestStream, IServerStreamWriter responseStream, ServerCallContext context) { - var readStream = new FlightServerRecordBatchStreamReader(requestStream); - var writeStream = new FlightServerRecordBatchStreamWriter(responseStream); + var readStream = new FlightServerRecordBatchStreamReader(requestStream, _flightServer.Context); + var writeStream = new FlightServerRecordBatchStreamWriter(responseStream, _flightServer.Context); return _flightServer.DoExchange(readStream, writeStream, context); } diff --git a/test/Apache.Arrow.Flight.TestWeb/TestFlightServer.cs b/test/Apache.Arrow.Flight.TestWeb/TestFlightServer.cs index 45aeff1a..424c5e87 100644 --- a/test/Apache.Arrow.Flight.TestWeb/TestFlightServer.cs +++ b/test/Apache.Arrow.Flight.TestWeb/TestFlightServer.cs @@ -28,7 +28,10 @@ public class TestFlightServer : FlightServer { private readonly FlightStore _flightStore; - public TestFlightServer(FlightStore flightStore) + // The context is optional: it is resolved from dependency injection when a test registers + // one, which exercises the path where ASP.NET Core creates the server. + public TestFlightServer(FlightStore flightStore, ArrowContext context = null) + : base(context) { _flightStore = flightStore; } diff --git a/test/Apache.Arrow.Flight.Tests/FlightContextTests.cs b/test/Apache.Arrow.Flight.Tests/FlightContextTests.cs new file mode 100644 index 00000000..c91d9b94 --- /dev/null +++ b/test/Apache.Arrow.Flight.Tests/FlightContextTests.cs @@ -0,0 +1,226 @@ +// 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.Buffers; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Apache.Arrow.Arrays; +using Apache.Arrow.Flight.Client; +using Apache.Arrow.Flight.TestWeb; +using Apache.Arrow.Memory; +using Grpc.Core.Utils; +using Microsoft.Extensions.DependencyInjection; +using Xunit; + +namespace Apache.Arrow.Flight.Tests +{ + /// + /// Tests that an given to a or to a + /// reaches the record-batch readers and writers they create. + /// The server is created by dependency injection, so the server tests also cover that path. + /// + public class FlightContextTests + { + private static readonly Guid s_guid = Guid.Parse("01234567-89ab-cdef-0123-456789abcdef"); + + [Fact] + public async Task ServerContextRegistryResolvesExtensionTypesOnPut() + { + FlightStore store = new FlightStore(); + using TestWebFactory factory = new TestWebFactory(store, GuidContext()); + FlightClient client = new FlightClient(factory.GetChannel()); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("guids"); + + RecordBatch batch = GuidBatch(); + FlightRecordBatchDuplexStreamingCall put = await client.StartPut(descriptor, batch.Schema); + await put.RequestStream.WriteAsync(batch); + await put.RequestStream.CompleteAsync(); + await put.ResponseStream.ToListAsync(); + + RecordBatch received = store.Flights[descriptor].GetRecordBatches().Single().RecordBatch; + Assert.Equal(s_guid, Assert.IsType(received.Column(0)).GetGuid(0)); + } + + [Fact] + public async Task ServerWithoutContextUsesTheDefaultRegistry() + { + Assert.False(ExtensionTypeRegistry.Default.TryGetDefinition(GuidType.Default.Name, out _), + "This test assumes that nothing has registered the GUID extension type globally."); + + FlightStore store = new FlightStore(); + using TestWebFactory factory = new TestWebFactory(store); + FlightClient client = new FlightClient(factory.GetChannel()); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("guids"); + + RecordBatch batch = GuidBatch(); + FlightRecordBatchDuplexStreamingCall put = await client.StartPut(descriptor, batch.Schema); + await put.RequestStream.WriteAsync(batch); + await put.RequestStream.CompleteAsync(); + await put.ResponseStream.ToListAsync(); + + RecordBatch received = store.Flights[descriptor].GetRecordBatches().Single().RecordBatch; + Assert.IsType(received.Column(0)); + } + + [Fact] + public async Task ClientContextRegistryResolvesExtensionTypesOnGet() + { + FlightStore store = new FlightStore(); + using TestWebFactory factory = new TestWebFactory(store); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("guids"); + RecordBatch batch = GuidBatch(); + FlightHolder holder = new FlightHolder(descriptor, batch.Schema, factory.GetAddress()); + holder.AddBatch(new RecordBatchWithMetadata(batch)); + store.Flights[descriptor] = holder; + + FlightClient withContext = new FlightClient(factory.GetChannel(), GuidContext()); + FlightClient withoutContext = new FlightClient(factory.GetChannel()); + FlightTicket ticket = new FlightTicket(descriptor.Paths.Single()); + + RecordBatch resolved = (await withContext.GetStream(ticket).ResponseStream.ToListAsync()).Single(); + RecordBatch unresolved = (await withoutContext.GetStream(ticket).ResponseStream.ToListAsync()).Single(); + + Assert.Equal(s_guid, Assert.IsType(resolved.Column(0)).GetGuid(0)); + Assert.IsType(unresolved.Column(0)); + } + + [Fact] + public async Task ClientFactoryClientGetsTheRegisteredContext() + { + FlightStore store = new FlightStore(); + using TestWebFactory factory = new TestWebFactory(store); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("guids"); + RecordBatch batch = GuidBatch(); + FlightHolder holder = new FlightHolder(descriptor, batch.Schema, factory.GetAddress()); + holder.AddBatch(new RecordBatchWithMetadata(batch)); + store.Flights[descriptor] = holder; + + // Grpc.Net.ClientFactory creates the client by reflection; the context comes from DI. + IServiceCollection services = new ServiceCollection(); + services.AddSingleton(GuidContext()); + services.AddGrpcClient(grpc => grpc.Address = new Uri(factory.GetAddress())); + using ServiceProvider provider = services.BuildServiceProvider(); + FlightClient client = provider.GetRequiredService(); + + RecordBatch received = (await client.GetStream(new FlightTicket("guids")).ResponseStream.ToListAsync()).Single(); + + Assert.Equal(s_guid, Assert.IsType(received.Column(0)).GetGuid(0)); + } + + [Fact] + public async Task ClientContextAllocatorIsUsedForWriterTemporaries() + { + FlightStore store = new FlightStore(); + using TestWebFactory factory = new TestWebFactory(store); + LiveCountingAllocator allocator = new LiveCountingAllocator(); + FlightClient client = new FlightClient(factory.GetChannel(), new ArrowContext(allocator)); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("sliced"); + + // A sliced string column makes the writer re-base its offsets into a new buffer. + RecordBatch batch = SlicedStringBatch(); + FlightRecordBatchDuplexStreamingCall put = await client.StartPut(descriptor, batch.Schema); + await put.RequestStream.WriteAsync(batch); + await put.RequestStream.CompleteAsync(); + await put.ResponseStream.ToListAsync(); + + Assert.True(allocator.Statistics.Allocations > 0, "The writer should have allocated from the context."); + Assert.Equal(0, allocator.LiveAllocations); + RecordBatch received = store.Flights[descriptor].GetRecordBatches().Single().RecordBatch; + Assert.Equal("ccc", ((StringArray)received.Column(0)).GetString(1)); + } + + [Fact] + public async Task ServerContextAllocatorIsUsedForWriterTemporaries() + { + FlightStore store = new FlightStore(); + LiveCountingAllocator allocator = new LiveCountingAllocator(); + using TestWebFactory factory = new TestWebFactory(store, new ArrowContext(allocator)); + FlightDescriptor descriptor = FlightDescriptor.CreatePathDescriptor("sliced"); + RecordBatch batch = SlicedStringBatch(); + FlightHolder holder = new FlightHolder(descriptor, batch.Schema, factory.GetAddress()); + holder.AddBatch(new RecordBatchWithMetadata(batch)); + store.Flights[descriptor] = holder; + + FlightClient client = new FlightClient(factory.GetChannel()); + RecordBatch received = (await client.GetStream(new FlightTicket("sliced")).ResponseStream.ToListAsync()).Single(); + + Assert.True(allocator.Statistics.Allocations > 0, "The writer should have allocated from the context."); + Assert.Equal(0, allocator.LiveAllocations); + Assert.Equal("ccc", ((StringArray)received.Column(0)).GetString(1)); + } + + private static ArrowContext GuidContext() + { + ExtensionTypeRegistry registry = new ExtensionTypeRegistry(); + registry.Register(GuidExtensionDefinition.Instance); + return new ArrowContext(extensionRegistry: registry); + } + + private static RecordBatch GuidBatch() + { + GuidArray guids = new GuidArray.Builder().Append(s_guid).Build(); + return new RecordBatch.Builder().Append("id", false, guids).Build(); + } + + private static RecordBatch SlicedStringBatch() + { + StringArray full = new StringArray.Builder().Append("a").Append("bb").Append("ccc").Build(); + return new RecordBatch.Builder().Append("s", false, (StringArray)full.Slice(1, 2)).Build(); + } + + /// + /// A caller-owned allocator over managed arrays that counts allocations not yet released. + /// + private sealed class LiveCountingAllocator : MemoryAllocator + { + private int _live; + + public int LiveAllocations => Volatile.Read(ref _live); + + public override AllocationLifetime Lifetime => AllocationLifetime.CallerOwned; + + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + Interlocked.Increment(ref _live); + bytesAllocated = length; + return new Owner(this, new byte[length]); + } + + private sealed class Owner : IMemoryOwner + { + private readonly LiveCountingAllocator _allocator; + private byte[] _buffer; + + public Owner(LiveCountingAllocator allocator, byte[] buffer) + { + _allocator = allocator; + _buffer = buffer; + } + + public Memory Memory => _buffer ?? throw new ObjectDisposedException(nameof(Owner)); + + public void Dispose() + { + if (Interlocked.Exchange(ref _buffer, null) != null) + { + Interlocked.Decrement(ref _allocator._live); + } + } + } + } + } +} diff --git a/test/Apache.Arrow.Flight.Tests/TestWebFactory.cs b/test/Apache.Arrow.Flight.Tests/TestWebFactory.cs index b971b159..32e77247 100644 --- a/test/Apache.Arrow.Flight.Tests/TestWebFactory.cs +++ b/test/Apache.Arrow.Flight.Tests/TestWebFactory.cs @@ -34,9 +34,9 @@ public class TestWebFactory : IDisposable readonly IHost host; private int _port; - public TestWebFactory(FlightStore flightStore) + public TestWebFactory(FlightStore flightStore, ArrowContext serverContext = null) { - host = WebHostBuilder(flightStore).Build(); //Create the server + host = WebHostBuilder(flightStore, serverContext).Build(); //Create the server host.Start(); var addressInfo = host.Services.GetRequiredService().Features.Get(); if (addressInfo == null) @@ -50,7 +50,7 @@ public TestWebFactory(FlightStore flightStore) "System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true); } - private IHostBuilder WebHostBuilder(FlightStore flightStore) + private IHostBuilder WebHostBuilder(FlightStore flightStore, ArrowContext serverContext) { return Host.CreateDefaultBuilder() .ConfigureWebHostDefaults(webBuilder => @@ -64,6 +64,10 @@ private IHostBuilder WebHostBuilder(FlightStore flightStore) .ConfigureServices(services => { services.AddSingleton(flightStore); + if (serverContext != null) + { + services.AddSingleton(serverContext); + } }); }); } From 03327a77c0a4bd90f1c205d82db0154402edd939 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 14:23:30 -0800 Subject: [PATCH 06/15] Add builder benchmarks DefaultPathBuilderBenchmark uses only long-standing APIs, so it can be run against earlier versions to check the default path for regressions. FixedWidthBuilderBenchmark compares ways of filling a fixed-width builder whose final length is known, with and without explicit allocators. Co-Authored-By: Claude Opus 5.5 --- .../DefaultPathBuilderBenchmark.cs | 181 ++++++++++++++++++ .../FixedWidthBuilderBenchmark.cs | 147 ++++++++++++++ 2 files changed, 328 insertions(+) create mode 100644 test/Apache.Arrow.Benchmarks/DefaultPathBuilderBenchmark.cs create mode 100644 test/Apache.Arrow.Benchmarks/FixedWidthBuilderBenchmark.cs diff --git a/test/Apache.Arrow.Benchmarks/DefaultPathBuilderBenchmark.cs b/test/Apache.Arrow.Benchmarks/DefaultPathBuilderBenchmark.cs new file mode 100644 index 00000000..ad9f303c --- /dev/null +++ b/test/Apache.Arrow.Benchmarks/DefaultPathBuilderBenchmark.cs @@ -0,0 +1,181 @@ +// 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.Threading.Tasks; +using BenchmarkDotNet.Attributes; + +namespace Apache.Arrow.Benchmarks +{ + /// + /// Builders used the way existing code uses them: no allocator, no capacity. Uses only APIs + /// that have existed for a long time, so the same file can be run against older versions to + /// check that the default path has not become slower. + /// + [MemoryDiagnoser] + public class DefaultPathBuilderBenchmark + { + [Params(100, 100_000)] + public int Count; + + private int[] _ints; + private string[] _strings; + + [GlobalSetup] + public void Setup() + { + _ints = new int[Count]; + _strings = new string[Math.Min(Count, 10_000)]; + for (int i = 0; i < _ints.Length; i++) + { + _ints[i] = i; + } + for (int i = 0; i < _strings.Length; i++) + { + _strings[i] = "value-" + i; + } + } + + [Benchmark] + public int Int32AppendPerElement() + { + Int32Array.Builder builder = new Int32Array.Builder(); + for (int i = 0; i < Count; i++) + { + builder.Append(i); + } + using Int32Array array = builder.Build(); + return array.Length; + } + + [Benchmark] + public int Int32ReserveThenAppend() + { + Int32Array.Builder builder = new Int32Array.Builder(); + builder.Reserve(Count); + for (int i = 0; i < Count; i++) + { + builder.Append(i); + } + using Int32Array array = builder.Build(); + return array.Length; + } + + [Benchmark] + public int Int32AppendSpan() + { + Int32Array.Builder builder = new Int32Array.Builder(); + builder.Append(_ints); + using Int32Array array = builder.Build(); + return array.Length; + } + + [Benchmark] + public int Int32WithNulls() + { + Int32Array.Builder builder = new Int32Array.Builder(); + for (int i = 0; i < Count; i++) + { + if (i % 10 == 0) + { + builder.AppendNull(); + } + else + { + builder.Append(i); + } + } + using Int32Array array = builder.Build(); + return array.Length; + } + + /// + /// The same appends as without building, so no native + /// memory or GC memory pressure is involved: this measures only the builder's own work. + /// + [Benchmark] + public int Int32WithNullsAppendOnly() + { + Int32Array.Builder builder = new Int32Array.Builder(); + for (int i = 0; i < Count; i++) + { + if (i % 10 == 0) + { + builder.AppendNull(); + } + else + { + builder.Append(i); + } + } + return builder.Length; + } + + [Benchmark] + public int StringAppend() + { + StringArray.Builder builder = new StringArray.Builder(); + foreach (string s in _strings) + { + builder.Append(s); + } + using StringArray array = builder.Build(); + return array.Length; + } + + /// + /// Many threads growing builders at once, without building, so that no native memory or + /// GC memory pressure is involved: this isolates contention on state shared by the + /// builders' growth path. + /// + [Benchmark] + public int ParallelGrowthOnly() + { + int total = 0; + Parallel.For(0, Environment.ProcessorCount * 64, _ => + { + ArrowBuffer.Builder builder = new ArrowBuffer.Builder(); + for (int i = 0; i < 2000; i++) + { + builder.Append(i); + } + System.Threading.Interlocked.Add(ref total, builder.Length); + }); + return total; + } + + /// + /// Many threads building small arrays at once, to expose contention on any state shared + /// between builders. Each build also makes a native allocation that reports GC memory + /// pressure, which makes this case noisy. + /// + [Benchmark] + public int ParallelSmallBuilds() + { + int total = 0; + Parallel.For(0, Environment.ProcessorCount * 64, _ => + { + Int32Array.Builder builder = new Int32Array.Builder(); + for (int i = 0; i < 100; i++) + { + builder.Append(i); + } + using Int32Array array = builder.Build(); + System.Threading.Interlocked.Add(ref total, array.Length); + }); + return total; + } + } +} diff --git a/test/Apache.Arrow.Benchmarks/FixedWidthBuilderBenchmark.cs b/test/Apache.Arrow.Benchmarks/FixedWidthBuilderBenchmark.cs new file mode 100644 index 00000000..203be58e --- /dev/null +++ b/test/Apache.Arrow.Benchmarks/FixedWidthBuilderBenchmark.cs @@ -0,0 +1,147 @@ +// 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.Buffers; +using System.Runtime.InteropServices; +using Apache.Arrow.Memory; +using BenchmarkDotNet.Attributes; + +namespace Apache.Arrow.Benchmarks +{ + /// + /// Compares the ways of filling a fixed-width builder whose final length is known. + /// Every case builds and disposes a complete , so allocation and + /// zeroing are included; isolates the cost of the writes themselves. + /// + [MemoryDiagnoser] + public class FixedWidthBuilderBenchmark + { + [Params(100_000)] + public int Count; + + /// + /// "None" passes no allocator: managed working memory copied into the default allocator, + /// as builders have always behaved. "Native" passes the default allocator explicitly, + /// opting into the hand-over; it reports GC memory pressure and so triggers collections + /// (see issue #261). "CallerOwned" reports none, isolating the builder's own cost. + /// + [Params("None", "Native", "CallerOwned")] + public string Allocator; + + private MemoryAllocator _allocator; + + private int[] _source; + private IMemoryOwner _scratch; + + [GlobalSetup] + public void Setup() + { + _allocator = Allocator switch + { + "CallerOwned" => new CallerOwnedNativeAllocator(), + "Native" => MemoryAllocator.Default.Value, + _ => null, + }; + + _source = new int[Count]; + for (int i = 0; i < Count; i++) + { + _source[i] = i; + } + + _scratch = MemoryAllocator.Default.Value.Allocate(Count * sizeof(int)); + } + + [GlobalCleanup] + public void Cleanup() + { + _scratch.Dispose(); + } + + /// + /// Lower bound: the same writes into native memory that was allocated once, up front. + /// + [Benchmark(Baseline = true)] + public int FillOnly() + { + Span span = MemoryMarshal.Cast(_scratch.Memory.Span); + for (int i = 0; i < span.Length; i++) + { + span[i] = i; + } + return span[span.Length - 1]; + } + + [Benchmark] + public int AppendPerElement() + { + Int32Array.Builder builder = new Int32Array.Builder(Count, _allocator); + for (int i = 0; i < Count; i++) + { + builder.Append(i); + } + return Finish(builder); + } + + [Benchmark] + public int AppendSpan() + { + Int32Array.Builder builder = new Int32Array.Builder(Count, _allocator); + builder.Append(_source); + return Finish(builder); + } + + [Benchmark] + public int GetSpanAdvanceWhole() => GetSpanAdvance(Count); + + [Benchmark] + public int GetSpanAdvanceChunk1024() => GetSpanAdvance(1024); + + [Benchmark] + public int GetSpanAdvanceChunk16() => GetSpanAdvance(16); + + [Benchmark] + public int GetSpanAdvanceChunk1() => GetSpanAdvance(1); + + private int GetSpanAdvance(int chunk) + { + Int32Array.Builder builder = new Int32Array.Builder(Count, _allocator); + int value = 0; + while (value < Count) + { + int n = Math.Min(chunk, Count - value); + Span span = builder.GetSpan(n); + for (int i = 0; i < span.Length; i++) + { + span[i] = value++; + } + builder.Advance(n); + } + return Finish(builder); + } + + private static int Finish(Int32Array.Builder builder) + { + // Disposing the builder matters only for the caller-owned allocator: after a + // hand-over the builder holds a reference to the array's memory. + using (builder) + { + using Int32Array array = builder.Build(); + return array.Length; + } + } + } +} From 35cd57008aaeed224ee383c42258a1a8df830469 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 15:32:17 -0800 Subject: [PATCH 07/15] Address Copilot review: zeroing, self-appends, buffer reuse and leaks - A growing BitmapBuilder.Resize explicitly unsets the bits it adds, instead of relying on the allocator to zero memory (GarbageMemoryAllocator does not). Clear() after a build and the padding of copied buffers are now zeroed explicitly for the same reason. - Appending a span that is part of the builder's own memory copies it first when the append has to grow, since growing releases that memory. Applies to both buffer builders. - A builder built again after a shrinking Resize no longer reuses the earlier buffer, which would have exposed the removed values in its padding. - BuilderMemory keeps itself alive while copying its working memory, so a collection during allocation cannot free the source. - Run-end concatenation releases its builders if it throws partway through. - TimestampArray.Builder(type, capacity, allocator) checks for a null type before allocating. - BitmapBuilder.Capacity no longer overflows for very large bitmaps. Co-Authored-By: Claude Opus 5.5 --- .../Arrays/ArrayDataConcatenator.cs | 20 +- src/Apache.Arrow/Arrays/TimestampArray.cs | 3 +- src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs | 17 +- src/Apache.Arrow/ArrowBuffer.Builder.cs | 7 + src/Apache.Arrow/Memory/BuilderMemory.cs | 37 +++- .../BuilderEdgeCaseTests.cs | 184 ++++++++++++++++++ 6 files changed, 245 insertions(+), 23 deletions(-) create mode 100644 test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs diff --git a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs index 49fb9a56..48d712bf 100644 --- a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs +++ b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs @@ -605,16 +605,12 @@ public void Visit(RunEndEncodedType type) } var slicedValues = new List(_arrayDataList.Count); - ArrowBuffer.Builder int16Builder = null; - ArrowBuffer.Builder int32Builder = null; - ArrowBuffer.Builder int64Builder = null; - - switch (runEndsTypeId) - { - case ArrowTypeId.Int16: int16Builder = new ArrowBuffer.Builder(0, _allocator); break; - case ArrowTypeId.Int32: int32Builder = new ArrowBuffer.Builder(0, _allocator); break; - case ArrowTypeId.Int64: int64Builder = new ArrowBuffer.Builder(0, _allocator); break; - } + // Only the builder for the run-ends type is used. A builder with no capacity + // allocates nothing, and the using declarations release working memory even if + // concatenation throws partway through (for example on run-end overflow). + using ArrowBuffer.Builder int16Builder = new ArrowBuffer.Builder(0, _allocator); + using ArrowBuffer.Builder int32Builder = new ArrowBuffer.Builder(0, _allocator); + using ArrowBuffer.Builder int64Builder = new ArrowBuffer.Builder(0, _allocator); long baseOffset = 0; int physicalRunCount = 0; @@ -705,10 +701,6 @@ public void Visit(RunEndEncodedType type) _ => int64Builder.Build(_allocator), }; - int16Builder?.Dispose(); - int32Builder?.Dispose(); - int64Builder?.Dispose(); - ArrayData runEndsResult = new ArrayData( type.RunEndsDataType, physicalRunCount, 0, 0, new[] { ArrowBuffer.Empty, runEndsValueBuffer }); diff --git a/src/Apache.Arrow/Arrays/TimestampArray.cs b/src/Apache.Arrow/Arrays/TimestampArray.cs index 4daa9b07..4322acad 100644 --- a/src/Apache.Arrow/Arrays/TimestampArray.cs +++ b/src/Apache.Arrow/Arrays/TimestampArray.cs @@ -81,7 +81,8 @@ public Builder(TimestampType type) /// what it builds into , as builders always have. /// public Builder(TimestampType type, int capacity, MemoryAllocator allocator = null) - : base(new TimestampBuilder(type, capacity, allocator)) + // Checked before the inner builder allocates, so that a failure leaks nothing. + : base(new TimestampBuilder(type ?? throw new ArgumentNullException(nameof(type)), capacity, allocator)) { DataType = type; } diff --git a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index 98d724e6..b33c5595 100644 --- a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs +++ b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs @@ -35,7 +35,7 @@ public class BitmapBuilder : IDisposable /// /// Gets the number of bits that can be contained in the memory allocated by the current instance. /// - public int Capacity => _buffer.Capacity * 8; + public int Capacity => (int)Math.Min((long)_buffer.Capacity * 8, int.MaxValue); /// /// Gets the number of bits currently appended. @@ -126,6 +126,13 @@ public BitmapBuilder Append(ReadOnlySpan source, int validBits) if (!source.IsEmpty && validBits > source.Length * 8) throw new ArgumentException($"Number of valid bits ({validBits}) cannot be greater than the source span length ({source.Length * 8} bits).", nameof(validBits)); + // Growing releases the current working memory, so a source that is part of this + // builder's own span would be read after release. Copy such a source first. + if (validBits > Capacity - Length && source.Overlaps(Span)) + { + source = source.ToArray(); + } + // Check if memory copy can be used from the source array (performance optimization for byte-aligned coping) if (!source.IsEmpty && Length % 8 == 0) { @@ -283,6 +290,14 @@ public BitmapBuilder Resize(int capacity) } EnsureCapacity(capacity); + + if (capacity > Length) + { + // The added bits must be unset (null), not whatever the memory held: allocators + // need not zero it, and earlier truncated bits may remain. + BitUtility.SetBits(Span, Length, capacity - Length, false); + } + Length = capacity; SetBitCount = BitUtility.CountBits(Span, 0, Length); diff --git a/src/Apache.Arrow/ArrowBuffer.Builder.cs b/src/Apache.Arrow/ArrowBuffer.Builder.cs index 9fa0988a..84080630 100644 --- a/src/Apache.Arrow/ArrowBuffer.Builder.cs +++ b/src/Apache.Arrow/ArrowBuffer.Builder.cs @@ -152,6 +152,13 @@ public Builder Append(T value) /// Returns the builder (for fluent-style composition). public Builder Append(ReadOnlySpan source) { + // Growing releases the current working memory, so a source that is part of this + // builder's own span would be read after release. Copy such a source first. + if (source.Length > Capacity - Length && source.Overlaps(Span)) + { + source = source.ToArray(); + } + EnsureAdditionalCapacity(source.Length); source.CopyTo(Span.Slice(Length, source.Length)); Length += source.Length; diff --git a/src/Apache.Arrow/Memory/BuilderMemory.cs b/src/Apache.Arrow/Memory/BuilderMemory.cs index 83d1c506..ff2c0383 100644 --- a/src/Apache.Arrow/Memory/BuilderMemory.cs +++ b/src/Apache.Arrow/Memory/BuilderMemory.cs @@ -69,6 +69,10 @@ internal sealed class BuilderMemory : IDisposable private ArrowBuffer _shared; private bool _isShared; + // How many bytes of _shared hold data, as opposed to padding. A later build can share + // the same buffer only if it would hold exactly the same bytes. + private int _sharedUsedBytes; + /// /// The allocator for both working memory and built buffers, or null for managed /// working memory copied into when built. @@ -123,8 +127,12 @@ public Memory Memory /// /// Grows the working memory to at least , preserving - /// its contents and zeroing the added region. + /// its contents. /// + /// + /// The contents of the added region are unspecified: allocators are not required to zero + /// memory, so callers that need zeroes must write them. + /// public void Grow(int capacityBytes) { int rounded = RoundUp(capacityBytes); @@ -156,9 +164,9 @@ public void Reset() ReleaseShared(); _owner = _temporary.Allocate(capacity); _memory = _owner.Memory; - return; } + // Cleared explicitly in both cases, since allocators need not zero what they return. _memory.Span.Clear(); } @@ -179,13 +187,17 @@ public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) if (_isShared) { - // Built again without being written to: share the same memory. - if (handOver && padded == _shared.Length) + // Built again holding exactly the same bytes: share the same memory. A Resize can + // change the length without writing to the builder, so the padded length alone + // is not enough; sharing after a shrink would expose the removed values. + if (handOver && usedBytes == _sharedUsedBytes && padded == _shared.Length) { return _shared.Retain(); } - return Copy(_shared.Span, usedBytes, padded, destination); + ArrowBuffer sharedCopy = Copy(_shared.Span, usedBytes, padded, destination); + GC.KeepAlive(this); + return sharedCopy; } ThrowIfDisposed(); @@ -193,7 +205,13 @@ public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) if (!handOver || padded == 0 || padded > _memory.Length || _memory.Length - padded > _memory.Length / MaxSlackDivisor) { - return Copy(_memory.Span, usedBytes, padded, destination); + ArrowBuffer copy = Copy(_memory.Span, usedBytes, padded, destination); + + // The span copied from refers to working memory this object owns. With a + // finalized native allocator, a collection during Allocate could otherwise free + // that memory before it was read (see the same issue in ArrowStreamWriter). + GC.KeepAlive(this); + return copy; } // The bytes between the data and the padding boundary may hold values left behind @@ -206,6 +224,7 @@ public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) ArrowBuffer result = new ArrowBuffer(owner, _temporary.Lifetime); _shared = result.Retain(); + _sharedUsedBytes = usedBytes; _isShared = true; _owner = null; _memory = Memory.Empty; @@ -247,7 +266,11 @@ private void ReleaseShared() private static ArrowBuffer Copy(ReadOnlySpan source, int usedBytes, int padded, MemoryAllocator allocator) { IMemoryOwner owner = allocator.Allocate(padded); - source.Slice(0, usedBytes).CopyTo(owner.Memory.Span); + Span destination = owner.Memory.Span; + source.Slice(0, usedBytes).CopyTo(destination); + + // Allocators need not zero memory, and the padding must not hold garbage. + destination.Slice(usedBytes).Clear(); return new ArrowBuffer(owner, allocator.Lifetime); } diff --git a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs new file mode 100644 index 00000000..826e7781 --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs @@ -0,0 +1,184 @@ +// 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 Apache.Arrow.Memory; +using Apache.Arrow.Types; +using Xunit; + +namespace Apache.Arrow.Tests +{ + /// + /// Edge cases in allocator-backed builders: allocators that do not zero their memory, appends + /// whose source is the builder's own memory, and reuse of a buffer after the builder changes. + /// + public class BuilderEdgeCaseTests + { + [Fact] + public void GrowingResizeMarksNewSlotsNullEvenWithoutZeroedMemory() + { + // Allocators are not required to zero memory (GarbageMemoryAllocator fills it with 0xA5). + GarbageMemoryAllocator allocator = new GarbageMemoryAllocator(); + using Int32Array.Builder builder = new Int32Array.Builder(0, allocator); + + using Int32Array array = builder.Resize(3).Build(); + + Assert.Equal(3, array.NullCount); + for (int i = 0; i < 3; i++) + { + Assert.True(array.IsNull(i)); + } + } + + [Fact] + public void GrowingBitmapResizeAddsUnsetBitsEvenWithoutZeroedMemory() + { + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(0, new GarbageMemoryAllocator()); + builder.Append(true); + + builder.Resize(16); + + Assert.Equal(1, builder.SetBitCount); + Assert.Equal(15, builder.UnsetBitCount); + } + + [Fact] + public void ClearAfterBuildZeroesTheBuilderEvenWithoutZeroedMemory() + { + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, new GarbageMemoryAllocator()); + builder.Append(1); + using ArrowBuffer built = builder.Build(); + + builder.Clear(); + + Assert.All(builder.Span.ToArray(), v => Assert.Equal(0, v)); + } + + [Fact] + public void CopiedBufferPaddingIsZeroedEvenWithoutZeroedMemory() + { + GarbageMemoryAllocator allocator = new GarbageMemoryAllocator(); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(1024, new CallerOwnedNativeAllocator()); + builder.Append(7); + + // A different target allocator forces the copying path. + using ArrowBuffer buffer = builder.Build(allocator); + + Assert.Equal(7, buffer.Span.CastTo()[0]); + for (int i = sizeof(int); i < 64; i++) + { + Assert.Equal(0, buffer.Span[i]); + } + } + + [Fact] + public void AppendingTheBuildersOwnSpanSurvivesGrowth() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + for (int i = 0; i < builder.Capacity; i++) + { + builder.Append(i); + } + int count = builder.Length; + + // The source is the builder's own memory, which growing would otherwise release. + builder.Append(builder.Span.Slice(0, count)); + + Assert.Equal(2 * count, builder.Length); + for (int i = 0; i < count; i++) + { + Assert.Equal(i, builder.Span[i]); + Assert.Equal(i, builder.Span[count + i]); + } + } + + [Fact] + public void AppendingTheBitmapBuildersOwnSpanSurvivesGrowth() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(512, allocator); + int bits = builder.Capacity; + for (int i = 0; i < bits; i++) + { + builder.Append(i % 3 == 0); + } + int setBits = builder.SetBitCount; + + builder.Append(builder.Span.Slice(0, bits / 8), bits); + + Assert.Equal(2 * bits, builder.Length); + Assert.Equal(2 * setBits, builder.SetBitCount); + for (int i = 0; i < bits; i++) + { + Assert.Equal(i % 3 == 0, BitUtility.GetBit(builder.Span, bits + i)); + } + } + + [Fact] + public void RebuildingAfterShrinkingDoesNotExposeRemovedValues() + { + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, new CallerOwnedNativeAllocator()); + for (int i = 1; i <= 16; i++) + { + builder.Append(i); + } + using ArrowBuffer first = builder.Build(); + + builder.Resize(1); + using ArrowBuffer second = builder.Build(); + + // The second buffer's padding must be zero, not the values the resize removed... + Assert.Equal(1, second.Span.CastTo()[0]); + for (int i = sizeof(int); i < second.Length; i++) + { + Assert.Equal(0, second.Span[i]); + } + + // ...and the first buffer must be unchanged. + for (int i = 0; i < 16; i++) + { + Assert.Equal(i + 1, first.Span.CastTo()[i]); + } + } + + [Fact] + public void FailedRunEndConcatenationReleasesItsWorkingMemory() + { + // Two Int16 run-end arrays of logical length 20,000 overflow Int16 when concatenated. + RunEndEncodedArray first = new RunEndEncodedArray( + new Int16Array.Builder().Append(20000).Build(), + new StringArray.Builder().Append("A").Build()); + RunEndEncodedArray second = new RunEndEncodedArray( + new Int16Array.Builder().Append(20000).Build(), + new StringArray.Builder().Append("B").Build()); + GarbageMemoryAllocator allocator = new GarbageMemoryAllocator(); + + Assert.ThrowsAny(() => ArrowArrayConcatenator.Concatenate(new IArrowArray[] { first, second }, allocator)); + + Assert.Equal(0, allocator.Outstanding); + } + + [Fact] + public void TimestampBuilderWithNullTypeAllocatesNothing() + { + GarbageMemoryAllocator allocator = new GarbageMemoryAllocator(); + + Assert.Throws(() => new TimestampArray.Builder((TimestampType)null, 100, allocator)); + + Assert.Equal(0, allocator.Outstanding); + } + } +} From 042534874e630aeb2db8a11aa1e6cbc45dbc7b4f Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 15:47:36 -0800 Subject: [PATCH 08/15] Address second Copilot review: concatenation lifetimes and pinned memory - Concatenated buffers now carry their allocator's lifetime, as built buffers do. They were created through a helper that always used the Finalized lifetime, so buffers from caller-owned or pooled allocators could still be released by collection. - CallerOwnedNativeAllocator tracks pins. Disposing a pinned buffer marks it disposed but defers freeing the memory until the last pin is released, so a pinned pointer never dangles. It also counts live allocations, for tests. Co-Authored-By: Claude Opus 5.5 --- .../Arrays/ArrayDataConcatenator.cs | 7 +- .../Memory/CallerOwnedNativeAllocator.cs | 76 +++++++++++++++++-- .../DefaultAllocationBehaviorTests.cs | 73 ++++++++++++++++++ 3 files changed, 146 insertions(+), 10 deletions(-) diff --git a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs index 48d712bf..8f1abf52 100644 --- a/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs +++ b/src/Apache.Arrow/Arrays/ArrayDataConcatenator.cs @@ -1101,12 +1101,15 @@ private IMemoryOwner AllocateBitmap(out Span destination) return owner; } - private static ArrowBuffer BuildBuffer(IMemoryOwner owner, int byteLength) + private ArrowBuffer BuildBuffer(IMemoryOwner owner, int byteLength) { // Allocators don't have to return zeroed memory, and may return more than was requested, // so clear everything past the written bytes explicitly owner.Memory.Span.Slice(byteLength).Clear(); - return new ArrowBuffer(owner); + + // Carry the allocator's lifetime, as built buffers do, so that allocators which opt + // out of release by finalization are not released by it here. + return new ArrowBuffer(owner, (_allocator ?? MemoryAllocator.Default.Value).Lifetime); } private ArrowBuffer ConcatenateLargeOffsetBuffer() diff --git a/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs index a34fe6d4..3a9b51e4 100644 --- a/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs +++ b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs @@ -47,8 +47,13 @@ public CallerOwnedNativeAllocator(int alignment = DefaultAlignment) } } + private int _liveAllocations; + public override AllocationLifetime Lifetime => AllocationLifetime.CallerOwned; + /// The number of allocations not yet freed. + internal int LiveAllocations => Volatile.Read(ref _liveAllocations); + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) { #if NET6_0_OR_GREATER @@ -64,21 +69,33 @@ protected override IMemoryOwner AllocateInternal(int length, out int bytes new Span((byte*)ptr + offset, length).Clear(); bytesAllocated = length + Alignment; - return new CallerOwnedMemoryManager(ptr, offset, length); + Interlocked.Increment(ref _liveAllocations); + return new CallerOwnedMemoryManager(this, ptr, offset, length); } /// /// A over native memory with no finalizer, so that /// reachability never determines when the memory is freed (CA2015). /// + /// + /// Disposal while the memory is pinned marks the manager disposed but defers freeing the + /// memory until the last pin is released, so a pinned pointer never dangles. This differs + /// from , which throws instead; throwing from disposal is + /// discouraged (CA1065), and deferral cannot leak unless a pin is never released. + /// private sealed class CallerOwnedMemoryManager : MemoryManager { + private readonly CallerOwnedNativeAllocator _allocator; private readonly int _offset; private readonly int _length; + private readonly object _sync = new object(); private IntPtr _ptr; + private int _pinCount; + private bool _disposed; - public CallerOwnedMemoryManager(void* ptr, int offset, int length) + public CallerOwnedMemoryManager(CallerOwnedNativeAllocator allocator, void* ptr, int offset, int length) { + _allocator = allocator; _ptr = (IntPtr)ptr; _offset = offset; _length = length; @@ -87,7 +104,7 @@ public CallerOwnedMemoryManager(void* ptr, int offset, int length) public override Span GetSpan() { IntPtr ptr = Volatile.Read(ref _ptr); - if (ptr == IntPtr.Zero) + if (ptr == IntPtr.Zero || Volatile.Read(ref _disposed)) { throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); } @@ -102,22 +119,64 @@ public override MemoryHandle Pin(int elementIndex = 0) throw new ArgumentOutOfRangeException(nameof(elementIndex)); } - IntPtr ptr = Volatile.Read(ref _ptr); - if (ptr == IntPtr.Zero) + IntPtr ptr; + lock (_sync) { - throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); + if (_disposed) + { + throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); + } + + _pinCount++; + ptr = _ptr; } - // Native memory does not move, so there is nothing to pin; the handle - // holds a reference to this manager so the memory stays reachable. + // Native memory does not move, so there is nothing to pin in the GC sense; the + // count only keeps disposal from freeing the memory while the pointer is in use. return new MemoryHandle((byte*)ptr + _offset + elementIndex, default, this); } public override void Unpin() { + bool free; + lock (_sync) + { + if (_pinCount == 0) + { + return; + } + + _pinCount--; + free = _disposed && _pinCount == 0; + } + + if (free) + { + Free(); + } } protected override void Dispose(bool disposing) + { + bool free; + lock (_sync) + { + if (_disposed) + { + return; + } + + _disposed = true; + free = _pinCount == 0; + } + + if (free) + { + Free(); + } + } + + private void Free() { IntPtr ptr = Interlocked.Exchange(ref _ptr, IntPtr.Zero); if (ptr != IntPtr.Zero) @@ -127,6 +186,7 @@ protected override void Dispose(bool disposing) #else AlignedNative.AlignedFree((void*)ptr); #endif + Interlocked.Decrement(ref _allocator._liveAllocations); } } } diff --git a/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs b/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs index e85cd9d8..62c65d5d 100644 --- a/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs +++ b/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs @@ -116,6 +116,67 @@ public void OtherLifetimesOptOutOfReleaseByCollection(AllocationLifetime lifetim Assert.Equal(1, allocator.LiveAllocations); } + [Fact] + public void UndisposedConcatenationsFromFinalizedAllocatorsAreReleasedByCollection() + { + CountingAllocator allocator = new CountingAllocator(AllocationLifetime.Finalized); + ConcatenateAndAbandon(allocator); + + Collect(); + + Assert.Equal(0, allocator.LiveAllocations); + } + + [Theory] + [InlineData(AllocationLifetime.CallerOwned)] + [InlineData(AllocationLifetime.GarbageCollected)] + public void ConcatenationsFromOtherLifetimesOptOutOfReleaseByCollection(AllocationLifetime lifetime) + { + // Concatenation writes directly into allocator memory, so its buffers must carry the + // allocator's lifetime just as built buffers do. + CountingAllocator allocator = new CountingAllocator(lifetime); + ConcatenateAndAbandon(allocator); + int allocated = allocator.LiveAllocations; + + Collect(); + + Assert.True(allocated > 0); + Assert.Equal(allocated, allocator.LiveAllocations); + } + + [Fact] + public void CallerOwnedMemoryIsNotFreedWhilePinned() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + IMemoryOwner owner = allocator.Allocate(64); + MemoryHandle pin = owner.Memory.Pin(); + + owner.Dispose(); + + // The pointer is still in use, so freeing waits until the last pin is released. + Assert.Equal(1, allocator.LiveAllocations); + Assert.Throws(() => owner.Memory.Span.Length); + + pin.Dispose(); + Assert.Equal(0, allocator.LiveAllocations); + + // Releasing again is harmless. + owner.Dispose(); + Assert.Equal(0, allocator.LiveAllocations); + } + + [Fact] + public void CallerOwnedMemoryIsFreedOnDisposalWhenNotPinned() + { + CallerOwnedNativeAllocator allocator = new CallerOwnedNativeAllocator(); + IMemoryOwner owner = allocator.Allocate(64); + owner.Memory.Pin().Dispose(); + + owner.Dispose(); + + Assert.Equal(0, allocator.LiveAllocations); + } + [Theory] [InlineData(MemoryAllocator.DefaultAlignment)] [InlineData(128)] @@ -141,6 +202,18 @@ private static void BuildAndAbandon(MemoryAllocator allocator) builder.Append(1).Build(); } + /// + /// Concatenates two arrays into buffers from and abandons the + /// result without disposing it. + /// + [MethodImpl(MethodImplOptions.NoInlining)] + private static void ConcatenateAndAbandon(MemoryAllocator allocator) + { + Int32Array first = new Int32Array.Builder().Append(1).AppendNull().Build(); + Int32Array second = new Int32Array.Builder().Append(3).Build(); + ArrowArrayConcatenator.Concatenate(new IArrowArray[] { first, second }, allocator); + } + private static void Collect() { GC.Collect(); From 4a022947b51f8086665f9c124b55779208f4b3f6 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 16:07:10 -0800 Subject: [PATCH 09/15] Address third Copilot review: appends after a build and decompression leaks - Appending a span that points into memory the builder is about to release now copies it first in both buffer builders. Besides growth, this covers the first write after a build: that releases the builder's reference to the built buffer, which may be the last one. The overlap check reads the current memory without detaching, since detaching would release it. - A failed decompression disposes its output buffer instead of leaking it. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs | 8 ++- src/Apache.Arrow/ArrowBuffer.Builder.cs | 10 +++- .../Ipc/DecompressingBufferCreator.cs | 16 +++++- src/Apache.Arrow/Memory/BuilderMemory.cs | 13 +++++ .../BuilderDisposalTests.cs | 55 +++++++++++++++++++ .../BuilderEdgeCaseTests.cs | 39 +++++++++++++ 6 files changed, 132 insertions(+), 9 deletions(-) diff --git a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index b33c5595..77828766 100644 --- a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs +++ b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs @@ -126,9 +126,11 @@ public BitmapBuilder Append(ReadOnlySpan source, int validBits) if (!source.IsEmpty && validBits > source.Length * 8) throw new ArgumentException($"Number of valid bits ({validBits}) cannot be greater than the source span length ({source.Length * 8} bits).", nameof(validBits)); - // Growing releases the current working memory, so a source that is part of this - // builder's own span would be read after release. Copy such a source first. - if (validBits > Capacity - Length && source.Overlaps(Span)) + // Writing can release the memory backing the builder: growing releases the working + // memory, and the first write after a build releases the builder's reference to the + // built buffer. A source that points into that memory must be copied first. The check + // reads the memory without detaching, since detaching would itself release it. + if ((validBits > Capacity - Length || _buffer.IsShared) && source.Overlaps(_buffer.CurrentBytes)) { source = source.ToArray(); } diff --git a/src/Apache.Arrow/ArrowBuffer.Builder.cs b/src/Apache.Arrow/ArrowBuffer.Builder.cs index 84080630..676a1994 100644 --- a/src/Apache.Arrow/ArrowBuffer.Builder.cs +++ b/src/Apache.Arrow/ArrowBuffer.Builder.cs @@ -16,6 +16,7 @@ using System; using System.Collections.Generic; using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; using Apache.Arrow.Memory; namespace Apache.Arrow @@ -152,9 +153,12 @@ public Builder Append(T value) /// Returns the builder (for fluent-style composition). public Builder Append(ReadOnlySpan source) { - // Growing releases the current working memory, so a source that is part of this - // builder's own span would be read after release. Copy such a source first. - if (source.Length > Capacity - Length && source.Overlaps(Span)) + // Writing can release the memory backing the builder: growing releases the working + // memory, and the first write after a build releases the builder's reference to the + // built buffer. A source that points into that memory must be copied first. The check + // reads the memory without detaching, since detaching would itself release it. + if ((source.Length > Capacity - Length || _buffer.IsShared) && + MemoryMarshal.AsBytes(source).Overlaps(_buffer.CurrentBytes)) { source = source.ToArray(); } diff --git a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs index eff39e5a..0e416ba5 100644 --- a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs +++ b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs @@ -52,10 +52,20 @@ public ArrowBuffer CreateBuffer(ReadOnlyMemory source) } var outputData = _allocator.Allocate(Convert.ToInt32(uncompressedLength)); - var decompressedLength = _compressionCodec.Decompress(source.Slice(8), outputData.Memory); - if (decompressedLength != uncompressedLength) + try { - throw new Exception($"Expected to decompress {uncompressedLength} bytes, but got {decompressedLength} bytes"); + var decompressedLength = _compressionCodec.Decompress(source.Slice(8), outputData.Memory); + if (decompressedLength != uncompressedLength) + { + throw new Exception($"Expected to decompress {uncompressedLength} bytes, but got {decompressedLength} bytes"); + } + } + catch + { + // Nothing else owns the output yet, so a failure (for example on corrupt input) + // would otherwise leak it; with a caller-owned allocator, permanently. + outputData.Dispose(); + throw; } return new ArrowBuffer(outputData, _allocator.Lifetime); diff --git a/src/Apache.Arrow/Memory/BuilderMemory.cs b/src/Apache.Arrow/Memory/BuilderMemory.cs index ff2c0383..7982ae69 100644 --- a/src/Apache.Arrow/Memory/BuilderMemory.cs +++ b/src/Apache.Arrow/Memory/BuilderMemory.cs @@ -108,6 +108,19 @@ private BuilderMemory(MemoryAllocator temporary, MemoryAllocator longTerm, int c /// public int Capacity => _isShared ? _shared.Length : _memory.Length; + /// + /// Whether the builder's memory currently belongs to a built buffer, in which case the + /// next write releases the builder's reference to it. + /// + public bool IsShared => _isShared; + + /// + /// The bytes currently backing the builder, read without detaching: the working memory, + /// or the buffer it was handed to. Callers use this to tell whether a span points into + /// memory that writing to the builder could release. + /// + public ReadOnlySpan CurrentBytes => _isShared ? _shared.Span : _memory.Span; + /// /// The writable working memory. If it has been handed to a built buffer, the contents /// are first copied into memory the builder owns, so writes never reach that buffer. diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index 63507cab..08c069f9 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -292,6 +292,36 @@ public void InMemoryReaderUsesContextAllocatorForDecompression() }); } + [Fact] + public void FailedDecompressionReleasesItsOutputBuffer() + { + using RecordBatch original = new RecordBatch.Builder() + .Append("ints", false, col => col.Int32(b => b.Append(1).Append(2))) + .Build(); + + MemoryStream stream = new MemoryStream(); + IpcOptions options = new IpcOptions + { + CompressionCodec = CompressionCodecType.Lz4Frame, + CompressionCodecFactory = new PassThroughCodecFactory(), + }; + using (ArrowStreamWriter writer = new ArrowStreamWriter(stream, original.Schema, leaveOpen: true, options)) + { + writer.WriteRecordBatch(original); + writer.WriteEnd(); + } + + // The in-memory reader allocates nothing but decompression output, so anything left + // outstanding after the failure is a leaked output buffer. + Run(allocator => + { + ArrowContext context = new ArrowContext(allocator, new FailingCodecFactory()); + using ArrowStreamReader reader = new ArrowStreamReader(context, new ReadOnlyMemory(stream.ToArray())); + + Assert.Throws(() => reader.ReadNextRecordBatch()); + }); + } + [Fact] public void CodecFactoryInOptionsTakesPrecedenceOverContext() { @@ -465,6 +495,31 @@ public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, CreateCodec(compressionCodecType); } + private sealed class FailingCodecFactory : ICompressionCodecFactory + { + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) => new FailingCodec(); + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, int? compressionLevel) => + CreateCodec(compressionCodecType); + } + + /// + /// A codec whose decompression fails on any data, as it would on corrupt input. Empty + /// buffers still succeed, so that the failure happens after an output buffer is allocated. + /// + private sealed class FailingCodec : ICompressionCodec + { + public int Decompress(ReadOnlyMemory source, Memory destination) => + source.IsEmpty ? 0 : throw new InvalidDataException("Corrupt compressed data."); + + public void Compress(ReadOnlyMemory source, Stream destination) => + throw new NotSupportedException(); + + public void Dispose() + { + } + } + private sealed class PassThroughCodec : ITryCompressionCodec { public int Decompress(ReadOnlyMemory source, Memory destination) diff --git a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs index 826e7781..49a028bc 100644 --- a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs +++ b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs @@ -127,6 +127,45 @@ public void AppendingTheBitmapBuildersOwnSpanSurvivesGrowth() } } + [Fact] + public void AppendingASpanCapturedBeforeBuildSurvivesTheHandOver() + { + // After a hand-over, the builder holds the only remaining reference once the built + // buffer is disposed; writing to the builder releases it. A span captured earlier + // points into that memory, so it must be copied before the release. + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); + builder.Append(0).Append(1).Append(2).Append(3); + Span captured = builder.Span.Slice(0, 4); + builder.Build().Dispose(); + + builder.Append(captured); + + Assert.Equal(new[] { 0, 1, 2, 3, 0, 1, 2, 3 }, builder.Span.Slice(0, 8).ToArray()); + } + + [Fact] + public void AppendingABitmapSpanCapturedBeforeBuildSurvivesTheHandOver() + { + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(64, allocator); + for (int i = 0; i < 16; i++) + { + builder.Append(i % 3 == 0); + } + Span captured = builder.Span.Slice(0, 2); + builder.Build().Dispose(); + + builder.Append(captured, 16); + + Assert.Equal(32, builder.Length); + Assert.Equal(12, builder.SetBitCount); + for (int i = 0; i < 16; i++) + { + Assert.Equal(i % 3 == 0, BitUtility.GetBit(builder.Span, 16 + i)); + } + } + [Fact] public void RebuildingAfterShrinkingDoesNotExposeRemovedValues() { From f8346b57b3b25f6155ab2b2fd28bd6a94be9758c Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 16:39:13 -0800 Subject: [PATCH 10/15] Release IPC buffers when reading or writing fails With a caller-owned allocator these paths leaked permanently; with the default allocator a finalizer eventually reclaimed the memory. - The writer allocates all of a batch's temporary buffers before writing and released each only after writing it, so a write that failed partway through (for example on a broken connection) leaked the rest. The batch builder now releases any buffers not yet released when it is disposed, and preparing a batch releases what it allocated if it throws. Buffers are still released as soon as they are written. - The readers released a message body only by handing it to a record batch. A truncated stream, a malformed message or a failed decompression leaked it, as did a non-empty body on a schema or unrecognized message. CreateArrowObjectFromMessage now owns the body and releases it unless the result refers to it, and the stream readers release it if reading it fails. - BitmapBuilder copies a source that overlaps its own memory whenever it appends it: appending bit by bit could otherwise overwrite source bits before reading them. Dictionary batch bodies are still never released; that needs a separate design. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs | 11 +- .../Ipc/ArrowReaderImplementation.cs | 73 ++++++--- .../Ipc/ArrowStreamReaderImplementation.cs | 28 +++- src/Apache.Arrow/Ipc/ArrowStreamWriter.cs | 101 ++++++++---- .../BuilderDisposalTests.cs | 148 ++++++++++++++++++ .../BuilderEdgeCaseTests.cs | 17 ++ 6 files changed, 317 insertions(+), 61 deletions(-) diff --git a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index 77828766..8db6dd7e 100644 --- a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs +++ b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs @@ -126,11 +126,12 @@ public BitmapBuilder Append(ReadOnlySpan source, int validBits) if (!source.IsEmpty && validBits > source.Length * 8) throw new ArgumentException($"Number of valid bits ({validBits}) cannot be greater than the source span length ({source.Length * 8} bits).", nameof(validBits)); - // Writing can release the memory backing the builder: growing releases the working - // memory, and the first write after a build releases the builder's reference to the - // built buffer. A source that points into that memory must be copied first. The check - // reads the memory without detaching, since detaching would itself release it. - if ((validBits > Capacity - Length || _buffer.IsShared) && source.Overlaps(_buffer.CurrentBytes)) + // A source that points into the builder's own memory is copied first. Writing can + // release that memory (growing releases the working memory, and the first write after + // a build releases the builder's reference to the built buffer), and appending bit by + // bit can overwrite source bits before they are read. The check reads the memory + // without detaching, since detaching would itself release it. + if (source.Overlaps(_buffer.CurrentBytes)) { source = source.ToArray(); } diff --git a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs index 10fbc8e3..fca07698 100644 --- a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs @@ -137,36 +137,61 @@ private static bool MatchEnum(Flatbuf.MessageHeader messageHeader, Type flatBuff /// The record batch when the message type is RecordBatch. /// Null when the message type is not RecordBatch. /// + /// + /// Creates the object a message describes. Takes ownership of , + /// the message body: it either passes it to the result or releases it, including when the + /// message cannot be read. + /// protected RecordBatch CreateArrowObjectFromMessage( Flatbuf.Message message, ByteBuffer bodyByteBuffer, IMemoryOwner memoryOwner) { - switch (message.HeaderType) + bool bodyKept = false; + try { - case Flatbuf.MessageHeader.Schema: - // TODO: Read schema and verify equality? - break; - case Flatbuf.MessageHeader.DictionaryBatch: - Flatbuf.DictionaryBatch dictionaryBatch = message.Header().Value; - ReadDictionaryBatch(message.Version, dictionaryBatch, bodyByteBuffer, memoryOwner); - break; - case Flatbuf.MessageHeader.RecordBatch: - Flatbuf.RecordBatch rb = message.Header().Value; - if (rb.Length < 0 || rb.Length > int.MaxValue) - { - throw new InvalidDataException( - $"Cannot read batch. Message body of {rb.Length} rows is out of range."); - } + switch (message.HeaderType) + { + case Flatbuf.MessageHeader.Schema: + // TODO: Read schema and verify equality? + break; + case Flatbuf.MessageHeader.DictionaryBatch: + Flatbuf.DictionaryBatch dictionaryBatch = message.Header().Value; + ReadDictionaryBatch(message.Version, dictionaryBatch, bodyByteBuffer, memoryOwner); + + // The dictionary's arrays refer to the body, so it must stay alive. Nothing + // owns it yet: it is reclaimed only by finalization, which leaks it with a + // caller-owned allocator. + bodyKept = true; + break; + case Flatbuf.MessageHeader.RecordBatch: + Flatbuf.RecordBatch rb = message.Header().Value; + if (rb.Length < 0 || rb.Length > int.MaxValue) + { + throw new InvalidDataException( + $"Cannot read batch. Message body of {rb.Length} rows is out of range."); + } - List arrays = BuildArrays(message.Version, Schema, bodyByteBuffer, rb); - LastBatchCustomMetadata = ReadMessageCustomMetadata(message); - return new RecordBatch(Schema, memoryOwner, arrays, (int)rb.Length); - default: - // NOTE: Skip unsupported message type - Debug.WriteLine($"Skipping unsupported message type '{message.HeaderType}'"); - break; - } + List arrays = BuildArrays(message.Version, Schema, bodyByteBuffer, rb); + LastBatchCustomMetadata = ReadMessageCustomMetadata(message); + RecordBatch batch = new RecordBatch(Schema, memoryOwner, arrays, (int)rb.Length); + bodyKept = true; + return batch; + default: + // NOTE: Skip unsupported message type + Debug.WriteLine($"Skipping unsupported message type '{message.HeaderType}'"); + break; + } - return null; + return null; + } + finally + { + // Release a body that no result refers to: one whose message has no use for it, + // or one that could not be read. + if (!bodyKept) + { + memoryOwner?.Dispose(); + } + } } private static IReadOnlyDictionary ReadMessageCustomMetadata(Flatbuf.Message message) diff --git a/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs index a2781028..6924d5bd 100644 --- a/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs @@ -95,9 +95,18 @@ protected async ValueTask ReadMessageAsync(CancellationToken cancell IMemoryOwner bodyBuffOwner = AllocateMessageBodyBuffer(bodyLength); Memory bodyBuff = bodyBuffOwner.Memory.Slice(0, bodyLength); - bytesRead = await BaseStream.ReadFullBufferAsync(bodyBuff, cancellationToken) - .ConfigureAwait(false); - EnsureFullRead(bodyBuff, bytesRead); + try + { + bytesRead = await BaseStream.ReadFullBufferAsync(bodyBuff, cancellationToken) + .ConfigureAwait(false); + EnsureFullRead(bodyBuff, bytesRead); + } + catch + { + // For example a truncated stream; nothing else owns the body yet. + bodyBuffOwner.Dispose(); + throw; + } Google.FlatBuffers.ByteBuffer bodybb = CreateByteBuffer(bodyBuff); result = CreateArrowObjectFromMessage(message, bodybb, bodyBuffOwner); @@ -146,8 +155,17 @@ protected ReadResult ReadMessage() IMemoryOwner bodyBuffOwner = AllocateMessageBodyBuffer(bodyLength); Memory bodyBuff = bodyBuffOwner.Memory.Slice(0, bodyLength); - bytesRead = BaseStream.ReadFullBuffer(bodyBuff); - EnsureFullRead(bodyBuff, bytesRead); + try + { + bytesRead = BaseStream.ReadFullBuffer(bodyBuff); + EnsureFullRead(bodyBuff, bytesRead); + } + catch + { + // For example a truncated stream; nothing else owns the body yet. + bodyBuffOwner.Dispose(); + throw; + } Google.FlatBuffers.ByteBuffer bodybb = CreateByteBuffer(bodyBuff); result = CreateArrowObjectFromMessage(message, bodybb, bodyBuffOwner); diff --git a/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs b/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs index f5418ab5..0a24293c 100644 --- a/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs +++ b/src/Apache.Arrow/Ipc/ArrowStreamWriter.cs @@ -103,6 +103,8 @@ public Buffer(ReadOnlyMemory buffer, int offset, IDisposable owner) _owner = owner; } public void Dispose() => _owner?.Dispose(); + + internal Buffer WithoutOwner() => new Buffer(DataBuffer, Offset, null); } private readonly List _fieldNodes; @@ -131,8 +133,30 @@ public ArrowRecordBatchFlatBufferBuilder( TotalLength = 0; } + /// + /// Releases the buffer at once it has been written, so that + /// temporary buffers are freed as early as possible. + /// + public void ReleaseBuffer(int index) + { + Buffer buffer = _buffers[index]; + _buffers[index] = buffer.WithoutOwner(); + buffer.Dispose(); + } + + /// + /// Releases every buffer not yet released, along with arrays whose buffers they refer + /// to. Writing releases buffers as it goes; this also covers a write that fails partway + /// through, which would otherwise leak the rest (permanently, with a caller-owned + /// allocator). + /// public void Dispose() { + for (int i = 0; i < _buffers.Count; i++) + { + ReleaseBuffer(i); + } + if (_deferredDisposals == null) { return; @@ -888,7 +912,7 @@ private protected void WriteRecordBatchInternal(RecordBatch recordBatch, IReadOn long metadataLength = WriteMessage(Flatbuf.MessageHeader.RecordBatch, recordBatchOffset, recordBatchBuilder.TotalLength, customMetadataVectorOffset); - long bufferLength = WriteBufferData(recordBatchBuilder.Buffers); + long bufferLength = WriteBufferData(recordBatchBuilder); // The buffers just written are views of recordBatch's memory, so it must stay // reachable until they have been copied out. Otherwise, once its last other use above @@ -947,7 +971,7 @@ private protected async Task WriteRecordBatchInternalAsync(RecordBatch recordBat customMetadataVectorOffset, cancellationToken).ConfigureAwait(false); - long bufferLength = await WriteBufferDataAsync(recordBatchBuilder.Buffers, cancellationToken).ConfigureAwait(false); + long bufferLength = await WriteBufferDataAsync(recordBatchBuilder, cancellationToken).ConfigureAwait(false); // The buffers just written are views of recordBatch's memory, so it must stay // reachable until they have been copied out. Otherwise, once its last other use above @@ -958,24 +982,29 @@ private protected async Task WriteRecordBatchInternalAsync(RecordBatch recordBat FinishedWritingRecordBatch(bufferLength, metadataLength); } - private long WriteBufferData(IReadOnlyList buffers) + private long WriteBufferData(ArrowRecordBatchFlatBufferBuilder builder) { + IReadOnlyList buffers = builder.Buffers; long bodyLength = 0; for (int i = 0; i < buffers.Count; i++) { - using var buffer = buffers[i]; // Dispose the buffer after writing - ReadOnlyMemory dataBuffer = buffer.DataBuffer; - if (dataBuffer.IsEmpty) - continue; - BaseStream.Write(dataBuffer); - int paddedLength = checked((int)BitUtility.RoundUpToMultipleOf8(dataBuffer.Length)); - int padding = paddedLength - dataBuffer.Length; - if (padding > 0) + ReadOnlyMemory dataBuffer = buffers[i].DataBuffer; + if (!dataBuffer.IsEmpty) { - WritePadding(padding); + BaseStream.Write(dataBuffer); + int paddedLength = checked((int)BitUtility.RoundUpToMultipleOf8(dataBuffer.Length)); + int padding = paddedLength - dataBuffer.Length; + if (padding > 0) + { + WritePadding(padding); + } + bodyLength += paddedLength; } - bodyLength += paddedLength; + + // Release the buffer after writing. If a write throws, the builder's Dispose + // releases the buffers not reached. + builder.ReleaseBuffer(i); } // Write padding so the record batch message body length is a multiple of 8 bytes @@ -987,27 +1016,31 @@ private long WriteBufferData(IReadOnlyList WriteBufferDataAsync(IReadOnlyList buffers, CancellationToken cancellationToken = default) + private async ValueTask WriteBufferDataAsync(ArrowRecordBatchFlatBufferBuilder builder, CancellationToken cancellationToken = default) { + IReadOnlyList buffers = builder.Buffers; long bodyLength = 0; for (int i = 0; i < buffers.Count; i++) { - using var buffer = buffers[i]; // Dispose the buffer after writing - ReadOnlyMemory dataBuffer = buffer.DataBuffer; - if (dataBuffer.IsEmpty) - continue; + ReadOnlyMemory dataBuffer = buffers[i].DataBuffer; + if (!dataBuffer.IsEmpty) + { + await BaseStream.WriteAsync(dataBuffer, cancellationToken).ConfigureAwait(false); - await BaseStream.WriteAsync(dataBuffer, cancellationToken).ConfigureAwait(false); + int paddedLength = checked((int)BitUtility.RoundUpToMultipleOf8(dataBuffer.Length)); + int padding = paddedLength - dataBuffer.Length; + if (padding > 0) + { + await WritePaddingAsync(padding).ConfigureAwait(false); + } - int paddedLength = checked((int)BitUtility.RoundUpToMultipleOf8(dataBuffer.Length)); - int padding = paddedLength - dataBuffer.Length; - if (padding > 0) - { - await WritePaddingAsync(padding).ConfigureAwait(false); + bodyLength += paddedLength; } - bodyLength += paddedLength; + // Release the buffer after writing. If a write throws, the builder's Dispose + // releases the buffers not reached. + builder.ReleaseBuffer(i); } // Write padding so the record batch message body length is a multiple of 8 bytes @@ -1035,7 +1068,21 @@ private Tuple Pre : null; var recordBatchBuilder = new ArrowRecordBatchFlatBufferBuilder(compressionCodec, _allocator, _fallbackCompressionStream); + try + { + return PrepareWritingRecordBatch(recordBatchBuilder, fields, arrays); + } + catch + { + // The caller only takes ownership of the builder once this returns. + recordBatchBuilder.Dispose(); + throw; + } + } + private Tuple PrepareWritingRecordBatch( + ArrowRecordBatchFlatBufferBuilder recordBatchBuilder, IReadOnlyList fields, IReadOnlyList arrays) + { // Visit all arrays recursively for (int i = 0; i < fields.Count; i++) { @@ -1104,7 +1151,7 @@ private protected void WriteDictionary(long id, IArrowType valueType, IArrowArra long metadataLength = WriteMessage(Flatbuf.MessageHeader.DictionaryBatch, dictionaryBatchOffset, recordBatchBuilder.TotalLength); - long bufferLength = WriteBufferData(recordBatchBuilder.Buffers); + long bufferLength = WriteBufferData(recordBatchBuilder); FinishedWritingDictionary(bufferLength, metadataLength); } @@ -1130,7 +1177,7 @@ private protected async Task WriteDictionaryAsync(long id, IArrowType valueType, long metadataLength = await WriteMessageAsync(Flatbuf.MessageHeader.DictionaryBatch, dictionaryBatchOffset, recordBatchBuilder.TotalLength, default, cancellationToken).ConfigureAwait(false); - long bufferLength = await WriteBufferDataAsync(recordBatchBuilder.Buffers, cancellationToken).ConfigureAwait(false); + long bufferLength = await WriteBufferDataAsync(recordBatchBuilder, cancellationToken).ConfigureAwait(false); FinishedWritingDictionary(bufferLength, metadataLength); } diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index 08c069f9..0fbad8b6 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -20,6 +20,7 @@ using System.Runtime.CompilerServices; using System.Runtime.InteropServices; using System.Threading; +using System.Threading.Tasks; using Apache.Arrow.Ipc; using Apache.Arrow.Memory; using Apache.Arrow.Types; @@ -292,6 +293,103 @@ public void InMemoryReaderUsesContextAllocatorForDecompression() }); } + [Theory] + [InlineData(false)] + [InlineData(true)] + public void FailedWritesReleaseTheWritersTemporaryBuffers(bool async) + { + // A sliced string column makes the writer re-base its offsets, and compression gives + // it an output buffer per array buffer, so the writer holds several temporary buffers. + StringArray strings = new StringArray.Builder().Append("a").Append("bb").Append("ccc").Append("dddd").Build(); + using RecordBatch batch = new RecordBatch.Builder() + .Append("s", false, (StringArray)strings.Slice(1, 3)) + .Append("i", false, col => col.Int32(b => b.Append(1).Append(2).Append(3))) + .Build(); + IpcOptions options = new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame }; + + // Count the writes a successful run makes, then fail at each of them in turn. + FailingStream counter = new FailingStream(failOnWrite: int.MaxValue); + Write(counter, new TrackingAllocator()); + Assert.True(counter.Writes > 3); + + for (int failOn = 1; failOn <= counter.Writes; failOn++) + { + int failure = failOn; + Run(allocator => + { + FailingStream stream = new FailingStream(failure); + Assert.ThrowsAny(() => Write(stream, allocator)); + }, expectAllocations: false); + } + + void Write(Stream stream, TrackingAllocator allocator) + { + ArrowContext context = new ArrowContext(allocator, new PassThroughCodecFactory()); + using ArrowStreamWriter writer = new ArrowStreamWriter(context, stream, batch.Schema, leaveOpen: true, options); + if (async) + { + writer.WriteRecordBatchAsync(batch).GetAwaiter().GetResult(); + } + else + { + writer.WriteRecordBatch(batch); + } + } + } + + [Fact] + public void TruncatedStreamReleasesTheMessageBody() + { + byte[] data = WriteBatch(compress: false); + byte[] truncated = new byte[data.Length - 16]; + System.Array.Copy(data, truncated, truncated.Length); + + Run(allocator => + { + // A stream that is not a MemoryStream makes the reader allocate the body. + using Stream stream = new BufferedStream(new MemoryStream(truncated)); + using ArrowStreamReader reader = new ArrowStreamReader(new ArrowContext(allocator), stream); + Assert.ThrowsAny(() => reader.ReadNextRecordBatch()); + }); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void FailedParsingReleasesTheMessageBody(bool fromMemoryStream) + { + byte[] data = WriteBatch(compress: true); + + // Decompression fails while the message is being parsed, after the body is allocated. + Run(allocator => + { + ArrowContext context = new ArrowContext(allocator, new FailingCodecFactory()); + using Stream stream = fromMemoryStream + ? new MemoryStream(data) + : new BufferedStream(new MemoryStream(data)); + using ArrowStreamReader reader = new ArrowStreamReader(context, stream); + Assert.Throws(() => reader.ReadNextRecordBatch()); + }); + } + + private static byte[] WriteBatch(bool compress) + { + using RecordBatch batch = new RecordBatch.Builder() + .Append("i", false, col => col.Int32(b => b.Append(1).Append(2).Append(3))) + .Build(); + IpcOptions options = compress + ? new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame, CompressionCodecFactory = new PassThroughCodecFactory() } + : null; + + MemoryStream stream = new MemoryStream(); + using (ArrowStreamWriter writer = new ArrowStreamWriter(stream, batch.Schema, leaveOpen: true, options)) + { + writer.WriteRecordBatch(batch); + writer.WriteEnd(); + } + return stream.ToArray(); + } + [Fact] public void FailedDecompressionReleasesItsOutputBuffer() { @@ -495,6 +593,56 @@ public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, CreateCodec(compressionCodecType); } + /// + /// A writable stream whose n-th write throws, once, and which counts the writes it + /// receives. Writes before and after the failure succeed. + /// + private sealed class FailingStream : Stream + { + private readonly int _failOnWrite; + private readonly MemoryStream _inner = new MemoryStream(); + + public FailingStream(int failOnWrite) => _failOnWrite = failOnWrite; + + public int Writes { get; private set; } + + public override bool CanRead => false; + public override bool CanSeek => false; + public override bool CanWrite => true; + public override long Length => _inner.Length; + public override long Position { get => _inner.Position; set => throw new NotSupportedException(); } + + public override void Write(byte[] buffer, int offset, int count) + { + if (++Writes == _failOnWrite) + { + throw new IOException("Simulated write failure."); + } + _inner.Write(buffer, offset, count); + } + + public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) + { + Write(buffer, offset, count); + return Task.CompletedTask; + } + +#if NET5_0_OR_GREATER + public override void Write(ReadOnlySpan buffer) => Write(buffer.ToArray(), 0, buffer.Length); + + public override ValueTask WriteAsync(ReadOnlyMemory buffer, CancellationToken cancellationToken = default) + { + Write(buffer.ToArray(), 0, buffer.Length); + return default; + } +#endif + + public override void Flush() { } + public override int Read(byte[] buffer, int offset, int count) => throw new NotSupportedException(); + public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException(); + public override void SetLength(long value) => throw new NotSupportedException(); + } + private sealed class FailingCodecFactory : ICompressionCodecFactory { public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) => new FailingCodec(); diff --git a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs index 49a028bc..46c04e60 100644 --- a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs +++ b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs @@ -127,6 +127,23 @@ public void AppendingTheBitmapBuildersOwnSpanSurvivesGrowth() } } + [Fact] + public void AppendingOwnBitsBeyondTheLengthUsesTheOriginalBits() + { + // Appending bit by bit (the length is not a whole number of bytes) writes into the + // byte the source is read from. The source must be read as it was before the append. + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(64); + builder.Append(true).Append(false).Append(true).Append(true); + byte[] before = builder.Span.Slice(0, 1).ToArray(); + + builder.Append(builder.Span.Slice(0, 1), 8); + + for (int i = 0; i < 8; i++) + { + Assert.Equal(BitUtility.GetBit(before, i), BitUtility.GetBit(builder.Span, 4 + i)); + } + } + [Fact] public void AppendingASpanCapturedBeforeBuildSurvivesTheHandOver() { From 35c2e41dc45ac0d9744245e22afaf40ef434c3de Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 17:01:47 -0800 Subject: [PATCH 11/15] Reference-count dictionary batch bodies in the IPC readers A dictionary's arrays are views into its message body, but nothing owned the body: it was reclaimed only by finalization, so with a caller-owned allocator every dictionary message leaked its body permanently. It cannot simply be released when the dictionary is replaced or the reader is disposed, because every record batch that uses the dictionary shares it and can outlive both. - Dictionary buffers now count references to the body (a MessageBody hands out sliced SharedMemoryHandles), including buffers stored uncompressed in a compressed stream. - Each record batch retains its own reference to the dictionary it uses, so disposing a batch releases only that batch's references. - The reader owns the dictionaries in its memo: it releases one when it is replaced, a delta and the dictionary it extends once they are concatenated, and all of them when it is disposed. - Arrays already built are released if building a batch or dictionary fails. With the default allocator the body is now released as soon as the reader and every batch using it are disposed, rather than at finalization. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ArrowBuffer.cs | 2 +- .../Ipc/ArrowReaderImplementation.cs | 120 +++++++++---- .../Ipc/ArrowStreamReaderImplementation.cs | 2 + .../Ipc/DecompressingBufferCreator.cs | 10 +- src/Apache.Arrow/Ipc/DictionaryMemo.cs | 44 +++++ src/Apache.Arrow/Ipc/MessageBody.cs | 70 ++++++++ src/Apache.Arrow/Ipc/NoOpBufferCreator.cs | 14 +- src/Apache.Arrow/Memory/SharedMemoryHandle.cs | 34 +++- src/Apache.Arrow/Memory/SharedMemoryOwner.cs | 9 +- .../BuilderDisposalTests.cs | 169 ++++++++++++++++++ 10 files changed, 429 insertions(+), 45 deletions(-) create mode 100644 src/Apache.Arrow/Ipc/MessageBody.cs diff --git a/src/Apache.Arrow/ArrowBuffer.cs b/src/Apache.Arrow/ArrowBuffer.cs index 83e599bd..85ce90ab 100644 --- a/src/Apache.Arrow/ArrowBuffer.cs +++ b/src/Apache.Arrow/ArrowBuffer.cs @@ -51,7 +51,7 @@ internal ArrowBuffer(IMemoryOwner memoryOwner, AllocationLifetime lifetime _memory = Memory.Empty; } - private ArrowBuffer(SharedMemoryHandle handle) + internal ArrowBuffer(SharedMemoryHandle handle) { _handle = handle; _memory = Memory.Empty; diff --git a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs index fca07698..39770d5f 100644 --- a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs @@ -78,6 +78,11 @@ public void Dispose() protected virtual void Dispose(bool disposing) { + if (disposing) + { + // Batches already read hold their own references to the dictionaries they use. + _dictionaryMemo?.DisposeOwnedDictionaries(); + } } public abstract ValueTask ReadSchemaAsync(CancellationToken cancellationToken); @@ -155,12 +160,9 @@ protected RecordBatch CreateArrowObjectFromMessage( break; case Flatbuf.MessageHeader.DictionaryBatch: Flatbuf.DictionaryBatch dictionaryBatch = message.Header().Value; - ReadDictionaryBatch(message.Version, dictionaryBatch, bodyByteBuffer, memoryOwner); - - // The dictionary's arrays refer to the body, so it must stay alive. Nothing - // owns it yet: it is reclaimed only by finalization, which leaks it with a - // caller-owned allocator. + // Takes ownership of the body, including on failure. bodyKept = true; + ReadDictionaryBatch(message.Version, dictionaryBatch, bodyByteBuffer, memoryOwner); break; case Flatbuf.MessageHeader.RecordBatch: Flatbuf.RecordBatch rb = message.Header().Value; @@ -219,31 +221,62 @@ private void ReadDictionaryBatch( ByteBuffer bodyByteBuffer, IMemoryOwner memoryOwner) { - long id = dictionaryBatch.Id; - IArrowType valueType = DictionaryMemo.GetDictionaryType(id); - Flatbuf.RecordBatch? recordBatch = dictionaryBatch.Data; - - if (!recordBatch.HasValue) + // The dictionary is shared by every batch that uses it and can outlive both the reader + // and the dictionaries that replace it, so its buffers count references to the body. + MessageBody body = memoryOwner == null ? null : new MessageBody(memoryOwner, _allocator.Lifetime); + IList arrays = null; + try { - throw new InvalidDataException("Dictionary must contain RecordBatch"); - } + long id = dictionaryBatch.Id; + IArrowType valueType = DictionaryMemo.GetDictionaryType(id); + Flatbuf.RecordBatch? recordBatch = dictionaryBatch.Data; - Field valueField = new Field("dummy", valueType, true); - var schema = new Schema(new[] { valueField }, default); - IList arrays = BuildArrays(version, schema, bodyByteBuffer, recordBatch.Value); + if (!recordBatch.HasValue) + { + throw new InvalidDataException("Dictionary must contain RecordBatch"); + } + + Field valueField = new Field("dummy", valueType, true); + var schema = new Schema(new[] { valueField }, default); + arrays = BuildArrays(version, schema, bodyByteBuffer, recordBatch.Value, body); + + if (arrays.Count != 1) + { + throw new InvalidDataException("Dictionary record batch must contain only one field"); + } - if (arrays.Count != 1) + // The memo takes ownership of the array, including on failure. + IArrowArray dictionary = arrays[0]; + arrays = null; + if (dictionaryBatch.IsDelta) + { + DictionaryMemo.AddOwnedDeltaDictionary(id, dictionary, _requestedAllocator); + } + else + { + DictionaryMemo.ReplaceOwnedDictionary(id, dictionary); + } + } + catch { - throw new InvalidDataException("Dictionary record batch must contain only one field"); + DisposeAll(arrays); + throw; } - - if (dictionaryBatch.IsDelta) + finally { - DictionaryMemo.AddDeltaDictionary(id, arrays[0], _requestedAllocator); + // The dictionary's buffers hold their own references to the body. + body?.Release(); } - else + } + + private static void DisposeAll(IList arrays) + { + if (arrays != null) { - DictionaryMemo.AddOrReplaceDictionary(id, arrays[0]); + foreach (IArrowArray array in arrays) + { + array.Dispose(); + } } } @@ -251,7 +284,8 @@ private List BuildArrays( MetadataVersion version, Schema schema, ByteBuffer messageBuffer, - Flatbuf.RecordBatch recordBatchMessage) + Flatbuf.RecordBatch recordBatchMessage, + MessageBody body = null) { var arrays = new List(recordBatchMessage.NodesLength); @@ -260,27 +294,39 @@ private List BuildArrays( return arrays; } - using var bufferCreator = GetBufferCreator(recordBatchMessage.Compression); - var recordBatchEnumerator = new RecordBatchEnumerator(in recordBatchMessage); - int schemaFieldIndex = 0; - do + try { - Field field = schema.GetFieldByIndex(schemaFieldIndex++); - Flatbuf.FieldNode fieldNode = recordBatchEnumerator.CurrentNode; + using var bufferCreator = GetBufferCreator(recordBatchMessage.Compression, body); + var recordBatchEnumerator = new RecordBatchEnumerator(in recordBatchMessage); + int schemaFieldIndex = 0; + do + { + Field field = schema.GetFieldByIndex(schemaFieldIndex++); + Flatbuf.FieldNode fieldNode = recordBatchEnumerator.CurrentNode; - ArrayData arrayData = LoadField(version, ref recordBatchEnumerator, field, in fieldNode, messageBuffer, bufferCreator); + ArrayData arrayData = LoadField(version, ref recordBatchEnumerator, field, in fieldNode, messageBuffer, bufferCreator); - arrays.Add(ArrowArrayFactory.BuildArray(arrayData)); - } while (recordBatchEnumerator.MoveNextNode()); + arrays.Add(ArrowArrayFactory.BuildArray(arrayData)); + } while (recordBatchEnumerator.MoveNextNode()); + } + catch + { + // Arrays already built can hold decompressed buffers and dictionary references. + DisposeAll(arrays); + throw; + } return arrays; } - private IBufferCreator GetBufferCreator(BodyCompression? compression) + /// + /// The shared message body, when buffers that view it must count references to it. + /// + private IBufferCreator GetBufferCreator(BodyCompression? compression, MessageBody body) { if (!compression.HasValue) { - return NoOpBufferCreator.Instance; + return body == null ? NoOpBufferCreator.Instance : new NoOpBufferCreator(body); } var method = compression.Value.Method; @@ -301,7 +347,7 @@ private IBufferCreator GetBufferCreator(BodyCompression? compression) Apache.Arrow.Flatbuf.CompressionType.ZSTD => _compressionCodecFactory.CreateCodec(CompressionCodecType.Zstd), _ => throw new NotImplementedException($"Compression codec {codec} is not supported") }; - return new DecompressingBufferCreator(decompressor, _allocator); + return new DecompressingBufferCreator(decompressor, _allocator, body); } private ArrayData LoadField( @@ -397,7 +443,9 @@ private ArrayData LoadField( dictionary = DictionaryMemo.GetDictionary(id); } - return new ArrayData(field.DataType, fieldLength, fieldNullCount, 0, arrowBuff, children, dictionary?.Data); + // Each batch holds its own reference to the dictionary, which the reader releases when + // it is replaced or the reader is disposed. + return new ArrayData(field.DataType, fieldLength, fieldNullCount, 0, arrowBuff, children, dictionary?.Data.Retain()); } private ArrayData[] GetChildren( diff --git a/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs index 6924d5bd..8f178b09 100644 --- a/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs @@ -45,6 +45,8 @@ protected override void Dispose(bool disposing) { BaseStream.Dispose(); } + + base.Dispose(disposing); } public override ValueTask ReadNextRecordBatchAsync(CancellationToken cancellationToken) diff --git a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs index 0e416ba5..024c118b 100644 --- a/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs +++ b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs @@ -26,11 +26,17 @@ internal sealed class DecompressingBufferCreator : IBufferCreator { private readonly ICompressionCodec _compressionCodec; private readonly MemoryAllocator _allocator; + private readonly MessageBody _body; - public DecompressingBufferCreator(ICompressionCodec compressionCodec, MemoryAllocator allocator) + /// + /// The shared message body the buffers lie within, or null to view uncompressed buffers + /// directly. + /// + public DecompressingBufferCreator(ICompressionCodec compressionCodec, MemoryAllocator allocator, MessageBody body = null) { _compressionCodec = compressionCodec; _allocator = allocator; + _body = body; } public ArrowBuffer CreateBuffer(ReadOnlyMemory source) @@ -48,7 +54,7 @@ public ArrowBuffer CreateBuffer(ReadOnlyMemory source) if (uncompressedLength == -1) { // The buffer is not actually compressed - return new ArrowBuffer(source.Slice(8)); + return _body != null ? _body.CreateBuffer(source.Slice(8)) : new ArrowBuffer(source.Slice(8)); } var outputData = _allocator.Allocate(Convert.ToInt32(uncompressedLength)); diff --git a/src/Apache.Arrow/Ipc/DictionaryMemo.cs b/src/Apache.Arrow/Ipc/DictionaryMemo.cs index 0e151b69..0432b126 100644 --- a/src/Apache.Arrow/Ipc/DictionaryMemo.cs +++ b/src/Apache.Arrow/Ipc/DictionaryMemo.cs @@ -107,6 +107,50 @@ public void AddOrReplaceDictionary(long id, IArrowArray dictionary) _idToDictionary[id] = dictionary; } + /// + /// Adds or replaces a dictionary the memo owns, releasing the one it replaces. Readers own + /// their dictionaries; each record batch retains its own reference. + /// + public void ReplaceOwnedDictionary(long id, IArrowArray dictionary) + { + _idToDictionary.TryGetValue(id, out IArrowArray previous); + _idToDictionary[id] = dictionary; + if (!ReferenceEquals(previous, dictionary)) + { + previous?.Dispose(); + } + } + + /// + /// Appends a delta to a dictionary the memo owns, releasing both the delta and the + /// dictionary it replaces. + /// + public void AddOwnedDeltaDictionary(long id, IArrowArray deltaDictionary, MemoryAllocator allocator = default) + { + try + { + IArrowArray currentDictionary = _idToDictionary[id]; + IArrowArray dictionary = ArrowArrayConcatenator.Concatenate(new List { currentDictionary, deltaDictionary }, allocator); + ReplaceOwnedDictionary(id, dictionary); + } + finally + { + deltaDictionary.Dispose(); + } + } + + /// + /// Releases the dictionaries the memo owns. + /// + public void DisposeOwnedDictionaries() + { + foreach (IArrowArray dictionary in _idToDictionary.Values) + { + dictionary.Dispose(); + } + _idToDictionary.Clear(); + } + public void AddDeltaDictionary(long id, IArrowArray deltaDictionary, MemoryAllocator allocator = default) { IArrowArray currentDictionary = _idToDictionary[id]; diff --git a/src/Apache.Arrow/Ipc/MessageBody.cs b/src/Apache.Arrow/Ipc/MessageBody.cs new file mode 100644 index 00000000..7e2e81c3 --- /dev/null +++ b/src/Apache.Arrow/Ipc/MessageBody.cs @@ -0,0 +1,70 @@ +// 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.Buffers; +using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; +using Apache.Arrow.Memory; + +namespace Apache.Arrow.Ipc +{ + /// + /// The body of an IPC message whose buffers are shared by reference counting, so that the + /// body is released once the reader and every buffer that refers to it have released it. + /// Dictionary batches need this: a dictionary is shared by every record batch that uses it, + /// and can outlive the reader and later dictionaries that replace it. + /// + internal sealed class MessageBody + { + private readonly SharedMemoryOwner _owner; + + /// The body's memory, of which this takes ownership. + /// The lifetime of the allocator came from. + public MessageBody(IMemoryOwner owner, AllocationLifetime lifetime) + { + _owner = new SharedMemoryOwner(owner, finalizeWhenUnreachable: lifetime == AllocationLifetime.Finalized); + } + + /// + /// Creates a buffer over , which must lie within the body, that + /// holds its own reference to the body. + /// + public ArrowBuffer CreateBuffer(ReadOnlyMemory source) + { + if (source.IsEmpty) + { + return ArrowBuffer.Empty; + } + + Memory body = _owner.Memory; + long offset = Unsafe.ByteOffset( + ref MemoryMarshal.GetReference(body.Span), + ref MemoryMarshal.GetReference(source.Span)).ToInt64(); + if (offset < 0 || offset > body.Length - source.Length) + { + throw new InvalidOperationException("The buffer does not lie within the message body."); + } + + return new ArrowBuffer(_owner.Retain((int)offset, source.Length)); + } + + /// + /// Releases the reference held since construction. Buffers created from the body keep + /// it alive until they are disposed too. + /// + public void Release() => _owner.Release(); + } +} diff --git a/src/Apache.Arrow/Ipc/NoOpBufferCreator.cs b/src/Apache.Arrow/Ipc/NoOpBufferCreator.cs index 13c22c7f..62a8e20c 100644 --- a/src/Apache.Arrow/Ipc/NoOpBufferCreator.cs +++ b/src/Apache.Arrow/Ipc/NoOpBufferCreator.cs @@ -25,11 +25,21 @@ internal sealed class NoOpBufferCreator : IBufferCreator /// /// Singleton instance, used as this class doesn't need to be disposed and has no state /// - public static readonly NoOpBufferCreator Instance = new NoOpBufferCreator(); + public static readonly NoOpBufferCreator Instance = new NoOpBufferCreator(null); + + private readonly MessageBody _body; + + /// + /// The shared message body the buffers lie within, or null to create plain views. + /// + public NoOpBufferCreator(MessageBody body) + { + _body = body; + } public ArrowBuffer CreateBuffer(ReadOnlyMemory source) { - return new ArrowBuffer(source); + return _body != null ? _body.CreateBuffer(source) : new ArrowBuffer(source); } public void Dispose() diff --git a/src/Apache.Arrow/Memory/SharedMemoryHandle.cs b/src/Apache.Arrow/Memory/SharedMemoryHandle.cs index c5a146d5..a7eaa172 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryHandle.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryHandle.cs @@ -21,10 +21,23 @@ namespace Apache.Arrow.Memory internal sealed class SharedMemoryHandle : IMemoryOwner { private SharedMemoryOwner _owner; + private readonly Memory _memory; + private readonly int _start; public SharedMemoryHandle(SharedMemoryOwner owner) + : this(owner, 0, owner?.Memory.Length ?? 0) + { + } + + /// + /// Creates a handle to a slice of the owner's memory. The handle holds a reference to all + /// of it. + /// + public SharedMemoryHandle(SharedMemoryOwner owner, int start, int length) { _owner = owner ?? throw new ArgumentNullException(nameof(owner)); + _memory = owner.Memory.Slice(start, length); + _start = start; if (!owner.FinalizeWhenUnreachable) { @@ -34,13 +47,30 @@ public SharedMemoryHandle(SharedMemoryOwner owner) } } - public Memory Memory => _owner.Memory; + public Memory Memory + { + get + { + if (_owner == null) + { + ThrowDisposed(); + } + return _memory; + } + } public SharedMemoryHandle Retain() { - return _owner.Retain(); + if (_owner == null) + { + ThrowDisposed(); + } + + return _owner.Retain(_start, _memory.Length); } + private static void ThrowDisposed() => throw new ObjectDisposedException(nameof(SharedMemoryHandle)); + public void Dispose() { Release(); diff --git a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs index 718a5ba8..06aa64d6 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs @@ -45,7 +45,12 @@ public SharedMemoryOwner(IMemoryOwner inner, bool finalizeWhenUnreachable) /// public bool FinalizeWhenUnreachable { get; } - public SharedMemoryHandle Retain() + public SharedMemoryHandle Retain() => Retain(0, _memory.Length); + + /// + /// Adds a reference, returning a handle to the given slice of the memory. + /// + public SharedMemoryHandle Retain(int start, int length) { while (true) { @@ -57,7 +62,7 @@ public SharedMemoryHandle Retain() if (Interlocked.CompareExchange(ref _refCount, current + 1, current) == current) { - return new SharedMemoryHandle(this); + return new SharedMemoryHandle(this, start, length); } } } diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index 0fbad8b6..d5bbd121 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -390,6 +390,143 @@ private static byte[] WriteBatch(bool compress) return stream.ToArray(); } + [Theory] + [InlineData(false, Compression.None)] + [InlineData(true, Compression.None)] + [InlineData(false, Compression.Compressed)] + [InlineData(false, Compression.StoredUncompressed)] + [InlineData(true, Compression.StoredUncompressed)] + public void ReadingDictionaryBatchesReleasesTheirBodies(bool fromMemoryStream, Compression compression) + { + byte[] data = Concat(WriteDictionaryStream(compression, "x", "y"), WriteDictionaryStream(compression, "p", "q")); + + Run(allocator => + { + List batches = ReadAll(data, Context(allocator, compression), fromMemoryStream, out ArrowStreamReader reader); + reader.Dispose(); + Assert.Equal(2, batches.Count); + batches.ForEach(b => b.Dispose()); + }); + } + + [Theory] + [InlineData(false, Compression.None)] + [InlineData(true, Compression.None)] + [InlineData(false, Compression.StoredUncompressed)] + public void BatchesKeepTheirDictionaryAfterItIsReplacedAndTheReaderIsDisposed(bool fromMemoryStream, Compression compression) + { + // The second stream's dictionary replaces the first's (both have id 0), and the + // reader is disposed while both batches are still in use. + byte[] data = Concat(WriteDictionaryStream(compression, "x", "y"), WriteDictionaryStream(compression, "p", "q")); + PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + + List batches = ReadAll(data, Context(allocator, compression), fromMemoryStream, out ArrowStreamReader reader); + reader.Dispose(); + + // Churn the pool, so that released memory would be reused and overwritten. + for (int i = 0; i < 4; i++) + { + using StringArray filler = new StringArray.Builder(allocator).Append("zzzzzzzzzzzzzzzz").Build(); + } + + AssertDictionaryValues(batches[0], "x", "y"); + AssertDictionaryValues(batches[1], "p", "q"); + + // Each batch holds its own reference: disposing one leaves the other intact. + batches[0].Dispose(); + AssertDictionaryValues(batches[1], "p", "q"); + batches[1].Dispose(); + } + + public enum Compression + { + None, + Compressed, + + /// Compressed, but every buffer is stored uncompressed (length -1). + StoredUncompressed, + } + + private static ICompressionCodecFactory Codecs(Compression compression) => compression switch + { + Compression.Compressed => new PassThroughCodecFactory(), + Compression.StoredUncompressed => new IncompressibleCodecFactory(), + _ => null, + }; + + private static ArrowContext Context(MemoryAllocator allocator, Compression compression) => + compression == Compression.None ? new ArrowContext(allocator) : new ArrowContext(allocator, Codecs(compression)); + + private static void AssertDictionaryValues(RecordBatch batch, params string[] expected) + { + DictionaryArray column = (DictionaryArray)batch.Column(0); + StringArray dictionary = (StringArray)column.Dictionary; + Assert.Equal(expected.Length, dictionary.Length); + for (int i = 0; i < expected.Length; i++) + { + Assert.Equal(expected[i], dictionary.GetString(i)); + } + Assert.Equal(1, ((Int32Array)column.Indices).GetValue(1)); + } + + private static List ReadAll(byte[] data, ArrowContext context, bool fromMemoryStream, out ArrowStreamReader reader) + { + // A stream that is not a MemoryStream makes the reader read through a different path. + Stream stream = fromMemoryStream + ? new MemoryStream(data) + : new BufferedStream(new MemoryStream(data)); + reader = new ArrowStreamReader(context, stream); + + List batches = new List(); + RecordBatch batch; + while ((batch = reader.ReadNextRecordBatch()) != null) + { + batches.Add(batch); + } + return batches; + } + + /// + /// Writes a stream holding one batch with a dictionary-encoded column, without the + /// end-of-stream marker, so that streams can be concatenated. Later schema messages are + /// ignored by the reader, and each stream's dictionary has id 0, so each replaces the last. + /// + private static byte[] WriteDictionaryStream(Compression compression, params string[] values) + { + StringArray.Builder dictionaryBuilder = new StringArray.Builder(); + foreach (string value in values) + { + dictionaryBuilder.Append(value); + } + DictionaryType type = new DictionaryType(Int32Type.Default, StringType.Default, false); + DictionaryArray column = new DictionaryArray( + type, + new Int32Array.Builder().Append(0).Append(1).Append(0).Build(), + dictionaryBuilder.Build()); + Schema schema = new Schema.Builder().Field(f => f.Name("d").DataType(type).Nullable(false)).Build(); + using RecordBatch batch = new RecordBatch(schema, new IArrowArray[] { column }, column.Length); + + MemoryStream stream = new MemoryStream(); + IpcOptions options = compression == Compression.None + ? null + : new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame, CompressionCodecFactory = Codecs(compression) }; + using (ArrowStreamWriter writer = new ArrowStreamWriter(stream, schema, leaveOpen: true, options)) + { + writer.WriteRecordBatch(batch); + } + return stream.ToArray(); + } + + private static byte[] Concat(params byte[][] parts) + { + MemoryStream result = new MemoryStream(); + foreach (byte[] part in parts) + { + result.Write(part, 0, part.Length); + } + return result.ToArray(); + } + [Fact] public void FailedDecompressionReleasesItsOutputBuffer() { @@ -668,6 +805,38 @@ public void Dispose() } } + /// + /// A codec that never manages to compress, so the writer stores every buffer uncompressed + /// and the reader views those buffers in the message body. + /// + private sealed class IncompressibleCodecFactory : ICompressionCodecFactory + { + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) => new IncompressibleCodec(); + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, int? compressionLevel) => + CreateCodec(compressionCodecType); + + private sealed class IncompressibleCodec : ITryCompressionCodec + { + // Only empty buffers, which the writer records as compressed, reach this. + public int Decompress(ReadOnlyMemory source, Memory destination) => + source.IsEmpty ? 0 : throw new InvalidOperationException("Nothing should have been compressed."); + + public void Compress(ReadOnlyMemory source, Stream destination) => + throw new NotSupportedException(); + + public bool TryCompress(ReadOnlyMemory source, Memory destination, out int bytesWritten) + { + bytesWritten = 0; + return false; + } + + public void Dispose() + { + } + } + } + private sealed class PassThroughCodec : ITryCompressionCodec { public int Decompress(ReadOnlyMemory source, Memory destination) From 8ed88459aa787e6aa57db221d9ccd611db246073 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 17:20:34 -0800 Subject: [PATCH 12/15] Release a field's buffers when reading it fails partway If reading a field failed after some of its buffers or children were created (for example, a decompression failure on a later buffer), the reader dropped the partially built field, leaking its decompressed buffers and references to a shared message body. LoadField and GetChildren now release what they built before rethrowing. Also build the shredded variant's top-level validity bitmap with the supplied allocator, so the result is handed over rather than copied, and dispose the builder. Co-Authored-By: Claude Opus 5.5 --- .../Shredding/ShreddedVariantArrayBuilder.cs | 2 +- .../Ipc/ArrowReaderImplementation.cs | 55 +++++++++-- .../BuilderDisposalTests.cs | 98 +++++++++++++++++++ 3 files changed, 144 insertions(+), 11 deletions(-) diff --git a/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs b/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs index 8b8143d3..73ab24b5 100644 --- a/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs +++ b/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs @@ -56,7 +56,7 @@ public static VariantArray Build( // Top-level validity. Children of a null row are emitted as missing // (value and typed_value both null); metadata is still populated // because the metadata field is non-nullable. - ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(rowCount); + using ArrowBuffer.BitmapBuilder validity = new ArrowBuffer.BitmapBuilder(rowCount, allocator); int nullCount = 0; ShredResult[] childRows = null; for (int i = 0; i < rowCount; i++) diff --git a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs index 39770d5f..38933a0d 100644 --- a/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs +++ b/src/Apache.Arrow/Ipc/ArrowReaderImplementation.cs @@ -428,19 +428,34 @@ private ArrayData LoadField( } ArrowBuffer[] arrowBuff = new ArrowBuffer[buffers]; - for (int i = 0; i < buffers; i++) + ArrayData[] children = null; + IArrowArray dictionary = null; + try { - arrowBuff[i] = BuildArrowBuffer(bodyData, recordBatchEnumerator.CurrentBuffer, bufferCreator); - recordBatchEnumerator.MoveNextBuffer(); - } + for (int i = 0; i < buffers; i++) + { + arrowBuff[i] = BuildArrowBuffer(bodyData, recordBatchEnumerator.CurrentBuffer, bufferCreator); + recordBatchEnumerator.MoveNextBuffer(); + } - ArrayData[] children = GetChildren(version, ref recordBatchEnumerator, field, bodyData, bufferCreator); + children = GetChildren(version, ref recordBatchEnumerator, field, bodyData, bufferCreator); - IArrowArray dictionary = null; - if (storageType.TypeId == ArrowTypeId.Dictionary) + if (storageType.TypeId == ArrowTypeId.Dictionary) + { + long id = DictionaryMemo.GetId(field); + dictionary = DictionaryMemo.GetDictionary(id); + } + } + catch { - long id = DictionaryMemo.GetId(field); - dictionary = DictionaryMemo.GetDictionary(id); + // The buffers can be decompressed copies or references to a shared body. Entries + // not yet built are default buffers, which own nothing. + foreach (ArrowBuffer buffer in arrowBuff) + { + buffer.Dispose(); + } + DisposeAll(children); + throw; } // Each batch holds its own reference to the dictionary, which the reader releases when @@ -466,11 +481,31 @@ private ArrayData[] GetChildren( Flatbuf.FieldNode childFieldNode = recordBatchEnumerator.CurrentNode; Field childField = type.Fields[index]; - children[index] = LoadField(version, ref recordBatchEnumerator, childField, in childFieldNode, bodyData, bufferCreator); + try + { + children[index] = LoadField(version, ref recordBatchEnumerator, childField, in childFieldNode, bodyData, bufferCreator); + } + catch + { + // LoadField releases what it built for the failing child; release its siblings. + DisposeAll(children); + throw; + } } return children; } + private static void DisposeAll(ArrayData[] arrays) + { + if (arrays != null) + { + foreach (ArrayData array in arrays) + { + array?.Dispose(); + } + } + } + private ArrowBuffer BuildArrowBuffer(ByteBuffer bodyData, Flatbuf.Buffer buffer, IBufferCreator bufferCreator) { if (buffer.Length <= 0) diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index d5bbd121..c0b6b1a7 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -527,6 +527,61 @@ private static byte[] Concat(params byte[][] parts) return result.ToArray(); } + [Fact] + public void FailingPartwayThroughAFieldReleasesItsBuffers() + { + // Nulls give the columns a validity buffer as well as their data buffers, and the list + // column has a child, so failures land between a field's buffers and in its children. + ListArray.Builder listBuilder = new ListArray.Builder(Int32Type.Default); + Int32Array.Builder listValues = (Int32Array.Builder)listBuilder.ValueBuilder; + listBuilder.Append(); + listValues.Append(1).Append(2); + listBuilder.AppendNull(); + listBuilder.Append(); + listValues.Append(3); + IArrowArray[] columns = + { + new Int32Array.Builder().Append(1).AppendNull().Append(3).Build(), + new StringArray.Builder().Append("a").AppendNull().Append("ccc").Build(), + listBuilder.Build(), + }; + Schema schema = new Schema.Builder() + .Field(f => f.Name("i").DataType(Int32Type.Default)) + .Field(f => f.Name("s").DataType(StringType.Default)) + .Field(f => f.Name("l").DataType(new ListType(Int32Type.Default))) + .Build(); + using RecordBatch batch = new RecordBatch(schema, columns, 3); + + IpcOptions options = new IpcOptions { CompressionCodec = CompressionCodecType.Lz4Frame, CompressionCodecFactory = new PassThroughCodecFactory() }; + MemoryStream written = new MemoryStream(); + using (ArrowStreamWriter writer = new ArrowStreamWriter(written, schema, leaveOpen: true, options)) + { + writer.WriteRecordBatch(batch); + writer.WriteEnd(); + } + byte[] data = written.ToArray(); + + // Count the decompressions a successful read makes, then fail at each in turn. + FailOnNthDecompressionFactory counter = new FailOnNthDecompressionFactory(int.MaxValue); + using (ArrowStreamReader reader = new ArrowStreamReader(new ArrowContext(new TrackingAllocator(), counter), new MemoryStream(data))) + using (RecordBatch read = reader.ReadNextRecordBatch()) + { + Assert.Equal(3, read.Length); + } + Assert.True(counter.Decompressions > 4); + + for (int failOn = 1; failOn <= counter.Decompressions; failOn++) + { + int failure = failOn; + Run(allocator => + { + ArrowContext context = new ArrowContext(allocator, new FailOnNthDecompressionFactory(failure)); + using ArrowStreamReader reader = new ArrowStreamReader(context, new BufferedStream(new MemoryStream(data))); + Assert.Throws(() => reader.ReadNextRecordBatch()); + }); + } + } + [Fact] public void FailedDecompressionReleasesItsOutputBuffer() { @@ -780,6 +835,49 @@ public override void Flush() { } public override void SetLength(long value) => throw new NotSupportedException(); } + /// + /// Creates codecs that pass data through, except that the n-th non-empty decompression + /// (counted across all of the factory's codecs) fails as it would on corrupt input. + /// + private sealed class FailOnNthDecompressionFactory : ICompressionCodecFactory + { + private readonly int _failOn; + private int _decompressions; + + public FailOnNthDecompressionFactory(int failOn) => _failOn = failOn; + + public int Decompressions => Volatile.Read(ref _decompressions); + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) => new Codec(this); + + public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType, int? compressionLevel) => + CreateCodec(compressionCodecType); + + private sealed class Codec : ICompressionCodec + { + private readonly FailOnNthDecompressionFactory _factory; + + public Codec(FailOnNthDecompressionFactory factory) => _factory = factory; + + public int Decompress(ReadOnlyMemory source, Memory destination) + { + if (!source.IsEmpty && Interlocked.Increment(ref _factory._decompressions) == _factory._failOn) + { + throw new InvalidDataException("Corrupt compressed data."); + } + source.CopyTo(destination); + return source.Length; + } + + public void Compress(ReadOnlyMemory source, Stream destination) => + throw new NotSupportedException(); + + public void Dispose() + { + } + } + } + private sealed class FailingCodecFactory : ICompressionCodecFactory { public ICompressionCodec CreateCodec(CompressionCodecType compressionCodecType) => new FailingCodec(); From e40fdf2804a2566452b6e6e41913128c73b1c064 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 17:42:46 -0800 Subject: [PATCH 13/15] Don't let builders keep what they built alive After handing its working memory to a built buffer, a builder kept its own reference to that buffer so it could keep appending. With a caller-owned allocator, a builder that was never disposed therefore leaked what it built permanently, even once the built array was disposed, and the usual chained style (new Builder(allocator).Append(x).Build()) never disposes it. A builder now holds a reference only for allocators whose lifetime is Finalized, where collection reclaims it, so contents still survive a built array that is dropped without being disposed. With other lifetimes it takes a reference only while reading the built buffer, which it can do while the buffer is alive. Once the buffer has been disposed the builder's contents are gone: using them throws ObjectDisposedException, and Clear makes the builder usable again. Also release what the list, list-view, fixed-size list, map and binary-view builders have built when a later part of Build fails, for example a child fixed-size list of the wrong length. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/Arrays/BinaryViewArray.cs | 18 ++- src/Apache.Arrow/Arrays/FixedSizeListArray.cs | 20 ++- src/Apache.Arrow/Arrays/LargeListArray.cs | 23 ++- src/Apache.Arrow/Arrays/LargeListViewArray.cs | 27 +++- src/Apache.Arrow/Arrays/ListArray.cs | 23 ++- src/Apache.Arrow/Arrays/ListViewArray.cs | 27 +++- src/Apache.Arrow/Arrays/MapArray.cs | 38 +++-- src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs | 2 +- src/Apache.Arrow/ArrowBuffer.Builder.cs | 2 +- src/Apache.Arrow/Memory/BuilderMemory.cs | 131 ++++++++++++++---- src/Apache.Arrow/Memory/SharedMemoryOwner.cs | 13 +- .../BuilderDisposalTests.cs | 71 +++++++++- .../BuilderEdgeCaseTests.cs | 107 ++++++++++++-- .../BuilderHandOverTests.cs | 34 ++++- 14 files changed, 455 insertions(+), 81 deletions(-) diff --git a/src/Apache.Arrow/Arrays/BinaryViewArray.cs b/src/Apache.Arrow/Arrays/BinaryViewArray.cs index 03679da5..206a281b 100644 --- a/src/Apache.Arrow/Arrays/BinaryViewArray.cs +++ b/src/Apache.Arrow/Arrays/BinaryViewArray.cs @@ -125,9 +125,21 @@ public TArray Build(MemoryAllocator allocator = default) { bool hasValues = ValueBuffer.Length > 0; var bufs = new ArrowBuffer[hasValues ? 3 : 2]; - bufs[0] = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; - bufs[1] = BinaryViews.Build(allocator); - if (hasValues) { bufs[2] = ValueBuffer.Build(allocator); } + try + { + bufs[0] = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; + bufs[1] = BinaryViews.Build(allocator); + if (hasValues) { bufs[2] = ValueBuffer.Build(allocator); } + } + catch + { + // For example running out of memory; release the buffers already built. + foreach (ArrowBuffer buffer in bufs) + { + buffer.Dispose(); + } + throw; + } var data = new ArrayData( DataType, diff --git a/src/Apache.Arrow/Arrays/FixedSizeListArray.cs b/src/Apache.Arrow/Arrays/FixedSizeListArray.cs index 7d5d68e2..24039af0 100644 --- a/src/Apache.Arrow/Arrays/FixedSizeListArray.cs +++ b/src/Apache.Arrow/Arrays/FixedSizeListArray.cs @@ -137,13 +137,25 @@ public FixedSizeListArray Build(MemoryAllocator allocator = default) ValidateChildLength(); int nullCount = NullCount; - ArrowBuffer validityBuffer = nullCount > 0 + ArrowBuffer validityBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = nullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + values = ValueBuilder.Build(allocator); - return new FixedSizeListArray(DataType, Length, - ValueBuilder.Build(allocator), - validityBuffer, nullCount, 0); + return new FixedSizeListArray(DataType, Length, values, validityBuffer, nullCount, 0); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/LargeListArray.cs b/src/Apache.Arrow/Arrays/LargeListArray.cs index 96c77c75..990b2e2e 100644 --- a/src/Apache.Arrow/Arrays/LargeListArray.cs +++ b/src/Apache.Arrow/Arrays/LargeListArray.cs @@ -122,13 +122,28 @@ public LargeListArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(ValueBuilder.Length); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); - return new LargeListArray(DataType, Length - 1, - ValueOffsetsBufferBuilder.Build(allocator), ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + return new LargeListArray(DataType, Length - 1, offsetsBuffer, values, validityBuffer, NullCount, 0); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + offsetsBuffer.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/LargeListViewArray.cs b/src/Apache.Arrow/Arrays/LargeListViewArray.cs index a482dcd4..69e99abf 100644 --- a/src/Apache.Arrow/Arrays/LargeListViewArray.cs +++ b/src/Apache.Arrow/Arrays/LargeListViewArray.cs @@ -150,14 +150,31 @@ public LargeListViewArray Build(MemoryAllocator allocator = default) { AppendPrevious(); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + ArrowBuffer sizesBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + sizesBuffer = SizesBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); - return new LargeListViewArray(DataType, Length, - ValueOffsetsBufferBuilder.Build(allocator), SizesBufferBuilder.Build(allocator), - ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + return new LargeListViewArray(DataType, Length, offsetsBuffer, sizesBuffer, values, validityBuffer, NullCount, 0); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + offsetsBuffer.Dispose(); + sizesBuffer.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/ListArray.cs b/src/Apache.Arrow/Arrays/ListArray.cs index 28a4707e..52ac136b 100644 --- a/src/Apache.Arrow/Arrays/ListArray.cs +++ b/src/Apache.Arrow/Arrays/ListArray.cs @@ -129,13 +129,28 @@ public ListArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(ValueBuilder.Length); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); - return new ListArray(DataType, Length - 1, - ValueOffsetsBufferBuilder.Build(allocator), ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + return new ListArray(DataType, Length - 1, offsetsBuffer, values, validityBuffer, NullCount, 0); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + offsetsBuffer.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/ListViewArray.cs b/src/Apache.Arrow/Arrays/ListViewArray.cs index 4da3e5bd..522a9ff5 100644 --- a/src/Apache.Arrow/Arrays/ListViewArray.cs +++ b/src/Apache.Arrow/Arrays/ListViewArray.cs @@ -151,14 +151,31 @@ public ListViewArray Build(MemoryAllocator allocator = default) { AppendPrevious(); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + ArrowBuffer sizesBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + sizesBuffer = SizesBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); - return new ListViewArray(DataType, Length, - ValueOffsetsBufferBuilder.Build(allocator), SizesBufferBuilder.Build(allocator), - ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + return new ListViewArray(DataType, Length, offsetsBuffer, sizesBuffer, values, validityBuffer, NullCount, 0); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + offsetsBuffer.Dispose(); + sizesBuffer.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/MapArray.cs b/src/Apache.Arrow/Arrays/MapArray.cs index 9d77ff61..d3f36ab6 100644 --- a/src/Apache.Arrow/Arrays/MapArray.cs +++ b/src/Apache.Arrow/Arrays/MapArray.cs @@ -114,15 +114,35 @@ public MapArray Build(MemoryAllocator allocator = default) { ValueOffsetsBufferBuilder.Append(KeyBuilder.Length); - ArrowBuffer validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; - - StructArray structs = new StructArray( - DataType.KeyValueType, KeyBuilder.Length, - new IArrowArray[] { KeyBuilder.Build(allocator), ValueBuilder.Build(allocator) }, - ArrowBuffer.Empty, 0 - ); - - return new MapArray(DataType, Length - 1, ValueOffsetsBufferBuilder.Build(allocator), structs, validityBuffer, NullCount); + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + IArrowArray keys = null; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + keys = KeyBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + + StructArray structs = new StructArray( + DataType.KeyValueType, KeyBuilder.Length, + new IArrowArray[] { keys, values }, + ArrowBuffer.Empty, 0 + ); + + return new MapArray(DataType, Length - 1, offsetsBuffer, structs, validityBuffer, NullCount); + } + catch + { + // A child that fails to build (for example a fixed-size list child of the wrong + // length) would otherwise leak the buffers already built. + validityBuffer.Dispose(); + offsetsBuffer.Dispose(); + keys?.Dispose(); + values?.Dispose(); + throw; + } } public Builder Reserve(int capacity) diff --git a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index 8db6dd7e..aa297ffd 100644 --- a/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs +++ b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs @@ -131,7 +131,7 @@ public BitmapBuilder Append(ReadOnlySpan source, int validBits) // a build releases the builder's reference to the built buffer), and appending bit by // bit can overwrite source bits before they are read. The check reads the memory // without detaching, since detaching would itself release it. - if (source.Overlaps(_buffer.CurrentBytes)) + if (_buffer.Overlaps(source)) { source = source.ToArray(); } diff --git a/src/Apache.Arrow/ArrowBuffer.Builder.cs b/src/Apache.Arrow/ArrowBuffer.Builder.cs index 676a1994..5c5a1c3f 100644 --- a/src/Apache.Arrow/ArrowBuffer.Builder.cs +++ b/src/Apache.Arrow/ArrowBuffer.Builder.cs @@ -158,7 +158,7 @@ public Builder Append(ReadOnlySpan source) // built buffer. A source that points into that memory must be copied first. The check // reads the memory without detaching, since detaching would itself release it. if ((source.Length > Capacity - Length || _buffer.IsShared) && - MemoryMarshal.AsBytes(source).Overlaps(_buffer.CurrentBytes)) + _buffer.Overlaps(MemoryMarshal.AsBytes(source))) { source = source.ToArray(); } diff --git a/src/Apache.Arrow/Memory/BuilderMemory.cs b/src/Apache.Arrow/Memory/BuilderMemory.cs index 7982ae69..c8716fa6 100644 --- a/src/Apache.Arrow/Memory/BuilderMemory.cs +++ b/src/Apache.Arrow/Memory/BuilderMemory.cs @@ -34,11 +34,21 @@ namespace Apache.Arrow.Memory /// single native allocation of the exact size. Passing an allocator opts into the hand-over. /// /// - /// After a hand-over the builder no longer owns writable memory. It keeps a retained - /// reference to the built buffer so that its contents stay readable, and copies them into - /// fresh working memory the first time the builder is written to again. Code that builds - /// once and discards the builder therefore allocates once; code that keeps appending after - /// a build pays one copy, which is what every build cost before. + /// After a hand-over the builder no longer owns writable memory. Its contents are the built + /// buffer's, which it copies into fresh working memory the first time it is written to + /// again. Code that builds once and discards the builder therefore allocates once; code + /// that keeps appending after a build pays one copy, which is what every build cost before. + /// + /// + /// The builder holds a reference to the built buffer only when the allocator's lifetime is + /// , where collection reclaims it, so contents + /// survive a built array that is dropped without being disposed, as they always have. Other + /// lifetimes are never reclaimed by collection, so holding a reference would leak whenever + /// the builder is not disposed, as in new Builder(allocator).Append(x).Build(). + /// Instead the builder takes a reference only while it reads the buffer, which it can do + /// while the buffer is alive. Once the buffer has been disposed the builder's contents are + /// gone with it: using them throws , and + /// makes the builder usable again. /// /// /// When it can hand over, working memory is always a multiple of @@ -62,15 +72,19 @@ internal sealed class BuilderMemory : IDisposable private readonly bool _canHandOver; // Exactly one of these is in use: _owner/_memory while the builder owns its working - // memory, _shared after that memory has been handed to a built buffer. Both are empty - // after disposal. + // memory, _sharedOwner after that memory has been handed to a built buffer. Both are + // empty after disposal. private IMemoryOwner _owner; private Memory _memory; - private ArrowBuffer _shared; + private SharedMemoryOwner _sharedOwner; private bool _isShared; - // How many bytes of _shared hold data, as opposed to padding. A later build can share - // the same buffer only if it would hold exactly the same bytes. + // The builder's own reference to the built buffer, held only for finalized lifetimes. + private SharedMemoryHandle _sharedHold; + private int _sharedLength; + + // How many bytes of the built buffer hold data, as opposed to padding. A later build can + // share the same buffer only if it would hold exactly the same bytes. private int _sharedUsedBytes; /// @@ -106,20 +120,43 @@ private BuilderMemory(MemoryAllocator temporary, MemoryAllocator longTerm, int c /// /// Size of the working memory in bytes. Reading this never copies. /// - public int Capacity => _isShared ? _shared.Length : _memory.Length; + public int Capacity => _isShared ? _sharedLength : _memory.Length; /// /// Whether the builder's memory currently belongs to a built buffer, in which case the - /// next write releases the builder's reference to it. + /// next write may release the builder's reference to it. /// public bool IsShared => _isShared; /// - /// The bytes currently backing the builder, read without detaching: the working memory, - /// or the buffer it was handed to. Callers use this to tell whether a span points into - /// memory that writing to the builder could release. + /// Whether points into the memory currently backing the + /// builder, read without detaching: the working memory, or the buffer it was handed to. + /// Callers use this to tell whether a span points into memory that writing to the + /// builder could release. /// - public ReadOnlySpan CurrentBytes => _isShared ? _shared.Span : _memory.Span; + public bool Overlaps(ReadOnlySpan source) + { + if (!_isShared) + { + return source.Overlaps(_memory.Span); + } + + SharedMemoryHandle handle = _sharedOwner.TryRetain(); + if (handle == null) + { + // Released memory: no valid span can point into it. + return false; + } + + try + { + return source.Overlaps(handle.Memory.Span); + } + finally + { + handle.Dispose(); + } + } /// /// The writable working memory. If it has been handed to a built buffer, the contents @@ -131,7 +168,7 @@ public Memory Memory { if (_isShared) { - Detach(_shared.Length); + Detach(_sharedLength); } return _memory; @@ -173,7 +210,8 @@ public void Reset() { if (_isShared) { - int capacity = _shared.Length; + // Needs no access to the built buffer, so works even once it has been disposed. + int capacity = _sharedLength; ReleaseShared(); _owner = _temporary.Allocate(capacity); _memory = _owner.Memory; @@ -203,14 +241,21 @@ public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) // Built again holding exactly the same bytes: share the same memory. A Resize can // change the length without writing to the builder, so the padded length alone // is not enough; sharing after a shrink would expose the removed values. - if (handOver && usedBytes == _sharedUsedBytes && padded == _shared.Length) + SharedMemoryHandle handle = AcquireShared(); + if (handOver && usedBytes == _sharedUsedBytes && padded == _sharedLength) { - return _shared.Retain(); + return new ArrowBuffer(handle); } - ArrowBuffer sharedCopy = Copy(_shared.Span, usedBytes, padded, destination); - GC.KeepAlive(this); - return sharedCopy; + try + { + return Copy(handle.Memory.Span, usedBytes, padded, destination); + } + finally + { + // Also keeps the memory alive while it is copied. + handle.Dispose(); + } } ThrowIfDisposed(); @@ -235,8 +280,12 @@ public ArrowBuffer Build(int usedBytes, int byteSize, MemoryAllocator target) ? _owner : new SlicedMemoryOwner(_owner, padded); - ArrowBuffer result = new ArrowBuffer(owner, _temporary.Lifetime); - _shared = result.Retain(); + AllocationLifetime lifetime = _temporary.Lifetime; + SharedMemoryOwner shared = new SharedMemoryOwner(owner, finalizeWhenUnreachable: lifetime == AllocationLifetime.Finalized); + ArrowBuffer result = new ArrowBuffer(new SharedMemoryHandle(shared)); + _sharedOwner = shared; + _sharedHold = lifetime == AllocationLifetime.Finalized ? shared.TryRetain() : null; + _sharedLength = padded; _sharedUsedBytes = usedBytes; _isShared = true; _owner = null; @@ -261,19 +310,41 @@ public void Dispose() private void Detach(int capacityBytes) { - IMemoryOwner owner = _temporary.Allocate(capacityBytes); - _shared.Span.CopyTo(owner.Memory.Span); + IMemoryOwner owner; + SharedMemoryHandle handle = AcquireShared(); + try + { + owner = _temporary.Allocate(capacityBytes); + handle.Memory.Span.CopyTo(owner.Memory.Span); + } + finally + { + handle.Dispose(); + } + ReleaseShared(); _owner = owner; _memory = owner.Memory; } + /// + /// Takes a reference to the built buffer the builder's contents belong to. + /// + private SharedMemoryHandle AcquireShared() + { + return _sharedOwner.TryRetain() ?? throw new ObjectDisposedException( + nameof(ArrowBuffer.Builder), + "The buffer built from this builder has been disposed, and the builder's contents with it. Clear the builder before using it again."); + } + private void ReleaseShared() { - ArrowBuffer shared = _shared; - _shared = default; + SharedMemoryHandle hold = _sharedHold; + _sharedHold = null; + _sharedOwner = null; + _sharedLength = 0; _isShared = false; - shared.Dispose(); + hold?.Dispose(); } private static ArrowBuffer Copy(ReadOnlySpan source, int usedBytes, int padded, MemoryAllocator allocator) diff --git a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs index 06aa64d6..5712ae83 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryOwner.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryOwner.cs @@ -51,13 +51,24 @@ public SharedMemoryOwner(IMemoryOwner inner, bool finalizeWhenUnreachable) /// Adds a reference, returning a handle to the given slice of the memory. /// public SharedMemoryHandle Retain(int start, int length) + { + return TryRetain(start, length) ?? throw new ObjectDisposedException(nameof(SharedMemoryOwner)); + } + + /// + /// Adds a reference to the whole memory, or returns null if it has already been + /// released. Once released, memory can never be retained again. + /// + public SharedMemoryHandle TryRetain() => TryRetain(0, _memory.Length); + + private SharedMemoryHandle TryRetain(int start, int length) { while (true) { int current = Volatile.Read(ref _refCount); if (current <= 0) { - throw new ObjectDisposedException(nameof(SharedMemoryOwner)); + return null; } if (Interlocked.CompareExchange(ref _refCount, current + 1, current) == current) diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index c0b6b1a7..40871adf 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -61,9 +61,37 @@ public void BuilderCanBeDisposedBeforeOrAfterArray() Int64Array array = builder.Build(); array.Dispose(); - Assert.True(allocator.LiveAllocations > 0, "The builder still holds the shared memory."); builder.Dispose(); }); + + Run(allocator => + { + Int64Array.Builder builder = new Int64Array.Builder(8, allocator).Append(1).Append(2); + Int64Array array = builder.Build(); + + builder.Dispose(); + Assert.Equal(2, array.GetValue(1)); + array.Dispose(); + }); + } + + [Fact] + public void DisposingTheArrayReleasesItsMemoryWhenTheBuilderIsNeverDisposed() + { + // The usual chained style never disposes the builder. With a caller-owned allocator, + // a builder that held a reference to what it built would leak it permanently. + Run(allocator => + { + using (Int32Array array = new Int32Array.Builder(16, allocator).Append(1).AppendNull().Build()) + { + Assert.Equal(1, array.GetValue(0)); + } + + using (StringArray strings = new StringArray.Builder(allocator).Append("a").AppendNull().Build()) + { + Assert.Equal("a", strings.GetString(0)); + } + }); } [Fact] @@ -582,6 +610,47 @@ public void FailingPartwayThroughAFieldReleasesItsBuffers() } } + public static TheoryData CompositeTypes => new TheoryData { "List", "LargeList", "ListView", "LargeListView", "FixedSizeList", "Map" }; + + [Theory] + [MemberData(nameof(CompositeTypes))] + public void FailingToBuildAChildReleasesTheParentsBuffers(string kind) + { + // The child is a fixed-size list holding one value where it needs two, so its Build + // throws, after the parent has built its own buffers. The parent's null makes it build + // a validity bitmap as well. + FixedSizeListType pair = new FixedSizeListType(Int32Type.Default, 2); + IArrowType type = kind switch + { + "List" => new ListType(pair), + "LargeList" => new LargeListType(pair), + "ListView" => new ListViewType(pair), + "LargeListView" => new LargeListViewType(pair), + "FixedSizeList" => new FixedSizeListType(pair, 1), + _ => new MapType(pair, Int32Type.Default), + }; + + Run(allocator => + { + IArrowArrayBuilder> builder = ArrowArrayBuilderFactory.Build(type, allocator); + IArrowArrayBuilder> child; + switch (builder) + { + case ListArray.Builder b: b.AppendNull(); child = b.ValueBuilder; break; + case LargeListArray.Builder b: b.AppendNull(); child = b.ValueBuilder; break; + case ListViewArray.Builder b: b.AppendNull(); child = b.ValueBuilder; break; + case LargeListViewArray.Builder b: b.AppendNull(); child = b.ValueBuilder; break; + case FixedSizeListArray.Builder b: b.AppendNull(); child = b.ValueBuilder; break; + case MapArray.Builder b: b.AppendNull(); child = b.KeyBuilder; break; + default: throw new InvalidOperationException(builder.GetType().Name); + } + ((Int32Array.Builder)((FixedSizeListArray.Builder)child).ValueBuilder).Append(1); + + Assert.Throws(() => builder.Build(allocator)); + ((IDisposable)builder).Dispose(); + }); + } + [Fact] public void FailedDecompressionReleasesItsOutputBuffer() { diff --git a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs index 46c04e60..6a87570a 100644 --- a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs +++ b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs @@ -144,34 +144,51 @@ public void AppendingOwnBitsBeyondTheLengthUsesTheOriginalBits() } } - [Fact] - public void AppendingASpanCapturedBeforeBuildSurvivesTheHandOver() + [Theory] + [InlineData(AllocationLifetime.Finalized)] + [InlineData(AllocationLifetime.GarbageCollected)] + [InlineData(AllocationLifetime.CallerOwned)] + public void AppendingASpanCapturedBeforeBuildSurvivesTheHandOver(AllocationLifetime lifetime) { - // After a hand-over, the builder holds the only remaining reference once the built - // buffer is disposed; writing to the builder releases it. A span captured earlier - // points into that memory, so it must be copied before the release. - PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + PoisoningAllocator allocator = new PoisoningAllocator(lifetime); using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(16, allocator); builder.Append(0).Append(1).Append(2).Append(3); Span captured = builder.Span.Slice(0, 4); - builder.Build().Dispose(); + ArrowBuffer built = builder.Build(); + + // With a Finalized lifetime the builder holds the only remaining reference once the + // built buffer is disposed, and writing to the builder releases it. The span points + // into that memory, so it must be copied before the release. With other lifetimes + // the builder holds no reference, and its contents last as long as the built buffer. + if (lifetime == AllocationLifetime.Finalized) + { + built.Dispose(); + } builder.Append(captured); Assert.Equal(new[] { 0, 1, 2, 3, 0, 1, 2, 3 }, builder.Span.Slice(0, 8).ToArray()); + built.Dispose(); } - [Fact] - public void AppendingABitmapSpanCapturedBeforeBuildSurvivesTheHandOver() + [Theory] + [InlineData(AllocationLifetime.Finalized)] + [InlineData(AllocationLifetime.GarbageCollected)] + [InlineData(AllocationLifetime.CallerOwned)] + public void AppendingABitmapSpanCapturedBeforeBuildSurvivesTheHandOver(AllocationLifetime lifetime) { - PooledManagedAllocator allocator = new PooledManagedAllocator(new PooledManagedAllocatorOptions { PoisonDisposedBuffers = true }); + PoisoningAllocator allocator = new PoisoningAllocator(lifetime); using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(64, allocator); for (int i = 0; i < 16; i++) { builder.Append(i % 3 == 0); } Span captured = builder.Span.Slice(0, 2); - builder.Build().Dispose(); + ArrowBuffer built = builder.Build(); + if (lifetime == AllocationLifetime.Finalized) + { + built.Dispose(); + } builder.Append(captured, 16); @@ -181,6 +198,27 @@ public void AppendingABitmapSpanCapturedBeforeBuildSurvivesTheHandOver() { Assert.Equal(i % 3 == 0, BitUtility.GetBit(builder.Span, 16 + i)); } + built.Dispose(); + } + + [Theory] + [InlineData(AllocationLifetime.GarbageCollected)] + [InlineData(AllocationLifetime.CallerOwned)] + public void UsingABuilderAfterItsBuiltBufferIsDisposedThrowsUntilCleared(AllocationLifetime lifetime) + { + PoisoningAllocator allocator = new PoisoningAllocator(lifetime); + using ArrowBuffer.BitmapBuilder builder = new ArrowBuffer.BitmapBuilder(64, allocator); + builder.Append(true).Append(false); + builder.Build().Dispose(); + + Assert.Throws(() => builder.Append(true)); + Assert.Throws(() => builder.Build()); + + builder.Clear(); + builder.Append(true); + using ArrowBuffer rebuilt = builder.Build(); + Assert.Equal(1, BitUtility.CountBits(rebuilt.Span, 0, 1)); + Assert.Equal(0, allocator.Live - 1); } [Fact] @@ -227,6 +265,53 @@ public void FailedRunEndConcatenationReleasesItsWorkingMemory() Assert.Equal(0, allocator.Outstanding); } + /// + /// Hands out managed memory with a chosen lifetime, and overwrites it when it is released + /// so that reading released memory shows up as wrong values. + /// + private sealed class PoisoningAllocator : MemoryAllocator + { + private readonly AllocationLifetime _lifetime; + private int _live; + + public PoisoningAllocator(AllocationLifetime lifetime) => _lifetime = lifetime; + + public override AllocationLifetime Lifetime => _lifetime; + + public int Live => System.Threading.Volatile.Read(ref _live); + + protected override System.Buffers.IMemoryOwner AllocateInternal(int length, out int bytesAllocated) + { + bytesAllocated = length; + System.Threading.Interlocked.Increment(ref _live); + return new Owner(this, new byte[length]); + } + + private sealed class Owner : System.Buffers.IMemoryOwner + { + private readonly PoisoningAllocator _allocator; + private byte[] _array; + + public Owner(PoisoningAllocator allocator, byte[] array) + { + _allocator = allocator; + _array = array; + } + + public Memory Memory => _array ?? throw new ObjectDisposedException(nameof(Owner)); + + public void Dispose() + { + byte[] array = System.Threading.Interlocked.Exchange(ref _array, null); + if (array != null) + { + array.AsSpan().Fill(0xDE); + System.Threading.Interlocked.Decrement(ref _allocator._live); + } + } + } + } + [Fact] public void TimestampBuilderWithNullTypeAllocatesNothing() { diff --git a/test/Apache.Arrow.Tests/BuilderHandOverTests.cs b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs index f22a8c8b..42355f61 100644 --- a/test/Apache.Arrow.Tests/BuilderHandOverTests.cs +++ b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs @@ -155,9 +155,11 @@ public void BuiltBufferSurvivesBuilderDisposal() } [Fact] - public void DisposingBuiltBufferLeavesBuilderReadable() + public void DisposingBuiltBufferLeavesBuilderReadableWithAFinalizedAllocator() { - using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, new CallerOwnedNativeAllocator()); + // With a Finalized lifetime the builder holds its own reference to what it built, + // which collection reclaims, so its contents outlive the built buffer as before. + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, MemoryAllocator.Default.Value); builder.Append(1).Append(2); builder.Build().Dispose(); @@ -166,6 +168,34 @@ public void DisposingBuiltBufferLeavesBuilderReadable() Assert.Equal(new[] { 1, 2, 3 }, builder.Span.Slice(0, 3).ToArray()); } + [Fact] + public void BuilderContentsLastAsLongAsTheBuiltBufferWithOtherLifetimes() + { + // Other lifetimes hold no reference, so that a builder that is never disposed cannot + // leak what it built. Its contents are the built buffer's, and go when it does. + using ArrowBuffer.Builder builder = new ArrowBuffer.Builder(8, new CallerOwnedNativeAllocator()); + builder.Append(1).Append(2); + + using (ArrowBuffer built = builder.Build()) + { + // While the built buffer is alive, the builder can still be read and extended. + builder.Append(3); + Assert.Equal(new[] { 1, 2, 3 }, builder.Span.Slice(0, 3).ToArray()); + Assert.Equal(new[] { 1, 2 }, built.Span.CastTo().Slice(0, 2).ToArray()); + } + + builder.Build().Dispose(); + + Assert.Throws(() => builder.Append(4)); + Assert.Throws(() => builder.Build()); + + // Clearing needs none of the old contents, so it makes the builder usable again. + builder.Clear(); + builder.Append(5); + using ArrowBuffer rebuilt = builder.Build(); + Assert.Equal(5, rebuilt.Span.CastTo()[0]); + } + [Fact] public void DifferentAllocatorForcesCopy() { From 34dc8887803f9b7fadb94b473cd79cc6e59b2e0c Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 18:01:34 -0800 Subject: [PATCH 14/15] Release what leaf builders built when Build fails Builders that build several buffers or child arrays in sequence dropped the earlier ones if a later step threw. With a pluggable allocator that is not only running out of memory: an allocator that enforces a budget refuses allocations by throwing, and with a caller-owned allocator the dropped buffers leaked permanently. The primitive, Boolean, binary, large binary, fixed-size binary, run-end encoded, timestamp with offset and variant builders now release what they built before rethrowing. A new test builds each into an allocator that refuses its n-th allocation, for every n a successful build makes, and checks that nothing is left outstanding in either allocator. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/Arrays/BinaryArray.cs | 36 ++++--- src/Apache.Arrow/Arrays/BooleanArray.cs | 19 +++- .../Arrays/FixedSizeBinaryArray.cs | 34 +++--- src/Apache.Arrow/Arrays/LargeBinaryArray.cs | 36 ++++--- .../Arrays/PrimitiveArrayBuilder.cs | 19 +++- .../Arrays/RunEndEncodedArray.Builder.cs | 18 +++- .../Arrays/TimestampWithOffsetArray.cs | 38 ++++--- src/Apache.Arrow/Arrays/VariantArray.cs | 32 ++++-- .../BuilderDisposalTests.cs | 102 ++++++++++++++++++ 9 files changed, 264 insertions(+), 70 deletions(-) diff --git a/src/Apache.Arrow/Arrays/BinaryArray.cs b/src/Apache.Arrow/Arrays/BinaryArray.cs index 2f5cca11..571c216b 100644 --- a/src/Apache.Arrow/Arrays/BinaryArray.cs +++ b/src/Apache.Arrow/Arrays/BinaryArray.cs @@ -173,20 +173,30 @@ protected virtual void Dispose(bool disposing) /// Returns an array of type . public TArray Build(MemoryAllocator allocator = default) { - var bufs = new[] + var bufs = new ArrowBuffer[3]; + try { - NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty, - ValueOffsets.Build(allocator), - ValueBuffer.Build(allocator), - }; - var data = new ArrayData( - DataType, - length: Length, - NullCount, - offset: 0, - bufs); - - return Build(data); + bufs[0] = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; + bufs[1] = ValueOffsets.Build(allocator); + bufs[2] = ValueBuffer.Build(allocator); + var data = new ArrayData( + DataType, + length: Length, + NullCount, + offset: 0, + bufs); + + return Build(data); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + foreach (ArrowBuffer buffer in bufs) + { + buffer.Dispose(); + } + throw; + } } /// diff --git a/src/Apache.Arrow/Arrays/BooleanArray.cs b/src/Apache.Arrow/Arrays/BooleanArray.cs index c1062354..17cc3c85 100644 --- a/src/Apache.Arrow/Arrays/BooleanArray.cs +++ b/src/Apache.Arrow/Arrays/BooleanArray.cs @@ -112,13 +112,24 @@ protected virtual void Dispose(bool disposing) public BooleanArray Build(MemoryAllocator allocator = default) { - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer valueBuffer = default; + try + { + validityBuffer = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; + valueBuffer = ValueBuffer.Build(allocator); - return new BooleanArray( - ValueBuffer.Build(allocator), validityBuffer, - Length, NullCount, 0); + return new BooleanArray(valueBuffer, validityBuffer, Length, NullCount, 0); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + validityBuffer.Dispose(); + valueBuffer.Dispose(); + throw; + } } public Builder Clear() diff --git a/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs b/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs index 78cc311c..ae0a8fb3 100644 --- a/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs +++ b/src/Apache.Arrow/Arrays/FixedSizeBinaryArray.cs @@ -135,19 +135,29 @@ protected virtual void Dispose(bool disposing) public TArray Build(MemoryAllocator allocator = default) { - var bufs = new[] + var bufs = new ArrowBuffer[2]; + try { - NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty, - ValueBuffer.Build(ByteWidth, allocator), - }; - var data = new ArrayData( - DataType, - Length, - NullCount, - 0, - bufs); - - return Build(data); + bufs[0] = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; + bufs[1] = ValueBuffer.Build(ByteWidth, allocator); + var data = new ArrayData( + DataType, + Length, + NullCount, + 0, + bufs); + + return Build(data); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + foreach (ArrowBuffer buffer in bufs) + { + buffer.Dispose(); + } + throw; + } } public TBuilder Reserve(int capacity) diff --git a/src/Apache.Arrow/Arrays/LargeBinaryArray.cs b/src/Apache.Arrow/Arrays/LargeBinaryArray.cs index f2ef3dc9..f50e8bf7 100644 --- a/src/Apache.Arrow/Arrays/LargeBinaryArray.cs +++ b/src/Apache.Arrow/Arrays/LargeBinaryArray.cs @@ -102,20 +102,30 @@ protected virtual void Dispose(bool disposing) public TArray Build(MemoryAllocator allocator = default) { - var bufs = new[] + var bufs = new ArrowBuffer[3]; + try { - NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty, - ValueOffsets.Build(allocator), - ValueBuffer.Build(allocator), - }; - var data = new ArrayData( - DataType, - length: Length, - NullCount, - offset: 0, - bufs); - - return Build(data); + bufs[0] = NullCount > 0 ? ValidityBuffer.Build(allocator) : ArrowBuffer.Empty; + bufs[1] = ValueOffsets.Build(allocator); + bufs[2] = ValueBuffer.Build(allocator); + var data = new ArrayData( + DataType, + length: Length, + NullCount, + offset: 0, + bufs); + + return Build(data); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + foreach (ArrowBuffer buffer in bufs) + { + buffer.Dispose(); + } + throw; + } } public TBuilder AppendNull() diff --git a/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs b/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs index 27225714..4e7b623a 100644 --- a/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs +++ b/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs @@ -310,13 +310,24 @@ protected virtual void Dispose(bool disposing) public TArray Build(MemoryAllocator allocator = default) { - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer valueBuffer = default; + try + { + validityBuffer = NullCount > 0 ? _validity.Build(allocator) : ArrowBuffer.Empty; + valueBuffer = ValueBuffer.Build(allocator); - return Build( - ValueBuffer.Build(allocator), validityBuffer, - ValueBuffer.Length, NullCount, 0); + return Build(valueBuffer, validityBuffer, ValueBuffer.Length, NullCount, 0); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + validityBuffer.Dispose(); + valueBuffer.Dispose(); + throw; + } } protected abstract TArray Build( diff --git a/src/Apache.Arrow/Arrays/RunEndEncodedArray.Builder.cs b/src/Apache.Arrow/Arrays/RunEndEncodedArray.Builder.cs index 67341e40..a65c7508 100644 --- a/src/Apache.Arrow/Arrays/RunEndEncodedArray.Builder.cs +++ b/src/Apache.Arrow/Arrays/RunEndEncodedArray.Builder.cs @@ -235,10 +235,22 @@ public RunEndEncodedArray Build(MemoryAllocator allocator = default) FlushCurrentRun(); } - TRunEndArray runEnds = RunEndsBuilder.Build(allocator); - TValueArray values = ValuesBuilder.Build(allocator); + TRunEndArray runEnds = default; + TValueArray values = default; + try + { + runEnds = RunEndsBuilder.Build(allocator); + values = ValuesBuilder.Build(allocator); - return new RunEndEncodedArray(runEnds, values); + return new RunEndEncodedArray(runEnds, values); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + runEnds?.Dispose(); + values?.Dispose(); + throw; + } } private void StartNewRun(TValue value, bool isNull) diff --git a/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs b/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs index 2376132d..16ca11e0 100644 --- a/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs +++ b/src/Apache.Arrow/Arrays/TimestampWithOffsetArray.cs @@ -372,18 +372,32 @@ public Builder Clear() public TimestampWithOffsetArray Build(MemoryAllocator allocator = default) { - TimestampArray timestamps = _timestampBuilder.Build(allocator); - Int16Array offsets = _offsetBuilder.Build(allocator); - int nullCount = _validityBuilder.UnsetBitCount; - ArrowBuffer validityBuffer = nullCount > 0 ? _validityBuilder.Build(allocator) : ArrowBuffer.Empty; - - var structType = (StructType)_type.StorageType; - var structArray = new StructArray( - structType, Length, - new IArrowArray[] { timestamps, offsets }, - validityBuffer, nullCount); - - return new TimestampWithOffsetArray(_type, structArray); + TimestampArray timestamps = null; + Int16Array offsets = null; + ArrowBuffer validityBuffer = default; + try + { + timestamps = _timestampBuilder.Build(allocator); + offsets = _offsetBuilder.Build(allocator); + int nullCount = _validityBuilder.UnsetBitCount; + validityBuffer = nullCount > 0 ? _validityBuilder.Build(allocator) : ArrowBuffer.Empty; + + var structType = (StructType)_type.StorageType; + var structArray = new StructArray( + structType, Length, + new IArrowArray[] { timestamps, offsets }, + validityBuffer, nullCount); + + return new TimestampWithOffsetArray(_type, structArray); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + timestamps?.Dispose(); + offsets?.Dispose(); + validityBuffer.Dispose(); + throw; + } } } } diff --git a/src/Apache.Arrow/Arrays/VariantArray.cs b/src/Apache.Arrow/Arrays/VariantArray.cs index cdb3568f..23f22faf 100644 --- a/src/Apache.Arrow/Arrays/VariantArray.cs +++ b/src/Apache.Arrow/Arrays/VariantArray.cs @@ -527,15 +527,29 @@ protected virtual void Dispose(bool disposing) /// public VariantArray Build(MemoryAllocator allocator = default) { - var metadataArray = _metadataBuilder.Build(allocator); - var valueArray = _valueBuilder.Build(allocator); - var structType = (StructType)VariantType.Default.StorageType; - var nullBitmap = _nullCount > 0 ? _validityBuilder.Build(allocator) : ArrowBuffer.Empty; - var structArray = new StructArray( - structType, _length, - new IArrowArray[] { metadataArray, valueArray }, - nullBitmap, _nullCount); - return new VariantArray(VariantType.Default, structArray); + BinaryArray metadataArray = null; + BinaryArray valueArray = null; + ArrowBuffer nullBitmap = default; + try + { + metadataArray = _metadataBuilder.Build(allocator); + valueArray = _valueBuilder.Build(allocator); + var structType = (StructType)VariantType.Default.StorageType; + nullBitmap = _nullCount > 0 ? _validityBuilder.Build(allocator) : ArrowBuffer.Empty; + var structArray = new StructArray( + structType, _length, + new IArrowArray[] { metadataArray, valueArray }, + nullBitmap, _nullCount); + return new VariantArray(VariantType.Default, structArray); + } + catch + { + // For example an allocator that has run out of its budget; release what was built. + metadataArray?.Dispose(); + valueArray?.Dispose(); + nullBitmap.Dispose(); + throw; + } } } } diff --git a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs index 40871adf..23a661f2 100644 --- a/test/Apache.Arrow.Tests/BuilderDisposalTests.cs +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -651,6 +651,92 @@ public void FailingToBuildAChildReleasesTheParentsBuffers(string kind) }); } + public static TheoryData LeafBuilders => new TheoryData + { + "Int32", "Boolean", "String", "LargeString", "Decimal128", "TimestampWithOffset", "Variant", "RunEndEncoded", + }; + + [Theory] + [MemberData(nameof(LeafBuilders))] + public void BuildingIntoAnAllocatorThatRunsOutReleasesWhatWasBuilt(string kind) + { + // An allocator with a memory budget refuses an allocation by throwing. Building into a + // different allocator copies each buffer, so every buffer is a separate allocation that + // can be refused, after earlier ones succeeded. Each builder has a null, so it builds a + // validity bitmap as well as its data. + TrackingAllocator counter = new TrackingAllocator(); + using (IArrowArray built = BuildInto(kind, new TrackingAllocator(), counter)) + { + } + int allocations = counter.Allocations; + Assert.True(allocations > 1, $"{kind} should build several buffers."); + + for (int failOn = 1; failOn <= allocations; failOn++) + { + int failure = failOn; + Run(target => + { + target.FailOnAllocation = failure; + TrackingAllocator working = new TrackingAllocator(); + Assert.Throws(() => BuildInto(kind, working, target)); + Assert.Equal(0, working.LiveAllocations); + }, expectAllocations: false); + } + } + + /// + /// Fills a builder whose working memory comes from , builds it + /// into , and disposes the builder. + /// + private static IArrowArray BuildInto(string kind, MemoryAllocator working, MemoryAllocator target) + { + switch (kind) + { + case "Int32": + using (Int32Array.Builder b = new Int32Array.Builder(8, working)) + { + return b.Append(1).AppendNull().Build(target); + } + case "Boolean": + using (BooleanArray.Builder b = new BooleanArray.Builder(working)) + { + return b.Append(true).AppendNull().Build(target); + } + case "String": + using (StringArray.Builder b = new StringArray.Builder(working)) + { + return b.Append("a").AppendNull().Build(target); + } + case "LargeString": + using (LargeStringArray.Builder b = new LargeStringArray.Builder(working)) + { + return b.Append("a").AppendNull().Build(target); + } + case "Decimal128": + using (Decimal128Array.Builder b = new Decimal128Array.Builder(new Decimal128Type(10, 2), working)) + { + return b.Append(1.5m).AppendNull().Build(target); + } + case "TimestampWithOffset": + using (TimestampWithOffsetArray.Builder b = new TimestampWithOffsetArray.Builder(TimestampWithOffsetType.Default, working)) + { + return b.Append(new DateTimeOffset(2000, 1, 1, 0, 0, 0, TimeSpan.Zero)).AppendNull().Build(target); + } + case "Variant": + using (VariantArray.Builder b = new VariantArray.Builder(working)) + { + return b.Append(Apache.Arrow.Scalars.Variant.VariantValue.FromInt32(1)).AppendNull().Build(target); + } + default: + using (Int32Array.Builder runEnds = new Int32Array.Builder(8, working)) + using (StringArray.Builder values = new StringArray.Builder(working)) + { + var b = new RunEndEncodedArray.Builder(runEnds, values); + return b.Append("a").Append("a").AppendNull().Build(target); + } + } + } + [Fact] public void FailedDecompressionReleasesItsOutputBuffer() { @@ -752,8 +838,24 @@ private sealed class TrackingAllocator : MemoryAllocator public override AllocationLifetime Lifetime => AllocationLifetime.CallerOwned; + /// + /// The allocation, counting from 1, that fails as if the allocator had run out of its + /// budget. + /// + public int FailOnAllocation { get; set; } = int.MaxValue; + + /// The number of allocations requested, including one refused. + public int Allocations => Volatile.Read(ref _allocations); + + private int _allocations; + protected override IMemoryOwner AllocateInternal(int length, out int bytesAllocated) { + if (Interlocked.Increment(ref _allocations) == FailOnAllocation) + { + throw new OutOfMemoryException("Simulated allocation budget exhausted."); + } + byte[] buffer = new byte[length]; lock (_handedOut) { From 399ab94506bc9c0ded4e3bba0129a6d33c0bf945 Mon Sep 17 00:00:00 2001 From: Curt Hagenlocher Date: Sun, 15 Nov 2026 19:11:34 -0800 Subject: [PATCH 15/15] Keep a buffer's memory alive while Clone and Equals read it Both read the buffer through a span, which doesn't root the handle that owns the memory. A buffer that was otherwise unreachable could have its handle finalized, freeing native memory, partway through the copy or comparison. This predates the allocator work; only buffers whose lifetime is Finalized are affected, since other lifetimes have no finalizer. Co-Authored-By: Claude Opus 5.5 --- src/Apache.Arrow/ArrowBuffer.cs | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/src/Apache.Arrow/ArrowBuffer.cs b/src/Apache.Arrow/ArrowBuffer.cs index 85ce90ab..30533286 100644 --- a/src/Apache.Arrow/ArrowBuffer.cs +++ b/src/Apache.Arrow/ArrowBuffer.cs @@ -99,12 +99,20 @@ public ArrowBuffer Clone(MemoryAllocator allocator = default) } using Builder builder = new Builder(Span.Length, allocator); - return builder.Append(Span).Build(allocator); + ArrowBuffer clone = builder.Append(Span).Build(allocator); + + // Nothing else roots the handle while its memory is read through a span, so without + // this a buffer that is otherwise unreachable could be finalized mid-copy. + GC.KeepAlive(_handle); + return clone; } public bool Equals(ArrowBuffer other) { - return Span.SequenceEqual(other.Span); + bool equal = Span.SequenceEqual(other.Span); + GC.KeepAlive(_handle); + GC.KeepAlive(other._handle); + return equal; } public void Dispose()