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 : Stream, IAsyncDisposable, IDisposable, IFlushableBufferWriter<byte>, IBufferWriter<byte>, IFlushable, IGrowableBuffer<byte>
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
| Improve this Doc View SourceFileBufferingWriter(Nullable<MemoryAllocator<Byte>>, Int32, Int32, String, Boolean)
Initializes a new writer.
Declaration
public FileBufferingWriter(MemoryAllocator<byte>? allocator = default(MemoryAllocator<byte>? ), int memoryThreshold = 32768, int initialCapacity = 0, string tempDir = null, bool asyncIO = true)
Parameters
Type | Name | Description |
---|---|---|
Nullable<MemoryAllocator<Byte>> | allocator | The allocator of internal buffer. |
Int32 | memoryThreshold | The maximum amount of memory in bytes to allocate before switching to a file on disk. |
Int32 | 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 |
Boolean | asyncIO | true if you will use asynchronous methods of the instance; otherwise, false. |
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException |
|
DirectoryNotFoundException |
|
Properties
| Improve this Doc View SourceAllocationCounter
Sets the counter used to report allocation of internal buffer.
Declaration
public EventCounter AllocationCounter { set; }
Property Value
Type | Description |
---|---|
EventCounter |
CanRead
Declaration
public override bool CanRead { get; }
Property Value
Type | Description |
---|---|
Boolean |
Overrides
| Improve this Doc View SourceCanSeek
Declaration
public override bool CanSeek { get; }
Property Value
Type | Description |
---|---|
Boolean |
Overrides
| Improve this Doc View SourceCanTimeout
Declaration
public override bool CanTimeout { get; }
Property Value
Type | Description |
---|---|
Boolean |
Overrides
| Improve this Doc View SourceCanWrite
Declaration
public override bool CanWrite { get; }
Property Value
Type | Description |
---|---|
Boolean |
Overrides
| Improve this Doc View SourceLength
Declaration
public override long Length { get; }
Property Value
Type | Description |
---|---|
Int64 |
Overrides
| Improve this Doc View SourcePosition
Declaration
public override long Position { get; set; }
Property Value
Type | Description |
---|---|
Int64 |
Overrides
Methods
| Improve this Doc View SourceAdvance(Int32)
Declaration
public void Advance(int count)
Parameters
Type | Name | Description |
---|---|---|
Int32 | count |
BeginRead(Byte[], Int32, Int32, AsyncCallback, Object)
Declaration
public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, AsyncCallback callback, object state)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count | |
AsyncCallback | callback | |
Object | state |
Returns
Type | Description |
---|---|
IAsyncResult |
Overrides
| Improve this Doc View SourceBeginWrite(Byte[], Int32, Int32, AsyncCallback, Object)
Declaration
public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, AsyncCallback callback, object state)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count | |
AsyncCallback | callback | |
Object | state |
Returns
Type | Description |
---|---|
IAsyncResult |
Overrides
| Improve this Doc View SourceClear()
Removes all written data.
Declaration
public void Clear()
Exceptions
Type | Condition |
---|---|
InvalidOperationException | Attempt to cleanup this writer while reading. |
CopyTo(IBufferWriter<Byte>, Int32, CancellationToken)
Drains buffered content to the buffer synchronously.
Declaration
public long CopyTo(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
IBufferWriter<Byte> | destination | The buffer to drain buffered contents to. |
Int32 | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
CancellationToken | token | The token to monitor for cancellation requests. |
Returns
Type | Description |
---|---|
Int64 | The number of copied elements.. |
Exceptions
Type | Condition |
---|---|
OperationCanceledException | The operation has been canceled. |
CopyTo(Stream, Int32)
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. |
Int32 | bufferSize | The size, in bytes, of the buffer used to copy bytes. |
Overrides
| Improve this Doc 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 |
---|---|
Int32 | The actual number of copied elements. |
CopyTo<TArg>(ReadOnlySpanAction<Byte, TArg>, TArg, Int32, CancellationToken)
Drains buffered content synchronously.
Declaration
public void CopyTo<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
ReadOnlySpanAction<Byte, TArg> | reader | The content reader. |
TArg | arg | The argument to be passed to the callback. |
Int32 | 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. |
CopyToAsync(IBufferWriter<Byte>, Int32, CancellationToken)
Drains buffered content to the buffer asynchronously.
Declaration
public Task<long> CopyToAsync(IBufferWriter<byte> destination, int bufferSize = 1024, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
IBufferWriter<Byte> | destination | The buffer to drain buffered contents to. |
Int32 | 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<Int64> | The number of copied elements.. |
Exceptions
Type | Condition |
---|---|
OperationCanceledException | The operation has been canceled. |
CopyToAsync(Stream, Int32, 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. |
Int32 | 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 Task<int> CopyToAsync(Memory<byte> output, CancellationToken token = default(CancellationToken))
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 |
---|---|
Task<Int32> | The actual number of copied elements. |
CopyToAsync<TArg>(ReadOnlySpanAction<Byte, TArg>, TArg, Int32, CancellationToken)
Drains buffered content asynchronously.
Declaration
public Task CopyToAsync<TArg>(ReadOnlySpanAction<byte, TArg> reader, TArg arg, int bufferSize = 1024, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
ReadOnlySpanAction<Byte, TArg> | reader | The content reader. |
TArg | arg | The argument to be passed to the callback. |
Int32 | 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. |
Dispose(Boolean)
Declaration
protected override void Dispose(bool disposing)
Parameters
Type | Name | Description |
---|---|---|
Boolean | disposing |
Overrides
| Improve this Doc View SourceDisposeAsync()
Declaration
public override ValueTask DisposeAsync()
Returns
Type | Description |
---|---|
ValueTask |
Overrides
| Improve this Doc View SourceEndRead(IAsyncResult)
Declaration
public override int EndRead(IAsyncResult asyncResult)
Parameters
Type | Name | Description |
---|---|---|
IAsyncResult | asyncResult |
Returns
Type | Description |
---|---|
Int32 |
Overrides
| Improve this Doc View SourceEndWrite(IAsyncResult)
Declaration
public override void EndWrite(IAsyncResult ar)
Parameters
Type | Name | Description |
---|---|---|
IAsyncResult | ar |
Overrides
| Improve this Doc View SourceFlush()
Declaration
public override void Flush()
Overrides
| Improve this Doc View SourceFlushAsync(CancellationToken)
Declaration
public override Task FlushAsync(CancellationToken token)
Parameters
Type | Name | Description |
---|---|---|
CancellationToken | token |
Returns
Type | Description |
---|---|
Task |
Overrides
| Improve this Doc View SourceGetMemory(Int32)
Declaration
public Memory<byte> GetMemory(int sizeHint = 0)
Parameters
Type | Name | Description |
---|---|---|
Int32 | sizeHint |
Returns
Type | Description |
---|---|
Memory<Byte> |
GetSpan(Int32)
Declaration
public Span<byte> GetSpan(int sizeHint = 0)
Parameters
Type | Name | Description |
---|---|---|
Int32 | sizeHint |
Returns
Type | Description |
---|---|
Span<Byte> |
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(Int32)
Gets written content in the form of ReadOnlySequence<T> synchronously.
Declaration
public IReadOnlySequenceSource<byte> GetWrittenContent(int segmentSize)
Parameters
Type | Name | Description |
---|---|---|
Int32 | 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(CancellationToken))
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(Int32, CancellationToken)
Gets written content in the form of ReadOnlySequence<T> asynchronously.
Declaration
public ValueTask<IReadOnlySequenceSource<byte>> GetWrittenContentAsync(int segmentSize, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
Int32 | segmentSize | The size of the contiguous segment of file to be mapped to memory. |
CancellationToken | token | The token that can be used to cancel the operation. |
Returns
Type | Description |
---|---|
ValueTask<IReadOnlySequenceSource<Byte>> | The factory of ReadOnlySequence<T> instances. |
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException |
|
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(CancellationToken))
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(CancellationToken))
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(Byte[], Int32, Int32)
Declaration
public override int Read(byte[] buffer, int offset, int count)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count |
Returns
Type | Description |
---|---|
Int32 |
Overrides
| Improve this Doc View SourceRead(Span<Byte>)
Declaration
public override int Read(Span<byte> buffer)
Parameters
Type | Name | Description |
---|---|---|
Span<Byte> | buffer |
Returns
Type | Description |
---|---|
Int32 |
Overrides
| Improve this Doc View SourceReadAsync(Byte[], Int32, Int32, CancellationToken)
Declaration
public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken token)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count | |
CancellationToken | token |
Returns
Type | Description |
---|---|
Task<Int32> |
Overrides
| Improve this Doc View SourceReadAsync(Memory<Byte>, CancellationToken)
Declaration
public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken token)
Parameters
Type | Name | Description |
---|---|---|
Memory<Byte> | buffer | |
CancellationToken | token |
Returns
Type | Description |
---|---|
ValueTask<Int32> |
Overrides
| Improve this Doc View SourceReadByte()
Declaration
public override int ReadByte()
Returns
Type | Description |
---|---|
Int32 |
Overrides
| Improve this Doc View SourceSeek(Int64, SeekOrigin)
Declaration
public override long Seek(long offset, SeekOrigin origin)
Parameters
Type | Name | Description |
---|---|---|
Int64 | offset | |
SeekOrigin | origin |
Returns
Type | Description |
---|---|
Int64 |
Overrides
| Improve this Doc View SourceSetLength(Int64)
Declaration
public override void SetLength(long value)
Parameters
Type | Name | Description |
---|---|---|
Int64 | value |
Overrides
| Improve this Doc View SourceTryGetWrittenContent(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 |
---|---|
Boolean | 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.
Write(Byte[], Int32, Int32)
Declaration
public override void Write(byte[] buffer, int offset, int count)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count |
Overrides
| Improve this Doc View SourceWrite(ReadOnlySpan<Byte>)
Declaration
public override void Write(ReadOnlySpan<byte> buffer)
Parameters
Type | Name | Description |
---|---|---|
ReadOnlySpan<Byte> | buffer |
Overrides
| Improve this Doc View SourceWriteAsync(Byte[], Int32, Int32, CancellationToken)
Declaration
public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken token)
Parameters
Type | Name | Description |
---|---|---|
Byte[] | buffer | |
Int32 | offset | |
Int32 | count | |
CancellationToken | token |
Returns
Type | Description |
---|---|
Task |
Overrides
| Improve this Doc View SourceWriteAsync(ReadOnlyMemory<Byte>, CancellationToken)
Declaration
public override ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken token = default(CancellationToken))
Parameters
Type | Name | Description |
---|---|---|
ReadOnlyMemory<Byte> | buffer | |
CancellationToken | token |
Returns
Type | Description |
---|---|
ValueTask |
Overrides
| Improve this Doc View SourceWriteByte(Byte)
Declaration
public override void WriteByte(byte value)
Parameters
Type | Name | Description |
---|---|---|
Byte | value |