skip to content

Channel-Based Queues

In-process work queues on System.Threading.Channels: bounded vs unbounded channels drained by a BackgroundService, and why Task.Run fire-and-forget loses work. Interviewers ask where it breaks.

part ofASP.NET Coreread it →
on this pageshow

explore

questions

5

For an ASP.NET Core work queue on System.Threading.Channels, when do you choose CreateBounded over CreateUnbounded, and what does BoundedChannelFullMode control?

level: middleimportance: must knowfreq 52%

answer

  1. unbounded grows until memory runs out
  2. capacity is back-pressure
  3. FullMode: Wait is the default
  4. TryWrite false only in Wait mode
  5. itemDropped callback for the Drop modes

basics

~20 s

Choose CreateBounded for any queue fed by HTTP traffic, because an unbounded channel grows until memory runs out. BoundedChannelFullMode decides what a write does when the channel is full: Wait (the default) waits for room; DropNewest, DropOldest and DropWrite discard an item.

solid answer

~40 s

`Channel.CreateUnbounded<T>()` never refuses a write, so if uploads arrive faster than thumbnails render, the queue grows until the process runs out of memory. `Channel.CreateBounded<T>(new BoundedChannelOptions(capacity) { FullMode = ... })` caps it, and `FullMode` sets the policy when the cap is reached. **`Wait`**, the default: `WriteAsync` waits for room, so back-pressure reaches the request, and `TryWrite` returns `false` at once, which lets the endpoint answer `503` instead. **`DropOldest`** / **`DropNewest`** evict a queued item to admit the new one, and **`DropWrite`** discards the item being written. In all three drop modes `TryWrite` returns `true` and `WriteAsync` completes, so the caller cannot tell; pass an `itemDropped` callback to `CreateBounded` to log or count drops. Thumbnails that must not vanish want `Wait`; telemetry where only recent samples matter can use `DropOldest`.

code

csharp · 11 lines
csharp
var options = new BoundedChannelOptions(500)
{
    FullMode = BoundedChannelFullMode.Wait,
    SingleReader = true
};
builder.Services.AddSingleton(Channel.CreateBounded<ThumbnailJob>(options));

app.MapPost("/photos/{id:guid}/thumbnails", (Guid id, Channel<ThumbnailJob> queue) =>
    queue.Writer.TryWrite(new ThumbnailJob(id))
        ? Results.Accepted($"/photos/{id}")
        : Results.StatusCode(StatusCodes.Status503ServiceUnavailable));

go deeper

for a junior

Recall that a bounded channel has a capacity and a FullMode, and that Wait is the default.

for a middle

Explain each BoundedChannelFullMode value, how TryWrite and WriteAsync behave when full, and why the drop modes need the itemDropped callback to be visible.

for a senior

Choose the overflow policy from the cost of losing an item, size capacity by memory and worst-case wait, and turn a full queue into a fast 503 instead of hung requests.

for a principal

Treat queue capacity as a capacity-planning decision tied to consumer throughput and acceptable loss, and set alerts on queue depth and drops.

## Unbounded: simple until the burst `Channel.CreateUnbounded<T>()` accepts every write immediately; for an unbounded channel `TryWrite` returns `true` unless the writer has been completed. That is ideal when producers can never outrun the consumer. A queue fed by HTTP requests offers no such guarantee: a marketing push or a client stuck in a retry loop sends uploads faster than a CPU-bound renderer can work. The queue then grows without limit, memory and GC pauses climb, and the process can fail with every queued job lost at once. ## Bounded: a capacity and a policy `Channel.CreateBounded<T>(int capacity)` or `Channel.CreateBounded<T>(BoundedChannelOptions options)` caps the number of **buffered** items. `BoundedChannelOptions.FullMode` decides what happens when a write meets a full channel: | `BoundedChannelFullMode` | `WriteAsync` when full | `TryWrite` when full | What is lost | |---|---|---|---| | `Wait` (default) | waits until a reader frees a slot | returns `false` | nothing; the producer waits or gives up | | `DropNewest` | completes at once | returns `true` | the most recently queued item | | `DropOldest` | completes at once | returns `true` | the oldest queued item | | `DropWrite` | completes at once | returns `true` | the item being written | The `CreateBounded<T>(int)` overload always uses `Wait`. The drop modes report success while discarding something, so the overload `CreateBounded<T>(BoundedChannelOptions, Action<T>? itemDropped)` exists to tell you which item was discarded: log it, count it in a metric, or mark it for a retry. ## Choosing the policy for an upload queue For thumbnails, losing a job means a photo without previews, so a drop mode is wrong. With `Wait` the endpoint picks one of two behaviours: 1. **Wait with a limit.** `await writer.WriteAsync(job, ct)` holds the request until a slot frees. Pass a token that combines the request's abort token with a short timeout, so a full queue turns into a fast error rather than hung requests piling up in Kestrel. 2. **Fail fast.** `if (!writer.TryWrite(job)) return Results.StatusCode(StatusCodes.Status503ServiceUnavailable);` sheds load at once and lets the client retry later, ideally with a `Retry-After` header. The drop modes fit data where newer replaces older: a live progress indicator, sampled telemetry, a "latest position" feed. `DropOldest` keeps the freshest items; `DropWrite` protects what is already queued. ## Sizing the capacity - Capacity times item size is the queue's worst-case memory. Queue **ids**, not image bytes. - Capacity divided by the consumer's throughput is the worst-case **wait** for the last item. 500 jobs at 10 per second is almost a minute. - Everything in the buffer is lost on a crash, so a larger capacity is also a larger loss. ## Watching the queue - `ChannelReader<T>.Count` reports the items currently buffered; check `CanCount` first. Bounded channels and the default unbounded channel support it; the unbounded channel chosen when `SingleReader = true` does not, and `Count` then throws `NotSupportedException`. - Publish that depth as a metric and alert when it stays high: a queue that never empties means the consumer cannot keep up. - Count the `TryWrite` failures (`503` responses) and the items passed to `itemDropped`; both are lost or refused work. ## Other options Both option classes inherit `SingleWriter`, `SingleReader` and `AllowSynchronousContinuations` from `ChannelOptions`, all `false` by default. They are optimisation hints; leave `SingleWriter` false when many concurrent requests write.

  • How do you find out that a DropOldest channel is losing items?
    Create it with `Channel.CreateBounded<T>(options, itemDropped)`. The channel invokes the `Action<T>` with each discarded item, outside its internal lock, so you can log it, increment a metric or record it for a retry. Without the callback, `TryWrite` and `WriteAsync` report success and the loss is invisible.
  • In Wait mode, what is the difference between awaiting WriteAsync and calling TryWrite?
    `WriteAsync` waits until a slot frees, the token is cancelled or the channel is completed, so a full queue becomes request latency. `TryWrite` never waits: it returns `false` when the channel is full or completed, and the endpoint decides what to answer, typically `503`.

  • An unbounded channel is fine because uploads are small
  • DropWrite makes TryWrite return false so the caller knows
  • The default BoundedChannelFullMode is DropOldest
  • WriteAsync throws ChannelClosedException when a bounded channel is full
  • Set SingleWriter = true when many requests write concurrently
open as a page

In ASP.NET Core, how do you hand work from an endpoint to a background consumer using a System.Threading.Channels Channel<T>?

level: juniorimportance: should knowfreq 45%

basics

~10 s

Register one Channel<T> as a singleton. The endpoint writes a job with channel.Writer.WriteAsync and returns 202 Accepted; a BackgroundService reads jobs one by one with await foreach over channel.Reader.ReadAllAsync(stoppingToken).

open as a page

How do you consume a System.Threading.Channels queue with limited concurrency in an ASP.NET Core BackgroundService, and which ChannelOptions settings matter?

level: middleimportance: should knowfreq 28%

basics

~20 s

Start a fixed number of reader loops over the same ChannelReader and await them together; each item goes to exactly one reader. Keep SingleReader false with several readers and AllowSynchronousContinuations false so writers never run consumer code.

open as a page

In an ASP.NET Core endpoint, why is `_ = Task.Run(...)` after a photo upload a poor way to render thumbnails, and what replaces it?

level: middleimportance: should knowfreq 48%

basics

~20 s

The task outlives the request: scoped services it captured are disposed, its exceptions go unobserved, the host neither tracks nor waits for it at shutdown, and a burst starts unlimited renders. A Channel drained by a BackgroundService replaces it.

open as a page

An ASP.NET Core photo site queues thumbnail jobs in an in-memory Channel; why are jobs lost on deploys and crashes, and how do you drain them or make them durable?

level: seniorimportance: should knowfreq 40%

basics

~20 s

Queued jobs exist only in process memory, so the queue is at-most-once: a crash, kill or overrun shutdown loses them. Drain on graceful stop by completing the writer and reading until empty; when loss is unacceptable, record each job durably first.

open as a page