HybridCache stampede coordination within one instance

30 min guided lesson · Read, predict, then run

External .NET10 SDK10.0.403. Real Kestrel, Microsoft.Data.Sqlite10.0.14 and HybridCache10.11.0. This Development-only owned-loopback fixture exposes deliberate fault controls; it is not a production deployment.

Read or download the complete SDK project, then follow its setup on your computer. The separate C# companion practice below runs in SharpRune’s .NET 9 console environment.

Define the ownership and result contract

A cache stampede occurs when concurrent misses cause repeated source work for the same entry. The relevant owner in this lesson is one real HybridCache instance, not every process that happens to use an equal key. Its shared operation can serve several waiting callers while one factory produces the value. Program.cs registers the actual Microsoft.Extensions.Caching.Hybrid package at version 10.11.0, separately from the ASP.NET and SQLite versions. No secondary cache is configured. Begin by naming the cache instance, key and factory lifetime so that one successful demonstration is not silently expanded into distributed coordination or general consistency across unrelated entries.

Trace the portable .NET9 console companion

The portable .NET9 console companion uses a TaskCompletionSource and a nullable pending Task reference. The first serialized call to Get stores result.Task and increments factories; the second returns that same reference. ReferenceEquals therefore prints shared:True. Completing the source with seven makes both awaited results available, and adding them prints total:14, followed by factories:1. These are actual BCL Task operations, but the null check is not synchronized and no concurrent threads race through Get. The program has no HybridCache, HTTP server, cache expiration or SQL provider. Its purpose is to make shared ownership visible before inspecting the external implementation.

using System;
using System.Linq;
using System.Collections.Generic;
using System.Globalization;
using System.Text;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;

var result=new TaskCompletionSource<int>(); Task<int>? pending=null; int factories=0; Task<int> Get() { if(pending is null) { factories++; pending=result.Task; } return pending; }
var first=Get(); var second=Get(); Console.WriteLine("shared:"+ReferenceEquals(first,second)); result.SetResult(7); Console.WriteLine("total:"+((await first)+(await second))); Console.WriteLine("factories:"+factories);

Walk through the actual external framework lab

The real /cache/shared endpoint calls GetOrCreateAsync with the fixed stampede:demo key. CacheProbe.Create increments its factory counter, captures the current gate task under a lock and awaits that task with the token supplied by HybridCache. Closing the development gate keeps the factory outstanding while up to eight owned HTTP callers join it. Opening the gate lets the value containing generation one complete. /cache/stats exposes the factory count separately from the returned value. Use a fresh fixture when expecting generation one because resetting an entry removes cached data without resetting the cumulative CacheProbe counters or recreating the cache service.

Keep failure and trust boundaries explicit

The package documents that factory cancellation reflects all callers abandoning the shared operation; canceling one waiter is a different event from canceling every participant. Distinct keys can legitimately start distinct factories. Other HybridCache instances, including instances in another process, do not inherit this owner's coordination even if a secondary store were shared. Neither a one-minute expiration nor RemoveAsync makes source data and cached data one transaction. The sample's ordinary Task companion is even narrower: it assumes serialized access and never retries a failed or canceled pending task. Keep each limitation attached to the component that actually owns it.

Practice one: observe the real contract

Practice one: reset the shared entry, close the factory gate, then begin at most eight requests against your owned loopback server. Inspect /cache/stats before release and compare every response generation afterward. Hint: wait until the factory counter becomes one rather than assuming a fixed sleep proves the miss started. Release the gate and await all requests before cleanup. Keep the fresh-process baseline with the report so a later run producing generation two is not mistaken for two concurrent factories. Record request failures and cancellations independently rather than counting only whichever responses completed successfully.

Practice two: test another boundary

Practice two: in a separate bounded run, cancel one of two waiting clients while leaving the other connected, then open the factory gate. Predict which client can observe a result and which cancellation belongs to the shared source operation. Hint: the package supplies a combined cancellation contract, whereas the portable Get method has no caller-token protocol. Do not change production middleware or increase traffic to force an effect. For a design extension, specify whether another process may perform the same source read and whether duplicate source reads are merely expensive or have side effects that require a different owner.

Interpret the evidence and defend the tradeoffs

A useful conclusion names the actual package version, one instance, one key, observed factory count and response generations. It does not claim a universal latency improvement or a cluster-wide lock. The companion establishes shared Task identity under serialized calls; the HTTP experiment establishes package behavior for the bounded external fixture. A senior explanation then asks whether factories are safe to repeat, how failed fills are handled and what source consistency the caller needs. Those questions guide an appropriate cache policy without converting an in-process optimization into a guarantee about external effects, cross-process recovery or coordinated invalidation.