Class ScyllaObjectPool<T>

High-performance pool for Unity objects (UnityEngine.Object). Stores inactive instances in an array-backed free-list (LIFO). Unsynchronized by default; use AsSynchronized(object) to obtain a synchronized wrapper.

Inheritance
object
ScyllaObjectPool<T>
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaObjectPool<T> : IScyllaCollection<T>, IScyllaCollection where T : Object
Type Parameters
Name Description
T

Unity object type
Remarks

This pool is intentionally dedicated to UnityEngine.Object types for important Unity-specific reasons:

  • Correct lifetime management: Unity objects must be created and destroyed via UnityEngine.Object.Instantiate(UnityEngine.Object), UnityEngine.Object.Destroy(UnityEngine.Object) and UnityEngine.Object.DestroyImmediate(UnityEngine.Object) (not via new or IDisposable).
  • Unity "fake null" semantics: destroyed Unity objects compare equal to null; pooling Unity objects needs to respect these semantics to avoid subtle bugs.
  • Activation/deactivation: for UnityEngine.GameObject and UnityEngine.Component instances, pooling usually implies toggling SetActive(false/true) on release/get, which is Unity-specific. 
// Direct construction
var pool = new ScyllaObjectPool<GameObject>(prefab: myPrefab, maxSize: 100, capacity: 32);
// Using fluent builder for complex configuration
var pool = ScyllaObjectPool<GameObject>.CreateBuilder()
.WithPrefab(myPrefab)
.WithCapacity(64)
.WithMaxSize(200)
.OnGet(obj => obj.SetActive(true))
.OnRelease(obj => obj.SetActive(false))
.Synchronized()
.Build();

Constructors

ScyllaObjectPool(T, Func<T>, Action<T>, Action<T>, Action<T>, bool, bool, int, int)

Creates a new object pool backed by a free-list of inactive instances.

Declaration
public ScyllaObjectPool(T prefab = null, Func<T> createFunc = null, Action<T> onGet = null, Action<T> onRelease = null, Action<T> onDestroy = null, bool collectionCheck = false, bool allowCreate = true, int maxSize = 2147483647, int capacity = 4)
Parameters
Type Name Description
T prefab

Optional prefab to instantiate when the pool is empty and allowCreate is true. If null, you must provide createFunc.
Func<T> createFunc

Optional creation function used when the pool is empty and allowCreate is true. If null, creation falls back to instantiating prefab.
Action<T> onGet

Optional callback invoked after an instance is retrieved from the pool
Action<T> onRelease

Optional callback invoked before an instance is stored back into the pool
Action<T> onDestroy

Optional callback invoked before an instance is destroyed (e.g., when pool is full)
bool collectionCheck

If true, Release(T) checks (O(n)) whether the instance is already in the pool. Useful for debugging; disable for maximum performance.
bool allowCreate

If true, Get() creates a new instance when the pool is empty. If false, TryGet(out T) returns false when empty.
int maxSize

Maximum number of inactive instances to keep in the pool. When exceeded, released instances are destroyed (and not stored).
int capacity

Initial free-list capacity (rounded up to at least 1)

Properties

AllowCreate

True if the pool creates new instances when empty.

Declaration
public bool AllowCreate { get; }
Property Value
Type Description
bool

Capabilities

Feature/capability flags supported by this pool instance.

Declaration
public ScyllaCollectionCapabilities Capabilities { get; }
Property Value
Type Description
ScyllaCollectionCapabilities

Capacity

Current free-list capacity (number of inactive slots that can be stored without resizing).

Declaration
public int Capacity { get; }
Property Value
Type Description
int

Count

Number of inactive instances currently stored in the pool. This maps to Count.

Declaration
public int Count { get; }
Property Value
Type Description
int

CountAll

Total number of instances ever created by this pool and not subsequently destroyed via Clear(bool).

Declaration
public int CountAll { get; }
Property Value
Type Description
int

IsEmpty

True if the pool has no inactive instances available.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
bool

MaxSize

Maximum number of inactive instances that can be stored before releases begin destroying instances.

Declaration
public int MaxSize { get; }
Property Value
Type Description
int

SyncRoot

Synchronization root for externally coordinating operations. This pool is unsynchronized by default.

Declaration
public object SyncRoot { get; }
Property Value
Type Description
object

ThreadSafety

Thread-safety guarantees provided by this pool instance.

Declaration
public ScyllaCollectionThreadSafety ThreadSafety { get; }
Property Value
Type Description
ScyllaCollectionThreadSafety

Methods

AsSynchronized(object)

Creates and returns a thread-safe synchronized wrapper around this pool.

Declaration
public ScyllaObjectPool<T>.SynchronizedScyllaObjectPool AsSynchronized(object syncRoot = null)
Parameters
Type Name Description
object syncRoot

Optional external lock object to use for synchronization. If null, the wrapper creates and owns a private lock.
Returns
Type Description
ScyllaObjectPool<T>.SynchronizedScyllaObjectPool

A thread-safe wrapper that synchronizes all operations

Clear()

Removes all inactive instances from the pool and destroys them.

Declaration
public void Clear()

Clear(bool)

Removes all inactive instances from the pool. If destroy is true, also destroys them.

Declaration
public void Clear(bool destroy)
Parameters
Type Name Description
bool destroy

If true, destroys inactive instances; if false, just forgets them

Contains(T)

Determines whether the pool currently contains the specified inactive instance (O(n)).

Declaration
public bool Contains(T instance)
Parameters
Type Name Description
T instance

Instance to locate
Returns
Type Description
bool

True if found among inactive instances, false otherwise

CopyTo(Span<T>)

Copies inactive instances from the pool into the provided span (top-to-bottom / LIFO order).

Declaration
public int CopyTo(Span<T> destination)
Parameters
Type Name Description
Span<T> destination

The span to copy instances into
Returns
Type Description
int

The number of instances copied

CopyTo(T[], int)

Copies inactive instances from the pool into the provided array starting at the specified index (top-to-bottom / LIFO order).

Declaration
public int CopyTo(T[] destination, int destinationIndex)
Parameters
Type Name Description
T[] destination

The array to copy instances into
int destinationIndex

The zero-based index in the destination array at which copying begins
Returns
Type Description
int

The number of instances copied

CreateBuilder()

Creates a new fluent builder for configuring and constructing a ScyllaObjectPool instance. The builder provides a discoverable API for setting prefab, capacity, max size, creation function, callbacks, and synchronized wrappers.

Declaration
public static ScyllaObjectPool<T>.Builder CreateBuilder()
Returns
Type Description
ScyllaObjectPool<T>.Builder

A new builder instance for configuring ScyllaObjectPool construction
Remarks
var pool = ScyllaObjectPool<GameObject>.CreateBuilder()
.WithPrefab(myPrefab)
.WithCapacity(64)
.WithMaxSize(200)
.Build();

Get()

Retrieves an instance from the pool. If the pool is empty and AllowCreate is true, a new instance is created.

Declaration
public T Get()
Returns
Type Description
T

An instance (never null when AllowCreate is true)
Exceptions
Type Condition
InvalidOperationException

Thrown when the pool is empty and AllowCreate is false

GetEnumerator()

Returns an enumerator that iterates through inactive instances in the pool (top-to-bottom / LIFO order). The enumerator is a value type, enabling allocation-free enumeration when using the concrete type.

Declaration
public ScyllaObjectPool<T>.Enumerator GetEnumerator()
Returns
Type Description
ScyllaObjectPool<T>.Enumerator

A value-type ScyllaObjectPool<T>.Enumerator positioned before the first inactive instance. The count is snapshotted at construction time; pool mutations during enumeration are not reflected.

Prewarm(int)

Pre-creates and stores up to the specified number of inactive instances.

Declaration
public int Prewarm(int count)
Parameters
Type Name Description
int count

Number of instances to create and store
Returns
Type Description
int

The number of instances actually created and stored

Release(T)

Returns an instance back to the pool. If the pool is at MaxSize, the instance is destroyed instead of being stored.

Declaration
public bool Release(T instance)
Parameters
Type Name Description
T instance

The instance to return to the pool
Returns
Type Description
bool

True if stored in the pool; false if destroyed due to capacity constraints
Exceptions
Type Condition
ArgumentNullException

Thrown when instance is null
InvalidOperationException

Thrown when instance is already in the pool and collection checking is enabled

TryAdd(T)

Attempts to add an instance to the pool (equivalent to Release(T)).

Declaration
public bool TryAdd(T item)
Parameters
Type Name Description
T item

The instance to add
Returns
Type Description
bool

True if stored, false if destroyed due to capacity constraints

TryGet(out T)

Attempts to retrieve an instance from the pool. If the pool is empty and AllowCreate is true, a new instance is created.

Declaration
public bool TryGet(out T instance)
Parameters
Type Name Description
T instance

When this method returns, contains the retrieved instance if successful, or null if not
Returns
Type Description
bool

True if an instance was retrieved or created; false if the pool is empty and AllowCreate is false

TryPeek(out T)

Attempts to peek at the next inactive instance without removing it.

Declaration
public bool TryPeek(out T item)
Parameters
Type Name Description
T item

When this method returns, contains the next inactive instance if available, or null if empty
Returns
Type Description
bool

True if an inactive instance was available; false otherwise

TryRemove(out T)

Attempts to remove an instance from the pool (equivalent to TryGet(out T)).

Declaration
public bool TryRemove(out T item)
Parameters
Type Name Description
T item

When this method returns, contains the retrieved instance if successful, or null if not
Returns
Type Description
bool

True if an instance was retrieved or created; false if the pool is empty and AllowCreate is false

Implements

Extension Methods