skip to content

In ASP.NET Core output caching, what does resource locking do when a popular entry expires under load, and when would you call SetLocking(false)?

level: seniorimportance: should knowfreq 27%

answer

  1. on by default in the default policy
  2. one request per key runs the endpoint
  3. waiters reuse the produced entry
  4. per process, not per cluster
  5. the leader's exception reaches waiters

basics

~20 s

Locking, on by default, lets only one request per cache key run the endpoint on a miss; concurrent requests for that key wait and are served the response it produced. SetLocking(false) lets every miss run the endpoint independently.

solid answer

~50 s

The default policy sets `AllowLocking = true`. When an eligible request misses, the middleware schedules the endpoint under the cache key: the first request runs it, and any request for the same key arriving meanwhile awaits that same work and is served the resulting entry without running the handler. That is the output cache's built-in stampede protection. If the response turns out not to be storable (a 500, a `Set-Cookie`), each waiter then runs the endpoint itself; if the leading request throws, every waiter receives that exception. The coordination is an in-memory dictionary inside one process, so three instances can still run the endpoint three times, even with the Redis store. `SetLocking(false)` suits endpoints where tying many callers to one slow or failure-prone execution is worse than duplicate work, typically cheap responses or ones that often fail.

code

csharp · 10 lines
csharp
builder.Services.AddOutputCache(options =>
{
    options.AddPolicy("Listings", b => b.Expire(TimeSpan.FromMinutes(5)));
    options.AddPolicy("LiveNoLock", b => b
        .Expire(TimeSpan.FromSeconds(5))
        .SetLocking(false));
});

app.MapGet("/lineup", GetLineup).CacheOutput("Listings");          // coalesced misses
app.MapGet("/lineup/live", GetLiveStatus).CacheOutput("LiveNoLock"); // every miss runs

go deeper

for a junior

Know that by default only one request per cache key runs the endpoint on a miss and the others reuse its response.

for a middle

Explain how waiters are served from the leader's captured response, what happens when the response is not storable, and how SetLocking(false) changes it.

for a senior

Describe the trade-off: coalescing protects the database but multiplies one slow or failing execution, and it is per process even with the Redis store.

for a principal

Decide per endpoint whether duplicate work or shared failure is the bigger risk, and whether per-instance coalescing is enough or the data layer needs its own protection.

## The problem locking addresses When a popular cached response expires, every request that arrives before a new one is stored is a miss. Without coordination each of them runs the endpoint, and a page that was cheap while cached suddenly costs N database queries at once. The general pattern is the cache stampede, discussed at length elsewhere; here the question is what ASP.NET Core's output cache does about it. ## What the middleware does on a miss The default policy sets `OutputCacheContext.AllowLocking = true`. With locking on, a miss goes like this: 1. The middleware computes the cache key and asks the store for it. Store **lookups** for the same key are coalesced too, whatever the locking setting: concurrent requests share one read. 2. On a miss it schedules "run the endpoint and capture the response" in an in-memory dispatcher keyed by the cache key. 3. The **first** request for that key becomes the leader and actually runs the endpoint. 4. Requests for the same key that arrive while the leader is working find the pending task and **await it**. 5. When the leader finishes, the entry is stored and each waiter is served that captured response, with an `Age` header, without running the handler. With locking off (`AllowLocking = false`), step 2 is skipped: every miss runs the endpoint and each stores its own result. ## Edge cases | Situation | What waiters get | |---|---| | leader produces a storable 200 | the leader's response | | leader's response is not storable (500, `Set-Cookie`, authenticated) | nothing shared; each waiter runs the endpoint itself | | leader throws | the same exception, so every waiter fails | | the leader is slow | every waiter is as slow as the leader | The last two rows are the price of coalescing: one bad or slow execution is multiplied across all the callers that were waiting on it. ## Which requests are coalesced at all Locking is a pre-condition of **storage**, not a separate feature. The middleware only schedules coalesced work when the policies left `AllowCacheStorage` set to `true` for the request. So: - an authenticated request, a `POST` or any request the default policy refuses is never coalesced; each one runs the endpoint; - requests are only coalesced with others that produce the **same cache key**, so `/lineup?day=fri` and `/lineup?day=sat` run independently; - the burst after an `EvictByTagAsync` call is coalesced exactly like the burst after an expiry, because both are ordinary misses. That makes locking a good fit for the moment an organiser edits a popular event: eviction empties the entry, and the hundreds of visitors refreshing the listing produce one rebuild per instance rather than hundreds. ## Scope: one process The dispatcher is a dictionary inside the middleware instance. It does not coordinate across servers, and the Redis output cache store adds no distributed lock. Three instances that miss the same key at the same moment each run the endpoint once, which is usually acceptable: the database sees three queries instead of three hundred. ## Turning it off ```csharp builder.Services.AddOutputCache(options => { options.AddPolicy("NoLock", b => b.SetLocking(false)); }); app.MapGet("/lineup/live", GetLiveLineup).CacheOutput("NoLock"); ``` `SetLocking(false)` adds a small policy that sets `AllowLocking = false` after the default policy has set it to `true`. `SetLocking(true)` exists for custom chains that start without the default policy. ## Choosing - **Keep locking** (the default) for expensive, popular, public responses: festival listings, a home page, a catalogue page. - **Consider turning it off** when the endpoint is cheap, so duplicate work costs little and coalescing only adds a wait. - **Consider turning it off** when the endpoint is slow *and* failure-prone, so a single timeout should not fail every waiting request. - Remember that locking only spans requests with the **same key**: a key that varies widely (every query string distinct) gets little benefit either way.

  • Does output cache locking prevent the endpoint from running twice across a web farm with the Redis store?
    No. The coordination lives in an in-memory dictionary inside each process's middleware, and the Redis store holds no lock. Each instance that misses runs the endpoint once, so the worst case is one execution per instance rather than one per request.
  • What happens to waiting requests if the leading request's response is a 500?
    A 500 is not storable under the default policy, so nothing is shared. Each waiting request then runs the endpoint itself, which means a failing endpoint under load still receives the full burst of executions.

Locking is a bakery where the first customer asking for a sold-out loaf triggers one fresh batch, and everyone who arrives meanwhile queues for that batch instead of ordering their own. If the batch burns, everyone in that queue leaves without bread; a bakery in another town bakes its own batch regardless.

  • Output caching has no protection against many concurrent misses for one key.
  • Locking makes the Redis output cache take a distributed lock per key.
  • If the leader throws, waiting requests fall back to running the endpoint.
  • Locking is off by default and must be enabled with SetLocking(true).
  • Waiting requests are answered 503 until the first response is stored.