High-performance, thread-safe object pool for reference types in .NET. Optimized for ultra-low overhead under contention with per-thread fast paths, avoiding locks on hot paths.

Under concurrent workloads, Tedd.ObjectPool delivers between 11× and 111× higher throughput than Microsoft.Extensions.ObjectPool, with the largest gains at high thread counts.

• .NET CLI:

  dotnet add package Tedd.ObjectPool

• PackageReference:

  <ItemGroup>
    <PackageReference Include="Tedd.ObjectPool" Version="x.y.z" />
  </ItemGroup>

• Package Manager Console:

  Install-Package Tedd.ObjectPool -Version x.y.z

Replace x.y.z with the desired version.

Basic pooling of an object, e.g., StringBuilder:

using Tedd;
using System.Text;

var pool = new ObjectPool<StringBuilder>(
    factory: () => new StringBuilder(capacity: 256),
    cleanup: sb => sb.Clear(),           // reset before publishing back
    size: 64                              // total pool slots
);

var sb = pool.Allocate();
try
{
    sb.Append("Hello, world!");
    // ... use sb ...
}
finally
{
    pool.Free(sb); // cleanup runs, then it goes back to the pool
}

• Constructors

  • new ObjectPool<T>(Factory factory)
  • new ObjectPool<T>(Factory factory, int size)
  • new ObjectPool<T>(Factory factory, Action<T> cleanup, int size)
  • new ObjectPool<T>(Factory factory, Action<T>? cleanup, int size, bool disposeWhenFull)

  Where Factory is delegate T Factory() and T : class.

• Core methods

  • T Allocate()
  • void Free(T obj) (no-op if obj is null)
  • void Prefill(int count) – optionally pre-create items to reduce cold-start latency
  • void AllocateExecuteDeallocate(Action<T> action, Action<T>? cleanupAction = null)
  • void Scoped<TState>(TState state, Action<T,TState> action) – allocation-free scoped usage
  • void Dispose() – disposes internal TLS cache; pooled items are not disposed

• Diagnostics (DEBUG builds)

  • void ForgetTrackedObject(T old, T? replacement = null) – mark an object as intentionally not returned

• Default size is Math.Max(1, Environment.ProcessorCount * 2) when only the factory is provided.
• If Free is called when the pool is full:
  • Default: the object is dropped (eligible for GC).
  • If constructed with disposeWhenFull: true and T : IDisposable, the object is disposed.
• The optional cleanup action runs on every Free before the object is published back to the pool.
• Free(null) is a no-op; useful for simplifying caller logic.

var pool = new ObjectPool<byte[]>(
    factory: () => new byte[4096],
    cleanup: _ => { /* optional reset */ },
    size: 128
);

var buffer = pool.Allocate();
try
{
    // use buffer
}
finally
{
    pool.Free(buffer);
}

pool.Scoped(Unit.Value, (sb, _) =>
{
    sb.AppendLine("Scoped work");
});

// Or with state:
pool.Scoped("hello", (sb, text) =>
{
    sb.Append(text);
});

readonly struct Unit { public static readonly Unit Value = default; }

pool.AllocateExecuteDeallocate(
    action: sb => { sb.Append("work"); },
    cleanupAction: sb => sb.Clear() // optional extra cleanup for this call
);

pool.Prefill(count: 32);

var socketPool = new ObjectPool<System.Net.Sockets.Socket>(
    factory: () => new System.Net.Sockets.Socket(System.Net.Sockets.SocketType.Stream, System.Net.Sockets.ProtocolType.Tcp),
    cleanup: s => { /* reset if applicable */ },
    size: 32,
    disposeWhenFull: true // overflowed sockets are disposed instead of dropped
);

• Designed for multi-threaded use. Most hot-path operations avoid locks.
• A per-thread single-item cache greatly reduces interlocked traffic for common allocate/free pairs.
• Allocation attempts spread contention across slots using rotating indices.

• Reuse of expensive-to-create reference types (e.g., StringBuilder, buffers, serializers, MemoryStream).
• High-throughput services needing minimal allocation and contention.

• T must be a reference type (class).
• The pool does not own lifetime of items except when disposeWhenFull: true is enabled for overflow.
• Dispose() only tears down internal thread-local storage; it does not dispose pooled items.

• Fast paths kept tiny: Allocate/Free are aggressively inlined; slow paths are marked NoInlining to keep the I-cache hot.
• Per-thread 1-slot cache: Most allocate/free pairs complete without touching shared memory.
• Fast slot + array: One hot fast slot (_firstItem) plus an array of elements (size - 1).
• Correct memory publication: Uses Volatile.Read/Write for unsynchronized accesses and a single CAS (Interlocked.CompareExchange) to claim/release.
• Contention spreading: Rotating probe indices on allocate/free reduce CAS collisions and cache-line ping-pong.
• Optional prefill: Prefill reduces first-use latency when the factory is expensive.
• Overflow policy: Configurable disposal of IDisposable items when the pool is full; default is drop-on-floor to let GC reclaim.
• DEBUG diagnostics: Optional leak tracking warns via Debug.WriteLine if an allocated item is never returned; ForgetTrackedObject lets you intentionally replace an item (e.g., upsizing a buffer) without spurious warnings.

These choices aim to deliver predictable, low-latency operation under contention while keeping the API simple and allocation-free on the hot path.

Tedd.ObjectPool is consistently faster than Microsoft.Extensions.ObjectPool across all tested thread counts.

• 2 threads: Tedd.ObjectPool is 11.28× faster
• 4 threads: 19.12× faster
• 8 threads: 36.30× faster
• 16 threads: ~95× faster
• 32 threads: ~111× faster

• Tedd.ObjectPool sustains low, stable latencies as concurrency increases (8.8 µs → 35.9 µs).
• The performance advantage grows with thread count, indicating better scalability and reduced contention effects.

Under concurrent workloads, Tedd.ObjectPool delivers between 11× and 111× higher throughput than Microsoft.Extensions.ObjectPool, with the largest gains at high thread counts.

// * Summary *

BenchmarkDotNet v0.15.2, Windows 11 (10.0.26100.4652/24H2/2024Update/HudsonValley) Unknown processor .NET SDK 10.0.100-preview.6.25358.103 [Host] : .NET 9.0.7 (9.0.725.31616), X64 RyuJIT AVX2 DefaultJob : .NET 9.0.7 (9.0.725.31616), X64 RyuJIT AVX2