Reservoir 1.4.0

Reservoir

Stop allocating the same thing twice.

Reservoir is thread-safe object pooling for .NET with 0 B warm paths and bounded shared retention. It ships as a small runtime library with public, library-friendly types and specialized generic policies.

dotnet add package Reservoir

Requires a .NET Standard 2.0-compatible runtime or later.

Why Reservoir?

• Zero general-purpose pool allocations when warm. ObjectPool<T,TPolicy> rent and return reuse fixed slots without allocating nodes. Legacy collection fallbacks may trim or replace backing storage.
• Bounded shared retention. You choose the shared tier's maximum idle-object count. Scoped rentals additionally retain one object per participating thread.
• Capacity-aware storage. Cache-line-separated slots keep small pools fast; dense striped storage keeps large async working sets scalable.
• Library-friendly delivery. One public assembly identity flows normally through PackageReference dependency graphs.
• Scoped ownership. Stack-only leases return rentals automatically when synchronous work leaves scope.

Rent. Work. Return.

Define lifecycle behavior as a struct policy so the JIT can specialize and inline it:

using Reservoir;

var pool = new ObjectPool<Buffer, BufferPolicy>(maxCapacity: 64);

using var lease = pool.RentScoped(out Buffer buffer);
buffer.Write(payload);

sealed class Buffer
{
    public int Length { get; set; }
    public void Write(ReadOnlySpan<byte> value) => Length += value.Length;
}

readonly struct BufferPolicy : IPooledObjectPolicy<Buffer>
{
    public Buffer Create() => new();

    public bool TryReset(Buffer buffer)
    {
        buffer.Length = 0;
        return true;
    }
}

Create() handles a miss. TryReset() prepares an object for reuse or returns false to discard it. Discarded IDisposable objects are disposed automatically; implement IPooledObjectDestroyPolicy<T> for custom cleanup. The scoped lease guarantees return when control leaves the synchronous scope. It uses a per-pool thread-local fast path and retains one object per participating thread in addition to the bounded shared tier.

For performance-critical synchronous code, prefer RentScoped(out T) on .NET 10; its thread-local path is faster and avoids the ownership validation needed by repeated lease.Value access. On .NET 8, manual Rent() and Return() remain faster. Manual rental is also required when work crosses an await or total idle retention must stay within MaximumRetained. Measure on target hardware when nanoseconds matter.

For work that crosses an await, use Rent() and return the object in finally. See the quick start for both patterns.

Pools included

Reservoir includes ready-to-use pools for:

List<T> · Dictionary<TKey,TValue> · HashSet<T> · Queue<T> · Stack<T> · StringBuilder · CancellationTokenSource

List<int> values = ListPool<int>.Shared.Rent();
try
{
    values.Add(42);
    Consume(values);
}
finally
{
    ListPool<int>.Shared.Return(values);
}

Collections return empty. Oversized backing stores are discarded instead of retained. Each pool exposes a shared instance and constructors for custom limits.

For synchronous scopes, RentScoped uses a per-pool thread-local fast path and returns the collection automatically:

using ListPool<int>.Lease lease = ListPool<int>.Shared.RentScoped(out List<int> values);
values.Add(42);
Consume(values);

The lease is stack-only and cannot cross an await. Manual Rent and Return keep using the bounded shared pool for asynchronous ownership.

CancellationTokenSourcePool.RentScoped uses the same per-pool thread-local strategy while preserving source reset and disposal semantics. Use Rent() or RentLinked() when ownership crosses an async boundary.

For synchronous, thread-affine hot paths, each specialized collection pool also exposes an opt-in ThreadLocalShared facade:

List<int> values = ListPool<int>.ThreadLocalShared.Rent();
try
{
    Consume(values);
}
finally
{
    ListPool<int>.ThreadLocalShared.Return(values);
}

It retains one item per participating thread, then falls back to the bounded Shared pool. This improves same-thread reuse but can retain items on idle threads and is not globally bounded by Shared.MaximumRetained.

The ownership rule

Returning an object transfers ownership to the pool. Do not touch it, return it twice, or return it to another pool.

Another thread may rent the same object immediately. Read the complete ownership rules.

Measured, not promised

BenchmarkDotNet 0.15.8 MediumRun, .NET 10.0.11, Windows 11, AMD EPYC 9V74:

Every measured warm Reservoir path allocated 0 B. Timings vary by machine; compare methods within the same run.

See all benchmark results or reproduce them locally:

dotnet run -c Release -f net10.0 --project benchmarks/Reservoir.Benchmarks -- --filter "*" --job Short --runtimes net8.0 net10.0 --apples

When it fits

Choose Reservoir when you want bounded shared custom-object reuse, struct-policy specialization, scoped leases, or capacity-aware storage.

Use ArrayPool<T> for raw arrays. Use Microsoft.Extensions.ObjectPool when integration with Microsoft Extensions abstractions matters more than Reservoir's specialized policies and leases.

Go deeper

Documentation · Installation · API guide · Design notes

Reservoir is available under the MIT license.