# 3.2 异步流


# AsyncStream 的使用

[AsyncStream](https://developer.apple.com/documentation/swift/asyncstream) 是一个遵循 `AsyncSequence` 协议的结构体，借助于它，我们无需手动实现异步迭代器，就可以方便地构建异步序列。相比 `AsyncSequence` ，它是一个实现异步序列的轻量级方案。

`AsyncStream` 的构建方法如下：

```swift
init(_ elementType: Element.Type = Element.self, bufferingPolicy limit: AsyncStream<Element>.Continuation.BufferingPolicy = .unbounded, _ build: (AsyncStream<Element>.Continuation) -> Void)
```

- elementType：异步流产生的数据的类型。

- limit：缓冲策略，默认是无限数量的元素。默认情况下，异步流中生产者产出的数据元素都会进入缓冲区，直到被消费者迭代消耗掉。这有可能导致数据的生产速度大于消耗速度，从而引发系统承压或数据丢失，所以有时我们需要设定合理的缓冲策略来应对。

  `AsyncStream<Element>.Continuation.BufferingPolicy` 是一个枚举类型，有如下值：

  - case unbounded：无限数量的元素
  - case bufferingOldest(Int)：最多缓冲最旧的指定数量的元素
  - case bufferingNewest(Int)：最多缓冲最新的指定数量的元素

- build：闭包内可以获取 `AsyncStream<Element>.Continuation` 类型的结构体实例，它提供了一个 `yield(_:)` 方法将产出的数据放入缓冲区，当迭代器请求该数据时才会被消耗掉。

以前面的指数计算为例，我们可以使用 `AsyncStream` 作更精简的实现：

```swift
func powerStream(input: [(CGFloat, CGFloat)]) -> AsyncStream<CGFloat> {
  return AsyncStream { continuation in
    Task {
      for v in input {
        // 模拟耗时的异步操作
        try await Task.sleep(seconds: Double.random(in: 0...1))
        continuation.yield(pow(v.0, v.1))
      }
      continuation.finish()
    }
  }
}

let random = { CGFloat(Int.random(in: 1...$0)) }
let input = (0..<10).map { _ in (random(100), random(10)) }
for await value in powerStream(input: input) {
  print(value)
}
```

上例中的 *continuation* 实例在发送完所有的数据后，调用了 `finish()` 方法，这会使异步流进入终止状态。异步流一旦进入终止状态，就不会再生产新的数据，再次调用 `yield(_:)`、`finishe()` 方法也不再起任何作用。

在合适的时机调用 `finish()` 方法，可以条件终止异步流：

```swift
func powerStream1(input: [(CGFloat, CGFloat)]) -> AsyncStream<CGFloat> {
  return AsyncStream { continuation in
    Task {
      for v in input {
        try await Task.sleep(seconds: Double.random(in: 0...1))
        let n = pow(v.0, v.1)
        continuation.yield(n)
        // 如果出现小于 100 的值，则终止异步流
        if n < 100 {
          continuation.finish()
        }
      }
      // 如果没有出现小于 100 的值，别忘了这里调用 `finish()` 终止异步流
      continuation.finish()
    }
  }
}
```

*continuation* 可以通过回调函数 `onTermination` 监听异步流的终止行为，`onTermination` 会返回一个类型为 `AsyncStream<Element>.Continuation.Termanation` 的枚举实例，它有两个枚举值：

- case finished：*continuation* 调用 `finish()` 时触发
- case cancelled：包含异步流的任务取消时触发

我们在上面的代码基础上尝试监听异步流的终止行为：

```swift
func powerStream2(input: [(CGFloat, CGFloat)]) -> AsyncStream<CGFloat> {
  return AsyncStream { continuation in
    continuation.onTermination = { termination in
      switch termination {
      case .cancelled:
        printLog("cancelled")
      case .finished:
        printLog("finished")
      @unknown default:
        printLog("unknown")
      }
    }
    Task {
      for v in input {
        try await Task.sleep(seconds: Double.random(in: 0...1))
        let n = pow(v.0, v.1)
        continuation.yield(n)
        if n < 100 {
          continuation.finish()
        }
      }
      continuation.finish()
    }
  }
}

let random = { CGFloat(Int.random(in: 1...$0)) }
let input = (0..<10).map { _ in (random(100), random(10)) }
let task = Task {
  for await value in powerStream2(input: input) {
    print(value)
  }
}
try? await Task.sleep(seconds: 3)
task.cancel()
```

运行程序后，观察控制台，它会按照如下逻辑输出：

- 3 秒内，没有出现小于 100 的值，任务会取消，控制台会打印 "cancelled"
- 3 秒内，出现小于 100 的值，异步流会提前结束，控制台会打印 "finished"
- 3 秒后，出现小于 100 的值，异步流会提前结束，控制台会打印 "finished"
- 3 秒后，一直没有出现小于 100 的值，缓冲区的所有数据迭代完后，异步流会结束，控制台会打印 "finished"

如果异步流可能会抛出错误，可以使用 [AsyncThrowingStream](https://developer.apple.com/documentation/swift/asyncthrowingstream)，使用方法与 `AsyncStream` 类似，此处不再赘述。

`AsyncStream` 还有一个构造方法：

```swift
init(unfolding produce: @escaping () async -> Element?, onCancel: (@Sendable () -> Void)? = nil)
```

此方法可以便利地将一个生成元素的闭包“展开”成异步流，并且有个可选闭包 `onCancel` 来处理取消事件。

比如下面的代码，就是一个从闭包中构建异步流的例子。每隔一秒，异步流就会产生一个 100 以内的随机数。3 秒后，我们取消了任务，因此触发了 `onCancel` 回调。

```swift
func unfoldingStream() -> AsyncStream<Int> {
  AsyncStream<Int> {
    try? await Task.sleep(seconds: 1)
    return Int.random(in: 1...100)
  } onCancel: {
    print("Cancelled")
  }
}

let task = Task {
  for await v in unfoldingStream() {
    printLog(v)
  }
}
try? await Task.sleep(seconds: 3)
task.cancel()
```

# 使用异步流迁移旧有的回调代码

在 *Swift 并发新体验* 一节中，介绍过如何将旧有的回调代码快速迁移至 `async/await` 范式。对于异步返回单个结果的情况，迁移至 `async/await` 是简单且明智的做法。但有些需求场景并非如此，比如下载文件时，下载进度是实时更新的，类似这种异步事件会随着时间的推移持续地向调用方返回一系列数据的场景，我们可以使用异步流来升级旧有的 API。

下面的代码是基于回调机制模拟下载文件的过程，每隔 0.25 秒控制台就会打印一次下载进度，直到文件下载完成。如果发生了错误，下载过程会终止，控制台会打印错误信息。

```swift
struct CallbackToAsyncStream: View {
  
  var body: some View {
    Text("Hello")
    .task {
      donwloadFile { v in
        printLog(v.progress, (v.data == nil) ? "" : String(data: v.data!, encoding: .utf8)!)
      } errorHandler: { error in
        printLog(error)
      }
    }
  }
  
  enum DownloadError: Error {
    case downloadFileError
  }
  
  struct DownloadData {
    var progress: CGFloat
    var data: Data?
  }
  
  func donwloadFile(progressHandler: @escaping (DownloadData) -> (),
                    errorHandler: @escaping (DownloadError) -> ()) {
    var res = DownloadData(progress: 0.0)
    var error: DownloadError?
    for i in 1...4 {
      DispatchQueue.main.asyncAfter(deadline: .now() + Double(i)) {
        res.progress += 0.25
        if res.progress >= 1.0 {
          res.data = "Hello".data(using: .utf8)!
        }
        if error == nil {
          progressHandler(res)
        }
        if Bool.random() && error == nil {
          error = .downloadFileError
          errorHandler(error!)
        }
      }
    }
  }
}
```

由于下载文件可能会发生错误，这里我们使用 `AsyncThrowingStream` 来构建异步流。显然，`DownloadData` 实例是随着时间推移不断更新的，它就是需要缓冲的数据。

代码很简单，参考如下：

```swift
func asyncDownloadData() -> AsyncThrowingStream<DownloadData, Error> {
  AsyncThrowingStream { continuation in
    donwloadFile { v in
      continuation.yield(v)
      // 下载完成后，终止异步流
      if v.data != nil { continuation.finish() }
    } errorHandler: { error in
      // 抛出错误，终止异步流
      continuation.finish(throwing: error)
    }
  }
}
```



---

> 作者: 宋明  
> URL: https://apolla.cc/posts/3.2-%E5%BC%82%E6%AD%A5%E6%B5%81/  

