CKTIS / C#
BoundedChannelOptions and BoundedChannelFullMode.Wait
Set a channel's buffer limit and see why, when it fills up, `TryWrite` returns `false` immediately but `WriteAsync` waits asynchronously for room.
Version: C# 12 and .NET 8; later runtimes may add compatible features
Syntax
using System.Threading.Channels;
var options = new BoundedChannelOptions(capacity: 2)
{
FullMode = BoundedChannelFullMode.Wait
};
Channel<int> channel = Channel.CreateBounded<int>(options);
bool written = channel.Writer.TryWrite(1);
await channel.Writer.WriteAsync(2);In C# 12 and .NET 8, pass BoundedChannelOptions from System.Threading.Channels to Channel.CreateBounded<T>(options). A positive Capacity caps the number of buffered items, not the number of items consumers are already processing or the number of pending writes. The simpler Channel.CreateBounded<T>(capacity) overload also uses Wait.
FullMode controls what happens when a write meets a full buffer. The default, BoundedChannelFullMode.Wait, does not drop items to handle overflow. TryWrite(item) returns true if the write succeeds, or false immediately if the channel is full or writing has been completed. A false result leaves no write pending.
WriteAsync(item, cancellationToken) returns a ValueTask: it can finish immediately, but if the buffer is full it waits for room without blocking a thread. Await it before producing the next item so a slow consumer can slow down the producer (backpressure). Cancellation can interrupt a pending write with OperationCanceledException; normal completion of the writer can interrupt it with ChannelClosedException. A successful write means the item was accepted, not processed.
WaitToWriteAsync signals an opportunity to write; it does not reserve a slot. With multiple producers, another can take the slot, so if TryWrite fails, wait again if writing is still possible. After normal completion with Complete(), the consumer can still drain buffered items.
Examples
using System;
using System.Threading.Channels;
var channel = Channel.CreateBounded<int>(new BoundedChannelOptions(capacity: 1)
{
FullMode = BoundedChannelFullMode.Wait
});
await channel.Writer.WriteAsync(1);
Console.WriteLine($"TryWrite(99): {channel.Writer.TryWrite(99)}");
var pending = channel.Writer.WriteAsync(2);
Console.WriteLine($"WriteAsync(2) completed: {pending.IsCompleted}");
Console.WriteLine($"Read: {await channel.Reader.ReadAsync()}");
await pending;
channel.Writer.Complete();
await foreach (var item in channel.Reader.ReadAllAsync())
{
Console.WriteLine($"Read: {item}");
}Result
TryWrite(99): False WriteAsync(2) completed: False Read: 1 Read: 2
`1` fills the buffer. The attempt to write `99` fails, and the write of `2` stays pending. Reading `1` frees a slot, the write of `2` completes, and `ReadAllAsync()` reads `2` after `Complete()`.
Related lessons
- C# · Lesson 46 · Advanced · Version: 3
Sources
- Channels - .NET
- BoundedChannelOptions Class
- BoundedChannelFullMode Enum
- Channel.CreateBounded Method
- ChannelWriter<T>.TryWrite(T) Method
- ChannelWriter<T>.WriteAsync(T, CancellationToken) Method
- ChannelWriter<T>.WaitToWriteAsync(CancellationToken) Method
- ChannelReader<T>.ReadAllAsync(CancellationToken) Method