PooledBuffer<T>

Namespace: SnowBank.Buffers · struct

Implements: IDisposable, IBufferWriter<T>

Lightweight wrapper over a pooled buffer, that can be resized whenever necessary.

Remarks

This type is intended for reusability where the caller will typically call Add, AddRange or GetSpan once per operation.

This instance should be disposed when the caller is done; otherwise, the currently allocated buffer will not be returned to the pool

Constructors

PooledBuffer<T>

PooledBuffer<T>(ArrayPool<T> pool, int initialCapacity)

Constructs a PooledBuffer with an initial capacity

• pool — Pool used to rent buffers
• initialCapacity — Initial capacity (or 0 for no initial buffer)

Properties

Capacity

int Capacity { get; }

Current buffer capacity

Item

T Item { get; }

Methods

Add

void Add(in T value)

Adds an item to the buffer

AddRange

void AddRange(ReadOnlySpan<T> values)

Adds a span of items to the buffer

Advance

void Advance(int count)

Notifies the buffer that count amount of data was written to the output Span/Memory

AsMemory

Memory<T> AsMemory()

Returns a memory region of all items previously written to this buffer.

AsSpan

Span<T> AsSpan()

Returns a span of all items previously written to this buffer.

Clear

void Clear()

Clears the buffer

CopyTo

void CopyTo(Span<T> destination, bool clear = false)

Copies items previously written to this buffer to the specified destination

• destination — Destination buffer, that must be large enough.
• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

Returns: true if the buffer was large enough; otherwise, false.

Create

static PooledBuffer<T> Create(ArrayPool<T> pool = null, int initialCapacity = 0)

Returns a new PooledBuffer

• pool — Pool used to rent buffers (use the shared pool if null)
• initialCapacity — Minimum initial capacity (or 0 for no initial buffer). Actual buffer size may be larger.

Dispose

void Dispose()

EnsureRemainingCapacity

void EnsureRemainingCapacity(int size)

Notifies the buffer that the caller intends to write a batch of items, and that it should pre-allocate the space now.

• size — Number of items that are expected to be written soon

If the remaining free capacity is not large enough, the buffer will resize its internal buffer.

The caller may decide to write fewer items, in which case some memory could be wasted. It could also decide to write more, in which case additional buffer resize may happen.

GetMemory

Memory<T> GetMemory(int size)

Gets a span for writing items to this buffer

• size — Required capacity, or 0 to return all the remaining space

Returns: Memory with the specified length

The caller MUST call Advance to specify how many items where actually written to the buffer!

The previous buffer will be recycled if it is not large enough.

GetSpan

Span<T> GetSpan(int size = 0)

Gets a span for writing items to this buffer

• size — Required capacity, or 0 to return all the remaining space

Returns: Span with the specified length

The caller MUST call Advance to specify how many items where actually written to the buffer!

If size if non-zero, the return span will have this exact size, even if there are more space available. This is different from the typical GetSpan behavior of returning a span that can be larger.

The previous buffer will be recycled if it is not large enough.

ToArray

T[] ToArray(bool clear = false)

Returns an array of items previously written to this buffer.

• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

ToHashSet

HashSet<T> ToHashSet(IEqualityComparer<T> comparer, bool clear = false)

Returns a list of items previously written to this buffer.

• comparer — Comparer for the elements in the set
• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

ToImmutableArray

ImmutableArray<T> ToImmutableArray(bool clear = false)

Returns a list of items previously written to this buffer.

• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

ToList

List<T> ToList(bool clear = false)

Returns a list of items previously written to this buffer.

• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

TryCopyTo

bool TryCopyTo(Span<T> destination, bool clear = false)

Copies items previously written to this buffer to the specified destination

• destination — Destination buffer, that must be large enough.
• clear — If true, this section of the buffer will be cleared, so that it can be reused immediately without leaking references.

Returns: true if the buffer was large enough; otherwise, false.

Fields

Buffer

T[] Buffer

Current buffer

Count

int Count

Number of items written to the buffer so far

Pool

readonly ArrayPool<T> Pool

Pool used to rent the buffers