Class FileBufferingWriter
Represents builder of contiguous block of memory that may switch to file as its backing store.
Implements
Inherited Members
Namespace: DotNext.IO
Assembly: DotNext.IO.dll
Syntax
public sealed class FileBufferingWriter : ModernStream, IAsyncDisposable, IFlushable, IBufferWriter<byte>, IGrowableBuffer<byte>, IReadOnlySpanConsumer<byte>, ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>, IFunctional<Func<ReadOnlyMemory<byte>, CancellationToken, ValueTask>>, IDisposable, IResettable, IDynamicInterfaceCastable
Remarks
This class can be used to write buffered content to a target Stream or IBufferWriter<T>. Additionally, it's possible to get buffered content as Memory<T>. If memory threshold was not reached then returned Memory<T> instance references bytes in memory. Otherwise, it references memory-mapped file.
Constructors
| Edit this page View SourceFileBufferingWriter(MemoryAllocator<byte>?, int, int, string?, bool)
Initializes a new writer.
Declaration
public FileBufferingWriter(MemoryAllocator<byte>? allocator = null, int memoryThreshold = 32768, int initialCapacity = 0, string? tempDir = null, bool asyncIO = true)
Parameters
| Type | Name | Description |
|---|---|---|
| MemoryAllocator<byte> | allocator | The allocator of internal buffer. |
| int | memoryThreshold | The maximum amount of memory in bytes to allocate before switching to a file on disk. |
| int | initialCapacity | Initial capacity of internal buffer. Should not be greater than |
| string | tempDir | The location of the directory to write buffered contents to.
When unspecified, uses the value specified by the environment variable |
| bool | asyncIO | true if you will use asynchronous methods of the instance; otherwise, false. |
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException |
|
| DirectoryNotFoundException |
|
FileBufferingWriter(in Options)
Initializes a new writer.
Declaration
public FileBufferingWriter(in FileBufferingWriter.Options options)
Parameters
| Type | Name | Description |
|---|---|---|
| FileBufferingWriter.Options | options | Buffer writer options. |
Exceptions
| Type | Condition |
|---|---|
| DirectoryNotFoundException | Temporary directory for the backing file doesn't exist. |
Properties
| Edit this page View SourceCanRead
When overridden in a derived class, gets a value indicating whether the current stream supports reading.
Declaration
public override bool CanRead { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Overrides
| Edit this page View SourceCanSeek
When overridden in a derived class, gets a value indicating whether the current stream supports seeking.
Declaration
public override bool CanSeek { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Overrides
| Edit this page View SourceCanWrite
When overridden in a derived class, gets a value indicating whether the current stream supports writing.
Declaration
public override bool CanWrite { get; }
Property Value
| Type | Description |
|---|---|
| bool |
Overrides
| Edit this page View SourceLength
When overridden in a derived class, gets the length in bytes of the stream.
Declaration
public override long Length { get; }
Property Value
| Type | Description |
|---|---|
| long | A long value representing the length of the stream in bytes. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| NotSupportedException | A class derived from |
| ObjectDisposedException | Methods were called after the stream was closed. |
Position
When overridden in a derived class, gets or sets the position within the current stream.
Declaration
public override long Position { get; set; }
Property Value
| Type | Description |
|---|---|
| long | The current position within the stream. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| IOException | An I/O error occurs. |
| NotSupportedException | The stream does not support seeking. |
| ObjectDisposedException | Methods were called after the stream was closed. |
Methods
| Edit this page View SourceAdvance(int)
Notifies the IBufferWriter<T> that count data items were written to the output Span<T> or Memory<T>.
Declaration
public void Advance(int count)
Parameters
| Type | Name | Description |
|---|---|---|
| int | count | The number of data items written to the Span<T> or Memory<T>. |
Clear(bool)
Removes all written data.
Declaration
public void Clear(bool reuseBuffer = true)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | reuseBuffer |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | Attempt to cleanup this writer while reading. |
CopyTo(IBufferWriter<byte>, int, CancellationToken)
Drains buffered content to the buffer synchronously.
Declaration
public void CopyTo(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| IBufferWriter<byte> | destination | The buffer to drain buffered contents to. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token to monitor for cancellation requests. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyTo(Stream, int)
Drains buffered content to the stream synchronously.
Declaration
public override void CopyTo(Stream destination, int bufferSize)
Parameters
| Type | Name | Description |
|---|---|---|
| Stream | destination | The stream to drain buffered contents to. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
Overrides
| Edit this page View SourceCopyTo(Span<byte>)
Drains buffered content to the memory block synchronously.
Declaration
public int CopyTo(Span<byte> output)
Parameters
| Type | Name | Description |
|---|---|---|
| Span<byte> | output | The memory block used as a destination for copy operation. |
Returns
| Type | Description |
|---|---|
| int | The actual number of copied elements. |
CopyToAsync(IBufferWriter<byte>, int, CancellationToken)
Drains buffered content to the buffer asynchronously.
Declaration
public Task CopyToAsync(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| IBufferWriter<byte> | destination | The buffer to drain buffered contents to. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token to monitor for cancellation requests. |
Returns
| Type | Description |
|---|---|
| Task | The task representing asynchronous execution of this method. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyToAsync(Stream, int, CancellationToken)
Drains buffered content to the stream asynchronously.
Declaration
public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken token)
Parameters
| Type | Name | Description |
|---|---|---|
| Stream | destination | The stream to drain buffered contents to. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token to monitor for cancellation requests. |
Returns
| Type | Description |
|---|---|
| Task | A task that represents the asynchronous copy operation. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyToAsync(Memory<byte>, CancellationToken)
Drains buffered content to the memory block asynchronously.
Declaration
public ValueTask<int> CopyToAsync(Memory<byte> output, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| Memory<byte> | output | The memory block used as a destination for copy operation. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| ValueTask<int> | The actual number of copied elements. |
CopyToAsync<TArg>(ReadOnlySpanAction<byte, TArg>, TArg, int, CancellationToken)
Drains buffered content asynchronously.
Declaration
public Task CopyToAsync<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlySpanAction<byte, TArg> | reader | The content reader. |
| TArg | arg | The argument to be passed to the callback. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| Task | The task representing asynchronous execution of the operation. |
Type Parameters
| Name | Description |
|---|---|
| TArg | The type of the argument to be passed to the callback. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyToAsync<TConsumer>(TConsumer, int, CancellationToken)
Drains the written content to the consumer asynchronously.
Declaration
public Task CopyToAsync<TConsumer>(TConsumer consumer, int bufferSize, CancellationToken token) where TConsumer : ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>
Parameters
| Type | Name | Description |
|---|---|---|
| TConsumer | consumer | The consumer of the written content. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| Task | The task representing asynchronous execution of this method. |
Type Parameters
| Name | Description |
|---|---|
| TConsumer | The type of the consumer. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyTo<TArg>(ReadOnlySpanAction<byte, TArg>, TArg, int, CancellationToken)
Drains buffered content synchronously.
Declaration
public void CopyTo<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlySpanAction<byte, TArg> | reader | The content reader. |
| TArg | arg | The argument to be passed to the callback. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Type Parameters
| Name | Description |
|---|---|
| TArg | The type of the argument to be passed to the callback. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
CopyTo<TConsumer>(TConsumer, int, CancellationToken)
Drains the written content to the consumer synchronously.
Declaration
public void CopyTo<TConsumer>(TConsumer consumer, int bufferSize, CancellationToken token) where TConsumer : IReadOnlySpanConsumer<byte>
Parameters
| Type | Name | Description |
|---|---|---|
| TConsumer | consumer | The consumer of the written content. |
| int | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Type Parameters
| Name | Description |
|---|---|
| TConsumer | The type of the consumer. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
Dispose(bool)
Releases the unmanaged resources used by the Stream and optionally releases the managed resources.
Declaration
protected override void Dispose(bool disposing)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | disposing | true to release both managed and unmanaged resources; false to release only unmanaged resources. |
Overrides
| Edit this page View SourceFlush()
When overridden in a derived class, clears all buffers for this stream and causes any buffered data to be written to the underlying device.
Declaration
public override void Flush()
Overrides
Exceptions
| Type | Condition |
|---|---|
| IOException | An I/O error occurs. |
Flush(bool)
Flushes the internal buffer with the file and optionally synchronize a file's in-core state with storage device.
Declaration
public void Flush(bool flushToDisk)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | flushToDisk | true to synchronize a file's in-core state with storage device; otherwise, false. |
FlushAsync(bool, CancellationToken)
Flushes the internal buffer with the file and optionally synchronize a file's in-core state with storage device.
Declaration
public ValueTask FlushAsync(bool flushToDisk, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| bool | flushToDisk | true to synchronize a file's in-core state with storage device; otherwise, false. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| ValueTask | The asynchronous result of the operation. |
Exceptions
| Type | Condition |
|---|---|
| OperationCanceledException | The operation has been canceled. |
FlushAsync(CancellationToken)
Asynchronously clears all buffers for this stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests.
Declaration
public override Task FlushAsync(CancellationToken token)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | token |
Returns
| Type | Description |
|---|---|
| Task | A task that represents the asynchronous flush operation. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| ObjectDisposedException | The stream has been disposed. |
GetMemory(int)
Returns a Memory<T> to write to that is at least the requested size (specified by sizeHint).
Declaration
public Memory<byte> GetMemory(int sizeHint = 0)
Parameters
| Type | Name | Description |
|---|---|---|
| int | sizeHint | The minimum length of the returned Memory<T>. If 0, a non-empty buffer is returned. |
Returns
| Type | Description |
|---|---|
| Memory<byte> | A Memory<T> of at least the size |
Exceptions
| Type | Condition |
|---|---|
| OutOfMemoryException | The requested buffer size is not available. |
GetSpan(int)
Returns a Span<T> to write to that is at least the requested size (specified by sizeHint).
Declaration
public Span<byte> GetSpan(int sizeHint = 0)
Parameters
| Type | Name | Description |
|---|---|---|
| int | sizeHint | The minimum length of the returned Span<T>. If 0, a non-empty buffer is returned. |
Returns
| Type | Description |
|---|---|
| Span<byte> | A Span<T> of at least the size |
GetWrittenContent()
Returns the whole buffered content as a source of Memory<T> instances synchronously.
Declaration
public IMemoryOwner<byte> GetWrittenContent()
Returns
| Type | Description |
|---|---|
| IMemoryOwner<byte> | The memory manager providing access to buffered content. |
Remarks
Use GetWrittenContent(Range) if buffered content is too large.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The memory manager is already obtained but not disposed. |
| OutOfMemoryException | The size of buffered content is too large and cannot be represented by Memory<T> instance. |
GetWrittenContent(int)
Gets written content in the form of ReadOnlySequence<T> synchronously.
Declaration
public IReadOnlySequenceSource<byte> GetWrittenContent(int segmentSize)
Parameters
| Type | Name | Description |
|---|---|---|
| int | segmentSize | The size of the contiguous segment of file to be mapped to memory. |
Returns
| Type | Description |
|---|---|
| IReadOnlySequenceSource<byte> | The factory of ReadOnlySequence<T> instances. |
Exceptions
| Type | Condition |
|---|---|
| ArgumentOutOfRangeException |
|
| InvalidOperationException | The memory manager is already obtained but not disposed. |
GetWrittenContent(Range)
Returns buffered content as a source of Memory<T> instances synchronously.
Declaration
public IMemoryOwner<byte> GetWrittenContent(Range range)
Parameters
| Type | Name | Description |
|---|---|---|
| Range | range | The range of buffered content to return. |
Returns
| Type | Description |
|---|---|
| IMemoryOwner<byte> | The memory manager providing access to buffered content. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The memory manager is already obtained but not disposed. |
| ArgumentOutOfRangeException |
|
| OutOfMemoryException | The size of buffered content is too large and cannot be represented by Memory<T> instance. |
GetWrittenContentAsStream()
Gets written content as read-only stream.
Declaration
public Stream GetWrittenContentAsStream()
Returns
| Type | Description |
|---|---|
| Stream | Read-only stream representing the written content. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The stream is already obtained but not disposed. |
GetWrittenContentAsStreamAsync(CancellationToken)
Gets written content as read-only stream asynchronously.
Declaration
public ValueTask<Stream> GetWrittenContentAsStreamAsync(CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| ValueTask<Stream> | Read-only stream representing the written content. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The stream is already obtained but not disposed. |
| OperationCanceledException | The operation has been canceled. |
GetWrittenContentAsync(Range, CancellationToken)
Returns buffered content as a source of Memory<T> instances asynchronously.
Declaration
public ValueTask<IMemoryOwner<byte>> GetWrittenContentAsync(Range range, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| Range | range | The range of buffered content to return. |
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| ValueTask<IMemoryOwner<byte>> | The memory manager providing access to buffered content. |
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The memory manager is already obtained but not disposed. |
| OperationCanceledException | The operation has been canceled. |
| ArgumentOutOfRangeException |
|
| OutOfMemoryException | The size of buffered content is too large and cannot be represented by Memory<T> instance. |
GetWrittenContentAsync(CancellationToken)
Returns the whole buffered content as a source of Memory<T> instances asynchronously.
Declaration
public ValueTask<IMemoryOwner<byte>> GetWrittenContentAsync(CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| CancellationToken | token | The token that can be used to cancel the operation. |
Returns
| Type | Description |
|---|---|
| ValueTask<IMemoryOwner<byte>> | The memory manager providing access to buffered content. |
Remarks
Use GetWrittenContentAsync(Range, CancellationToken) if buffered content is too large.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The memory manager is already obtained but not disposed. |
| OperationCanceledException | The operation has been canceled. |
| OutOfMemoryException | The size of buffered content is too large and cannot be represented by Memory<T> instance. |
Read(Span<byte>)
When overridden in a derived class, reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
Declaration
public override int Read(Span<byte> data)
Parameters
| Type | Name | Description |
|---|---|---|
| Span<byte> | data |
Returns
| Type | Description |
|---|---|
| int | The total number of bytes read into the buffer. This can be less than the size of the buffer if that many bytes are not currently available, or zero (0) if the buffer's length is zero or the end of the stream has been reached. |
Overrides
| Edit this page View SourceReadAsync(Memory<byte>, CancellationToken)
Asynchronously reads a sequence of bytes from the current stream, advances the position within the stream by the number of bytes read, and monitors cancellation requests.
Declaration
public override ValueTask<int> ReadAsync(Memory<byte> data, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| Memory<byte> | data | |
| CancellationToken | token |
Returns
| Type | Description |
|---|---|
| ValueTask<int> | A task that represents the asynchronous read operation. The value of its Result property contains the total number of bytes read into the buffer. The result value can be less than the length of the buffer if that many bytes are not currently available, or it can be 0 (zero) if the length of the buffer is 0 or if the end of the stream has been reached. |
Overrides
| Edit this page View SourceSeek(long, SeekOrigin)
When overridden in a derived class, sets the position within the current stream.
Declaration
public override long Seek(long offset, SeekOrigin origin)
Parameters
| Type | Name | Description |
|---|---|---|
| long | offset | A byte offset relative to the |
| SeekOrigin | origin | A value of type SeekOrigin indicating the reference point used to obtain the new position. |
Returns
| Type | Description |
|---|---|
| long | The new position within the current stream. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| IOException | An I/O error occurs. |
| NotSupportedException | The stream does not support seeking, such as if the stream is constructed from a pipe or console output. |
| ObjectDisposedException | Methods were called after the stream was closed. |
SetLength(long)
When overridden in a derived class, sets the length of the current stream.
Declaration
public override void SetLength(long value)
Parameters
| Type | Name | Description |
|---|---|---|
| long | value | The desired length of the current stream in bytes. |
Overrides
Exceptions
| Type | Condition |
|---|---|
| IOException | An I/O error occurs. |
| NotSupportedException | The stream does not support both writing and seeking, such as if the stream is constructed from a pipe or console output. |
| ObjectDisposedException | Methods were called after the stream was closed. |
TryGetWrittenContent(out ReadOnlyMemory<byte>)
Attempts to get written content if it is located in memory.
Declaration
public bool TryGetWrittenContent(out ReadOnlyMemory<byte> content)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | content | The written content. |
Returns
| Type | Description |
|---|---|
| bool | true if whole content is in memory and available without allocation of MemoryManager<T>; otherwise, false. |
Remarks
If this method returns false then use GetWrittenContent(), GetWrittenContent(Range), GetWrittenContentAsync(CancellationToken) or GetWrittenContentAsync(Range, CancellationToken) to obtain the content.
TryGetWrittenContent(out ReadOnlyMemory<byte>, out string?)
Attempts to get written content if it is located in memory.
Declaration
public bool TryGetWrittenContent(out ReadOnlyMemory<byte> content, out string? fileName)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | content | The written content. |
| string | fileName | The path to the file used as a buffer if this writer switched to the file. |
Returns
| Type | Description |
|---|---|
| bool | true if whole content is in memory and available without allocation of MemoryManager<T>; otherwise, false. |
Remarks
If this method returns false then
fileName contains full path to the file containing the written content.
This method is useful only if the file was not created as temporary file.
Write(ReadOnlySpan<byte>)
When overridden in a derived class, writes a sequence of bytes to the current stream and advances the current position within this stream by the number of bytes written.
Declaration
public override void Write(ReadOnlySpan<byte> input)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlySpan<byte> | input |
Overrides
| Edit this page View SourceWriteAsync(ReadOnlyMemory<byte>, CancellationToken)
Asynchronously writes a sequence of bytes to the current stream, advances the current position within this stream by the number of bytes written, and monitors cancellation requests.
Declaration
public override ValueTask WriteAsync(ReadOnlyMemory<byte> input, CancellationToken token = default)
Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | input | |
| CancellationToken | token |
Returns
| Type | Description |
|---|---|
| ValueTask | A task that represents the asynchronous write operation. |