Meziantou.FrameworkPooledMemoryStream Class
A MemoryStream whose storage is a chain of pooled byte arrays rented from a process-wide pool shared by all instances. The stream also implements IBufferWriter<T> (explicit implementation), so it can be used as a destination for APIs such as Utf8JsonWriter.
public sealed class PooledMemoryStream : MemoryStream, IBufferWriter<byte>Remarks
Unlike MemoryStream, growing the stream never reallocates and copies a single backing array: new pooled blocks are appended to a chain. Blocks are only ever rented in the discrete sizes configured by PooledMemoryStreamOptions, which keeps the shared pool buckets small and reusable.
Buffers (including the array returned by PooledMemoryStream.GetBuffer / PooledMemoryStream.TryGetBuffer, and the spans returned by the IBufferWriter<T> members) are owned by the stream and are returned to the pool when the stream is disposed. Accessing them after the stream is disposed is undefined behavior.
An array returned by PooledMemoryStream.GetBuffer / PooledMemoryStream.TryGetBuffer is never returned to the pool before the stream is disposed, so no other stream can rent it while the caller may still hold it. As with MemoryStream, it stays the stream's storage (shrinking the stream with PooledMemoryStream.SetLength or PooledMemoryStream.Capacity keeps it, so later writes overwrite it) until a later PooledMemoryStream.GetBuffer / PooledMemoryStream.TryGetBuffer call has to consolidate several blocks into a new array; from then on it remains valid but no longer reflects the contents of the stream.
Because the storage is a chain of blocks rather than one array, the stream is not bounded by Array.MaxLength: it can hold as many bytes as memory allows. The members that have to materialize the contents as a single array (PooledMemoryStream.ToArray, PooledMemoryStream.GetBuffer and PooledMemoryStream.TryGetBuffer) are still bounded by it and throw an InvalidOperationException on a longer stream.
This type is not thread-safe; the shared pool is.
- Inheritance
MemoryStreamPooledMemoryStream- Implements
Constructors
| Name | Description |
|---|---|
| PooledMemoryStream() | Initializes a new instance using PooledMemoryStreamOptions.Default. |
| PooledMemoryStream(PooledMemoryStreamOptions) | Initializes a new instance using the specified options. |
| PooledMemoryStream(PooledMemoryStreamOptions, int) | Initializes a new instance using the specified options and reserves at least initialCapacity bytes. |
| PooledMemoryStream(int) | Initializes a new instance using PooledMemoryStreamOptions.Default and reserves at least initialCapacity bytes. |
PooledMemoryStream overloads
PooledMemoryStream()
PooledMemoryStream.csInitializes a new instance using PooledMemoryStreamOptions.Default.
public PooledMemoryStream()PooledMemoryStream(PooledMemoryStreamOptions)
PooledMemoryStream.csInitializes a new instance using the specified options.
public PooledMemoryStream(PooledMemoryStreamOptions options)Parameters
optionsPooledMemoryStreamOptions
PooledMemoryStream(PooledMemoryStreamOptions, int)
PooledMemoryStream.csInitializes a new instance using the specified options and reserves at least initialCapacity bytes.
public PooledMemoryStream(PooledMemoryStreamOptions options, int initialCapacity)Parameters
optionsPooledMemoryStreamOptionsinitialCapacityint
PooledMemoryStream(int)
PooledMemoryStream.csInitializes a new instance using PooledMemoryStreamOptions.Default and reserves at least initialCapacity bytes.
public PooledMemoryStream(int initialCapacity)Parameters
initialCapacityint
Properties
| Name | Description |
|---|---|
| CanRead | Gets a value indicating whether the current stream supports reading. |
| CanSeek | Gets a value indicating whether the current stream supports seeking. |
| CanWrite | Gets a value indicating whether the current stream supports writing. |
| Capacity | Gets or sets the number of bytes allocated for this stream. |
| Length | Gets the length of the stream in bytes. |
| Position | Gets or sets the current position within the stream. |
CanRead
PooledMemoryStream.csCanSeek
PooledMemoryStream.csCanWrite
PooledMemoryStream.csCapacity
PooledMemoryStream.csGets or sets the number of bytes allocated for this stream.
public override int Capacity { get; set; }Property value
Exceptions
ArgumentOutOfRangeException- A capacity is set that is negative or less than the current length of the stream.
ObjectDisposedException- The current stream is closed.
NotSupportedExceptionsetis invoked on a stream whose capacity cannot be modified.
Length
PooledMemoryStream.csGets the length of the stream in bytes.
public override long Length { get; }Position
PooledMemoryStream.csGets or sets the current position within the stream.
public override long Position { get; set; }Property value
Exceptions
ArgumentOutOfRangeException- The position is set to a negative value or a value greater than Int32.MaxValue.
ObjectDisposedException- The stream is closed.
Methods
| Name | Description |
|---|---|
| CopyTo(Stream, int) | Reads the bytes from the current memory stream and writes them to another stream, using a specified buffer size. |
| CopyToAsync(Stream, int, CancellationToken) | Asynchronously reads all the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token. |
| Flush() | Overrides the Stream.Flush method so that no action is performed. |
| FlushAsync(CancellationToken) | Asynchronously clears all buffers for this stream, and monitors cancellation requests. |
| GetBuffer() | Consolidates the stream contents into a single contiguous array and returns it. The returned array may be larger than PooledMemoryStream.Length; only the first PooledMemoryStream.Length bytes are valid. The array is owned by the stream and is returned to the pool when the stream is disposed, not before: if a later operation replaces it, it stays valid but no longer reflects the contents of the stream. |
| Read(byte[], int, int) | Reads a block of bytes from the current stream and writes the data to a buffer. |
| Read(Span<byte>) | Reads a sequence of bytes from the current memory stream and advances the position within the memory stream by the number of bytes read. |
| ReadAsync(byte[], int, int, 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. |
| ReadAsync(Memory<byte>, CancellationToken) | Asynchronously reads a sequence of bytes from the current memory stream, writes the sequence into destination, advances the position within the memory stream by the number of bytes read, and monitors cancellation requests. |
| ReadByte() | Reads a byte from the current stream. |
| Seek(long, SeekOrigin) | Sets the position within the current stream to the specified value. |
| SetLength(long) | Sets the length of the current stream to the specified value. |
| System.Buffers.IBufferWriter<System.Byte>.Advance(int) | |
| System.Buffers.IBufferWriter<System.Byte>.GetMemory(int) | Returns a contiguous region of memory to write to. Data written through IBufferWriter<T> is always appended at the end of the stream (after PooledMemoryStream.Length); after Advance, the PooledMemoryStream.Position is moved to the new end. |
| System.Buffers.IBufferWriter<System.Byte>.GetSpan(int) | Returns a Span<T> to write to that is at least the requested size (specified by sizeHint). |
| ToArray() | Returns a new array containing the contents of the stream. |
| TryGetBuffer(ArraySegment<byte>) | Returns the array of unsigned bytes from which this stream was created. The return value indicates whether the conversion succeeded. |
| Write(byte[], int, int) | Writes a block of bytes to the current stream using data read from a buffer. |
| Write(ReadOnlySpan<byte>) | Writes the sequence of bytes contained in source into the current memory stream and advances the current position within this memory stream by the number of bytes written. |
| WriteAsync(byte[], int, int, 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. |
| WriteAsync(ReadOnlyMemory<byte>, CancellationToken) | Asynchronously writes the sequence of bytes contained in source into the current memory stream, advances the current position within this memory stream by the number of bytes written, and monitors cancellation requests. |
| WriteByte(byte) | Writes a byte to the current stream at the current position. |
| WriteTo(Stream) | Writes the entire contents of this stream to another stream, regardless of the current position. |
CopyTo(Stream, int)
PooledMemoryStream.csReads the bytes from the current memory stream and writes them to another stream, using a specified buffer size.
Parameters
destinationStream- The stream to which the contents of the current memory stream will be copied.
bufferSizeint- The size of the buffer. This value must be greater than zero. The default size is 81920.
Exceptions
ArgumentNullExceptiondestinationisnull.ArgumentOutOfRangeExceptionbufferSizeis not a positive number.ObjectDisposedException- Either the underlying memory stream or the
destinationstream is closed. NotSupportedException- The underlying memory stream is unreadable. -or- The
destinationstream is unwritable.
CopyToAsync(Stream, int, CancellationToken)
PooledMemoryStream.csAsynchronously reads all the bytes from the current stream and writes them to another stream, using a specified buffer size and cancellation token.
public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken cancellationToken)Parameters
destinationStream- The stream to which the contents of the current stream will be copied.
bufferSizeint- The size, in bytes, of the buffer. This value must be greater than zero.
cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
Task A task that represents the asynchronous copy operation.
Exceptions
ArgumentNullExceptiondestinationisnull.ArgumentOutOfRangeExceptionbufferSizeis negative or zero.ObjectDisposedException- Either the current stream or the destination stream is disposed.
NotSupportedException- The current stream does not support reading, or the destination stream does not support writing.
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
Flush()
PooledMemoryStream.csOverrides the Stream.Flush method so that no action is performed.
public override void Flush()FlushAsync(CancellationToken)
PooledMemoryStream.csAsynchronously clears all buffers for this stream, and monitors cancellation requests.
public override Task FlushAsync(CancellationToken cancellationToken)Parameters
cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
Task A task that represents the asynchronous flush operation.
Exceptions
ObjectDisposedException- The stream has been disposed.
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
GetBuffer()
PooledMemoryStream.csConsolidates the stream contents into a single contiguous array and returns it. The returned array may be larger than PooledMemoryStream.Length; only the first PooledMemoryStream.Length bytes are valid. The array is owned by the stream and is returned to the pool when the stream is disposed, not before: if a later operation replaces it, it stays valid but no longer reflects the contents of the stream.
public override byte[] GetBuffer()Read overloads
Read(byte[], int, int)
PooledMemoryStream.csReads a block of bytes from the current stream and writes the data to a buffer.
Parameters
bufferbyte[]- When this method returns, contains the specified byte array with the values between
offsetand (offset+count- 1) replaced by the characters read from the current stream. offsetint- The zero-based byte offset in
bufferat which to begin storing data from the current stream. countint- The maximum number of bytes to read.
Returns
int The total number of bytes written into the buffer. This can be less than the number of bytes requested if that number of bytes are not currently available, or zero if the end of the stream is reached before any bytes are read.
Exceptions
ArgumentNullExceptionbufferisnull.ArgumentOutOfRangeExceptionoffsetorcountis negative.ArgumentExceptionoffsetsubtracted from the buffer length is less thancount.ObjectDisposedException- The current stream instance is closed.
Read(Span<byte>)
PooledMemoryStream.csReads a sequence of bytes from the current memory stream and advances the position within the memory stream by the number of bytes read.
Parameters
bufferSpan<byte>
Returns
int The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the memory stream has been reached.
ReadAsync overloads
ReadAsync(byte[], int, int, CancellationToken)
PooledMemoryStream.csAsynchronously 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.
public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)Parameters
bufferbyte[]- The buffer to write the data into.
offsetint- The byte offset in
bufferat which to begin writing data from the stream. countint- The maximum number of bytes to read.
cancellationTokenCancellationToken- The token to monitor for cancellation requests. The default value is
CancellationToken.None.
Returns
Task<int> A task that represents the asynchronous read operation. The value of the TResult parameter contains the total number of bytes read into the buffer. The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the stream has been reached.
Exceptions
ArgumentNullExceptionbufferisnull.ArgumentOutOfRangeExceptionoffsetorcountis negative.ArgumentException- The sum of
offsetandcountis larger than the buffer length. NotSupportedException- The stream does not support reading.
ObjectDisposedException- The stream has been disposed.
InvalidOperationException- The stream is currently in use by a previous read operation.
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
ReadAsync(Memory<byte>, CancellationToken)
PooledMemoryStream.csAsynchronously reads a sequence of bytes from the current memory stream, writes the sequence into destination, advances the position within the memory stream by the number of bytes read, and monitors cancellation requests.
public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)Parameters
bufferMemory<byte>cancellationTokenCancellationToken- The token to monitor for cancellation requests. The default value is
CancellationToken.None.
Returns
ValueTask<int> A task that represents the asynchronous read operation. The value of its ValueTask<TResult>.Result property contains the total number of bytes read into the destination. The result value can be less than the number of bytes allocated in destination if that many bytes are not currently available, or it can be 0 (zero) if the end of the memory stream has been reached.
Exceptions
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
ReadByte()
PooledMemoryStream.csReads a byte from the current stream.
public override int ReadByte()Returns
int The byte cast to a Int32, or -1 if the end of the stream has been reached.
Exceptions
ObjectDisposedException- The current stream instance is closed.
Seek(long, SeekOrigin)
PooledMemoryStream.csSets the position within the current stream to the specified value.
public override long Seek(long offset, SeekOrigin loc)Parameters
offsetlong- The new position within the stream. This is relative to the
locparameter, and can be positive or negative. locSeekOrigin- A value of type
SeekOrigin, which acts as the seek reference point.
Returns
long The new position within the stream, calculated by combining the initial reference point and the offset.
Exceptions
IOException- Seeking is attempted before the beginning of the stream.
ArgumentOutOfRangeExceptionoffsetis greater than Int32.MaxValue.ArgumentException- There is an invalid
SeekOrigin. -or-offsetcaused an arithmetic overflow. ObjectDisposedException- The current stream instance is closed.
SetLength(long)
PooledMemoryStream.csSets the length of the current stream to the specified value.
Parameters
valuelong- The value at which to set the length.
Exceptions
NotSupportedException- The current stream is not resizable and
valueis larger than the current capacity. -or- The current stream does not support writing. ArgumentOutOfRangeExceptionvalueis negative or is greater than the maximum length of theMemoryStream, where the maximum length is (Int32.MaxValue -origin), andoriginis the index into the underlying buffer at which the stream starts.
System.Buffers.IBufferWriter<System.Byte>.Advance(int)
PooledMemoryStream.csSystem.Buffers.IBufferWriter<System.Byte>.GetMemory(int)
PooledMemoryStream.csReturns a contiguous region of memory to write to. Data written through IBufferWriter<T> is always appended at the end of the stream (after PooledMemoryStream.Length); after Advance, the PooledMemoryStream.Position is moved to the new end.
Memory<byte> IBufferWriter<byte>.GetMemory(int sizeHint)System.Buffers.IBufferWriter<System.Byte>.GetSpan(int)
PooledMemoryStream.csReturns a Span<T> to write to that is at least the requested size (specified by sizeHint).
Span<byte> IBufferWriter<byte>.GetSpan(int sizeHint)Parameters
Returns
Span<byte> A Span<T> of at least the size sizeHint. If sizeHint is 0, returns a non-empty buffer.
ToArray()
PooledMemoryStream.csReturns a new array containing the contents of the stream.
public override byte[] ToArray()TryGetBuffer(ArraySegment<byte>)
PooledMemoryStream.csReturns the array of unsigned bytes from which this stream was created. The return value indicates whether the conversion succeeded.
public override bool TryGetBuffer(out ArraySegment<byte> buffer)Parameters
bufferArraySegment<byte>- When this method returns
true, the byte array segment from which this stream was created; when this method returnsfalse, this parameter is set todefault.
Returns
bool true if the buffer is exposable; otherwise, false.
Exceptions
InvalidOperationException- The stream is longer than
Array.MaxLength.
Write overloads
Write(byte[], int, int)
PooledMemoryStream.csWrites a block of bytes to the current stream using data read from a buffer.
Parameters
bufferbyte[]- The buffer to write data from.
offsetint- The zero-based byte offset in
bufferat which to begin copying bytes to the current stream. countint- The maximum number of bytes to write.
Exceptions
ArgumentNullExceptionbufferisnull.NotSupportedException- The stream does not support writing. For additional information see
Stream.CanWrite. -or- The current position is closer thancountbytes to the end of the stream, and the capacity cannot be modified. ArgumentExceptionoffsetsubtracted from the buffer length is less thancount.ArgumentOutOfRangeExceptionoffsetorcountare negative.IOException- An I/O error occurs.
ObjectDisposedException- The current stream instance is closed.
Write(ReadOnlySpan<byte>)
PooledMemoryStream.csWrites the sequence of bytes contained in source into the current memory stream and advances the current position within this memory stream by the number of bytes written.
public override void Write(ReadOnlySpan<byte> buffer)Parameters
bufferReadOnlySpan<byte>
WriteAsync overloads
WriteAsync(byte[], int, int, CancellationToken)
PooledMemoryStream.csAsynchronously 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.
public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)Parameters
bufferbyte[]- The buffer to write data from.
offsetint- The zero-based byte offset in
bufferfrom which to begin copying bytes to the stream. countint- The maximum number of bytes to write.
cancellationTokenCancellationToken- The token to monitor for cancellation requests. The default value is
CancellationToken.None.
Returns
Task A task that represents the asynchronous write operation.
Exceptions
ArgumentNullExceptionbufferisnull.ArgumentOutOfRangeExceptionoffsetorcountis negative.ArgumentException- The sum of
offsetandcountis larger than the buffer length. NotSupportedException- The stream does not support writing.
ObjectDisposedException- The stream has been disposed.
InvalidOperationException- The stream is currently in use by a previous write operation.
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
WriteAsync(ReadOnlyMemory<byte>, CancellationToken)
PooledMemoryStream.csAsynchronously writes the sequence of bytes contained in source into the current memory stream, advances the current position within this memory stream by the number of bytes written, and monitors cancellation requests.
public override ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default)Parameters
bufferReadOnlyMemory<byte>cancellationTokenCancellationToken- The token to monitor for cancellation requests. The default value is
CancellationToken.None.
Returns
ValueTask A task that represents the asynchronous write operation.
Exceptions
OperationCanceledException- The cancellation token was canceled. This exception is stored into the returned task.
WriteByte(byte)
PooledMemoryStream.csWrites a byte to the current stream at the current position.
Parameters
valuebyte- The byte to write.
Exceptions
NotSupportedException- The stream does not support writing. For additional information see
Stream.CanWrite. -or- The current position is at the end of the stream, and the capacity cannot be modified. ObjectDisposedException- The current stream is closed.