mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
This PR adds an experimental module for asynchronous streaming interfaces as a potential evolution to async sequence. These APIs are considered highly unstable and are mostly for experimentation purposes; hence, they are part of an underscored module and all APIs are hidden behind a trait. I expect significant changes to those APIs to offer more functionality such as gather scatter and more.
70 lines
2.8 KiB
Swift
70 lines
2.8 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the Swift Async Algorithms open source project
|
|
//
|
|
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
|
// Licensed under Apache License v2.0 with Runtime Library Exception
|
|
//
|
|
// See https://swift.org/LICENSE.txt for license information
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
#if UnstableAsyncStreaming && compiler(>=6.4)
|
|
public import ContainersPreview
|
|
|
|
/// Reads elements asynchronously from a source.
|
|
///
|
|
/// Adopt ``AsyncReader`` when you need to provide callee-managed buffering,
|
|
/// where the reader controls the buffer and passes a span of elements
|
|
/// to the caller through the `body` closure.
|
|
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
|
public protocol AsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
|
|
/// The type of elements this reader reads.
|
|
associatedtype ReadElement: ~Copyable
|
|
|
|
/// The error type that reading operations throw.
|
|
associatedtype ReadFailure: Error
|
|
|
|
/// Reads elements from the underlying source and passes them to the provided body closure.
|
|
///
|
|
/// This method asynchronously reads a span of elements from the source,
|
|
/// then passes them to `body` for processing.
|
|
///
|
|
/// ```swift
|
|
/// var fileReader: FileAsyncReader = ...
|
|
///
|
|
/// // Read data from a file asynchronously and process it.
|
|
/// let result = try await fileReader.read { data in
|
|
/// guard data.count > 0 else {
|
|
/// return
|
|
/// }
|
|
/// return data
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// - Parameter maximumCount: The maximum count of items you're ready
|
|
/// to process. Must be greater than zero.
|
|
/// - Parameter body: A closure that processes a span of read elements
|
|
/// and returns a value of type `Return`. When the span is empty,
|
|
/// it indicates the end of the stream.
|
|
/// - Returns: The value the body closure returns after processing the read elements.
|
|
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
|
|
/// or a `Failure` from the body closure.
|
|
mutating func read<Return: ~Copyable, Failure: Error>(
|
|
maximumCount: Int,
|
|
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Return
|
|
) async throws(EitherError<ReadFailure, Failure>) -> Return
|
|
|
|
}
|
|
|
|
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
|
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
|
|
/// Reads elements with no upper bound on span size.
|
|
public mutating func read<Return: ~Copyable, Failure: Error>(
|
|
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Return
|
|
) async throws(EitherError<ReadFailure, Failure>) -> Return {
|
|
try await read(maximumCount: .max, body: body)
|
|
}
|
|
}
|
|
#endif
|