Class ArrayPoolBufferWriterProvider<T>

Namespace

CryptoHives.Foundation.Memory.Pools

Assembly

CryptoHives.Foundation.Memory.dll

An immutable set of ArrayPoolBufferWriter<T> settings that hands out writers already configured with them.

public sealed class ArrayPoolBufferWriterProvider<T>

Type Parameters

T

The element type the writers accept.

Inheritance

object

ArrayPoolBufferWriterProvider<T>

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Remarks

Writers are configured when they are rented rather than when they are constructed, so pooled instances are interchangeable and a single pool serves an entire application. Declare one provider per use case and rent from it; every provider draws from the same pool unless it is given one of its own.

static readonly ArrayPoolBufferWriterProvider<byte> JsonWriters = new(maxChunkBytes: 1 << 20);
static readonly ArrayPoolBufferWriterProvider<byte> SecretWriters = new(clearArray: true);
using var writer = JsonWriters.Rent();

A provider is immutable and safe to share; the writers it hands out are not, and belong to one caller until disposed.

Constructors

ArrayPoolBufferWriterProvider(bool, int, int, ObjectPool<ArrayPoolBufferWriter<T>>?)

Initializes a new instance of the ArrayPoolBufferWriterProvider<T> class.

public ArrayPoolBufferWriterProvider(bool clearArray = false, int defaultChunkBytes = 256, int maxChunkBytes = 65536, ObjectPool<ArrayPoolBufferWriter<T>>? pool = null)

Parameters

clearArray bool

Whether rented writers zero each buffer as it returns to the array pool.

defaultChunkBytes int

The size, in bytes, of the first chunk a rented writer takes.

maxChunkBytes int

The ceiling, in bytes, the chunk size ramps up to. A value at or below defaultChunkBytes disables the ramp, pinning every chunk to that size.

pool ObjectPool<ArrayPoolBufferWriter<T>>

The pool to draw from. Defaults to the shared pool for T, which is what lets differently configured providers share one set of instances. Pass a pool from CreateBufferWriterPool<T>(int) only when a use case genuinely needs to be isolated from the rest of the application.

Remarks

The two budgets are bytes, not elements, so a profile means the same thing whatever T is. See MaxChunkBytes for why the default ceiling is 64 KiB.

Exceptions

ArgumentOutOfRangeException

defaultChunkBytes is less than one.

Methods

Rent()

Rents a writer carrying this provider's settings.

public ArrayPoolBufferWriter<T> Rent()

Returns

ArrayPoolBufferWriter<T>

A writer in its just-constructed state, configured and attached to the pool.

Remarks

Dispose the writer as usual and it returns itself to the pool. Do not use it afterwards: a returned instance does not throw, it silently becomes whatever the next renter is doing.