Class FileBufferingWriter

Represents builder of contiguous block of memory that may switch to file as its backing store.

Inheritance
Object
MarshalByRefObject
Stream
FileBufferingWriter
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 Source

FileBufferingWriter(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 memoryThreshold.
String tempDir

The location of the directory to write buffered contents to. When unspecified, uses the value specified by the environment variable ASPNETCORE_TEMP if available, otherwise uses the value returned by GetTempPath().
Boolean asyncIO

true if you will use asynchronous methods of the instance; otherwise, false.
Exceptions
Type Condition
ArgumentOutOfRangeException

memoryThreshold is less than or equal to zero; or initialCapacity is less than zero or greater than memoryThreshold.
DirectoryNotFoundException

tempDir doesn't exist.

Properties

| Improve this Doc View Source

AllocationCounter

Sets the counter used to report allocation of internal buffer.

Declaration
public EventCounter AllocationCounter { set; }
Property Value
Type Description
EventCounter
| Improve this Doc View Source

CanRead

Declaration
public override bool CanRead { get; }
Property Value
Type Description
Boolean
Overrides
| Improve this Doc View Source

CanSeek

Declaration
public override bool CanSeek { get; }
Property Value
Type Description
Boolean
Overrides
| Improve this Doc View Source

CanTimeout

Declaration
public override bool CanTimeout { get; }
Property Value
Type Description
Boolean
Overrides
| Improve this Doc View Source

CanWrite

Declaration
public override bool CanWrite { get; }
Property Value
Type Description
Boolean
Overrides
| Improve this Doc View Source

Length

Declaration
public override long Length { get; }
Property Value
Type Description
Int64
Overrides
| Improve this Doc View Source

Position

Declaration
public override long Position { get; set; }
Property Value
Type Description
Int64
Overrides

Methods

| Improve this Doc View Source

Advance(Int32)

Declaration
public void Advance(int count)
Parameters
Type Name Description
Int32 count
| Improve this Doc View Source

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 Source

BeginWrite(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 Source

Clear()

Removes all written data.

Declaration
public void Clear()
Exceptions
Type Condition
InvalidOperationException

Attempt to cleanup this writer while reading.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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 Source

CopyTo(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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

Dispose(Boolean)

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
Boolean disposing
Overrides
| Improve this Doc View Source

DisposeAsync()

Declaration
public override ValueTask DisposeAsync()
Returns
Type Description
ValueTask
Overrides
| Improve this Doc View Source

EndRead(IAsyncResult)

Declaration
public override int EndRead(IAsyncResult asyncResult)
Parameters
Type Name Description
IAsyncResult asyncResult
Returns
Type Description
Int32
Overrides
| Improve this Doc View Source

EndWrite(IAsyncResult)

Declaration
public override void EndWrite(IAsyncResult ar)
Parameters
Type Name Description
IAsyncResult ar
Overrides
| Improve this Doc View Source

Flush()

Declaration
public override void Flush()
Overrides
| Improve this Doc View Source

FlushAsync(CancellationToken)

Declaration
public override Task FlushAsync(CancellationToken token)
Parameters
Type Name Description
CancellationToken token
Returns
Type Description
Task
Overrides
| Improve this Doc View Source

GetMemory(Int32)

Declaration
public Memory<byte> GetMemory(int sizeHint = 0)
Parameters
Type Name Description
Int32 sizeHint
Returns
Type Description
Memory<Byte>
| Improve this Doc View Source

GetSpan(Int32)

Declaration
public Span<byte> GetSpan(int sizeHint = 0)
Parameters
Type Name Description
Int32 sizeHint
Returns
Type Description
Span<Byte>
| Improve this Doc View Source

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.
| Improve this Doc View Source

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

segmentSize is less than or equal to zero.
InvalidOperationException

The memory manager is already obtained but not disposed.
| Improve this Doc View Source

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

range is invalid.
OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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

segmentSize is less than or equal to zero.
OperationCanceledException

The operation has been canceled.
| Improve this Doc View Source

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

range is invalid.
OutOfMemoryException

The size of buffered content is too large and cannot be represented by Memory<T> instance.
| Improve this Doc View Source

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.
| Improve this Doc View Source

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 Source

Read(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 Source

ReadAsync(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 Source

ReadAsync(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 Source

ReadByte()

Declaration
public override int ReadByte()
Returns
Type Description
Int32
Overrides
| Improve this Doc View Source

Seek(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 Source

SetLength(Int64)

Declaration
public override void SetLength(long value)
Parameters
Type Name Description
Int64 value
Overrides
| Improve this Doc View Source

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
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.

| Improve this Doc View Source

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 Source

Write(ReadOnlySpan<Byte>)

Declaration
public override void Write(ReadOnlySpan<byte> buffer)
Parameters
Type Name Description
ReadOnlySpan<Byte> buffer
Overrides
| Improve this Doc View Source

WriteAsync(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 Source

WriteAsync(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 Source

WriteByte(Byte)

Declaration
public override void WriteByte(byte value)
Parameters
Type Name Description
Byte value
Overrides

Implements

IGrowableBuffer<>

Extension Methods