For an ASP.NET Core work queue on System.Threading.Channels, when do you choose CreateBounded over CreateUnbounded, and what does BoundedChannelFullMode control?
answer
- unbounded grows until memory runs out
- capacity is back-pressure
- FullMode: Wait is the default
- TryWrite false only in Wait mode
- itemDropped callback for the Drop modes
basics
~20 sChoose 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 linesvar 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
Recall that a bounded channel has a capacity and a FullMode, and that Wait is the default.
Explain each BoundedChannelFullMode value, how TryWrite and WriteAsync behave when full, and why the drop modes need the itemDropped callback to be visible.
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.
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