プロトコル

AsyncIteratorProtocol

シーケンスの値を 1 つずつ非同期的に提供する型。

iOS 13.0+ iPadOS 13.0+ Mac Catalyst 13.0+ macOS 10.15+

tvOS 13.0+ visionOS 1.0+ watchOS 6.0+

protocol AsyncIteratorProtocol<Element, Failure>

概観

AsyncIteratorProtocol は、AsyncSequence プロトコルの makeAsyncIterator() メソッドによって返される型を定義します。つまり、反復子は非同期シーケンスの値を生成するものです。このプロトコルは、シーケンスの次の要素を生成するか、シーケンスの終了を示す nil を返す、単一の非同期メソッド next() を定義します。

あなた独自の AsyncSequence を実装するには、AsyncIteratorProtocol に準拠する包み込む型を実装します。以下の例は、内部の反復子を使用して howHigh 値に達するまで単調に Int 値を生成する Counter 型を示しています。この例自体は非同期ではありませんが、カスタムシーケンスと反復子の形状、そしてそれらを非同期であるかのように使用する方法を示しています。

struct Counter: AsyncSequence {
    typealias Element = Int
    let howHigh: Int

    struct AsyncIterator: AsyncIteratorProtocol {
        let howHigh: Int
        var current = 1

        mutating func next() async -> Int? {
            // A genuinely asynchronous implementation uses the `Task`
            // API to check for cancellation here and return early.
            guard current <= howHigh else {
                return nil
            }

            let result = current
            current += 1
            return result
        }
    }

    func makeAsyncIterator() -> AsyncIterator {
        return AsyncIterator(howHigh: howHigh)
    }
}

呼び出しサイトではこれは次のようになります。

for await number in Counter(howHigh: 10) {
  print(number, terminator: " ")
}
// Prints "1 2 3 4 5 6 7 8 9 10 "

反復の終了

反復子は sequence の終了を示すために nil を返します。next() から nil が返された（またはエラーが throw された）後、反復子は終了状態に入り、それ以降の next() の呼び出しはすべて nil を返さなければなりません。

キャンセル

AsyncIteratorProtocol に準拠する型は、Swift の Task API が提供するキャンセルプリミティブを使用する必要があります。反復子は、キャンセルの処理方法と応答方法を選択できます。具体的には、以下のようになります。

next() 内で現在の Task の isCancelled 値を確認し、nil を返してシーケンスを終了します。

Task に対して checkCancellation() を呼び出します。これにより、CancellationError を throw します。

キャンセルに即座に対応するために、withTaskCancellationHandler(handler:operation:) 呼び出しを使用して next() を実装します。

反復子がキャンセル時にクリーンアップする必要がある場合は、上記のようにキャンセルをチェックした後にクリーンアップするか、参照型の場合は deinit でクリーンアップすることができます。

トピックス

反復子のトポグラフィの宣言

associatedtype Element

必須

反復値の生成

func next() async throws -> Self.Element?

非同期的に次の要素に進み、それを返します。次の要素がない場合は、シーケンスを終了します。

必須デフォルトの実装が提供されます。

インスタンスメソッド

func next(isolation: isolated (any Actor)?) async throws(Self.Failure) -> Self.Element?

非同期的に次の要素に進み、それを返します。次の要素がない場合は、シーケンスを終了します。

必須デフォルトの実装が提供されます。

以下も見よ

反復子の作成

func makeAsyncIterator() -> Self.AsyncIterator

この非同期シーケンスの要素を生成する非同期反復子を作成します。

必須

protocol AsyncIteratorProtocol