Swift 中的 AsyncThrowingStream 和 AsyncStream

AsyncThrowingStream 和 AsyncStream是Swift 5.5中由SE-314引入的併發框架的一部分。異步流允許你替換基於閉包或 Combine 發佈器的現有代碼。

在深入研究圍繞拋出流的細節之前，如果你還沒有閱讀我的文章，我建議你先閱讀我的文章，內容包括async-await。本文解釋的大部分代碼將使用那裏解釋的API。

什麼是 AsyncThrowingStream？

你可以把 AsyncThrowingStream 看作是一個有可能導致拋出錯誤的元素流。他的值隨着時間的推移而傳遞，流可以通過一個結束事件來關閉。一旦發生錯誤，結束事件既可以是成功，也可以是失敗。

什麼是 AsyncStream?

AsyncStream 類似於拋出的變體，但絕不會導致拋出錯誤。一個非拋出型的異步流會根據明確的完成調用或流的取消而完成。

在這篇文章中，我們將解釋如何使用AsyncThrowingStream。除了發生錯誤處理的部分，代碼示例與AsyncStream類似。

如何使用 AsyncThrowingStream

AsyncThrowingStream可以很好地替代現有的基於閉包的代碼，如進度和完成處理程序。爲了更好地理解我的意思，我將向你介紹我們在 WeTransfer 應用程序中遇到的一個場景。

在我們的應用程序中，我們有一個基於閉包的現有類，叫做FileDownloader：

struct FileDownloader {
    enum Status {
        case downloading(Float)
        case finished(Data)
    }

    func download(_ url: URL, progressHandler: (Float) -> Void, completion: (Result<Data, Error>) -> Void) throws {
        // .. Download implementation
    }
}

文件下載器接受一個URL，報告進度情況，並完成一個包含下載數據的結果或在失敗時顯示一個錯誤。

文件下載器在文件下載過程中報告一個數值流。在這種情況下，它報告的是一個狀態值流，以報告正在運行的下載的當前狀態。FileDownloader是一個完美的例子，你可以重寫一段代碼來使用AsyncThrowingStream。然而，重寫需要你在實現層面上也重寫你的代碼，所以讓我們定義一個重載方法來代替：

extension FileDownloader {
    func download(_ url: URL) -> AsyncThrowingStream<Status, Error> {
        return AsyncThrowingStream { continuation in
            do {
                try self.download(url, progressHandler: { progress in
                    continuation.yield(.downloading(progress))
                }, completion: { result in
                    switch result {
                    case .success(let data):
                        continuation.yield(.finished(data))
                        continuation.finish()
                    case .failure(let error):
                        continuation.finish(throwing: error)
                    }
                })
            } catch {
                continuation.finish(throwing: error)
            }
        }
    }
}

正如你所看到的，我們把下載方法包裹在一個AsyncThrowingStream裏面。我們將流的值Status的類型描述爲一個通用的類型，允許我們用狀態更新來延續流。

只要有錯誤發生，我們就會通過拋出一個錯誤來完成流。在完成處理程序的情況下，我們要麼通過拋出一個錯誤來完成，要麼用一個不拋出的完成回調來跟進數據的產生。

switch result {
case .success(let data):
    continuation.yield(.finished(data))
    continuation.finish()
case .failure(let error):
    continuation.finish(throwing: error)
}

在收到最後的狀態更新後，不要忘記finish()回調，這一點至關重要。否則，我們將保持流的存活，而實現層面的代碼將永遠不會繼續。

我們可以通過使用另一個yield方法來重寫上述代碼，接受一個Result枚舉作爲參數：

continuation.yield(with: result.map { .finished($0) })
continuation.finish()

重寫後的代碼簡化了我們的代碼，並去掉了switch-case 代碼。我們必須映射我們的Reslut枚舉以匹配預期的Status值。如果我們產生一個失敗的結果，我們的流將在拋出包含的錯誤後結束。

AsyncThrowingStream 迭代

一旦你配置好你的異步拋出流，你就可以開始在數值流上進行迭代。在我們的FileDownloader例子中，它將看起來如下所示：

do {
    for try await status in download(url) {
        switch status {
        case .downloading(let progress):
            print("Downloading progress: \(progress)")
        case .finished(let data):
            print("Downloading completed with data: \(data)")
        }
    }
    print("Download finished and stream closed")
} catch {
    print("Download failed with \(error)")
}

我們處理任何狀態的更新，並且我們可以使用catch閉包來處理任何發生的錯誤。你可以使用基於AsyncSequence接口的for ... in循環進行迭代，這對AsyncStream來說是一樣的。

如果你遇到了類似的編譯錯誤:

‘async’ in a function that does not support concurrency

你可能想讀一讀我的文章，其中深入介紹了async-await。

上述代碼示例中的打印語句有助於你理解 AsyncThrowingStream的生命週期。你可以替換打印語句來處理進度更新和處理數據，爲你的用戶實現可視化。

調試 AsyncStream

如果一個流不能報告數值，我們可以通過放置斷點來調試流產生的回調。雖然也可能是上面的“Download finished and stream closed” 的打印語句不會調用，這意味着你在實現層的代碼永遠不會繼續。後者可能是一個未完成的流的結果。

爲了驗證，我們可以利用onTermination回調：

func download(_ url: URL) -> AsyncThrowingStream<Status, Error> {
    return AsyncThrowingStream { continuation in

        ///  配置一個終止回調，以瞭解你的流的生命週期。
        continuation.onTermination = { @Sendable status in
            print("Stream terminated with status \(status)")
        }

        // ..
    }
}

回調在流終止時被調用，它將告訴你你的流是否還活着。我推薦你閱讀Sendable 和 @Sendable 閉包——代碼實例詳解來理解@Sendable屬性。

如果出現了錯誤，輸出結果可能如下:

Stream terminated with status finished(Optional(FileDownloader.FileDownloadingError.example))

上述輸出只有在使用AsyncThrowingStream時才能實現。如果是一個普通的AsyncStream，完成的輸出看起來如下：

Stream terminated with status finished

而取消的結果對這兩種類型的流來說都是這樣的:

Stream terminated with status cancelled

你也可以在流結束後使用這個終止回調進行任何清理。例如，刪除任何觀察者或在文件下載後清理磁盤空間。

取消一個 AsyncStream

一個AsyncStream或AsyncThrowingStream可以由於一個封閉的任務被取消而取消。一個例子可以如下：

let task = Task.detached {
    do {
        for try await status in download(url) {
            switch status {
            case .downloading(let progress):
                print("Downloading progress: \(progress)")
            case .finished(let data):
                print("Downloading completed with data: \(data)")
            }
        }
    } catch {
        print("Download failed with \(error)")
    }
}
task.cancel()

一個流在超出範圍或包圍的任務取消時就會取消。如前所述，取消將相應地觸發onTermination回調。

繼續你的Swift併發之旅

如果你喜歡你所讀到的關於異步流的內容，你可能也會喜歡其他的併發主題:

• Swift 中的 async/await
• Swift 中的 async let
• Swift 中的 Task
• Swift 中的 Actors 使用以如何及防止數據競爭
• Swift 中的 MainActor 使用和主線程調度
• 理解 Swift Actor 隔離關鍵字：nonisolated 和 isolated
• Swift 中的 Sendable 和 @Sendable 閉包
• Swift 中的 AsyncThrowingStream 和 AsyncStream
• Swift 中的 AsyncSequence

結論

AsyncThrowingStream或AsyncStream是重寫基於閉包的現有代碼到支持 async-awai t的替代品的好方法。你可以提供一個連續的值流，並在成功或失敗時完成一個流。你可以使用基於AsyncSequence APIs的 for 循環在實現層面上迭代值。

• 轉自 AsyncThrowingStream and AsyncStream explained with code examples