Class PoolFactory

Namespace

CryptoHives.Foundation.Memory.Pools

Assembly

CryptoHives.Foundation.Memory.dll

A factory of object pools.

public static class PoolFactory

Inheritance

object

PoolFactory

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Remarks

This class makes it easy to create efficient object pools used to improve performance by reducing strain on the garbage collector.

Fields

DefaultMaxStringBuilderCapacity

The default ceiling, in characters, on how large a StringBuilder may be and still be worth pooling. One that has grown beyond this is discarded on return rather than retained.

public const int DefaultMaxStringBuilderCapacity = 8192

Field Value

int

DefaultStringBuilderCapacity

The default maximum number of StringBuilder instances a pool retains.

public const int DefaultStringBuilderCapacity = 1024

Field Value

int

InitialStringBuilderCapacity

The capacity, in characters, that a freshly created pooled StringBuilder starts with.

public const int InitialStringBuilderCapacity = 128

Field Value

int

Properties

SharedStringBuilderPool

Gets the shared pool of StringBuilder instances.

public static ObjectPool<StringBuilder> SharedStringBuilderPool { get; }

Property Value

ObjectPool<StringBuilder>

Methods

CreateBufferWriterPool<T>(int)

Creates a pool of ArrayPoolBufferWriter<T> instances.

public static ObjectPool<ArrayPoolBufferWriter<T>> CreateBufferWriterPool<T>(int maximumRetained = 0)

Parameters

maximumRetained int

The maximum number of writers to keep. Pass a value of zero or less to use the default, which scales with the processor count.

Returns

ObjectPool<ArrayPoolBufferWriter<T>>

The pool.

Type Parameters

T

The element type the writers accept.

Remarks

The pool takes no writer settings: those are applied when a writer is rented, so instances in the pool are interchangeable. Hand the returned pool to an ArrayPoolBufferWriterProvider<T> to rent from it.

Most callers do not need this. SharedBufferWriterPool<T>() is the pool every provider uses by default, and sharing it is what keeps the instance count down; create a separate one only to isolate a use case deliberately.

CreatePool<T>(Func<T>, Func<T, bool>, int)

Creates a pool for any reference type, driven by a pair of delegates.

public static ObjectPool<T> CreatePool<T>(Func<T> create, Func<T, bool> reset, int maximumRetained = 0) where T : class

Parameters

create Func<T>

Produces a new instance when the pool is empty.

reset Func<T, bool>

Restores an instance to a reusable state on return. Return true to let the pool keep it, or false to reject it.

maximumRetained int

The maximum number of instances to keep. Pass a value of zero or less to use the default, which scales with the processor count.

Returns

ObjectPool<T>

The pool.

Type Parameters

T

The type to pool.

Remarks

This exists so callers can pool types this package does not reference. It is how a Utf8JsonWriter gets pooled without the Memory package taking a dependency on System.Text.Json:

ObjectPool<Utf8JsonWriter> pool = PoolFactory.CreatePool(
    () => new Utf8JsonWriter(Stream.Null),
    writer => { writer.Reset(Stream.Null); return true; });

A rejected instance is dropped, not disposed. When reset returns false the pool simply lets the instance go, so if T holds unmanaged or pooled resources, reset must dispose it before returning false — otherwise those resources are never released.

Exceptions

ArgumentNullException

create or reset is null.

CreateStringBuilderPool(int, int)

Creates a pool of StringBuilder instances.

public static ObjectPool<StringBuilder> CreateStringBuilderPool(int maxCapacity = 1024, int maxStringBuilderCapacity = 8192)

Parameters

maxCapacity int

The maximum number of builders to keep, defaulting to DefaultStringBuilderCapacity. The value is a recommendation: the pool may hold more than this.

maxStringBuilderCapacity int

The ceiling, in characters, on how large a builder may be and still be worth keeping; anything larger is discarded on return. Defaults to DefaultMaxStringBuilderCapacity.

Returns

ObjectPool<StringBuilder>

The pool.

Remarks

Nothing here is released under memory pressure. DefaultObjectPool<T> drops an instance only when its policy rejects one or the pool is already full on return, so a pool that has filled up stays filled for the life of the process. The rented arrays behind ArrayPoolBufferWriter<T> are a separate matter: those come from ArrayPool<T>, which trims itself on every gen-2 collection.

SharedBufferWriterPool<T>()

Gets the shared pool of ArrayPoolBufferWriter<T> instances for the default configuration, one pool per element type.

public static ObjectPool<ArrayPoolBufferWriter<T>> SharedBufferWriterPool<T>()

Returns

ObjectPool<ArrayPoolBufferWriter<T>>

Type Parameters

T

The element type the writers accept.