CacheManager & ICacheProvider

Overview

The BeepDM caching subsystem is built around two complementary surfaces:

• CacheManager — a static, globally-shared cache with pluggable primary + fallback providers, stale-while-revalidate (SWR), batch operations, tag groups, and centralized statistics.
• CacheScope — an isolated, per-component instance cache obtained via CacheManager.CreateScope(). Each scope owns its own provider, statistics, and key namespace. Used by ProxyDataSource for per-datasource caches.

Cache Providers

All providers implement ICacheProvider and are located in Caching/Providers/.

Provider selection guide

Custom provider

public class MyCustomProvider : ICacheProvider
{
    public string Name => "MyCustom";
    public bool IsAvailable => true;
    public CacheStatistics Statistics { get; } = new CacheStatistics();

    // Implement GetAsync, SetAsync, RemoveAsync, ExistsAsync, ClearAsync,
    // GetManyAsync, SetManyAsync, RefreshAsync, Dispose ...
}

// Register globally
CacheManager.SetProvider(new MyCustomProvider());

CacheConfiguration

Passed to CacheManager.Initialize() or CacheManager.CreateScope().

Top-level properties

RedisConfiguration

MemoryCacheConfiguration

var config = new CacheConfiguration
{
    DefaultExpiry        = TimeSpan.FromMinutes(30),
    MaxItems             = 5_000,
    CleanupInterval      = TimeSpan.FromMinutes(2),
    KeyPrefix            = "myapp:",
    EnableCompression    = true,
    CompressionThreshold = 1_024,
    Redis = new RedisConfiguration
    {
        ConnectionString = "redis-host:6379,password=secret",
        Database         = 1,
        RetryPolicy      = new RetryPolicyConfiguration { MaxRetries = 5 }
    }
};

ICacheProvider Interface

All providers implement ICacheProvider : IDisposable. The interface is fully async to avoid blocking on I/O-bound operations.

CacheManager — Initialization

CacheManager is a static class. It must be initialised once before use. Subsequent calls to Initialize are no-ops (idempotent).

Initialize

public static void Initialize(
    CacheConfiguration configuration  = null,
    CacheProviderType  primaryProvider = CacheProviderType.InMemory,
    CacheProviderType? fallbackProvider = null)

Registers the primary provider and an optional explicit fallback. If fallbackProvider is null, a SimpleCacheProvider is used as the automatic fallback so cache operations always succeed even when the primary is unavailable.

SetProvider

public static void SetProvider(ICacheProvider provider, ICacheProvider fallbackProvider = null)

Replace the primary (and optionally the fallback) provider at runtime. The replaced provider is disposed. Useful for tests or to swap from in-memory to Redis after startup.

Quick-start examples

// Default — SimpleCacheProvider (no config needed)
CacheManager.Initialize();

// InMemory primary, default Simple fallback
CacheManager.Initialize(
    new CacheConfiguration { MaxItems = 5_000, DefaultExpiry = TimeSpan.FromMinutes(30) },
    CacheProviderType.InMemory);

// Redis primary + InMemory fallback
CacheManager.Initialize(
    new CacheConfiguration { Redis = new RedisConfiguration { ConnectionString = "redis:6379" } },
    primaryProvider  : CacheProviderType.Redis,
    fallbackProvider : CacheProviderType.InMemory);

// Inject a custom provider
CacheManager.SetProvider(new MyCustomProvider());

CacheManager — Core Operations

Fallback behaviour

On every read (GetAsync, ExistsAsync, GetManyAsync) the manager tries the primary first. If the primary's IsAvailable is false or the call throws, the operation is retried transparently against the fallback provider. Writes go to the primary only; the fallback is read-only when the primary is down.

Stale-While-Revalidate

The stale-while-revalidate (SWR) pattern uses two TTLs per entry to decouple freshness from availability:

 time ─────────────────────────────────────────────────────────────────────►
       │◄──── soft TTL ────►│◄──── stale window (hard−soft) ────►│ expired │
       │   return cached   │  return stale + trigger background  │ block   │

Stampede guard: A ConcurrentDictionary<string,int> (_swrInFlight) ensures only one background refresh fires per key at a time. Additional callers during an in-flight refresh all receive the stale value immediately.

CacheManager.GetOrCreateWithStaleAsync

var data = await CacheManager.GetOrCreateWithStaleAsync(
    key      : "report:weekly",
    factory  : () => ReportService.GenerateAsync(),
    softTtl  : TimeSpan.FromMinutes(5),
    hardTtl  : TimeSpan.FromMinutes(60));
// Callers within 5 min → instant
// Callers 5-60 min later → instant (stale) + silent background refresh
// After 60 min → blocks once to regenerate

CacheScope.GetOrCreateAsync (scoped SWR)

using var scope = CacheManager.CreateScope(CacheProviderType.InMemory, config);

var rows = await scope.GetOrCreateAsync(
    key     : "orders:open",
    factory : () => db.GetOpenOrdersAsync(),
    softTtl : TimeSpan.FromSeconds(30),
    hardTtl : TimeSpan.FromMinutes(5));

Extension Operations

Additional static methods on CacheManager from CacheManager.Extensions.cs.

Tagged cache entries

Group related entries under one or more string tags to mass-invalidate them together.

// Store with tags
await CacheManager.SetWithTagsAsync(
    key   : "user:123:profile",
    value : userProfile,
    tags  : new[] { "user:123", "profiles" },
    expiry: TimeSpan.FromHours(1));

await CacheManager.SetWithTagsAsync(
    key   : "user:123:orders",
    value : orderList,
    tags  : new[] { "user:123", "orders" });

// Invalidate everything tagged "user:123" (removes both entries above)
long removed = await CacheManager.RemoveByTagAsync("user:123");
Console.WriteLine($"Removed {removed} entries");

Conditional writes

// Store only if the key does not already exist
bool didSet = await CacheManager.SetIfNotExistsAsync("lock:export-job", true, TimeSpan.FromMinutes(5));
if (!didSet)
    Console.WriteLine("Job already running — skip duplicate"); 

Full extension method list

CacheScope

A CacheScope is a disposable, instance-based cache backed by its own ICacheProvider. It is the recommended way to give a component or service its own isolated cache without polluting the global CacheManager state.

Creating a scope

// Factory on CacheManager
CacheScope scope = CacheManager.CreateScope(
    CacheProviderType.InMemory,
    new CacheConfiguration
    {
        MaxItems   = 200,
        DefaultExpiry = TimeSpan.FromMinutes(10),
        KeyPrefix  = "proxy:orders-db:"
    });

CacheScope API

Statistics & Diagnostics

CacheStatistics (per provider)

CacheManagerStatistics (combined)

Inspecting statistics

var stats = CacheManager.GetStatistics();

Console.WriteLine($"Primary: {stats.PrimaryProviderName}  available={stats.PrimaryProviderAvailable}");
Console.WriteLine($"  Hits:    {stats.PrimaryProvider?.Hits}");
Console.WriteLine($"  Misses:  {stats.PrimaryProvider?.Misses}");
Console.WriteLine($"  HitRatio:{stats.PrimaryProvider?.HitRatio:F2}%");
Console.WriteLine($"  Items:   {stats.TotalItemCount}");
Console.WriteLine($"  Memory:  {stats.TotalMemoryUsage / 1024.0:F1} KB");
Console.WriteLine($"  Combined hit ratio: {stats.CombinedHitRatio:F2}%");

Usage Examples

Example 1 — Basic store and retrieve

CacheManager.Initialize();   // SimpleCacheProvider by default

await CacheManager.SetAsync("user:123", new UserDto { Name = "Alice", Age = 30 });
await CacheManager.SetAsync("product:456", new ProductDto { Name = "Widget", Price = 9.99m },
    expiry: TimeSpan.FromMinutes(5));

if (await CacheManager.ExistsAsync("user:123"))
{
    var user = await CacheManager.GetAsync<UserDto>("user:123");
    Console.WriteLine(user.Name);
}

await CacheManager.RemoveAsync("user:123");

Example 2 — GetOrCreate pattern

// Async factory is called only on a cache miss
var report = await CacheManager.GetOrCreateAsync(
    key    : "report:monthly",
    factory: async () => await ReportService.GenerateMonthlyAsync(),
    expiry : TimeSpan.FromHours(1));

// Synchronous overload
var config = CacheManager.GetOrCreate("app:config", () => ConfigLoader.Load());

Example 3 — Stale-while-revalidate

// Callers never wait longer than a millisecond after the first population.
// Background refresh ensures data stays fresh without blocking.
var dashboard = await CacheManager.GetOrCreateWithStaleAsync(
    key     : "dashboard:stats",
    factory : async () => await StatsService.ComputeAsync(),
    softTtl : TimeSpan.FromMinutes(2),
    hardTtl : TimeSpan.FromMinutes(30));

Example 4 — Batch operations

// Set 1 000 items in one call
var batch = Enumerable.Range(1, 1_000)
    .ToDictionary(i => $"item:{i}", i => new ItemDto { Id = i });

long stored = await CacheManager.SetManyAsync(batch, TimeSpan.FromMinutes(15));
Console.WriteLine($"Stored {stored} items");

// Retrieve a subset
var keys = new[] { "item:1", "item:42", "item:999" };
var found = await CacheManager.GetManyAsync<ItemDto>(keys);
Console.WriteLine($"Found {found.Count} / {keys.Length}");

Example 5 — Tag-based invalidation

// Populate user-scoped entries
await CacheManager.SetWithTagsAsync("user:7:profile", profile,  tags: new[] { "user:7" });
await CacheManager.SetWithTagsAsync("user:7:orders",  orders,   tags: new[] { "user:7", "orders" });
await CacheManager.SetWithTagsAsync("user:7:prefs",   prefs,    tags: new[] { "user:7" });

// User logs out / account deleted — invalidate everything for user 7
long cleared = await CacheManager.RemoveByTagAsync("user:7");
Console.WriteLine($"Cleared {cleared} entries for user 7");

Example 6 — Redis primary with InMemory fallback

CacheManager.Initialize(
    new CacheConfiguration
    {
        DefaultExpiry = TimeSpan.FromMinutes(20),
        KeyPrefix     = "orders:",
        Redis         = new RedisConfiguration
        {
            ConnectionString = "redis-prod:6379,password=s3cr3t",
            ConnectTimeout   = TimeSpan.FromSeconds(3),
            RetryPolicy      = new RetryPolicyConfiguration { MaxRetries = 3 }
        }
    },
    primaryProvider  : CacheProviderType.Redis,
    fallbackProvider : CacheProviderType.InMemory);

// If Redis is down, the InMemory fallback is used automatically
var order = await CacheManager.GetOrCreateAsync("order:88", () => db.GetOrderAsync(88));

Example 7 — Scoped cache for a component

public class OrderRepository : IDisposable
{
    private readonly IDatabase   _db;
    private readonly CacheScope  _cache;

    public OrderRepository(IDatabase db)
    {
        _db    = db;
        _cache = CacheManager.CreateScope(
            CacheProviderType.InMemory,
            new CacheConfiguration { MaxItems = 500, KeyPrefix = "orders:" });
    }

    public async Task<IReadOnlyList<Order>> GetOpenOrdersAsync()
        => await _cache.GetOrCreateAsync(
               key     : "open",
               factory : () => _db.QueryAsync<Order>("SELECT * FROM Orders WHERE Status='Open'"),
               softTtl : TimeSpan.FromSeconds(30),
               hardTtl : TimeSpan.FromMinutes(5));

    public async Task InvalidateAsync() => await _cache.ClearAsync();

    public void Dispose() => _cache.Dispose();
}

Example 8 — Monitoring statistics

// Periodic health check
var stats = CacheManager.GetStatistics();

if (stats.PrimaryProvider?.HitRatio < 50)
    Console.WriteLine("Warning: cache hit ratio below 50% — consider increasing MaxItems");

if (!stats.PrimaryProviderAvailable)
    Console.WriteLine("Warning: primary cache provider is down — running on fallback");

Console.WriteLine($"Total memory: {stats.TotalMemoryUsage / 1024:F0} KB");
Console.WriteLine($"Evictions:    {stats.TotalEvictedItems}");

Example 9 — Custom provider injection

// Use a custom provider (e.g. Garnet, Memcached, Cosmos DB cache)
var provider = new MemcachedCacheProvider("memcached-host:11211");
CacheManager.SetProvider(provider, fallbackProvider: new SimpleCacheProvider());

// Or replace just for one component via scope
using var scope = new CacheScope(provider);