Async streams
An IEnumerable<T> produces one element at a time, and IAsyncEnumerable<T> does the same while each step may wait: a file read, a socket, a page of results from an API. The consumer writes await foreach, and the producer writes yield return inside an async method.
An async iterator
The producer prints nothing itself; it yields squares and waits before each one. The consumer prints every value it receives:
Console.WriteLine("squares");
await foreach (var number in Numbers(3))
{
Console.WriteLine($"got {number}");
}
Console.WriteLine("done");
static async IAsyncEnumerable<int> Numbers(int count)
{
for (var i = 1; i <= count; i++)
{
await Task.Delay(5);
yield return i * i;
}
}
dotnet run
squares
got 1
got 4
got 9
done
The method is lazy like a plain iterator: the first square is computed when the loop asks for the first element, not when Numbers(3) is called. Each step waited five milliseconds, and the consumer awaited every one without blocking the thread. A method that returns IAsyncEnumerable may not take an out or ref parameter, for the same reason a plain iterator may not.
await foreach
The loop is the only new syntax: await foreach calls MoveNextAsync and awaits each step. Inside it the element is available as usual, and break stops the enumeration and disposes the iterator, which runs the finally blocks of the producer.
var count = 0;
var total = 0;
await foreach (var number in CountTo(5))
{
count++;
total += number;
if (number == 3)
{
break;
}
}
Console.WriteLine($"count {count} total {total}");
static async IAsyncEnumerable<int> CountTo(int last)
{
for (var i = 1; i <= last; i++)
{
await Task.Delay(1);
yield return i;
}
}
dotnet run
count 3 total 6
The loop took three elements and left, so the producer was never asked for the fourth and fifth. The total is 1 + 2 + 3, and the count is three. A producer that holds a resource, a file handle or a database reader, puts its cleanup in a finally inside the iterator, and the disposal of the enumeration runs it even after a break.
Cancelling the enumeration
A token reaches the producer through the parameter marked [EnumeratorCancellation], and the consumer attaches its token with WithCancellation. This program cancels from inside its own loop, which is what a consumer that has seen enough does:
using System.Runtime.CompilerServices;
Console.WriteLine("stop at four");
using var source = new CancellationTokenSource();
try
{
await foreach (var number in Count(source.Token).WithCancellation(source.Token))
{
Console.WriteLine($"number {number}");
if (number == 4)
{
source.Cancel();
}
}
}
catch (OperationCanceledException)
{
Console.WriteLine("stopped");
}
Console.WriteLine($"cancelled {source.IsCancellationRequested}");
static async IAsyncEnumerable<int> Count([EnumeratorCancellation] CancellationToken token)
{
for (var i = 1; i <= 10; i++)
{
await Task.Delay(2, token);
yield return i;
}
}
dotnet run
stop at four
number 1
number 2
number 3
number 4
stopped
cancelled True
The fifth step waited with a cancelled token, so it threw TaskCanceledException, which the catch of OperationCanceledException took. This is the shape the capstone uses for a reader of a channel: a loop that stops when the token fires and a catch that reports the stop as a normal end.
When a stream fits
- A page of results that arrives over the network, then the next page: the producer waits between elements, which the type expresses.
- A file read line by line with an asynchronous read: no thread waits for the disk.
- A consumer that needs every element before it can work: collect the stream with ToListAsync and use a list, because the stream buys nothing.
- A hot path with no waiting: a plain IEnumerable<T> is faster, and the task per element costs more than the work.
Exercises
- Write an async iterator that yields the lines of a file and add a delay between two of them.
- Break out of a stream inside a try and confirm with a finally that the producer was disposed.
- Cancel a stream from a timer instead of from the loop.
- Compare the same sequence as IEnumerable and as IAsyncEnumerable.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which interface is an async stream?
Answer
IAsyncEnumerable<T>
The async form produces an element at a time and awaits each step.
-
Which loop consumes an IAsyncEnumerable?
Answer
await foreach
await foreach awaits MoveNextAsync on every step.
-
What does this program print?
var count = 0; await foreach (var n in Numbers()) { count++; } Console.WriteLine(count); static async IAsyncEnumerable<int> Numbers() { for (var i = 1; i <= 3; i++) { await Task.Delay(1); yield return i; } }Answer
3
The iterator yields three elements and the loop counts each one.
-
Which attribute marks the token parameter of an async iterator?
Answer
[EnumeratorCancellation]
It tells the compiler to combine the token with the one of the enumeration.
-
What does this program print?
var total = 0; await foreach (var n in Numbers()) { total += n; } Console.WriteLine(total); static async IAsyncEnumerable<int> Numbers() { for (var i = 1; i <= 3; i++) { await Task.Delay(1); yield return i; } }Answer
6
The sum of 1, 2 and 3 is 6.
-
What does yield return do in an async iterator?
Answer
Produces the next element when the consumer asks for it
The iterator is lazy: one element per step of the consumer.
-
What does this program print?
var first = -1; await foreach (var n in Numbers()) { first = n; break; } Console.WriteLine(first); static async IAsyncEnumerable<int> Numbers() { await Task.Delay(1); yield return 7; yield return 8; }Answer
7
The loop takes the first element and breaks before the second is produced.
-
What does WithCancellation do?
Answer
Attaches a token to the enumeration
The token reaches the producer through the [EnumeratorCancellation] parameter.
-
What does break do inside await foreach?
Answer
Stops the loop and disposes the iterator
The enumeration is disposed, which runs the finally blocks of the producer.
-
Why is await foreach needed instead of foreach?
Answer
Each step may wait, and the step returns a task
MoveNextAsync is asynchronous, so the loop must await it.
The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev