Skip to content
Tutorials Center
My learning

Topics

Lesson 103 of 182 ยท Async and Concurrency

Channels and Producer-Consumer

Learn System.Threading.Channels in C# - bounded and unbounded channels, writers and readers, back-pressure, multiple consumers, pipelines, completion, errors and await foreach with ReadAllAsync.

Many programs have a producer-consumer shape: one part creates work (requests, messages, files to process) and another part handles it. A channel sits between them. Producers put items in, consumers take items out, and the channel takes care of the waiting: a consumer awaits when nothing is there yet, and (if the channel is bounded) a producer awaits when it is too full. The type is System.Threading.Channels.Channel<T>, and it is the modern, async-friendly replacement for BlockingCollection<T>.

Channels are thread-safe, allocation-light, and used inside ASP.NET Core itself. They are the right building block for background job queues, event buses inside one process, and multi-stage pipelines, because they give you back-pressure and clean shutdown with very little code. In this lesson you will create channels, read them with await foreach, limit them, fan work out to several consumers, chain them into a pipeline and shut them down safely.

Creating a channel: writer and reader

A channel has two ends. channel.Writer is a ChannelWriter<T> that producers use; channel.Reader is a ChannelReader<T> that consumers use. It is good style to hand each side only the end it needs.

You create one with a factory:

  • Channel.CreateUnbounded<T>() accepts any number of waiting items. Writing never waits. If producers are faster than consumers, memory grows without limit.
  • Channel.CreateBounded<T>(capacity) holds at most capacity items. When full, writers wait (back-pressure).
C# The smallest producer and consumer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

ReadAllAsync() returns an IAsyncEnumerable<T> (see Async Streams). The await foreach loop gets each item as soon as it is available, waits when there is none, and ends when the writer calls Complete() and every remaining item has been read. Forgetting Complete() is the classic bug: the loop would wait forever.

Items from one writer are read in the order they were written (first in, first out).

The writing API

ChannelWriter<T> offers three ways to add an item:

Method Behavior
WriteAsync(item) Returns a ValueTask that completes when the item is stored. Waits if the channel is full. Throws ChannelClosedException if the channel was completed.
TryWrite(item) Never waits. Returns true if stored, false if the channel is full (in the default Wait mode) or completed.
WaitToWriteAsync() Waits until there is room; returns false if the channel is completed. Use it in a while loop with TryWrite.

For a bounded channel, WriteAsync is the normal choice because the wait is exactly the back-pressure you want.

Back-pressure with a bounded channel

Suppose a producer creates 1,000 items per second but a consumer handles 100. With an unbounded channel the backlog grows forever. A bounded channel stops the producer instead: WriteAsync does not complete until the consumer has made room. The slow part sets the pace for the whole pipeline, and memory stays flat.

The next example shows it without any timing. We fill a channel of capacity 2, start a third write, and look at that write's state.

C# WriteAsync waits when the channel is full

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The third write is parked. As soon as the reader takes item 1, the write completes and item 3 enters the channel. You never wrote a lock, a timer or a polling loop.

What to do when the channel is full

BoundedChannelOptions.FullMode controls what a write does when there is no room:

  • Wait (default): the write waits.
  • DropWrite: the new item is discarded.
  • DropOldest / DropNewest: an item already in the channel is discarded to make room.

Dropping is appropriate for data where only the latest matters (sensor readings, UI updates) and wrong for jobs that must not be lost.

C# FullMode controls overflow

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

DropWrite keeps the first three items (1, 2, 3) and ignores 4 and 5. DropOldest accepts every write but evicts the oldest items, so 3, 4, 5 remain. Note that in a dropping mode TryWrite still returns true for every write (the output above shows five True values), even when the item was discarded or an older one was evicted, so you cannot detect the loss from the result.

Reading: the three styles

  1. await foreach (var x in reader.ReadAllAsync()) is the shortest and handles completion for you. Use it by default.
  2. ReadAsync() reads one item and throws ChannelClosedException if the channel is completed and empty.
  3. WaitToReadAsync() + TryRead() is the low-level loop. WaitToReadAsync returns false when the channel is completed and empty; TryRead takes an item if one is there. It lets you handle several items per wake-up, for example to process in batches.
C# Batch reading with WaitToReadAsync

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

TryRead inside the inner loop empties the channel without paying for an await per item, which is the fastest way to consume a busy channel.

Several consumers

A channel can have many readers; each item goes to exactly one of them (it is a work queue, not a broadcast). That makes it easy to scale processing: start N consumer tasks on the same reader. Which consumer gets which item is not predictable, so design the work so the order does not matter and make any shared result thread-safe.

C# Three consumers share one channel

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Every job is handled exactly once, so the totals are exact (30 jobs, sum 2 x 465 = 930). When the producer completes the writer, each consumer's loop ends after the channel drains, and Task.WhenAll(workers) returns.

Multiple writers are fine too. If several producers share a channel, call Complete() only after all of them are done, for example after await Task.WhenAll(producers).

Pipelines

A pipeline chains stages: each stage reads from one channel, transforms the items and writes to the next. Because every channel can be bounded, a slow stage automatically throttles the stages before it. Each stage is a small, testable method that takes a reader and returns a reader.

C# A three-stage pipeline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Because each stage has one reader and one writer, items stay in order and the output is always #1, #4, #9, #16, #25, #36. The channels hold only two items each, so no stage can race far ahead of the next.

The stage methods ignore failures to keep the example short. In real pipelines, wrap each stage body in try/catch and complete the writer with the exception, as shown in the next section, so a failure travels downstream instead of leaving consumers waiting.

Completion and errors

writer.Complete() says "no more items". Items already inside are still delivered. writer.Complete(exception) also says "and this is why": consumers drain what is left and then see the exception, thrown from ReadAllAsync / ReadAsync. reader.Completion is a Task that finishes when the channel is complete and fully drained, which is handy for waiting on a shutdown.

C# Propagating a producer failure

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Items 1, 2 and 3 are delivered, then the loop throws the producer's exception. If the producer had simply died without completing the writer, the consumer would wait forever. Always complete the writer in a finally or catch.

Cancellation

Pass a CancellationToken to ReadAllAsync(token), WriteAsync(item, token) or ReadAsync(token). When the token fires, the waiting call throws OperationCanceledException. A common shutdown order is: stop producers, call Complete(), let consumers drain, then await them. See Cancellation and Timeouts for token patterns.

C# Cancelling a waiting consumer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Channel options and performance

Channel.CreateBounded and CreateUnbounded accept options that let the runtime pick faster code paths:

  • SingleReader = true / SingleWriter = true promise that only one task reads or writes at a time. The implementation then avoids some synchronization. If you break the promise, behavior is undefined, so set them only when it is true.
  • AllowSynchronousContinuations runs a consumer's continuation directly on the producer's thread. It is faster but can make a producer run consumer code, so leave it false (the default) unless you have measured the gain.

Channels are designed for in-process use. They are not durable: if the process stops, queued items are lost. For work that must survive restarts, use a real message queue or database and keep a channel only as the in-memory buffer in front of it. You will build exactly such a buffer in the background job queue project.

Channel, BlockingCollection or ConcurrentQueue?

  • Use a Channel in async code. Waiting consumes no thread.
  • Use BlockingCollection only in older code or with dedicated blocking threads.
  • Use ConcurrentQueue when you never need to wait: you poll or drain it at moments you choose.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What ends an await foreach over reader.ReadAllAsync()?

    ReadAllAsync waits for more items until the writer completes. Without Complete the loop never ends.
  2. 2. What does WriteAsync do on a full bounded channel with the default FullMode?

    FullMode.Wait applies back-pressure: the producer is suspended until there is space.
  3. 3. Three consumers read the same channel. How is each item delivered?

    A channel is a queue of work. Each item is taken by one reader; it is not a broadcast.
  4. 4. How do you tell consumers that the producer failed?

    Complete(exception) lets consumers drain the queue and then rethrows the exception from the read.
  5. 5. Which FullMode keeps the newest data and throws away the oldest queued item?

    DropOldest evicts the oldest queued item to make room for the new one. DropWrite discards the new item instead.

Summary

  • A Channel<T> connects producers and consumers; use Writer to write and Reader to read, and prefer await foreach (... ReadAllAsync()) for reading.
  • Unbounded channels never make writers wait; bounded channels give back-pressure, and FullMode can drop items instead of waiting.
  • Always call Writer.Complete() (or Complete(exception)) when the producers are done, or consumers wait forever.
  • Several consumers share one channel and each item goes to exactly one of them; pipelines chain stages with bounded channels.
  • Pass a CancellationToken for shutdown; use SingleReader/SingleWriter only when true; channels are in-memory and not durable.

Next: Async Streams