[AsyncStreaming] Add support for final elements (#422)

## Motivation

Real transports deliver structured data alongside end-of-stream and need to fuse the last write with the close. HTTP trailers and gRPC status are the obvious cases. Neither can be expressed by an empty-buffer terminator, and both lose H2/H3/QUIC's DATA+END_STREAM coalescing without a fused call.

## Modification

Adds `FinalElement: ~Copyable = Void` as a primary associated type on all four protocols. `AsyncReader` delivers it via a `consuming FinalElement?` closure parameter; `CallerAsyncReader` returns it. Both writers gain a consuming `finish` carrying the last chunk and the payload in one call.

`forEachBuffer`, `collect`, and the `pipe` variants thread the payload through. `collect` becomes consuming and gains a `Void`-final overload returning just the result.

Adds an "Alternatives considered" entry covering what would break without
this: HTTP body, gRPC, and fused close on H2/H3/QUIC.

## Result

The four protocols can back HTTP body, gRPC streaming, and similar shapes without giving up the fused close. Default `Void` keeps simple conformers unchanged; `Never` marks infinite streams. Custom and `~Copyable` payloads work end to end.
This commit is contained in:
Franz Busch authored and GitHub committed 2026-06-02 08:16:01 +02:00
1 parent 268087d1de
commit f4177dcc17
20 files changed
+992 -519

No files matched your search

@@ -27,9 +27,11 @@ extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Cop
/// Collects elements from the reader up to a specified limit and processes them.
///
/// This method continuously reads elements from the async reader, accumulating them in an
/// internal buffer until either it reaches the end of the stream or the specified limit.
/// internal buffer until either the reader signals end-of-stream (by delivering a
/// non-`nil` ``AsyncReader/FinalElement``) or the specified limit is reached.
/// Once collection completes, it passes the accumulated elements to the provided body
/// closure as an `InputSpan` for processing.
/// closure as an `InputSpan` for processing, and returns the body's result together
/// with the ``AsyncReader/FinalElement``.
///
/// - Parameters:
/// - limit: The maximum number of elements to collect. This prevents unbounded memory
@@ -37,7 +39,8 @@ extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Cop
/// - body: A closure that receives an `InputSpan` containing all collected elements and returns
/// a result of type `Result`.
///
/// - Returns: The value returned by the body closure after processing the collected elements.
/// - Returns: A tuple of the body closure's result and the ``AsyncReader/FinalElement``
/// delivered with the terminal chunk.
///
/// - Throws: An `EitherError` wrapping either a read failure (which itself may be an
/// ``AsyncReaderLeftOverElementsError`` if the reader produces more elements than the limit),
@@ -48,32 +51,38 @@ extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Cop
/// ```swift
/// var reader: SomeAsyncReader = ...
///
/// let processedData = try await reader.collect(upTo: 1000) { span in
/// let (processedData, _) = try await reader.collect(upTo: 1000) { span in
/// // Process all collected elements
/// }
/// ```
public mutating func collect<Result, Failure: Error>(
// TODO: We should make this method take an inout `RangeReplacableCollection` instead
public consuming func collect<Result, Failure: Error>(
upTo limit: Int,
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result {
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> (
Result, FinalElement
) {
var reader = self
// TODO: In the future we might want to use a temporary allocation instead
// but those don't support async closures yet.
var collectedBuffer = UniqueArray<ReadElement>()
collectedBuffer.reserveCapacity(limit)
var shouldContinue = true
var finalElement: FinalElement? = nil
do {
while shouldContinue {
try await self.read { (buffer: inout Buffer) throws(AsyncReaderLeftOverElementsError) -> Void in
guard buffer.count > 0 else {
shouldContinue = false
return
while finalElement == nil {
try await reader.read {
(buffer: inout Buffer, final: FinalElement?) throws(AsyncReaderLeftOverElementsError) -> Void in
if buffer.count > 0 {
if limit - collectedBuffer.count < buffer.count {
throw AsyncReaderLeftOverElementsError()
}
var consumer = buffer.consumeAll()
while let element = consumer.next() {
collectedBuffer.append(element)
}
}
if limit - collectedBuffer.count < buffer.count {
throw AsyncReaderLeftOverElementsError()
}
var consumer = buffer.consumeAll()
while let element = consumer.next() {
collectedBuffer.append(element)
if let final {
finalElement = final
}
}
}
@@ -82,11 +91,36 @@ extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Cop
}
do {
var consumer = collectedBuffer.consumeAll()
return try await body(consumer.drainNext())
let result = try await body(consumer.drainNext())
// The force-unwrap is safe since final element must be set at this point
return (result, finalElement!)
} catch {
throw .second(error)
}
}
}
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable, FinalElement == Void {
/// Collects elements from the reader up to a specified limit and processes them.
///
/// This overload is available when ``AsyncReader/FinalElement`` is `Void`.
/// It returns only the body closure's result — there is no payload to surface.
///
/// - Parameters:
/// - limit: The maximum number of elements to collect.
/// - body: A closure that receives an `InputSpan` of collected elements.
/// - Returns: The body closure's result.
/// - Throws: An `EitherError` wrapping either a read failure (possibly an
/// ``AsyncReaderLeftOverElementsError``) or a `Failure` from `body`.
// TODO: We should make this method take an inout `RangeReplacableCollection` instead
public consuming func collect<Result, Failure: Error>(
upTo limit: Int,
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result {
let (result, _): (Result, Void?) = try await self.collect(upTo: limit, body: body)
return result
}
}
#endif
@@ -11,87 +11,89 @@
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
import ContainersPreview
// swift-format-ignore: AmbiguousTrailingClosureOverload
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Iterates over all chunks from the reader, executing the provided body for each buffer.
/// Iterates over all chunks from the reader, executing the provided body for
/// each buffer until the stream signals end-of-stream.
///
/// This method continuously reads chunks from the async reader until the stream ends,
/// executing the provided closure for each buffer of elements read. The iteration terminates
/// when the reader produces an empty buffer, indicating the end of the stream.
///
/// - Parameter body: An asynchronous closure that processes each buffer of elements read
/// from the stream.
///
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
/// or a `Failure` from the body closure.
/// This method continuously reads chunks from the async reader, executing
/// `body` for every chunk — including the terminal one — and terminates the
/// loop when the reader delivers a non-`nil` ``AsyncReader/FinalElement``.
/// The returned value is that ``AsyncReader/FinalElement``.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// try await fileReader.forEachBuffer { buffer in
/// _ = try await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
///
/// - Parameter body: An asynchronous closure that processes each buffer of
/// elements read from the stream.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal
/// chunk, or `nil` if none was observed.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the
/// read operation or a `Failure` from the body closure.
public consuming func forEachBuffer<Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Void
) async throws(EitherError<ReadFailure, Failure>) {
var shouldContinue = true
while shouldContinue {
try await self.read { (next) throws(Failure) -> Void in
guard next.count > 0 else {
shouldContinue = false
return
}
) async throws(EitherError<ReadFailure, Failure>) -> FinalElement? {
var final: FinalElement? = nil
var done = false
while !done {
try await self.read { (next, finalElement) throws(Failure) -> Void in
try await body(&next)
if let finalElement {
final = finalElement
done = true
}
}
}
return final
}
/// Iterates over all chunks from a non-failing reader, executing the provided body for each buffer.
///
/// This method continuously reads chunks from the async reader until the stream ends,
/// executing the provided closure for each buffer of elements read. The iteration terminates
/// when the reader produces an empty buffer, indicating the end of the stream.
/// Iterates over all chunks from a non-failing reader, executing the
/// provided body for each buffer until the stream signals end-of-stream.
///
/// Use this overload when the reader's ``AsyncReader/ReadFailure`` type is `Never`.
///
/// - Parameter body: An asynchronous closure that processes each buffer of elements read
/// from the stream.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// await fileReader.forEachBuffer { buffer in
/// _ = await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
///
/// - Parameter body: An asynchronous closure that processes each buffer of
/// elements read from the stream.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
@inlinable
public consuming func forEachBuffer(
body: (inout Buffer) async -> Void
) async where ReadFailure == Never {
var shouldContinue = true
while shouldContinue {
) async -> FinalElement where ReadFailure == Never {
var finalElement: FinalElement? = nil
while finalElement == nil {
do {
try await self.read { (next) -> Void in
guard next.count > 0 else {
shouldContinue = false
return
}
try await self.read { (next, final) -> Void in
await body(&next)
if let final {
finalElement = final
}
}
} catch {
fatalError()
}
}
// The force-unwrap is safe since final element must be set at this point
return finalElement!
}
}
#endif
@@ -13,92 +13,150 @@
import ContainersPreview
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
// should additionally be constrained `& ~Escapable`. We currently can't express
// that because of a Swift lifetime-checker limitation: with `FinalElement:
// ~Copyable`, the `consuming FinalElement?` parameter on the read closure
// changes the closure's lifetime category, and capturing a `~Escapable Writer`
// inside that closure (which `pipe` does, via the `writerOpt` Optional that
// alternates between `write` and `finish` calls) trips
// "lifetime-dependent variable 'writer' escapes its scope". When that
// restriction is relaxed (or `pipe` is restructured to avoid capturing the
// writer across the read closure boundary) the constraint should be added
// back so `pipe` works for `~Escapable` writers too.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given writer.
/// Pipes all elements from this reader into the given writer, fusing the
/// terminal chunk with a `finish` on the writer.
///
/// This method consumes the reader and writes all of its elements into the writer's
/// destination. It iterates over each buffer the reader produces and hands it to the
/// writer until this reader's stream ends.
/// Consumes both the reader and the writer. Each chunk the reader produces is
/// forwarded with `writer.write(buffer:)` until the reader signals
/// end-of-stream by delivering a non-`nil` ``AsyncReader/FinalElement``. The
/// terminal chunk is fused with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataAsyncReader = ...
/// var fileWriter: FileCallerAsyncWriter = ...
/// let fileWriter: FileCallerAsyncWriter = ...
///
/// // Copy all data from reader to writer
/// try await dataReader.pipe(into: &fileWriter)
/// // Copy all data from reader to writer and finish the writer.
/// try await dataReader.pipe(into: fileWriter)
/// ```
///
/// - Parameter writer: A ``CallerAsyncWriter`` to receive the elements. The writer is
/// mutated in place and remains usable after this operation.
/// - Parameter writer: A ``CallerAsyncWriter`` to receive the elements. The
/// writer is consumed; its ``CallerAsyncWriter/finish(buffer:finalElement:)``
/// method is called with the reader's terminal chunk and ``AsyncReader/FinalElement``.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
into writer: inout Writer
into writer: consuming Writer
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where Writer: CallerAsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement {
try await self.forEachBuffer { (buffer: inout Buffer) throws(Writer.WriteFailure) in
try await writer.write(buffer: &buffer)
where
Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
try await reader.read { (buffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
if let finalElement {
let w = writerOpt.take()!
try await w.finish(buffer: &buffer, finalElement: finalElement)
done = true
} else {
try await writerOpt!.write(buffer: &buffer)
}
}
}
}
/// Pipes all elements from this reader into the given writer, copying each element from the reader's
/// buffer into the writer's buffer.
/// Pipes all elements from this reader into the given writer, copying each
/// element from the reader's buffer into the writer's buffer.
///
/// This method consumes the reader and writes all of its elements into the writer's
/// destination. Because both protocols supply their own buffer, each element must be
/// transferred from the reader's buffer into the writer's buffer. The writer's buffer
/// may be smaller than the reader's, in which case multiple `write` calls are issued
/// per chunk produced by the reader.
/// Consumes both the reader and the writer. Because both protocols supply
/// their own buffer, each element is transferred between them. The writer's
/// buffer may be smaller than the reader's, in which case multiple `write`
/// calls are issued per chunk produced by the reader.
///
/// On the terminal chunk this method drains all bytes through `write` calls
/// first and then calls ``AsyncWriter/finish(finalElement:)`` carrying
/// only the ``AsyncReader/FinalElement`` payload.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataAsyncReader = ...
/// var fileWriter: FileAsyncWriter = ...
/// let fileWriter: FileAsyncWriter = ...
///
/// // Copy all data from reader to writer
/// try await dataReader.pipe(copyingInto: &fileWriter)
/// try await dataReader.pipe(copyingInto: fileWriter)
/// ```
///
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The writer is
/// mutated in place and remains usable after this operation.
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
/// writer is consumed; its ``AsyncWriter/finish(finalElement:)`` method
/// is called with the reader's ``AsyncReader/FinalElement`` payload.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
copyingInto writer: inout Writer
copyingInto writer: consuming Writer
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where Writer: AsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement {
try await self.forEachBuffer { (readerBuffer: inout Buffer) throws(Writer.WriteFailure) in
var consumer = readerBuffer.consumeAll()
while let firstElement = consumer.next() {
var pending: ReadElement? = firstElement
do throws(EitherError<Writer.WriteFailure, Never>) {
try await writer.write { (writerBuffer: inout Writer.Buffer) in
switch consume pending {
case .some(let element):
writerBuffer.append(element)
case .none:
break
}
pending = nil
// TODO: We should check if we can use one of the append methods instead of
// element by element copies in the future
while writerBuffer.freeCapacity > 0 {
guard let element = consumer.next() else { return }
writerBuffer.append(element)
}
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
try await reader.read {
(readerBuffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
try await Self.drain(readerBuffer: &readerBuffer, into: &writerOpt!)
if let finalElement {
let w = writerOpt.take()!
try await w.finish(finalElement: finalElement)
done = true
}
}
}
}
/// Drains `readerBuffer` into `writer` across as many `write` calls as
/// required to move every element. Used by ``pipe(copyingInto:)`` to share
/// the multi-write loop between mid-stream and terminal chunks.
private static func drain<Writer>(
readerBuffer: inout Buffer,
into writer: inout Writer
) async throws(Writer.WriteFailure)
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement
{
var consumer = readerBuffer.consumeAll()
while let firstElement = consumer.next() {
var pending: ReadElement? = firstElement
do throws(EitherError<Writer.WriteFailure, Never>) {
try await writer.write { (writerBuffer: inout Writer.Buffer) in
switch consume pending {
case .some(let element):
writerBuffer.append(element)
case .none:
break
}
} catch {
switch error {
case .first(let writeFailure):
throw writeFailure
case .second:
fatalError("Unreachable")
pending = nil
while writerBuffer.freeCapacity > 0 {
guard let element = consumer.next() else { return }
writerBuffer.append(element)
}
}
} catch {
switch error {
case .first(let writeFailure): throw writeFailure
case .second: fatalError("Unreachable")
}
}
}
}
@@ -17,42 +17,74 @@ public import ContainersPreview
/// Adopt ``AsyncReader`` when you need callee-managed buffering,
/// where the reader controls the buffer and passes it to the caller
/// through the `body` closure.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by passing a non-`nil` value for the
/// `finalElement` parameter of the `body` closure. This call may also carry a
/// final chunk of elements in the buffer, allowing the reader to fuse the last
/// chunk with the end signal in a single operation.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`, which means the
/// signal carries no payload. Set ``FinalElement`` to a custom type when the
/// reader needs to deliver structured data with the terminator. Set it to `Never` to indicate
/// that the stream never ends — the `finalElement` parameter will always be `nil`.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol AsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
public protocol AsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
// TODO: Check if we should support ~Escapable elements
associatedtype ReadElement: ~Copyable
/// The container type the reader uses to pass elements to the caller.
// TODO: Check if we should support ~Escapable buffer
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the
/// end signal. Use `Never` for streams that never end.
// TODO: Check if we should support ~Escapable final elements
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the underlying source and passes them to the provided body closure.
///
/// This method asynchronously reads elements from the source into a buffer,
/// then passes the buffer to `body` for processing. When the buffer is empty,
/// the stream has ended.
/// then passes the buffer and an optional `finalElement` to `body` for
/// processing.
///
/// A `nil` value for `finalElement` means more data may follow. A non-`nil`
/// value (which is the only way a stream of `FinalElement == Void` signals
/// end) marks this chunk as the last one and delivers the final payload.
/// The terminal chunk's buffer may be empty or contain a final batch of
/// elements; the caller must process both.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// let result = try await fileReader.read { buffer in
/// guard buffer.count > 0 else {
/// return 0
/// }
/// return buffer.count
/// let result = try await fileReader.read { buffer, finalElement in
/// let processed = buffer.count
/// return (processed, finalElement != nil)
/// }
/// ```
///
/// - Parameter body: A closure that receives a mutable reference to the buffer
/// of read elements and returns a value of type `Return`. When the buffer
/// is empty, it indicates the end of the stream.
/// of read elements together with the optional end-of-stream payload and
/// returns a value of type `Return`.
/// - 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>(
body: (inout Buffer) async throws(Failure) -> Return
body: (inout Buffer, consuming FinalElement?) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
#endif
@@ -17,31 +17,48 @@ public import ContainersPreview
/// Adopt ``AsyncWriter`` when you need callee-managed buffering,
/// where the writer supplies a buffer that the caller fills
/// with elements to write.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(finalElement:)``.
/// Bulk transfer happens through ``write(_:)`` calls; ``finish(finalElement:)``
/// only carries the ``FinalElement`` payload.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(finalElement:)`` cannot
/// be called and the writer can be written to indefinitely.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol AsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
public protocol AsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
// TODO: Check if we should support ~Escapable elements
associatedtype WriteElement: ~Copyable
/// The container type the writer uses to receive elements from the caller.
// TODO: Check if we should support ~Escapable buffer
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer that `body` uses to append elements.
/// The writer manages the buffer allocation and handles the writing
/// operation once `body` completes.
/// The writer supplies a buffer, sized by the implementation, that
/// `body` uses to append elements. The writer manages the buffer
/// allocation and handles the writing operation once `body` completes.
/// Oversized payloads are split across multiple calls.
///
/// - Parameter body: A closure that receives a buffer for appending elements
/// to write. The closure returns a result of type `Return`.
///
/// - Returns: The value the body closure returns.
///
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
/// or a `Failure` from the body closure.
///
/// ## Example
///
/// ```swift
@@ -54,8 +71,34 @@ public protocol AsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// return buffer.count
/// }
/// ```
///
/// - Returns: The value the body closure returns.
///
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
/// or a `Failure` from the body closure.
mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
/// Closes the writer, delivering a ``FinalElement`` payload alongside the
/// end-of-stream signal.
///
/// - Parameter finalElement: The ``FinalElement`` payload to deliver with
/// the end signal.
/// - Throws: A ``WriteFailure`` from the underlying write operation.
consuming func finish(
finalElement: consuming FinalElement
) async throws(WriteFailure)
}
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
/// Concludes the writer with no payload.
///
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
/// ``finish(finalElement:)`` with `()`.
public consuming func finish() async throws(WriteFailure) {
try await self.finish(finalElement: ())
}
}
#endif
@@ -14,88 +14,124 @@
import ContainersPreview
import BasicContainers
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
// should additionally be constrained `& ~Escapable`. We currently can't
// express that because of a Swift lifetime-checker limitation: with
// `FinalElement: ~Copyable`, the `consuming FinalElement?` parameter on the
// reader's `read` closure changes the closure's lifetime category, and
// capturing a `~Escapable Writer` inside that closure (which `pipe` does, via
// the `writerOpt` Optional that alternates between `write` and `finish`
// calls) trips "lifetime-dependent variable 'writer' escapes its scope".
// When that restriction is relaxed (or `pipe` is restructured to avoid
// capturing the writer across the closure boundary) the constraint should be
// added back so `pipe` works for `~Escapable` writers too.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given writer.
/// Pipes all elements from this reader into the given writer, then signals
/// end-of-stream with a `finish` call on the writer.
///
/// This method consumes the reader and writes all of its elements into the writer's
/// destination. It continuously reads chunks into buffers supplied by the writer and
/// flushes them until this reader's stream ends.
/// Consumes both the reader and the writer. The reader fills the writer's
/// buffer on each iteration; once the reader signals end-of-stream, the
/// writer's ``AsyncWriter/finish(finalElement:)`` is called with the reader's
/// ``CallerAsyncReader/FinalElement``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataCallerAsyncReader = ...
/// var fileWriter: FileAsyncWriter = ...
/// let fileWriter: FileAsyncWriter = ...
///
/// // Copy all data from reader to writer
/// try await dataReader.pipe(into: &fileWriter)
/// try await dataReader.pipe(into: fileWriter)
/// ```
///
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The writer is mutated
/// in place and remains usable after this operation.
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
/// writer is consumed.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
into writer: inout Writer
into writer: consuming Writer
) async throws(EitherError<Writer.WriteFailure, ReadFailure>)
where Writer: AsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement {
var shouldContinue = true
while shouldContinue {
try await writer
.write { (buffer: inout Writer.Buffer) throws(ReadFailure) in
try await self.read(into: &buffer)
if buffer.count == 0 {
shouldContinue = false
}
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
var pendingFinal: FinalElement? = nil
try await writerOpt!
.write { (buffer: inout Writer.Buffer) throws(ReadFailure) -> Void in
pendingFinal = try await reader.read(into: &buffer)
}
if let final = pendingFinal {
let w = writerOpt.take()!
do throws(Writer.WriteFailure) {
try await w.finish(finalElement: final)
} catch {
throw .first(error)
}
done = true
}
}
}
/// Pipes all elements from this reader into the given writer through an intermediate buffer.
///
/// This method consumes the reader and writes all of its elements into the writer's
/// destination. Because neither the reader nor the writer supplies a buffer, this
/// method allocates an intermediate buffer of the requested capacity and reuses it
/// across iterations: each iteration fills the buffer from the reader and then hands
/// it to the writer to drain.
/// Consumes both the reader and the writer. Because neither protocol supplies
/// a buffer, this method allocates an intermediate buffer of the requested
/// capacity and reuses it across iterations. The terminal chunk is fused
/// with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataCallerAsyncReader = ...
/// var fileWriter: FileCallerAsyncWriter = ...
/// let fileWriter: FileCallerAsyncWriter = ...
///
/// // Copy all data from reader to writer using a 4 KB intermediate buffer
/// try await dataReader.pipe(bufferingInto: &fileWriter, intermediateCapacity: 4096)
/// try await dataReader.pipe(bufferingInto: fileWriter, intermediateCapacity: 4096)
/// ```
///
/// - Parameters:
/// - writer: A ``CallerAsyncWriter`` to receive the elements. The writer is mutated
/// in place and remains usable after this operation.
/// - intermediateCapacity: The capacity of the intermediate buffer that mediates
/// between the reader and writer. Larger values reduce the number of read and
/// write calls at the cost of memory.
/// - writer: A ``CallerAsyncWriter`` to receive the elements. The writer
/// is consumed.
/// - intermediateCapacity: The capacity of the intermediate buffer that
/// mediates between the reader and writer.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
bufferingInto writer: inout Writer,
bufferingInto writer: consuming Writer,
intermediateCapacity: Int
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where Writer: CallerAsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement {
where
Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var buffer = UniqueArray<ReadElement>(minimumCapacity: intermediateCapacity)
var shouldContinue = true
while shouldContinue {
var done = false
while !done {
let final: FinalElement?
do throws(ReadFailure) {
try await self.read(into: &buffer)
final = try await reader.read(into: &buffer)
} catch {
throw .first(error)
}
if buffer.count == 0 {
shouldContinue = false
} else {
if let final {
let w = writerOpt.take()!
do throws(Writer.WriteFailure) {
try await writer.write(buffer: &buffer)
try await w.finish(buffer: &buffer, finalElement: final)
} catch {
throw .second(error)
}
done = true
} else if buffer.count > 0 {
do throws(Writer.WriteFailure) {
try await writerOpt!.write(buffer: &buffer)
assert(buffer.count == 0, "CallerAsyncWriter must drain the buffer during write(buffer:)")
} catch {
throw .second(error)
@@ -17,23 +17,53 @@ public import ContainersPreview
/// Adopt ``CallerAsyncReader`` when you need caller-managed buffering,
/// where the caller supplies a buffer that the reader fills
/// with elements.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by returning a non-`nil` ``FinalElement``
/// from ``read(into:)``. The same call may also append a final batch of
/// elements to the caller's buffer, allowing the reader to fuse the last
/// chunk with the end signal.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`. Use a custom type
/// to carry data along with the end signal, or `Never` for streams that never
/// end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol CallerAsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
public protocol CallerAsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
// TODO: Check if we should support ~Escapable elements
associatedtype ReadElement: ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal, or `Never` for streams that never end.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the source into the provided buffer.
///
/// This method appends elements into `buffer`. When the read operation
/// reaches the end of the source, it appends no elements.
/// This method appends elements into `buffer`. A non-`nil` return value
/// signals end-of-stream and delivers the final payload. The call may
/// also append a final batch of elements before signaling end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Returns: A non-`nil` ``FinalElement`` if this call delivered the
/// end-of-stream signal; `nil` if more elements may follow.
/// - Throws: A `ReadFailure` from the underlying read operation.
// TODO: Check if we should support ~Escapable buffer
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable
) async throws(ReadFailure) -> FinalElement? where Buffer.Element: ~Copyable
}
#endif
@@ -11,28 +11,49 @@
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
import BasicContainers
/// Writes elements asynchronously from a caller-provided buffer.
///
/// Adopt ``CallerAsyncWriter`` when you need caller-managed buffering,
/// where the caller provides a buffer of elements for the writer
/// to consume.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(buffer:finalElement:)``.
/// The `finish` call communicates a final buffer (if any) and the
/// ``FinalElement`` payload, allowing implementations to fuse the last data
/// frame with the end signal on transports that support it.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(buffer:finalElement:)``
/// cannot be called and the writer can be written to indefinitely.
///
/// Conformers must accept zero, one, or many `write(buffer:)` calls, optionally
/// followed by a single `finish(buffer:finalElement:)` call. After `finish`
/// returns, the writer is consumed and no further calls are valid.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
public protocol CallerAsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
// TODO: Check if we should support ~Escapable elements
associatedtype WriteElement: ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Writes elements from the provided buffer to the underlying destination.
///
/// This method asynchronously writes all elements from the provided buffer to the destination
/// the writer represents.
///
/// - Parameter buffer: The buffer of elements to write.
///
/// - Throws: A `WriteFailure` from the underlying write operation.
/// This method asynchronously writes all elements from the provided buffer
/// to the underlying destination.
///
/// ## Example
///
@@ -42,8 +63,42 @@ public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escap
///
/// try await fileWriter.write(buffer: &data)
/// ```
///
/// - Parameter buffer: The buffer of elements to write.
///
/// - Throws: A `WriteFailure` from the underlying write operation.
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
/// Sends the final buffer and ``FinalElement`` payload, and signals
/// end-of-stream to the destination.
///
/// The buffer may be empty if there is no remaining content to emit
/// alongside the terminator. When ``FinalElement`` is `Void`, use the
/// closure-less ``finish()`` convenience instead of passing `()` explicitly.
///
/// - Parameters:
/// - buffer: The buffer of remaining elements to write alongside the
/// terminator.
/// - finalElement: The ``FinalElement`` payload to deliver with the end
/// signal.
/// - Throws: A `WriteFailure` from the underlying write operation.
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming FinalElement
) async throws(WriteFailure) where Buffer.Element: ~Copyable
}
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
extension CallerAsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
/// Concludes the writer with no final buffer and no extra payload.
///
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
/// ``finish(buffer:finalElement:)`` with an empty buffer and `()`.
public consuming func finish() async throws(WriteFailure) {
var empty = UniqueArray<WriteElement>()
try await self.finish(buffer: &empty, finalElement: ())
}
}
#endif
+400 -131
View File
@@ -13,9 +13,10 @@
Introduces four protocols for asynchronous streaming with caller- and
callee-managed buffer ownership for both reading and writing. Supports
noncopyable types, bulk/chunked access, and bidirectional streaming while
maintaining structured concurrency. Provides bridging extensions between
`AsyncReader` and `AsyncSequence`.
noncopyable types, bulk/chunked access, fused end-of-stream signaling with an
optional final-element payload, and bidirectional streaming while maintaining
structured concurrency. Provides bridging extensions between `AsyncReader` and
`AsyncSequence`.
## Motivation
@@ -276,29 +277,76 @@ The callee-owned reader controls the buffer and passes a mutable reference to it
through a scoped closure. This is the preferred protocol for read streams.
```swift
public protocol AsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be read.
associatedtype ReadElement: ~Copyable
/// Reads elements asynchronously from a source using callee-managed buffering.
///
/// Adopt ``AsyncReader`` when you need callee-managed buffering,
/// where the reader controls the buffer and passes it to the caller
/// through the `body` closure.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by passing a non-`nil` value for the
/// `finalElement` parameter of the `body` closure. This call may also carry a
/// final chunk of elements in the buffer, allowing the reader to fuse the last
/// chunk with the end signal in a single operation.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`, which means the
/// signal carries no payload. Set ``FinalElement`` to a custom type when the
/// reader needs to deliver structured data with the terminator. Set it to `Never` to indicate
/// that the stream never ends — the `finalElement` parameter will always be `nil`.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
public protocol AsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
associatedtype ReadElement: ~Copyable
/// The container type the reader uses to pass elements to the caller.
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The container type the reader uses to pass elements to the caller.
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The type of error thrown during reading.
associatedtype ReadFailure: Error
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// Reads elements from the source and passes them to the body closure.
///
/// The reader fills an internal buffer from its source and passes a mutable
/// reference to it to `body`. When the buffer is empty, the stream
/// has ended.
///
/// - Parameter body: A closure that processes the read elements.
/// - Returns: The value returned by the body closure.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read
/// operation or a `Failure` from the body closure.
mutating func read<Return, Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the
/// end signal. Use `Never` for streams that never end.
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the underlying source and passes them to the provided body closure.
///
/// This method asynchronously reads elements from the source into a buffer,
/// then passes the buffer and an optional `finalElement` to `body` for
/// processing.
///
/// A `nil` value for `finalElement` means more data may follow. A non-`nil`
/// value (which is the only way a stream of `FinalElement == Void` signals
/// end) marks this chunk as the last one and delivers the final payload.
/// The terminal chunk's buffer may be empty or contain a final batch of
/// elements; the caller must process both.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// let result = try await fileReader.read { buffer, finalElement in
/// let processed = buffer.count
/// return (processed, finalElement != nil)
/// }
/// ```
///
/// - Parameter body: A closure that receives a mutable reference to the buffer
/// of read elements together with the optional end-of-stream payload and
/// returns a value of type `Return`.
/// - 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>(
body: (inout Buffer, consuming FinalElement?) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
```
@@ -308,23 +356,56 @@ The caller provides a buffer that the reader fills with elements from the
source.
```swift
public protocol CallerAsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be read.
associatedtype ReadElement: ~Copyable
/// Reads elements asynchronously into a caller-provided buffer.
///
/// Adopt ``CallerAsyncReader`` when you need caller-managed buffering,
/// where the caller supplies a buffer that the reader fills
/// with elements.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by returning a non-`nil` ``FinalElement``
/// from ``read(into:)``. The same call may also append a final batch of
/// elements to the caller's buffer, allowing the reader to fuse the last
/// chunk with the end signal.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`. Use a custom type
/// to carry data along with the end signal, or `Never` for streams that never
/// end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
public protocol CallerAsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
associatedtype ReadElement: ~Copyable
/// The type of error thrown during reading.
associatedtype ReadFailure: Error
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// Reads elements from the source into the provided buffer.
///
/// Appends elements into `buffer`. When the read operation reaches the
/// end of the source, no elements are appended.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Throws: A `ReadFailure` from the underlying read operation.
mutating func read<Buffer: RangeReplaceableContainer<ReadElement>>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal, or `Never` for streams that never end.
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the source into the provided buffer.
///
/// This method appends elements into `buffer`. A non-`nil` return value
/// signals end-of-stream and delivers the final payload. The call may
/// also append a final batch of elements before signaling end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Returns: A non-`nil` ``FinalElement`` if this call delivered the
/// end-of-stream signal; `nil` if more elements may follow.
/// - Throws: A `ReadFailure` from the underlying read operation.
// TODO: Check if we should support ~Escapable buffer
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) -> FinalElement? where Buffer.Element: ~Copyable
}
```
@@ -334,22 +415,78 @@ The caller provides a buffer of elements for the writer to consume. This is the
preferred protocol for write streams.
```swift
public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be written.
associatedtype WriteElement: ~Copyable
/// Writes elements asynchronously from a caller-provided buffer.
///
/// Adopt ``CallerAsyncWriter`` when you need caller-managed buffering,
/// where the caller provides a buffer of elements for the writer
/// to consume.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(buffer:finalElement:)``.
/// The `finish` call communicates a final buffer (if any) and the
/// ``FinalElement`` payload, allowing implementations to fuse the last data
/// frame with the end signal on transports that support it.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(buffer:finalElement:)``
/// cannot be called and the writer can be written to indefinitely.
///
/// Conformers must accept zero, one, or many `write(buffer:)` calls, optionally
/// followed by a single `finish(buffer:finalElement:)` call. After `finish`
/// returns, the writer is consumed and no further calls are valid.
public protocol CallerAsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
associatedtype WriteElement: ~Copyable
/// The type of error thrown during writing.
associatedtype WriteFailure: Error
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// Writes elements from the provided buffer to the destination.
///
/// Asynchronously writes all elements from the provided buffer.
///
/// - Parameter buffer: The buffer of elements to write.
/// - Throws: A `WriteFailure` from the underlying write operation.
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`.
associatedtype FinalElement: ~Copyable = Void
/// Writes elements from the provided buffer to the underlying destination.
///
/// This method asynchronously writes all elements from the provided buffer
/// to the underlying destination.
///
/// ## Example
///
/// ```swift
/// var fileWriter: FileAsyncWriter = ...
/// var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
///
/// try await fileWriter.write(buffer: &data)
/// ```
///
/// - Parameter buffer: The buffer of elements to write.
///
/// - Throws: A `WriteFailure` from the underlying write operation.
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
/// Sends the final buffer and ``FinalElement`` payload, and signals
/// end-of-stream to the destination.
///
/// The buffer may be empty if there is no remaining content to emit
/// alongside the terminator. When ``FinalElement`` is `Void`, use the
/// closure-less ``finish()`` convenience instead of passing `()` explicitly.
///
/// - Parameters:
/// - buffer: The buffer of remaining elements to write alongside the
/// terminator.
/// - finalElement: The ``FinalElement`` payload to deliver with the end
/// signal.
/// - Throws: A `WriteFailure` from the underlying write operation.
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming FinalElement
) async throws(WriteFailure) where Buffer.Element: ~Copyable
}
```
@@ -358,32 +495,116 @@ public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escap
The writer provides a buffer that the caller fills with elements to write.
```swift
public protocol AsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be written.
associatedtype WriteElement: ~Copyable
/// Writes elements asynchronously to a destination using callee-managed buffering.
///
/// Adopt ``AsyncWriter`` when you need callee-managed buffering,
/// where the writer supplies a buffer that the caller fills
/// with elements to write.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(finalElement:)``.
/// Bulk transfer happens through ``write(_:)`` calls; ``finish(finalElement:)``
/// only carries the ``FinalElement`` payload.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(finalElement:)`` cannot
/// be called and the writer can be written to indefinitely.
public protocol AsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
associatedtype WriteElement: ~Copyable
/// The container type the writer uses to receive elements from the caller.
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The container type the writer uses to receive elements from the caller.
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The type of error thrown during writing.
associatedtype WriteFailure: Error
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer that the `body` closure fills with
/// elements. After the closure returns, the writer handles the actual
/// write operation.
///
/// - Parameter body: A closure that receives a mutable buffer to fill.
/// - Returns: The value returned by the body closure.
/// - Throws: An `EitherError` containing either a `WriteFailure` from the
/// write operation or a `Failure` from the body closure.
mutating func write<Return, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal.
associatedtype FinalElement: ~Copyable = Void
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer, sized by the implementation, that
/// `body` uses to append elements. The writer manages the buffer
/// allocation and handles the writing operation once `body` completes.
/// Oversized payloads are split across multiple calls.
///
/// - Parameter body: A closure that receives a buffer for appending elements
/// to write. The closure returns a result of type `Return`.
///
/// ## Example
///
/// ```swift
/// var writer: SomeAsyncWriter = ...
///
/// try await writer.write { buffer in
/// for item in items {
/// buffer.append(item)
/// }
/// return buffer.count
/// }
/// ```
///
/// - Returns: The value the body closure returns.
///
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
/// or a `Failure` from the body closure.
mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
/// Closes the writer, delivering a ``FinalElement`` payload alongside the
/// end-of-stream signal.
///
/// - Parameter finalElement: The ``FinalElement`` payload to deliver with
/// the end signal.
/// - Throws: A ``WriteFailure`` from the underlying write operation.
consuming func finish(
finalElement: consuming FinalElement
) async throws(WriteFailure)
}
```
### Final-element payload
Every protocol carries a `FinalElement` associated type, the data, if any,
that the stream delivers alongside its end-of-stream signal. The default is
`Void`, which carries no extra payload; the signal itself is the only
information conveyed. Besides `Void` final elements there are two other
possibilities:
* **`FinalElement == Never`** marks a stream as endless. For readers, the
terminal signal can never fire (because `Never?` only inhabits `nil`), so
callers can rely statically on the absence of termination — useful for
clocks, log tails, and other endless sources. The same applies symmetrically
to writers: with `FinalElement == Never`, `finish` cannot be called, so the
writer can be written to indefinitely but never explicitly terminated.
Examples include logging sinks, metrics emitters, and continuous output
streams.
* **A custom payload type** lets the stream attach structured data to the
close: HTTP trailers, a checksum, a frame's status code. An example is HTTP,
which specializes `FinalElement` to `HTTPFields?` so the last DATA frame and
the trailers can be fused into a single transport operation.
For readers, the terminal `read` call may also carry a final chunk of payload
elements alongside the end signal; the caller must process both. For writers,
`finish` is a consuming operation that delivers the `FinalElement` payload and
signals end-of-stream. `CallerAsyncWriter.finish(buffer:finalElement:)` also
carries a final buffer, so the last buffer and the terminator can be fused
into a single transport operation. `AsyncWriter.finish(finalElement:)` carries
only the terminator; conformers that can fuse may defer flushing the most
recent `write(_:)` until `finish` is called, achieving the same coalescing.
Convenience extensions on the writer protocols expose a closure-less `finish()`
when `FinalElement == Void`, so callers that don't need a custom payload can
omit the explicit `()` argument.
### Bridging between `AsyncReader` and `AsyncSequence`
We provide extensions for converting between `AsyncReader` and `AsyncSequence`
@@ -484,106 +705,118 @@ core protocols are established.
### Iteration and collection helpers
Two common patterns emerge immediately when working with `AsyncReader`: iterating
over all chunks until the stream ends, and collecting elements into a buffer up
to a specified limit. We envision convenience extensions for both:
Two common patterns emerge immediately when working with `AsyncReader`:
iterating over all chunks until the stream ends, and collecting elements into
a buffer up to a specified limit. We envision convenience extensions for both,
both of which surface the `FinalElement` payload to the caller:
```swift
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Iterates over all chunks, executing `body` for each buffer until the
/// stream ends.
/// Iterates every chunk, executing `body` for each, until the reader
/// signals end-of-stream. Returns the `FinalElement` delivered with the
/// terminal chunk.
public consuming func forEachBuffer<Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Void
) async throws(EitherError<ReadFailure, Failure>)
) async throws(EitherError<ReadFailure, Failure>) -> FinalElement?
}
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Collects elements up to `limit`, then passes the accumulated
/// elements to `body` as an `InputSpan`.
public mutating func collect<Result, Failure: Error>(
/// Collects up to `limit` elements, then passes the accumulated elements
/// to `body` as an `InputSpan`. Returns the body's result together with
/// the `FinalElement`.
public consuming func collect<Result, Failure: Error>(
upTo limit: Int,
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> (Result, FinalElement?)
}
```
`forEachBuffer` provides a simple way to consume an entire stream without manually
looping over `read` calls and checking for empty buffers. `collect` accumulates
elements from multiple reads into a single buffer before processing, which is
useful when an algorithm needs all data in contiguous memory (for example,
parsing a complete message frame).
`forEachBuffer` provides a simple way to consume an entire stream without
manually looping over `read` calls and threading the end signal. `collect`
accumulates elements from multiple reads into a single buffer before
processing, which is useful when an algorithm needs all data in contiguous
memory (for example, parsing a complete message frame). A second
`where FinalElement == Void` overload of `collect` lets callers that don't
need the payload omit the tuple.
These helpers are intentionally excluded from this proposal because their error
handling semantics (particularly `collect`'s nested `EitherError` and the
These helpers are intentionally excluded from this proposal because their
error-handling shapes (particularly `collect`'s nested `EitherError` and the
`AsyncReaderLeftOverElementsError` overflow behavior) benefit from real-world
usage feedback before stabilization.
### Piping a reader into a writer
A common pattern when bridging streams is piping all elements from a reader to
a writer. We envision convenience extensions on each reader protocol that
consume the reader and forward its elements into a matching writer.
A common pattern when bridging streams is piping all elements from a reader
to a writer. We envision convenience extensions on each reader protocol that
consume both sides and forward the elements — including the `FinalElement`
payload, fused with the writer's `finish` where the protocols allow it.
When the buffer ownership of the reader and writer aligns, the buffer can flow
directly between the two without an intermediate stage:
When the buffer ownership of the reader and writer aligns, the buffer can
flow directly between the two without an intermediate stage:
```swift
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given callee-owned writer
/// until the stream ends.
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given caller-owned
/// writer, fusing the terminal chunk with `finish` so the transport
/// sees a single close.
public consuming func pipe<Writer>(
into writer: inout Writer
) async throws where Writer: AsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement
into writer: consuming Writer
) async throws
where Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
}
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Pipes all elements from this reader into the given caller-owned writer
/// until the stream ends.
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given callee-owned
/// writer.
public consuming func pipe<Writer>(
into writer: inout Writer
) async throws where Writer: CallerAsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement
into writer: consuming Writer
) async throws
where Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
}
```
The two remaining combinations require a transfer between separate buffers. We
distinguish them with explicit argument labels so the cost is visible at the
call site:
The two remaining combinations require a transfer between separate buffers.
We distinguish them with explicit argument labels so the cost is visible at
the call site:
```swift
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given callee-owned writer,
/// copying each element from the reader's buffer into the writer's buffer.
///
/// Both protocols supply their own buffer, so each element is moved between
/// them. The writer's buffer may be smaller than the reader's, in which case
/// multiple `write` calls are issued per chunk produced by the reader.
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given callee-owned
/// writer, copying each element from the reader's buffer into the
/// writer's buffer.
public consuming func pipe<Writer>(
copyingInto writer: inout Writer
) async throws where Writer: AsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement
copyingInto writer: consuming Writer
) async throws
where Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
}
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given caller-owned writer
/// through an intermediate buffer of the requested capacity.
///
/// Neither protocol supplies a buffer, so this method allocates a single
/// `UniqueArray` and reuses it across iterations. The writer must drain all
/// elements during each `write(buffer:)` call.
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given caller-owned
/// writer through an intermediate buffer of the requested capacity.
public consuming func pipe<Writer>(
bufferingInto writer: inout Writer,
bufferingInto writer: consuming Writer,
intermediateCapacity: Int
) async throws where Writer: CallerAsyncWriter & ~Copyable & ~Escapable, Writer.WriteElement == ReadElement
) async throws
where Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
}
```
These helpers eliminate the boilerplate of manually looping, threading an
end-of-stream signal, and shuttling buffers between the two sides. Defining
`pipe` on the reader matches the precedent that the operation hangs off the
consumed source rather than the long-lived destination.
These helpers eliminate the boilerplate of manually looping, threading the
end signal, and shuttling buffers between the two sides. Defining `pipe` on
the reader matches the precedent that the operation hangs off the consumed
source rather than the long-lived destination.
Like the iteration and collection helpers above, these are intentionally
excluded from the initial proposal so that their error handling semantics can
mature through real-world use before stabilization.
excluded from the initial proposal so that their error-handling and
fused-close semantics can mature through real-world use before stabilization.
### Owned buffer transfer protocols
@@ -726,6 +959,42 @@ necessary. With clear signposting of which protocols are "preferred," the
developer experience remains approachable for the majority while not tying the
hands of those with specialized requirements.
### Omitting the `FinalElement` associated type
An earlier shape of this proposal had no `FinalElement` concept at all: the
read side signaled end-of-stream by returning an empty buffer; the write side
signaled it implicitly by deinitializing or consuming the writer. That design
is simpler to teach but fails on two fronts.
**It cannot express transports that deliver structured data with the close.**
Many real protocols attach a payload to the end-of-stream signal:
* **HTTP** sends trailing fields after the last DATA frame, these are arbitrary
header-like key/value pairs (checksums, signed digests, gRPC status) that
are only available once the body has been transmitted. Without
`FinalElement`, an HTTP body reader has no way to surface the trailers to
its caller alongside the last chunk; the application would need a separate
out-of-band channel.
* **gRPC** carries the call's terminal status (OK / error code + message) in
the trailers of every server-streaming response. The body protocol *must*
be able to deliver that status to the caller.
These are not exotic edge cases, they are two of the most common streaming
transports a Swift server library will need to support.
**It cannot fuse the last write with the close signal.** HTTP/2, HTTP/3, and
QUIC all let the sender attach an END_STREAM flag to the same frame that
carries the final body bytes. Without an explicit `finish` operation that
takes both the last chunk and the terminator, the writer would have to emit
two separate transport operations: one `write` for the final bytes, and a
later deinit-driven close. That doubles the syscall / framing cost on the hot
path of every request and forfeits the kernel-side coalescing these protocols
were specifically designed to enable.
Defaulting `FinalElement` to `Void` keeps the trivial case ergonomic, a plain
file or byte-stream conformer needn't think about the associated type, while
making the HTTP- and gRPC-shaped use cases expressible at all.
### Not using closures to provide temporary access to buffers
The callee-owned read and write APIs use closures that receive a span, which
@@ -20,7 +20,7 @@ import Testing
struct AsyncReaderCollectTests {
@Test
func collectAllElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try await reader.collect(upTo: 10) { span in
return Array(span)
@@ -31,7 +31,7 @@ struct AsyncReaderCollectTests {
@Test
func collectWithExactLimit() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try await reader.collect(upTo: 5) { span in
return Array(span)
@@ -42,7 +42,7 @@ struct AsyncReaderCollectTests {
@Test
func collectEmptyReader() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
let result = try await reader.collect(upTo: 10) { span in
return span.count
@@ -53,7 +53,7 @@ struct AsyncReaderCollectTests {
@Test
func collectProcessesAllElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
let result = try await reader.collect(upTo: 10) { span in
var sum = 0
@@ -67,16 +67,30 @@ struct AsyncReaderCollectTests {
}
@Test
func collectThrowsLeftOverElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
func collectVoidOverloadReturnsResultOnly() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
let expectedError = EitherError<EitherError<Never, AsyncReaderLeftOverElementsError>, Never>.first(
.second(AsyncReaderLeftOverElementsError())
)
await #expect(throws: expectedError) {
try await reader.collect(upTo: 1) { span in
let result: [Int] = try await reader.collect(upTo: 10) { span in
return Array(span)
}
#expect(result == [1, 2, 3])
}
@Test
func collectThrowsLeftOverElements() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
do {
_ = try await reader.collect(upTo: 1) { (span) -> Int in
return span.count
}
Issue.record("Expected error")
} catch {
let expected = EitherError<EitherError<Never, AsyncReaderLeftOverElementsError>, Never>.first(
.second(AsyncReaderLeftOverElementsError())
)
#expect(error == expected)
}
}
}
@@ -53,7 +53,8 @@ struct AsyncReaderforEachBufferTests {
callCount += 1
}
#expect(callCount == 0)
// The reader still emits a terminal call (with an empty buffer + finalElement).
#expect(callCount == 1)
}
@Test
@@ -65,7 +66,7 @@ struct AsyncReaderforEachBufferTests {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
do {
try await reader.forEachBuffer { (_) throws(TestError) -> Void in
_ = try await reader.forEachBuffer { (_) throws(TestError) -> Void in
throw TestError.failed
}
Issue.record("Expected error to be thrown")
@@ -84,7 +85,7 @@ struct AsyncReaderforEachBufferTests {
var count = 0
do {
try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
_ = try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
count += buffer.count
}
} catch {
@@ -99,7 +100,7 @@ struct AsyncReaderforEachBufferTests {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var results: [Int] = []
await reader.forEachBuffer { buffer in
_ = await reader.forEachBuffer { buffer in
await Task.yield()
for i in buffer.indices {
results.append(buffer[i])
@@ -18,136 +18,69 @@ import Testing
@Suite
struct AsyncReaderPipeTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoCopiesAllElements() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
)
var writer = UniqueArrayCallerAsyncWriter()
let writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(into: &writer)
#expect(writer.storage.count == 5)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
#expect(writer.storage[4] == 5)
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoWithEmptyReader() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray<Int>()
)
var writer = UniqueArrayCallerAsyncWriter()
let writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(into: &writer)
#expect(writer.storage.count == 0)
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoPreservesElementOrder() async throws {
let elements = Array(1...50)
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: elements.count, copying: elements)
)
var writer = UniqueArrayCallerAsyncWriter(capacity: elements.count)
let writer = UniqueArrayCallerAsyncWriter(capacity: elements.count)
try await reader.pipe(into: &writer)
#expect(writer.storage.count == elements.count)
for i in 0..<elements.count {
#expect(writer.storage[i] == elements[i])
}
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writerIntoRemainsUsableAfterPipe() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: 3, copying: [1, 2, 3])
)
var writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(into: &writer)
var more = UniqueArray(capacity: 1, copying: [99])
await writer.write(buffer: &more)
#expect(writer.storage.count == 4)
#expect(writer.storage[3] == 99)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeCopyingIntoCopiesAllElements() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
)
var writer = UniqueArrayAsyncWriter()
let writer = UniqueArrayAsyncWriter()
try await reader.pipe(copyingInto: &writer)
#expect(writer.storage.count == 5)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
#expect(writer.storage[4] == 5)
try await reader.pipe(copyingInto: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeCopyingIntoWithEmptyReader() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray<Int>()
)
var writer = UniqueArrayAsyncWriter()
let writer = UniqueArrayAsyncWriter()
try await reader.pipe(copyingInto: &writer)
#expect(writer.storage.count == 0)
try await reader.pipe(copyingInto: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeCopyingIntoChunksReaderBufferAcrossMultipleWrites() async throws {
// Reader hands out a single 200-element buffer. The writer hands out 64-element
// buffers, so the reader buffer must be drained across multiple writer.write calls.
func pipeCopyingIntoChunksTerminalChunkAcrossMultipleWrites() async throws {
// The reader's terminal chunk is 200 elements; the writer hands out
// 64-element buffers. Verify pipe runs without dropping bytes — the
// payload-bearing version of this scenario in FinalElementPipeTests
// checks the actual contents delivered.
let elements = Array(1...200)
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: elements.count, copying: elements)
)
var writer = UniqueArrayAsyncWriter(capacity: 256)
let writer = UniqueArrayAsyncWriter(capacity: 256)
try await reader.pipe(copyingInto: &writer)
#expect(writer.storage.count == elements.count)
for i in 0..<elements.count {
#expect(writer.storage[i] == elements[i])
}
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writerCopyingIntoRemainsUsableAfterPipe() async throws {
let reader = UniqueArrayAsyncReader(
storage: UniqueArray(capacity: 3, copying: [1, 2, 3])
)
var writer = UniqueArrayAsyncWriter()
try await reader.pipe(copyingInto: &writer)
try! await writer.write { buffer in
buffer.append(99)
}
#expect(writer.storage.count == 4)
#expect(writer.storage[3] == 99)
try await reader.pipe(copyingInto: writer)
}
}
#endif
@@ -21,7 +21,9 @@ struct AsyncReaderTests {
func read() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try! await reader.read { buffer in
var observedFinal = false
let result: UniqueArray<Int> = try! await reader.read { (buffer, finalElement) in
observedFinal = finalElement != nil
return buffer.clone()
}
@@ -31,25 +33,21 @@ struct AsyncReaderTests {
#expect(result[2] == 3)
#expect(result[3] == 4)
#expect(result[4] == 5)
#expect(observedFinal)
}
@Test
func readEmptyAtEnd() async {
func readDeliversTerminator() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
// Read all data
let first = try! await reader.read { buffer in
var observedFinal = false
let count: Int = try! await reader.read { (buffer, finalElement) in
observedFinal = finalElement != nil
return buffer.count
}
#expect(first == 3)
// Next read should return empty span
let second = try! await reader.read { buffer in
return buffer.count
}
#expect(second == 0)
#expect(count == 3)
#expect(observedFinal)
}
}
#endif
@@ -94,5 +94,17 @@ struct AsyncWriterTests {
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
}
@Test
func finishVoidConvenience() async {
let writer = UniqueArrayAsyncWriter()
await writer.finish()
}
@Test
func finishDeliversFinalElement() async {
let writer = UniqueArrayAsyncWriter()
await writer.finish(finalElement: ())
}
}
#endif
@@ -18,138 +18,65 @@ import Testing
@Suite
struct CallerAsyncReaderPipeTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoCopiesAllElements() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
)
var writer = UniqueArrayAsyncWriter()
let writer = UniqueArrayAsyncWriter()
try await reader.pipe(into: &writer)
#expect(writer.storage.count == 5)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
#expect(writer.storage[4] == 5)
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoWithEmptyReader() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray<Int>()
)
var writer = UniqueArrayAsyncWriter()
let writer = UniqueArrayAsyncWriter()
try await reader.pipe(into: &writer)
#expect(writer.storage.count == 0)
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeIntoLoopsAcrossMultipleBuffers() async throws {
// The writer hands out 64-element buffers. Use 200 elements to force the
// implementation to call write multiple times.
let elements = Array(1...200)
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: elements.count, copying: elements)
)
var writer = UniqueArrayAsyncWriter(capacity: 256)
let writer = UniqueArrayAsyncWriter(capacity: 256)
try await reader.pipe(into: &writer)
#expect(writer.storage.count == elements.count)
for i in 0..<elements.count {
#expect(writer.storage[i] == elements[i])
}
try await reader.pipe(into: writer)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writerIntoRemainsUsableAfterPipe() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 3, copying: [1, 2, 3])
)
var writer = UniqueArrayAsyncWriter()
try await reader.pipe(into: &writer)
try! await writer.write { buffer in
buffer.append(99)
}
#expect(writer.storage.count == 4)
#expect(writer.storage[3] == 99)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeBufferingIntoCopiesAllElements() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
)
var writer = UniqueArrayCallerAsyncWriter()
let writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(bufferingInto: &writer, intermediateCapacity: 16)
#expect(writer.storage.count == 5)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
#expect(writer.storage[4] == 5)
try await reader.pipe(bufferingInto: writer, intermediateCapacity: 16)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeBufferingIntoWithEmptyReader() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray<Int>()
)
var writer = UniqueArrayCallerAsyncWriter()
let writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(bufferingInto: &writer, intermediateCapacity: 16)
#expect(writer.storage.count == 0)
try await reader.pipe(bufferingInto: writer, intermediateCapacity: 16)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func pipeBufferingIntoReusesIntermediateBufferAcrossMultipleIterations() async throws {
// The intermediate buffer holds 16 elements. With 100 source elements, the loop
// must iterate at least 7 times, reusing the same buffer.
let elements = Array(1...100)
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: elements.count, copying: elements)
)
var writer = UniqueArrayCallerAsyncWriter(capacity: elements.count)
let writer = UniqueArrayCallerAsyncWriter(capacity: elements.count)
try await reader.pipe(bufferingInto: &writer, intermediateCapacity: 16)
#expect(writer.storage.count == elements.count)
for i in 0..<elements.count {
#expect(writer.storage[i] == elements[i])
}
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writerBufferingIntoRemainsUsableAfterPipe() async throws {
let reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 3, copying: [1, 2, 3])
)
var writer = UniqueArrayCallerAsyncWriter()
try await reader.pipe(bufferingInto: &writer, intermediateCapacity: 8)
var more = UniqueArray(capacity: 1, copying: [99])
await writer.write(buffer: &more)
#expect(writer.storage.count == 4)
#expect(writer.storage[3] == 99)
try await reader.pipe(bufferingInto: writer, intermediateCapacity: 16)
}
}
#endif
@@ -80,10 +80,6 @@ struct CallerAsyncReaderTests {
#expect(buffer2[0] == 4)
#expect(buffer2[1] == 5)
#expect(buffer2[2] == 6)
var buffer3 = UniqueArray<Int>(minimumCapacity: 3)
await reader.read(into: &buffer3)
#expect(buffer3.count == 0)
}
}
#endif
@@ -18,16 +18,20 @@ struct UniqueArrayAsyncReader: ~Copyable, AsyncReader {
typealias ReadElement = Int
typealias Buffer = UniqueArray<Int>
typealias ReadFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didEmitFinal: Bool = false
mutating func read<Return: ~Copyable, Failure: Error>(
body: (inout UniqueArray<Int>) async throws(Failure) -> Return
body: (inout UniqueArray<Int>, Void?) async throws(Failure) -> Return
) async throws(EitherError<Never, Failure>) -> Return {
precondition(!self.didEmitFinal, "read called after end-of-stream")
self.didEmitFinal = true
do {
var uniqueArray = self.storage.clone()
self.storage = .init()
return try await body(&uniqueArray)
return try await body(&uniqueArray, .some(()))
} catch {
throw .second(error)
}
@@ -18,8 +18,10 @@ struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
typealias WriteElement = Int
typealias Buffer = UniqueArray<Int>
typealias WriteFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didFinish: Bool = false
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
@@ -37,5 +39,11 @@ struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
throw .second(error)
}
}
consuming func finish(
finalElement: consuming Void
) async throws(Never) {
self.didFinish = true
}
}
#endif
@@ -17,19 +17,26 @@ import ContainersPreview
struct UniqueArrayCallerAsyncReader: ~Copyable, CallerAsyncReader {
typealias ReadElement = Int
typealias ReadFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var position: Int = 0
var didEmitFinal: Bool = false
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable {
guard position < storage.count else { return }
) async throws(ReadFailure) -> Void? where Buffer.Element: ~Copyable {
precondition(!self.didEmitFinal, "read called after end-of-stream")
let count = min(buffer.freeCapacity, storage.count - position)
for i in 0..<count {
buffer.append(storage[position + i])
}
position += count
if position >= storage.count {
self.didEmitFinal = true
return .some(())
}
return nil
}
}
#endif
@@ -19,8 +19,10 @@ struct WriterCapacityError: Error {}
struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
typealias WriteElement = Int
typealias WriteFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didFinish: Bool = false
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
@@ -35,5 +37,17 @@ struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
self.storage.append(element)
}
}
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming Void
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
self.storage.reserveCapacity(buffer.count)
var consumer = buffer.consumeAll()
while let element = consumer.next() {
self.storage.append(element)
}
self.didFinish = true
}
}
#endif