mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d0b4a06d0f | ||
|
|
6a92272e13 | ||
|
|
6783e0f2d2 | ||
|
|
d14a83b31f | ||
|
|
0a5f92d159 | ||
|
|
be2467e0c0 |
No files matched your search
+58
-2
@@ -35,7 +35,22 @@ let availabilityMacros: [SwiftSetting] = [
|
||||
let package = Package(
|
||||
name: "swift-async-algorithms",
|
||||
products: [
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"])
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]),
|
||||
.library(name: "AsyncStreaming", targets: ["AsyncStreaming"]),
|
||||
],
|
||||
traits: [
|
||||
.default(
|
||||
enabledTraits: [
|
||||
// "UnstableAsyncStreaming"
|
||||
]
|
||||
),
|
||||
.trait(
|
||||
name: "UnstableAsyncStreaming",
|
||||
description: """
|
||||
Enables source unstable async streaming components in the _AsyncStreaming
|
||||
module. Do not rely on this module in API stable packages.
|
||||
"""
|
||||
),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
@@ -48,6 +63,24 @@ let package = Package(
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncStreaming",
|
||||
dependencies: [
|
||||
.product(name: "BasicContainers", package: "swift-collections"),
|
||||
.product(name: "ContainersPreview", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
|
||||
.enableExperimentalFeature("LifetimeDependence"),
|
||||
.enableExperimentalFeature("Lifetimes"),
|
||||
.enableUpcomingFeature("LifetimeDependence"),
|
||||
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
|
||||
.enableUpcomingFeature("InferIsolatedConformances"),
|
||||
.enableUpcomingFeature("ExistentialAny"),
|
||||
.enableUpcomingFeature("MemberImportVisibility"),
|
||||
.enableUpcomingFeature("InternalImportsByDefault"),
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
|
||||
@@ -104,12 +137,35 @@ let package = Package(
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "AsyncStreamingTests",
|
||||
dependencies: [
|
||||
"AsyncStreaming",
|
||||
.product(name: "BasicContainers", package: "swift-collections"),
|
||||
.product(name: "ContainersPreview", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
|
||||
.enableExperimentalFeature("LifetimeDependence"),
|
||||
.enableExperimentalFeature("Lifetimes"),
|
||||
.enableUpcomingFeature("LifetimeDependence"),
|
||||
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
|
||||
.enableUpcomingFeature("InferIsolatedConformances"),
|
||||
.enableUpcomingFeature("ExistentialAny"),
|
||||
.enableUpcomingFeature("MemberImportVisibility"),
|
||||
.enableUpcomingFeature("InternalImportsByDefault"),
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
if Context.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
|
||||
package.dependencies += [
|
||||
.package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0")
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-collections.git",
|
||||
from: "1.5.0",
|
||||
traits: [.trait(name: "UnstableContainersPreview", condition: .when(traits: ["UnstableAsyncStreaming"]))]
|
||||
)
|
||||
]
|
||||
} else {
|
||||
package.dependencies += [
|
||||
|
||||
+128
-66
@@ -321,11 +321,13 @@ extension MultiProducerSingleConsumerAsyncChannel {
|
||||
return $0.enqueueProducer(callbackToken: callbackToken, onProduceMore: onProduceMore)
|
||||
}
|
||||
|
||||
switch action {
|
||||
switch consume action {
|
||||
case .resumeProducer(let onProduceMore):
|
||||
let onProduceMore = onProduceMore.take()
|
||||
onProduceMore(Result<Void, Error>.success(()))
|
||||
|
||||
case .resumeProducerWithError(let onProduceMore, let error):
|
||||
let onProduceMore = onProduceMore.take()
|
||||
onProduceMore(Result<Void, Error>.failure(error))
|
||||
|
||||
case .none:
|
||||
@@ -396,7 +398,7 @@ extension MultiProducerSingleConsumerAsyncChannel {
|
||||
$0.next()
|
||||
}
|
||||
|
||||
switch action {
|
||||
switch consume action {
|
||||
case .returnElement(let element):
|
||||
return element.take()
|
||||
|
||||
@@ -438,17 +440,15 @@ extension MultiProducerSingleConsumerAsyncChannel {
|
||||
$0.suspendNext(continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeConsumerWithElement(let continuation, let element):
|
||||
continuation.resume(returning: element.take())
|
||||
switch consume action {
|
||||
case .resumeConsumerWithElement(let payload):
|
||||
let element = payload.element.take()
|
||||
payload.continuation.resume(returning: element)
|
||||
|
||||
case .resumeConsumerWithElementAndProducers(
|
||||
let continuation,
|
||||
let element,
|
||||
let producerContinuations
|
||||
):
|
||||
continuation.resume(returning: element.take())
|
||||
for producerContinuation in producerContinuations {
|
||||
case .resumeConsumerWithElementAndProducers(let payload):
|
||||
let element = payload.element.take()
|
||||
payload.continuation.resume(returning: element)
|
||||
for producerContinuation in payload.producerContinuations {
|
||||
switch producerContinuation {
|
||||
case .closure(let onProduceMore):
|
||||
onProduceMore(.success(()))
|
||||
@@ -457,19 +457,13 @@ extension MultiProducerSingleConsumerAsyncChannel {
|
||||
}
|
||||
}
|
||||
|
||||
case .resumeConsumerWithFailureAndCallOnTerminations(
|
||||
let continuation,
|
||||
let failure,
|
||||
let onTerminations
|
||||
):
|
||||
switch failure {
|
||||
case .some(let error):
|
||||
continuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
continuation.resume(returning: nil)
|
||||
case .resumeConsumerWithFailureAndCallOnTerminations(let payload):
|
||||
if let error = payload.failure {
|
||||
payload.continuation.resume(throwing: error)
|
||||
} else {
|
||||
payload.continuation.resume(returning: nil)
|
||||
}
|
||||
onTerminations.forEach { $0.1() }
|
||||
payload.onTerminations.forEach { $0.1() }
|
||||
|
||||
case .resumeConsumerWithNil(let continuation):
|
||||
continuation.resume(returning: nil)
|
||||
@@ -543,7 +537,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `sourceDeinitialized()`.
|
||||
@usableFromInline
|
||||
enum SetOnTerminationCallback {
|
||||
enum SetOnTerminationCallback: Sendable {
|
||||
/// Indicates that `onTermination` should be called.
|
||||
case callOnTermination(
|
||||
@Sendable () -> Void
|
||||
@@ -615,7 +609,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `sourceDeinitialized()`.
|
||||
@usableFromInline
|
||||
enum SourceDeinitialized {
|
||||
enum SourceDeinitialized: Sendable {
|
||||
/// Indicates that the consumer should be resumed with the failure, the producers
|
||||
/// should be resumed with an error and `onTermination`s should be called.
|
||||
case resumeConsumerAndCallOnTerminations(
|
||||
@@ -710,7 +704,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `sequenceDeinitialized()`.
|
||||
@usableFromInline
|
||||
enum ChannelOrSequenceDeinitializedAction {
|
||||
enum ChannelOrSequenceDeinitializedAction: Sendable {
|
||||
/// Indicates that `onTermination`s should be called.
|
||||
case callOnTerminations(_TinyArray<(UInt64, @Sendable () -> Void)>)
|
||||
/// Indicates that all producers should be failed and `onTermination`s should be called.
|
||||
@@ -875,7 +869,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `iteratorDeinitialized()`.
|
||||
@usableFromInline
|
||||
enum IteratorDeinitializedAction {
|
||||
enum IteratorDeinitializedAction: Sendable {
|
||||
/// Indicates that `onTermination`s should be called.
|
||||
case callOnTerminations(_TinyArray<(UInt64, @Sendable () -> Void)>)
|
||||
/// Indicates that all producers should be failed and `onTermination`s should be called.
|
||||
@@ -1047,11 +1041,11 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `enqueueProducer()`.
|
||||
@usableFromInline
|
||||
enum EnqueueProducerAction {
|
||||
enum EnqueueProducerAction: ~Copyable, Sendable {
|
||||
/// Indicates that the producer should be notified to produce more.
|
||||
case resumeProducer((Result<Void, Error>) -> Void)
|
||||
case resumeProducer(Disconnected<(Result<Void, Error>) -> Void>)
|
||||
/// Indicates that the producer should be notified about an error.
|
||||
case resumeProducerWithError((Result<Void, Error>) -> Void, Error)
|
||||
case resumeProducerWithError(Disconnected<(Result<Void, Error>) -> Void>, Error)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
@@ -1066,12 +1060,12 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
channeling.cancelledAsyncProducers.remove(at: index)
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .resumeProducerWithError(onProduceMore, CancellationError())
|
||||
return .resumeProducerWithError(.init(value: onProduceMore), CancellationError())
|
||||
} else if channeling.hasOutstandingDemand {
|
||||
// We hit an edge case here where we wrote but the consuming thread got interleaved
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .resumeProducer(onProduceMore)
|
||||
return .resumeProducer(.init(value: onProduceMore))
|
||||
} else {
|
||||
channeling.suspendedProducers.append((callbackToken, .closure(onProduceMore)))
|
||||
self = .init(state: .channeling(channeling))
|
||||
@@ -1084,20 +1078,26 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
// It can happen that the source got finished or the consumption fully finishes.
|
||||
self = .init(state: .sourceFinished(sourceFinished))
|
||||
|
||||
return .resumeProducerWithError(onProduceMore, MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError())
|
||||
return .resumeProducerWithError(
|
||||
.init(value: onProduceMore),
|
||||
MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError()
|
||||
)
|
||||
|
||||
case .finished(let finished):
|
||||
// Since we are unlocking between sending elements and suspending the send
|
||||
// It can happen that the source got finished or the consumption fully finishes.
|
||||
self = .init(state: .finished(finished))
|
||||
|
||||
return .resumeProducerWithError(onProduceMore, MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError())
|
||||
return .resumeProducerWithError(
|
||||
.init(value: onProduceMore),
|
||||
MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError()
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `enqueueContinuation()`.
|
||||
@usableFromInline
|
||||
enum EnqueueContinuationAction {
|
||||
enum EnqueueContinuationAction: Sendable {
|
||||
/// Indicates that the producer should be notified to produce more.
|
||||
case resumeProducer(UnsafeContinuation<Void, any Error>)
|
||||
/// Indicates that the producer should be notified about an error.
|
||||
@@ -1147,7 +1147,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `cancelProducer()`.
|
||||
@usableFromInline
|
||||
enum CancelProducerAction {
|
||||
enum CancelProducerAction: Sendable {
|
||||
/// Indicates that the producer should be notified about cancellation.
|
||||
case resumeProducerWithCancellationError(_MultiProducerSingleConsumerSuspendedProducer)
|
||||
}
|
||||
@@ -1190,7 +1190,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `finish()`.
|
||||
@usableFromInline
|
||||
enum FinishAction {
|
||||
enum FinishAction: Sendable {
|
||||
/// Indicates that `onTermination`s should be called.
|
||||
case callOnTerminations(_TinyArray<(UInt64, @Sendable () -> Void)>)
|
||||
/// Indicates that the consumer should be resumed with the failure, the producers
|
||||
@@ -1266,12 +1266,12 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `next()`.
|
||||
@usableFromInline
|
||||
enum NextAction {
|
||||
enum NextAction: ~Copyable, Sendable {
|
||||
/// Indicates that the element should be returned to the caller.
|
||||
case returnElement(SendableConsumeOnceBox<Element>)
|
||||
case returnElement(Disconnected<Element>)
|
||||
/// Indicates that the element should be returned to the caller and that all producers should be called.
|
||||
case returnElementAndResumeProducers(
|
||||
SendableConsumeOnceBox<Element>,
|
||||
Disconnected<Element>,
|
||||
_TinyArray<_MultiProducerSingleConsumerSuspendedProducer>
|
||||
)
|
||||
/// Indicates that the `Failure` should be returned to the caller and that `onTermination`s should be called.
|
||||
@@ -1310,14 +1310,14 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
// We don't have any new demand, so we can just return the element.
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .returnElement(element)
|
||||
return .returnElement(Disconnected(value: element.take()))
|
||||
}
|
||||
// There is demand and we have to resume our producers
|
||||
let producers = _TinyArray(channeling.suspendedProducers.lazy.map { $0.1 })
|
||||
channeling.suspendedProducers.removeAll(keepingCapacity: true)
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .returnElementAndResumeProducers(element, producers)
|
||||
return .returnElementAndResumeProducers(Disconnected(value: element.take()), producers)
|
||||
|
||||
case .sourceFinished(var sourceFinished):
|
||||
// Check if we have an element left in the buffer and return it
|
||||
@@ -1340,7 +1340,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
}
|
||||
self = .init(state: .sourceFinished(sourceFinished))
|
||||
|
||||
return .returnElement(element)
|
||||
return .returnElement(Disconnected(value: element.take()))
|
||||
|
||||
case .finished(let finished):
|
||||
self = .init(state: .finished(finished))
|
||||
@@ -1351,21 +1351,72 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `suspendNext()`.
|
||||
@usableFromInline
|
||||
enum SuspendNextAction: ~Copyable {
|
||||
enum SuspendNextAction: ~Copyable, Sendable {
|
||||
/// Payload for `.resumeConsumerWithElement`.
|
||||
///
|
||||
/// - Note: Wrapped in a struct to work around a SILGen crash when
|
||||
/// destructively pattern-matching an enum case with multiple payloads
|
||||
/// that include a `~Copyable` generic wrapper type (`Disconnected`).
|
||||
@usableFromInline
|
||||
struct ResumeElement: ~Copyable, Sendable {
|
||||
@usableFromInline let continuation: UnsafeContinuation<Element?, Error>
|
||||
@usableFromInline var element: Disconnected<Element>
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
continuation: UnsafeContinuation<Element?, Error>,
|
||||
element: consuming Disconnected<Element>
|
||||
) {
|
||||
self.continuation = continuation
|
||||
self.element = element
|
||||
}
|
||||
}
|
||||
/// Payload for `.resumeConsumerWithElementAndProducers`.
|
||||
///
|
||||
/// - Note: See `ResumeElement` for the reason behind this wrapper.
|
||||
@usableFromInline
|
||||
struct ResumeElementAndProducers: ~Copyable, Sendable {
|
||||
@usableFromInline let continuation: UnsafeContinuation<Element?, Error>
|
||||
@usableFromInline var element: Disconnected<Element>
|
||||
@usableFromInline let producerContinuations: _TinyArray<_MultiProducerSingleConsumerSuspendedProducer>
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
continuation: UnsafeContinuation<Element?, Error>,
|
||||
element: consuming Disconnected<Element>,
|
||||
producerContinuations: _TinyArray<_MultiProducerSingleConsumerSuspendedProducer>
|
||||
) {
|
||||
self.continuation = continuation
|
||||
self.element = element
|
||||
self.producerContinuations = producerContinuations
|
||||
}
|
||||
}
|
||||
/// Payload for `.resumeConsumerWithFailureAndCallOnTerminations`.
|
||||
///
|
||||
/// - Note: See `ResumeElement` for the reason behind this wrapper.
|
||||
@usableFromInline
|
||||
struct ResumeFailure: ~Copyable, Sendable {
|
||||
@usableFromInline let continuation: UnsafeContinuation<Element?, Error>
|
||||
@usableFromInline let failure: Failure?
|
||||
@usableFromInline let onTerminations: _TinyArray<(UInt64, @Sendable () -> Void)>
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
continuation: UnsafeContinuation<Element?, Error>,
|
||||
failure: Failure?,
|
||||
onTerminations: _TinyArray<(UInt64, @Sendable () -> Void)>
|
||||
) {
|
||||
self.continuation = continuation
|
||||
self.failure = failure
|
||||
self.onTerminations = onTerminations
|
||||
}
|
||||
}
|
||||
/// Indicates that the consumer should be resumed.
|
||||
case resumeConsumerWithElement(UnsafeContinuation<Element?, Error>, SendableConsumeOnceBox<Element>)
|
||||
case resumeConsumerWithElement(ResumeElement)
|
||||
/// Indicates that the consumer and all producers should be resumed.
|
||||
case resumeConsumerWithElementAndProducers(
|
||||
UnsafeContinuation<Element?, Error>,
|
||||
SendableConsumeOnceBox<Element>,
|
||||
_TinyArray<_MultiProducerSingleConsumerSuspendedProducer>
|
||||
)
|
||||
case resumeConsumerWithElementAndProducers(ResumeElementAndProducers)
|
||||
/// Indicates that the consumer should be resumed with the failure and that `onTermination`s should be called.
|
||||
case resumeConsumerWithFailureAndCallOnTerminations(
|
||||
UnsafeContinuation<Element?, Error>,
|
||||
Failure?,
|
||||
_TinyArray<(UInt64, @Sendable () -> Void)>
|
||||
)
|
||||
case resumeConsumerWithFailureAndCallOnTerminations(ResumeFailure)
|
||||
/// Indicates that the consumer should be resumed with `nil`.
|
||||
case resumeConsumerWithNil(UnsafeContinuation<Element?, Error>)
|
||||
}
|
||||
@@ -1396,7 +1447,9 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
// We don't have any new demand, so we can just return the element.
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .resumeConsumerWithElement(continuation, element)
|
||||
return .resumeConsumerWithElement(
|
||||
.init(continuation: continuation, element: Disconnected(value: element.take()))
|
||||
)
|
||||
}
|
||||
// There is demand and we have to resume our producers
|
||||
let producers = _TinyArray(channeling.suspendedProducers.lazy.map { $0.1 })
|
||||
@@ -1404,9 +1457,11 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
self = .init(state: .channeling(channeling))
|
||||
|
||||
return .resumeConsumerWithElementAndProducers(
|
||||
continuation,
|
||||
element,
|
||||
producers
|
||||
.init(
|
||||
continuation: continuation,
|
||||
element: Disconnected(value: element.take()),
|
||||
producerContinuations: producers
|
||||
)
|
||||
)
|
||||
|
||||
case .sourceFinished(var sourceFinished):
|
||||
@@ -1424,14 +1479,18 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
)
|
||||
|
||||
return .resumeConsumerWithFailureAndCallOnTerminations(
|
||||
continuation,
|
||||
sourceFinished.failure,
|
||||
sourceFinished.onTerminations
|
||||
.init(
|
||||
continuation: continuation,
|
||||
failure: sourceFinished.failure,
|
||||
onTerminations: sourceFinished.onTerminations
|
||||
)
|
||||
)
|
||||
}
|
||||
self = .init(state: .sourceFinished(sourceFinished))
|
||||
|
||||
return .resumeConsumerWithElement(continuation, element)
|
||||
return .resumeConsumerWithElement(
|
||||
.init(continuation: continuation, element: Disconnected(value: element.take()))
|
||||
)
|
||||
|
||||
case .finished(let finished):
|
||||
self = .init(state: .finished(finished))
|
||||
@@ -1442,7 +1501,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
|
||||
|
||||
/// Actions returned by `cancelNext()`.
|
||||
@usableFromInline
|
||||
enum CancelNextAction {
|
||||
enum CancelNextAction: Sendable {
|
||||
/// Indicates that the continuation should be resumed with nil, the producers should be finished and call onTerminations.
|
||||
case resumeConsumerWithNilAndCallOnTerminations(
|
||||
UnsafeContinuation<Element?, Error>,
|
||||
@@ -1715,11 +1774,14 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage._StateMachine {
|
||||
|
||||
@available(AsyncAlgorithms 1.1, *)
|
||||
@usableFromInline
|
||||
enum _MultiProducerSingleConsumerSuspendedProducer {
|
||||
// TODO: This type is unchecked Sendable since the closure is actually sending
|
||||
// We can't yet use Disconnected here since we need to have a UniqueDeque to store them
|
||||
enum _MultiProducerSingleConsumerSuspendedProducer: @unchecked Sendable {
|
||||
case closure((Result<Void, Error>) -> Void)
|
||||
case continuation(UnsafeContinuation<Void, Error>)
|
||||
}
|
||||
|
||||
// TODO: This should be replaced with Disconnected once we have a UniqueDeque
|
||||
@usableFromInline
|
||||
struct SendableConsumeOnceBox<Wrapped> {
|
||||
@usableFromInline
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
import BasicContainers
|
||||
|
||||
/// An error indicating that the reader produced more elements than the specified collection limit.
|
||||
///
|
||||
/// This error occurs when calling ``AsyncReader/collect(upTo:body:)`` and the reader's buffer
|
||||
/// contains more elements than the allowed limit.
|
||||
public struct AsyncReaderLeftOverElementsError: Error, Hashable {
|
||||
public init() {}
|
||||
}
|
||||
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
|
||||
/// 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.
|
||||
/// Once collection completes, it passes the accumulated elements to the provided body
|
||||
/// closure as an `InputSpan` for processing.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - limit: The maximum number of elements to collect. This prevents unbounded memory
|
||||
/// growth when reading from potentially infinite streams.
|
||||
/// - 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.
|
||||
///
|
||||
/// - Throws: An `EitherError` wrapping either a read failure (which itself may be an
|
||||
/// ``AsyncReaderLeftOverElementsError`` if the reader produces more elements than the limit),
|
||||
/// or a `Failure` from the body closure.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var reader: SomeAsyncReader = ...
|
||||
///
|
||||
/// let processedData = try await reader.collect(upTo: 1000) { span in
|
||||
/// // Process all collected elements
|
||||
/// }
|
||||
/// ```
|
||||
public mutating func collect<Result, Failure: Error>(
|
||||
upTo limit: Int,
|
||||
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
|
||||
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result {
|
||||
// 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
|
||||
do {
|
||||
while shouldContinue {
|
||||
try await self.read { (buffer: inout Buffer) throws(AsyncReaderLeftOverElementsError) -> Void in
|
||||
guard buffer.count > 0 else {
|
||||
shouldContinue = false
|
||||
return
|
||||
}
|
||||
if limit - collectedBuffer.count < buffer.count {
|
||||
throw AsyncReaderLeftOverElementsError()
|
||||
}
|
||||
var consumer = buffer.consumeAll()
|
||||
while let element = consumer.next() {
|
||||
collectedBuffer.append(element)
|
||||
}
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
do {
|
||||
var consumer = collectedBuffer.consumeAll()
|
||||
return try await body(consumer.drainNext())
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,97 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
// swift-format-ignore: AmbiguousTrailingClosureOverload
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
|
||||
/// Iterates over all chunks from the 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.
|
||||
///
|
||||
/// - 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.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileReader: FileAsyncReader = ...
|
||||
///
|
||||
/// try await fileReader.forEachBuffer { buffer in
|
||||
/// print("Processing \(buffer.count) elements")
|
||||
/// }
|
||||
/// ```
|
||||
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
|
||||
}
|
||||
|
||||
try await body(&next)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// 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
|
||||
/// print("Processing \(buffer.count) elements")
|
||||
/// }
|
||||
/// ```
|
||||
@inlinable
|
||||
public consuming func forEachBuffer(
|
||||
body: (inout Buffer) async -> Void
|
||||
) async where ReadFailure == Never {
|
||||
var shouldContinue = true
|
||||
while shouldContinue {
|
||||
do {
|
||||
try await self.read { (next) -> Void in
|
||||
guard next.count > 0 else {
|
||||
shouldContinue = false
|
||||
return
|
||||
}
|
||||
|
||||
await body(&next)
|
||||
}
|
||||
} catch {
|
||||
fatalError()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,58 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 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.
|
||||
@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 container type the reader uses to pass elements to the caller.
|
||||
associatedtype Buffer: RangeReplaceableContainer<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 elements from the source into a buffer,
|
||||
/// then passes the buffer to `body` for processing. When the buffer is empty,
|
||||
/// the stream has ended.
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileReader: FileAsyncReader = ...
|
||||
///
|
||||
/// let result = try await fileReader.read { buffer in
|
||||
/// guard buffer.count > 0 else {
|
||||
/// return 0
|
||||
/// }
|
||||
/// return buffer.count
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - 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.
|
||||
/// - 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
|
||||
) async throws(EitherError<ReadFailure, Failure>) -> Return
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,61 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
/// 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.
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
public protocol AsyncWriter<WriteElement, WriteFailure>: ~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 error type that writing operations throw.
|
||||
associatedtype WriteFailure: Error
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// - 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
|
||||
/// var writer: SomeAsyncWriter = ...
|
||||
///
|
||||
/// try await writer.write { buffer in
|
||||
/// for item in items {
|
||||
/// buffer.append(item)
|
||||
/// }
|
||||
/// return buffer.count
|
||||
/// }
|
||||
/// ```
|
||||
mutating func write<Return: ~Copyable, Failure: Error>(
|
||||
_ body: (inout Buffer) async throws(Failure) -> Return
|
||||
) async throws(EitherError<WriteFailure, Failure>) -> Return
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,39 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 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.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
||||
public protocol CallerAsyncReader<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 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.
|
||||
///
|
||||
/// - Parameter buffer: The buffer to fill with read elements.
|
||||
/// - Throws: A `ReadFailure` from the underlying read operation.
|
||||
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
|
||||
into buffer: inout Buffer
|
||||
) async throws(ReadFailure) where Buffer.Element: ~Copyable
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,49 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
/// 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.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
||||
public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
|
||||
/// The type of elements this writer writes.
|
||||
associatedtype WriteElement: ~Copyable
|
||||
|
||||
/// The error type that writing operations throw.
|
||||
associatedtype WriteFailure: Error
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileWriter: FileAsyncWriter = ...
|
||||
/// var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
///
|
||||
/// try await fileWriter.write(buffer: &data)
|
||||
/// ```
|
||||
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,54 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2022 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)
|
||||
/// A type-safe wrapper around one of two distinct error types.
|
||||
///
|
||||
/// Use ``EitherError`` when an operation can fail with errors from two
|
||||
/// different sources, such as a read failure and a body closure failure.
|
||||
@frozen
|
||||
public enum EitherError<First: Error, Second: Error>: Error {
|
||||
/// An error of the first type.
|
||||
case first(First)
|
||||
|
||||
/// An error of the second type.
|
||||
case second(Second)
|
||||
|
||||
/// Throws the underlying error, unwrapping this ``EitherError``.
|
||||
///
|
||||
/// This method extracts and throws the contained error,
|
||||
/// whether it's the first or second type. Use this when you need to propagate
|
||||
/// the original error without the ``EitherError`` wrapper.
|
||||
///
|
||||
/// - Throws: The underlying error, either of type `First` or `Second`.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// do {
|
||||
/// let result = try await operation()
|
||||
/// } catch let eitherError as EitherError<NetworkError, ParseError> {
|
||||
/// try eitherError.unwrap()
|
||||
/// }
|
||||
/// ```
|
||||
public func unwrap() throws {
|
||||
switch self {
|
||||
case .first(let first):
|
||||
throw first
|
||||
case .second(let second):
|
||||
throw second
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension EitherError: Equatable where First: Equatable, Second: Equatable {}
|
||||
extension EitherError: Hashable where First: Hashable, Second: Hashable {}
|
||||
#endif
|
||||
@@ -0,0 +1,829 @@
|
||||
# Generalized asynchronous streaming
|
||||
|
||||
* Proposal: [SE-NNNN](NNNN-async-streaming.md)
|
||||
* Authors: [Franz Busch](https://github.com/FranzBusch), [Karoy
|
||||
Lorentey](https://github.com/lorentey), [David
|
||||
Smith](https://github.com/Catfish-Man)
|
||||
* Review Manager: TBD
|
||||
* Status: **Awaiting implementation**
|
||||
* Implementation: …
|
||||
* Review: ([pitch](https://forums.swift.org/...))
|
||||
|
||||
## Summary of changes
|
||||
|
||||
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`.
|
||||
|
||||
## Motivation
|
||||
|
||||
`AsyncSequence` (SE-0298) gave Swift a concurrency-compatible model for streams
|
||||
of values arriving over time. It has served us well but has a number of
|
||||
important limitations that become apparent when building high-performance,
|
||||
bidirectional I/O systems.
|
||||
|
||||
### Values arrive one at a time
|
||||
|
||||
When each value is computationally "large", the overhead of calling `next()` is
|
||||
negligible. But for simple types like bytes, that per-element overhead can dwarf
|
||||
the actual work. This forces library authors into tricky, not-fully-general
|
||||
workarounds with inline functions (as seen in `AsyncBufferedByteIterator`) or
|
||||
into giving up on the `AsyncSequence` abstraction entirely.
|
||||
|
||||
The standard solution is buffering: read or write many elements at once. But
|
||||
buffering introduces its own set of challenges — more on that below.
|
||||
|
||||
### Noncopyable types cannot be streamed
|
||||
|
||||
`AsyncSequence` was introduced before noncopyable types existed and requires its
|
||||
`Element` to be `Copyable`. Streaming types are conceptually about moving values
|
||||
from one place to another, and many important types such as move-only buffers
|
||||
are noncopyable by nature.
|
||||
|
||||
### The iterator pattern is a poor fit for asynchronous streams
|
||||
|
||||
`AsyncSequence` followed the design of its synchronous counterpart `Sequence` by
|
||||
using an iterator pattern. While iterators work well for synchronous
|
||||
collections, they are a poor fit for asynchronous streams for two reasons:
|
||||
|
||||
* **Most asynchronous sequences do not support multiple iterators.** Unlike an
|
||||
`Array`, which can be iterated multiple times independently, a network socket
|
||||
or file stream produces each value exactly once.
|
||||
* **Most asynchronous sequences are not replayable.** The iterator pattern
|
||||
suggests that calling `makeAsyncIterator()` again would restart iteration
|
||||
from the beginning, but this is almost never true for asynchronous sources.
|
||||
|
||||
### There is no protocol for the write side of a stream
|
||||
|
||||
During the design of APIs supporting bidirectional streaming — such as HTTP or
|
||||
gRPC — it became apparent that `AsyncSequence`'s pull-based model only works for
|
||||
one side. Trying to express both sides as an `AsyncSequence` forces the
|
||||
introduction of unstructured tasks, breaking structured concurrency guarantees:
|
||||
|
||||
```swift
|
||||
func bidirectionalStreaming(
|
||||
input: some AsyncSequence<UInt8, Never>
|
||||
) async throws -> some AsyncSequence<UInt8, Never> {
|
||||
// The output sequence can produce values before input is fully consumed.
|
||||
// This forces an unstructured task to continue iterating the input
|
||||
// after this method returns.
|
||||
Task {
|
||||
for await byte in input {
|
||||
// Send byte
|
||||
}
|
||||
}
|
||||
return SomeOutputSequence()
|
||||
}
|
||||
```
|
||||
|
||||
A dedicated write protocol eliminates this problem by giving the output side a
|
||||
push-based interface that can be driven within the same structured scope as the
|
||||
input side.
|
||||
|
||||
### Buffer management has no single optimal strategy
|
||||
|
||||
Given the limitations above, we need new streaming protocols. Addressing the
|
||||
per-element overhead requires buffering, but someone must be responsible for
|
||||
creating and managing each buffer. There are two fundamental choices:
|
||||
|
||||
* **The caller provides the buffer.** The stream fills (for reads) or drains
|
||||
(for writes) the caller's buffer.
|
||||
* **The callee provides the buffer.** The stream lends a filled buffer (for
|
||||
reads) or an empty buffer (for writes) to the caller via a scoped closure.
|
||||
|
||||
Each strategy is optimal in different situations, and neither can be eliminated
|
||||
without imposing unnecessary overhead on important use cases:
|
||||
|
||||
**Callee-owned read is optimal when data arrives from an external source.** When
|
||||
doing interprocess communication, the kernel's virtual memory system can re-map
|
||||
a buffer from one process to another with zero copying. If the read stream takes
|
||||
a buffer from its caller, this zero-copy transfer still incurs a copy to move
|
||||
data from the remapped buffer to the client's buffer. With callee-owned read,
|
||||
the data can be used in-place. The same applies to kernel-managed buffer schemes
|
||||
where the operating system shares buffers directly with userspace.
|
||||
|
||||
**Caller-owned read is optimal when reading into an existing buffer.** If the
|
||||
caller wants to initialize a subrange of an existing allocation by reading into
|
||||
it, having the stream produce its own buffer — even a pre-allocated one — forces
|
||||
at least a copy from the stream's buffer into the target region. With
|
||||
caller-owned read, the stream fills the target region directly.
|
||||
|
||||
**Caller-owned write is optimal when the data already exists in a buffer.**
|
||||
Writing the contents of an `Array` to disk via a stream that uses the `write()`
|
||||
syscall internally requires no intermediate buffer if the caller hands the
|
||||
array's storage directly to the stream. If the stream (callee) provided its own
|
||||
buffer, the caller would have to copy the array's elements into it first.
|
||||
|
||||
**Callee-owned write is optimal when the destination already has storage.** In
|
||||
many situations the writer already owns a buffer — a kernel-shared memory
|
||||
region, a pre-registered I/O buffer, or the backing storage of a collection
|
||||
being initialized. With callee-owned write, the writer exposes that existing
|
||||
storage directly, letting the producer write into it in-place with no
|
||||
intermediate buffer and no copy.
|
||||
|
||||
Caller-owned read and write are also important for Embedded Swift and other
|
||||
resource-constrained environments, where the caller provides one buffer up front
|
||||
and nothing else in the system ever needs to allocate.
|
||||
|
||||
If buffers cannot be reused, memory management overhead often dominates
|
||||
performance. This motivates a design where the compiler enforces that buffers
|
||||
are not stored after the operation completes, enabling safe reuse.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
We propose a family of four protocols representing the possible combinations of
|
||||
the 2×2 possibility matrix:
|
||||
|
||||
{ Caller Buffers, Callee Buffers } × { Read, Write }
|
||||
|
||||
These protocols use generic buffer types constrained to `RangeReplaceableContainer`
|
||||
from the Swift Collections library. For the callee-owned variants, a closure-scoped
|
||||
API with `inout` access ensures the caller can process elements without taking
|
||||
ownership of the buffer, enabling safe reuse.
|
||||
|
||||
The bite-sized pseudocode:
|
||||
|
||||
```
|
||||
protocol AsyncReader {
|
||||
// Callee provides a full buffer; caller drains it
|
||||
func read(body: (inout buffer) throws -> R) throws -> R
|
||||
}
|
||||
|
||||
protocol CallerAsyncReader {
|
||||
// Caller provides an empty buffer; callee fills it
|
||||
func read(into buffer: inout buffer) throws
|
||||
}
|
||||
|
||||
protocol CallerAsyncWriter {
|
||||
// Caller provides a full buffer; callee drains it
|
||||
func write(buffer: inout buffer) throws
|
||||
}
|
||||
|
||||
protocol AsyncWriter {
|
||||
// Callee provides an empty buffer; caller fills it
|
||||
func write(body: (inout buffer) throws -> R) throws -> R
|
||||
}
|
||||
```
|
||||
|
||||
### Progressive disclosure
|
||||
|
||||
Four protocols is a little daunting to newcomers, and immediately raises the
|
||||
question "which one(s) should my type conform to?". We believe that applying
|
||||
"streams flow downhill" as a rule of thumb gets the best results in the majority
|
||||
of situations:
|
||||
|
||||
> If you are not sure, pick callee-owned (`AsyncReader`) for read streams and
|
||||
> caller-owned (`CallerAsyncWriter`) for write streams.
|
||||
|
||||
The intuition: data produced by the callee flows toward the caller on the read
|
||||
side, so the callee is the natural owner of the buffer. On the write side, data
|
||||
produced by the caller flows toward the callee, so the caller is the natural
|
||||
owner. The "other" pair exists for cases where the default imposes unnecessary
|
||||
overhead.
|
||||
|
||||
By documenting this rule and following it in our own types, we expect developers
|
||||
to naturally reach for `AsyncReader` and `CallerAsyncWriter`, leaving
|
||||
`CallerAsyncReader` and `AsyncWriter` for the specialized situations that
|
||||
truly need them.
|
||||
|
||||
### Bridging with `AsyncSequence`
|
||||
|
||||
Rather than reparenting `AsyncSequence`, we provide bidirectional bridging
|
||||
extensions that allow converting freely between the two abstractions:
|
||||
|
||||
```swift
|
||||
// AsyncReader → AsyncSequence
|
||||
let sequence = someReader.asyncSequence
|
||||
|
||||
// AsyncSequence → AsyncReader
|
||||
let reader = someSequence.asyncReader
|
||||
```
|
||||
|
||||
This approach avoids requiring the protocol reparenting language feature while
|
||||
giving developers a clear migration path. Existing `AsyncSequence`-based APIs
|
||||
can be consumed by code expecting an `AsyncReader`, and new `AsyncReader`-based
|
||||
APIs can interoperate with the existing `AsyncSequence` ecosystem.
|
||||
|
||||
## Detailed design
|
||||
|
||||
### Support types
|
||||
|
||||
```swift
|
||||
/// A type-safe wrapper around one of two distinct error types.
|
||||
///
|
||||
/// Use ``EitherError`` when an operation can fail with errors from two
|
||||
/// different sources, such as a read failure and a body closure failure.
|
||||
@frozen
|
||||
public enum EitherError<First: Error, Second: Error>: Error {
|
||||
/// An error of the first type.
|
||||
///
|
||||
/// The associated value contains the specific error instance of type `First`.
|
||||
case first(First)
|
||||
|
||||
/// An error of the second type.
|
||||
///
|
||||
/// The associated value contains the specific error instance of type `Second`.
|
||||
case second(Second)
|
||||
|
||||
/// Throws the underlying error, unwrapping this either error.
|
||||
///
|
||||
/// This method extracts and throws the error in the either error,
|
||||
/// whether it's the first or second type. Use this when you need to propagate
|
||||
/// the original error without the either error wrapper.
|
||||
///
|
||||
/// - Throws: The underlying error, either of type `First` or `Second`.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// do {
|
||||
/// // Some operation that returns EitherError
|
||||
/// let result = try await operation()
|
||||
/// } catch let eitherError as EitherError<NetworkError, ParseError> {
|
||||
/// try eitherError.unwrap() // Throws the original error
|
||||
/// }
|
||||
/// ```
|
||||
public func unwrap() throws {
|
||||
switch self {
|
||||
case .first(let first):
|
||||
throw first
|
||||
case .second(let second):
|
||||
throw second
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension EitherError where Second == Never {
|
||||
public func unwrap() throws(First) { ... }
|
||||
}
|
||||
|
||||
extension EitherError where First == Never {
|
||||
public func unwrap() throws(Second) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
The `EitherError` type exists because the callee-owned protocols have two
|
||||
distinct failure domains: the underlying stream operation can fail, and the
|
||||
caller's body closure can also fail. These are logically independent error
|
||||
types, and conflating them would lose information. The `Never`-constrained
|
||||
extensions allow ergonomic use when one side cannot fail.
|
||||
|
||||
### Callee-owned async reader (preferred read type)
|
||||
|
||||
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
|
||||
|
||||
/// 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
|
||||
|
||||
/// 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
|
||||
}
|
||||
```
|
||||
|
||||
### Caller-owned async reader
|
||||
|
||||
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
|
||||
|
||||
/// The type of error thrown during reading.
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
### Caller-owned async writer (preferred write type)
|
||||
|
||||
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
|
||||
|
||||
/// The type of error thrown during writing.
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
### Callee-owned async writer
|
||||
|
||||
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
|
||||
|
||||
/// 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
|
||||
|
||||
/// 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
|
||||
}
|
||||
```
|
||||
|
||||
### Bridging between `AsyncReader` and `AsyncSequence`
|
||||
|
||||
We provide extensions for converting between `AsyncReader` and `AsyncSequence`
|
||||
in both directions. These require `Element: Copyable` since `AsyncSequence` does
|
||||
not support noncopyable elements.
|
||||
|
||||
#### `AsyncReader` to `AsyncSequence`
|
||||
|
||||
```swift
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: Copyable {
|
||||
/// Returns an `AsyncSequence` that yields the elements of this reader
|
||||
/// one at a time.
|
||||
///
|
||||
/// The returned sequence calls `read` on the underlying reader and
|
||||
/// yields the elements from each buffer individually.
|
||||
public var asyncSequence: AsyncReaderSequence<Self> { get }
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` adapter over an `AsyncReader`.
|
||||
public struct AsyncReaderSequence<
|
||||
Reader: AsyncReader & ~Copyable & ~Escapable
|
||||
>: AsyncSequence where Reader.ReadElement: Copyable {
|
||||
public typealias Element = Reader.ReadElement
|
||||
public typealias Failure = Reader.ReadFailure
|
||||
|
||||
public struct AsyncIterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws(Failure) -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncIterator
|
||||
}
|
||||
```
|
||||
|
||||
#### `AsyncSequence` to `AsyncReader`
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
/// Returns an `AsyncReader` that reads elements from this sequence.
|
||||
///
|
||||
/// Each call to `read` on the returned reader advances the sequence's
|
||||
/// iterator and passes available elements to the body closure as a buffer.
|
||||
public var asyncReader: AsyncSequenceReader<Self> { get }
|
||||
}
|
||||
|
||||
/// An `AsyncReader` adapter over an `AsyncSequence`.
|
||||
public struct AsyncSequenceReader<
|
||||
Base: AsyncSequence
|
||||
>: AsyncReader {
|
||||
public typealias ReadElement = Base.Element
|
||||
public typealias ReadFailure = Base.Failure
|
||||
|
||||
public mutating func read<Return, Failure: Error>(
|
||||
body: (inout Buffer) async throws(Failure) -> Return
|
||||
) async throws(EitherError<ReadFailure, Failure>) -> Return
|
||||
}
|
||||
```
|
||||
|
||||
These bridging types allow incremental adoption: existing `AsyncSequence`-based
|
||||
APIs can be consumed by code expecting an `AsyncReader`, and new
|
||||
`AsyncReader`-based APIs remain accessible to code that expects an
|
||||
`AsyncSequence`.
|
||||
|
||||
## Source compatibility
|
||||
|
||||
This proposal is purely additive. It introduces new protocols, types, and
|
||||
extensions without modifying any existing declarations.
|
||||
|
||||
## ABI compatibility
|
||||
|
||||
This proposal is purely an extension of the ABI of the standard library and does
|
||||
not change any existing features.
|
||||
|
||||
## Implications on adoption
|
||||
|
||||
Like almost all new types, these protocols do not support back deployment.
|
||||
|
||||
Library authors adopting these protocols can do so additively. Conforming a type
|
||||
to one of the new protocols does not affect existing API or ABI. The conformance
|
||||
can be removed later without breaking source or ABI compatibility, subject to
|
||||
normal API evolution considerations.
|
||||
|
||||
## Future directions
|
||||
|
||||
### Convenience extensions
|
||||
|
||||
The core protocol signatures are general but unwieldy for types that have no
|
||||
interest in bulk access. Convenience extensions would simplify common usage
|
||||
patterns, for example:
|
||||
|
||||
* Simplified error handling when one side cannot fail (`Failure == Never` or a
|
||||
non-throwing body closure).
|
||||
* Single-element access via a `next()` method for callee-owned readers.
|
||||
* Adapting a callee-owned reader to a caller-owned buffer (at the cost of a
|
||||
copy) for interoperability between the two buffer ownership strategies.
|
||||
|
||||
These extensions are straightforward to add in a follow-up proposal once the
|
||||
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:
|
||||
|
||||
```swift
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
|
||||
/// Iterates over all chunks, executing `body` for each buffer until the
|
||||
/// stream ends.
|
||||
public consuming func forEachBuffer<Failure: Error>(
|
||||
body: (inout Buffer) async throws(Failure) -> Void
|
||||
) async throws(EitherError<ReadFailure, Failure>)
|
||||
}
|
||||
|
||||
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>(
|
||||
upTo limit: Int,
|
||||
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
|
||||
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result
|
||||
}
|
||||
```
|
||||
|
||||
`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).
|
||||
|
||||
These helpers are intentionally excluded from this proposal because their error
|
||||
handling semantics (particularly `collect`'s nested `EitherError` and the
|
||||
`AsyncReaderLeftOverElementsError` overflow behavior) benefit from real-world
|
||||
usage feedback before stabilization.
|
||||
|
||||
### Owned buffer transfer protocols
|
||||
|
||||
The four protocols in this proposal all use generic `RangeReplaceableContainer`
|
||||
buffers with closure-scoped `inout` access. This is optimal for high-throughput
|
||||
streaming where buffer reuse matters — the caller processes elements in-place
|
||||
without taking ownership, enabling safe reuse without copies.
|
||||
|
||||
However, there are important message-oriented I/O patterns where the caller
|
||||
needs to take ownership of the data with an independent lifetime. Consider an
|
||||
HTTP/2 proxy: the proxy decodes a DATA frame, which internally allocates a
|
||||
buffer to hold the frame payload. With the closure-scoped protocols, the proxy
|
||||
receives a mutable reference and must copy the data if it needs to store it for
|
||||
retry or fan-out to multiple downstream connections.
|
||||
|
||||
An owned buffer transfer protocol would let the decoder hand over its
|
||||
internally-allocated buffer by value. The proxy can store it, retry a failed
|
||||
send, or pass it to multiple consumers — all without copying:
|
||||
|
||||
```swift
|
||||
// Conceptual sketch — not part of this proposal
|
||||
protocol OwnedAsyncReader<Buffer, Failure>: ~Copyable, ~Escapable {
|
||||
associatedtype Buffer: ~Copyable
|
||||
associatedtype Failure: Error
|
||||
|
||||
mutating func read() async throws(Failure) -> Buffer?
|
||||
}
|
||||
```
|
||||
|
||||
This differs fundamentally from the caller/callee distinction in this proposal.
|
||||
The closure-scoped protocols are about **who manages a reusable buffer during a
|
||||
streaming operation**. Owned buffer transfer is about **transferring
|
||||
independently-allocated data with a lifecycle decoupled from the stream**. This
|
||||
is the distinction between stream-oriented I/O (TCP byte streams, file reads)
|
||||
and message-oriented I/O (HTTP frames, protocol messages).
|
||||
|
||||
Several open design questions remain for owned buffer transfer:
|
||||
|
||||
* **What type should the buffer be?** An associated type bounded by a protocol
|
||||
(similar to how the `http-body` crate in other ecosystems uses an associated
|
||||
`Data` type bounded by a `Buf` trait) provides maximum flexibility — each
|
||||
conforming type can yield its own buffer type (`Array`, `UniqueArray`,
|
||||
`Data`, or a custom reference-counted immutable buffer). The protocol bound
|
||||
would provide basic operations: count, access to underlying bytes, and
|
||||
possibly zero-copy slicing.
|
||||
* **Copyable or noncopyable?** For message-oriented patterns where cheap
|
||||
sharing matters (proxy retry, fan-out, logging), a copy-on-write `Copyable`
|
||||
type like `Array` is the natural default. For kernel-shared or DMA-mapped
|
||||
buffers where copying is meaningless or dangerous, a `~Copyable` type
|
||||
enforces single-ownership. The associated type should be bounded as
|
||||
`~Copyable` to allow both.
|
||||
|
||||
Because owned buffer transfer has fundamentally different semantics — it returns
|
||||
owned values rather than providing scoped access — it requires its own
|
||||
protocols. The four protocols proposed here are stable and orthogonal to this
|
||||
future addition.
|
||||
|
||||
### Vectored I/O protocols (scatter/gather)
|
||||
|
||||
Operating systems provide scatter/gather I/O operations (`readv`/`writev` on
|
||||
POSIX, `WSARecv`/`WSASend` on Windows) that read into or write from multiple
|
||||
non-contiguous buffers in a single system call. This is important for network
|
||||
interfaces that may have many separately allocated packets ready to deliver, or
|
||||
for protocols that produce headers and payloads in separate buffers.
|
||||
|
||||
A vectored variant would operate on a collection of spans rather than a single
|
||||
contiguous span. The central design challenge is **sizing**: how many span
|
||||
entries can the collection hold?
|
||||
|
||||
* A fixed-size inline array (e.g., `InlineArray<N, InputSpan<Element>>`) avoids
|
||||
heap allocation but requires choosing N at compile time. Too small limits
|
||||
flexibility; too large wastes stack space.
|
||||
* A dynamically-sized array heap-allocates on every I/O operation, which is
|
||||
unacceptable on hot paths.
|
||||
* A small-vector optimization (inline N, then spill to heap) adds branching and
|
||||
complexity.
|
||||
|
||||
The callee-owned pattern from this proposal suggests a solution: the entity
|
||||
closest to the system call knows the right sizing. A file writer wrapping
|
||||
`writev` knows it needs at most `IOV_MAX` (typically 1024) entries. A TLS writer
|
||||
knows it produces at most 2 segments. A UDP socket sends one segment per
|
||||
datagram. By having the callee manage the vectored span's backing storage —
|
||||
using inline arrays, pooled allocations, or `withUnsafeTemporaryAllocation` as
|
||||
appropriate — the sizing problem is delegated to the entity with the most
|
||||
information.
|
||||
|
||||
Because vectored I/O operates on a fundamentally different data structure (a
|
||||
collection of non-contiguous spans rather than a single contiguous span),
|
||||
grafting it onto the existing protocols would complicate the common
|
||||
single-buffer case for all users. It is best served by its own protocols. The
|
||||
four protocols proposed here are stable and orthogonal to this future addition.
|
||||
|
||||
### Synchronous versions of the protocols
|
||||
|
||||
The engineers working on the ["future of
|
||||
serialization"](https://forums.swift.org/t/the-future-of-serialization-deserialization-apis/78585)
|
||||
project have indicated that async-only is unpalatable for uses like theirs.
|
||||
Synchronous equivalents of these protocols would be valuable, but the design for
|
||||
synchronous noncopyable iteration and container types is still in flux. We
|
||||
should wait to see how best to integrate with that work.
|
||||
|
||||
### Structured algorithms with scoped lifetime
|
||||
|
||||
Some algorithms in `swift-async-algorithms` — such as `merge`, `zip`, and
|
||||
`buffer` — currently require unstructured tasks because reading from an upstream
|
||||
sequence must outlive a single call to the iterator's `next()` method. For
|
||||
example, `merge` races multiple base sequences on each call to `next`; when one
|
||||
base produces a value, iteration of the other bases must continue independently.
|
||||
|
||||
The use of unstructured tasks means cancellation, priority escalation, task
|
||||
executor preference, and task locals must all be propagated manually — a fragile
|
||||
and error-prone pattern.
|
||||
|
||||
These algorithms could instead be redesigned as scoped, `with`-style operations
|
||||
or types with an explicit `run` method that manages the concurrent iteration
|
||||
within a structured child task:
|
||||
|
||||
```swift
|
||||
await merge(first, second) { merged in
|
||||
for await element in merged {
|
||||
// process element
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is an independent concern from the streaming protocols proposed here, but
|
||||
the new protocols provide a better foundation for such redesigns.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### Only supporting a subset of the buffer ownership options
|
||||
|
||||
For simplicity, it would be nice to have fewer protocols. We could support only
|
||||
callee-owned read and caller-owned write (the "preferred" pair), or only
|
||||
caller-owned for both directions.
|
||||
|
||||
We decided that since no single buffer ownership strategy is optimal for all
|
||||
cases (as demonstrated in the Motivation section), the full 2×2 matrix is
|
||||
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.
|
||||
|
||||
### Not using closures to provide temporary access to buffers
|
||||
|
||||
The callee-owned read and write APIs use closures that receive a span, which
|
||||
introduces the complexity of `EitherError` (since both the stream operation and
|
||||
the closure can throw independent error types). It would be simpler to return a
|
||||
span directly.
|
||||
|
||||
However, without closures (or equivalent coroutine support like generators),
|
||||
there would be no way for the callee to perform cleanup work when the caller is
|
||||
done with the buffer. This makes the design incompatible with buffer pools,
|
||||
where the callee must reclaim the buffer after use. The closure-scoped pattern
|
||||
ensures the callee maintains control over buffer lifecycle.
|
||||
|
||||
### Just extending `AsyncSequence` with bulk transfer support
|
||||
|
||||
This was the original plan. However, recent developments on `Sequence` have
|
||||
shown that supporting noncopyable types requires a new protocol regardless.
|
||||
Given that a new protocol is needed anyway, designing the full streaming family
|
||||
from scratch allows us to address all the limitations at once.
|
||||
|
||||
### Reparenting `AsyncSequence`
|
||||
|
||||
Instead of bridging extensions, we could use protocol reparenting to
|
||||
retroactively make `AsyncSequence` a subtype of `AsyncReader`. This would give
|
||||
every existing `AsyncSequence` conformance automatic participation in the new
|
||||
streaming ecosystem without any code changes.
|
||||
|
||||
However, would also force an `AsyncReader`/`AsyncReaderIterator` split to match
|
||||
`AsyncSequence`'s existing `makeAsyncIterator()` pattern, complicating the
|
||||
`AsyncReader` protocol for all users. The bridging approach achieves the same
|
||||
interoperability with explicit, discoverable conversions and a simpler protocol
|
||||
definition.
|
||||
|
||||
### Using a concrete type rather than protocols
|
||||
|
||||
We could define concrete streaming types instead of protocols. This would
|
||||
simplify some aspects of the design but would prevent adapting existing types to
|
||||
the new abstraction. Protocols give library authors the flexibility to implement
|
||||
streaming over their own storage and I/O backends.
|
||||
|
||||
### Using `throws` rather than typed throws
|
||||
|
||||
Embedded Swift environments do not support allocating boxes for existential
|
||||
errors. Using typed throws (`throws(Failure)`) allows these protocols to be used
|
||||
in resource-constrained environments, which is an explicit goal of this design.
|
||||
|
||||
### Having split stream/iterator types
|
||||
|
||||
For symmetry with `AsyncSequence`'s `makeAsyncIterator()` pattern, we considered
|
||||
adding an iterator split to some or all of the streaming protocols. This would
|
||||
be necessary if we chose to reparent `AsyncSequence` (see above). Since we use
|
||||
bridging extensions instead, none of the four protocols need an iterator split,
|
||||
resulting in a simpler and more uniform design.
|
||||
|
||||
### Async generators
|
||||
|
||||
Asynchronous generators could provide an alternative to `AsyncSequence` and
|
||||
`AsyncReader` by allowing a function to `yield` values over time. However,
|
||||
generators would require significant compiler work and would primarily address
|
||||
only the read side. The write side — which is essential for bidirectional
|
||||
streaming — would still need a separate push-based protocol. Generators may
|
||||
complement this proposal in the future, but they do not replace the need for the
|
||||
protocols proposed here.
|
||||
|
||||
### Approaches in other ecosystems
|
||||
|
||||
Other language ecosystems have explored the same problem space of async I/O
|
||||
buffer management.
|
||||
|
||||
#### Go
|
||||
|
||||
Go's I/O model is built on two minimal interfaces: `io.Reader` with `Read(p
|
||||
[]byte) (n int, err error)` and `io.Writer` with `Write(p []byte) (n int, err
|
||||
error)`. **Buffer ownership is strictly caller-owned in both directions.** The
|
||||
documentation states "implementations must not retain p" but this is enforced
|
||||
only by convention — Go has no lifetime or borrowing annotations.
|
||||
|
||||
Go has no general-purpose callee-owned buffer interface. The `bufio.Reader` type
|
||||
provides `Peek()` and `ReadSlice()` methods that return views into an internal
|
||||
buffer, but only as concrete methods on a specific type, not as an interface
|
||||
abstraction. When data arrives from the kernel or IPC in an existing buffer, the
|
||||
caller-only model forces a copy into the caller's `[]byte` — there is no
|
||||
standard way for the reader to say "here is data I already have."
|
||||
|
||||
Go's goroutine model — where blocking I/O suspends a goroutine rather than an OS
|
||||
thread — means there is less pressure to model async operations at the type
|
||||
level. The `io.Reader`/`io.Writer` interfaces are synchronous, and concurrency
|
||||
comes from running readers and writers in separate goroutines. This simplifies
|
||||
interface signatures but means cancellation is handled separately via
|
||||
`context.Context`, outside the I/O interfaces themselves.
|
||||
|
||||
For scatter/gather I/O, `net.Buffers` (a `[][]byte`) dispatches to `writev` on
|
||||
supported connections, but only for writes — there is no equivalent for vectored
|
||||
reads.
|
||||
|
||||
#### .NET
|
||||
|
||||
.NET's classic `System.IO.Stream` uses caller-owned buffers, like Go:
|
||||
`ReadAsync(Memory<byte> buffer)` and `WriteAsync(ReadOnlyMemory<byte> buffer)`.
|
||||
Limitations observed in high-performance server code (ASP.NET Core's Kestrel)
|
||||
motivated a redesign.
|
||||
|
||||
`System.IO.Pipelines` (2018) introduces `PipeReader` and `PipeWriter` as
|
||||
separate types with distinct buffer ownership strategies:
|
||||
|
||||
* **`PipeReader` is callee-owned read.** `ReadAsync()` returns a `ReadResult`
|
||||
containing a `ReadOnlySequence<byte>` — a linked list of memory segments
|
||||
owned by the pipe. The caller examines the data in-place, then calls
|
||||
`AdvanceTo(consumed, examined)` to signal how much was processed. This
|
||||
enables partial consumption without copying and provides .NET's answer to
|
||||
non-contiguous buffers: segments from multiple network reads are chained
|
||||
together without coalescing into a single contiguous buffer.
|
||||
|
||||
* **`PipeWriter` is callee-owned write.** The writer exposes its internal
|
||||
buffer via `GetMemory()`/`GetSpan()`, the caller fills it, then calls
|
||||
`Advance()` to commit. This is formalized as the `IBufferWriter<T>`
|
||||
interface. `PipeWriter` also offers `WriteAsync(ReadOnlyMemory<byte>)` as a
|
||||
caller-owned convenience that internally copies into the pipe's buffer.
|
||||
|
||||
Pipelines includes built-in backpressure: when unconsumed data exceeds a
|
||||
configurable threshold, `FlushAsync()` suspends the writer until the reader
|
||||
catches up. Buffer pooling is integrated via `MemoryPool<T>`.
|
||||
|
||||
The lifetime safety of buffer access in Pipelines is enforced at runtime — using
|
||||
a `ReadOnlySequence<byte>` after calling `AdvanceTo` is undefined behavior.
|
||||
.NET's `Span<T>` (a stack-only ref struct that cannot survive across `await`
|
||||
points) provides some compile-time safety, but `Memory<T>` (the heap-storable
|
||||
counterpart needed for async code) does not.
|
||||
|
||||
#### Rust
|
||||
|
||||
In the Rust ecosystem, the `AsyncRead` and `AsyncWrite` traits use borrowed
|
||||
buffers (`&mut [u8]`), which works for readiness-based I/O but is fundamentally
|
||||
incompatible with completion-based I/O where the kernel holds the buffer for an
|
||||
indeterminate period. This led to a fragmented ecosystem: readiness-based
|
||||
runtimes (tokio, async-std) use one set of traits, while completion-based
|
||||
runtimes (tokio-uring, monoio, compio) use a different set of ownership-transfer
|
||||
traits (`IoBuf`/`IoBufMut`).
|
||||
|
||||
A major contributor to this fragmentation is the interaction between Rust's
|
||||
`Future` trait (where futures can be dropped at any suspension point) and
|
||||
completion-based I/O (where the kernel may still hold a buffer when a future is
|
||||
cancelled). This creates potential use-after-free scenarios that require complex
|
||||
workarounds: ownership transfer, buffer graveyards, or the still-unresolved
|
||||
async destructor RFC.
|
||||
|
||||
#### What Swift's design learns from these ecosystems
|
||||
|
||||
Swift's structured concurrency model avoids the cancellation and buffer lifetime
|
||||
problems that fragment Rust's ecosystem: structured concurrency guarantees that
|
||||
child tasks complete before the parent scope exits, and cancellation is
|
||||
cooperative. The closure-scoped design of the callee-owned protocols provides
|
||||
compiler-enforced safety — the `Buffer` associated type is `~Copyable`, and the
|
||||
`inout` closure pattern ensures buffers cannot be stored beyond the closure scope.
|
||||
This is stronger than Go's convention-based "must not retain p" and .NET's
|
||||
runtime-only enforcement after `AdvanceTo`.
|
||||
|
||||
The proposal's 2×2 matrix of {caller, callee} × {read, write} is unique among
|
||||
these ecosystems. Go provides only caller-owned for both directions. .NET
|
||||
Pipelines provides callee-owned for both directions (with a caller-owned write
|
||||
convenience) but not caller-owned read as a first-class abstraction. The Swift
|
||||
proposal provides all four combinations, informed by the observation that each
|
||||
is optimal in distinct situations.
|
||||
|
||||
We studied these ecosystems' experiences to validate the design space
|
||||
decomposition, and to confirm that owned buffer transfer and vectored I/O (both
|
||||
listed as future directions) are genuinely separate concerns that warrant their
|
||||
own protocols rather than being forced into the caller/callee framework.
|
||||
@@ -0,0 +1,89 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderCollectTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func collectAllElements() async throws {
|
||||
var 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)
|
||||
}
|
||||
|
||||
#expect(result == [1, 2, 3, 4, 5])
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func collectWithExactLimit() async throws {
|
||||
var 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)
|
||||
}
|
||||
|
||||
#expect(result == [1, 2, 3, 4, 5])
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func collectEmptyReader() async throws {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
|
||||
let result = try await reader.collect(upTo: 10) { span in
|
||||
return span.count
|
||||
}
|
||||
|
||||
#expect(result == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func collectProcessesAllElements() async throws {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
|
||||
|
||||
let result = try await reader.collect(upTo: 10) { span in
|
||||
var sum = 0
|
||||
for i in span.indices {
|
||||
sum += span[i]
|
||||
}
|
||||
return sum
|
||||
}
|
||||
|
||||
#expect(result == 60)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func collectThrowsLeftOverElements() async throws {
|
||||
var 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
|
||||
return span.count
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,119 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderforEachBufferTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferIteratesAllSpans() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
var elementCount = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
elementCount += buffer.count
|
||||
}
|
||||
|
||||
#expect(elementCount == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferProcessesElements() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
|
||||
var sum = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
for i in buffer.indices {
|
||||
sum += buffer[i]
|
||||
}
|
||||
}
|
||||
|
||||
#expect(sum == 60)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferWithEmptyReader() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
var callCount = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
callCount += 1
|
||||
}
|
||||
|
||||
#expect(callCount == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferWithThrowingBody() async {
|
||||
enum TestError: Error {
|
||||
case failed
|
||||
}
|
||||
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
|
||||
do {
|
||||
try await reader.forEachBuffer { (_) throws(TestError) -> Void in
|
||||
throw TestError.failed
|
||||
}
|
||||
Issue.record("Expected error to be thrown")
|
||||
} catch {
|
||||
#expect(error == EitherError.second(TestError.failed))
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferWithNeverFailingReader() async {
|
||||
enum TestError: Error {
|
||||
case failed
|
||||
}
|
||||
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var count = 0
|
||||
|
||||
do {
|
||||
try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
|
||||
count += buffer.count
|
||||
}
|
||||
} catch {
|
||||
Issue.record("No error should be thrown from reader")
|
||||
}
|
||||
|
||||
#expect(count == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func forEachBufferWithAsyncWork() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var results: [Int] = []
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
await Task.yield()
|
||||
for i in buffer.indices {
|
||||
results.append(buffer[i])
|
||||
}
|
||||
}
|
||||
|
||||
#expect(results == [1, 2, 3])
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,57 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func read() async {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
|
||||
let result = try! await reader.read { buffer in
|
||||
return buffer.clone()
|
||||
}
|
||||
|
||||
#expect(result.count == 5)
|
||||
#expect(result[0] == 1)
|
||||
#expect(result[1] == 2)
|
||||
#expect(result[2] == 3)
|
||||
#expect(result[3] == 4)
|
||||
#expect(result[4] == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func readEmptyAtEnd() async {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
|
||||
// Read all data
|
||||
let first = try! await reader.read { buffer in
|
||||
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)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,103 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncWriterTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeElements() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(1)
|
||||
buffer.append(2)
|
||||
buffer.append(3)
|
||||
}
|
||||
|
||||
#expect(writer.storage.count == 3)
|
||||
#expect(writer.storage[0] == 1)
|
||||
#expect(writer.storage[1] == 2)
|
||||
#expect(writer.storage[2] == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeEmptyBuffer() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { _ in }
|
||||
|
||||
#expect(writer.storage.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeReturnsValue() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
let count = try! await writer.write { buffer in
|
||||
buffer.append(10)
|
||||
buffer.append(20)
|
||||
return buffer.count
|
||||
}
|
||||
|
||||
#expect(count == 2)
|
||||
#expect(writer.storage.count == 2)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeWithThrowingBody() async {
|
||||
enum TestError: Error, Equatable {
|
||||
case failed
|
||||
}
|
||||
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
do {
|
||||
try await writer.write { (_) throws(TestError) -> Void in
|
||||
throw TestError.failed
|
||||
}
|
||||
Issue.record("Expected error to be thrown")
|
||||
} catch {
|
||||
#expect(error == EitherError<Never, TestError>.second(TestError.failed))
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeMultipleTimes() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(1)
|
||||
buffer.append(2)
|
||||
}
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(3)
|
||||
buffer.append(4)
|
||||
}
|
||||
|
||||
#expect(writer.storage.count == 4)
|
||||
#expect(writer.storage[0] == 1)
|
||||
#expect(writer.storage[1] == 2)
|
||||
#expect(writer.storage[2] == 3)
|
||||
#expect(writer.storage[3] == 4)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,93 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncReaderTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func readIntoBuffer() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 10)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 5)
|
||||
#expect(buffer[0] == 1)
|
||||
#expect(buffer[1] == 2)
|
||||
#expect(buffer[2] == 3)
|
||||
#expect(buffer[3] == 4)
|
||||
#expect(buffer[4] == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func readIntoBufferAtEnd() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 0, copying: [])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 10)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func readIntoBufferRespectsCapacity() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 10, copying: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 3)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 3)
|
||||
#expect(buffer[0] == 1)
|
||||
#expect(buffer[1] == 2)
|
||||
#expect(buffer[2] == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func readMultipleTimes() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 6, copying: [1, 2, 3, 4, 5, 6])
|
||||
)
|
||||
|
||||
var buffer1 = UniqueArray<Int>(minimumCapacity: 3)
|
||||
await reader.read(into: &buffer1)
|
||||
#expect(buffer1.count == 3)
|
||||
#expect(buffer1[0] == 1)
|
||||
#expect(buffer1[1] == 2)
|
||||
#expect(buffer1[2] == 3)
|
||||
|
||||
var buffer2 = UniqueArray<Int>(minimumCapacity: 3)
|
||||
await reader.read(into: &buffer2)
|
||||
#expect(buffer2.count == 3)
|
||||
#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
|
||||
@@ -0,0 +1,53 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncWriterTests {
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter()
|
||||
var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeEmptyBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter()
|
||||
var data = UniqueArray<Int>()
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
func writeLargeBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter(capacity: 100)
|
||||
var data = UniqueArray(capacity: 5, copying: Array(1...50))
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 50)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,68 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct EitherErrorTests {
|
||||
enum FirstError: Error, Equatable, Hashable {
|
||||
case one
|
||||
case two
|
||||
}
|
||||
|
||||
enum SecondError: Error, Equatable, Hashable {
|
||||
case alpha
|
||||
case beta
|
||||
}
|
||||
|
||||
@Test
|
||||
func unwrapFirst() throws {
|
||||
let error: EitherError<FirstError, SecondError> = .first(.one)
|
||||
|
||||
#expect(throws: FirstError.one) {
|
||||
try error.unwrap()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func unwrapSecond() throws {
|
||||
let error: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(throws: SecondError.alpha) {
|
||||
try error.unwrap()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func equatable() {
|
||||
let a: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let b: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let c: EitherError<FirstError, SecondError> = .first(.two)
|
||||
let d: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(a == b)
|
||||
#expect(a != c)
|
||||
#expect(a != d)
|
||||
}
|
||||
|
||||
@Test
|
||||
func hashable() {
|
||||
let a: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let b: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let c: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(a.hashValue == b.hashValue)
|
||||
#expect(a.hashValue != c.hashValue)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,43 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
extension Array {
|
||||
init(_ span: Span<Element>) {
|
||||
self.init()
|
||||
for index in span.indices {
|
||||
self.append(span[index])
|
||||
}
|
||||
}
|
||||
|
||||
init(_ inputSpan: borrowing InputSpan<Element>) {
|
||||
self.init()
|
||||
for index in inputSpan.indices {
|
||||
self.append(inputSpan[index])
|
||||
}
|
||||
}
|
||||
|
||||
mutating func append(span: Span<Element>) {
|
||||
for index in span.indices {
|
||||
self.append(span[index])
|
||||
}
|
||||
}
|
||||
|
||||
mutating func append(inputSpan: borrowing InputSpan<Element>) {
|
||||
for index in inputSpan.indices {
|
||||
self.append(inputSpan[index])
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,37 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
struct UniqueArrayAsyncReader: ~Copyable, AsyncReader {
|
||||
typealias ReadElement = Int
|
||||
typealias Buffer = UniqueArray<Int>
|
||||
typealias ReadFailure = Never
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
|
||||
mutating func read<Return: ~Copyable, Failure: Error>(
|
||||
body: (inout UniqueArray<Int>) async throws(Failure) -> Return
|
||||
) async throws(EitherError<Never, Failure>) -> Return {
|
||||
do {
|
||||
var uniqueArray = self.storage.clone()
|
||||
self.storage = .init()
|
||||
return try await body(&uniqueArray)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,42 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
|
||||
typealias WriteElement = Int
|
||||
typealias Buffer = UniqueArray<Int>
|
||||
typealias WriteFailure = Never
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
|
||||
init(capacity: Int = 100) {
|
||||
self.storage = UniqueArray(minimumCapacity: capacity)
|
||||
}
|
||||
|
||||
mutating func write<Return: ~Copyable, Failure: Error>(
|
||||
_ body: (inout UniqueArray<Int>) async throws(Failure) -> Return
|
||||
) async throws(EitherError<Never, Failure>) -> Return {
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 64)
|
||||
do {
|
||||
let result = try await body(&buffer)
|
||||
self.storage.append(copying: buffer)
|
||||
return result
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,36 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
||||
struct UniqueArrayCallerAsyncReader: ~Copyable, CallerAsyncReader {
|
||||
typealias ReadElement = Int
|
||||
typealias ReadFailure = Never
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
var position: Int = 0
|
||||
|
||||
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
|
||||
into buffer: inout Buffer
|
||||
) async throws(ReadFailure) where Buffer.Element: ~Copyable {
|
||||
guard position < storage.count else { return }
|
||||
let count = min(buffer.freeCapacity, storage.count - position)
|
||||
for i in 0..<count {
|
||||
buffer.append(storage[position + i])
|
||||
}
|
||||
position += count
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,37 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
struct WriterCapacityError: Error {}
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
|
||||
struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
|
||||
typealias WriteElement = Int
|
||||
typealias WriteFailure = Never
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
|
||||
init(capacity: Int = 100) {
|
||||
self.storage = UniqueArray(minimumCapacity: capacity)
|
||||
}
|
||||
|
||||
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
|
||||
self.storage.reserveCapacity(buffer.count)
|
||||
self.storage.append(copying: buffer)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
Reference in new issue
Block a user