skip to content

Asynchronous Sequences and Streams

AsyncSequence delivers values over time to for await loops, and AsyncStream adapts callbacks and delegates. Interviewers ask how to bridge a delegate API and which buffering policy to pick.

on this pageshow

explore

questions

5

In Swift, how does a for await loop over an AsyncSequence work, when does it need try, and what ends it?

level: juniorimportance: must knowfreq 55%

answer

  1. the async twin of for-in
  2. makeAsyncIterator, then an awaited next()
  3. nil ends it, a thrown error ends it
  4. try follows the sequence's Failure type

basics

~20 s

A 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 lines
swift
import 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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).

open as a page

How do you turn a chat socket's delegate callbacks into a Swift AsyncThrowingStream that a screen reads with for try await?

level: middleimportance: must knowfreq 60%

basics

~20 s

Create an AsyncThrowingStream, keep its Continuation where the delegate methods can reach it, call yield(_:) per message and finish(throwing:) when the socket closes, and close the socket in onTermination. makeStream(of:) returns stream and continuation together.

open as a page

In Swift, what happens when two tasks iterate the same AsyncStream or AsyncThrowingStream of chat messages, and how do you give both every message?

level: middleimportance: should knowfreq 40%

basics

~10 s

Neither gets every message: streams are single-consumer, and concurrent iteration is documented as a programmer error. In Swift 6.4 AsyncStream splits elements between waiting tasks and AsyncThrowingStream traps. Give each subscriber its own stream.

open as a page

A Swift chat client feeds messages and presence updates into AsyncStreams; which buffering policy suits each, and what does yield report when the buffer fills?

level: seniorimportance: should knowfreq 35%

basics

~20 s

yield(_:) never waits, so the policy decides what a lagging reader loses: .unbounded keeps all, .bufferingNewest(n) evicts the oldest, .bufferingOldest(n) rejects the newcomer. Messages need every element; presence needs .bufferingNewest(1). yield returns .enqueued, .dropped or .terminated.

open as a page

A Swift chat screen breaks out of its for await loop, yet the socket behind the AsyncStream stays open; when does onTermination actually run?

level: seniorimportance: should knowfreq 35%

basics

~20 s

onTermination runs once: with .finished when the producer calls finish, and with .cancelled when the reading task is cancelled or the stream and its iterators are released. break only drops the iterator, so a stream stored elsewhere stays open.

open as a page