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/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs b/src/Apache.Arrow.Operations/Shredding/ShreddedVariantArrayBuilder.cs index 3428fa18..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++) @@ -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..8f1abf52 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(); break; - case ArrowTypeId.Int32: int32Builder = new ArrowBuffer.Builder(); break; - case ArrowTypeId.Int64: int64Builder = new ArrowBuffer.Builder(); 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; @@ -1105,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/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..571c216b 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. /// @@ -133,20 +173,30 @@ protected void AdvanceValueBuffer(int count) /// 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/BinaryViewArray.cs b/src/Apache.Arrow/Arrays/BinaryViewArray.cs index 35001309..206a281b 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. /// @@ -85,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/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..17cc3c85 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,15 +87,49 @@ 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 + 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/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..ae0a8fb3 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,28 +98,66 @@ 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) { - 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/FixedSizeListArray.cs b/src/Apache.Arrow/Arrays/FixedSizeListArray.cs index bb395a3c..24039af0 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,18 +109,53 @@ 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(); 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/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..f50e8bf7 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,22 +76,56 @@ 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[] + var bufs = new ArrowBuffer[3]; + try + { + 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 { - 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); + // 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/LargeListArray.cs b/src/Apache.Arrow/Arrays/LargeListArray.cs index 4cc58747..990b2e2e 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,17 +94,56 @@ 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); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; - - return new LargeListArray(DataType, Length - 1, - ValueOffsetsBufferBuilder.Build(allocator), ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); + + 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 7e832588..69e99abf 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,18 +121,60 @@ 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(); - 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/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..52ac136b 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,17 +101,56 @@ 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); - ArrowBuffer validityBuffer = NullCount > 0 + ArrowBuffer validityBuffer = default; + ArrowBuffer offsetsBuffer = default; + IArrowArray values = null; + try + { + validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; - - return new ListArray(DataType, Length - 1, - ValueOffsetsBufferBuilder.Build(allocator), ValueBuilder.Build(allocator), - validityBuffer, NullCount, 0); + offsetsBuffer = ValueOffsetsBufferBuilder.Build(allocator); + values = ValueBuilder.Build(allocator); + + 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 2c50e413..522a9ff5 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,18 +122,60 @@ 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(); - 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 baff2008..d3f36ab6 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,19 +85,64 @@ public Builder AppendNull() return this; } - public MapArray Build(MemoryAllocator allocator = default) + /// + /// 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() { - ValueOffsetsBufferBuilder.Append(KeyBuilder.Length); + Dispose(true); + GC.SuppressFinalize(this); + } - ArrowBuffer validityBuffer = NullCount > 0 ? ValidityBufferBuilder.Build(allocator) : ArrowBuffer.Empty; + protected virtual void Dispose(bool disposing) + { + if (disposing) + { + (KeyBuilder as IDisposable)?.Dispose(); + (ValueBuilder as IDisposable)?.Dispose(); + ValueOffsetsBufferBuilder.Dispose(); + ValidityBufferBuilder.Dispose(); + } + } - StructArray structs = new StructArray( - DataType.KeyValueType, KeyBuilder.Length, - new IArrowArray[] { KeyBuilder.Build(allocator), ValueBuilder.Build(allocator) }, - ArrowBuffer.Empty, 0 - ); + public MapArray Build(MemoryAllocator allocator = default) + { + ValueOffsetsBufferBuilder.Append(KeyBuilder.Length); - 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/Arrays/PrimitiveArrayBuilder.cs b/src/Apache.Arrow/Arrays/PrimitiveArrayBuilder.cs index ffda77df..4e7b623a 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,42 +236,118 @@ 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) + 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( 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/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/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..4322acad 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,23 @@ 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) + // 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; + } + 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..16ca11e0 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); @@ -334,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/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..23f22faf 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,20 +498,58 @@ 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. /// 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/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs b/src/Apache.Arrow/ArrowBuffer.BitmapBuilder.cs index 6983af3a..aa297ffd 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 => (int)Math.Min((long)_buffer.Capacity * 8, int.MaxValue); /// /// 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)); } /// @@ -100,6 +126,16 @@ 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)); + // 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 (_buffer.Overlaps(source)) + { + 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) { @@ -257,6 +293,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); @@ -270,7 +314,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 +323,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 +362,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..5c5a1c3f 100644 --- a/src/Apache.Arrow/ArrowBuffer.Builder.cs +++ b/src/Apache.Arrow/ArrowBuffer.Builder.cs @@ -14,9 +14,9 @@ // limitations under the License. using System; -using System.Buffers; using System.Collections.Generic; using System.Runtime.CompilerServices; +using System.Runtime.InteropServices; using Apache.Arrow.Memory; namespace Apache.Arrow @@ -32,17 +32,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 +60,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 +81,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 +114,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; } @@ -117,6 +153,16 @@ public Builder Append(T value) /// Returns the builder (for fluent-style composition). public Builder Append(ReadOnlySpan source) { + // 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) && + _buffer.Overlaps(MemoryMarshal.AsBytes(source))) + { + source = source.ToArray(); + } + EnsureAdditionalCapacity(source.Length); source.CopyTo(Span.Slice(Length, source.Length)); Length += source.Length; @@ -166,6 +212,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 +288,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 +296,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 +320,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 +335,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..30533286 100644 --- a/src/Apache.Arrow/ArrowBuffer.cs +++ b/src/Apache.Arrow/ArrowBuffer.cs @@ -34,12 +34,24 @@ 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; } - private ArrowBuffer(SharedMemoryHandle handle) + internal ArrowBuffer(SharedMemoryHandle handle) { _handle = handle; _memory = Memory.Empty; @@ -81,14 +93,26 @@ 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); + 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() 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/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/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..38933a0d 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; @@ -73,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); @@ -132,36 +142,58 @@ 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; + // 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; + 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) @@ -189,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], _allocator); + // 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(); + } } } @@ -221,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); @@ -230,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; @@ -271,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( @@ -352,22 +428,39 @@ 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; } - 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( @@ -388,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/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/ArrowStreamReaderImplementation.cs b/src/Apache.Arrow/Ipc/ArrowStreamReaderImplementation.cs index a2781028..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) @@ -95,9 +97,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 +157,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 aa63985e..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; @@ -425,7 +449,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 +481,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 +550,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 +601,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 +763,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 +793,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 +833,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 +845,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) @@ -852,7 +912,13 @@ 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 + // 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); } @@ -905,29 +971,40 @@ 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 + // 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); } - 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 @@ -939,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 @@ -983,11 +1064,25 @@ 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); + 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++) { @@ -1056,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); } @@ -1082,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/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs b/src/Apache.Arrow/Ipc/DecompressingBufferCreator.cs index dd8654ad..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,17 +54,27 @@ 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)); - 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); + return new ArrowBuffer(outputData, _allocator.Lifetime); } public void Dispose() 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/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/BuilderMemory.cs b/src/Apache.Arrow/Memory/BuilderMemory.cs new file mode 100644 index 00000000..c8716fa6 --- /dev/null +++ b/src/Apache.Arrow/Memory/BuilderMemory.cs @@ -0,0 +1,374 @@ +// 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. 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 + /// 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, _sharedOwner after that memory has been handed to a built buffer. Both are + // empty after disposal. + private IMemoryOwner _owner; + private Memory _memory; + private SharedMemoryOwner _sharedOwner; + private bool _isShared; + + // 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; + + /// + /// 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 ? _sharedLength : _memory.Length; + + /// + /// Whether the builder's memory currently belongs to a built buffer, in which case the + /// next write may release the builder's reference to it. + /// + public bool IsShared => _isShared; + + /// + /// 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 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 + /// are first copied into memory the builder owns, so writes never reach that buffer. + /// + public Memory Memory + { + get + { + if (_isShared) + { + Detach(_sharedLength); + } + + return _memory; + } + } + + /// + /// Grows the working memory to at least , preserving + /// 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); + 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) + { + // 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; + } + + // Cleared explicitly in both cases, since allocators need not zero what they 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 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. + SharedMemoryHandle handle = AcquireShared(); + if (handOver && usedBytes == _sharedUsedBytes && padded == _sharedLength) + { + return new ArrowBuffer(handle); + } + + try + { + return Copy(handle.Memory.Span, usedBytes, padded, destination); + } + finally + { + // Also keeps the memory alive while it is copied. + handle.Dispose(); + } + } + + ThrowIfDisposed(); + + if (!handOver || padded == 0 || padded > _memory.Length || + _memory.Length - padded > _memory.Length / MaxSlackDivisor) + { + 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 + // 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); + + 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; + _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; + 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() + { + SharedMemoryHandle hold = _sharedHold; + _sharedHold = null; + _sharedOwner = null; + _sharedLength = 0; + _isShared = false; + hold?.Dispose(); + } + + private static ArrowBuffer Copy(ReadOnlySpan source, int usedBytes, int padded, MemoryAllocator allocator) + { + IMemoryOwner owner = allocator.Allocate(padded); + 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); + } + + 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/CallerOwnedNativeAllocator.cs b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs new file mode 100644 index 00000000..3a9b51e4 --- /dev/null +++ b/src/Apache.Arrow/Memory/CallerOwnedNativeAllocator.cs @@ -0,0 +1,194 @@ +// 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."); + } + } + + 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 + 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; + 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(CallerOwnedNativeAllocator allocator, void* ptr, int offset, int length) + { + _allocator = allocator; + _ptr = (IntPtr)ptr; + _offset = offset; + _length = length; + } + + public override Span GetSpan() + { + IntPtr ptr = Volatile.Read(ref _ptr); + if (ptr == IntPtr.Zero || Volatile.Read(ref _disposed)) + { + 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; + lock (_sync) + { + if (_disposed) + { + throw new ObjectDisposedException(nameof(CallerOwnedMemoryManager)); + } + + _pinCount++; + ptr = _ptr; + } + + // 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) + { +#if NET6_0_OR_GREATER + NativeMemory.AlignedFree((void*)ptr); +#else + AlignedNative.AlignedFree((void*)ptr); +#endif + Interlocked.Decrement(ref _allocator._liveAllocations); + } + } + } + } +} 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..a7eaa172 100644 --- a/src/Apache.Arrow/Memory/SharedMemoryHandle.cs +++ b/src/Apache.Arrow/Memory/SharedMemoryHandle.cs @@ -21,25 +21,66 @@ 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) + { + // 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; + 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(); 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..5712ae83 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,19 +40,40 @@ public SharedMemoryOwner(IMemoryOwner inner) public Memory Memory => _memory; - public SharedMemoryHandle Retain() + /// + /// Whether handles to this memory release it from a finalizer when they are not disposed. + /// + public bool FinalizeWhenUnreachable { get; } + + 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) + { + 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) { - return new SharedMemoryHandle(this); + return new SharedMemoryHandle(this, start, length); } } } 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.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; + } + } + } +} 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); + } }); }); } 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/BuilderDisposalTests.cs b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs new file mode 100644 index 00000000..23a661f2 --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderDisposalTests.cs @@ -0,0 +1,1138 @@ +// 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 System.Threading.Tasks; +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(); + 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] + 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)); + }); + } + + [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(); + } + + [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 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()); + }); + } + } + + 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(); + }); + } + + 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() + { + 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() + { + 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; + + /// + /// 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) + { + _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); + } + + /// + /// 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(); + } + + /// + /// 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(); + + 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() + { + } + } + + /// + /// 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) + { + 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() + { + } + } + } +} diff --git a/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs new file mode 100644 index 00000000..6a87570a --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderEdgeCaseTests.cs @@ -0,0 +1,325 @@ +// 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 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)); + } + } + + [Theory] + [InlineData(AllocationLifetime.Finalized)] + [InlineData(AllocationLifetime.GarbageCollected)] + [InlineData(AllocationLifetime.CallerOwned)] + public void AppendingASpanCapturedBeforeBuildSurvivesTheHandOver(AllocationLifetime lifetime) + { + 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); + 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(); + } + + [Theory] + [InlineData(AllocationLifetime.Finalized)] + [InlineData(AllocationLifetime.GarbageCollected)] + [InlineData(AllocationLifetime.CallerOwned)] + public void AppendingABitmapSpanCapturedBeforeBuildSurvivesTheHandOver(AllocationLifetime lifetime) + { + 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); + ArrowBuffer built = builder.Build(); + if (lifetime == AllocationLifetime.Finalized) + { + built.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)); + } + 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] + 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); + } + + /// + /// 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() + { + GarbageMemoryAllocator allocator = new GarbageMemoryAllocator(); + + Assert.Throws(() => new TimestampArray.Builder((TimestampType)null, 100, allocator)); + + Assert.Equal(0, allocator.Outstanding); + } + } +} diff --git a/test/Apache.Arrow.Tests/BuilderHandOverTests.cs b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs new file mode 100644 index 00000000..42355f61 --- /dev/null +++ b/test/Apache.Arrow.Tests/BuilderHandOverTests.cs @@ -0,0 +1,461 @@ +// 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 DisposingBuiltBufferLeavesBuilderReadableWithAFinalizedAllocator() + { + // 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(); + builder.Append(3); + + 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() + { + 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..62c65d5d --- /dev/null +++ b/test/Apache.Arrow.Tests/DefaultAllocationBehaviorTests.cs @@ -0,0 +1,269 @@ +// 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); + } + + [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)] + [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(); + } + + /// + /// 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(); + 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); + } + } + } + } + } +} 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; + } + } + } +}