ZeroAlloc.Cache 1.1.2

ZeroAlloc.Cache

Source-generated zero-allocation caching proxy from an annotated interface.

Add [Cache] to an interface and a Roslyn source generator emits a proxy class that transparently intercepts every method call, returning a cached result on hit with no heap allocation on the cache-hit path. Backed by IMemoryCache by default, with optional HybridCache (L1 + L2) opt-in per method. AOT-safe.

Quick start

dotnet add package ZeroAlloc.Cache

[Cache(TtlMs = 60_000)]
public interface IProductRepository
{
    ValueTask<Product?> GetByIdAsync(int id, CancellationToken ct);

    [Cache(TtlMs = 300_000, MaxEntries = 1_000)]
    ValueTask<IReadOnlyList<Product>> SearchAsync(string query, CancellationToken ct);
}

// Register — one line wires everything
builder.Services.AddIProductRepositoryCache<ProductRepositoryImpl>();

Inject IProductRepository anywhere — caching is transparent to the caller.

public class ProductsController(IProductRepository repo)
{
    public async Task<Product?> Get(int id, CancellationToken ct)
        => await repo.GetByIdAsync(id, ct); // cache hit = zero allocation
}

Performance

L1 (in-process) cache-hit comparison. .NET 10.0.7, i9-12900HK, BenchmarkDotNet v0.15.8.

ZA.Cache is 2.3× faster than FusionCache with comparable allocation. The ~2× premium over hand-rolled IMemoryCache.GetOrCreateAsync is the cost of the typed [Cache] attribute abstraction (generated key building + async wrapper) — in exchange you don't write the lookup boilerplate at every call site. FusionCache's overhead comes from carrying L2-cache and stampede-protection infrastructure even when only L1 is configured.

Full methodology + design analysis: docs/performance.md.

Features

Cache behavior

Telemetry

Each cached method emits both metrics (via Meter("ZeroAlloc.Cache")) and a tracing span (via ActivitySource("ZeroAlloc.Cache")) — no extra package required, plain BCL System.Diagnostics.

Breaking change in 2.0: Meter name renamed from "zeroalloc.cache" to "ZeroAlloc.Cache" for ecosystem consistency with the other ZeroAlloc telemetry packages. Subscribers must update — calls to AddMeter("zeroalloc.cache") will silently stop receiving metrics:

-services.AddOpenTelemetry().WithMetrics(m => m.AddMeter("zeroalloc.cache"));
+services.AddOpenTelemetry().WithMetrics(m => m.AddMeter("ZeroAlloc.Cache"));

Metrics. Counters tagged with method (the cached method name): cache.hits, cache.misses, cache.evictions, cache.hybrid_calls (factory invocations on the HybridCache path). The cache.lookup_duration_ms histogram records per-lookup latency tagged with cache.method.

Tracing. Each cached method emits a cache.lookup span tagged with:

Subscribe via OpenTelemetry:

services.AddOpenTelemetry()
    .WithMetrics(m => m.AddMeter("ZeroAlloc.Cache"))
    .WithTracing(t => t.AddSource("ZeroAlloc.Cache"));

Diagnostics

Documentation

Full docs live in docs/:

• Getting Started
• Attribute Reference
• Diagnostics: ZC0001 · ZC0002

License

MIT