Swift AsyncSequence: Write Cleaner Asynchronous Code

Swift's AsyncSequence revolutionizes how you work with asynchronous streams of data, combining the elegance of sequences with the power of Swift's concurrency model. By integrating seamlessly with async/await, it simplifies handling asynchronous code, whether you're processing real-time events, handling backpressure, or building custom sequences.

This blog dives into creating and managing AsyncSequence, debugging and testing strategies, and leveraging advanced concurrency features to optimize performance.

What is AsyncSequence in Swift?

The AsyncSequence in Swift is a powerful abstraction introduced in Swift 5.5, enabling you to work with asynchronous streams of data using the async/await syntax. Unlike a regular sequence, which operates synchronously, an asynchronous sequence generates its elements over time, making it ideal for scenarios involving asynchronous code, such as fetching remote data or processing events as they arrive.

To better understand it, think of an AsyncSequence as the asynchronous counterpart of the familiar Sequence. While a synchronous sequence produces elements all at once, an asynchronous sequence supplies each element asynchronously, pausing execution at a suspension point until the next element becomes available.

The difference between AsyncSequence and AsyncStream lies in their use cases. While AsyncSequence emphasizes lazy iteration and predictable iteration behavior, AsyncStream is more flexible for custom asynchronous sequences with dynamic element generation.

Example: Using AsyncSequence with Swift's Concurrency Features

Copy
1import Foundation
2
3struct Counter: AsyncSequence {
4    typealias Element = Int
5
6    struct AsyncIterator: AsyncIteratorProtocol {
7        var current = 1
8        let limit: Int
9
10        mutating func next() async -> Int? {
11            guard current <= limit else { return nil }
12            let nextValue = current
13            current += 1
14            return nextValue
15        }
16    }
17
18    let limit: Int
19
20    func makeAsyncIterator() -> AsyncIterator {
21        return AsyncIterator(limit: limit)
22    }
23}
24
25// Using the Counter AsyncSequence
26Task {
27    let counter = Counter(limit: 5)
28    for await value in counter {
29        print(value) // Prints 1, 2, 3, 4, 5
30    }
31}

In this example, the Counter async sequence produces elements one at a time until the limit is reached, demonstrating how async sequences can be structured using the makeAsyncIterator requirement.

Key Use Cases for AsyncSequence

An asynchronous sequence is useful whenever you need to handle data that arrives over time rather than all at once. Examples include reading data from a network stream, processing events in a user interface, or reacting to changes in shared data sources like databases. These scenarios treat asynchronous sequences as a seamless way to handle streams of values in Swift apps.

Example: Handling Asynchronous Data Streams

Copy
1import SwiftAsyncAlgorithms
2
3Task {
4    let numbers = [1, 2, 3, 4].async // Convert an array to an async sequence
5    for await number in numbers {
6        print(number) // Prints each number asynchronously
7    }
8}

The Swift Async Algorithms package provides utilities for operations like filtering, mapping, and merging async sequences, making it easier to build robust Swift apps that leverage structured concurrency and the async/await model.

How AsyncSequence Works in Swift

Conforming to AsyncSequence Protocol

To work with async sequences effectively, it is crucial to understand the AsyncSequence protocol and its primary components. At its core, an AsyncSequence must conform to the AsyncSequence protocol by implementing the makeAsyncIterator method. This method produces an asynchronous iterator that iterates over the sequence's elements.

Example: Custom AsyncSequence

Copy
1struct Countdown: AsyncSequence {
2    typealias Element = Int
3
4    struct AsyncIterator: AsyncIteratorProtocol {
5        var current: Int
6
7        mutating func next() async -> Int? {
8            guard current > 0 else { return nil }
9            let value = current
10            current -= 1
11            return value
12        }
13    }
14
15    let start: Int
16
17    func makeAsyncIterator() -> AsyncIterator {
18        return AsyncIterator(current: start)
19    }
20}
21
22// Using the Countdown AsyncSequence
23Task {
24    let countdown = Countdown(start: 5)
25    for await value in countdown {
26        print(value) // Prints: 5, 4, 3, 2, 1
27    }
28}

In this example, the makeAsyncIterator function initializes the iterator, and the iterator’s next method generates new elements until the sequence ends by returning nil.

AsyncSequence Methods

Transformations like map and filter allow you to manipulate the sequence's data flow without disrupting the asynchronous nature of the operation.

Example: Transforming AsyncSequences

Copy
1import SwiftAsyncAlgorithms
2
3Task {
4    let numbers = (1...10).async // Convert range to async sequence
5
6    let evenNumbers = numbers.filter { $0 % 2 == 0 }
7    let squares = evenNumbers.map { $0 * $0 }
8
9    for await square in squares {
10        print(square) // Prints 4, 16, 36, 64, 100
11    }
12}

Here, the filter method selects even numbers, and the map method squares each value. These operations are applied lazily and only as elements are iterated.

Building Custom AsyncSequences

Steps to Define a Custom AsyncSequence

1. Define the AsyncSequence Type: Create a struct or class conforming to AsyncSequence. Specify the Element type.
2. Implement makeAsyncIterator: Define the method that returns an AsyncIterator.
3. Create the AsyncIterator: Implement the iterator as a nested struct or separate type conforming to AsyncIteratorProtocol. Define the mutating func next() method.
4. Handle State: Use local variables or shared data to maintain intermediate state between iterations.

Practical Example: Custom AsyncSequence

Copy
1import Foundation
2
3struct RandomNumberGenerator: AsyncSequence {
4    typealias Element = Int
5
6    struct AsyncIterator: AsyncIteratorProtocol {
7        let count: Int
8        var current = 0
9
10        mutating func next() async -> Int? {
11            guard current < count else { return nil }
12            current += 1
13            return Int.random(in: 1...100)
14        }
15    }
16
17    let count: Int
18
19    func makeAsyncIterator() -> AsyncIterator {
20        return AsyncIterator(count: count)
21    }
22}
23
24// Using the RandomNumberGenerator
25Task {
26    let randomNumbers = RandomNumberGenerator(count: 5)
27    for await number in randomNumbers {
28        print("Generated number: \(number)")
29    }
30}

Debugging and Testing AsyncSequences

Debugging and testing custom async sequences can be challenging due to their asynchronous nature. Effective debugging techniques include using print statements, logging, and Xcode’s debugging tools.

Unit Test Example

Copy
1import XCTest
2
3final class RandomNumberGeneratorTests: XCTestCase {
4    func testRandomNumberGeneratorProducesCorrectCount() async throws {
5        let generator = RandomNumberGenerator(count: 5)
6        var numbers: [Int] = []
7
8        for await number in generator {
9            numbers.append(number)
10        }
11
12        XCTAssertEqual(numbers.count, 5, "Should produce exactly 5 numbers")
13    }
14
15    func testRandomNumberGeneratorTerminatesProperly() async throws {
16        let generator = RandomNumberGenerator(count: 0)
17
18        var iterator = generator.makeAsyncIterator()
19        let firstElement = await iterator.next()
20
21        XCTAssertNil(firstElement, "Should return nil immediately for zero count")
22    }
23}

Using AsyncSequence with Swift Concurrency

Example: Managing Cancellation

Copy
1import Foundation
2
3struct CancellableSequence: AsyncSequence {
4    typealias Element = Int
5
6    struct AsyncIterator: AsyncIteratorProtocol {
7        var current = 1
8        let limit: Int
9
10        mutating func next() async throws -> Int? {
11            try Task.checkCancellation()
12            guard current <= limit else { return nil }
13            let value = current
14            current += 1
15            return value
16        }
17    }
18
19    let limit: Int
20
21    func makeAsyncIterator() -> AsyncIterator {
22        return AsyncIterator(limit: limit)
23    }
24}
25
26// Using the CancellableSequence
27Task {
28    let sequence = CancellableSequence(limit: 10)
29    for try await number in sequence {
30        print(number)
31        if number == 5 { Task.cancel() }
32    }
33}

By understanding and leveraging AsyncSequence effectively, you can create robust Swift apps that elegantly handle asynchronous streams of data.