Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 146 ยท Concurrency

AsyncSequence and AsyncStream

Learn Swift AsyncSequence and AsyncStream - for await loops, writing your own async sequence, continuations, finishing and termination, buffering policies, throwing streams and merging streams.

An async function gives you one value after a wait. Many things in real programs produce many values over time: lines arriving from a file, messages from a chat server, sensor readings, progress updates, search results trickling in. You could use callbacks for those, but you already know the problem with callbacks. Swift's answer is the AsyncSequence, a sequence whose next element may take a while to arrive, consumed with a for await loop.

This lesson shows how to read async sequences, how to write one by hand, and how to build the most useful one with very little code: AsyncStream, which turns "something happens now and then" into a sequence. It continues from async and await and Task groups, and the next lessons (cancellation and continuations) build on it.

Sequences you already know, with a delay

A normal Sequence like an array hands out its next element immediately, so a for-in loop never waits. An AsyncSequence may suspend before each element, so you loop with for await:

Swift
for await value in someAsyncSequence {
    print(value)
}

The loop runs its body once per element, pausing (without blocking a thread) while it waits for the next one, and ends when the sequence finishes. Because it can wait, a for await loop may only appear in an async context. Forget the await and the compiler says so:

Swift for-in over an async sequence (fails on purpose)

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 readLine()), it gets the next line from this box.

The message is main.swift:6:10: error: for-in loop requires 'AsyncStream<Int>' to conform to 'Sequence'. Change for to for await and it works. The error is a good reminder that an AsyncSequence is a different protocol from Sequence, so it does not fit APIs such as Array(...) directly.

Writing an AsyncSequence by hand

An AsyncSequence has the same two-part design as a normal Sequence: the sequence creates an iterator, and the iterator hands out elements one at a time. The difference is that the iterator's next() is async, and it returns nil when the sequence is over.

Swift A countdown as an AsyncSequence

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 readLine()), it gets the next line from this box.

The loop prints 3, 2, 1 and then liftoff. Behind the scenes for await does this: call makeAsyncIterator() once, then repeat await iterator.next() until it returns nil. If your sequence can fail, declare next() async throws and the loop becomes for try await.

You will rarely write one of these. Hand-written iterators are useful for a data source with its own state machine, such as reading a file in chunks. For everything else, AsyncStream below is shorter.

Operators come for free

Every AsyncSequence gets many of the methods you know from arrays, written as async versions: map, filter, compactMap, prefix, reduce, contains, first(where:), min(), max() and more. Those that return a single value are async themselves, so you await them. Those that transform, like map, return another async sequence and are lazy: nothing happens until you loop.

Swift map, filter, reduce, contains and friends

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 readLine()), it gets the next line from this box.

The output is [100, 80, 60, 40, 20], then 10 (4+3+2+1), then true, then Optional(2), and finally prefix 9 and prefix 8. Operators like contains and first(where:) stop pulling as soon as they have their answer, so they do not wait for the rest of the sequence.

To fetch the next element yourself without a loop, make an iterator in a function or other non-main context and call await iterator.next(). In the top-level code of main.swift the compiler rejects await it.next() on a var iterator, because top-level variables belong to the main actor. Wrap the code in an async func, as in the next example.

Swift Pulling elements by hand with an iterator

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 readLine()), it gets the next line from this box.

You get Optional("first"), Optional("second") and nil. A nil always means "this sequence has ended".

AsyncStream: a sequence you feed

AsyncStream lets you create an async sequence without writing an iterator. You get a continuation, a little handle with two jobs: yield(_:) puts an element into the stream, and finish() ends it.

Swift Your first AsyncStream

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 readLine()), it gets the next line from this box.

It prints 1, 4, 9, done. The closure runs when the stream is created, and everything you yield is buffered until somebody reads it. A buffer is what makes AsyncStream convenient: the producer and the consumer do not need to run at the same speed.

The usual shape in real code is to create the stream and its continuation together, so a different part of the program can produce values. makeStream(of:) does exactly that:

Swift makeStream: producer and consumer apart

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 readLine()), it gets the next line from this box.

Output: received alpha, received beta, received gamma, producer finished. The loop ends because the producer called finish().

Always call finish(). If nothing ever finishes the stream, a for await loop over it waits forever and your task never completes. Finish it when the source is exhausted, when an error makes further values impossible, or when the owner shuts down.

A stream has one reader

An AsyncStream is single-consumer: each element is delivered to exactly one reader, and a second loop over the same stream does not get a replay. Here the stream is read twice. Only the first loop receives anything.

Swift Reading a stream twice

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 readLine()), it gets the next line from this box.

You get first: [1, 2] and second: []. If several parts of a program need the same events, create one stream per consumer (and keep a list of continuations), or build a small broadcaster actor.

What happens when the reader stops

The consumer can leave early: it breaks out of the loop, or its task is cancelled. The producer should then stop doing work nobody wants. You learn about it with the continuation's onTermination callback, which also reports why the stream ended.

Swift onTermination when the loop breaks

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 readLine()), it gets the next line from this box.

The output order is 1, 2, after loop, terminated: cancelled, after demo. Leaving the loop does not terminate the stream immediately. The stream ends when the last reference to it is dropped, which here happens when demo returns. That is why the callback runs after after loop. The reason is .cancelled for an early exit or cancellation and .finished after finish(). Use the callback to stop a timer, close a socket or cancel a task, and keep it short and thread-safe because it can run on any thread.

If you yield into a stream that has ended, yield returns .terminated and the value is dropped. Each yield returns a result you can inspect when it matters.

Buffering: what if the reader is slow?

By default an AsyncStream buffers every yielded element without limit. That is safe but can use a lot of memory when a fast producer meets a slow consumer. You can choose a different policy when you create the stream:

Policy Behavior
.unbounded (default) Keep everything
.bufferingNewest(n) Keep at most n; drop the oldest when full
.bufferingOldest(n) Keep at most n; drop new elements when full
Swift Bounded buffers drop elements

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 readLine()), it gets the next line from this box.

The first part prints newest 2: [4, 5]. In the second part, the results of yield show what happened: elements 1 and 2 are enqueued(remaining: 1) and enqueued(remaining: 0), while 3, 4 and 5 give dropped(3), dropped(4) and dropped(5). The last line is oldest 2: [1, 2]. Use .bufferingNewest(1) for "latest value wins" data such as the current temperature, and .unbounded when every element matters.

Streams that can fail

A normal AsyncStream cannot fail. If errors are possible, use AsyncThrowingStream, which adds an error type and lets finish(throwing:) end the stream with an error. The consumer uses for try await.

Swift AsyncThrowingStream

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 readLine()), it gets the next line from this box.

Elements already in the buffer are delivered first: value 1, value 2, and then the loop throws, printing feed failed: broken(after: 2). The error ends the loop exactly like a thrown error ends any code in a do block.

Pulling instead of pushing: unfolding

Sometimes the data comes from something you can ask, not something that tells you. For that, AsyncStream(unfolding:) takes a closure that is called each time the consumer wants an element, and returns nil to end. No buffer is involved: nothing runs until the consumer asks.

Swift AsyncStream(unfolding:) pulls on demand

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 readLine()), it gets the next line from this box.

You see pulled 1, pulled 2, pulled 3. The mutable state lives in an actor because the closure is @Sendable: it may not mutate a captured local variable (Sendable).

Merging streams

Because a stream has one reader, combining several sources means creating a new stream that several tasks feed. A task group does the feeding, one child per source:

Swift Merging two streams into one

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 readLine()), it gets the next line from this box.

The merged stream finishes only after both sources finish, and it delivers all six elements: ["a1", "a2", "a3", "b1", "b2", "b3"] and then 6. I sorted the list because the real arrival order depends on the timing of the two tickers, and timing is exactly the thing you should never print as a result. The onTermination line is the cleanup: if the reader goes away, the feeder task is cancelled, which stops the child loops.

Hiding the concrete type

Functions that return an async sequence do not have to reveal AsyncStream. Since Swift 5.7 the protocol has primary associated types, so you can write some AsyncSequence<Int, Never> (element Int, no failure) for a return type or a parameter, and any AsyncSequence<Int, Never> when you need a stored value of mixed concrete types.

Swift some AsyncSequence and any AsyncSequence

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 readLine()), it gets the next line from this box.

The sum is 6, followed by erased 1, erased 2, erased 3. The some form keeps the exact type for the compiler and so is faster; any pays a small cost for flexibility. The Opaque and Existential Types lesson explains the trade-off.

Cancellation and async sequences

If the task that runs a for await loop is cancelled, the loop does not stop at once by magic. For AsyncStream, cancellation makes the iterator's next() return nil at its next opportunity, so the loop ends, and onTermination reports .cancelled. A hand-written iterator should check Task.isCancelled (or call try Task.checkCancellation() in a throwing iterator) between elements. See Cancellation and Timeouts.

Common mistakes

  • Forgetting finish(). The consumer waits forever. Finish on every exit path of the producer.
  • Reading one stream from two places. Elements go to only one reader. Create one stream per consumer.
  • Using the default unbounded buffer for a fast firehose. Pick bufferingNewest or bufferingOldest, or let the consumer pull with unfolding.
  • Yielding after termination. The value is dropped silently; check the result of yield if you care.
  • Capturing mutable local state in a stream closure. Closures that run concurrently must capture Sendable state; use an actor or a Mutex.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which loop reads an AsyncSequence called events?

    An async sequence may suspend between elements, so it needs for await (or for try await if it can throw). A plain for-in needs a regular Sequence.
  2. 2. What happens when two for await loops read the same AsyncStream one after the other?

    Each element of an AsyncStream is delivered to one consumer. After the first loop has drained and finished the stream, the second finds it empty.
  3. 3. What is the effect of forgetting to call continuation.finish() on a stream that a for await loop reads?

    The loop ends only when the stream signals completion (or the task is cancelled). Without finish() the loop keeps waiting.
  4. 4. Which buffering policy keeps only the latest two elements and drops older ones when full?

    .bufferingNewest(n) drops the oldest buffered element to make room. .bufferingOldest(n) does the opposite: it drops the new ones.
  5. 5. When would you use AsyncStream(unfolding:) instead of the continuation initializer?

    unfolding calls your closure each time the consumer asks for an element and ends when it returns nil. There is no buffer, so nothing is produced ahead of demand.

Summary

  • An AsyncSequence delivers elements over time and is read with for await (or for try await when it can fail); the loop ends when the sequence returns nil from next().
  • You can write one with an AsyncIteratorProtocol type, but AsyncStream is usually simpler: yield elements through a continuation and finish() when done.
  • AsyncStream.makeStream(of:) creates the stream and continuation separately, which suits a producer in one place and a consumer in another.
  • A stream has a single reader, buffers without limit by default, and accepts .bufferingNewest(n) or .bufferingOldest(n) policies.
  • AsyncThrowingStream adds finish(throwing:); AsyncStream(unfolding:) produces elements only when asked.
  • onTermination tells the producer to clean up when the reader finishes or is cancelled.
  • Operators such as map, filter, reduce and prefix work on any async sequence; merge sources by feeding a new stream from a task group.

Next: Cancellation and Timeouts shows how tasks are asked to stop and how to put a time limit on work.