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 | ||
|
|
9d349bcc32 | ||
|
|
5043186441 |
No files matched your search
+2
-1
@@ -9,4 +9,5 @@ DerivedData/
|
||||
.netrc
|
||||
.swiftpm
|
||||
Package.resolved
|
||||
.swift-version
|
||||
.swift-version
|
||||
test_output.log
|
||||
File renamed without changes.
@@ -0,0 +1,200 @@
|
||||
# FlatMapLatest
|
||||
|
||||
* Proposal: [SAA-00nn](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/00nn-flatMapLatest.md)
|
||||
* Author(s): [Peter Friese](https://github.com/peterfriese)
|
||||
* Status: **Proposed**
|
||||
* Implementation:
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
When transforming elements of an asynchronous sequence into new asynchronous sequences, there are cases where only the results from the most recent transformation are relevant, and previous transformations should be abandoned. This is particularly common in reactive user interfaces where rapid user input triggers asynchronous operations, but only the result of the latest operation matters.
|
||||
|
||||
## Motivation
|
||||
|
||||
Consider a search-as-you-type interface where each keystroke triggers a network request:
|
||||
|
||||
```swift
|
||||
let searchQueries = userInputField.textChanges
|
||||
|
||||
// Without flatMapLatest - all requests complete, wasting resources
|
||||
for await query in searchQueries {
|
||||
let results = try await searchAPI(query)
|
||||
displayResults(results) // May display stale results
|
||||
}
|
||||
```
|
||||
|
||||
Without automatic cancellation, earlier requests continue to completion even though their results are no longer relevant. This wastes network bandwidth, server resources, and may display stale results to the user if a slower request completes after a faster one.
|
||||
|
||||
The `flatMapLatest` operator solves this by automatically cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence:
|
||||
|
||||
```swift
|
||||
let searchResults = searchQueries.flatMapLatest { query in
|
||||
searchAPI(query)
|
||||
}
|
||||
|
||||
for await result in searchResults {
|
||||
displayResults(result) // Only latest results displayed
|
||||
}
|
||||
```
|
||||
|
||||
This pattern is broadly applicable:
|
||||
- **Location-based queries**: Cancel previous location lookups when user moves
|
||||
- **Dynamic configuration**: Restart data loading when settings change
|
||||
- **Auto-save**: Only save the most recent changes when user types rapidly
|
||||
- **Real-time data**: Switch to new data streams based on user selections
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The `flatMapLatest` algorithm transforms each element from the base `AsyncSequence` into a new inner `AsyncSequence` using a transform closure. When a new element is produced by the base sequence, iteration on the current inner sequence is cancelled, and iteration begins on the newly created sequence.
|
||||
|
||||
The interface is available on all `AsyncSequence` types where both the base and inner sequences are `Sendable` along with two disfavored refinements to account for variations of typed throws signatures:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where T.Failure == Failure, T.Element: Sendable, Element: Sendable
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, Failure> & Sendable where T.Failure == Never, T.Element: Sendable, Element: Sendable
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where Failure == Never, T.Element: Sendable, Element: Sendable
|
||||
}
|
||||
```
|
||||
|
||||
This provides a clean API for expressing switching behavior:
|
||||
|
||||
```swift
|
||||
userActions.flatMapLatest { action in
|
||||
performAction(action)
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm emits elements from the inner sequences. It throws when either the base type or any inner sequence throws.
|
||||
|
||||
Since both the base sequence and inner sequences must be `Sendable` (to support concurrent iteration and cancellation), `AsyncFlatMapLatestSequence` is unconditionally `Sendable`.
|
||||
|
||||
### Implementation Strategy
|
||||
|
||||
The implementation uses a state machine pattern to ensure thread-safe operation:
|
||||
|
||||
1. **Generation Tracking**: Each new inner sequence is assigned a generation number. Elements from stale generations are discarded.
|
||||
2. **Explicit Cancellation**: When a new outer element arrives, the previous inner sequence's task is explicitly cancelled and its continuation is resumed with a cancellation error.
|
||||
3. **Lock-Based Coordination**: A `Lock` protects the state machine from concurrent access.
|
||||
4. **Continuation Management**: The storage manages continuations for both upstream (outer/inner sequences) and downstream (consumer) demand.
|
||||
|
||||
This approach eliminates race conditions where cancelled sequences could emit stale values.
|
||||
|
||||
### Behavioral Characteristics
|
||||
|
||||
**Switching**: When the base sequence produces a new element, the current inner sequence iteration is immediately cancelled. Any elements it would have produced are lost.
|
||||
|
||||
**Completion**: The sequence completes when:
|
||||
1. The base sequence finishes producing elements, AND
|
||||
2. The final inner sequence finishes producing elements
|
||||
|
||||
**Error Handling**: If either the base sequence or any inner sequence throws, the error is immediately propagated and all tasks are cancelled.
|
||||
|
||||
**Cancellation**: Cancelling the downstream iteration cancels both the base sequence iteration and the current inner sequence iteration.
|
||||
|
||||
## Example
|
||||
|
||||
```swift
|
||||
let requests = AsyncStream<String> { continuation in
|
||||
continuation.yield("query1")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("query2")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("query3")
|
||||
continuation.finish()
|
||||
}
|
||||
|
||||
let responses = requests.flatMapLatest { query in
|
||||
AsyncStream<String> { continuation in
|
||||
continuation.yield("\(query): loading")
|
||||
try? await Task.sleep(for: .milliseconds(50))
|
||||
continuation.yield("\(query): complete")
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
|
||||
for await response in responses {
|
||||
print(response)
|
||||
}
|
||||
// Output (may vary due to timing):
|
||||
// query1: loading
|
||||
// query2: loading
|
||||
// query3: loading
|
||||
// query3: complete
|
||||
```
|
||||
|
||||
In this example, the earlier queries (query1 and query2) are cancelled before they complete, so only query3 produces its complete response.
|
||||
|
||||
## Effect on API Resilience
|
||||
|
||||
This is an additive API. No existing systems are changed. The new types introduced are:
|
||||
- `AsyncFlatMapLatestSequence<Base, Inner>`: The sequence type
|
||||
- Associated private types for the state machine implementation
|
||||
|
||||
These types will be part of the ABI surface area.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative Names
|
||||
|
||||
**`switchMap`**: Used in ReactiveX, but "switch" in Swift has strong association with control flow statements.
|
||||
|
||||
**`switchToLatest`**: Combine's terminology, but `flatMapLatest` is more discoverable alongside other `map` variants.
|
||||
|
||||
**`flatMap(...).latest()`**: Requires a hypothetical `flatMap` first, adding complexity.
|
||||
|
||||
### Delivering All Elements
|
||||
|
||||
An alternative behavior would buffer elements from cancelled sequences and deliver them later. However, this contradicts the core purpose of "latest" semantics and would be better served by a different operator.
|
||||
|
||||
### No Automatic Cancellation
|
||||
|
||||
Requiring manual cancellation would place significant burden on developers and be error-prone. The automatic cancellation is the key value proposition.
|
||||
|
||||
### Shorthand version for async sequences of async sequences
|
||||
|
||||
Mimicing combine a shorthand extension of `switchToLatest` could be added as an extension when the base AsyncSequence's element conforms to AsyncSequence. The implementation of which is trivial:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Failure, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Never, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Failure == Never, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Comparison with Other Libraries
|
||||
|
||||
**ReactiveX**: ReactiveX has an [API definition of switchMap](https://reactivex.io/documentation/operators/flatmap.html) that performs the same operation for Observables, switching to the latest inner Observable.
|
||||
|
||||
**Combine**: Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which subscribes to the most recent Publisher produced by an upstream Publisher of Publishers. `flatMapLatest` combines the map and switch operations into a single convenient operator.
|
||||
|
||||
**RxSwift**: RxSwift calls this operator `flatMapLatest`, which is the naming this proposal adopts.
|
||||
+64
-2
@@ -9,9 +9,12 @@ let AsyncAlgorithms_v1_1 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
let AsyncAlgorithms_v1_2 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
let AsyncAlgorithms_v1_3 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.3:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
#else
|
||||
let AsyncAlgorithms_v1_1 = "AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
let AsyncAlgorithms_v1_2 = "AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
let AsyncAlgorithms_v1_3 = "AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
#endif
|
||||
|
||||
let availabilityMacros: [SwiftSetting] = [
|
||||
@@ -24,12 +27,30 @@ let availabilityMacros: [SwiftSetting] = [
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_2
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_3
|
||||
),
|
||||
]
|
||||
|
||||
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(
|
||||
@@ -42,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"],
|
||||
@@ -98,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 += [
|
||||
|
||||
@@ -15,6 +15,9 @@ let availabilityMacros: [SwiftSetting] = [
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.3:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
),
|
||||
]
|
||||
|
||||
let package = Package(
|
||||
|
||||
@@ -0,0 +1,139 @@
|
||||
# FlatMapLatest
|
||||
|
||||
* Author(s): [Peter Friese](https://github.com/peterfriese)
|
||||
|
||||
Transforms elements into asynchronous sequences, emitting elements from only the most recent inner sequence.
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)]
|
||||
|
||||
```swift
|
||||
let searchQuery = AsyncStream<String> { continuation in
|
||||
// User types into search field
|
||||
continuation.yield("swi")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("swift")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("swift async")
|
||||
continuation.finish()
|
||||
}
|
||||
|
||||
let searchResults = searchQuery.flatMapLatest { query in
|
||||
performSearch(query) // Returns AsyncSequence<SearchResult>
|
||||
}
|
||||
|
||||
for try await result in searchResults {
|
||||
print(result) // Only shows results from "swift async"
|
||||
}
|
||||
```
|
||||
|
||||
## Introduction
|
||||
|
||||
When transforming elements of an asynchronous sequence into new asynchronous sequences, you often want to abandon previous sequences when new data arrives. This is particularly useful for scenarios like search-as-you-type, where each keystroke triggers a new search request and you only care about results from the most recent query.
|
||||
|
||||
The `flatMapLatest` operator solves this by cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The `flatMapLatest` algorithm transforms each element from the base `AsyncSequence` into a new inner `AsyncSequence` using the provided `transform` closure. When a new element is produced by the base sequence, iteration on the current inner sequence is cancelled, and iteration begins on the newly created sequence.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> AsyncFlatMapLatestSequence<Self, T>
|
||||
}
|
||||
```
|
||||
|
||||
This creates a concise way to express switching behavior:
|
||||
|
||||
```swift
|
||||
userInput.flatMapLatest { input in
|
||||
fetchDataFromNetwork(input)
|
||||
}
|
||||
```
|
||||
|
||||
In this case, each new user input cancels any ongoing network request and starts a fresh one, ensuring only the latest data is delivered.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm emits elements from the inner sequences. It throws when either the base type or any inner sequence throws.
|
||||
|
||||
```swift
|
||||
public struct AsyncFlatMapLatestSequence<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: AsyncSequence, Sendable
|
||||
where Base.Element: Sendable, Inner.Element: Sendable {
|
||||
public typealias Element = Inner.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
The implementation uses a state machine to ensure thread-safe operation and generation tracking to prevent stale values from cancelled sequences.
|
||||
|
||||
### Behavior
|
||||
|
||||
- **Switching**: When a new element arrives from the base sequence, the current inner sequence is cancelled immediately
|
||||
- **Completion**: The sequence completes when the base sequence finishes and the final inner sequence completes
|
||||
- **Error Handling**: Errors from either the base or inner sequences are propagated immediately
|
||||
- **Cancellation**: Cancelling iteration cancels both the base and current inner sequence
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Search as You Type
|
||||
|
||||
```swift
|
||||
let searchField = AsyncStream<String> { continuation in
|
||||
// Emit search queries as user types
|
||||
continuation.yield("s")
|
||||
continuation.yield("sw")
|
||||
continuation.yield("swift")
|
||||
}
|
||||
|
||||
let results = searchField.flatMapLatest { query in
|
||||
searchAPI(for: query)
|
||||
}
|
||||
```
|
||||
|
||||
Only the results for "swift" will be emitted, as earlier queries are cancelled.
|
||||
|
||||
### Location-Based Data
|
||||
|
||||
```swift
|
||||
let locationUpdates = CLLocationManager.shared.locationUpdates
|
||||
|
||||
let nearbyPlaces = locationUpdates.flatMapLatest { location in
|
||||
fetchNearbyPlaces(at: location)
|
||||
}
|
||||
```
|
||||
|
||||
Each location update triggers a new search, cancelling any ongoing requests for previous locations.
|
||||
|
||||
### Dynamic Configuration
|
||||
|
||||
```swift
|
||||
let settings = userSettingsStream
|
||||
|
||||
let data = settings.flatMapLatest { config in
|
||||
loadData(with: config)
|
||||
}
|
||||
```
|
||||
|
||||
When settings change, data loading is restarted with the new configuration.
|
||||
|
||||
## Comparison with Other Operators
|
||||
|
||||
**`map`**: Transforms elements synchronously without producing sequences.
|
||||
|
||||
**`flatMap`** (if it existed): Would emit elements from all inner sequences concurrently, not cancelling previous ones.
|
||||
|
||||
**`switchToLatest`** (Combine): Equivalent operator in Combine framework - `flatMapLatest` is the `AsyncSequence` equivalent.
|
||||
|
||||
## Comparison with Other Libraries
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of switchMap](https://reactivex.io/documentation/operators/flatmap.html) which performs the same operation for Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which flattens a publisher of publishers by subscribing to the most recent one.
|
||||
@@ -0,0 +1,89 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2025 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.3, *)
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
/// Transforms elements into new asynchronous sequences, emitting elements
|
||||
/// from the most recent inner sequence.
|
||||
///
|
||||
/// When a new element is emitted by this sequence, the `transform`
|
||||
/// is called to produce a new inner sequence. Iteration on the
|
||||
/// previous inner sequence is cancelled, and iteration begins
|
||||
/// on the new one.
|
||||
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable
|
||||
where T.Failure == Failure, T.Element: Sendable, Element: Sendable {
|
||||
return AsyncFlatMapLatestSequence(self, transform: transform)
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, Failure> & Sendable
|
||||
where T.Failure == Never, T.Element: Sendable, Element: Sendable {
|
||||
return AsyncFlatMapLatestSequence(self) {
|
||||
transform($0).mapError { _ -> Failure in
|
||||
fatalError()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable
|
||||
where Failure == Never, T.Element: Sendable, Element: Sendable {
|
||||
return AsyncFlatMapLatestSequence(
|
||||
self.mapError { _ -> T.Failure in
|
||||
fatalError()
|
||||
},
|
||||
transform: transform
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.3, *)
|
||||
struct AsyncFlatMapLatestSequence<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: AsyncSequence,
|
||||
Sendable
|
||||
where Base.Element: Sendable, Inner.Element: Sendable, Base.Failure == Inner.Failure {
|
||||
typealias Element = Inner.Element
|
||||
typealias Failure = Inner.Failure
|
||||
|
||||
let base: Base
|
||||
let transform: @Sendable (Base.Element) -> Inner
|
||||
|
||||
init(_ base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base: base, transform: transform)
|
||||
}
|
||||
|
||||
struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
let storage: FlatMapLatestStorage<Base, Inner>
|
||||
|
||||
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
|
||||
self.storage = FlatMapLatestStorage(base: base, transform: transform)
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
return try await storage.next(isolation: nil)
|
||||
}
|
||||
|
||||
func next(isolation: isolated (any Actor)? = #isolation) async throws(Failure) -> Element? {
|
||||
return try await storage.next(isolation: isolation)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,531 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2025 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import DequeModule
|
||||
|
||||
@available(AsyncAlgorithms 1.3, *)
|
||||
struct FlatMapLatestStateMachine<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>
|
||||
where Base.Element: Sendable, Inner.Element: Sendable {
|
||||
typealias Element = Inner.Element
|
||||
|
||||
private enum State {
|
||||
case initial(Base)
|
||||
case running(
|
||||
outerTask: Task<Void, Never>?,
|
||||
outerContinuation: UnsafeContinuation<Void, Error>?,
|
||||
innerTask: Task<Void, Never>?,
|
||||
innerContinuation: UnsafeContinuation<Void, Error>?,
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>?,
|
||||
buffer: Deque<Result<Element, Error>>,
|
||||
generation: Int,
|
||||
outerFinished: Bool
|
||||
)
|
||||
case finished
|
||||
}
|
||||
|
||||
private var state: State
|
||||
private let transform: @Sendable (Base.Element) -> Inner
|
||||
|
||||
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
|
||||
self.state = .initial(base)
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
enum NextAction {
|
||||
case returnElement(Element)
|
||||
case returnNil
|
||||
case throwError(Error)
|
||||
case startOuterTask(Base)
|
||||
case suspend
|
||||
}
|
||||
|
||||
enum Action {
|
||||
case startInnerTask(
|
||||
Inner,
|
||||
generation: Int,
|
||||
previousTask: Task<Void, Never>?,
|
||||
previousContinuation: UnsafeContinuation<Void, Error>?
|
||||
)
|
||||
case cancelInnerTask(Task<Void, Never>, UnsafeContinuation<Void, Error>?)
|
||||
case resumeDownstream(UnsafeContinuation<Element?, Error>, Result<Element?, Error>)
|
||||
case resumeOuterContinuation(UnsafeContinuation<Void, Error>)
|
||||
case cancelTasks(
|
||||
Task<Void, Never>?,
|
||||
Task<Void, Never>?,
|
||||
UnsafeContinuation<Void, Error>?,
|
||||
UnsafeContinuation<Void, Error>?
|
||||
)
|
||||
case none
|
||||
}
|
||||
|
||||
enum SuspendAction {
|
||||
case resumeOuterContinuation(UnsafeContinuation<Void, Error>)
|
||||
case resumeInnerContinuation(UnsafeContinuation<Void, Error>)
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func next() -> NextAction {
|
||||
switch state {
|
||||
case .initial(let base):
|
||||
return .startOuterTask(base)
|
||||
|
||||
case .running(
|
||||
let outerTask,
|
||||
let outerCont,
|
||||
let innerTask,
|
||||
let innerCont,
|
||||
let downstreamCont,
|
||||
var buffer,
|
||||
let generation,
|
||||
let outerFinished
|
||||
):
|
||||
if let result = buffer.popFirst() {
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
switch result {
|
||||
case .success(let element): return .returnElement(element)
|
||||
case .failure(let error): return .throwError(error)
|
||||
}
|
||||
} else if outerFinished && innerTask == nil {
|
||||
state = .finished
|
||||
return .returnNil
|
||||
} else {
|
||||
return .suspend
|
||||
}
|
||||
|
||||
case .finished:
|
||||
return .returnNil
|
||||
}
|
||||
}
|
||||
|
||||
mutating func next(for continuation: UnsafeContinuation<Element?, Error>) -> SuspendAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
fatalError("Should be started")
|
||||
|
||||
case .running(
|
||||
let outerTask,
|
||||
let outerCont,
|
||||
let innerTask,
|
||||
let innerCont,
|
||||
let downstreamCont,
|
||||
let buffer,
|
||||
let generation,
|
||||
let outerFinished
|
||||
):
|
||||
precondition(downstreamCont == nil, "Already have downstream continuation")
|
||||
precondition(buffer.isEmpty, "Buffer should be empty if suspending")
|
||||
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: continuation,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
|
||||
// Resume waiting tasks to produce elements for downstream demand
|
||||
if let innerCont = innerCont {
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: continuation,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .resumeInnerContinuation(innerCont)
|
||||
}
|
||||
|
||||
if let outerCont = outerCont {
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: nil,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: continuation,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .resumeOuterContinuation(outerCont)
|
||||
}
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
continuation.resume(returning: nil)
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func outerTaskStarted(_ task: Task<Void, Never>) {
|
||||
switch state {
|
||||
case .initial:
|
||||
// Transition to running
|
||||
state = .running(
|
||||
outerTask: task,
|
||||
outerContinuation: nil,
|
||||
innerTask: nil,
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: nil,
|
||||
buffer: Deque(),
|
||||
generation: 0,
|
||||
outerFinished: false
|
||||
)
|
||||
default:
|
||||
fatalError("Invalid state transition")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func outerTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> SuspendAction {
|
||||
switch state {
|
||||
case .running(
|
||||
let outerTask,
|
||||
_,
|
||||
let innerTask,
|
||||
let innerCont,
|
||||
let downstreamCont,
|
||||
let buffer,
|
||||
let generation,
|
||||
let outerFinished
|
||||
):
|
||||
// If we have downstream demand, resume immediately
|
||||
if downstreamCont != nil {
|
||||
return .resumeOuterContinuation(continuation)
|
||||
}
|
||||
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: continuation,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
continuation.resume(throwing: CancellationError())
|
||||
return .none
|
||||
|
||||
default:
|
||||
fatalError("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func outerElementProduced(_ element: Base.Element) -> Action {
|
||||
switch state {
|
||||
case .running(
|
||||
let outerTask,
|
||||
_,
|
||||
let innerTask,
|
||||
let innerCont,
|
||||
let downstreamCont,
|
||||
let buffer,
|
||||
var generation,
|
||||
let outerFinished
|
||||
):
|
||||
// New element from outer -> Cancel previous inner, start new inner
|
||||
let newInner = transform(element)
|
||||
generation += 1
|
||||
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: nil, // We just consumed the continuation by producing
|
||||
innerTask: nil, // Will be set by innerTaskStarted
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
|
||||
return .startInnerTask(newInner, generation: generation, previousTask: innerTask, previousContinuation: innerCont)
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
|
||||
default:
|
||||
fatalError("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func innerTaskStarted(_ task: Task<Void, Never>, generation: Int) {
|
||||
switch state {
|
||||
case .running(
|
||||
let outerTask,
|
||||
let outerCont,
|
||||
_,
|
||||
let innerCont,
|
||||
let downstreamCont,
|
||||
let buffer,
|
||||
let currentGen,
|
||||
let outerFinished
|
||||
):
|
||||
if generation != currentGen {
|
||||
// Stale task from previous generation, ignore it
|
||||
return
|
||||
}
|
||||
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: task,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
|
||||
default:
|
||||
// If finished, we don't care
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
mutating func innerTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>, generation: Int) -> SuspendAction {
|
||||
switch state {
|
||||
case .running(
|
||||
let outerTask,
|
||||
let outerCont,
|
||||
let innerTask,
|
||||
_,
|
||||
let downstreamCont,
|
||||
let buffer,
|
||||
let currentGen,
|
||||
let outerFinished
|
||||
):
|
||||
if generation != currentGen {
|
||||
// Stale generation
|
||||
continuation.resume(throwing: CancellationError())
|
||||
return .none
|
||||
}
|
||||
|
||||
if downstreamCont != nil {
|
||||
return .resumeInnerContinuation(continuation)
|
||||
}
|
||||
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: continuation,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
continuation.resume(throwing: CancellationError())
|
||||
return .none
|
||||
|
||||
default:
|
||||
fatalError("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func innerElementProduced(_ element: Element, generation: Int) -> Action {
|
||||
switch state {
|
||||
case .running(
|
||||
let outerTask,
|
||||
let outerCont,
|
||||
let innerTask,
|
||||
_,
|
||||
let downstreamCont,
|
||||
var buffer,
|
||||
let currentGen,
|
||||
let outerFinished
|
||||
):
|
||||
if generation != currentGen {
|
||||
return .none
|
||||
}
|
||||
|
||||
guard let downstreamCont = downstreamCont else {
|
||||
buffer.append(.success(element))
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: nil,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .none
|
||||
}
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: nil, // Consumed
|
||||
downstreamContinuation: nil,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .resumeDownstream(downstreamCont, .success(element))
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
|
||||
default:
|
||||
fatalError("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func innerFinished(generation: Int) -> Action {
|
||||
switch state {
|
||||
case .running(let outerTask, let outerCont, _, _, let downstreamCont, let buffer, let currentGen, let outerFinished):
|
||||
if generation != currentGen {
|
||||
return .none
|
||||
}
|
||||
|
||||
// Inner finished.
|
||||
if outerFinished {
|
||||
// Both finished
|
||||
state = .finished
|
||||
if let downstreamCont = downstreamCont {
|
||||
return .resumeDownstream(downstreamCont, .success(nil))
|
||||
}
|
||||
} else {
|
||||
// Just this inner finished. Wait for next outer.
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: outerCont,
|
||||
innerTask: nil,
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
// Resume outer sequence if downstream is waiting for more elements
|
||||
if downstreamCont != nil, let outerCont = outerCont {
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: nil, // Consumed
|
||||
innerTask: nil,
|
||||
innerContinuation: nil,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: currentGen,
|
||||
outerFinished: outerFinished
|
||||
)
|
||||
return .resumeOuterContinuation(outerCont)
|
||||
}
|
||||
}
|
||||
return .none
|
||||
|
||||
default:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func innerThrew(_ error: Error, generation: Int) -> Action {
|
||||
switch state {
|
||||
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, let currentGen, _):
|
||||
if generation != currentGen {
|
||||
return .none
|
||||
}
|
||||
|
||||
state = .finished
|
||||
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
|
||||
|
||||
guard let downstreamCont = downstreamCont else {
|
||||
return action
|
||||
}
|
||||
return .resumeDownstream(downstreamCont, .failure(error))
|
||||
|
||||
default:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func outerFinished() -> Action {
|
||||
switch state {
|
||||
case .running(let outerTask, _, let innerTask, let innerCont, let downstreamCont, let buffer, let generation, _):
|
||||
if innerTask == nil && buffer.isEmpty {
|
||||
state = .finished
|
||||
if let downstreamCont = downstreamCont {
|
||||
return .resumeDownstream(downstreamCont, .success(nil))
|
||||
}
|
||||
} else {
|
||||
state = .running(
|
||||
outerTask: outerTask,
|
||||
outerContinuation: nil,
|
||||
innerTask: innerTask,
|
||||
innerContinuation: innerCont,
|
||||
downstreamContinuation: downstreamCont,
|
||||
buffer: buffer,
|
||||
generation: generation,
|
||||
outerFinished: true
|
||||
)
|
||||
}
|
||||
return .none
|
||||
|
||||
default:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func outerThrew(_ error: Error) -> Action {
|
||||
switch state {
|
||||
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, _, _):
|
||||
state = .finished
|
||||
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
|
||||
|
||||
guard let downstreamCont = downstreamCont else {
|
||||
return action
|
||||
}
|
||||
return .resumeDownstream(downstreamCont, .failure(error))
|
||||
|
||||
default:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func cancelled() -> Action {
|
||||
switch state {
|
||||
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, _, _):
|
||||
state = .finished
|
||||
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
|
||||
|
||||
if let downstreamCont = downstreamCont {
|
||||
return .resumeDownstream(downstreamCont, .success(nil))
|
||||
}
|
||||
return action
|
||||
|
||||
default:
|
||||
state = .finished
|
||||
return .none
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,199 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2025 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.3, *)
|
||||
final class FlatMapLatestStorage<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: @unchecked Sendable
|
||||
where Base.Element: Sendable, Inner.Element: Sendable {
|
||||
typealias Element = Inner.Element
|
||||
|
||||
private let lock = Lock.allocate()
|
||||
private var stateMachine: FlatMapLatestStateMachine<Base, Inner>
|
||||
|
||||
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
|
||||
self.stateMachine = FlatMapLatestStateMachine(base: base, transform: transform)
|
||||
}
|
||||
|
||||
deinit {
|
||||
lock.deinitialize()
|
||||
}
|
||||
|
||||
func next(isolation: isolated (any Actor)? = #isolation) async throws(Inner.Failure) -> Inner.Element? {
|
||||
do {
|
||||
return try await withTaskCancellationHandler {
|
||||
lock.lock()
|
||||
let action = stateMachine.next()
|
||||
|
||||
switch action {
|
||||
case .returnElement(let element):
|
||||
lock.unlock()
|
||||
return element
|
||||
|
||||
case .returnNil:
|
||||
lock.unlock()
|
||||
return nil
|
||||
|
||||
case .throwError(let error):
|
||||
lock.unlock()
|
||||
throw error
|
||||
|
||||
case .startOuterTask(let base):
|
||||
// We need to start the outer task and then suspend
|
||||
startOuterTask(base)
|
||||
|
||||
return try await suspend()
|
||||
|
||||
case .suspend:
|
||||
lock.unlock()
|
||||
return try await suspend()
|
||||
}
|
||||
} onCancel: {
|
||||
let action = lock.withLock { stateMachine.cancelled() }
|
||||
handleAction(action)
|
||||
}
|
||||
} catch {
|
||||
throw error as! Inner.Failure
|
||||
}
|
||||
}
|
||||
|
||||
private func suspend() async throws -> Element? {
|
||||
return try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = lock.withLock { stateMachine.next(for: continuation) }
|
||||
|
||||
switch action {
|
||||
case .resumeOuterContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .resumeInnerContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func startOuterTask(_ base: Base) {
|
||||
let task = Task {
|
||||
var iterator = base.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
// Create a continuation to wait for demand
|
||||
do {
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = lock.withLock { stateMachine.outerTaskSuspended(continuation) }
|
||||
|
||||
switch action {
|
||||
case .resumeOuterContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .resumeInnerContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Cancellation or other error during suspension
|
||||
let action = lock.withLock { stateMachine.outerThrew(error) }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
|
||||
do {
|
||||
guard let element = try await iterator.next() else {
|
||||
let action = lock.withLock { stateMachine.outerFinished() }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
let action = lock.withLock { stateMachine.outerElementProduced(element) }
|
||||
handleAction(action)
|
||||
} catch {
|
||||
let action = lock.withLock { stateMachine.outerThrew(error) }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
stateMachine.outerTaskStarted(task)
|
||||
lock.unlock()
|
||||
}
|
||||
|
||||
private func startInnerTask(_ inner: Inner, generation: Int) {
|
||||
let task = Task {
|
||||
var iterator = inner.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
// Wait for demand
|
||||
do {
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = lock.withLock { stateMachine.innerTaskSuspended(continuation, generation: generation) }
|
||||
|
||||
switch action {
|
||||
case .resumeInnerContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .resumeOuterContinuation(let continuation):
|
||||
continuation.resume()
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Cancellation
|
||||
let action = lock.withLock { stateMachine.innerThrew(error, generation: generation) }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
|
||||
do {
|
||||
guard let element = try await iterator.next() else {
|
||||
let action = lock.withLock { stateMachine.innerFinished(generation: generation) }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
let action = lock.withLock { stateMachine.innerElementProduced(element, generation: generation) }
|
||||
handleAction(action)
|
||||
} catch {
|
||||
let action = lock.withLock { stateMachine.innerThrew(error, generation: generation) }
|
||||
handleAction(action)
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
stateMachine.innerTaskStarted(task, generation: generation)
|
||||
}
|
||||
|
||||
private func handleAction(_ action: FlatMapLatestStateMachine<Base, Inner>.Action) {
|
||||
switch action {
|
||||
case .startInnerTask(let inner, let generation, let previousTask, let previousCont):
|
||||
if let previousTask = previousTask {
|
||||
previousTask.cancel()
|
||||
previousCont?.resume(throwing: CancellationError())
|
||||
}
|
||||
startInnerTask(inner, generation: generation)
|
||||
|
||||
case .cancelInnerTask(let task, let continuation):
|
||||
task.cancel()
|
||||
continuation?.resume(throwing: CancellationError())
|
||||
|
||||
case .resumeDownstream(let continuation, let result):
|
||||
continuation.resume(with: result)
|
||||
|
||||
case .resumeOuterContinuation(let continuation):
|
||||
continuation.resume()
|
||||
|
||||
case .cancelTasks(let outer, let inner, let outerCont, let innerCont):
|
||||
outer?.cancel()
|
||||
inner?.cancel()
|
||||
outerCont?.resume(throwing: CancellationError())
|
||||
innerCont?.resume(throwing: CancellationError())
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
+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,240 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import XCTest
|
||||
import AsyncAlgorithms
|
||||
|
||||
@available(macOS 15.0, *)
|
||||
final class TestFlatMapLatest: XCTestCase {
|
||||
|
||||
func test_simple_sequence() async throws {
|
||||
let source = [1, 2, 3].async
|
||||
let transformed = source.flatMapLatest { intValue in
|
||||
return [intValue, intValue * 10].async
|
||||
}
|
||||
|
||||
var results: [Int] = []
|
||||
for try await element in transformed {
|
||||
results.append(element)
|
||||
}
|
||||
|
||||
// With synchronous emission, we expect only the last inner sequence [3, 30]
|
||||
// However, depending on timing, we might see more intermediate values
|
||||
XCTAssertTrue(results.contains(3), "Should contain 3")
|
||||
XCTAssertTrue(results.contains(30), "Should contain 30")
|
||||
// We should also verify it ends with the last sequence
|
||||
XCTAssertEqual(results.suffix(2), [3, 30], "Should end with [3, 30]")
|
||||
}
|
||||
|
||||
func test_interleaving_race_condition() async throws {
|
||||
// This test simulates a scenario where the inner sequence is slow.
|
||||
// In a naive implementation (without generation tracking), the inner task for '1'
|
||||
// might wake up and yield AFTER '2' has already started, causing interleaving.
|
||||
|
||||
let source = [1, 2, 3].async
|
||||
let transformed = source.flatMapLatest { intValue -> AsyncStream<Int> in
|
||||
AsyncStream { continuation in
|
||||
Task {
|
||||
// Yield the value immediately
|
||||
continuation.yield(intValue)
|
||||
|
||||
// Sleep for a bit to allow the outer sequence to move on
|
||||
try? await Task.sleep(nanoseconds: 10_000_000) // 10ms
|
||||
|
||||
// Yield a second value - this should be ignored if a new outer value has arrived
|
||||
continuation.yield(intValue * 10)
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// We expect:
|
||||
// 1 arrives -> starts inner(1) -> yields 1 -> sleeps
|
||||
// 2 arrives -> cancels inner(1) -> starts inner(2) -> yields 2 -> sleeps
|
||||
// 3 arrives -> cancels inner(2) -> starts inner(3) -> yields 3 -> sleeps
|
||||
// inner(3) finishes sleep -> yields 30
|
||||
//
|
||||
// Ideally, we should NOT see 10 or 20.
|
||||
// However, without strict synchronization, we might see them.
|
||||
// The strict expectation for flatMapLatest is that once a new value arrives,
|
||||
// the old one produces NO MORE values.
|
||||
|
||||
// Note: This test is probabilistic in the naive implementation.
|
||||
// It might pass or fail depending on scheduling.
|
||||
// But with a correct implementation, it should ALWAYS pass.
|
||||
|
||||
// We'll collect all results to see what happened
|
||||
var results: [Int] = []
|
||||
|
||||
for try await element in transformed {
|
||||
results.append(element)
|
||||
}
|
||||
|
||||
// In the naive implementation, we might get [1, 2, 3, 10, 20, 30] or similar.
|
||||
// We want strictly [3, 30] (or [1, 2, 3, 30] depending on how fast the outer sequence is consumed vs produced)
|
||||
// Actually, if the outer sequence is consumed fast, we might see intermediate "first" values (1, 2).
|
||||
// But we should NEVER see "second" values (10, 20) from cancelled sequences.
|
||||
|
||||
// Let's relax the check to: "Must not contain 10 or 20"
|
||||
XCTAssertFalse(results.contains(10), "Should not contain 10 (from cancelled sequence 1)")
|
||||
XCTAssertFalse(results.contains(20), "Should not contain 20 (from cancelled sequence 2)")
|
||||
XCTAssertTrue(results.contains(30), "Should contain 30 (from final sequence)")
|
||||
}
|
||||
func test_outer_throwing() async throws {
|
||||
let source = AsyncThrowingStream<Int, Error> { continuation in
|
||||
Task {
|
||||
for value in [1, 2, 3] {
|
||||
if value == 2 {
|
||||
continuation.finish(throwing: FlatMapLatestFailure())
|
||||
return
|
||||
}
|
||||
continuation.yield(value)
|
||||
try? await Task.sleep(nanoseconds: 5_000_000) // 5ms delay
|
||||
}
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
|
||||
let transformed = source.flatMapLatest { intValue in
|
||||
return [intValue, intValue * 10].async
|
||||
}
|
||||
|
||||
do {
|
||||
for try await _ in transformed {}
|
||||
XCTFail("Should have thrown")
|
||||
} catch {
|
||||
XCTAssertEqual(error as? FlatMapLatestFailure, FlatMapLatestFailure())
|
||||
}
|
||||
}
|
||||
|
||||
func test_inner_throwing() async throws {
|
||||
let source = AsyncStream<Int> { continuation in
|
||||
Task {
|
||||
for value in [1, 2, 3] {
|
||||
continuation.yield(value)
|
||||
try? await Task.sleep(nanoseconds: 5_000_000) // 5ms delay between outer values
|
||||
}
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
|
||||
let transformed = source.flatMapLatest { intValue in
|
||||
return [intValue].async.map { try $0.throwIf(2) }
|
||||
}
|
||||
|
||||
do {
|
||||
for try await _ in transformed {}
|
||||
XCTFail("Should have thrown")
|
||||
} catch {
|
||||
XCTAssertEqual(error as? FlatMapLatestFailure, FlatMapLatestFailure())
|
||||
}
|
||||
}
|
||||
|
||||
func test_cancellation() async throws {
|
||||
let source = [1, 2, 3].async
|
||||
let transformed = source.flatMapLatest { intValue in
|
||||
return [intValue].async
|
||||
}
|
||||
|
||||
let task = Task {
|
||||
for try await _ in transformed {}
|
||||
}
|
||||
|
||||
task.cancel()
|
||||
|
||||
do {
|
||||
try await task.value
|
||||
} catch is CancellationError {
|
||||
// Expected
|
||||
} catch {
|
||||
XCTFail("Unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
|
||||
func test_empty_outer() async throws {
|
||||
let source = [].async.map { $0 as Int }
|
||||
let transformed = source.flatMapLatest { intValue in
|
||||
return [intValue].async
|
||||
}
|
||||
|
||||
var count = 0
|
||||
for try await _ in transformed {
|
||||
count += 1
|
||||
}
|
||||
XCTAssertEqual(count, 0)
|
||||
}
|
||||
|
||||
func test_empty_inner() async throws {
|
||||
let source = [1, 2, 3].async
|
||||
let transformed = source.flatMapLatest { _ in
|
||||
return [].async.map { $0 as Int }
|
||||
}
|
||||
|
||||
var count = 0
|
||||
for try await _ in transformed {
|
||||
count += 1
|
||||
}
|
||||
XCTAssertEqual(count, 0)
|
||||
}
|
||||
func test_concurrency_crash_repro() async throws {
|
||||
// This test simulates the exact race condition where an inner stream producer
|
||||
// mimics the behavior of Firestore/Combine publisher wrappers that might
|
||||
// yield values or finish asynchronously relative to cancellation.
|
||||
|
||||
@Sendable func innerStream(for user: String) -> AsyncThrowingStream<Int, Error> {
|
||||
return AsyncThrowingStream { continuation in
|
||||
let task = Task {
|
||||
for i in 0...100 {
|
||||
// Artificial delay to allow overlap/interleaving
|
||||
// This is critical to hit the race condition window
|
||||
try await Task.sleep(nanoseconds: 1_000_000) // 1ms
|
||||
|
||||
continuation.yield(i)
|
||||
}
|
||||
continuation.finish()
|
||||
}
|
||||
|
||||
continuation.onTermination = { @Sendable termination in
|
||||
task.cancel()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let authStream = AsyncStream<String> { continuation in
|
||||
continuation.yield("A")
|
||||
Task {
|
||||
// Yielding again triggers the switch (and cancellation of the previous inner stream)
|
||||
try? await Task.sleep(nanoseconds: 10_000_000) // 10ms
|
||||
continuation.yield("B")
|
||||
try? await Task.sleep(nanoseconds: 10_000_000)
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
|
||||
let combined = authStream.flatMapLatest { user in
|
||||
innerStream(for: user)
|
||||
}
|
||||
|
||||
// Determine success by running without crashing
|
||||
for try await _ in combined {}
|
||||
}
|
||||
}
|
||||
|
||||
private struct FlatMapLatestFailure: Error, Equatable {}
|
||||
|
||||
extension Int {
|
||||
fileprivate func throwIf(_ value: Int) throws -> Int {
|
||||
if self == value {
|
||||
throw FlatMapLatestFailure()
|
||||
}
|
||||
return self
|
||||
}
|
||||
}
|
||||
@@ -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