Reservoir 0.3.5

Reservoir

Stop allocating the same thing twice.

Reservoir is bounded, thread-safe object pooling for .NET with a 0 B warm general-purpose object-pool rent/return path. It ships as C# source, so the optimized code compiles into your assembly—no runtime dependency, version conflict, or extra DLL.

dotnet add package Reservoir

Requires .NET Standard 2.0 and C# 12 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 retention. You choose the maximum number of idle objects; the pool cannot grow without limit.
• Capacity-aware storage. Cache-line-separated slots keep small pools fast; dense striped storage keeps large async working sets scalable.
• Source-only delivery. Reservoir stays private to your project and adds no runtime package or assembly.
• Ownership guardrails. Debug builds detect invalid returns and report leaked rentals.

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.

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.

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. Debug diagnostics make violations visible and report rentals that become unreachable without being returned. 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 custom-object reuse, source ownership, struct-policy specialization, scoped leases, or debug ownership diagnostics.

Use ArrayPool<T> for raw arrays. Use Microsoft.Extensions.ObjectPool when ecosystem integration matters more than source-only delivery.

Go deeper

Documentation · Installation · API guide · Design notes

Reservoir is available under the MIT license.