In Swift, how does a for await loop over an AsyncSequence work, when does it need try, and what ends it?
answer
- the async twin of for-in
- makeAsyncIterator, then an awaited next()
- nil ends it, a thrown error ends it
- try follows the sequence's Failure type
basics
~20 sA for await loop awaits its iterator's next() before every pass, suspending until the next value or the end. It needs for try await when the sequence can throw, and ends when next() returns nil or throws, or the body breaks.
solid answer
~40 s`for await line in log.lines` calls `makeAsyncIterator()` once and then `await`s the iterator's `next()` before every pass, so the loop can suspend at each iteration and must sit in an `async` context. You write `for try await` when the sequence can throw: since Swift 6.0 that follows its `Failure` type, so an `AsyncStream` (`Failure == Never`) takes plain `for await`, while `URL.lines` or an `AsyncThrowingStream` needs `try`. The loop ends when `next()` returns `nil`, when `next()` throws (the error propagates out of the loop), or when the body runs `break` or `return`. Cancelling the task ends it only if the iterator reacts to cancellation: `AsyncStream` does, and a hand-written iterator must check `Task.isCancelled` itself.
code
swift · 20 linesimport Foundation
// A log tailer: `URL.lines` is an AsyncSequence of String that can throw.
func countErrors(in log: URL) async throws -> Int {
var count = 0
for try await line in log.lines where line.hasPrefix("ERROR") {
count += 1
}
return count
}
// Roughly what the loop above does for you.
func countErrorsByHand(in log: URL) async throws -> Int {
var count = 0
var iterator = log.lines.makeAsyncIterator()
while let line = try await iterator.next() { // suspends until a line arrives
if line.hasPrefix("ERROR") { count += 1 }
}
return count // next() returned nil: the file ended
}go deeper
Recall that for await awaits next() before every pass, that try appears only when the sequence can throw, and that nil from next() ends the loop.
Explain the desugaring into makeAsyncIterator and a while-let loop over next(), and how Swift 6.0's Failure type decides whether try is required.
Show you know cancellation is up to the iterator: AsyncStream returns nil when cancelled, while a hand-written iterator keeps going unless it checks Task.isCancelled.
Be ready to say when a team should expose some AsyncSequence<Element, Failure> instead of a concrete stream type, trading flexibility for hidden implementation details.
## Two protocols behind the loop An **`AsyncSequence`** is the asynchronous counterpart of `Sequence`: a type that hands out values one at a time, where a value may not exist yet when you ask for it. The protocol itself is small: - `makeAsyncIterator()` returns an **`AsyncIterator`**, a type conforming to `AsyncIteratorProtocol`. - That iterator has one essential method, `mutating func next() async throws -> Element?`. It returns the next element, or `nil` to say the sequence is over. - Since Swift 6.0 both protocols also carry a **`Failure`** associated type (SE-0421) and use `Element` and `Failure` as primary associated types, so you can write `some AsyncSequence<String, any Error>`. The standard library documents that the sequence "doesn't generate or contain the values; it just defines how you access them". A file being read, a socket, a timer or a stream fed by callbacks can all sit behind the same interface. A plain `Array` cannot: `for await x in [1, 2, 3]` is rejected with *for-in loop requires '[Int]' to conform to 'AsyncSequence'*. ## What the compiler turns the loop into A `for await` loop is roughly this `while` loop, written by hand: ```swift var iterator = log.lines.makeAsyncIterator() while let line = try await iterator.next() { if line.hasPrefix("ERROR") { count += 1 } } ``` Three consequences follow: 1. **Every pass is a possible suspension point.** The task waits inside `next()` until the producer has a line, then resumes and runs the body. The body runs for one element at a time, in order; the loop never runs two bodies concurrently. 2. **The enclosing function must be `async`**, because `await` is only allowed in an asynchronous context. 3. **A `where` clause, `break`, `continue` and `return` work as in an ordinary `for-in` loop.** ## When the loop needs `try` | Sequence | `Failure` | Loop form | |---|---|---| | `AsyncStream<Element>` | `Never` | `for await` | | `AsyncThrowingStream<Element, any Error>` | `any Error` | `for try await` | | `URL.lines`, `FileHandle.bytes.lines` | `any Error` | `for try await` | | Custom sequence whose `next()` does not throw | inferred `Never` | `for await` | Leaving `try` off a throwing sequence is a compile error: *call can throw, but it is not marked with 'try' and the error is not handled*. For a hand-written sequence the compiler infers `Failure` from the iterator: a non-throwing `next()` makes it `Never`, and callers write no `try`. Before Swift 6.0 the same decision came from an experimental mechanism inside the standard library; the rule callers see did not change. ## What ends the loop - **`next()` returns `nil`**: the sequence finished, for example the file reached its end or a stream's producer called `finish()`. - **`next()` throws**: the loop stops and the error propagates to the caller, like any `try` expression. - **The body exits** with `break`, `return` or a thrown error. - **Cancellation, only if the iterator honours it.** Cancellation in Swift is cooperative. `AsyncStream` terminates when its reading task is cancelled, and `next()` then returns `nil` once any already-buffered elements are delivered, but the `AsyncIteratorProtocol` documentation leaves the reaction to each iterator, which "should use the cancellation primitives". A custom iterator that never checks `Task.isCancelled` keeps producing after its task is cancelled. The protocol also states a contract for implementers: after `next()` returns `nil` or throws, the iterator is in a terminal state and every later call must return `nil`. ## Operators: lazy, like `Sequence`'s The standard library gives `AsyncSequence` the familiar transformations: `map`, `compactMap`, `flatMap`, `filter`, `prefix`, `dropFirst`, `drop(while:)` and `prefix(while:)`, plus single-value methods such as `contains`, `first(where:)`, `min`, `max` and `reduce`. The transformations return new sequence types such as `AsyncMapSequence` and do no work until someone iterates them. The single-value methods consume the sequence for you and return one awaited result. The standard library has no `zip`, `merge` or `debounce` for asynchronous sequences. ## Common slips - Expecting `for await` to work over an `Array`; it needs an `AsyncSequence`. - Assuming `Task.cancel()` stops every loop at once; it stops only loops whose iterator checks for cancellation. - Writing `try` on every loop out of habit; the compiler accepts a redundant `try`, which hides whether the sequence can actually fail. - Iterating a stream a second time and expecting the values again; a stream is consumed as it is read and never replays, and whether another asynchronous sequence starts over for a new iterator depends on that type. - Doing slow work inside the body without noticing that the producer may be waiting, or buffering, until the body finishes; the next element is requested only when the body returns.
- How does AsyncSequence's map differ from Array's map?`map` on an `AsyncSequence` returns another asynchronous sequence (`AsyncMapSequence`, or `AsyncThrowingMapSequence` for a throwing closure) and transforms nothing until someone iterates it; each element is transformed as it arrives. `Array.map` runs eagerly and returns an array at once. To collect an async sequence you iterate it, for example with `reduce(into:_:)`.
- What must a hand-written AsyncIteratorProtocol's next() do after it has returned nil?Keep returning `nil`. The protocol documents that once `next()` returns `nil` or throws, the iterator is in a terminal state and every later call must return `nil`. It should also react to cancellation, for example by checking `Task.isCancelled` and returning `nil`, because nothing else stops a loop over it.
- In Swift 6, how does the compiler know a custom AsyncSequence never throws?It infers `Failure` from the iterator. If `next()` is declared without `throws`, `Failure` is `Never`, and callers write plain `for await`. If `next()` throws, `Failure` is `any Error` unless you declare a typed `throws(E)`. Before Swift 6.0 an experimental standard-library mechanism made the same call; callers saw the same rule.
- A for await loop runs its body for several elements at the same time.
- for await works over any Sequence, such as an Array of URLs.
- Every for await loop needs try, because next() is declared async throws.
- The loop ends as soon as the sequence has no element ready at that moment.
- Cancelling the task stops any for await loop immediately, whatever the iterator does.
Assumes Swift 6.4; for await dates from Swift 5.5, and the Failure associated type with AsyncSequence<Element, Failure> primary associated types arrived in Swift 6.0 (SE-0421).