Compare commits

...
25 Commits
Author SHA1 Message Date
Franz Busch 3da39bbc4e [AsyncStreaming] Redesign AsyncReader.collect to take a target container (#436)
Replace `collect(upTo:body:)` with three target-based overloads: `collect(into:)`, `collect(exactlyInto:)`, and `collect(into:maximumSize:)`. Add `AsyncReaderInsufficientElementsError` for the exact-match shortfall case.
2026-06-25 10:14:54 +02:00
kSibalic c8a9349238 [AsyncStreaming] Exclude the proposal file from the target (#434)
- NNNN-async-streaming.md is intentionally kept alongside the AsyncStreaming
implementation
- Exclude it from the target in Package.swift so SwiftPM no
longer reports it as an unhandled file (#433)
2026-06-23 12:41:18 +02:00
Franz Busch e81438119c [AsyncStreaming] Skip empty buffers in AsyncReader.forEachBuffer (#435)
When a reader signals end-of-stream with an empty buffer, body was still invoked with that empty buffer. Skip the body call when the buffer is empty.
2026-06-23 10:48:22 +02:00
David SmithandFranz Busch 8ee3d2be19 "[AsyncStreaming] Introduce a MultiProducerSingleConsumerChannel and a duplex" + a build fix (#428)
* [AsyncStreaming] Introduce a `MultiProducerSingleConsumerChannel` and a duplex

* Add tests

* Fix UnstableAsyncStreaming test build

---------

Co-authored-by: Franz Busch <f.busch@apple.com>
2026-06-05 17:15:19 -07:00
Franz Busch 8e16632775 [AsyncStreaming] Add bidirectional adapters for the async writers (#424)
* [AsyncStreaming] Add support for final elements

## Motivation

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

## Modification

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

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

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

## Result

The four protocols can back HTTP body, gRPC streaming, and similar shapes without giving up the fused close. Default `Void` keeps simple conformers unchanged; `Never` marks infinite streams. Custom and `~Copyable` payloads work end to end.

* [AsyncStreaming] Add bidirectional adapters for the async writers

## Motivation

It is quite common to have one type of writer and wanting to adapt to the other type of writer.

## Modifications

This PR adds two adapters into either direction between the writers to make conversion seamless.

## Result

It is easy to go from one type of writer to the other type.
2026-06-02 08:16:42 +02:00
Franz Busch f4177dcc17 [AsyncStreaming] Add support for final elements (#422)
## Motivation

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

## Modification

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

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

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

## Result

The four protocols can back HTTP body, gRPC streaming, and similar shapes without giving up the fused close. Default `Void` keeps simple conformers unchanged; `Never` marks infinite streams. Custom and `~Copyable` payloads work end to end.
2026-06-02 08:16:01 +02:00
Aditya Singh 268087d1de Correct reductions docs: exclusive variants do not emit the initial value (#423)
The doc comments for the exclusive reductions overloads stated that the
returned sequence is "the initial value followed by the reduced elements".
That does not match the behavior: the iterator pulls a base element before
emitting anything, so the first emitted element is the result of combining
the initial value with the first base element, and the initial value is
never emitted. For an empty base sequence the result is empty rather than a
single-element sequence containing the initial value.

This is the behavior the existing tests already pin down, and changing it
would be source-breaking, so this corrects the documentation to match.
Updates all four exclusive overloads (throwing and non-throwing, value and
into:) and adds empty-base tests covering the now-documented edge case.

The inclusive reductions and the DocC Reductions guide already describe the
actual behavior and are left unchanged.
2026-05-27 15:29:38 +02:00
Franz Busch 3bd2de010e Add new pipe convenience methods for the async readers (#420)
## Motivation

Often developers want to pipe the contents of an async reader into a writer. This is a common scenario in asynchronous streaming APIs. Readers are modeling sources of data where writers are modeling sinks. As an example imagine reading from a network socket and writing the contents into a file. Importantly, the entire operation needs to uphold backpressure.

## Modifications

This PR adds 2 new `pipe` methods to each reader one for each writer type. Depending on the buffer ownership those methods will the pipe operation is copy free, requires a copy or even requires an intermediate allocation for copying. The method parameter labels are trying to express what the operation does.

## Result

It is very easy for developers now to move elements from readers into writers.
2026-05-20 09:49:59 +02:00
Guoye Zhang b2beeb25b4 Change all AsyncStreaming availability from 26.2 to SwiftStdlib 5.0 (#421)
* Change all AsyncStreaming availability from 26.2 to SwiftStdlib 5.0

* Spelling
2026-05-19 10:31:31 +02:00
Franz Busch d0b4a06d0f Rework AsyncStreaming protocols to use generic RangeReplaceableContainer buffers (#417)
Replace `InputSpan`/`OutputSpan` with generic `Buffer` associated types constrained to `RangeReplaceableContainer` across all four streaming protocols. This sidesteps the limitation that `OutputSpan` (and other `~Escapable` types) cannot be used in async contexts today, while still allowing conforming types to choose a buffer representation optimized for their use case (e.g. `UniqueArray` for heap-backed storage, or a future stack-allocated container for embedded).

Switch callee-owned protocols from `consuming` to `inout` closure semantics, rename `forEachChunk` to `forEachBuffer`, and move `forEach`/`collect` to future directions in the proposal.

Adds test coverage for `AsyncWriter`, `CallerAsyncReader`, and `EitherError`. Updates all documentation to reflect the new API surface.
2026-05-14 23:42:25 +02:00
Franz Busch 6a92272e13 Fix a few new region isolation errors in nightly-main (#419)
* Rework `AsyncStreaming` protocols to use generic `RangeReplaceableContainer` buffers

Replace `InputSpan`/`OutputSpan` with generic `Buffer` associated types constrained to `RangeReplaceableContainer` across all four streaming protocols. This sidesteps the limitation that `OutputSpan` (and other `~Escapable` types) cannot be used in async contexts today, while still allowing conforming types to choose a buffer representation optimized for their use case (e.g. `UniqueArray` for heap-backed storage, or a future stack-allocated container for embedded).

Switch callee-owned protocols from `consuming` to `inout` closure semantics, rename `forEachChunk` to `forEachBuffer`, and move `forEach`/`collect` to future directions in the proposal.

Adds test coverage for `AsyncWriter`, `CallerAsyncReader`, and `EitherError`. Updates all documentation to reflect the new API surface.

* Fix a few new region isolation errors in `nightly-main`

Region isolation got smarter and started diagnosing more potential data races. This PR addresses the new errors. Importantly I had to introduce one `@unchecked Sendable` conformance since we can't yet use `UniqueDeque`
2026-05-14 23:22:27 +02:00
Franz Busch 6783e0f2d2 Adds a new AsyncReader.forEach method (#416)
It is often needed to iterate over all elements of a reader. This PR provides two convenience `forEach` methods to make iteration easier.
2026-05-13 13:20:41 +02:00
Franz Busch d14a83b31f Adds a new AsyncReader.collect method (#415)
Often developers want to collect elements from a reader up to a certain limit. This PR provides a few convenience methods for this.
2026-05-12 23:07:29 +02:00
Franz Busch 0a5f92d159 Expose the AsyncStreaming target as a product (#414) 2026-05-12 22:20:26 +02:00
Franz Busch be2467e0c0 Add new experimental _AsyncStreaming module (#400)
This PR adds an experimental module for asynchronous streaming interfaces as a potential evolution to async sequence. These APIs are considered highly unstable and are mostly for experimentation purposes; hence, they are part of an underscored module and all APIs are hidden behind a trait. I expect significant changes to those APIs to offer more functionality such as gather scatter and more.
2026-05-11 14:58:21 +02:00
Philippe Hausler 9d349bcc32 Cleanup pass for flatMapLatest and housekeeping tasks around proposals (#403)
* rename the map error proposal to have a specific number

* rename the flatMapLatest proposal to have a specific numbering

* Update availability markers for flatmapLatest

* Cleanup formatting pass for FlatMapLatest

* Remove stray extra single quote

* Add a fallback for older versions of swift for the next method on flatMapLatest
2026-03-04 14:27:48 -08:00
5043186441 feat: Add AsyncSequence.flatMapLatest operator (#382)
* feat: Add initial naive implementation of flatMapLatest

This introduces a simplified version of the flatMapLatest operator for AsyncSequence, along with a basic unit test. Note that this implementation uses unstructured concurrency and may have race conditions regarding task cancellation.

* refactor: Implement robust flatMapLatest with generation tracking

- Replaces naive implementation with a thread-safe approach using ManagedCriticalState.
- Introduces generation tracking to prevent race conditions where cancelled inner sequences could yield stale values.
- Adds test_interleaving_race_condition to verify correctness under concurrent load.
- Ensures Swift 6 Sendable compliance.

* refactor: Implement high-performance State Machine for flatMapLatest

- Replaces AsyncThrowingStream implementation with a custom AsyncSequence, Storage, and StateMachine.
- Implements explicit state management using Lock for thread safety.
- Handles concurrency between outer and inner sequences robustly.
- Ensures correct cancellation propagation and error handling.
- Verified with test_interleaving_race_condition.

* refactor: Split flatMapLatest into separate files

- Moves AsyncFlatMapLatestSequence.swift to Sources/AsyncAlgorithms/FlatMapLatest/
- Extracts FlatMapLatestStateMachine and FlatMapLatestStorage into their own files.
- Aligns project structure with other complex operators like CombineLatest and Debounce.

* test: Add comprehensive tests for flatMapLatest

- Added test_outer_throwing to verify outer sequence error propagation
- Added test_inner_throwing to verify inner sequence error propagation
- Added test_cancellation to verify proper cancellation handling
- Added test_empty_outer to verify empty outer sequence handling
- Added test_empty_inner to verify empty inner sequence handling
- Fixed test_simple_sequence to be more robust against timing issues

* fix: Make test_outer_throwing stable

- Changed from synchronous map with throwIf to AsyncThrowingStream
- Added delay to ensure proper error propagation timing
- Fixes intermittent test failures

* refactor: Clean up verbose comments in FlatMapLatestStateMachine

- Removed LLM-style thinking comments
- Kept only essential, professional explanations
- No functional changes, all tests pass

* docs: Add comprehensive guide for flatMapLatest

- Added FlatMapLatest.md documentation guide
- Authored by Peter Friese
- Includes introduction, code samples, and use cases
- Covers search-as-you-type, location-based data, and dynamic config examples
- Compares with similar operators in ReactiveX and Combine

* docs: Add evolution proposal for flatMapLatest

- Created SAA-00nn proposal for flatMapLatest operator
- Includes motivation, detailed design, and examples
- Covers implementation strategy with state machine
- Compares with ReactiveX switchMap and Combine switchToLatest

* mapError - transforming failures (#366)

* Implement AsyncMapErrorSequence

* Update the proposal, implementation and tests with formatting, additional details and modifications for being able to push it to a review

* Foratting and preambles

* Update Copyright date for error sequence

Co-authored-by: Clive <clive819@users.noreply.github.com>

* Update copyright year for mapError tests

Co-authored-by: Clive <clive819@users.noreply.github.com>

* Update availablity and modify the mapError algorithm to be opaque

* Correct pre 6.0 build avail parameters

* Make the formatting of the algorithm accesor a bit more consistent

* Update the 5.8 package builder to define 1.2

* re-run formatter

---------

Co-authored-by: Clive <clive819@gmail.com>
Co-authored-by: Clive <clive819@users.noreply.github.com>

* Update the flatMapLatest proposal and implementation to a pitchable state

* Fix race condition in flatMapLatest and add regression test

* chore: Remove test_output.log and add it to .gitignore

---------

Co-authored-by: Philippe Hausler <phausler@apple.com>
Co-authored-by: Clive <clive819@gmail.com>
Co-authored-by: Clive <clive819@users.noreply.github.com>
2026-03-04 13:58:48 -08:00
Franz Busch 2971dd5d9f Fix a data race error with the internal Optional.takeSending (#399)
We added a little helper to move a non-Sendable type into an optional and take it out as sending so that it is disconnected. This was actually a data race hole which got fixed by the compiler so we need to use a proper disconnected abstractions.
2026-02-11 11:02:07 -08:00
Oleksii M. 103f5e5bea Fix swift tool version (#374) 2026-01-26 09:34:26 -08:00
Kenta Kubo b8006a9de0 Add support for FreeBSD (#375)
* Add partial support for FreeBSD

This change will allow `swift build` to succeed. However, SwiftPM support is still incomplete and does not yet allow adding `.freebsd` to `.when(platforms:)`, so `swift test` cannot be executed.

* Make `swift test` work on FreeBSD
2026-01-26 09:33:54 -08:00
Alessio NossaandPhilippe Hausler 2de50036f6 Fix unbuffered share deadlock (#387)
* Introduce test_share_with_no_buffering

* Update test_share_with_no_buffering implementation

* Check limit bigger than 0 in AsyncShareSequence iterate

* Revert "Check limit bigger than 0 in AsyncShareSequence iterate"

This reverts commit 3c9e1ab0ff.

* Check limit bigger than 0 in iterate in AsyncShareSequence

* Hand correct the lint failures in TestShare.swift

* An additional hand-edit lint fix for TestShare.swift

---------

Co-authored-by: Philippe Hausler <phausler@apple.com>
2026-01-26 09:29:41 -08:00
scottmarchant ba540240d3 docs: Update comments in Locking.swift to better clarify threading scenario for WASILibc. (#393)
### Motivation:

The previous comments could mislead readers into thinking WASILibc doesn't have pthreads or locks, which isn't correct. The updated comment adds needed clarification to help readers know there multiple variations and configurations of Swift for WebAssembly, some of which provide pthreads and locks.

### Modifications:

- Updated code comments in Locking.swift

### Result:

- Better explanation of WASILibc capabilities.
2026-01-13 22:12:46 +00:00
65ed06871b mapError - transforming failures (#366)
* Implement AsyncMapErrorSequence

* Update the proposal, implementation and tests with formatting, additional details and modifications for being able to push it to a review

* Foratting and preambles

* Update Copyright date for error sequence

Co-authored-by: Clive <clive819@users.noreply.github.com>

* Update copyright year for mapError tests

Co-authored-by: Clive <clive819@users.noreply.github.com>

* Update availablity and modify the mapError algorithm to be opaque

* Correct pre 6.0 build avail parameters

* Make the formatting of the algorithm accesor a bit more consistent

* Update the 5.8 package builder to define 1.2

* re-run formatter

---------

Co-authored-by: Clive <clive819@gmail.com>
Co-authored-by: Clive <clive819@users.noreply.github.com>
2026-01-12 12:21:06 -08:00
scottmarchant d98a48b8c2 feat: Add support for compiling to wasm when pthreads aren't available (#389) 2026-01-12 10:37:45 -08:00
Franz Busch 6c050d5ef8 Make MPSCAsyncChannel source methods nonisolated(nonsending) (#380)
`nonisolated(nonsending)` is a 6.2 language feature that allows the inheritance of the callers isolation. The new `MPSCAsyncChannel.Source` send methods should adopt this to avoid unnecessary isolation hops.
2025-12-01 11:18:00 -08:00
58 changed files with 9043 additions and 110 deletions

No files matched your search

+1 -2
View File
@@ -15,11 +15,10 @@ jobs:
linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}, {\"swift_version\": \"5.10\"}]]"
windows_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}]"
enable_wasm_sdk_build: true
wasm_sdk_build_command: swift build -Xcc -D_WASI_EMULATED_PTHREAD
soundness:
name: Soundness
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
with:
license_header_check_project_name: "Swift Async Algorithms"
format_check_container_image: "swiftlang/swift:nightly-6.1-noble" # Needed since 6.0.x doesn't support sending keyword
format_check_container_image: "swiftlang/swift:nightly-main-noble" # Needed due to https://github.com/swiftlang/swift-format/issues/1081
+2 -1
View File
@@ -9,4 +9,5 @@ DerivedData/
.netrc
.swiftpm
Package.resolved
.swift-version
.swift-version
test_output.log
+49
View File
@@ -0,0 +1,49 @@
# Map Error
* Proposal: [SAA-NNNN](NNNN-map-error.md)
* Authors: [Clive Liu](https://github.com/clive819) [Philippe Hausler](https://github.com/phausler)
* Review Manager: TBD
* Status: **Awaiting review**
## Introduction
Asynchronous sequences often particpate in carefully crafted systems of algorithms spliced together. Some of those algorithms require that both the element type and the failure type are the same as each-other. In order to line those types up for the element we have the map algorithm today, however there are other times at which when using more specific APIs that transforming the Failure type is needed.
## Motivation
The `mapError` function empowers developers to elegantly transform errors within asynchronous sequences, enhancing code readability and maintainability.
Building failure-type-safe versions of zip or other algorithms will need to require that the associated Failure types are the same. Having an effecient and easy to use transformation routine to adjust the failure-types is then key to delivering or interfacing with those failure-type-safe algorithms.
## Proposed solution
A new extension and type will be added to transform the failure-types of AsyncSequences.
## Detailed design
The method will be applied to all AsyncSequences via an extension with the function name of `mapError`. This is spiritually related to the `mapError` method on `Result` and similar in functionality to other frameworks' methods of the similar naming. This will not return an opaque result since the type needs to be refined for `Sendable`; in that the `AsyncMapERrorSequence` is only `Sendable` when the base `AsyncSequence` is `Sendable`.
```swift
extension AsyncSequence {
public func mapError<MappedFailure: Error>(_ transform: @Sendable @escaping (Failure) async -> MappedFailure) -> AsyncMapErrorSequence<Element, MappedFailure>
}
public struct AsyncMapErrorSequence<Base: AsyncSequence, TransformedFailure: Error>: AsyncSequence { }
extension AsyncMapErrorSequence: Sendable where Base: Sendable { }
@available(*, unavailable)
extension AsyncMapErrorSequence.Iterator: Sendable {}
```
## Effect on API resilience
This cannot be back-deployed to 1.0 since it has a base requirement for the associated `Failure` and requires typed throws.
## Naming
The naming follows to current method naming of the Combine [mapError](https://developer.apple.com/documentation/combine/publisher/maperror(_:)) method and similarly the name of the method on `Result`
## Alternatives considered
It was initially considered that the return type would be opaque, however the only way to refine that as Sendable would be to have a disfavored overload; this ended up creating more ambiguity than it seemed worth.
+200
View File
@@ -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.
+74 -2
View File
@@ -7,8 +7,14 @@ let AsyncAlgorithms_v1_0 = "AvailabilityMacro=AsyncAlgorithms 1.0:macOS 10.15, i
#if compiler(>=6.0) && swift(>=6.0) // 5.10 doesnt support visionOS availability
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] = [
@@ -18,12 +24,33 @@ let availabilityMacros: [SwiftSetting] = [
.enableExperimentalFeature(
AsyncAlgorithms_v1_1
),
.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(
@@ -36,6 +63,26 @@ let package = Package(
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
.target(
name: "AsyncStreaming",
dependencies: [
.product(name: "BasicContainers", package: "swift-collections"),
.product(name: "ContainersPreview", package: "swift-collections"),
.product(name: "DequeModule", package: "swift-collections"),
],
exclude: ["NNNN-async-streaming.md"],
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"],
@@ -66,6 +113,7 @@ let package = Package(
.macCatalyst,
.android,
.linux,
.custom("freebsd"),
.openbsd,
.wasi,
])
@@ -81,6 +129,7 @@ let package = Package(
.macCatalyst,
.android,
.linux,
.custom("freebsd"),
.openbsd,
.wasi,
])
@@ -90,12 +139,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.1",
traits: [.trait(name: "UnstableContainersPreview", condition: .when(traits: ["UnstableAsyncStreaming"]))]
)
]
} else {
package.dependencies += [
+1 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version: 5.6
// swift-tools-version: 5.7
import PackageDescription
+6
View File
@@ -12,6 +12,12 @@ let availabilityMacros: [SwiftSetting] = [
.enableExperimentalFeature(
"AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
),
.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.
@@ -14,15 +14,18 @@ extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
/// Starting from the initial value, this combines each element of the base
/// asynchronous sequence with the running result and emits each intermediate
/// result. The initial value itself is not emitted, so the first element of
/// the returned sequence is the result of combining the initial value with
/// the first element of the base sequence. If the base sequence is empty, the
/// returned sequence is also empty.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously-reduced result and
/// the next element in the receiving asynchronous sequence, which it returns.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
/// - Returns: An asynchronous sequence of the reduced elements.
@available(AsyncAlgorithms 1.0, *)
@inlinable
public func reductions<Result>(
@@ -37,16 +40,19 @@ extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
/// Starting from the initial value, this combines each element of the base
/// asynchronous sequence with the running result and emits each intermediate
/// result. The initial value itself is not emitted, so the first element of
/// the returned sequence is the result of combining the initial value with
/// the first element of the base sequence. If the base sequence is empty, the
/// returned sequence is also empty.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously-reduced result and
/// the next element in the receiving asynchronous sequence, mutating the
/// previous result instead of returning a value.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
/// - Returns: An asynchronous sequence of the reduced elements.
@available(AsyncAlgorithms 1.0, *)
@inlinable
public func reductions<Result>(
@@ -0,0 +1,106 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
#if compiler(>=6.0)
@available(AsyncAlgorithms 1.2, *)
extension AsyncSequence {
/// Converts any failure into a new error.
///
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
///
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
@available(AsyncAlgorithms 1.2, *)
public func mapError<MappedError: Error>(
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
) -> some AsyncSequence<Self.Element, MappedError> {
AsyncMapErrorSequence(base: self, transform: transform)
}
/// Converts any failure into a new error.
///
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
///
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
@available(AsyncAlgorithms 1.2, *)
public func mapError<MappedError: Error>(
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
) -> (some AsyncSequence<Self.Element, MappedError> & Sendable) where Self: Sendable, Self.Element: Sendable {
AsyncMapErrorSequence(base: self, transform: transform)
}
}
/// An asynchronous sequence that converts any failure into a new error.
@available(AsyncAlgorithms 1.2, *)
struct AsyncMapErrorSequence<Base: AsyncSequence, MappedError: Error> {
typealias Element = Base.Element
typealias Failure = MappedError
private let base: Base
private let transform: @Sendable (Base.Failure) async -> MappedError
init(
base: Base,
transform: @Sendable @escaping (Base.Failure) async -> MappedError
) {
self.base = base
self.transform = transform
}
}
@available(AsyncAlgorithms 1.2, *)
extension AsyncMapErrorSequence: AsyncSequence {
/// The iterator that produces elements of the map sequence.
struct Iterator: AsyncIteratorProtocol {
typealias Element = Base.Element
private var base: Base.AsyncIterator
private let transform: @Sendable (Base.Failure) async -> MappedError
init(
base: Base.AsyncIterator,
transform: @Sendable @escaping (Base.Failure) async -> MappedError
) {
self.base = base
self.transform = transform
}
mutating func next() async throws(MappedError) -> Element? {
try await self.next(isolation: nil)
}
mutating func next(isolation actor: isolated (any Actor)?) async throws(MappedError) -> Element? {
do {
return try await base.next(isolation: actor)
} catch {
throw await transform(error)
}
}
}
func makeAsyncIterator() -> Iterator {
Iterator(
base: base.makeAsyncIterator(),
transform: transform
)
}
}
@available(AsyncAlgorithms 1.2, *)
extension AsyncMapErrorSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
@available(*, unavailable)
extension AsyncMapErrorSequence.Iterator: Sendable {}
#endif
@@ -423,7 +423,7 @@ where Base.Element: Sendable, Base: SendableMetatype, Base.AsyncIterator: Sendab
}
func iterate() async -> Bool {
if let limit {
if let limit, limit > 0 {
let cancelled = await withUnsafeContinuation { (continuation: UnsafeContinuation<Bool, Never>) in
let (resume, cancelled) = state.withLock { state -> (UnsafeContinuation<Bool, Never>?, Bool) in
guard state.buffer.count >= limit else {
@@ -14,16 +14,19 @@ extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given error-throwing closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
/// Starting from the initial value, this combines each element of the base
/// asynchronous sequence with the running result and emits each intermediate
/// result. The initial value itself is not emitted, so the first element of
/// the returned sequence is the result of combining the initial value with
/// the first element of the base sequence. If the base sequence is empty, the
/// returned sequence is also empty.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving asynchronous sequence and returns
/// the result. If the closure throws an error, the sequence throws.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
/// - Returns: An asynchronous sequence of the reduced elements.
@available(AsyncAlgorithms 1.0, *)
@inlinable
public func reductions<Result>(
@@ -38,8 +41,12 @@ extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given error-throwing closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
/// Starting from the initial value, this combines each element of the base
/// asynchronous sequence with the running result and emits each intermediate
/// result. The initial value itself is not emitted, so the first element of
/// the returned sequence is the result of combining the initial value with
/// the first element of the base sequence. If the base sequence is empty, the
/// returned sequence is also empty.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
@@ -47,8 +54,7 @@ extension AsyncSequence {
/// the next element in the receiving asynchronous sequence, mutating the
/// previous result instead of returning a value. If the closure throws an
/// error, the sequence throws.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
/// - Returns: An asynchronous sequence of the reduced elements.
@available(AsyncAlgorithms 1.0, *)
@inlinable
public func reductions<Result>(
@@ -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
}
}
}
@@ -0,0 +1,38 @@
//===----------------------------------------------------------------------===//
//
// 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 compiler(>=6.1)
// This is a helper type to move a non-Sendable value across isolation regions.
@usableFromInline
struct Disconnected<Value: ~Copyable>: ~Copyable, Sendable {
// This is safe since we take the value as sending and take consumes it
// and returns it as sending.
private nonisolated(unsafe) var value: Value?
@usableFromInline
init(value: consuming sending Value) {
self.value = .some(value)
}
@usableFromInline
consuming func take() -> sending Value {
nonisolated(unsafe) let value = self.value.take()!
return value
}
@usableFromInline
mutating func swap(newValue: consuming sending Value) -> sending Value {
nonisolated(unsafe) let value = self.value.take()!
self.value = consume newValue
return value
}
}
#endif
+28
View File
@@ -21,6 +21,11 @@ import WinSDK
import Bionic
#elseif canImport(wasi_pthread)
import wasi_pthread
#elseif canImport(WASILibc)
// Here, we can not import wasi_pthread, but we can import WASILibc. So
// this is a variation of WASILibc without pthread support. As such, the
// platform does not have locks or mechanisms to become multi-threaded,
// so no locks are needed.
#else
#error("Unsupported platform")
#endif
@@ -29,7 +34,13 @@ internal struct Lock {
#if canImport(Darwin)
typealias Primitive = os_unfair_lock
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
#if os(FreeBSD) || os(OpenBSD)
typealias Primitive = pthread_mutex_t?
#else
typealias Primitive = pthread_mutex_t
#endif
#elseif canImport(WASILibc)
// This WASILibc variation is single threaded, provides no locks
#elseif canImport(WinSDK)
typealias Primitive = SRWLOCK
#else
@@ -49,6 +60,11 @@ internal struct Lock {
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
let result = pthread_mutex_init(platformLock, nil)
precondition(result == 0, "pthread_mutex_init failed")
#elseif canImport(WASILibc)
// Here, we can not import wasi_pthread, but we can import WASILibc. So
// this is a variation of WASILibc without pthread support. As such, the
// platform does not have locks or mechanisms to become multi-threaded,
// so no locks are needed.
#elseif canImport(WinSDK)
InitializeSRWLock(platformLock)
#else
@@ -69,6 +85,12 @@ internal struct Lock {
os_unfair_lock_lock(platformLock)
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
pthread_mutex_lock(platformLock)
#elseif canImport(WASILibc)
// Here, we can not import wasi_pthread, but we can import WASILibc. So
// this is a variation of WASILibc without pthread support. As such, the
// platform does not have locks or mechanisms to become multi-threaded,
// so no locks are needed.
return
#elseif canImport(WinSDK)
AcquireSRWLockExclusive(platformLock)
#else
@@ -82,6 +104,12 @@ internal struct Lock {
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
let result = pthread_mutex_unlock(platformLock)
precondition(result == 0, "pthread_mutex_unlock failed")
#elseif canImport(WASILibc)
// Here, we can not import wasi_pthread, but we can import WASILibc. So
// this is a variation of WASILibc without pthread support. As such, the
// platform does not have locks or mechanisms to become multi-threaded,
// so no locks are needed.
return
#elseif canImport(WinSDK)
ReleaseSRWLockExclusive(platformLock)
#else
@@ -261,9 +261,9 @@ extension MultiProducerSingleConsumerAsyncChannel {
) throws -> MultiProducerSingleConsumerAsyncChannel<Element, Failure>.Source.SendResult {
// We need to move the value into an optional since we don't have call-once
// closures in the Swift yet.
var optionalSequence = Optional(sequence)
var optionalSequence = Disconnected(value: Optional(sequence))
let action = self._stateMachine.withLock {
let sequence = optionalSequence.takeSending()!
let sequence = optionalSequence.swap(newValue: nil)!
return $0.send(sequence)
}
@@ -313,19 +313,21 @@ extension MultiProducerSingleConsumerAsyncChannel {
callbackToken: UInt64,
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
) {
// We need to move the value into an optional since we don't have call-once
// We need to move the value into a disconnected since we don't have call-once
// closures in the Swift yet.
var optionalOnProduceMore = Optional(onProduceMore)
var optionalOnProduceMore = Disconnected(value: Optional(onProduceMore))
let action = self._stateMachine.withLock {
let onProduceMore = optionalOnProduceMore.takeSending()!
let onProduceMore = optionalOnProduceMore.swap(newValue: nil)!
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,20 +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>)
}
extension Optional where Wrapped: ~Copyable {
@usableFromInline
mutating func takeSending() -> sending Self {
let result = consume self
self = nil
return result
}
}
// TODO: This should be replaced with Disconnected once we have a UniqueDeque
@usableFromInline
struct SendableConsumeOnceBox<Wrapped> {
@usableFromInline
@@ -1741,7 +1794,8 @@ struct SendableConsumeOnceBox<Wrapped> {
@inlinable
consuming func take() -> sending Wrapped {
return self.wrapped.takeSending()!
nonisolated(unsafe) let value = self.wrapped.take()!
return value
}
}
#endif
@@ -138,23 +138,24 @@ public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>:
public struct ChannelAndStream: ~Copyable {
/// The channel.
@usableFromInline
var channel: MultiProducerSingleConsumerAsyncChannel?
var channel: Disconnected<MultiProducerSingleConsumerAsyncChannel?>
/// Takes and returns the channel.
///
/// - Important: If this is called more than once it will result in a runtime crash.
@inlinable
public mutating func takeChannel() -> sending MultiProducerSingleConsumerAsyncChannel {
return self.channel.takeSending()!
var channel = self.channel.swap(newValue: nil)
return channel.take()!
}
/// The source.
public var source: Source
init(
channel: consuming MultiProducerSingleConsumerAsyncChannel,
channel: consuming sending MultiProducerSingleConsumerAsyncChannel,
source: consuming Source
) {
self.channel = .some(channel)
self.channel = Disconnected(value: channel)
self.source = source
}
}
@@ -445,6 +446,95 @@ extension MultiProducerSingleConsumerAsyncChannel {
}
}
#if compiler(>=6.2)
/// Send new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
@inlinable
public mutating nonisolated(nonsending) func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element == S.Element, S: Sequence, Element: Copyable {
let syncSend: (sending S, inout Self) throws -> SendResult = { try $1.send(contentsOf: $0) }
let sendResult = try syncSend(sequence, &self)
switch consume sendResult {
case .produceMore:
return ()
case .enqueueCallback(let callbackToken):
let id = callbackToken._id
let storage = self._storage
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { continuation in
self._storage.enqueueProducer(
callbackToken: id,
continuation: continuation
)
}
} onCancel: {
storage.cancelProducer(callbackToken: id)
}
}
}
/// Send new element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - element: The element to send to the channel.
@inlinable
public mutating nonisolated(nonsending) func send(_ element: consuming sending Element) async throws {
let syncSend: (consuming sending Element, inout Self) throws -> SendResult = { try $1.send($0) }
let sendResult = try syncSend(element, &self)
switch consume sendResult {
case .produceMore:
return ()
case .enqueueCallback(let callbackHandle):
let id = callbackHandle._id
let storage = self._storage
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { continuation in
self._storage.enqueueProducer(
callbackToken: id,
continuation: continuation
)
}
} onCancel: {
storage.cancelProducer(callbackToken: id)
}
}
}
/// Send the elements of the asynchronous sequence to the channel.
///
/// This method returns once the provided asynchronous sequence or the channel finished.
///
/// - Important: This method does not finish the source if consuming the upstream sequence terminated.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
@inlinable
public mutating nonisolated(nonsending) func send<S>(contentsOf sequence: consuming sending S) async throws
where Element == S.Element, S: AsyncSequence, Element: Copyable, S: Sendable, Element: Sendable {
for try await element in sequence {
try await self.send(contentsOf: CollectionOfOne(element))
}
}
#else
/// Send new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
@@ -532,6 +622,7 @@ extension MultiProducerSingleConsumerAsyncChannel {
try await self.send(contentsOf: CollectionOfOne(element))
}
}
#endif
/// Indicates that the production terminated.
///
@@ -55,6 +55,8 @@ final class TaskDriver: Sendable {
let queue: WorkQueue
#if canImport(Darwin) || canImport(wasi_pthread)
nonisolated(unsafe) var thread: pthread_t?
#elseif os(FreeBSD)
nonisolated(unsafe) var thread = pthread_t(bitPattern: 0)
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
nonisolated(unsafe) var thread = pthread_t()
#elseif canImport(WinSDK)
@@ -0,0 +1,160 @@
//===----------------------------------------------------------------------===//
//
// 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
/// An error that indicates the reader produced more elements than the
/// destination container could accept.
public struct AsyncReaderLeftOverElementsError: Error, Hashable {
public init() {}
}
/// An error that indicates the reader signaled end-of-stream before producing
/// enough elements to fill the destination container.
public struct AsyncReaderInsufficientElementsError: Error, Hashable {
public init() {}
}
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Collects elements from the reader into the provided container, up to the
/// container's available space.
///
/// Reads chunks from the reader and moves them into `target` until the reader
/// signals end-of-stream. The reader can deliver fewer elements than
/// `target.freeCapacity`; the container needn't be full when the stream ends.
/// If the reader produces more elements than `target` can accept, the method
/// throws ``AsyncReaderLeftOverElementsError``.
///
/// - Parameter target: The container that receives the collected elements.
/// The method preserves the container's existing contents and appends
/// collected elements to the end.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure`` or
/// an ``AsyncReaderLeftOverElementsError`` if the reader produced more
/// elements than `target` could accept.
public consuming func collect<Container: RangeReplaceableContainer<ReadElement> & ~Copyable & ~Escapable>(
into target: inout Container
) async throws(EitherError<ReadFailure, AsyncReaderLeftOverElementsError>) -> FinalElement {
var reader = self
var finalElement: FinalElement? = nil
while finalElement == nil {
try await reader.read { (buffer, final) throws(AsyncReaderLeftOverElementsError) -> Void in
if buffer.count > target.freeCapacity {
throw AsyncReaderLeftOverElementsError()
}
target.append(moving: buffer.startIndex..<buffer.endIndex, from: &buffer)
if let final {
finalElement = final
}
}
}
// The force-unwrap is safe since final element must be set at this point
return finalElement!
}
/// Collects elements from the reader into the provided container, requiring
/// that the reader fill the container exactly.
///
/// Reads chunks from the reader and moves them into `target` until either the
/// reader signals end-of-stream or the container becomes full. The reader
/// must produce exactly `target.freeCapacity` elements. If it produces fewer
/// before signaling end-of-stream, the method throws
/// ``AsyncReaderInsufficientElementsError``. If it produces more, it throws
/// ``AsyncReaderLeftOverElementsError``.
///
/// - Parameter target: The container to fill exactly. The method appends
/// collected elements to the container's existing contents.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure``
/// or an `EitherError` wrapping
/// ``AsyncReaderLeftOverElementsError`` (too many elements) or
/// ``AsyncReaderInsufficientElementsError`` (too few elements).
public consuming func collect<Container: RangeReplaceableContainer<ReadElement> & ~Copyable & ~Escapable>(
exactlyInto target: inout Container
) async throws(EitherError<
ReadFailure, EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
>) -> FinalElement {
var reader = self
var finalElement: FinalElement? = nil
while finalElement == nil {
try await reader.read {
(
buffer,
final
) throws(EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>) -> Void in
if buffer.count > target.freeCapacity {
throw .first(AsyncReaderLeftOverElementsError())
}
if final != nil, buffer.count < target.freeCapacity {
throw .second(AsyncReaderInsufficientElementsError())
}
target.append(moving: buffer.startIndex..<buffer.endIndex, from: &buffer)
if let final {
finalElement = final
}
}
}
// The force-unwrap is safe since final element must be set at this point
return finalElement!
}
/// Collects elements from the reader into the provided dynamic container,
/// growing it up to the specified maximum size.
///
/// Reads chunks from the reader and appends them to `target`, which grows as
/// elements arrive. The reader can deliver fewer than `maximumSize` elements
/// before signaling end-of-stream; if it delivers more, the method throws
/// ``AsyncReaderLeftOverElementsError``.
///
/// - Parameters:
/// - target: The dynamic container that receives the collected elements.
/// The method appends collected elements to the container's existing
/// contents.
/// - maximumSize: The maximum number of elements to append to `target`.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure`` or
/// an ``AsyncReaderLeftOverElementsError`` if the reader produced more than
/// `maximumSize` elements.
public consuming func collect<Container: DynamicContainer<ReadElement> & ~Copyable>(
into target: inout Container,
maximumSize: Int
) async throws(EitherError<ReadFailure, AsyncReaderLeftOverElementsError>) -> FinalElement {
precondition(maximumSize >= 0, "maximumSize must be non-negative")
var reader = self
var finalElement: FinalElement? = nil
var remaining = maximumSize
while finalElement == nil {
try await reader.read { (buffer, final) throws(AsyncReaderLeftOverElementsError) -> Void in
let chunkCount = buffer.count
if chunkCount > remaining {
throw AsyncReaderLeftOverElementsError()
}
if chunkCount > 0 {
var consumer = buffer.consumeAll()
while let element = consumer.next() {
target.append(element)
}
remaining -= chunkCount
}
if let final {
finalElement = final
}
}
}
// The force-unwrap is safe since final element must be set at this point
return finalElement!
}
}
#endif
@@ -0,0 +1,95 @@
//===----------------------------------------------------------------------===//
//
// 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 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Iterates over all chunks from the reader, executing the provided body for
/// each buffer until the stream signals end-of-stream.
///
/// This method continuously reads chunks from the async reader, executing
/// `body` for every chunk — including the terminal one — and terminates the
/// loop when the reader delivers a non-`nil` ``AsyncReader/FinalElement``.
/// The returned value is that ``AsyncReader/FinalElement``.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// _ = try await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
///
/// - Parameter body: An asynchronous closure that processes each buffer of
/// elements read from the stream.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal
/// chunk, or `nil` if none was observed.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the
/// read operation or a `Failure` from the body closure.
public consuming func forEachBuffer<Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Void
) async throws(EitherError<ReadFailure, Failure>) -> FinalElement? {
var final: FinalElement? = nil
var done = false
while !done {
try await self.read { (next, finalElement) throws(Failure) -> Void in
if !next.isEmpty {
try await body(&next)
}
if let finalElement {
final = finalElement
done = true
}
}
}
return final
}
/// Iterates over all chunks from a non-failing reader, executing the
/// provided body for each buffer until the stream signals end-of-stream.
///
/// Use this overload when the reader's ``AsyncReader/ReadFailure`` type is `Never`.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// _ = await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
///
/// - Parameter body: An asynchronous closure that processes each buffer of
/// elements read from the stream.
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
@inlinable
public consuming func forEachBuffer(
body: (inout Buffer) async -> Void
) async -> FinalElement where ReadFailure == Never {
do {
let final: FinalElement? = try await self.forEachBuffer { (buffer) async throws(Never) -> Void in
await body(&buffer)
}
// The force-unwrap is safe since final element must be set at this point
return final!
} catch {
fatalError()
}
}
}
#endif
@@ -0,0 +1,164 @@
//===----------------------------------------------------------------------===//
//
// 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 ContainersPreview
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
// should additionally be constrained `& ~Escapable`. We currently can't express
// that because of a Swift lifetime-checker limitation: with `FinalElement:
// ~Copyable`, the `consuming FinalElement?` parameter on the read closure
// changes the closure's lifetime category, and capturing a `~Escapable Writer`
// inside that closure (which `pipe` does, via the `writerOpt` Optional that
// alternates between `write` and `finish` calls) trips
// "lifetime-dependent variable 'writer' escapes its scope". When that
// restriction is relaxed (or `pipe` is restructured to avoid capturing the
// writer across the read closure boundary) the constraint should be added
// back so `pipe` works for `~Escapable` writers too.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given writer, fusing the
/// terminal chunk with a `finish` on the writer.
///
/// Consumes both the reader and the writer. Each chunk the reader produces is
/// forwarded with `writer.write(buffer:)` until the reader signals
/// end-of-stream by delivering a non-`nil` ``AsyncReader/FinalElement``. The
/// terminal chunk is fused with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataAsyncReader = ...
/// let fileWriter: FileCallerAsyncWriter = ...
///
/// // Copy all data from reader to writer and finish the writer.
/// try await dataReader.pipe(into: fileWriter)
/// ```
///
/// - Parameter writer: A ``CallerAsyncWriter`` to receive the elements. The
/// writer is consumed; its ``CallerAsyncWriter/finish(buffer:finalElement:)``
/// method is called with the reader's terminal chunk and ``AsyncReader/FinalElement``.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
into writer: consuming Writer
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where
Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
try await reader.read { (buffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
if let finalElement {
let w = writerOpt.take()!
try await w.finish(buffer: &buffer, finalElement: finalElement)
done = true
} else {
try await writerOpt!.write(buffer: &buffer)
}
}
}
}
/// Pipes all elements from this reader into the given writer, copying each
/// element from the reader's buffer into the writer's buffer.
///
/// Consumes both the reader and the writer. Because both protocols supply
/// their own buffer, each element is transferred between them. The writer's
/// buffer may be smaller than the reader's, in which case multiple `write`
/// calls are issued per chunk produced by the reader.
///
/// On the terminal chunk this method drains all bytes through `write` calls
/// first and then calls ``AsyncWriter/finish(finalElement:)`` carrying
/// only the ``AsyncReader/FinalElement`` payload.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataAsyncReader = ...
/// let fileWriter: FileAsyncWriter = ...
///
/// try await dataReader.pipe(copyingInto: fileWriter)
/// ```
///
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
/// writer is consumed; its ``AsyncWriter/finish(finalElement:)`` method
/// is called with the reader's ``AsyncReader/FinalElement`` payload.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
copyingInto writer: consuming Writer
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
try await reader.read {
(readerBuffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
try await Self.drain(readerBuffer: &readerBuffer, into: &writerOpt!)
if let finalElement {
let w = writerOpt.take()!
try await w.finish(finalElement: finalElement)
done = true
}
}
}
}
/// Drains `readerBuffer` into `writer` across as many `write` calls as
/// required to move every element. Used by ``pipe(copyingInto:)`` to share
/// the multi-write loop between mid-stream and terminal chunks.
private static func drain<Writer>(
readerBuffer: inout Buffer,
into writer: inout Writer
) async throws(Writer.WriteFailure)
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement
{
var consumer = readerBuffer.consumeAll()
while let firstElement = consumer.next() {
var pending: ReadElement? = firstElement
do throws(EitherError<Writer.WriteFailure, Never>) {
try await writer.write { (writerBuffer: inout Writer.Buffer) in
switch consume pending {
case .some(let element):
writerBuffer.append(element)
case .none:
break
}
pending = nil
while writerBuffer.freeCapacity > 0 {
guard let element = consumer.next() else { return }
writerBuffer.append(element)
}
}
} catch {
switch error {
case .first(let writeFailure): throw writeFailure
case .second: fatalError("Unreachable")
}
}
}
}
}
#endif
@@ -0,0 +1,90 @@
//===----------------------------------------------------------------------===//
//
// 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.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by passing a non-`nil` value for the
/// `finalElement` parameter of the `body` closure. This call may also carry a
/// final chunk of elements in the buffer, allowing the reader to fuse the last
/// chunk with the end signal in a single operation.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`, which means the
/// signal carries no payload. Set ``FinalElement`` to a custom type when the
/// reader needs to deliver structured data with the terminator. Set it to `Never` to indicate
/// that the stream never ends — the `finalElement` parameter will always be `nil`.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol AsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
// TODO: Check if we should support ~Escapable elements
associatedtype ReadElement: ~Copyable
/// The container type the reader uses to pass elements to the caller.
// TODO: Check if we should support ~Escapable buffer
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the
/// end signal. Use `Never` for streams that never end.
// TODO: Check if we should support ~Escapable final elements
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the underlying source and passes them to the provided body closure.
///
/// This method asynchronously reads elements from the source into a buffer,
/// then passes the buffer and an optional `finalElement` to `body` for
/// processing.
///
/// A `nil` value for `finalElement` means more data may follow. A non-`nil`
/// value (which is the only way a stream of `FinalElement == Void` signals
/// end) marks this chunk as the last one and delivers the final payload.
/// The terminal chunk's buffer may be empty or contain a final batch of
/// elements; the caller must process both.
///
/// After the reader has emitted a non-`nil` `finalElement`, calling
/// ``read(body:)`` again is a programmer error.
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// let result = try await fileReader.read { buffer, finalElement in
/// let processed = buffer.count
/// return (processed, finalElement != nil)
/// }
/// ```
///
/// - Parameter body: A closure that receives a mutable reference to the buffer
/// of read elements together with the optional end-of-stream payload and
/// returns a value of type `Return`.
/// - Returns: The value the body closure returns after processing the read elements.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
/// or a `Failure` from the body closure.
mutating func read<Return: ~Copyable, Failure: Error>(
body: (inout Buffer, consuming FinalElement?) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
#endif
@@ -0,0 +1,104 @@
//===----------------------------------------------------------------------===//
//
// 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.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(finalElement:)``.
/// Bulk transfer happens through ``write(_:)`` calls; ``finish(finalElement:)``
/// only carries the ``FinalElement`` payload.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(finalElement:)`` cannot
/// be called and the writer can be written to indefinitely.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol AsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
// TODO: Check if we should support ~Escapable elements
associatedtype WriteElement: ~Copyable
/// The container type the writer uses to receive elements from the caller.
// TODO: Check if we should support ~Escapable buffer
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer, sized by the implementation, that
/// `body` uses to append elements. The writer manages the buffer
/// allocation and handles the writing operation once `body` completes.
/// Oversized payloads are split across multiple calls.
///
/// - Parameter body: A closure that receives a buffer for appending elements
/// to write. The closure returns a result of type `Return`.
///
/// ## Example
///
/// ```swift
/// var writer: SomeAsyncWriter = ...
///
/// try await writer.write { buffer in
/// for item in items {
/// buffer.append(item)
/// }
/// return buffer.count
/// }
/// ```
///
/// - Returns: The value the body closure returns.
///
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
/// or a `Failure` from the body closure.
mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
/// Closes the writer, delivering a ``FinalElement`` payload alongside the
/// end-of-stream signal.
///
/// - Parameter finalElement: The ``FinalElement`` payload to deliver with
/// the end signal.
/// - Throws: A ``WriteFailure`` from the underlying write operation.
consuming func finish(
finalElement: consuming FinalElement
) async throws(WriteFailure)
}
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension AsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
/// Concludes the writer with no payload.
///
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
/// ``finish(finalElement:)`` with `()`.
public consuming func finish() async throws(WriteFailure) {
try await self.finish(finalElement: ())
}
}
#endif
@@ -0,0 +1,98 @@
//===----------------------------------------------------------------------===//
//
// 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
/// A ``CallerAsyncWriter`` that is implemented in terms of an
/// ``AsyncWriter``.
///
/// Each ``write(buffer:)`` call drains the caller's buffer through one
/// or more ``AsyncWriter/write(_:)`` closures on the underlying writer.
/// When the underlying writer's buffer fills before the caller's empties,
/// the adapter loops with another closure call to continue draining.
///
/// The adapter introduces no buffer of its own — elements move directly
/// from the caller-supplied buffer into the underlying writer's
/// closure-supplied buffer. The underlying writer's deferred-flush
/// behavior, if any, is preserved.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
public struct AsyncWriterCallerAsyncWriterAdapter<
Underlying: AsyncWriter & ~Copyable
>: ~Copyable, CallerAsyncWriter {
public typealias WriteElement = Underlying.WriteElement
public typealias WriteFailure = Underlying.WriteFailure
public typealias FinalElement = Underlying.FinalElement
@usableFromInline
var underlying: Underlying
@inlinable
init(underlying: consuming Underlying) {
self.underlying = underlying
}
@inlinable
public mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) {
var consumer = buffer.consumeAll()
while let head = consumer.next() {
var pending: WriteElement? = head
do throws(EitherError<WriteFailure, Never>) {
try await self.underlying.write {
(innerBuffer: inout Underlying.Buffer) async throws(Never) -> Void in
if case .some(let element) = pending.take() {
innerBuffer.append(element)
}
while innerBuffer.freeCapacity > 0 {
guard let element = consumer.next() else { return }
innerBuffer.append(element)
}
}
} catch {
switch error {
case .first(let writeFailure): throw writeFailure
case .second: fatalError("Unreachable")
}
}
}
}
@inlinable
public consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming FinalElement
) async throws(WriteFailure) {
try await self.write(buffer: &buffer)
try await self.underlying.finish(finalElement: finalElement)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension AsyncWriter where Self: ~Copyable {
/// Adapts this ``AsyncWriter`` to a ``CallerAsyncWriter``.
///
/// The returned adapter accepts caller-supplied buffers via
/// ``CallerAsyncWriter/write(buffer:)`` and drains them through this
/// writer's closure-based ``AsyncWriter/write(_:)``. When this
/// writer's buffer fills before the caller's empties, the adapter
/// loops with another closure call.
///
/// The adapter introduces no buffer of its own.
///
/// - Returns: An adapter that conforms to ``CallerAsyncWriter``.
@inlinable
public consuming func asCallerAsyncWriter() -> AsyncWriterCallerAsyncWriterAdapter<Self> {
.init(underlying: self)
}
}
#endif
@@ -0,0 +1,143 @@
//===----------------------------------------------------------------------===//
//
// 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 ContainersPreview
import BasicContainers
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
// should additionally be constrained `& ~Escapable`. We currently can't
// express that because of a Swift lifetime-checker limitation: with
// `FinalElement: ~Copyable`, the `consuming FinalElement?` parameter on the
// reader's `read` closure changes the closure's lifetime category, and
// capturing a `~Escapable Writer` inside that closure (which `pipe` does, via
// the `writerOpt` Optional that alternates between `write` and `finish`
// calls) trips "lifetime-dependent variable 'writer' escapes its scope".
// When that restriction is relaxed (or `pipe` is restructured to avoid
// capturing the writer across the closure boundary) the constraint should be
// added back so `pipe` works for `~Escapable` writers too.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
/// Pipes all elements from this reader into the given writer, then signals
/// end-of-stream with a `finish` call on the writer.
///
/// Consumes both the reader and the writer. The reader fills the writer's
/// buffer on each iteration; once the reader signals end-of-stream, the
/// writer's ``AsyncWriter/finish(finalElement:)`` is called with the reader's
/// ``CallerAsyncReader/FinalElement``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataCallerAsyncReader = ...
/// let fileWriter: FileAsyncWriter = ...
///
/// try await dataReader.pipe(into: fileWriter)
/// ```
///
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
/// writer is consumed.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
into writer: consuming Writer
) async throws(EitherError<Writer.WriteFailure, ReadFailure>)
where
Writer: AsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var done = false
while !done {
var pendingFinal: FinalElement? = nil
try await writerOpt!
.write { (buffer: inout Writer.Buffer) throws(ReadFailure) -> Void in
pendingFinal = try await reader.read(into: &buffer)
}
if let final = pendingFinal {
let w = writerOpt.take()!
do throws(Writer.WriteFailure) {
try await w.finish(finalElement: final)
} catch {
throw .first(error)
}
done = true
}
}
}
/// Pipes all elements from this reader into the given writer through an intermediate buffer.
///
/// Consumes both the reader and the writer. Because neither protocol supplies
/// a buffer, this method allocates an intermediate buffer of the requested
/// capacity and reuses it across iterations. The terminal chunk is fused
/// with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
///
/// ## Example
///
/// ```swift
/// let dataReader: DataCallerAsyncReader = ...
/// let fileWriter: FileCallerAsyncWriter = ...
///
/// try await dataReader.pipe(bufferingInto: fileWriter, intermediateCapacity: 4096)
/// ```
///
/// - Parameters:
/// - writer: A ``CallerAsyncWriter`` to receive the elements. The writer
/// is consumed.
/// - intermediateCapacity: The capacity of the intermediate buffer that
/// mediates between the reader and writer.
///
/// - Throws: An error originating from the read or write operations.
public consuming func pipe<Writer>(
bufferingInto writer: consuming Writer,
intermediateCapacity: Int
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
where
Writer: CallerAsyncWriter & ~Copyable,
Writer.WriteElement == ReadElement,
Writer.FinalElement == FinalElement
{
var reader = self
var writerOpt: Writer? = .some(writer)
var buffer = UniqueArray<ReadElement>(minimumCapacity: intermediateCapacity)
var done = false
while !done {
let final: FinalElement?
do throws(ReadFailure) {
final = try await reader.read(into: &buffer)
} catch {
throw .first(error)
}
if let final {
let w = writerOpt.take()!
do throws(Writer.WriteFailure) {
try await w.finish(buffer: &buffer, finalElement: final)
} catch {
throw .second(error)
}
done = true
} else if buffer.count > 0 {
do throws(Writer.WriteFailure) {
try await writerOpt!.write(buffer: &buffer)
assert(buffer.count == 0, "CallerAsyncWriter must drain the buffer during write(buffer:)")
} catch {
throw .second(error)
}
}
}
}
}
#endif
@@ -0,0 +1,69 @@
//===----------------------------------------------------------------------===//
//
// 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.
///
/// ## Signaling end of stream
///
/// The reader signals end-of-stream by returning a non-`nil` ``FinalElement``
/// from ``read(into:)``. The same call may also append a final batch of
/// elements to the caller's buffer, allowing the reader to fuse the last
/// chunk with the end signal.
///
/// The ``FinalElement`` associated type controls what data, if any, the reader
/// delivers alongside the end signal. The default is `Void`. Use a custom type
/// to carry data along with the end signal, or `Never` for streams that never
/// end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol CallerAsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
// TODO: Check if we should support ~Escapable elements
associatedtype ReadElement: ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// The data the reader delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`. Use a custom type to carry data along with the end
/// signal, or `Never` for streams that never end.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Reads elements from the source into the provided buffer.
///
/// This method appends elements into `buffer`. A non-`nil` return value
/// signals end-of-stream and delivers the final payload. The call may
/// also append a final batch of elements before signaling end.
///
/// After the reader has returned a non-`nil` `FinalElement`, calling
/// ``read(into:)`` again is a programmer error.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Returns: A non-`nil` ``FinalElement`` if this call delivered the
/// end-of-stream signal; `nil` if more elements may follow.
/// - Throws: A `ReadFailure` from the underlying read operation.
// TODO: Check if we should support ~Escapable buffer
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) -> FinalElement? where Buffer.Element: ~Copyable
}
#endif
@@ -0,0 +1,104 @@
//===----------------------------------------------------------------------===//
//
// 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
/// Writes elements asynchronously from a caller-provided buffer.
///
/// Adopt ``CallerAsyncWriter`` when you need caller-managed buffering,
/// where the caller provides a buffer of elements for the writer
/// to consume.
///
/// ## Signaling end of stream
///
/// The writer is terminated by a call to ``finish(buffer:finalElement:)``.
/// The `finish` call communicates a final buffer (if any) and the
/// ``FinalElement`` payload, allowing implementations to fuse the last data
/// frame with the end signal on transports that support it.
///
/// The ``FinalElement`` associated type controls what data, if any, the writer
/// transmits alongside the end signal. The default is `Void`. Use a custom
/// type to carry data along with the end signal, or `Never` for endless
/// streams. When ``FinalElement`` is `Never`, ``finish(buffer:finalElement:)``
/// cannot be called and the writer can be written to indefinitely.
///
/// Conformers must accept zero, one, or many `write(buffer:)` calls, optionally
/// followed by a single `finish(buffer:finalElement:)` call. After `finish`
/// returns, the writer is consumed and no further calls are valid.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
public protocol CallerAsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
// TODO: Check if we should support ~Escapable elements
associatedtype WriteElement: ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// The data the writer delivers alongside the end-of-stream signal.
///
/// Defaults to `Void`.
// TODO: Check if we should support ~Escapable final element
associatedtype FinalElement: ~Copyable = Void
/// Writes elements from the provided buffer to the underlying destination.
///
/// This method asynchronously writes all elements from the provided buffer
/// to the underlying destination.
///
/// ## Example
///
/// ```swift
/// var fileWriter: FileAsyncWriter = ...
/// var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
///
/// try await fileWriter.write(buffer: &data)
/// ```
///
/// - Parameter buffer: The buffer of elements to write.
///
/// - Throws: A `WriteFailure` from the underlying write operation.
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
/// Sends the final buffer and ``FinalElement`` payload, and signals
/// end-of-stream to the destination.
///
/// The buffer may be empty if there is no remaining content to emit
/// alongside the terminator. When ``FinalElement`` is `Void`, use the
/// closure-less ``finish()`` convenience instead of passing `()` explicitly.
///
/// - Parameters:
/// - buffer: The buffer of remaining elements to write alongside the
/// terminator.
/// - finalElement: The ``FinalElement`` payload to deliver with the end
/// signal.
/// - Throws: A `WriteFailure` from the underlying write operation.
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming FinalElement
) async throws(WriteFailure) where Buffer.Element: ~Copyable
}
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
extension CallerAsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
/// Concludes the writer with no final buffer and no extra payload.
///
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
/// ``finish(buffer:finalElement:)`` with an empty buffer and `()`.
public consuming func finish() async throws(WriteFailure) {
var empty = UniqueArray<WriteElement>()
try await self.finish(buffer: &empty, finalElement: ())
}
}
#endif
@@ -0,0 +1,118 @@
//===----------------------------------------------------------------------===//
//
// 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
public import BasicContainers
/// An ``AsyncWriter`` that is implemented in terms of a ``CallerAsyncWriter``.
///
/// The adapter allocates a fresh buffer for each ``write(_:)`` call, runs
/// the body to fill it, and immediately drains it into the underlying
/// ``CallerAsyncWriter``. Writes are flushed *eagerly*: the adapter does
/// not defer the most recent buffer to fuse it with ``finish(finalElement:)``.
///
/// Eager flushing keeps request/response patterns deadlock-free — a write
/// is observable to the peer as soon as the underlying writer accepts it.
/// The trade-off is that fused close (HTTP/2 DATA+END_STREAM coalescing,
/// and similar) is not available through this adapter; the underlying
/// ``CallerAsyncWriter/finish(buffer:finalElement:)`` always receives an
/// empty buffer. Conformers that need fused close should implement
/// ``AsyncWriter`` directly rather than going through this adapter.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
public struct CallerAsyncWriterAsyncWriterAdapter<
Underlying: CallerAsyncWriter & ~Copyable,
Buffer: DynamicContainer<Underlying.WriteElement> & ~Copyable
>: ~Copyable, AsyncWriter {
public typealias WriteElement = Underlying.WriteElement
public typealias WriteFailure = Underlying.WriteFailure
public typealias FinalElement = Underlying.FinalElement
@usableFromInline
var underlying: Underlying
@usableFromInline
let initialCapacity: Int
@inlinable
init(underlying: consuming Underlying, initialCapacity: Int) {
self.underlying = underlying
self.initialCapacity = initialCapacity
}
@inlinable
public mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return {
var buffer = Buffer(minimumCapacity: self.initialCapacity)
let result: Return
do throws(Failure) {
result = try await body(&buffer)
} catch {
throw .second(error)
}
do throws(WriteFailure) {
try await self.underlying.write(buffer: &buffer)
} catch {
throw .first(error)
}
return result
}
@inlinable
public consuming func finish(
finalElement: consuming FinalElement
) async throws(WriteFailure) {
var empty = Buffer()
try await self.underlying.finish(buffer: &empty, finalElement: finalElement)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension CallerAsyncWriter where Self: ~Copyable {
/// Adapts this ``CallerAsyncWriter`` to an ``AsyncWriter``, using
/// ``UniqueArray`` as the buffer container.
///
/// Each ``AsyncWriter/write(_:)`` call on the returned adapter
/// allocates a fresh buffer, runs the closure to fill it, and
/// immediately drains it into this writer. Writes are flushed
/// eagerly — see ``CallerAsyncWriterAsyncWriterAdapter`` for the
/// trade-off this implies for fused close.
///
/// - Parameter initialCapacity: The capacity reserved on each
/// freshly allocated buffer.
/// - Returns: An adapter that conforms to ``AsyncWriter``.
@inlinable
public consuming func asAsyncWriter(
initialCapacity: Int = 4096
) -> CallerAsyncWriterAsyncWriterAdapter<Self, UniqueArray<WriteElement>> {
.init(underlying: self, initialCapacity: initialCapacity)
}
/// Adapts this ``CallerAsyncWriter`` to an ``AsyncWriter`` with a
/// caller-chosen buffer container type.
///
/// - Parameters:
/// - bufferType: The container type for buffers handed to the
/// ``AsyncWriter/write(_:)`` body.
/// - initialCapacity: The capacity reserved on each freshly
/// allocated buffer.
/// - Returns: An adapter that conforms to ``AsyncWriter``.
@inlinable
public consuming func asAsyncWriter<Buffer>(
bufferOf bufferType: Buffer.Type,
initialCapacity: Int = 4096
) -> CallerAsyncWriterAsyncWriterAdapter<Self, Buffer>
where Buffer: DynamicContainer<WriteElement> & ~Copyable {
.init(underlying: self, initialCapacity: initialCapacity)
}
}
#endif
@@ -0,0 +1,536 @@
//===----------------------------------------------------------------------===//
//
// 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 DequeModule
public import ContainersPreview
/// A bidirectional, in-memory duplex channel with four connected handles.
///
/// Each call to ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
/// creates two ``Writer``s and two ``Reader``s connected by a pair of
/// internal ``MultiProducerSingleConsumerAsyncChannel`` storages — one
/// per direction:
///
/// ```
/// forward
/// writerA ────────────────────────────────────────> readerB
///
/// reverse
/// readerA <──────────────────────────────────────── writerB
/// ```
///
/// The four handles are independent `~Copyable` values so each can be
/// sent to its own task without an intermediate decomposition step.
///
/// Each direction applies backpressure independently using the configured
/// ``BackpressureStrategy``: writes suspend when the per-direction buffer
/// rises above the high watermark and resume once it drops below the low
/// watermark.
///
///
/// To scope the channel and its handles to a structured-concurrency
/// region, use
/// ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``.
/// When `body` returns, both directions are finalized and any remaining
/// suspended producers are resumed with an error.
///
/// The ``FinalElement`` and ``Failure`` types apply to both directions.
/// Each direction's writer terminates its half of the channel
/// independently by calling ``Writer/finish(finalElement:)`` or
/// ``Writer/finish(throwing:)``.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
public struct DuplexAsyncChannel<
Element: Sendable,
FinalElement: Sendable,
Failure: Error
>: ~Copyable {
/// Creates a new duplex channel with four connected handles and runs
/// `body` with all four.
///
/// The handles are paired by side:
///
/// - `writerA` and `readerA` belong to side A. Elements `writerA`
/// sends are observed on `readerB`; `readerA` observes elements
/// `writerB` sends.
/// - `writerB` and `readerB` belong to side B, mirrored.
///
/// After `body` returns, the duplex finalizes both directions and
/// resumes any remaining suspended producers with an error.
///
/// The handles are noncopyable and have no `deinit`-based cleanup. To
/// terminate one direction before the scope ends, call
/// ``Writer/finish(finalElement:)`` or ``Writer/finish(throwing:)`` on
/// the corresponding writer. Otherwise `withDuplex` finalizes both
/// directions when `body` returns.
///
/// - Parameters:
/// - elementType: The element type of both directions.
/// - finalElementType: The end-of-stream payload type of both
/// directions.
/// - failureType: The failure type of both directions.
/// - backpressureStrategy: The backpressure strategy applied
/// independently to each direction.
/// - isolation: The actor isolation in which `body` runs. Defaults to
/// the caller's isolation.
/// - body: A closure that receives ownership of the four connected
/// handles, in order: side A's writer, side A's reader, side B's
/// writer, side B's reader.
/// - Returns: The value returned from `body`.
@inlinable
public static func withDuplex<Result: ~Copyable, BodyFailure: Error>(
of elementType: Element.Type = Element.self,
withFinalElement finalElementType: FinalElement.Type,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: BackpressureStrategy,
isolation: isolated (any Actor)? = #isolation,
body: (
consuming sending Writer,
consuming sending Reader,
consuming sending Writer,
consuming sending Reader
) async throws(BodyFailure) -> sending Result
) async throws(BodyFailure) -> sending Result {
let forward = MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage(
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
)
let reverse = MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage(
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
)
let writerA = Writer(storage: forward)
let readerA = Reader(storage: reverse)
let writerB = Writer(storage: reverse)
let readerB = Reader(storage: forward)
let result: Result
do throws(BodyFailure) {
result = try await body(writerA, readerA, writerB, readerB)
} catch {
forward.finish(throwing: nil, finalElement: nil)
reverse.finish(throwing: nil, finalElement: nil)
forward.channelDeinitialized()
reverse.channelDeinitialized()
throw error
}
forward.finish(throwing: nil, finalElement: nil)
reverse.finish(throwing: nil, finalElement: nil)
forward.channelDeinitialized()
reverse.channelDeinitialized()
return result
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension DuplexAsyncChannel where FinalElement == Void {
/// Creates a new duplex channel with a `Void` end-of-stream payload and
/// runs `body` with all four handles.
///
/// This overload is available when ``FinalElement`` is `Void`. It's
/// equivalent to calling
/// ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
/// with `withFinalElement: Void.self`.
@inlinable
public static func withDuplex<Result: ~Copyable, BodyFailure: Error>(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: BackpressureStrategy,
isolation: isolated (any Actor)? = #isolation,
body: (
consuming sending Writer,
consuming sending Reader,
consuming sending Writer,
consuming sending Reader
) async throws(BodyFailure) -> sending Result
) async throws(BodyFailure) -> sending Result {
try await self.withDuplex(
of: elementType,
withFinalElement: Void.self,
throwing: failureType,
backpressureStrategy: backpressureStrategy,
isolation: isolation,
body: body
)
}
}
// MARK: - Backpressure strategy
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension DuplexAsyncChannel {
/// A backpressure strategy applied independently to each direction of
/// the duplex.
public struct BackpressureStrategy: Sendable {
@usableFromInline
var internalBackpressureStrategy:
MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._InternalBackpressureStrategy
@inlinable
init(
internalBackpressureStrategy:
MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._InternalBackpressureStrategy
) {
self.internalBackpressureStrategy = internalBackpressureStrategy
}
/// A backpressure strategy that suspends and resumes producers based
/// on high and low watermarks.
///
/// - Parameters:
/// - low: When the buffered element count drops below this
/// watermark, the channel resumes suspended producers in that
/// direction.
/// - high: When the buffered element count rises above this
/// watermark, the channel suspends new writes in that direction.
@inlinable
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: nil)
)
)
}
/// A backpressure strategy that suspends and resumes producers based
/// on high and low watermarks, weighted by a per-element water level.
///
/// - Parameters:
/// - low: When the water level drops below this watermark, the
/// channel resumes suspended producers in that direction.
/// - high: When the water level rises above this watermark, the
/// channel suspends new writes in that direction.
/// - waterLevelForElement: A closure that returns the water-level
/// contribution of a single element. The channel calls this
/// closure while holding its lock, so the closure must be free of
/// side effects and should run in constant time.
@inlinable
public static func watermark(
low: Int,
high: Int,
waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int
) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: waterLevelForElement)
)
)
}
}
}
// MARK: - Writer
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension DuplexAsyncChannel {
/// The writer half of one side of a ``DuplexAsyncChannel``.
///
/// Conforms to ``CallerAsyncWriter``: callers provide their own
/// ``RangeReplaceableContainer``-conforming buffer that the writer
/// drains.
///
/// Elements written here travel the channel's forward or reverse
/// direction and are observed on the peer side's ``Reader``. The writer
/// applies backpressure: ``write(buffer:)`` suspends when the
/// destination's buffer rises above the configured high watermark.
///
/// Writers can be cloned with ``clone()`` to produce concurrently from
/// multiple tasks. Terminate the direction with
/// ``finish(buffer:finalElement:)``, ``finish(finalElement:)``, or
/// ``finish(throwing:)``.
public struct Writer: ~Copyable, CallerAsyncWriter {
public typealias WriteElement = Element
public typealias WriteFailure = any Error
@usableFromInline
let _storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
@usableFromInline
let _id: UInt64
@usableFromInline
init(
storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
) {
self._storage = storage
self._id = storage.sourceInitialized()
}
/// Sets a callback to invoke when this direction terminates.
///
/// The duplex calls `callback` after the peer's reader observes its
/// last element on this direction. If the direction has already
/// terminated, the duplex invokes `callback` immediately.
///
/// - Important: A writer supports a single termination callback.
/// Setting a new callback replaces any previous one.
@inlinable
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
}
/// Creates an additional writer for this direction so multiple
/// producers can send concurrently.
///
/// The cloned writer terminates the direction independently — the
/// direction stays open until every clone has finished or been
/// dropped, mirroring ``MultiProducerSingleConsumerAsyncChannel/Source/clone()``.
@inlinable
public mutating func clone() -> sending Self {
.init(storage: self._storage)
}
/// Terminates this direction with the supplied error.
///
/// After the peer reader consumes all buffered elements on this
/// direction, its next ``Reader/read(body:)`` call throws `error`.
/// This path delivers no ``FinalElement`` payload to the peer.
///
/// To terminate this direction cleanly with an end-of-stream payload,
/// call ``finish(finalElement:)`` instead. When ``FinalElement`` is
/// `Void`, you can also call the ``finish()`` convenience.
@inlinable
public consuming func finish(throwing error: Failure) {
self._storage.finish(throwing: error, finalElement: nil)
}
/// Finishes this direction with a ``FinalElement`` payload.
///
/// The peer reader observes end-of-stream as a non-`nil` `finalElement`
/// argument to the body of its next ``Reader/read(body:)`` call. The
/// channel delivers any elements still buffered from earlier
/// ``write(buffer:)`` calls before the terminator.
///
/// - Note: This method delivers only the end-of-stream signal. To
/// send a final batch of elements alongside the terminator, call
/// ``write(buffer:)`` first and then ``finish(finalElement:)``.
@inlinable
public consuming func finish(finalElement: consuming sending FinalElement) {
self._storage.finish(throwing: nil, finalElement: finalElement)
}
/// Writes every element of `buffer` to this direction.
///
/// On success the call drains `buffer` completely. If the
/// direction's backpressure strategy signals that production should
/// pause, the call suspends until the peer reader drains enough of
/// the channel to fall below the low watermark.
///
/// - Throws: ``MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError``
/// if this direction has already finished, or `CancellationError`
/// if the task is canceled while suspended on backpressure.
@inlinable
public mutating func write<Buffer: RangeReplaceableContainer<Element> & ~Copyable>(
buffer: inout Buffer
) async throws {
// Move the caller's buffer into a `nonisolated(unsafe)` local so we
// can hand it to the storage's `inout sending` API. Safe because
// the elements are Sendable and we have the buffer inout so an exclusive
// ownership.
nonisolated(unsafe) var localBuffer = consume buffer
let sendResult: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>.Source._SendResult
do {
sendResult = try self._storage.write(buffer: &localBuffer)
} catch {
buffer = consume localBuffer
throw error
}
buffer = consume localBuffer
switch consume sendResult {
case .produceMore:
return
case .enqueueCallback(let token):
let storage = self._storage
do {
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Void, any Error>) in
storage.enqueueProducer(callbackToken: token, continuation: continuation)
}
} onCancel: {
storage.cancelProducer(callbackToken: token)
}
} catch {
throw error
}
}
}
/// Drains `buffer` to the peer, then signals end-of-stream with the
/// ``FinalElement`` payload. Consumes the writer.
///
/// This is the ``CallerAsyncWriter`` protocol entry point. The
/// duplex's in-memory transport doesn't fuse the last write with the
/// end-of-stream signal — `write(buffer:)` and `finish` are issued
/// sequentially. The observable result for the peer reader matches
/// the fused contract: the peer sees the trailing buffer's elements
/// and the `finalElement` together on its terminal `read`.
///
/// - Parameters:
/// - buffer: A buffer of remaining elements to write before
/// signaling end-of-stream.
/// - finalElement: The payload to deliver alongside the
/// end-of-stream signal.
/// - Throws: Any error thrown while draining `buffer`. If draining
/// fails, the direction is left unterminated; the scope's
/// finalizer terminates it on body return.
@inlinable
public consuming func finish<Buffer: RangeReplaceableContainer<Element> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming FinalElement
) async throws {
try await self.write(buffer: &buffer)
self._storage.finish(throwing: nil, finalElement: finalElement)
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension DuplexAsyncChannel.Writer where FinalElement == Void {
/// Finishes this direction with an empty `Void` end-of-stream payload.
///
/// This method is equivalent to calling ``finish(finalElement:)`` with
/// `()`. The peer reader observes end-of-stream as a non-`nil`
/// `finalElement` argument to the body of its next read.
@inlinable
public consuming func finish() {
self._storage.finish(throwing: nil, finalElement: ())
}
}
// MARK: - Reader
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension DuplexAsyncChannel {
/// The reader half of one side of a ``DuplexAsyncChannel``.
///
/// Conforms to ``AsyncReader``: the reader hands a noncopyable
/// ``UniqueDeque`` of elements to the body closure alongside an
/// optional ``FinalElement`` payload that signals end-of-stream when
/// present.
///
/// Reads elements written by the peer side's ``Writer``.
public struct Reader: ~Copyable, AsyncReader {
public typealias ReadElement = Element
public typealias Buffer = UniqueDeque<Element>
public typealias ReadFailure = EitherError<Failure, CancellationError>
@usableFromInline
let _storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
@usableFromInline
init(
storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
) {
self._storage = storage
}
/// Reads the next chunk of elements from this direction.
///
/// The reader passes the buffered elements to `body` along with an
/// optional ``FinalElement`` payload. A non-`nil` `finalElement`
/// marks the chunk as terminal and delivers the end-of-stream signal.
/// The terminal chunk's buffer may be empty or contain a final batch
/// of elements.
///
/// - Throws: An ``EitherError`` whose outer `.first` arm carries a
/// read-side error — either the duplex's `Failure` (when the peer
/// writer called ``Writer/finish(throwing:)``) or a
/// `CancellationError` (when the task is canceled while suspended
/// in `read`) — and whose outer `.second` arm carries the failure
/// thrown by `body`.
///
/// - Important: After the reader observes a non-`nil` `finalElement`,
/// calling `read(body:)` again is a programmer error.
@inlinable
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
) async throws(EitherError<EitherError<Failure, CancellationError>, BodyFailure>) -> Return {
while true {
let action = self._storage.readAvailable()
switch consume action {
case .returnElements(let disconnected):
var buffer = disconnected.take()
let result: Return
do throws(BodyFailure) {
result = try await body(&buffer, nil)
let buffer = buffer
self._storage.returnCachedReadBuffer(buffer)
} catch {
let buffer = buffer
self._storage.returnCachedReadBuffer(buffer)
throw .second(error)
}
return result
case .returnElementsAndResumeProducers(let disconnected, let producers):
var buffer = disconnected.take()
for producer in producers {
switch producer {
case .closure(let onProduceMore):
onProduceMore(Result<Void, any Error>.success(()))
case .continuation(let continuation):
continuation.resume()
}
}
let result: Return
do throws(BodyFailure) {
result = try await body(&buffer, nil)
let buffer = buffer
self._storage.returnCachedReadBuffer(buffer)
} catch {
let buffer = buffer
self._storage.returnCachedReadBuffer(buffer)
throw .second(error)
}
return result
case .returnTerminalChunk(let disconnectedBuffer, let disconnectedFinal, let onTerminations):
for (_, callback) in onTerminations { callback() }
var buffer = disconnectedBuffer.take()
let final = disconnectedFinal.take()
do throws(BodyFailure) {
return try await body(&buffer, final)
} catch {
throw .second(error)
}
case .throwFailure(let failure, let onTerminations):
for (_, callback) in onTerminations { callback() }
if let failure {
throw .first(.first(failure))
}
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .returnNil:
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .suspend:
do {
try await self._storage.suspendRead()
} catch {
throw .first(error)
}
continue
}
}
}
}
}
#endif
+54
View File
@@ -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,421 @@
//===----------------------------------------------------------------------===//
//
// 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 DequeModule
public import ContainersPreview
/// A multi-producer single-consumer channel.
///
/// This is the streaming-oriented variant of
/// ``AsyncAlgorithms.MultiProducerSingleConsumerAsyncChannel``. Instead of
/// exposing the consumer side as an `AsyncSequence`, it offers a chunked
/// ``read(body:)`` method that delivers a noncopyable ``UniqueDeque`` buffer
/// to the caller, so elements move through the channel without copying.
///
/// The channel applies backpressure to producers: it suspends writes when
/// the buffer rises above the high watermark and resumes them once the
/// buffer drops below the low watermark.
///
/// To scope the channel and its initial source to a structured-concurrency
/// region, use ``withChannel(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``.
///
/// The channel takes a ``FinalElement`` type that it delivers alongside the
/// end-of-stream signal. A producer terminates the channel by calling
/// either ``Source/finish(finalElement:)`` to signal end-of-stream
/// or ``Source/finish(throwing:)`` to terminate with a failure.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
public struct MultiProducerSingleConsumerAsyncChannel<
Element,
FinalElement,
Failure: Error
>: ~Copyable {
@usableFromInline
let storage: _Storage
@usableFromInline
init(storage: _Storage) {
self.storage = storage
}
/// Creates a new channel and runs `body` with the channel and its initial
/// source. After `body` returns, the channel finalizes itself and resumes
/// any remaining suspended producers with an error.
///
/// The channel and source are noncopyable and have no `deinit`-based
/// cleanup. To terminate the channel before its scope ends, call
/// ``Source/finish(finalElement:)`` or ``Source/finish(throwing:)`` on a
/// source. Otherwise `withChannel` finalizes the channel when `body`
/// returns.
///
/// - Parameters:
/// - elementType: The element type of the channel.
/// - finalElementType: The end-of-stream payload type of the channel.
/// - failureType: The failure type of the channel.
/// - backpressureStrategy: The backpressure strategy that the channel uses.
/// - isolation: The actor isolation in which `body` runs. Defaults to the caller's isolation.
/// - body: A closure that receives ownership of the channel and its initial source.
/// - Returns: The value returned from `body`.
@inlinable
public static func withChannel<Result: ~Copyable, BodyFailure: Error>(
of elementType: Element.Type = Element.self,
withFinalElement finalElementType: FinalElement.Type,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy,
isolation: isolated (any Actor)? = #isolation,
body: (
consuming sending MultiProducerSingleConsumerAsyncChannel,
consuming sending Source
) async throws(BodyFailure) -> sending Result
) async throws(BodyFailure) -> sending Result {
let storage = _Storage(
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
)
let channel = MultiProducerSingleConsumerAsyncChannel(storage: storage)
let source = Source(storage: storage)
let result: Result
do throws(BodyFailure) {
result = try await body(channel, source)
} catch {
storage.finish(throwing: nil, finalElement: nil)
storage.channelDeinitialized()
throw error
}
storage.finish(throwing: nil, finalElement: nil)
storage.channelDeinitialized()
return result
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel where FinalElement == Void {
/// Creates a new channel with a `Void` end-of-stream payload and runs
/// `body` with the channel and its initial source.
///
/// This overload is available when ``FinalElement`` is `Void`. It's
/// equivalent to calling
/// ``withChannel(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
/// with `withFinalElement: Void.self`.
public static func withChannel<Result: ~Copyable, BodyFailure: Error>(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy,
isolation: isolated (any Actor)? = #isolation,
body: (
consuming sending MultiProducerSingleConsumerAsyncChannel,
consuming sending Source
) async throws(BodyFailure) -> sending Result
) async throws(BodyFailure) -> sending Result {
try await self.withChannel(
of: elementType,
withFinalElement: Void.self,
throwing: failureType,
backpressureStrategy: backpressureStrategy,
isolation: isolation,
body: body
)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// A handle for sending elements to the channel.
public struct Source: ~Copyable, Sendable {
/// A backpressure strategy for the channel.
public struct BackpressureStrategy: Sendable {
@usableFromInline
var internalBackpressureStrategy: _InternalBackpressureStrategy
@inlinable
init(internalBackpressureStrategy: _InternalBackpressureStrategy) {
self.internalBackpressureStrategy = internalBackpressureStrategy
}
/// A backpressure strategy that suspends and resumes producers based on
/// high and low watermarks.
///
/// - Parameters:
/// - low: When the buffered element count drops below this watermark, the channel resumes suspended producers.
/// - high: When the buffered element count rises above this watermark, the channel suspends new writes.
@inlinable
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: nil)
)
)
}
/// A backpressure strategy that suspends and resumes producers based on
/// high and low watermarks, weighted by a per-element water level.
///
/// - Parameters:
/// - low: When the water level drops below this watermark, the channel resumes suspended producers.
/// - high: When the water level rises above this watermark, the channel suspends new writes.
/// - waterLevelForElement: A closure that returns the water-level
/// contribution of a single element. The channel calls this closure
/// while holding its lock, so the closure must be free of side
/// effects and should run in constant time.
@inlinable
public static func watermark(
low: Int,
high: Int,
waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int
) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: waterLevelForElement)
)
)
}
}
@usableFromInline
enum _SendResult: ~Copyable, Sendable {
case produceMore
case enqueueCallback(callbackToken: UInt64)
}
@usableFromInline
let _storage: _Storage
@usableFromInline
let _id: UInt64
@usableFromInline
init(storage: _Storage) {
self._storage = storage
self._id = self._storage.sourceInitialized()
}
/// Sets a callback to invoke when the channel terminates.
///
/// The channel calls `callback` after the reader observes its last element.
/// If the channel has already terminated, the channel invokes `callback`
/// immediately.
///
/// - Important: A source supports a single termination callback. Setting a
/// new callback replaces any previous one.
@inlinable
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
}
/// Creates an additional source for sending elements to the channel
/// concurrently from multiple producers.
@inlinable
public mutating func clone() -> sending Self {
.init(storage: self._storage)
}
/// Terminates the channel with the supplied error.
///
/// After the reader consumes all buffered elements, the next call to
/// ``MultiProducerSingleConsumerAsyncChannel/read(body:)`` throws `error`.
/// This path delivers no ``FinalElement`` payload to the reader.
///
/// To terminate the channel cleanly with an end-of-stream payload, call
/// ``finish(finalElement:)`` instead. When ``FinalElement`` is `Void`,
/// you can also call the ``finish()`` convenience.
@inlinable
public consuming func finish(throwing error: Failure) {
self._storage.finish(throwing: error, finalElement: nil)
}
/// Finishes the channel with a ``FinalElement`` payload.
///
/// The reader observes end-of-stream as a non-`nil` `finalElement`
/// argument to the body of its next
/// ``MultiProducerSingleConsumerAsyncChannel/read(body:)`` call. The
/// channel delivers any elements still buffered from earlier
/// ``write(buffer:)`` calls before the terminator.
///
/// - Note: This method delivers only the end-of-stream signal. To send a
/// final batch of elements alongside the terminator, call
/// ``write(buffer:)`` first and then ``finish(finalElement:)``.
@inlinable
public consuming func finish(finalElement: consuming sending FinalElement) {
self._storage.finish(throwing: nil, finalElement: finalElement)
}
/// Writes every element of `buffer` to the channel.
///
/// On success the call drains `buffer` completely. If the channel's
/// backpressure strategy signals that production should pause, the call
/// suspends until the reader drains enough of the channel to fall below
/// the low watermark.
///
/// - Throws: ``MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError``
/// if the channel has already finished, or `CancellationError` if the
/// task is canceled while suspended on backpressure.
@inlinable
public mutating func write<Buffer: RangeReplaceableContainer<Element> & ~Copyable & Sendable>(
buffer: inout sending Buffer
) async throws {
let sendResult: _SendResult
do {
sendResult = try self._storage.write(buffer: &buffer)
} catch {
throw error
}
switch consume sendResult {
case .produceMore:
return
case .enqueueCallback(let token):
let storage = self._storage
do {
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Void, any Error>) in
storage.enqueueProducer(callbackToken: token, continuation: continuation)
}
} onCancel: {
storage.cancelProducer(callbackToken: token)
}
} catch {
throw error
}
}
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel.Source where FinalElement == Void {
/// Finishes the channel with an empty `Void` end-of-stream payload.
///
/// This method is equivalent to calling ``finish(finalElement:)`` with
/// `()`. The reader observes end-of-stream as a non-`nil`
/// `finalElement` argument to the body of its next read.
@inlinable
public consuming func finish() {
self._storage.finish(throwing: nil, finalElement: ())
}
}
// MARK: - Reading
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// Reads the next chunk of elements from the channel.
///
/// The channel passes the buffered elements to `body` along with an
/// optional ``FinalElement`` payload. A non-`nil` `finalElement` marks
/// the chunk as terminal and delivers the end-of-stream signal. The
/// terminal chunk's buffer may be empty or contain a final batch of
/// elements.
///
/// - Throws: An ``EitherError`` whose outer `.first` arm carries a
/// read-side error — either the channel's `Failure` (when a producer
/// called ``Source/finish(throwing:)``) or a `CancellationError` (when
/// the task is canceled while suspended in `read`) — and whose outer
/// `.second` arm carries the failure thrown by `body`.
///
/// - Important: After the reader observes a non-`nil` `finalElement`,
/// calling `read(body:)` again is a programmer error.
@inlinable
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
) async throws(EitherError<EitherError<Failure, CancellationError>, BodyFailure>) -> Return {
while true {
let action = self.storage.readAvailable()
switch consume action {
case .returnElements(let disconnected):
var buffer = disconnected.take()
let result: Return
do throws(BodyFailure) {
result = try await body(&buffer, nil)
// TODO: This should not be necessary
nonisolated(unsafe) let buffer = buffer
self.storage.returnCachedReadBuffer(buffer)
} catch {
// TODO: This should not be necessary
nonisolated(unsafe) let buffer = buffer
self.storage.returnCachedReadBuffer(buffer)
throw .second(error)
}
return result
case .returnElementsAndResumeProducers(let disconnected, let producers):
var buffer = disconnected.take()
for producer in producers {
switch producer {
case .closure(let onProduceMore):
onProduceMore(Result<Void, any Error>.success(()))
case .continuation(let continuation):
continuation.resume()
}
}
let result: Return
do throws(BodyFailure) {
result = try await body(&buffer, nil)
// TODO: This should not be necessary
nonisolated(unsafe) let buffer = buffer
self.storage.returnCachedReadBuffer(buffer)
} catch {
// TODO: This should not be necessary
nonisolated(unsafe) let buffer = buffer
self.storage.returnCachedReadBuffer(buffer)
throw .second(error)
}
return result
case .returnTerminalChunk(let disconnectedBuffer, let disconnectedFinal, let onTerminations):
for (_, callback) in onTerminations { callback() }
var buffer = disconnectedBuffer.take()
let final = disconnectedFinal.take()
do throws(BodyFailure) {
return try await body(&buffer, final)
} catch {
throw .second(error)
}
case .throwFailure(let failure, let onTerminations):
for (_, callback) in onTerminations { callback() }
if let failure {
throw .first(.first(failure))
}
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .returnNil:
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .suspend:
do {
try await self.storage.suspendRead()
} catch {
throw .first(error)
}
continue
}
}
}
}
/// An error that ``MultiProducerSingleConsumerAsyncChannel/Source/write(buffer:)``
/// throws when its source has already finished.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error {
@usableFromInline
init() {}
}
#endif
File diff suppressed because it is too large. Load diff
@@ -962,7 +962,7 @@ final class MultiProducerSingleConsumerAsyncChannelTests: XCTestCase {
_ = await iterator.next(isolation: nil)
}
func testWatermarWithLotsOfElements() async throws {
func testWatermarkWithLotsOfElements() async throws {
await withThrowingTaskGroup(of: Void.self) { group in
// This test should in the future use a custom task executor to schedule to avoid sending
// 1000 elements.
@@ -971,7 +971,7 @@ final class MultiProducerSingleConsumerAsyncChannelTests: XCTestCase {
backpressureStrategy: .watermark(low: 2, high: 4)
)
let channel = channelAndSource.takeChannel()
var source: MultiProducerSingleConsumerAsyncChannel.Source! = consume channelAndSource.source
var source: MultiProducerSingleConsumerAsyncChannel.Source? = consume channelAndSource.source
group.addTask {
var source = source.take()!
@@ -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,117 @@
//===----------------------------------------------------------------------===//
//
// 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 AsyncAlgorithms
import XCTest
#if compiler(>=6.0)
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
final class TestMapError: XCTestCase {
func test_mapError() async throws {
let array: [Any] = [1, 2, 3, MyAwesomeError.originalError, 4, 5, 6]
let sequence = array.async
.map {
if let error = $0 as? Error {
throw error
} else {
$0 as! Int
}
}
.mapError { _ in
MyAwesomeError.mappedError
}
var results: [Int] = []
do {
for try await number in sequence {
results.append(number)
}
XCTFail("sequence should throw")
} catch {
XCTAssertEqual(error, .mappedError)
}
XCTAssertEqual(results, [1, 2, 3])
}
func test_mapError_cancellation() async throws {
let value = "test"
let source = Indefinite(value: value).async
let sequence =
source
.map {
if $0 == "just to trick compiler that this may throw" {
throw MyAwesomeError.originalError
} else {
$0
}
}
.mapError { _ in
MyAwesomeError.mappedError
}
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
for try await el in sequence {
XCTAssertEqual(el, value)
if !firstIteration {
firstIteration = true
iterated.fulfill()
}
}
finished.fulfill()
}
// ensure the other task actually starts
await fulfillment(of: [iterated], timeout: 1.0)
// cancellation should ensure the loop finishes
// without regards to the remaining underlying sequence
task.cancel()
await fulfillment(of: [finished], timeout: 1.0)
}
func test_mapError_empty() async throws {
let array: [String] = []
let sequence = array.async
.map {
if $0 == "just to trick compiler that this may throw" {
throw MyAwesomeError.originalError
} else {
$0
}
}
.mapError { _ in
MyAwesomeError.mappedError
}
var results: [String] = []
for try await value in sequence {
results.append(value)
}
XCTAssert(results.isEmpty)
}
}
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
extension TestMapError {
fileprivate enum MyAwesomeError: Error {
case originalError
case mappedError
}
}
#endif
@@ -27,6 +27,34 @@ final class TestReductions: XCTestCase {
XCTAssertNil(pastEnd)
}
func test_reductions_empty() async {
let sequence = [Int]().async.reductions("") { partial, value in
partial + "\(value)"
}
var iterator = sequence.makeAsyncIterator()
var collected = [String]()
while let item = await iterator.next() {
collected.append(item)
}
XCTAssertEqual(collected, [])
let pastEnd = await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_reductions_empty() async throws {
let sequence = [Int]().async.reductions("") { (partial, value) throws -> String in
partial + "\(value)"
}
var iterator = sequence.makeAsyncIterator()
var collected = [String]()
while let item = try await iterator.next() {
collected.append(item)
}
XCTAssertEqual(collected, [])
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_inclusive_reductions() async {
let sequence = [1, 2, 3, 4].async.reductions { $0 + $1 }
var iterator = sequence.makeAsyncIterator()
@@ -130,6 +130,55 @@ final class TestShare: XCTestCase {
XCTAssertEqual(results2.withLock { $0 }.sorted(), [1, 2, 3, 4, 5])
}
func test_share_with_no_buffering() async {
let shared = [1, 2, 3, 4, 5].async.share(bufferingPolicy: .bounded(0))
let expectation1 = XCTestExpectation(description: "Consumer 1 finished looping")
let expectation2 = XCTestExpectation(description: "Consumer 2 finished looping")
let results1 = Mutex([Int]())
let results2 = Mutex([Int]())
let gate1 = Gate()
let gate2 = Gate()
let consumer1 = Task {
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
while let value = await iterator.next(isolation: nil) {
results1.withLock { $0.append(value) }
// Add some delay to consumer 1
try? await Task.sleep(for: .milliseconds(1))
}
expectation1.fulfill()
}
let consumer2 = Task {
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
while let value = await iterator.next(isolation: nil) {
results2.withLock { $0.append(value) }
}
expectation2.fulfill()
}
await fulfillment(of: [expectation1, expectation2], timeout: 5)
await consumer1.value
await consumer2.value
// Both consumers should receive all elements
XCTAssertEqual(results1.withLock { $0 }.sorted(), [1, 2, 3, 4, 5])
XCTAssertEqual(results2.withLock { $0 }.sorted(), [1, 2, 3, 4, 5])
}
func test_share_with_no_buffering_multiple() async {
for _ in 0..<10 {
await test_share_with_no_buffering()
}
}
func test_share_with_unbounded_buffering() async {
let source = [1, 2, 3, 4, 5]
let shared = source.async.share(bufferingPolicy: .unbounded)
@@ -0,0 +1,172 @@
//===----------------------------------------------------------------------===//
//
// 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 AsyncReaderCollectIntoTests {
@Test
func collectFillsTargetWhenReaderHasFewerElements() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var target = RigidArray<Int>(capacity: 10)
try await reader.collect(into: &target)
var collected: [Int] = []
var c = target.consumeAll()
while let v = c.next() { collected.append(v) }
#expect(collected == [1, 2, 3])
}
@Test
func collectFillsTargetWhenReaderHasExactlyFreeCapacityElements() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var target = RigidArray<Int>(capacity: 3)
try await reader.collect(into: &target)
#expect(target.count == 3)
}
@Test
func collectThrowsWhenReaderProducesMoreThanFreeCapacity() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
var target = RigidArray<Int>(capacity: 2)
do {
try await reader.collect(into: &target)
Issue.record("Expected error")
} catch {
let expected = EitherError<Never, AsyncReaderLeftOverElementsError>.second(AsyncReaderLeftOverElementsError())
#expect(error == expected)
}
}
@Test
func collectIntoEmptyReader() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
var target = RigidArray<Int>(capacity: 5)
try await reader.collect(into: &target)
#expect(target.count == 0)
}
}
@Suite
struct AsyncReaderCollectExactlyTests {
@Test
func collectExactlyFillsTargetWhenReaderProducesExactCount() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var target = RigidArray<Int>(capacity: 3)
try await reader.collect(exactlyInto: &target)
var collected: [Int] = []
var c = target.consumeAll()
while let v = c.next() { collected.append(v) }
#expect(collected == [1, 2, 3])
}
@Test
func collectExactlyThrowsWhenReaderProducesFewer() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var target = RigidArray<Int>(capacity: 5)
do {
try await reader.collect(exactlyInto: &target)
Issue.record("Expected error")
} catch {
let expected = EitherError<
Never,
EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
>.second(.second(AsyncReaderInsufficientElementsError()))
#expect(error == expected)
}
}
@Test
func collectExactlyThrowsWhenReaderProducesMore() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
var target = RigidArray<Int>(capacity: 2)
do {
try await reader.collect(exactlyInto: &target)
Issue.record("Expected error")
} catch {
let expected = EitherError<
Never,
EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
>.second(.first(AsyncReaderLeftOverElementsError()))
#expect(error == expected)
}
}
}
@Suite
struct AsyncReaderCollectIntoMaximumSizeTests {
@Test
func collectGrowsContainerWhenReaderHasFewerThanMaximum() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var target = UniqueArray<Int>()
try await reader.collect(into: &target, maximumSize: 10)
var collected: [Int] = []
var c = target.consumeAll()
while let v = c.next() { collected.append(v) }
#expect(collected == [1, 2, 3])
}
@Test
func collectFillsContainerExactlyAtMaximum() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
var target = UniqueArray<Int>()
try await reader.collect(into: &target, maximumSize: 3)
#expect(target.count == 3)
}
@Test
func collectThrowsWhenReaderProducesMoreThanMaximum() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
var target = UniqueArray<Int>()
do {
try await reader.collect(into: &target, maximumSize: 2)
Issue.record("Expected error")
} catch {
let expected = EitherError<Never, AsyncReaderLeftOverElementsError>.second(AsyncReaderLeftOverElementsError())
#expect(error == expected)
}
}
@Test
func collectAppendsToExistingContents() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 2, copying: [3, 4]))
var target = UniqueArray<Int>(capacity: 2, copying: [1, 2])
try await reader.collect(into: &target, maximumSize: 10)
var collected: [Int] = []
var c = target.consumeAll()
while let v = c.next() { collected.append(v) }
#expect(collected == [1, 2, 3, 4])
}
}
#endif
@@ -0,0 +1,140 @@
//===----------------------------------------------------------------------===//
//
// 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
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
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
func forEachBufferWithEmptyReader() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
var callCount = 0
await reader.forEachBuffer { buffer in
callCount += 1
}
// The reader signals end-of-stream with an empty buffer; body should not be called.
#expect(callCount == 0)
}
@Test
func forEachBufferDoesNotInvokeBodyWithEmptyTerminalBuffer() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
var observedCounts: [Int] = []
_ = await reader.forEachBuffer { buffer in
observedCounts.append(buffer.count)
}
#expect(observedCounts.allSatisfy { $0 > 0 })
}
@Test
func forEachBufferThrowingDoesNotInvokeBodyWithEmptyTerminalBuffer() async throws {
enum TestError: Error {}
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
var observedCounts: [Int] = []
_ = try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
observedCounts.append(buffer.count)
}
#expect(observedCounts.allSatisfy { $0 > 0 })
}
@Test
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
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
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,162 @@
//===----------------------------------------------------------------------===//
//
// 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 AsyncReaderPipeTests {
// MARK: - pipe(into:) — into a CallerAsyncWriter
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoCopiesAllElements() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
var array = UniqueArray(copying: [1, 2, 3, 4, 5])
try await writerA.write(buffer: &array)
writerA.finish()
try await readerB.pipe(into: writerB)
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoWithEmptyReader() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { writerA, readerA, writerB, readerB in
let writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
writerA.finish()
try await readerB.pipe(into: writerB)
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoPreservesElementOrder() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 16, high: 100)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
let elements = Array(1...50)
var array = UniqueArray(copying: elements)
try await writerA.write(buffer: &array)
writerA.finish()
try await readerB.pipe(into: writerB)
var target = RigidArray<Int>(capacity: 50)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == elements)
}
}
// MARK: - pipe(copyingInto:) — into an AsyncWriter via the adapter
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeCopyingIntoCopiesAllElements() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
var array = UniqueArray(copying: [1, 2, 3, 4, 5])
try await writerA.write(buffer: &array)
writerA.finish()
try await readerB.pipe(copyingInto: writerB.asAsyncWriter())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeCopyingIntoWithEmptyReader() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { writerA, readerA, writerB, readerB in
let writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
writerA.finish()
try await readerB.pipe(copyingInto: writerB.asAsyncWriter())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeCopyingIntoChunksTerminalChunkAcrossMultipleWrites() async throws {
// 200 elements through a small (16-element) AsyncWriter buffer
// forces the pipe loop to drain across multiple writes.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 32, high: 256)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
let readerA = readerA
let writerB = writerB
let readerB = readerB
let elements = Array(1...200)
var array = UniqueArray(copying: elements)
try await writerA.write(buffer: &array)
writerA.finish()
try await readerB.pipe(copyingInto: writerB.asAsyncWriter(initialCapacity: 16))
var target = RigidArray<Int>(capacity: 200)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == elements)
}
}
}
#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 AsyncReaderTests {
@Test
func read() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
var observedFinal = false
let result: UniqueArray<Int> = try! await reader.read { (buffer, finalElement) in
observedFinal = finalElement != nil
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)
#expect(observedFinal)
}
@Test
func readDeliversTerminator() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var observedFinal = false
let count: Int = try! await reader.read { (buffer, finalElement) in
observedFinal = finalElement != nil
return buffer.count
}
#expect(count == 3)
#expect(observedFinal)
}
}
#endif
@@ -0,0 +1,118 @@
//===----------------------------------------------------------------------===//
//
// 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 AsyncWriterCallerAsyncWriterAdapterTests {
// The adapter wraps an AsyncWriter and exposes a CallerAsyncWriter.
// We can't get an AsyncWriter from the duplex directly (its Writer is
// a CallerAsyncWriter), so we wrap the duplex's Writer first via
// asAsyncWriter() to get an AsyncWriter, then wrap THAT via
// asCallerAsyncWriter() to exercise this adapter end-to-end.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeAndFinishRoundTrip() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
var callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
var buf = UniqueArray(copying: [1, 2, 3])
try await callerWriter.write(buffer: &buf)
var empty = UniqueArray<Int>()
try await callerWriter.finish(buffer: &empty, finalElement: ())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(Array(draining: &target) == [1, 2, 3])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeLoopsAcrossMultipleUnderlyingBuffers() async throws {
// The CallerAsyncWriterAsyncWriterAdapter underneath uses a
// 4096-element default buffer. We use a small initialCapacity to
// force the inverse adapter to drive multiple underlying writes.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 32, high: 256)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
var callerWriter =
writerB
.asAsyncWriter(initialCapacity: 16)
.asCallerAsyncWriter()
let elements = Array(1...100)
var buf = UniqueArray(copying: elements)
try await callerWriter.write(buffer: &buf)
var empty = UniqueArray<Int>()
try await callerWriter.finish(buffer: &empty, finalElement: ())
var target = RigidArray<Int>(capacity: 100)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == elements)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func finishWithoutWriteDeliversEmptyTerminator() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
var empty = UniqueArray<Int>()
try await callerWriter.finish(buffer: &empty, finalElement: ())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func finishDeliversTrailingBufferAndPayload() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
var trailing = UniqueArray(copying: [42, 43, 44])
try await callerWriter.finish(buffer: &trailing, finalElement: ())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(Array(draining: &target) == [42, 43, 44])
}
}
}
#endif
@@ -0,0 +1,110 @@
//===----------------------------------------------------------------------===//
//
// 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
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
func writeEmptyBuffer() async {
var writer = UniqueArrayAsyncWriter()
try! await writer.write { _ in }
#expect(writer.storage.count == 0)
}
@Test
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
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
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)
}
@Test
func finishVoidConvenience() async {
let writer = UniqueArrayAsyncWriter()
await writer.finish()
}
@Test
func finishDeliversFinalElement() async {
let writer = UniqueArrayAsyncWriter()
await writer.finish(finalElement: ())
}
}
#endif
@@ -0,0 +1,152 @@
//===----------------------------------------------------------------------===//
//
// 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 CallerAsyncReaderPipeTests {
// MARK: - pipe(into:) — into an AsyncWriter via the adapter
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoCopiesAllElements() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let source = UniqueArrayCallerAsyncReader(
storage: UniqueArray(copying: [1, 2, 3, 4, 5])
)
try await source.pipe(into: writerB.asAsyncWriter())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoWithEmptyReader() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let source = UniqueArrayCallerAsyncReader(storage: UniqueArray<Int>())
try await source.pipe(into: writerB.asAsyncWriter())
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeIntoLoopsAcrossMultipleBuffers() async throws {
// 200 elements through a small AsyncWriter buffer forces the pipe
// loop to iterate multiple times.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 32, high: 256)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let elements = Array(1...200)
let source = UniqueArrayCallerAsyncReader(
storage: UniqueArray(copying: elements)
)
try await source.pipe(into: writerB.asAsyncWriter(initialCapacity: 16))
var target = RigidArray<Int>(capacity: 200)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == elements)
}
}
// MARK: - pipe(bufferingInto:) — into a CallerAsyncWriter
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeBufferingIntoCopiesAllElements() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let source = UniqueArrayCallerAsyncReader(
storage: UniqueArray(copying: [1, 2, 3, 4, 5])
)
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeBufferingIntoWithEmptyReader() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let source = UniqueArrayCallerAsyncReader(storage: UniqueArray<Int>())
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func pipeBufferingIntoReusesIntermediateBufferAcrossMultipleIterations() async throws {
// 100 elements through a 16-element intermediate buffer forces the
// pipe loop to iterate the buffer many times.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 16, high: 200)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let elements = Array(1...100)
let source = UniqueArrayCallerAsyncReader(
storage: UniqueArray(copying: elements)
)
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
var target = RigidArray<Int>(capacity: 100)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == elements)
}
}
}
#endif
@@ -0,0 +1,85 @@
//===----------------------------------------------------------------------===//
//
// 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
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
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
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
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)
}
}
#endif
@@ -0,0 +1,130 @@
//===----------------------------------------------------------------------===//
//
// 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 CallerAsyncWriterAsyncWriterAdapterTests {
// The adapter wraps a CallerAsyncWriter and exposes an AsyncWriter, so
// we drive it through the duplex's CallerAsyncWriter side and verify
// the elements arrive on the peer reader.
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeAndFinishRoundTrip() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
var asyncWriter = writerB.asAsyncWriter()
try await asyncWriter.write { buffer in
buffer.append(1)
buffer.append(2)
buffer.append(3)
}
try await asyncWriter.finish()
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(Array(draining: &target) == [1, 2, 3])
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func multipleWritesAreFlushedEagerly() async throws {
// The adapter must NOT defer the most recent write — each write call
// should flush before returning, so the peer can observe progress
// before close. We verify by reading back after each write.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
var readerA = readerA
let writerB = writerB
var asyncWriter = writerB.asAsyncWriter()
try await asyncWriter.write { $0.append(10) }
// Reader sees the first write before any second write or finish.
try await readerA.read { buffer, _ in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 10)
}
try await asyncWriter.write { $0.append(20) }
try await readerA.read { buffer, _ in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 20)
}
try await asyncWriter.finish()
try await readerA.read { buffer, finalElement in
#expect(buffer.count == 0)
#expect(finalElement != nil)
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func finishWithoutWriteDeliversEmptyTerminator() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
let asyncWriter = writerB.asAsyncWriter()
try await asyncWriter.finish()
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(into: &target)
#expect(target.count == 0)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func customBufferTypePreservesElements() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 8, high: 32)
) { _, readerA, writerB, _ in
let readerA = readerA
let writerB = writerB
var asyncWriter = writerB.asAsyncWriter(
bufferOf: UniqueArray<Int>.self,
initialCapacity: 16
)
try await asyncWriter.write { buffer in
for v in 1...5 { buffer.append(v) }
}
try await asyncWriter.finish()
var target = RigidArray<Int>(capacity: 5)
try await readerA.collect(exactlyInto: &target)
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
}
}
}
#endif
@@ -0,0 +1,50 @@
//===----------------------------------------------------------------------===//
//
// 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
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
func writeEmptyBuffer() async {
var writer = UniqueArrayCallerAsyncWriter()
var data = UniqueArray<Int>()
await writer.write(buffer: &data)
#expect(writer.storage.count == 0)
}
@Test
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,527 @@
//===----------------------------------------------------------------------===//
//
// 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 DequeModule
import Testing
@Suite(.serialized)
struct DuplexAsyncChannelTests {
// MARK: - Round-trip
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func roundTripForwardDirection() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 10)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerB = readerB
var buf = UniqueArray<Int>(minimumCapacity: 5)
for v in [1, 2, 3, 4, 5] { buf.append(v) }
try await writerA.write(buffer: &buf)
try await readerB.read { buffer, _ in
#expect(buffer.count == 5)
var c = buffer.consumeAll()
var collected: [Int] = []
while let v = c.next() { collected.append(v) }
#expect(collected == [1, 2, 3, 4, 5])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func roundTripReverseDirection() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 10)
) { writerA, readerA, writerB, readerB in
var readerA = readerA
var writerB = writerB
var buf = UniqueArray<Int>(minimumCapacity: 3)
for v in [10, 20, 30] { buf.append(v) }
try await writerB.write(buffer: &buf)
try await readerA.read { buffer, _ in
#expect(buffer.count == 3)
var c = buffer.consumeAll()
var collected: [Int] = []
while let v = c.next() { collected.append(v) }
#expect(collected == [10, 20, 30])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func directionsAreIndependent() async throws {
// Bytes sent on the forward direction must NOT appear on the side that
// sent them.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerA = readerA
var writerB = writerB
var readerB = readerB
var fwdBuf = UniqueArray<Int>(minimumCapacity: 1)
fwdBuf.append(1)
try await writerA.write(buffer: &fwdBuf)
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
revBuf.append(99)
try await writerB.write(buffer: &revBuf)
// readerB sees the forward write.
try await readerB.read { buffer, _ in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 1)
}
// readerA sees the reverse write, and only that.
try await readerA.read { buffer, _ in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 99)
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func concurrentReadsOnBothDirections() async throws {
try await withThrowingTaskGroup(of: [Int].self) { group in
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 20)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerA = readerA
var writerB = writerB
var readerB = readerB
group.addTask {
var collected: [Int] = []
var done = false
while !done {
try await readerA.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
if finalElement != nil { done = true }
}
}
return collected
}
// Forward: write 0..<10 from main scope.
var fwd = UniqueArray<Int>(minimumCapacity: 10)
for i in 0..<10 { fwd.append(i) }
try await writerA.write(buffer: &fwd)
writerA.finish()
// Reverse: write 100..<110 from main scope.
var rev = UniqueArray<Int>(minimumCapacity: 10)
for i in 100..<110 { rev.append(i) }
try await writerB.write(buffer: &rev)
writerB.finish()
// Drain forward from the main scope.
var forwardCollected: [Int] = []
var done = false
while !done {
try await readerB.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { forwardCollected.append(v) }
if finalElement != nil { done = true }
}
}
#expect(forwardCollected == Array(0..<10))
let reverseCollected = try await group.next() ?? []
#expect(reverseCollected == Array(100..<110))
}
}
}
// MARK: - Half-close
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func finishingOneDirectionLeavesTheOtherOpen() async throws {
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerA = readerA
var writerB = writerB
var readerB = readerB
// Close forward direction.
var fwdBuf = UniqueArray<Int>(minimumCapacity: 1)
fwdBuf.append(7)
try await writerA.write(buffer: &fwdBuf)
writerA.finish()
// Reverse direction still works.
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
revBuf.append(8)
try await writerB.write(buffer: &revBuf)
// Forward EOS is fused with the buffered element on the same read.
var sawForwardFinal = false
try await readerB.read { buffer, finalElement in
#expect(buffer.count == 1)
if finalElement != nil { sawForwardFinal = true }
buffer.removeAll()
}
#expect(sawForwardFinal)
// Reverse still delivers elements after forward is closed.
try await readerA.read { buffer, finalElement in
#expect(buffer.count == 1)
#expect(finalElement == nil)
buffer.removeAll()
}
}
}
// MARK: - Final element
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func finalElementDeliveredOnFinish() async throws {
try await DuplexAsyncChannel<Int, String, Never>.withDuplex(
of: Int.self,
withFinalElement: String.self,
backpressureStrategy: .watermark(low: 2, high: 8)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerB = readerB
var buf = UniqueArray<Int>(minimumCapacity: 3)
for v in [1, 2, 3] { buf.append(v) }
try await writerA.write(buffer: &buf)
writerA.finish(finalElement: "trailers")
var collected: [Int] = []
var trailerSeen: String? = nil
var done = false
while !done {
try await readerB.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
if let f = finalElement {
trailerSeen = f
done = true
}
}
}
#expect(collected == [1, 2, 3])
#expect(trailerSeen == "trailers")
}
}
// MARK: - Failure isolation
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func failureOnOneDirectionDoesNotPoisonTheOther() async throws {
struct TestError: Error, Equatable {}
try await DuplexAsyncChannel<Int, Void, TestError>.withDuplex(
of: Int.self,
throwing: TestError.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerA = readerA
var writerB = writerB
var readerB = readerB
// Send a final element on reverse so we can verify it survives.
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
revBuf.append(42)
try await writerB.write(buffer: &revBuf)
writerB.finish()
// Fail forward direction.
writerA.finish(throwing: TestError())
// readerB sees the forward failure.
do {
try await readerB.read { _, _ in }
Issue.record("expected throw on forward direction")
} catch let EitherError<EitherError<TestError, CancellationError>, Never>.first(.first(err)) {
#expect(err == TestError())
} catch {
Issue.record("unexpected error: \(error)")
}
// readerA still gets the reverse element + EOS unaffected. The EOS
// is fused with the buffered element on the same read.
var sawFinal = false
try await readerA.read { buffer, finalElement in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 42)
if finalElement != nil { sawFinal = true }
}
#expect(sawFinal)
}
}
// MARK: - Backpressure isolation
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func backpressureOnOneDirectionDoesNotBlockTheOther() async throws {
// Forward writer is suspended on backpressure (writes more than the
// high watermark with no concurrent reader). Reverse must still
// accept writes and deliver them while forward is stuck.
try await withThrowingTaskGroup(of: Void.self) { group in
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerA = readerA
var writerB = writerB
var readerB = readerB
// Forward writer: 4 elements with high=2 → suspends mid-batch.
group.addTask {
var fwd = UniqueArray<Int>(minimumCapacity: 4)
for i in 0..<4 { fwd.append(i) }
try await writerA.write(buffer: &fwd)
}
// Even with forward backpressured, reverse fully works.
var rev = UniqueArray<Int>(minimumCapacity: 1)
rev.append(99)
try await writerB.write(buffer: &rev)
try await readerA.read { buffer, _ in
#expect(buffer.count == 1)
var c = buffer.consumeAll()
#expect(c.next() == 99)
}
// Drain forward (4 elements) so the suspended writer task can
// complete and we can join it before exiting the scope.
var collected: [Int] = []
while collected.count < 4 {
try await readerB.read { buffer, _ in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
}
}
#expect(collected == [0, 1, 2, 3])
try await group.waitForAll()
}
}
}
// MARK: - Multi-producer per direction
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func clonedWriterCanProduceConcurrently() async throws {
// Two writes happen sequentially through the original writer and its
// clone, demonstrating both share the same direction. We can't issue
// `finish()` from inside an escaping closure (it consumes the writer),
// so we keep the multi-producer demonstration sequential here.
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 50)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerB = readerB
_ = readerA
_ = writerB
var clone = writerA.clone()
var buf1 = UniqueArray<Int>(minimumCapacity: 5)
for v in 0..<5 { buf1.append(v) }
try await writerA.write(buffer: &buf1)
var buf2 = UniqueArray<Int>(minimumCapacity: 5)
for v in 100..<105 { buf2.append(v) }
try await clone.write(buffer: &buf2)
// Either writer can close the direction independently. The other
// writer is still alive but the channel is now finishing.
writerA.finish()
clone.finish()
nonisolated(unsafe) var collected = Set<Int>()
var done = false
while !done {
try await readerB.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.insert(v) }
if finalElement != nil { done = true }
}
}
#expect(collected == Set([0, 1, 2, 3, 4, 100, 101, 102, 103, 104]))
}
}
// MARK: - Body-error wrapping
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readBodyErrorsWrappedInSecond() async throws {
struct BodyError: Error, Equatable {}
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerB = readerB
_ = readerA
_ = writerB
var buf = UniqueArray<Int>(minimumCapacity: 1)
buf.append(1)
try await writerA.write(buffer: &buf)
do {
try await readerB.read { _, _ throws(BodyError) in
throw BodyError()
}
Issue.record("expected throw")
} catch let EitherError<EitherError<Never, CancellationError>, BodyError>.second(err) {
#expect(err == BodyError())
} catch {
Issue.record("unexpected error: \(error)")
}
}
}
// MARK: - Scope cleanup
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func scopeFinalizesBothDirectionsOnReturn() async throws {
nonisolated(unsafe) var aTerminated = false
nonisolated(unsafe) var bTerminated = false
await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { writerA, readerA, writerB, readerB in
writerA.setOnTerminationCallback { aTerminated = true }
writerB.setOnTerminationCallback { bTerminated = true }
_ = readerA
_ = readerB
}
#expect(aTerminated)
#expect(bTerminated)
}
// MARK: - Protocol conformance
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writerConformsToCallerAsyncWriter() async throws {
// Exercise CallerAsyncWriter.finish(buffer:finalElement:) by calling
// it through a generic function that only sees the protocol.
func finishViaProtocol<W: CallerAsyncWriter & ~Copyable>(
_ writer: consuming W,
finalElement: consuming W.FinalElement
) async throws(W.WriteFailure) where W.WriteElement == Int {
var buf = UniqueArray<Int>(minimumCapacity: 3)
buf.append(7)
buf.append(8)
buf.append(9)
try await writer.finish(buffer: &buf, finalElement: finalElement)
}
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 50)
) { writerA, readerA, writerB, readerB in
var readerB = readerB
_ = readerA
_ = writerB
try await finishViaProtocol(writerA, finalElement: ())
var collected: [Int] = []
var sawFinal = false
var done = false
while !done {
try await readerB.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
if finalElement != nil {
sawFinal = true
done = true
}
}
}
#expect(collected == [7, 8, 9])
#expect(sawFinal)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readerConformsToAsyncReader() async throws {
// Exercise AsyncReader.read through a generic function that only
// sees the protocol.
func readOneChunk<R: AsyncReader & ~Copyable & ~Escapable>(
_ reader: inout R
) async throws -> [Int] where R.ReadElement == Int, R.Buffer == UniqueDeque<Int> {
nonisolated(unsafe) var collected: [Int] = []
do throws(EitherError<R.ReadFailure, Never>) {
try await reader.read { (buffer: inout R.Buffer, _: consuming R.FinalElement?) in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
}
} catch {
// Swallow read-side errors for the test.
}
return collected
}
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 10)
) { writerA, readerA, writerB, readerB in
var writerA = writerA
var readerB = readerB
_ = readerA
_ = writerB
var buf = UniqueArray<Int>(minimumCapacity: 3)
for v in [11, 22, 33] { buf.append(v) }
try await writerA.write(buffer: &buf)
let collected = try await readOneChunk(&readerB)
#expect(collected == [11, 22, 33])
}
}
}
#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,51 @@
//===----------------------------------------------------------------------===//
//
// 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])
}
}
init<C: RangeReplaceableContainer<Element> & ~Copyable & ~Escapable>(draining container: inout C) {
self.init()
var consumer = container.consumeAll()
while let value = consumer.next() {
self.append(value)
}
}
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,40 @@
//===----------------------------------------------------------------------===//
//
// 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 UniqueArrayAsyncReader: ~Copyable, AsyncReader {
typealias ReadElement = Int
typealias Buffer = UniqueArray<Int>
typealias ReadFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didEmitFinal: Bool = false
mutating func read<Return: ~Copyable, Failure: Error>(
body: (inout UniqueArray<Int>, Void?) async throws(Failure) -> Return
) async throws(EitherError<Never, Failure>) -> Return {
precondition(!self.didEmitFinal, "read called after end-of-stream")
self.didEmitFinal = true
do {
var uniqueArray = self.storage.clone()
self.storage = .init()
return try await body(&uniqueArray, .some(()))
} catch {
throw .second(error)
}
}
}
#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)
import AsyncStreaming
import BasicContainers
import ContainersPreview
struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
typealias WriteElement = Int
typealias Buffer = UniqueArray<Int>
typealias WriteFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didFinish: Bool = false
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
}
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)
}
}
consuming func finish(
finalElement: consuming Void
) async throws(Never) {
self.didFinish = true
}
}
#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
struct UniqueArrayCallerAsyncReader: ~Copyable, CallerAsyncReader {
typealias ReadElement = Int
typealias ReadFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var position: Int = 0
var didEmitFinal: Bool = false
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) -> Void? where Buffer.Element: ~Copyable {
precondition(!self.didEmitFinal, "read called after end-of-stream")
let count = min(buffer.freeCapacity, storage.count - position)
for i in 0..<count {
buffer.append(storage[position + i])
}
position += count
if position >= storage.count {
self.didEmitFinal = true
return .some(())
}
return nil
}
}
#endif
@@ -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
struct WriterCapacityError: Error {}
struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
typealias WriteElement = Int
typealias WriteFailure = Never
typealias FinalElement = Void
var storage: UniqueArray<Int>
var didFinish: Bool = false
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
}
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
self.storage.reserveCapacity(buffer.count)
var consumer = buffer.consumeAll()
while let element = consumer.next() {
self.storage.append(element)
}
}
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer,
finalElement: consuming Void
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
self.storage.reserveCapacity(buffer.count)
var consumer = buffer.consumeAll()
while let element = consumer.next() {
self.storage.append(element)
}
self.didFinish = true
}
}
#endif
@@ -0,0 +1,490 @@
//===----------------------------------------------------------------------===//
//
// 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 DequeModule
import Testing
@Suite(.serialized)
struct MultiProducerSingleConsumerAsyncChannelTests {
// MARK: - AsyncReader.read
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readReturnsAllBufferedElementsInOrder() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 10)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
for v in [1, 2, 3, 4, 5] { writeBuffer.append(v) }
try await source.write(buffer: &writeBuffer)
try await channel.read { buffer, _ in
#expect(buffer.count == 5)
var consumer = buffer.consumeAll()
var actual: [Int] = []
while let v = consumer.next() { actual.append(v) }
#expect(actual == [1, 2, 3, 4, 5])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readSuspendsUntilElementArrives() async throws {
try await withThrowingTaskGroup(of: [Int].self) { group in
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { channel, source in
var channel = channel
var source = source
group.addTask {
var collected: [Int] = []
try await channel.read { buffer, _ in
var consumer = buffer.consumeAll()
while let v = consumer.next() { collected.append(v) }
}
return collected
}
try await Task.sleep(nanoseconds: 10_000_000)
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(42)
try await source.write(buffer: &writeBuffer)
let result = try await group.next()
#expect(result == [42])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readReturnsEmptyBufferOnEOSAfterFinish() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(1)
try await source.write(buffer: &writeBuffer)
source.finish()
try await channel.read { buffer, _ in
#expect(buffer.count == 1)
buffer.removeAll()
}
var sawEmpty = false
try await channel.read { buffer, _ in
sawEmpty = buffer.count == 0
}
#expect(sawEmpty)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readThrowsFailureAfterFinishWithError() async throws {
struct TestError: Error, Equatable {}
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
throwing: TestError.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(1)
try await source.write(buffer: &writeBuffer)
source.finish(throwing: TestError())
// First read still delivers the buffered element.
try? await channel.read { buffer, _ in
#expect(buffer.count == 1)
buffer.removeAll()
}
// Second read throws the queued failure through EitherError.first.
do {
try await channel.read { _, _ in }
Issue.record("expected throw")
} catch let EitherError<EitherError<TestError, CancellationError>, Never>.first(.first(err)) {
#expect(err == TestError())
} catch {
Issue.record("unexpected error: \(error)")
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readBodyErrorsWrappedInSecond() async throws {
struct BodyError: Error, Equatable {}
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(1)
try await source.write(buffer: &writeBuffer)
do {
try await channel.read { _, _ throws(BodyError) in
throw BodyError()
}
Issue.record("expected throw")
} catch let EitherError<EitherError<Never, CancellationError>, BodyError>.second(err) {
#expect(err == BodyError())
} catch {
Issue.record("unexpected error: \(error)")
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readPartialConsumptionRemainsVisibleOnNextRead() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 10)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
for v in [1, 2, 3, 4, 5] { writeBuffer.append(v) }
try await source.write(buffer: &writeBuffer)
try await channel.read { buffer, _ in
var consumer = buffer.consumeFirst(2)
#expect(consumer.next() == 1)
#expect(consumer.next() == 2)
}
try await channel.read { buffer, _ in
#expect(buffer.count == 3)
var consumer = buffer.consumeAll()
var collected: [Int] = []
while let v = consumer.next() { collected.append(v) }
#expect(collected == [3, 4, 5])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readResumesSuspendedProducersWhenWaterLevelDrops() async throws {
try await withThrowingTaskGroup(of: Void.self) { group in
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
) { channel, source in
var channel = channel
var source = source
group.addTask {
// Fill to exactly the high watermark - this write suspends.
var firstBatch = UniqueArray<Int>(minimumCapacity: 4)
for v in [1, 2, 3, 4] { firstBatch.append(v) }
try await source.write(buffer: &firstBatch)
// Then send the 5th element once backpressure is relieved.
var secondBatch = UniqueArray<Int>(minimumCapacity: 1)
secondBatch.append(5)
try await source.write(buffer: &secondBatch)
}
// Wait until the producer suspends after appending the first batch.
try await Task.sleep(nanoseconds: 10_000_000)
// Drain the buffered elements - the water level drops below the low
// watermark and wakes the producer.
try await channel.read { buffer, _ in
#expect(buffer.count == 4)
buffer.removeAll()
}
try await group.next()
// The 5th element produced after the producer resumed.
try await channel.read { buffer, _ in
#expect(buffer.count == 1)
buffer.removeAll()
}
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readWaterLevelForElementCalledPerElementInBatch() async throws {
nonisolated(unsafe) var callCount = 0
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(
low: 5,
high: 100,
waterLevelForElement: { _ in
callCount += 1
return 1
}
)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 4)
for v in [1, 2, 3, 4] { writeBuffer.append(v) }
try await source.write(buffer: &writeBuffer)
let afterSend = callCount
try await channel.read { buffer, _ in
#expect(buffer.count == 4)
buffer.removeAll()
}
// Called once per element on send, once per element on consume.
#expect(afterSend == 4)
#expect(callCount == 8)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readBufferIsReusedAcrossReads() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 100)
) { channel, source in
var channel = channel
var source = source
// The channel alternates two internal buffers across reads (swap
// design): on each read the producer-side buffer is handed to the
// reader and the previously-handed-back buffer becomes the new
// producer-side. Verify that two reads of the same size land on
// matching capacities, i.e. the channel is reusing storage rather than
// allocating a fresh buffer per read.
var firstBatch = UniqueArray<Int>(minimumCapacity: 10)
for v in 0..<10 { firstBatch.append(v) }
try await source.write(buffer: &firstBatch)
nonisolated(unsafe) var firstCapacity = 0
try await channel.read { buffer, _ in
firstCapacity = buffer.capacity
var c = buffer.consumeAll()
while c.next() != nil {}
}
#expect(firstCapacity >= 10)
// Second read of the same size lands on the alternate buffer; after
// the first round trip both buffers have grown to at least the
// workload's capacity, so this read should see at least as much.
var secondBatch = UniqueArray<Int>(minimumCapacity: 10)
for v in 0..<10 { secondBatch.append(v) }
try await source.write(buffer: &secondBatch)
try await channel.read { buffer, _ in
#expect(buffer.capacity >= firstCapacity)
var c = buffer.consumeAll()
while c.next() != nil {}
}
// A third read of the same size should reuse the original buffer
// (capacity matches first read's exactly).
var thirdBatch = UniqueArray<Int>(minimumCapacity: 10)
for v in 0..<10 { thirdBatch.append(v) }
try await source.write(buffer: &thirdBatch)
try await channel.read { buffer, _ in
#expect(buffer.capacity == firstCapacity)
var c = buffer.consumeAll()
while c.next() != nil {}
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readDeliversFinalElementOnFinish() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 8)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 3)
for v in [1, 2, 3] { writeBuffer.append(v) }
try await source.write(buffer: &writeBuffer)
source.finish()
nonisolated(unsafe) var collected: [Int] = []
var sawFinal = false
var done = false
while !done {
try await channel.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
if finalElement != nil {
sawFinal = true
done = true
}
}
}
#expect(collected == [1, 2, 3])
#expect(sawFinal)
}
}
// MARK: - CallerAsyncWriter.write
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeAppendsAllElementsAndClearsBuffer() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 5, high: 100)
) { channel, source in
var channel = channel
var source = source
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
writeBuffer.append(10)
writeBuffer.append(20)
writeBuffer.append(30)
try await source.write(buffer: &writeBuffer)
#expect(writeBuffer.count == 0, "write should drain the caller's buffer")
try await channel.read { buffer, _ in
#expect(buffer.count == 3)
var c = buffer.consumeAll()
var collected: [Int] = []
while let v = c.next() { collected.append(v) }
#expect(collected == [10, 20, 30])
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeAfterFinishThrows() async throws {
await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 4)
) { channel, source in
var channel = channel
var source = source
// Keep an additional source around so we can attempt a write after the
// channel has been finished by consuming the first source.
var extraSource = source.clone()
source.finish()
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(1)
do {
try await extraSource.write(buffer: &writeBuffer)
Issue.record("expected throw")
} catch is MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError {
// expected
} catch {
Issue.record("unexpected error: \(error)")
}
// Drain anything still buffered before exiting the scope.
try? await channel.read { _, _ in }
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeSuspendsOnBackpressureAndResumesAfterRead() async throws {
try await withThrowingTaskGroup(of: Void.self) { group in
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
var source = source
group.addTask {
// Reader drains until EOS.
while true {
var done = false
try await channel.read { buffer, _ in
if buffer.count == 0 {
done = true
} else {
buffer.removeAll()
}
}
if done { break }
}
}
var buf = UniqueArray<Int>(minimumCapacity: 4)
for i in 0..<4 { buf.append(i) }
try await source.write(buffer: &buf)
source.finish()
try await group.next()
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func writeReadRoundtripPreservesOrder() async throws {
let total = 100
try await withThrowingTaskGroup(of: Void.self) { group in
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 10, high: 50)
) { channel, source in
var channel = channel
var source = source
group.addTask {
nonisolated(unsafe) var collected: [Int] = []
var done = false
while !done {
try await channel.read { buffer, _ in
if buffer.count == 0 {
done = true
} else {
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
}
}
}
#expect(collected == Array(0..<total))
}
for start in stride(from: 0, to: total, by: 10) {
var buf = UniqueArray<Int>(minimumCapacity: 10)
for i in start..<(start + 10) { buf.append(i) }
try await source.write(buffer: &buf)
}
source.finish()
try await group.next()
}
}
}
}
#endif