Class FileBufferingWriter

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

Inheritance

object

MarshalByRefObject

Stream

ModernStream

FileBufferingWriter

Implements

IAsyncDisposable

IFlushable

IGrowableBuffer<byte>

IBufferWriter<byte>

IConsumer<ReadOnlySpan<byte>>

ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>

IFunctional

IDisposable

IResettable

IDynamicInterfaceCastable

Inherited Members

ModernStream.Read(byte[], int, int)

ModernStream.ReadAsync(byte[], int, int, CancellationToken)

ModernStream.BeginRead(byte[], int, int, AsyncCallback, object)

ModernStream.EndRead(IAsyncResult)

ModernStream.ReadByte()

ModernStream.Write(byte[], int, int)

ModernStream.WriteByte(byte)

ModernStream.WriteAsync(byte[], int, int, CancellationToken)

ModernStream.BeginWrite(byte[], int, int, AsyncCallback, object)

ModernStream.EndWrite(IAsyncResult)

Stream.Null

Stream.CopyTo(Stream)

Stream.CopyToAsync(Stream)

Stream.CopyToAsync(Stream, int)

Stream.CopyToAsync(Stream, CancellationToken)

Stream.Dispose()

Stream.Close()

Stream.DisposeAsync()

Stream.FlushAsync()

Stream.ReadAsync(byte[], int, int)

Stream.ReadExactlyAsync(Memory<byte>, CancellationToken)

Stream.ReadExactlyAsync(byte[], int, int, CancellationToken)

Stream.ReadAtLeastAsync(Memory<byte>, int, bool, CancellationToken)

Stream.WriteAsync(byte[], int, int)

Stream.ReadExactly(Span<byte>)

Stream.ReadExactly(byte[], int, int)

Stream.ReadAtLeast(Span<byte>, int, bool)

Stream.Synchronized(Stream)

Stream.CanTimeout

Stream.ReadTimeout

Stream.WriteTimeout

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Namespace: DotNext.IO

Assembly: DotNext.IO.dll

Syntax

public sealed class FileBufferingWriter : ModernStream, IAsyncDisposable, IFlushable, IGrowableBuffer<byte>, IBufferWriter<byte>, IConsumer<ReadOnlySpan<byte>>, ISupplier<ReadOnlyMemory<byte>, CancellationToken, ValueTask>, IFunctional, 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

FileBufferingWriter(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 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().
bool	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.

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

CanRead

Declaration

public override bool CanRead { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanRead

CanSeek

Declaration

public override bool CanSeek { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanSeek

CanWrite

Declaration

public override bool CanWrite { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanWrite

Length

Declaration

public override long Length { get; }

Property Value

Type	Description
long

Overrides

Stream.Length

Position

Declaration

public override long Position { get; set; }

Property Value

Type	Description
long

Overrides

Stream.Position

Methods

Advance(int)

Declaration

public void Advance(int count)

Parameters

Type	Name	Description
int	count

Clear(bool)

Removes all written data.

Declaration

public void Clear(bool reuseBuffer = true)

Parameters

Type	Name	Description
bool	reuseBuffer	true to keep internal buffer alive; otherwise, false.

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

Stream.CopyTo(Stream, int)

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

Stream.CopyToAsync(Stream, int, CancellationToken)

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 : IConsumer<ReadOnlySpan<byte>>, allows ref struct

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)

Declaration

protected override void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing

Overrides

Stream.Dispose(bool)

Flush()

Declaration

public override void Flush()

Overrides

Stream.Flush()

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)

Declaration

public override Task FlushAsync(CancellationToken token)

Parameters

Type	Name	Description
CancellationToken	token

Returns

Type	Description
Task

Overrides

Stream.FlushAsync(CancellationToken)

GetMemory(int)

Declaration

public Memory<byte> GetMemory(int sizeHint = 0)

Parameters

Type	Name	Description
int	sizeHint

Returns

Type	Description
Memory<byte>

GetSpan(int)

Declaration

public Span<byte> GetSpan(int sizeHint = 0)

Parameters

Type	Name	Description
int	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(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	segmentSize is less than or equal to zero.
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	range is invalid.
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	range is invalid.
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>)

Declaration

public override int Read(Span<byte> data)

Parameters

Type	Name	Description
Span<byte>	data

Returns

Type	Description
int

Overrides

ModernStream.Read(Span<byte>)

ReadAsync(Memory<byte>, CancellationToken)

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>

Overrides

ModernStream.ReadAsync(Memory<byte>, CancellationToken)

Seek(long, SeekOrigin)

Declaration

public override long Seek(long offset, SeekOrigin origin)

Parameters

Type	Name	Description
long	offset
SeekOrigin	origin

Returns

Type	Description
long

Overrides

Stream.Seek(long, SeekOrigin)

SetLength(long)

Declaration

public override void SetLength(long value)

Parameters

Type	Name	Description
long	value

Overrides

Stream.SetLength(long)

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

Declaration

public override void Write(ReadOnlySpan<byte> input)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	input

Overrides

ModernStream.Write(ReadOnlySpan<byte>)

WriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Declaration

public override ValueTask WriteAsync(ReadOnlyMemory<byte> input, CancellationToken token = default)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	input
CancellationToken	token

Returns

Type	Description
ValueTask

Overrides

ModernStream.WriteAsync(ReadOnlyMemory<byte>, CancellationToken)

Implements

IAsyncDisposable

IFlushable

IGrowableBuffer<T>

IBufferWriter<T>

IConsumer<T>

ISupplier<T1, T2, TResult>

IFunctional

IDisposable

IResettable

IDynamicInterfaceCastable

Extension Methods

BasicExtensions.As<T>(T)

BasicExtensions.IsBetween<T, TLowerBound, TUpperBound>(T, TLowerBound, TUpperBound)

BasicExtensions.IsOneOf<T>(T, params ReadOnlySpan<T>)

BufferWriter.Encode(IBufferWriter<byte>, ReadOnlySpan<char>, in EncodingContext, LengthFormat?)

BufferWriter.Format<T>(IBufferWriter<byte>, T, in EncodingContext, LengthFormat?, ReadOnlySpan<char>, IFormatProvider?, MemoryAllocator<char>?)

BufferWriter.Format<T>(IBufferWriter<byte>, T, LengthFormat?, ReadOnlySpan<char>, IFormatProvider?)

BufferWriter.Write<T>(IBufferWriter<T>, in ReadOnlySequence<T>)

StreamExtensions.CopyToAsync(Stream, IBufferWriter<byte>, int, CancellationToken)

StreamExtensions.CopyToAsync(Stream, IBufferWriter<byte>, long, int, CancellationToken)

StreamExtensions.CopyToAsync(Stream, Stream, long, Memory<byte>, CancellationToken)

StreamExtensions.CopyToAsync(Stream, Stream, Memory<byte>, CancellationToken)

StreamExtensions.CopyToAsync<TConsumer>(Stream, TConsumer, long, Memory<byte>, CancellationToken)

StreamExtensions.CopyToAsync<TConsumer>(Stream, TConsumer, Memory<byte>, CancellationToken)

StreamExtensions.DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)

StreamExtensions.DecodeAsync(Stream, DecodingContext, LengthFormat, Memory<char>, Memory<byte>, CancellationToken)

StreamExtensions.EncodeAsync(Stream, ReadOnlyMemory<char>, EncodingContext, LengthFormat?, Memory<byte>, CancellationToken)

StreamExtensions.FormatAsync<T>(Stream, T, EncodingContext, LengthFormat?, Memory<byte>, string?, IFormatProvider?, MemoryAllocator<char>?, CancellationToken)

StreamExtensions.FormatAsync<T>(Stream, T, LengthFormat?, Memory<byte>, string?, IFormatProvider?, CancellationToken)

StreamExtensions.ParseAsync<T>(Stream, LengthFormat, Memory<byte>, NumberStyles, IFormatProvider?, CancellationToken)

StreamExtensions.ParseAsync<T>(Stream, LengthFormat, Memory<byte>, IFormatProvider?, CancellationToken)

StreamExtensions.ParseAsync<TArg, TResult>(Stream, TArg, Func<ReadOnlySpan<char>, TArg, TResult>, DecodingContext, LengthFormat, Memory<byte>, MemoryAllocator<char>?, CancellationToken)

StreamExtensions.ReadAllAsync(Stream, int, MemoryAllocator<byte>?, CancellationToken)

StreamExtensions.ReadAsync<T>(Stream, Memory<byte>, CancellationToken)

StreamExtensions.ReadBigEndianAsync<T>(Stream, Memory<byte>, CancellationToken)

StreamExtensions.ReadBlockAsync(Stream, LengthFormat, MemoryAllocator<byte>?, CancellationToken)

StreamExtensions.ReadExactlyAsync(Stream, long, int, MemoryAllocator<byte>?, CancellationToken)

StreamExtensions.ReadLittleEndianAsync<T>(Stream, Memory<byte>, CancellationToken)

StreamExtensions.ReadUtf8(Stream, Span<byte>, IBufferWriter<char>)

StreamExtensions.ReadUtf8Async(Stream, Memory<byte>, IBufferWriter<char>, CancellationToken)

StreamExtensions.ReadUtf8Async<TArg>(Stream, Memory<byte>, Memory<char>, Func<ReadOnlyMemory<char>, TArg, CancellationToken, ValueTask>, TArg, CancellationToken)

StreamExtensions.ReadUtf8<TArg>(Stream, Span<byte>, Span<char>, ReadOnlySpanAction<char, TArg>, TArg)

StreamExtensions.Slice(Stream, long, long)

StreamExtensions.WriteAsync(Stream, ReadOnlySequence<byte>, CancellationToken)

StreamExtensions.WriteAsync(Stream, ReadOnlyMemory<byte>, LengthFormat, Memory<byte>, CancellationToken)

StreamExtensions.WriteAsync<T>(Stream, T, Memory<byte>, CancellationToken)

StreamExtensions.WriteBigEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)

StreamExtensions.WriteLittleEndianAsync<T>(Stream, T, Memory<byte>, CancellationToken)