Compare commits

..
27 Commits
Author SHA1 Message Date
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
Joseph Heck 2773d41253 This removes the build constraint at Swift Package Index from Swift 5.8 so that (#377)
symbols that are only available in later versions (for example, MultiProducerSingleConsumerAsyncChannel)
are reflected in the hosted documentation.
2025-11-19 22:22:29 +01:00
Franz BuschandJoe Heck 4686d2edd3 Add MultiProducerSingleConsumerChannel (#305)
* Add `AsyncBackpressuredStream` proposal and implementation

# Motivation

The pitch to add external backpressure support to the standard libraries `AsyncStream` got returned for revision since there are larger open questions around `AsyncSequence`. However, having external backpressure in a source asynchronous sequence is becoming more and more important.

# Modification

This PR adds a modified proposal and implementation that brings the Swift Evolution proposal over to Swift Async Algorithms.

* Update proposal and implementation

* Update proposal

* Add example project

* Formatting

* Fix Swift 6.0 build

* Future direction for ~Copyable elements

* Apply formatting

* Fix CI

* Move to 6.1 and update proposal

* Guard tests

* Minor edits to the proposal

* Fix revision order

* FIxup setOnTerminationCallback

* Address review feedback

* Rename to `MultiProducerSingleConsumerAsyncChannel`

* Allow one termination callback per source.

* Fix all sendable warnings

* Remove unbounded strategy, rename copy -> makeAdditionalSource, rename asyncSequence() -> elements(), and move enqueue and cancel to the `CallbackHandle` previously called `CallbackToken`

* Remove Example and fix docs and fix format

* fixes grammar and some word order issues

* Remove unnecessary consume

---------

Co-authored-by: Joe Heck <j_heck@apple.com>
2025-11-18 15:56:41 -08:00
Melissa Kilby 24bd5acc81 chore: restrict GitHub workflow permissions - future-proof (#373)
Signed-off-by: Melissa Kilby <mkilby@apple.com>
2025-10-27 15:09:46 -07:00
Changmin Lee 26111a6fb7 Fix broken documentation links in Interspersed guide (#371) 2025-10-06 09:28:20 -07:00
Janosch Hildebrand daf3c0d723 Fix typo in doc comment for share (#370) 2025-10-01 08:43:45 -07:00
Philippe HauslerandJamie 70c36ce9a1 Share algorithm (#357)
This is an implementation of share; an algorithm for allowing AsyncSequence types to be iterated by multiple consumers. In addition this cleans up the project to be a starting point for the 1.1 release - it fixes the continuous integration support and configurations but has the cost of only supporting 3 active releases (6.0, 6.1, and 6.2). Previous releases are only going to have legacy support via older released versions.

* Fix the remaining todo on hard cancellation vs soft cancellation

* Update Sources/AsyncAlgorithms/AsyncShareSequence.swift

Co-authored-by: Jamie <2119834+jamieQ@users.noreply.github.com>

* Update the implementation of share to handle sendability requirements, address some edge cases and update to the latest version of the discussion around buffering behaviors as well as adding some documentation and commentary

* Add some first drafts at unit tests for verifying share behaviors

* Cleanup some of the documentation and address feedback for implementation details

* Fix merge damage by restoring the changes from @jamieQ

* Fix up some availability issues w.r.t. sendable metatypes

* Add a preamble to SendableMetatypes.swift

* Add a fallback for next (for pre 6.2 swift's)

* Slight adjustments for older compiler builds and expose the sendable metatypes since those are part of documentation

* Update formatting and gate availability for older compilers

* Speculative fix for pre 6.1 compiler crashes by removing the sending keyword

* Revert "Speculative fix for pre 6.1 compiler crashes by removing the sending keyword"

This reverts commit 875fa81bc6.

* Speculative fix for pre 6.1 compiler crashes by removing the sending keyword, and correct sendable metatype shim availability

* Remove block comment for formatting check

* Take a more conservative approach and roll back to only supporting share on 6.2

* Only test share on 6.2 or newer

* roll back to older sendable metatype constraints

* yet another stab at 5.10 visionOS guards

* Formatting pass

* Disable 5.10 builds and leave those to older releases

* Ignore swift-version files to avoid local swiftly toolchain selection from being required by others

* Renumber the proposals and copy share into a guide

* Add a link from the primary doc interface to share

---------

Co-authored-by: Jamie <2119834+jamieQ@users.noreply.github.com>
2025-09-10 10:00:31 -07:00
Philippe Hausler ca38935fc0 Clear up CI issues and testing failures (#365)
* Conditionalize the testing targets for non-windows targets to avoid the TaskDriver requirements
* Some driveby formatting fixes and remove the freebsd target since that is not supported in swiftpm yet
* Rework validation import conditions to dependency conditionals
* Exclude 5.9 workflows and enable macOS testing scheme for CI
* Additional ifdefing out non windows targets for sequence diagram testing and more formatting fixes
2025-09-08 16:23:41 -07:00
Philippe Hausler 18e2398481 Update the project to address concurrency failures for 6.2 build modes. (#362)
* Correct build failures while updating to 6.2 swift build modes

* Add a package definition for 5.8 builds

* Add some brief explanation for the alteration of the Element in the buffer to an UnsafeTransfer

* Fix broken merge for wasi threads
2025-09-08 09:38:39 -07:00
Max Desiatov c537393339 Add enable_wasm_sdk_build: true to pull_request.yml (#363)
`swift-async-algorithms` should be built for Wasm as one of the officially supported platforms on CI to prevent possible future regressions.
2025-09-02 16:10:59 +01:00
Philippe Hausler 6dcb3acddd Simplify the version definitions and add a new definition for 1.1 (#359) 2025-08-11 14:51:05 -07:00
Franz Busch 3997ce3255 Remove the DocC plugin as a dependency (#354)
When DocC was introduced the DocC plugin was useful for building documentation locally. Nowadays both Xcode and VSCode have built-in support to generate this without the need for the plugin.

This PR removes the direct dependency on the plugin.
2025-07-02 08:09:32 -07:00
71 changed files with 10752 additions and 89 deletions

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
+9
View File
@@ -1,5 +1,8 @@
name: Pull request
permissions:
contents: read
on:
pull_request:
types: [opened, reopened, synchronize]
@@ -8,8 +11,14 @@ jobs:
tests:
name: Test
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
with:
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
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-main-noble" # Needed due to https://github.com/swiftlang/swift-format/issues/1081
+3 -1
View File
@@ -8,4 +8,6 @@ DerivedData/
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
.netrc
.swiftpm
Package.resolved
Package.resolved
.swift-version
test_output.log
-1
View File
@@ -2,4 +2,3 @@ version: 1
builder:
configs:
- documentation_targets: [AsyncAlgorithms]
swift_version: 5.8
File renamed without changes.
@@ -1,7 +1,7 @@
# Chunked & Timer
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-chunk.md)
* Proposal: [SAA-0013](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0013-chunk.md)
* Author(s): [Kevin Perry](https://github.com/kperryua), [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Status: **Accepted**
* Implementation: [
[By group](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedByGroupSequence.swift),
[On projection](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
@@ -1,8 +1,8 @@
# Rate Limiting
* Proposal: [SAA-NNNN]()
* Proposal: [SAA-0014](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0014-rate-limits.md)
* Authors: [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Status: **Accepted**
* Implementation:
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncDebounceSequence.swift) |
@@ -1,7 +1,7 @@
# Reductions
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-reductions.md)
* Proposal: [SAA-0015](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0015-reductions.md)
* Author(s): [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Status: **Accepted**
* Implementation: [
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncExclusiveReductionsSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestReductions.swift)
@@ -0,0 +1,838 @@
# MultiProducerSingleConsumerAsyncChannel
* Proposal: [SAA-0016](0016-multi-producer-single-consumer-channel.md)
* Authors: [Franz Busch](https://github.com/FranzBusch)
* Status: **Implemented**
## Revision
- 2023/12/18: Migrate proposal from Swift Evolution to Swift Async Algorithms.
- 2023/12/19: Add element size dependent strategy
- 2024/05/19: Rename to multi producer single consumer channel
- 2024/05/28: Add unbounded strategy
- 2025/03/24: Adopt `~Copyable` for correct semantics and better performance.
## Introduction
[SE-0314](https://github.com/apple/swift-evolution/blob/main/proposals/0314-async-stream.md)
introduced new `Async[Throwing]Stream` types which act as root asynchronous
sequences. These two types allow bridging from synchronous callbacks such as
delegates to an asynchronous sequence. This proposal adds a new root primitive
with the goal of modeling asynchronous multi-producer-single-consumer systems.
## Motivation
After using the `AsyncSequence` protocol, the `Async[Throwing]Stream` types, and
the `Async[Throwing]Channel` types extensively over the past years, we learned
that there is a gap in the ecosystem for a type that provides strict
multi-producer-single-consumer guarantees with external backpressure support.
Additionally, any stream/channel like type needs to have a clear definition
about the following behaviors:
1. Backpressure
2. Multi/single consumer support
3. Downstream consumer termination
4. Upstream producer termination
The below sections are providing a detailed explanation of each of those.
### Backpressure
In general, backpressure is the mechanism that prevents a fast producer from
overwhelming a slow consumer. It helps the stability of the overall system by
regulating the flow of data between different components. Additionally, it
allows us to put an upper bound on the resource consumption of a system. In reality,
backpressure is used in almost all networked applications.
In Swift, asynchronous sequences also have the concept of internal backpressure.
This is modeled by the pull-based implementation where a consumer has to call
`next` on the `AsyncIterator`. In this model, there is no way for a consumer to
overwhelm a producer since the producer controls the rate of pulling elements.
However, the internal backpressure of an asynchronous sequence isn't the only
backpressure in play. There is also the source backpressure that is producing
the actual elements. For a backpressured system, it is important that every
component of such a system is aware of the backpressure of its consumer and its
producer.
Let's take a quick look at how our current root asynchronous sequences are handling
this.
`Async[Throwing]Stream` aims to support backpressure by providing a configurable
buffer and returning `Async[Throwing]Stream.Continuation.YieldResult` which
contains the current buffer depth from the `yield()` method. However, only
providing the current buffer depth on `yield()` is not enough to bridge a
backpressured system into an asynchronous sequence since this can only be used
as a "stop" signal, but we are missing a signal to indicate resuming the
production. The only viable backpressure strategy that can be implemented with
the current API is a timed backoff where we stop producing for some period of
time and then speculatively produce again. This is a very inefficient pattern
that produces high latencies and inefficient use of resources.
`Async[Throwing]Channel` is a multi-producer-multi-consumer channel that only
supports asynchronous producers. Additionally, the backpressure strategy is
fixed by a buffer size of 1 element per producer.
We are currently lacking a type that supports a configurable backpressure
strategy and both asynchronous and synchronous producers.
### Multi/single consumer support
The `AsyncSequence` protocol itself makes no assumptions about whether the
implementation supports multiple consumers or not. This allows the creation of
unicast and multicast asynchronous sequences. The difference between a unicast
and multicast asynchronous sequence is if they allow multiple iterators to be
created. `AsyncStream` does support the creation of multiple iterators and it
does handle multiple consumers correctly. On the other hand,
`AsyncThrowingStream` also supports multiple iterators but does `fatalError`
when more than one iterator has to suspend. The original proposal states:
> As with any sequence, iterating over an AsyncStream multiple times, or
creating multiple iterators and iterating over them separately, may produce an
unexpected series of values.
While that statement leaves room for any behavior, we learned that a clear distinction
of behavior for root asynchronous sequences is beneficial; especially when it comes to
how transformation algorithms are applied on top.
### Downstream consumer termination
Downstream consumer termination allows the producer to notify the consumer that
no more values are going to be produced. `Async[Throwing]Stream` does support
this by calling the `finish()` or `finish(throwing:)` methods of the
`Async[Throwing]Stream.Continuation`. However, `Async[Throwing]Stream` does not
handle the case that the `Continuation` may be `deinit`ed before one of the
finish methods is called. This currently leads to async streams that never
terminate.
### Upstream producer termination
Upstream producer termination is the inverse of downstream consumer termination,
where the producer is notified once the consumption has terminated. Currently,
`Async[Throwing]Stream` does expose the `onTermination` property on the
`Continuation`. The `onTermination` closure is invoked once the consumer has
terminated. The consumer can terminate in four separate cases:
1. The asynchronous sequence was `deinit`ed and no iterator was created.
2. The iterator was `deinit`ed and the asynchronous sequence is unicast.
3. The consuming task is canceled.
4. The asynchronous sequence returned `nil` or threw.
`Async[Throwing]Stream` currently invokes `onTermination` in all cases; however,
since `Async[Throwing]Stream` supports multiple consumers (as discussed in the
`Multi/single consumer support` section), a single consumer task being canceled
leads to the termination of all consumers. This is not expected from multicast
asynchronous sequences in general.
## Proposed solution
The above motivation lays out the expected behaviors for any consumer/producer
system and compares them to the behaviors of `Async[Throwing]Stream` and
`Async[Throwing]Channel`.
This section proposes a new type called `MultiProducerSingleConsumerAsyncChannel`
that implements all of the above-mentioned behaviors. Importantly, this proposed
solution is taking advantage of `~Copyable` types to model the
multi-producer-single-consumer behavior. While the current `AsyncSequence`
protocols are not supporting `~Copyable` types, we provide a way to convert the
proposed channel to an asynchronous sequence. This leaves us room to support any
potential future asynchronous streaming protocol that supports `~Copyable`.
### Creating a MultiProducerSingleConsumerAsyncChannel
You can create an `MultiProducerSingleConsumerAsyncChannel` instance using the
`makeChannel(of:backpressureStrategy:)` method. This method returns you the
channel and the source. The source can be used to send new values to the
asynchronous channel. The new API specifically provides a
multi-producer/single-consumer pattern.
```swift
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
// The channel and source can be extracted from the returned type
let channel = consume channelAndSource.channel
let source = consume channelAndSource.source
```
The new proposed APIs offer two different backpressure strategies:
- Watermark: Using a low and high watermark.
- Unbounded: Unbounded buffering of the channel. **Only** use this if the
production is limited through some other means.
The source is used to send values to the channel. It provides different APIs for
synchronous and asynchronous producers. All of the APIs are relaying the
backpressure of the channel. The synchronous multi-step APIs are the foundation
for all other APIs. Below is an example of how it can be used:
```swift
do {
let sendResult = try source.send(contentsOf: sequence)
switch sendResult {
case .produceMore:
// Trigger more production in the underlying system
case .enqueueCallback(let callbackHandle):
// There are enough values in the channel already. We need to enqueue
// a callback to get notified when we should produce more.
callbackHandle.enqueueCallback(onProduceMore: { result in
switch result {
case .success:
// Trigger more production in the underlying system
case .failure(let error):
// Terminate the underlying producer
}
})
}
} catch {
// `send(contentsOf:)` throws if the channel already terminated
}
```
The above API offers the most control and highest performance when bridging a
synchronous producer to a `MultiProducerSingleConsumerAsyncChannel`. First, you have
to send values using the `send(contentsOf:)` which returns a `SendResult`. The
result either indicates that more values should be produced or that a callback
should be enqueued by calling the `enqueueCallback(onProduceMore:)` method.
This callback is invoked once the backpressure strategy
decides that more values should be produced. This API aims to offer the most
flexibility with the greatest performance. The callback only has to be allocated
in the case where the producer needs to pause production.
Additionally, the above API is the building block for some higher-level and
easier-to-use APIs to send values to the channel. Below is an
example of the two higher-level APIs.
```swift
// Writing new values and providing a callback when to produce more
try source.send(contentsOf: sequence, onProduceMore: { result in
switch result {
case .success:
// Trigger more production
case .failure(let error):
// Terminate the underlying producer
}
})
// This method suspends until more values should be produced
try await source.send(contentsOf: sequence)
```
With the above APIs, we should be able to effectively bridge any system into a
`MultiProducerSingleConsumerAsyncChannel` regardless of whether the system is callback-based,
blocking, or asynchronous.
### Multi producer
To support multiple producers, the source offers a `copy` method to produce a new
source. The source is returned `sending`, so it is in a disconnected isolation
region from the original source, allowing it to be passed into a different isolation
region to concurrently produce elements.
```swift
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 5)
)
var channel = consume channelAndSource.channel
var source1 = consume channelAndSource.source
var source2 = source1.makeAdditionalSource()
group.addTask {
try await source1.send(1)
}
group.addTask() {
try await source2.send(2)
}
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
```
### Downstream consumer termination
> When reading the next two examples of termination behavior, keep in mind
that the newly proposed APIs are providing a strict single consumer channel.
Calling `finish()` terminates the downstream consumer. Below is an example of
this:
```swift
// Termination through calling finish
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
source.finish()
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints nil
```
If the channel has a failure type it can also be finished with an error.
```swift
// Termination through calling finish
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
throwing: SomeError.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
source.finish(throwing: SomeError)
print(try await channel.next()) // Prints Optional(1)
print(try await channel.next()) // Throws SomeError
```
The other way to terminate the consumer is by deiniting the source. This has the
same effect as calling `finish()`. Since the source is a `~Copyable` type, this
will happen automatically when the source is last used or explicitly consumed.
```swift
// Termination through deiniting the source
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
_ = consume source // Explicitly consume the source
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints nil
```
### Upstream producer termination
The producer will get notified about termination through the `onTerminate`
callback. Termination of the producer happens in the following scenarios:
```swift
// Termination through task cancellation
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
let task = Task {
await channel.next()
}
task.cancel() // Prints Terminated
```
```swift
// Termination through deiniting the channel
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
_ = consume channel // Prints Terminated
```
```swift
// Termination through finishing the source and consuming the last element
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
_ = try await source.send(1)
source.finish()
print(await channel.next()) // Prints Optional(1)
await channel.next() // Prints Terminated
```
```swift
// Termination through deiniting the last source and consuming the last element
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source1 = consume channelAndSource.source
var source2 = source1.makeAdditionalSource()
source1.setOnTerminationCallback { print("Terminated") }
_ = try await source1.send(1)
_ = consume source1
_ = try await source2.send(2)
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints Optional(2)
_ = consume source2
await channel.next() // Prints Terminated
```
Similar to the downstream consumer termination, trying to send more elements after the
producer has been terminated will result in an error thrown from the send methods.
## Detailed design
```swift
#if compiler(>=6.1)
/// An error that is thrown from the various `send` methods of the
/// ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// This error is thrown when the channel is already finished when
/// trying to send new elements to the source.
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error { }
/// A multi-producer single-consumer channel.
///
/// The ``MultiProducerSingleConsumerAsyncChannel`` provides a ``MultiProducerSingleConsumerAsyncChannel/Source`` to
/// send values to the channel. The channel supports different back pressure strategies to control the
/// buffering and demand. The channel will buffer values until its backpressure strategy decides that the
/// producer have to wait.
///
/// This channel is also suitable for the single-producer single-consumer use-case
///
/// ## Using a MultiProducerSingleConsumerAsyncChannel
///
/// To use a ``MultiProducerSingleConsumerAsyncChannel`` you have to create a new channel with its source first by calling
/// the ``MultiProducerSingleConsumerAsyncChannel/makeChannel(of:throwing:BackpressureStrategy:)`` method.
/// Afterwards, you can pass the source to the producer and the channel to the consumer.
///
/// ```
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 2, high: 4)
/// )
///
/// // The channel and source can be extracted from the returned type
/// let channel = consume channelAndSource.channel
/// let source = consume channelAndSource.source
/// ```
///
/// ### Asynchronous producing
///
/// Values can be send to the source from asynchronous contexts using ``MultiProducerSingleConsumerAsyncChannel/Source/send(_:)-8eo96``
/// and ``MultiProducerSingleConsumerAsyncChannel/Source/send(contentsOf:)``. Backpressure results in calls
/// to the `send` methods to be suspended. Once more elements should be produced the `send` methods will be resumed.
///
/// ```
/// try await withThrowingTaskGroup(of: Void.self) { group in
/// group.addTask {
/// try await source.send(1)
/// try await source.send(2)
/// try await source.send(3)
/// }
///
/// for await element in channel {
/// print(element)
/// }
/// }
/// ```
///
/// ### Synchronous produceing
///
/// Values can also be send to the source from synchronous context. Backpressure is also exposed on the synchronous contexts; however,
/// it is up to the caller to decide how to properly translate the backpressure to underlying producer e.g. by blocking the thread.
///
/// ```swift
/// do {
/// let sendResult = try source.send(contentsOf: sequence)
///
/// switch sendResult {
/// case .produceMore:
/// // Trigger more production in the underlying system
///
/// case .enqueueCallback(let callbackHandle):
/// // There are enough values in the channel already. We need to enqueue
/// // a callback to get notified when we should produce more.
/// callbackHandle.enqueueCallback(onProduceMore: { result in
/// switch result {
/// case .success:
/// // Trigger more production in the underlying system
/// case .failure(let error):
/// // Terminate the underlying producer
/// }
/// })
/// }
/// } catch {
/// // `send(contentsOf:)` throws if the channel already terminated
/// }
/// ```
///
/// ### Multiple producers
///
/// To support multiple producers the source offers a ``Source/makeAdditionalSource()`` method to produce a new source.
///
/// ### Terminating the production of values
///
/// The consumer can be terminated through multiple ways:
/// - Calling ``Source/finish(throwing:)``.
/// - Deiniting all sources.
///
/// In both cases, if there are still elements buffered by the channel, then the consumer will receive
/// all buffered elements. Afterwards it will be terminated.
///
/// ### Observing termination of the consumer
///
/// When the consumer stops consumption by either deiniting the channel or the task calling ``next(isolation:)``
/// getting cancelled, the source will get notified about the termination if a termination callback has been set
/// before by calling ``Source/setOnTerminationCallback(_:)``.
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>: ~Copyable {
/// A struct containing the initialized channel and source.
///
/// This struct can be deconstructed by consuming the individual
/// components from it.
///
/// ```swift
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 5, high: 10)
/// )
/// var channel = consume channelAndSource.channel
/// var source = consume channelAndSource.source
/// ```
@frozen
public struct ChannelAndStream : ~Copyable {
/// The channel.
public var channel: MultiProducerSingleConsumerAsyncChannel
/// The source.
public var source: Source
}
/// Initializes a new ``MultiProducerSingleConsumerAsyncChannel`` and an ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// - Parameters:
/// - elementType: The element type of the channel.
/// - failureType: The failure type of the channel.
/// - backpressureStrategy: The backpressure strategy that the channel should use.
/// - Returns: A tuple containing the channel and its source. The source should be passed to the
/// producer while the channel should be passed to the consumer.
public static func makeChannel(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy
) -> ChannelAndStream
/// Returns the next element.
///
/// If this method returns `nil` it indicates that no further values can ever
/// be returned. The channel automatically closes when all sources have been deinited.
///
/// If there are no elements and the channel has not been finished yet, this method will
/// suspend until an element is send to the channel.
///
/// If the task calling this method is cancelled this method will return `nil`.
///
/// - Parameter isolation: The callers isolation.
/// - Returns: The next buffered element.
public func next(isolation: isolated (any Actor)? = #isolation) async throws(Failure) -> Element?
}
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// A struct to send values to the channel.
///
/// Use this source to provide elements to the channel by calling one of the `send` methods.
public struct Source: ~Copyable, Sendable {
/// A struct representing the backpressure of the channel.
public struct BackpressureStrategy: Sendable {
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
public static func watermark(low: Int, high: Int) -> BackpressureStrategy
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
/// - waterLevelForElement: A closure used to compute the contribution of each buffered element to the current water level.
///
/// - Note, `waterLevelForElement` will be called on each element when it is written into the source and when
/// it is consumed from the channel, so it is recommended to provide a function that runs in constant time.
public static func watermark(low: Int, high: Int, waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int) -> BackpressureStrategy
/// An unbounded backpressure strategy.
///
/// - Important: Only use this strategy if the production of elements is limited through some other mean. Otherwise
/// an unbounded backpressure strategy can result in infinite memory usage and cause
/// your process to run out of memory.
public static func unbounded() -> BackpressureStrategy
}
/// A type that indicates the result of sending elements to the source.
public enum SendResult: ~Copyable, Sendable {
/// A handle that is returned when the channel's backpressure strategy indicated that production should
/// be suspended. Use this handle to enqueue a callback by calling the ``CallbackHandle/enqueueCallback(onProduceMore:)`` method.
///
/// - Important: ``CallbackHandle/enqueueCallback(onProduceMore:)`` and ``CallbackHandle/cancelCallback()`` must
/// only be called once.
public struct CallbackHandle: Sendable, Hashable {
/// Enqueues a callback that will be invoked once more elements should be produced.
///
/// - Important: Calling enqueue more than once is **not allowed**.
///
/// - Parameters:
/// - onProduceMore: The callback which gets invoked once more elements should be produced.
@inlinable
public mutating func enqueueCallback(
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
)
/// Cancel an enqueued callback.
///
/// - Note: This methods supports being called before ``enqueueCallback(onProduceMore:)`` is called.
///
/// - Important: Calling enqueue more than once is **not allowed**.
@inlinable
public mutating func cancelCallback()
}
/// Indicates that more elements should be produced and send to the source.
case produceMore
/// Indicates that a callback should be enqueued.
case enqueueCallback(CallbackHandle)
}
/// A callback to invoke when the channel finished.
///
/// This is called after the last element has been consumed by the channel.
public func setOnTerminationCallback(_ callback: @escaping @Sendable () -> Void)
/// Creates a new source which can be used to send elements to the channel concurrently.
///
/// The channel will only automatically be finished if all existing sources have been deinited.
///
/// - Returns: A new source for sending elements to the channel.
public mutating func makeAdditionalSource() -> Source
/// Sends 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.
///
/// - Parameter sequence: The elements to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) throws -> SendResult where Element == S.Element, S: Sequence
/// Send the 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.
///
/// - Parameter element: The element to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
public mutating func send(_ element: sending consuming Element) throws -> SendResult
/// Send new elements to the channel and provide a callback which will be invoked once more elements should be produced.
///
/// 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 `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(contentsOf:onProduceMore:)``.
public mutating func send<S>(
contentsOf sequence: consuming sending S,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) where Element == S.Element, S: Sequence
/// Sends the 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 `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - element: The element to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(_:onProduceMore:)``.
public mutating func send(
_ element: consuming sending Element,
onProduceMore: @escaping @Sendable (Result<Void, Error>
) -> Void)
/// 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.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element == S.Element, S: Sequence
/// 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.
public mutating func send(_ element: consuming sending Element) async throws
/// 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.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element: Sendable, Element == S.Element, S: Sendable, S: AsyncSequence
/// Indicates that the production terminated.
///
/// After all buffered elements are consumed the subsequent call to ``MultiProducerSingleConsumerAsyncChannel/next(isolation:)`` will return
/// `nil` or throw an error.
///
/// Calling this function more than once has no effect. After calling finish, the channel enters a terminal state and doesn't accept
/// new elements.
///
/// - Parameters:
/// - error: The error to throw, or `nil`, to finish normally.
public consuming func finish(throwing error: Failure? = nil)
}
}
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// Converts the channel to an asynchronous sequence for consumption.
///
/// - Important: The returned asynchronous sequence only supports a single iterator to be created and
/// will fatal error at runtime on subsequent calls to `makeAsyncIterator`.
public consuming func asyncSequence() -> some (AsyncSequence<Element, Failure> & Sendable)
}
```
## Comparison to other root asynchronous primitives
### swift-async-algorithm: AsyncChannel
The `AsyncChannel` is a multi-consumer/multi-producer root asynchronous sequence
which can be used to communicate between two tasks. It only offers asynchronous
production APIs and has an effective buffer of one per producer. This means that
any producer will be suspended until its value has been consumed. `AsyncChannel`
can handle multiple consumers and resumes them in FIFO order.
### swift-nio: NIOAsyncSequenceProducer
The NIO team has created their own root asynchronous sequence with the goal to
provide a high-performance sequence that can be used to bridge a NIO `Channel`
inbound stream into Concurrency. The `NIOAsyncSequenceProducer` is a highly
generic and fully inlinable type and quite unwieldy to use. This proposal is
heavily inspired by the learnings from this type but tries to create a more
flexible and easier-to-use API that fits into the standard library.
## Future directions
### Adaptive backpressure strategy
The high/low watermark strategy is common in networking code; however, there are
other strategies such as an adaptive strategy that we could offer in the future.
An adaptive strategy regulates the backpressure based on the rate of
consumption and production. With the proposed new APIs, we can easily add further
strategies.
### Support `~Copyable` elements
In the future, we can extend the channel to support `~Copyable` elements. We
only need an underlying buffer primitive that can hold `~Copyable` types, and the
continuations need to support `~Copyable` elements as well. By making the
channel not directly conform to `AsyncSequence`, we can support this down the
road.
## Alternatives considered
### Provide an `onTermination` callback to the factory method
During development of the new APIs, I first tried to provide the `onTermination`
callback in the `makeChannel` method. However, that showed significant usability
problems in scenarios where one wants to store the source in a type and
reference `self` in the `onTermination` closure at the same time; hence, I kept
the current pattern of setting the `onTermination` closure on the source.
### Provide a `onConsumerCancellation` callback
During the pitch phase, it was raised that we should provide a
`onConsumerCancellation` callback which gets invoked once the asynchronous
channel notices that the consuming task got cancelled. This callback could be
used to customize how cancellation is handled by the channel, e.g. one could
imagine writing a few more elements to the channel before finishing it. Right now,
the channel immediately returns `nil` or throws a `CancellationError` when it
notices cancellation. This proposal decided not to provide this customization
because it opens up the possibility that asynchronous channels are not terminating
when implemented incorrectly. Additionally, asynchronous sequences are not the
only place where task cancellation leads to an immediate error being thrown i.e.
`Task.sleep()` does the same. Hence, the value of the asynchronous not
terminating immediately brings little value when the next call in the iterating
task might throw. However, the implementation is flexible enough to add this in
the future, and we can just default it to the current behaviour.
### Create a custom type for the `Result` of the `onProduceMore` callback
The `onProducerMore` callback takes a `Result<Void, Error>` which is used to
indicate if the producer should produce more or if the asynchronous channel
finished. We could introduce a new type for this, but the proposal decided
against it since it effectively is a result type.
### Use an initializer instead of factory methods
Instead of providing a `makeChannel` factory method, we could use an initializer
approach that takes a closure which gets the `Source` passed into. A similar API
has been offered with the `Continuation` based approach and
[SE-0388](https://github.com/apple/swift-evolution/blob/main/proposals/0388-async-stream-factory.md)
introduced new factory methods to solve some of the usability ergonomics with
the initializer based APIs.
### Provide the type on older compilers
To achieve maximum performance, the implementation is using `~Copyable` extensively.
On Swift versions before 6.1, there is a https://github.com/swiftlang/swift/issues/78048 when using; hence, this type
is only usable with Swift 6.1 and later compilers.
## Acknowledgements
- [Johannes Weiss](https://github.com/weissi) - For making me aware how
important this problem is and providing great ideas on how to shape the API.
- [Philippe Hausler](https://github.com/phausler) - For helping me designing the
APIs and continuously providing feedback
- [George Barnett](https://github.com/glbrntt) - For providing extensive code
reviews and testing the implementation.
- [Si Beaumont](https://github.com/simonjbeaumont) - For implementing the element size dependent strategy
+197
View File
@@ -0,0 +1,197 @@
# Share
* Proposal: [SAA-0015](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0016-share.md)
* Author(s): [Philippe Hausler](https://github.com/phausler)
* Status: **Accepted**
* Implementation: [
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncShareSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestShare.swift)
]
* Decision Notes:
* Bugs:
## Introduction
Many of the AsyncSequence adopting types only permit a one singular consumption. However there are many times that the same produced values are useful in more than one place. Out of that mechanism there are a few approaches to share, distribute, and broadcast those values. This proposal will focus on one concept; sharing. Sharing is where each consumption independently can make forward progress and get the same values but do not replay from the beginning of time.
## Motivation
There are many potential usages for the sharing concept of AsyncSequences.
One such example is the case where a source of data as an asynchronous sequence needs to be consumed by updating UI, logging, and additionally a network connection. This particular case does not matter on which uses but instead that those uses are independent of each other. It would not be expected for networking to block or delay the updates to UI, nor should logging. This example case also illustrates that the isolation of each side might be different and that some of the sides may not tolerate coalescing or dropping values.
There are many other use cases that have been requested for this family of algorithms. Since the release of AsyncAlgorithms it has perhaps been the most popularly requested set of behaviors as additions to the package.
## Proposed solution
AsyncAlgorithms will introduce a new extension function on AsyncSequence that will provide a shareable asynchronous sequence that will produce the same values upon iteration from multiple instances of it's AsyncIterator. Those iterations can take place in multiple isolations.
When values from a differing isolation cannot be coalesced, the two options available are either awaiting (an exertion of back-pressure across the sequences) or buffering (an internal back-pressure to a buffer). Replaying the values from the beginning of the creation of the sequence is a distinctly different behavior that should be considered a different use case. This then leaves the behavioral characteristic of this particular operation of share as; sharing a buffer of values started from the initialization of a new iteration of the sequence. Control over that buffer should then have options to determine the behavior, similar to how AsyncStream allows that control. It should have options to be unbounded, buffering the oldest count of elements, or buffering the newest count of elements.
It is critical to identify that this is one algorithm in the family of algorithms for sharing values. It should not attempt to solve all behavioral requirements but instead serve a common set of them that make cohesive sense together. This proposal is not mutually exclusive to the other algorithms in the sharing family.
## Detailed design
A new extension will be added to return a `Sendable` `AsyncSequence`. This extension will take a buffering policy to identify how the buffer will be handled when iterations do not consume at the same rate.
The `Sendable` annotation identifies to the developer that this sequence can be shared and stored in an existental `any`.
```swift
extension AsyncSequence where Element: Sendable {
public func share(
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
) -> some AsyncSequence<Element, Failure> & Sendable
}
```
The buffer internally to the share algorithm will only extend back to the furthest element available but there will only be a singular buffer shared across all iterators. This ensures that with the application of the buffering policy the storage size is as minimal as possible while still allowing all iterations to avoid dropping values and keeping the memory usage in check. The signature reuses the existing `AsyncBufferSequencePolicy` type to specify the behavior around buffering either responding to how it should limit emitting to the buffer or what should happen when the buffer is exceeded.
## Runtime Behavior
The runtime behaviors fall into a few categories; ordering, iteration isolation, cancellation, and lifetimes. To understand the beahviors there are a terms useful to define. Each creation of the AsyncIterator of the sequence and invocation of next will be referred to a side of the share iteration. The back pressure to the system to fetch a new element or termination is refered to as demand. The limit which is the pending gate for awaiting until the buffer has been serviced used for the `AsyncBufferSequencePolicy.bounded(_ : Int)` policy. The last special definition is that of the extent which is specifically in this case the lifetime of the asynchronous sequence itself.
When the underlying type backing the share algorithm is constructed a new extent is created; this is used for tracking the reference lifetime under the hood and is used to both house the iteration but also to identify the point at which no more sides can be constructed. When no more sides can be constructed and no sides are left to iterate then the backing iteration is canceled. This prevents any un-referenced task backing the iteration to not be leaked by the algorith itself.
That construction then creates an initial shared state and buffer. No task is started initially; it is only upon the first demand that the task backing the iteration is started; this means on the first call to next a task is spun up servicing all potential sides. The order of which the sides are serviced is not specified and cannot be relied upon, however the order of delivery within a side is always guarenteed to be ordered. The singular task servicing the iteration will be the only place holding any sort of iterator from the base `AsyncSequence`; so that iterator is isolated and not sent from one isolation to another. That iteration first awaits any limit availability and then awaits for a demand given by a side. After-which it then awaits an element or terminal event from the iterator and enqueues the elements to the buffer.
The buffer itself is only held in one location, each side however has a cursor index into that buffer and when values are consumed it adjusts the indexes accordingly; leaving the buffer usage only as big as the largest deficit. This means that new sides that are started post initial start up will not have a "replay" effect; that is a similar but distinct algorithm and is not addressed by this proposal. Any buffer size sensitive systems that wish to adjust behavior should be aware that specifying a policy is a suggested step. However in common usage similar to other such systems servicing desktop and mobile applications the common behavior is often unbounded. Alternatively desktop or mobile applications will often want `.bounded(1)` since that enforces the slowest consumption to drive the forward progress at most 1 buffered element. All of the use cases have a reasonable default of `.bounded(1)`; mobile, deskop, and server side uses. Leaving this as the default parameter keeps the progressive disclosure of the beahviors - such that the easiest thing to write is correct for all uses, and then more advanced control can be adjusted by passing in a specific policy. This default argument diverges slightly from AsyncStream, but follows a similar behavior to that of Combine's `share`.
As previously stated, the isolation of the iteration of the upstream/base AsyncSequence is to a detached task, this ensures that individual sides can have independent cancellation. Those cancellations will have the effect of remvoing that side from the shared iteration and cleaning up accordingly (including adjusting the trimming of the internal buffer).
Representing concurrent access is difficult to express all potential examples but there are a few cases included with this proposal to illustrate some of the behaviors. If a more comprehensive behavioral analysis is needed, it is strongly suggested to try out the pending pull request to identify how specific behaviors work. Please keep in mind that the odering between tasks is not specified, only the order within one side of iteration.
Practically this all means that a given iteration may be "behind" another and can eventually catch up (provided it is within the buffer limit).
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .unbounded)
let t1 = Task {
for await element in exampleSource {
if element == 0 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 1", element)
}
}
let t2 = Task {
for await element in exampleSource {
if element == 3 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 2", element)
}
}
await t1.value
await t2.value
```
This example will print a possible ordering of the following:
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 3
Task 2 4
Task 1 1
Task 1 2
Task 1 3
Task 1 4
```
The order of the interleaving of the prints are not guaranteed; however the order of the elements per iteration is. Likewise in this buffering case it is guaranteed that all values are represented in the output.
If the creation were instead altered to the following:
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingLatest(2))
```
The output would print the possible ordering of:
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 4
Task 1 3
Task 1 4
```
Some values are dropped due to the buffering policy, but eventually they reach consistency. Which similarly works for the following:
```
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingOldest(2))
```
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 4
Task 1 1
Task 1 2
```
However in this particular case the newest values are the dropped elements.
The `.bounded(N)` policy enforces consumption to prevent any side from being beyond a given amount away from other sides' consumption.
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bounded(1))
let t1 = Task {
for await element in exampleSource {
if element == 0 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 1", element)
}
}
let t2 = Task {
for await element in exampleSource {
if element == 3 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 2", element)
}
}
await t1.value
await t2.value
```
Will have a potential ordering output of:
```
Task 2 0
Task 2 1
Task 1 0
Task 1 1
Task 2 2
Task 1 2
Task 1 3
Task 1 4
Task 2 3
Task 2 4
```
In that example output Task 2 can get element 0 and 1 but must await until task 1 has caught up to the specified buffering. This limit means that no additional iteration (and no values are then dropped) is made until the buffer count is below the specified value.
## Effect on API resilience
This is an additive API and no existing systems are changed, however it will introduce a few new types that will need to be maintained as ABI interfaces. Since the intent of this is to provide a mechanism to store AsyncSequences to a shared context the type must be exposed as ABI (for type sizing).
## Alternatives considered
It has been considered that the buffering policy would be nested inside the `AsyncShareSequence` type. However since this seems to be something that will be useful for other types it makes sense to use an existing type from a top level type. However if it is determined that a general form of a buffering policy would require additional behaviors this might be a debatable placement to move back to an interior type similar to AsyncStream.
+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.
+121 -33
View File
@@ -1,42 +1,56 @@
// swift-tools-version: 5.8
// swift-tools-version: 6.2
import PackageDescription
import CompilerPluginSupport
// Availability Macros
let availabilityTags = [Availability("AsyncAlgorithms")]
let versionNumbers = ["1.0"]
let AsyncAlgorithms_v1_0 = "AvailabilityMacro=AsyncAlgorithms 1.0:macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0"
#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
// Availability Macro Utilities
enum OSAvailability: String {
// This should match the package's deployment target
case initialIntroduction = "macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0"
case pending = "macOS 9999, iOS 9999, tvOS 9999, watchOS 9999"
// Use 10000 for future availability to avoid compiler magic around
// the 9999 version number but ensure it is greater than 9999
case future = "macOS 10000, iOS 10000, tvOS 10000, watchOS 10000"
}
struct Availability {
let name: String
let osAvailability: OSAvailability
init(_ name: String, availability: OSAvailability = .initialIntroduction) {
self.name = name
self.osAvailability = availability
}
}
let availabilityMacros: [SwiftSetting] = versionNumbers.flatMap { version in
availabilityTags.map {
.enableExperimentalFeature("AvailabilityMacro=\($0.name) \(version):\($0.osAvailability.rawValue)")
}
}
let availabilityMacros: [SwiftSetting] = [
.enableExperimentalFeature(
AsyncAlgorithms_v1_0
),
.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(
@@ -49,6 +63,24 @@ let package = Package(
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
.target(
name: "AsyncStreaming",
dependencies: [
.product(name: "BasicContainers", package: "swift-collections"),
.product(name: "ContainersPreview", package: "swift-collections"),
],
swiftSettings: [
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
.enableExperimentalFeature("LifetimeDependence"),
.enableExperimentalFeature("Lifetimes"),
.enableUpcomingFeature("LifetimeDependence"),
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
.enableUpcomingFeature("InferIsolatedConformances"),
.enableUpcomingFeature("ExistentialAny"),
.enableUpcomingFeature("MemberImportVisibility"),
.enableUpcomingFeature("InternalImportsByDefault"),
]
),
.target(
name: "AsyncSequenceValidation",
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
@@ -66,18 +98,74 @@ let package = Package(
),
.testTarget(
name: "AsyncAlgorithmsTests",
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"],
dependencies: [
.target(name: "AsyncAlgorithms"),
.target(
name: "AsyncSequenceValidation",
condition: .when(platforms: [
.macOS,
.iOS,
.tvOS,
.watchOS,
.visionOS,
.macCatalyst,
.android,
.linux,
.custom("freebsd"),
.openbsd,
.wasi,
])
),
.target(
name: "AsyncAlgorithms_XCTest",
condition: .when(platforms: [
.macOS,
.iOS,
.tvOS,
.watchOS,
.visionOS,
.macCatalyst,
.android,
.linux,
.custom("freebsd"),
.openbsd,
.wasi,
])
),
],
swiftSettings: availabilityMacros + [
.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-docc-plugin", from: "1.0.0"),
.package(
url: "https://github.com/apple/swift-collections.git",
from: "1.5.0",
traits: [.trait(name: "UnstableContainersPreview", condition: .when(traits: ["UnstableAsyncStreaming"]))]
)
]
} else {
package.dependencies += [
+1 -1
View File
@@ -1,4 +1,4 @@
// swift-tools-version: 5.6
// swift-tools-version: 5.7
import PackageDescription
+104
View File
@@ -0,0 +1,104 @@
// swift-tools-version: 5.8
import PackageDescription
import CompilerPluginSupport
// Availability Macros
let availabilityMacros: [SwiftSetting] = [
.enableExperimentalFeature(
"AvailabilityMacro=AsyncAlgorithms 1.0:macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0"
),
.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(
name: "swift-async-algorithms",
products: [
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"])
],
targets: [
.target(
name: "AsyncAlgorithms",
dependencies: [
.product(name: "OrderedCollections", package: "swift-collections"),
.product(name: "DequeModule", package: "swift-collections"),
],
swiftSettings: availabilityMacros + [
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
.target(
name: "AsyncSequenceValidation",
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
swiftSettings: availabilityMacros + [
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
.target(
name: "AsyncAlgorithms_XCTest",
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
swiftSettings: availabilityMacros + [
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
.testTarget(
name: "AsyncAlgorithmsTests",
dependencies: [
.target(name: "AsyncAlgorithms"),
.target(
name: "AsyncSequenceValidation",
condition: .when(platforms: [
.macOS,
.iOS,
.tvOS,
.watchOS,
.visionOS,
.macCatalyst,
.android,
.linux,
.openbsd,
.wasi,
])
),
.target(
name: "AsyncAlgorithms_XCTest",
condition: .when(platforms: [
.macOS,
.iOS,
.tvOS,
.watchOS,
.visionOS,
.macCatalyst,
.android,
.linux,
.openbsd,
.wasi,
])
),
],
swiftSettings: availabilityMacros + [
.enableExperimentalFeature("StrictConcurrency=complete")
]
),
]
)
if Context.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
package.dependencies += [
.package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0")
]
} else {
package.dependencies += [
.package(path: "../swift-collections")
]
}
@@ -30,6 +30,7 @@ This package has three main goals:
- <doc:Merge>
- <doc:Reductions>
- <doc:RemoveDuplicates>
- <doc:Share>
- <doc:Throttle>
- <doc:Timer>
- <doc:Zip>
@@ -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.
@@ -2,8 +2,8 @@
Places a given value in between each element of the asynchronous sequence.
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncInterspersedSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestInterspersed.swift)]
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Interspersed/AsyncInterspersedSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/Interspersed/TestInterspersed.swift)]
```swift
let numbers = [1, 2, 3].async.interspersed(with: 0)
@@ -0,0 +1,194 @@
# Share
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncShareSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestShare.swift)
]
## Introduction
Many of the AsyncSequence adopting types only permit a one singular consumption. However there are many times that the same produced values are useful in more than one place. Out of that mechanism there are a few approaches to share, distribute, and broadcast those values. This proposal will focus on one concept; sharing. Sharing is where each consumption independently can make forward progress and get the same values but do not replay from the beginning of time.
## Motivation
There are many potential usages for the sharing concept of AsyncSequences.
One such example is the case where a source of data as an asynchronous sequence needs to be consumed by updating UI, logging, and additionally a network connection. This particular case does not matter on which uses but instead that those uses are independent of each other. It would not be expected for networking to block or delay the updates to UI, nor should logging. This example case also illustrates that the isolation of each side might be different and that some of the sides may not tolerate coalescing or dropping values.
There are many other use cases that have been requested for this family of algorithms. Since the release of AsyncAlgorithms it has perhaps been the most popularly requested set of behaviors as additions to the package.
## Proposed solution
AsyncAlgorithms will introduce a new extension function on AsyncSequence that will provide a shareable asynchronous sequence that will produce the same values upon iteration from multiple instances of it's AsyncIterator. Those iterations can take place in multiple isolations.
When values from a differing isolation cannot be coalesced, the two options available are either awaiting (an exertion of back-pressure across the sequences) or buffering (an internal back-pressure to a buffer). Replaying the values from the beginning of the creation of the sequence is a distinctly different behavior that should be considered a different use case. This then leaves the behavioral characteristic of this particular operation of share as; sharing a buffer of values started from the initialization of a new iteration of the sequence. Control over that buffer should then have options to determine the behavior, similar to how AsyncStream allows that control. It should have options to be unbounded, buffering the oldest count of elements, or buffering the newest count of elements.
It is critical to identify that this is one algorithm in the family of algorithms for sharing values. It should not attempt to solve all behavioral requirements but instead serve a common set of them that make cohesive sense together. This proposal is not mutually exclusive to the other algorithms in the sharing family.
## Detailed design
A new extension will be added to return a `Sendable` `AsyncSequence`. This extension will take a buffering policy to identify how the buffer will be handled when iterations do not consume at the same rate.
The `Sendable` annotation identifies to the developer that this sequence can be shared and stored in an existental `any`.
```swift
extension AsyncSequence where Element: Sendable {
public func share(
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
) -> some AsyncSequence<Element, Failure> & Sendable
}
```
The buffer internally to the share algorithm will only extend back to the furthest element available but there will only be a singular buffer shared across all iterators. This ensures that with the application of the buffering policy the storage size is as minimal as possible while still allowing all iterations to avoid dropping values and keeping the memory usage in check. The signature reuses the existing `AsyncBufferSequencePolicy` type to specify the behavior around buffering either responding to how it should limit emitting to the buffer or what should happen when the buffer is exceeded.
## Runtime Behavior
The runtime behaviors fall into a few categories; ordering, iteration isolation, cancellation, and lifetimes. To understand the beahviors there are a terms useful to define. Each creation of the AsyncIterator of the sequence and invocation of next will be referred to a side of the share iteration. The back pressure to the system to fetch a new element or termination is refered to as demand. The limit which is the pending gate for awaiting until the buffer has been serviced used for the `AsyncBufferSequencePolicy.bounded(_ : Int)` policy. The last special definition is that of the extent which is specifically in this case the lifetime of the asynchronous sequence itself.
When the underlying type backing the share algorithm is constructed a new extent is created; this is used for tracking the reference lifetime under the hood and is used to both house the iteration but also to identify the point at which no more sides can be constructed. When no more sides can be constructed and no sides are left to iterate then the backing iteration is canceled. This prevents any un-referenced task backing the iteration to not be leaked by the algorith itself.
That construction then creates an initial shared state and buffer. No task is started initially; it is only upon the first demand that the task backing the iteration is started; this means on the first call to next a task is spun up servicing all potential sides. The order of which the sides are serviced is not specified and cannot be relied upon, however the order of delivery within a side is always guarenteed to be ordered. The singular task servicing the iteration will be the only place holding any sort of iterator from the base `AsyncSequence`; so that iterator is isolated and not sent from one isolation to another. That iteration first awaits any limit availability and then awaits for a demand given by a side. After-which it then awaits an element or terminal event from the iterator and enqueues the elements to the buffer.
The buffer itself is only held in one location, each side however has a cursor index into that buffer and when values are consumed it adjusts the indexes accordingly; leaving the buffer usage only as big as the largest deficit. This means that new sides that are started post initial start up will not have a "replay" effect; that is a similar but distinct algorithm and is not addressed by this proposal. Any buffer size sensitive systems that wish to adjust behavior should be aware that specifying a policy is a suggested step. However in common usage similar to other such systems servicing desktop and mobile applications the common behavior is often unbounded. Alternatively desktop or mobile applications will often want `.bounded(1)` since that enforces the slowest consumption to drive the forward progress at most 1 buffered element. All of the use cases have a reasonable default of `.bounded(1)`; mobile, deskop, and server side uses. Leaving this as the default parameter keeps the progressive disclosure of the beahviors - such that the easiest thing to write is correct for all uses, and then more advanced control can be adjusted by passing in a specific policy. This default argument diverges slightly from AsyncStream, but follows a similar behavior to that of Combine's `share`.
As previously stated, the isolation of the iteration of the upstream/base AsyncSequence is to a detached task, this ensures that individual sides can have independent cancellation. Those cancellations will have the effect of remvoing that side from the shared iteration and cleaning up accordingly (including adjusting the trimming of the internal buffer).
Representing concurrent access is difficult to express all potential examples but there are a few cases included with this proposal to illustrate some of the behaviors. If a more comprehensive behavioral analysis is needed, it is strongly suggested to try out the pending pull request to identify how specific behaviors work. Please keep in mind that the odering between tasks is not specified, only the order within one side of iteration.
Practically this all means that a given iteration may be "behind" another and can eventually catch up (provided it is within the buffer limit).
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .unbounded)
let t1 = Task {
for await element in exampleSource {
if element == 0 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 1", element)
}
}
let t2 = Task {
for await element in exampleSource {
if element == 3 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 2", element)
}
}
await t1.value
await t2.value
```
This example will print a possible ordering of the following:
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 3
Task 2 4
Task 1 1
Task 1 2
Task 1 3
Task 1 4
```
The order of the interleaving of the prints are not guaranteed; however the order of the elements per iteration is. Likewise in this buffering case it is guaranteed that all values are represented in the output.
If the creation were instead altered to the following:
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingLatest(2))
```
The output would print the possible ordering of:
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 4
Task 1 3
Task 1 4
```
Some values are dropped due to the buffering policy, but eventually they reach consistency. Which similarly works for the following:
```
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingOldest(2))
```
```
Task 2 0
Task 2 1
Task 2 2
Task 1 0
Task 2 4
Task 1 1
Task 1 2
```
However in this particular case the newest values are the dropped elements.
The `.bounded(N)` policy enforces consumption to prevent any side from being beyond a given amount away from other sides' consumption.
```swift
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bounded(1))
let t1 = Task {
for await element in exampleSource {
if element == 0 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 1", element)
}
}
let t2 = Task {
for await element in exampleSource {
if element == 3 {
try? await Task.sleep(for: .seconds(1))
}
print("Task 2", element)
}
}
await t1.value
await t2.value
```
Will have a potential ordering output of:
```
Task 2 0
Task 2 1
Task 1 0
Task 1 1
Task 2 2
Task 1 2
Task 1 3
Task 1 4
Task 2 3
Task 2 4
```
In that example output Task 2 can get element 0 and 1 but must await until task 1 has caught up to the specified buffering. This limit means that no additional iteration (and no values are then dropped) is made until the buffer count is below the specified value.
## Effect on API resilience
This is an additive API and no existing systems are changed, however it will introduce a few new types that will need to be maintained as ABI interfaces. Since the intent of this is to provide a mechanism to store AsyncSequences to a shared context the type must be exposed as ABI (for type sizing).
## Alternatives considered
It has been considered that the buffering policy would be nested inside the `AsyncShareSequence` type. However since this seems to be something that will be useful for other types it makes sense to use an existing type from a top level type. However if it is determined that a general form of a buffering policy would require additional behaviors this might be a debatable placement to move back to an interior type similar to AsyncStream.
@@ -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
@@ -0,0 +1,726 @@
//===----------------------------------------------------------------------===//
//
// 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 compiler(>=6.2)
import Synchronization
import DequeModule
@available(AsyncAlgorithms 1.1, *)
extension AsyncSequence
where Element: Sendable, Self: SendableMetatype, AsyncIterator: SendableMetatype {
/// Creates a shared async sequence that allows multiple concurrent iterations over a single source.
///
/// The `share` method transforms an async sequence into a shareable sequence that can be safely
/// iterated by multiple concurrent tasks. This is useful when you want to broadcast elements from
/// a single source to multiple consumers without duplicating work or creating separate iterations.
///
/// Each element from the source sequence is delivered to all active iterators.
/// Elements are buffered according to the specified buffering policy to handle timing differences
/// between consumers.
///
/// The base sequence is iterated in it's own task to ensure that cancellation is not polluted from
/// one side of iteration to another.
///
/// ## Example Usage
///
/// ```swift
/// let numbers = [1, 2, 3, 4, 5].async.map {
/// try? await Task.sleep(for: .seconds(1))
/// return $0
/// }
///
/// let shared = numbers.share()
///
/// // Multiple tasks can iterate concurrently
/// let consumer1 = Task {
/// for await value in shared {
/// print("Consumer 1: \(value)")
/// }
/// }
///
/// let consumer2 = Task {
/// for await value in shared {
/// print("Consumer 2: \(value)")
/// }
/// }
///
/// await consumer1.value
/// await consumer2.value
/// ```
///
/// - Parameter bufferingPolicy: The policy controlling how elements are enqueued to the shared buffer. Defaults to `.bounded(1)`.
/// - `.bounded(n)`: Limits the buffer to `n` elements, applying backpressure to the source when that limit is reached
/// - `.bufferingOldest(n)`: Keeps the oldest `n` elements, discarding newer ones when full
/// - `.bufferingNewest(n)`: Keeps the newest `n` elements, discarding older ones when full
/// - `.unbounded`: Allows unlimited buffering (use with caution)
///
/// - Returns: A sendable async sequence that can be safely shared across multiple concurrent tasks.
///
public func share(
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
) -> some AsyncSequence<Element, Failure> & Sendable {
// The iterator is transferred to the isolation of the iterating task
// this has to be done "unsafely" since we cannot annotate the transfer
// however since iterating an AsyncSequence types twice has been defined
// as invalid and one creation of the iterator is virtually a consuming
// operation so this is safe at runtime.
// The general principal of `.share()` is to provide a mecahnism for non-
// shared AsyncSequence types to be shared. The parlance for those is
// that the base AsyncSequence type is not Sendable. If the iterator
// is not marked as `nonisolated(unsafe)` the compiler will claim that
// the value is "Capture of 'iterator' with non-Sendable type 'Self.AsyncIterator' in a '@Sendable' closure;"
// Since the closure returns a disconnected non-sendable value there is no
// distinct problem here and the compiler just needs to be informed
// that the diagnostic is overly pessimistic.
nonisolated(unsafe) let iterator = makeAsyncIterator()
return AsyncShareSequence<Self>(
{
iterator
},
bufferingPolicy: bufferingPolicy
)
}
}
// An async sequence that enables safe concurrent sharing of a single source sequence.
//
// `AsyncShareSequence` wraps a base async sequence and allows multiple concurrent iterators
// to consume elements from the same source. It handles all the complexity of coordinating
// between multiple consumers, buffering elements, and managing the lifecycle of the underlying
// iteration.
//
// ## Key Features
//
// **Single Source Iteration**: The base sequence's iterator is created and consumed only once
// **Concurrent Safe**: Multiple tasks can safely iterate simultaneously
// **Configurable Buffering**: Supports various buffering strategies for different use cases
// **Automatic Cleanup**: Properly manages resources and cancellation across all consumers
//
// ## Internal Architecture
//
// The implementation uses several key components:
// `Side`: Represents a single consumer's iteration state
// `Iteration`: Coordinates all consumers and manages the shared buffer
// `Extent`: Manages the overall lifecycle and cleanup
//
// This type is typically not used directly; instead, use the `share()` method on any
// async sequence that meets the sendability requirements.
@available(AsyncAlgorithms 1.1, *)
struct AsyncShareSequence<Base: AsyncSequence>: Sendable
where Base.Element: Sendable, Base: SendableMetatype, Base.AsyncIterator: SendableMetatype {
// Represents a single consumer's connection to the shared sequence.
//
// Each iterator of the shared sequence creates its own `Side` instance, which tracks
// that consumer's position in the shared buffer and manages its continuation for
// async iteration. The `Side` automatically registers itself with the central
// `Iteration` coordinator and cleans up when deallocated.
//
// ## Lifecycle
//
// **Creation**: Automatically registers with the iteration coordinator
// **Usage**: Tracks buffer position and manages async continuations
// **Cleanup**: Automatically unregisters and cancels pending operations on deinit
final class Side {
// Tracks the state of a single consumer's iteration.
//
// - `continuation`: The continuation waiting for the next element (nil if not waiting)
// - `position`: The consumer's current position in the shared buffer
struct State {
var continuation: UnsafeContinuation<Result<Element?, Failure>, Never>?
var position = 0
// Creates a new state with the position adjusted by the given offset.
//
// This is used when the shared buffer is trimmed to maintain correct
// relative positioning for this consumer.
//
// - Parameter adjustment: The number of positions to subtract from the current position
// - Returns: A new `State` with the adjusted position
func offset(_ adjustment: Int) -> State {
State(continuation: continuation, position: position - adjustment)
}
}
let iteration: Iteration
let id: Int
init(_ iteration: Iteration) {
self.iteration = iteration
id = iteration.registerSide()
}
deinit {
iteration.unregisterSide(id)
}
func next(isolation actor: isolated (any Actor)?) async throws(Failure) -> Element? {
try await iteration.next(isolation: actor, id: id)
}
}
// The central coordinator that manages the shared iteration state.
//
// `Iteration` is responsible for:
// Managing the single background task that consumes the source sequence
// Coordinating between multiple consumer sides
// Buffering elements according to the specified policy
// Handling backpressure and flow control
// Managing cancellation and cleanup
//
// ## Thread Safety
//
// All operations are synchronized using a `Mutex` to ensure thread-safe access
// to the shared state across multiple concurrent consumers.
final class Iteration: Sendable {
// Represents the state of the background task that consumes the source sequence.
//
// The iteration task goes through several states during its lifecycle:
// `pending`: Initial state, holds the factory to create the iterator
// `starting`: Transitional state while the task is being created
// `running`: Active state with a running background task
// `cancelled`: Terminal state when the iteration has been cancelled
enum IteratingTask {
case pending(@Sendable () -> sending Base.AsyncIterator)
case starting
case running(Task<Void, Never>)
case cancelled
var isStarting: Bool {
switch self {
case .starting: true
default: false
}
}
func cancel() {
switch self {
case .running(let task):
task.cancel()
default:
break
}
}
}
// The complete shared state for coordinating all aspects of the shared iteration.
//
// This state is protected by a mutex and contains all the information needed
// to coordinate between multiple consumers, manage buffering, and control
// the background iteration task.
struct State: Sendable {
// Defines how elements are stored and potentially discarded in the shared buffer.
//
// `unbounded`: Store all elements without limit (may cause memory growth)
// `bufferingOldest(Int)`: Keep only the oldest N elements, ignore newer ones when full
// `bufferingNewest(Int)`: Keep only the newest N elements, discard older ones when full
enum StoragePolicy: Sendable {
case unbounded
case bufferingOldest(Int)
case bufferingNewest(Int)
}
var generation = 0
var sides = [Int: Side.State]()
var iteratingTask: IteratingTask
private(set) var buffer = Deque<Element>()
private(set) var finished = false
private(set) var failure: Failure?
var cancelled = false
var limit: UnsafeContinuation<Bool, Never>?
var demand: UnsafeContinuation<Void, Never>?
let storagePolicy: StoragePolicy
init(
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
bufferingPolicy: AsyncBufferSequencePolicy
) {
self.iteratingTask = .pending(iteratorFactory)
switch bufferingPolicy.policy {
case .bounded: self.storagePolicy = .unbounded
case .bufferingOldest(let bound): self.storagePolicy = .bufferingOldest(bound)
case .bufferingNewest(let bound): self.storagePolicy = .bufferingNewest(bound)
case .unbounded: self.storagePolicy = .unbounded
}
}
// Removes elements from the front of the buffer that all consumers have already processed.
//
// This method finds the minimum position across all active consumers and removes
// that many elements from the front of the buffer. It then adjusts all consumer
// positions to account for the removed elements, maintaining their relative positions.
//
// This optimization prevents the buffer from growing indefinitely when all consumers
// are keeping pace with each other.
mutating func trimBuffer() {
if let minimumIndex = sides.values.map({ $0.position }).min(), minimumIndex > 0 {
buffer.removeFirst(minimumIndex)
sides = sides.mapValues {
$0.offset(minimumIndex)
}
}
}
// Private state machine transitions for the emission of a given value.
//
// This method ensures the continuations are properly consumed when emitting values
// and returns those continuations for resumption.
private mutating func _emit<T>(
_ value: T,
limit: Int
) -> (T, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) {
let belowLimit = buffer.count < limit || limit == 0
defer {
if belowLimit {
self.limit = nil
}
demand = nil
}
guard case .cancelled = iteratingTask else {
return (value, belowLimit ? self.limit : nil, demand, false)
}
return (value, belowLimit ? self.limit : nil, demand, true)
}
// Internal state machine transitions for the emission of a given value.
//
// This method ensures the continuations are properly consumed when emitting values
// and returns those continuations for resumption.
//
// If no limit is specified it interprets that as an unbounded limit.
mutating func emit<T>(
_ value: T,
limit: Int?
) -> (T, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) {
return _emit(value, limit: limit ?? .max)
}
// Adds an element to the buffer according to the configured storage policy.
//
// The behavior depends on the storage policy:
// **Unbounded**: Always appends the element
// **Buffering Oldest**: Appends only if under the limit, otherwise ignores the element
// **Buffering Newest**: Appends if under the limit, otherwise removes the oldest and appends
//
// - Parameter element: The element to add to the buffer
mutating func enqueue(_ element: Element) {
let count = buffer.count
switch storagePolicy {
case .unbounded:
buffer.append(element)
case .bufferingOldest(let limit):
if count < limit {
buffer.append(element)
}
case .bufferingNewest(let limit):
if count < limit {
buffer.append(element)
} else if count > 0 {
buffer.removeFirst()
buffer.append(element)
}
}
}
mutating func finish() {
finished = true
}
mutating func fail(_ error: Failure) {
finished = true
failure = error
}
}
let state: Mutex<State>
let limit: Int?
init(
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
bufferingPolicy: AsyncBufferSequencePolicy
) {
state = Mutex(State(iteratorFactory, bufferingPolicy: bufferingPolicy))
switch bufferingPolicy.policy {
case .bounded(let limit):
self.limit = limit
default:
self.limit = nil
}
}
func cancel() {
let (task, limitContinuation, demand, cancelled) = state.withLock {
state -> (IteratingTask?, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) in
guard state.sides.count == 0 else {
state.cancelled = true
return state.emit(nil, limit: limit)
}
defer {
state.iteratingTask = .cancelled
state.cancelled = true
}
return state.emit(state.iteratingTask, limit: limit)
}
task?.cancel()
limitContinuation?.resume(returning: cancelled)
demand?.resume()
}
func registerSide() -> Int {
state.withLock { state in
defer { state.generation += 1 }
state.sides[state.generation] = Side.State()
return state.generation
}
}
func unregisterSide(_ id: Int) {
let (side, continuation, cancelled, iteratingTaskToCancel) = state.withLock {
state -> (Side.State?, UnsafeContinuation<Bool, Never>?, Bool, IteratingTask?) in
let side = state.sides.removeValue(forKey: id)
state.trimBuffer()
let cancelRequested = state.sides.count == 0 && state.cancelled
guard let limit, state.buffer.count < limit else {
guard case .cancelled = state.iteratingTask else {
defer {
if cancelRequested {
state.iteratingTask = .cancelled
}
}
return (side, nil, false, cancelRequested ? state.iteratingTask : nil)
}
return (side, nil, true, nil)
}
defer { state.limit = nil }
guard case .cancelled = state.iteratingTask else {
defer {
if cancelRequested {
state.iteratingTask = .cancelled
}
}
return (side, state.limit, false, cancelRequested ? state.iteratingTask : nil)
}
return (side, state.limit, true, nil)
}
if let continuation {
continuation.resume(returning: cancelled)
}
if let side {
side.continuation?.resume(returning: .success(nil))
}
if let iteratingTaskToCancel {
iteratingTaskToCancel.cancel()
}
}
func iterate() async -> Bool {
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 {
assert(state.limit == nil)
guard case .cancelled = state.iteratingTask else {
return (continuation, false)
}
return (continuation, true)
}
state.limit = continuation
guard case .cancelled = state.iteratingTask else {
return (nil, false)
}
return (nil, true)
}
if let resume {
resume.resume(returning: cancelled)
}
}
if cancelled {
return false
}
}
// await a demand
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
let hasPendingDemand = state.withLock { state in
for (_, side) in state.sides {
if side.continuation != nil {
return true
}
}
state.demand = continuation
return false
}
if hasPendingDemand {
continuation.resume()
}
}
return state.withLock { state in
switch state.iteratingTask {
case .cancelled:
return false
default:
return true
}
}
}
func cancel(id: Int) {
unregisterSide(id) // doubly unregistering is idempotent but has a side effect of emitting nil if present
}
struct Resumption {
let continuation: UnsafeContinuation<Result<Element?, Failure>, Never>
let result: Result<Element?, Failure>
func resume() {
continuation.resume(returning: result)
}
}
func emit(_ result: Result<Element?, Failure>) {
let (resumptions, limitContinuation, demandContinuation, cancelled) = state.withLock {
state -> ([Resumption], UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) in
var resumptions = [Resumption]()
switch result {
case .success(let element):
if let element {
state.enqueue(element)
} else {
state.finish()
}
case .failure(let failure):
state.fail(failure)
}
for (id, side) in state.sides {
if let continuation = side.continuation {
if side.position < state.buffer.count {
resumptions.append(Resumption(continuation: continuation, result: .success(state.buffer[side.position])))
state.sides[id]?.position += 1
state.sides[id]?.continuation = nil
} else if state.finished {
state.sides[id]?.continuation = nil
if let failure = state.failure {
resumptions.append(Resumption(continuation: continuation, result: .failure(failure)))
} else {
resumptions.append(Resumption(continuation: continuation, result: .success(nil)))
}
}
}
}
state.trimBuffer()
return state.emit(resumptions, limit: limit)
}
if let limitContinuation {
limitContinuation.resume(returning: cancelled)
}
if let demandContinuation {
demandContinuation.resume()
}
for resumption in resumptions {
resumption.resume()
}
}
private func nextIteration(
_ id: Int
) async -> Result<AsyncShareSequence<Base>.Element?, AsyncShareSequence<Base>.Failure> {
return await withTaskCancellationHandler {
await withUnsafeContinuation { continuation in
let (res, limitContinuation, demandContinuation, cancelled) = state.withLock {
state -> (
Result<Element?, Failure>?, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool
) in
guard let side = state.sides[id] else {
return state.emit(.success(nil), limit: limit)
}
if side.position < state.buffer.count {
// There's an element available at this position
let element = state.buffer[side.position]
state.sides[id]?.position += 1
state.trimBuffer()
return state.emit(.success(element), limit: limit)
} else {
// Position is beyond the buffer
if let failure = state.failure {
return state.emit(.failure(failure), limit: limit)
} else if state.finished {
return state.emit(.success(nil), limit: limit)
} else {
state.sides[id]?.continuation = continuation
return state.emit(nil, limit: limit)
}
}
}
if let limitContinuation {
limitContinuation.resume(returning: cancelled)
}
if let demandContinuation {
demandContinuation.resume()
}
if let res {
continuation.resume(returning: res)
}
}
} onCancel: {
cancel(id: id)
}
}
private func iterationLoop(factory: @Sendable () -> sending Base.AsyncIterator) async {
var iterator = factory()
do {
while await iterate() {
if let element = try await iterator.next() {
emit(.success(element))
} else {
emit(.success(nil))
}
}
} catch {
emit(.failure(error as! Failure))
}
}
func next(isolation actor: isolated (any Actor)?, id: Int) async throws(Failure) -> Element? {
let (factory, cancelled) = state.withLock { state -> ((@Sendable () -> sending Base.AsyncIterator)?, Bool) in
switch state.iteratingTask {
case .pending(let factory):
state.iteratingTask = .starting
return (factory, false)
case .cancelled:
return (nil, true)
default:
return (nil, false)
}
}
if cancelled { return nil }
if let factory {
let task: Task<Void, Never>
// for the fancy dance of availability and canImport see the comment on the next check for details
#if swift(>=6.2)
if #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) {
task = Task(name: "Share Iteration") { [factory, self] in
await iterationLoop(factory: factory)
}
} else {
task = Task.detached(name: "Share Iteration") { [factory, self] in
await iterationLoop(factory: factory)
}
}
#else
task = Task.detached { [factory, self] in
await iterationLoop(factory: factory)
}
#endif
// Known Issue: there is a very small race where the task may not get a priority escalation during startup
// this unfortuantely cannot be avoided since the task should ideally not be formed within the critical
// region of the state. Since that could lead to potential deadlocks in low-core-count systems.
// That window is relatively small and can be revisited if a suitable proof of safe behavior can be
// determined.
state.withLock { state in
precondition(state.iteratingTask.isStarting)
state.iteratingTask = .running(task)
}
}
// withTaskPriorityEscalationHandler is only available for the '26 releases and the 6.2 version of
// the _Concurrency library. This menas for Darwin based OSes we have to have a fallback at runtime,
// and for non-darwin OSes we need to verify against the ability to import that version.
// Using this priority escalation means that the base task can avoid being detached.
//
// This is disabled for now until the 9999 availability is removed from `withTaskPriorityEscalationHandler`
#if false // TODO: remove when this is resolved
guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else {
return try await nextIteration(id).get()
}
return try await withTaskPriorityEscalationHandler {
return await nextIteration(id)
} onPriorityEscalated: { old, new in
let task = state.withLock { state -> Task<Void, Never>? in
switch state.iteratingTask {
case .running(let task):
return task
default:
return nil
}
}
task?.escalatePriority(to: new)
}.get()
#else
return try await nextIteration(id).get()
#endif
}
}
// Manages the lifecycle of the shared iteration.
//
// `Extent` serves as the ownership boundary for the shared sequence. When the
// `AsyncShareSequence` itself is deallocated, the `Extent` ensures that the
// background iteration task is properly cancelled and all resources are cleaned up.
//
// This design allows multiple iterators to safely reference the same underlying
// iteration coordinator while ensuring proper cleanup when the shared sequence
// is no longer needed.
final class Extent: Sendable {
let iteration: Iteration
init(
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
bufferingPolicy: AsyncBufferSequencePolicy
) {
iteration = Iteration(iteratorFactory, bufferingPolicy: bufferingPolicy)
}
deinit {
iteration.cancel()
}
}
let extent: Extent
init(
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
bufferingPolicy: AsyncBufferSequencePolicy
) {
extent = Extent(iteratorFactory, bufferingPolicy: bufferingPolicy)
}
}
@available(AsyncAlgorithms 1.1, *)
extension AsyncShareSequence: AsyncSequence {
typealias Element = Base.Element
typealias Failure = Base.Failure
struct Iterator: AsyncIteratorProtocol {
let side: Side
init(_ iteration: Iteration) {
side = Side(iteration)
}
mutating func next() async rethrows -> Element? {
try await side.next(isolation: nil)
}
mutating func next(isolation actor: isolated (any Actor)?) async throws(Failure) -> Element? {
try await side.next(isolation: actor)
}
}
func makeAsyncIterator() -> Iterator {
Iterator(extent.iteration)
}
}
#endif
@@ -74,6 +74,14 @@ public struct AsyncBufferSequencePolicy: Sendable {
/// An `AsyncSequence` that buffers elements in regard to a policy.
@available(AsyncAlgorithms 1.0, *)
public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence {
// Internal implementation note:
// This type origianlly had no requirement that the element is actually Sendable. However,
// that is technically an implementation detail hole in the safety of the system, it needs
// to specify that the element is actually Sendable since the draining mechanism passes
// through the isolation that is in nature sending but cannot be marked as such for the
// isolated next method.
// In practice the users of this type are safe from isolation crossing since the Element
// is as sendable as it is required by the base sequences the buffer is constructed from.
enum StorageType {
case transparent(Base.AsyncIterator)
case bounded(storage: BoundedBufferStorage<Base>)
@@ -121,9 +129,9 @@ public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence
self.storageType = .transparent(iterator)
return element
case .bounded(let storage):
return try await storage.next()?._rethrowGet()
return try await storage.next().wrapped?._rethrowGet()
case .unbounded(let storage):
return try await storage.next()?._rethrowGet()
return try await storage.next().wrapped?._rethrowGet()
}
}
}
@@ -15,7 +15,7 @@ import DequeModule
struct BoundedBufferStateMachine<Base: AsyncSequence> {
typealias Element = Base.Element
typealias SuspendedProducer = UnsafeContinuation<Void, Never>
typealias SuspendedConsumer = UnsafeContinuation<Result<Base.Element, Error>?, Never>
typealias SuspendedConsumer = UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>
// We are using UnsafeTransfer here since we have to get the elements from the task
// into the consumer task. This is a transfer but we cannot prove this to the compiler at this point
@@ -137,7 +137,7 @@ struct BoundedBufferStateMachine<Base: AsyncSequence> {
enum ElementProducedAction {
case none
case resumeConsumer(continuation: SuspendedConsumer, result: Result<Element, Error>)
case resumeConsumer(continuation: SuspendedConsumer, result: UnsafeTransfer<Result<Base.Element, Error>?>)
}
mutating func elementProduced(element: Element) -> ElementProducedAction {
@@ -161,7 +161,7 @@ struct BoundedBufferStateMachine<Base: AsyncSequence> {
// we have an awaiting consumer, we can resume it with the element and exit
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
return .resumeConsumer(continuation: suspendedConsumer, result: .success(element))
return .resumeConsumer(continuation: suspendedConsumer, result: UnsafeTransfer(.success(element)))
case .buffering(_, _, .some, _):
preconditionFailure("Invalid state. There should not be a suspended producer.")
@@ -177,7 +177,7 @@ struct BoundedBufferStateMachine<Base: AsyncSequence> {
enum FinishAction {
case none
case resumeConsumer(
continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
continuation: UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>?
)
}
@@ -295,7 +295,7 @@ struct BoundedBufferStateMachine<Base: AsyncSequence> {
case resumeProducerAndConsumer(
task: Task<Void, Never>,
producerContinuation: UnsafeContinuation<Void, Never>?,
consumerContinuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
consumerContinuation: UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>?
)
}
@@ -17,7 +17,7 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
self.stateMachine = ManagedCriticalState(BoundedBufferStateMachine(base: base, limit: limit))
}
func next() async -> Result<Base.Element, Error>? {
func next() async -> UnsafeTransfer<Result<Base.Element, Error>?> {
return await withTaskCancellationHandler {
let action: BoundedBufferStateMachine<Base>.NextAction? = self.stateMachine.withCriticalRegion {
stateMachine in
@@ -45,14 +45,14 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
case .returnResult(let producerContinuation, let result):
producerContinuation?.resume()
return result
return UnsafeTransfer(result)
case .none:
break
}
return await withUnsafeContinuation {
(continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
(continuation: UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>) in
let action = self.stateMachine.withCriticalRegion { stateMachine in
stateMachine.nextSuspended(continuation: continuation)
}
@@ -61,7 +61,7 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
break
case .returnResult(let producerContinuation, let result):
producerContinuation?.resume()
continuation.resume(returning: result)
continuation.resume(returning: UnsafeTransfer(result))
}
}
} onCancel: {
@@ -120,7 +120,7 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: nil)
continuation?.resume(returning: UnsafeTransfer(nil))
}
} catch {
let action = self.stateMachine.withCriticalRegion { stateMachine in
@@ -130,7 +130,7 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: .failure(error))
continuation?.resume(returning: UnsafeTransfer(Result<Base.Element, Error>.failure(error)))
}
}
}
@@ -148,7 +148,7 @@ final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Send
case .resumeProducerAndConsumer(let task, let producerContinuation, let consumerContinuation):
task.cancel()
producerContinuation?.resume()
consumerContinuation?.resume(returning: nil)
consumerContinuation?.resume(returning: UnsafeTransfer(nil))
}
}
@@ -14,7 +14,7 @@ import DequeModule
@available(AsyncAlgorithms 1.0, *)
struct UnboundedBufferStateMachine<Base: AsyncSequence> {
typealias Element = Base.Element
typealias SuspendedConsumer = UnsafeContinuation<Result<Element, Error>?, Never>
typealias SuspendedConsumer = UnsafeContinuation<UnsafeTransfer<Result<Element, Error>?>, Never>
enum Policy {
case unlimited
@@ -73,7 +73,7 @@ struct UnboundedBufferStateMachine<Base: AsyncSequence> {
case none
case resumeConsumer(
continuation: SuspendedConsumer,
result: Result<Element, Error>
result: UnsafeTransfer<Result<Element, Error>?>
)
}
@@ -108,7 +108,7 @@ struct UnboundedBufferStateMachine<Base: AsyncSequence> {
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
return .resumeConsumer(
continuation: suspendedConsumer,
result: .success(element)
result: UnsafeTransfer(.success(element))
)
case .modifying:
@@ -17,7 +17,7 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
self.stateMachine = ManagedCriticalState(UnboundedBufferStateMachine<Base>(base: base, policy: policy))
}
func next() async -> Result<Base.Element, Error>? {
func next() async -> UnsafeTransfer<Result<Base.Element, Error>?> {
return await withTaskCancellationHandler {
let action: UnboundedBufferStateMachine<Base>.NextAction? = self.stateMachine.withCriticalRegion {
@@ -42,13 +42,13 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
case .suspend:
break
case .returnResult(let result):
return result
return UnsafeTransfer(result)
case .none:
break
}
return await withUnsafeContinuation {
(continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
(continuation: UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>) in
let action = self.stateMachine.withCriticalRegion { stateMachine in
stateMachine.nextSuspended(continuation: continuation)
}
@@ -56,7 +56,7 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
case .none:
break
case .resumeConsumer(let result):
continuation.resume(returning: result)
continuation.resume(returning: UnsafeTransfer(result))
}
}
} onCancel: {
@@ -89,7 +89,7 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: nil)
continuation?.resume(returning: UnsafeTransfer(nil))
}
} catch {
let action = self.stateMachine.withCriticalRegion { stateMachine in
@@ -99,7 +99,7 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: .failure(error))
continuation?.resume(returning: UnsafeTransfer(Result<Base.Element, Error>.failure(error)))
}
}
}
@@ -116,7 +116,7 @@ final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Se
break
case .resumeConsumer(let task, let continuation):
task.cancel()
continuation?.resume(returning: nil)
continuation?.resume(returning: UnsafeTransfer(nil))
}
}
@@ -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
@@ -0,0 +1,329 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2023 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
//
//===----------------------------------------------------------------------===//
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftCertificates open source project
//
// Copyright (c) 2023 Apple Inc. and the SwiftCertificates project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// ``_TinyArray`` is a ``RandomAccessCollection`` optimised to store zero or one ``Element``.
/// It supports arbitrary many elements but if only up to one ``Element`` is stored it does **not** allocate separate storage on the heap
/// and instead stores the ``Element`` inline.
@usableFromInline
struct _TinyArray<Element> {
@usableFromInline
enum Storage {
case one(Element)
case arbitrary([Element])
}
@usableFromInline
var storage: Storage
}
// MARK: - TinyArray "public" interface
extension _TinyArray: Equatable where Element: Equatable {}
extension _TinyArray: Hashable where Element: Hashable {}
extension _TinyArray: Sendable where Element: Sendable {}
extension _TinyArray: RandomAccessCollection {
@usableFromInline
typealias Element = Element
@usableFromInline
typealias Index = Int
@inlinable
subscript(position: Int) -> Element {
get {
self.storage[position]
}
set {
self.storage[position] = newValue
}
}
@inlinable
var startIndex: Int {
self.storage.startIndex
}
@inlinable
var endIndex: Int {
self.storage.endIndex
}
}
extension _TinyArray {
@inlinable
init(_ elements: some Sequence<Element>) {
self.storage = .init(elements)
}
@inlinable
init() {
self.storage = .init()
}
@inlinable
mutating func append(_ newElement: Element) {
self.storage.append(newElement)
}
@inlinable
mutating func append(contentsOf newElements: some Sequence<Element>) {
self.storage.append(contentsOf: newElements)
}
@discardableResult
@inlinable
mutating func remove(at index: Int) -> Element {
self.storage.remove(at: index)
}
@inlinable
mutating func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows {
try self.storage.removeAll(where: shouldBeRemoved)
}
@inlinable
mutating func sort(by areInIncreasingOrder: (Element, Element) throws -> Bool) rethrows {
try self.storage.sort(by: areInIncreasingOrder)
}
}
// MARK: - TinyArray.Storage "private" implementation
extension _TinyArray.Storage: Equatable where Element: Equatable {
@inlinable
static func == (lhs: Self, rhs: Self) -> Bool {
switch (lhs, rhs) {
case (.one(let lhs), .one(let rhs)):
return lhs == rhs
case (.arbitrary(let lhs), .arbitrary(let rhs)):
// we don't use lhs.elementsEqual(rhs) so we can hit the fast path from Array
// if both arrays share the same underlying storage: https://github.com/apple/swift/blob/b42019005988b2d13398025883e285a81d323efa/stdlib/public/core/Array.swift#L1775
return lhs == rhs
case (.one(let element), .arbitrary(let array)),
(.arbitrary(let array), .one(let element)):
guard array.count == 1 else {
return false
}
return element == array[0]
}
}
}
extension _TinyArray.Storage: Hashable where Element: Hashable {
@inlinable
func hash(into hasher: inout Hasher) {
// same strategy as Array: https://github.com/apple/swift/blob/b42019005988b2d13398025883e285a81d323efa/stdlib/public/core/Array.swift#L1801
hasher.combine(count)
for element in self {
hasher.combine(element)
}
}
}
extension _TinyArray.Storage: Sendable where Element: Sendable {}
extension _TinyArray.Storage: RandomAccessCollection {
@inlinable
subscript(position: Int) -> Element {
get {
switch self {
case .one(let element):
guard position == 0 else {
fatalError("index \(position) out of bounds")
}
return element
case .arbitrary(let elements):
return elements[position]
}
}
set {
switch self {
case .one:
guard position == 0 else {
fatalError("index \(position) out of bounds")
}
self = .one(newValue)
case .arbitrary(var elements):
elements[position] = newValue
self = .arbitrary(elements)
}
}
}
@inlinable
var startIndex: Int {
0
}
@inlinable
var endIndex: Int {
switch self {
case .one: return 1
case .arbitrary(let elements): return elements.endIndex
}
}
}
extension _TinyArray.Storage {
@inlinable
init(_ elements: some Sequence<Element>) {
var iterator = elements.makeIterator()
guard let firstElement = iterator.next() else {
self = .arbitrary([])
return
}
guard let secondElement = iterator.next() else {
// newElements just contains a single element
// and we hit the fast path
self = .one(firstElement)
return
}
var elements: [Element] = []
elements.reserveCapacity(elements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
while let nextElement = iterator.next() {
elements.append(nextElement)
}
self = .arbitrary(elements)
}
@inlinable
init() {
self = .arbitrary([])
}
@inlinable
mutating func append(_ newElement: Element) {
self.append(contentsOf: CollectionOfOne(newElement))
}
@inlinable
mutating func append(contentsOf newElements: some Sequence<Element>) {
switch self {
case .one(let firstElement):
var iterator = newElements.makeIterator()
guard let secondElement = iterator.next() else {
// newElements is empty, nothing to do
return
}
var elements: [Element] = []
elements.reserveCapacity(1 + newElements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
elements.appendRemainingElements(from: &iterator)
self = .arbitrary(elements)
case .arbitrary(var elements):
if elements.isEmpty {
// if `self` is currently empty and `newElements` just contains a single
// element, we skip allocating an array and set `self` to `.one(firstElement)`
var iterator = newElements.makeIterator()
guard let firstElement = iterator.next() else {
// newElements is empty, nothing to do
return
}
guard let secondElement = iterator.next() else {
// newElements just contains a single element
// and we hit the fast path
self = .one(firstElement)
return
}
elements.reserveCapacity(elements.count + newElements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
elements.appendRemainingElements(from: &iterator)
self = .arbitrary(elements)
} else {
elements.append(contentsOf: newElements)
self = .arbitrary(elements)
}
}
}
@discardableResult
@inlinable
mutating func remove(at index: Int) -> Element {
switch self {
case .one(let oldElement):
guard index == 0 else {
fatalError("index \(index) out of bounds")
}
self = .arbitrary([])
return oldElement
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
return elements.remove(at: index)
}
}
@inlinable
mutating func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows {
switch self {
case .one(let oldElement):
if try shouldBeRemoved(oldElement) {
self = .arbitrary([])
}
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
return try elements.removeAll(where: shouldBeRemoved)
}
}
@inlinable
mutating func sort(by areInIncreasingOrder: (Element, Element) throws -> Bool) rethrows {
switch self {
case .one:
// a collection of just one element is always sorted, nothing to do
break
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
try elements.sort(by: areInIncreasingOrder)
}
}
}
extension Array {
@inlinable
mutating func appendRemainingElements(from iterator: inout some IteratorProtocol<Element>) {
while let nextElement = iterator.next() {
append(nextElement)
}
}
}
+39 -5
View File
@@ -19,6 +19,13 @@ import Musl
import WinSDK
#elseif canImport(Bionic)
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
@@ -26,8 +33,14 @@ import Bionic
internal struct Lock {
#if canImport(Darwin)
typealias Primitive = os_unfair_lock
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#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
@@ -44,9 +57,14 @@ internal struct Lock {
fileprivate static func initialize(_ platformLock: PlatformLock) {
#if canImport(Darwin)
platformLock.initialize(to: os_unfair_lock())
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#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
@@ -55,7 +73,7 @@ internal struct Lock {
}
fileprivate static func deinitialize(_ platformLock: PlatformLock) {
#if canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#if canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
let result = pthread_mutex_destroy(platformLock)
precondition(result == 0, "pthread_mutex_destroy failed")
#endif
@@ -65,8 +83,14 @@ internal struct Lock {
fileprivate static func lock(_ platformLock: PlatformLock) {
#if canImport(Darwin)
os_unfair_lock_lock(platformLock)
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#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
@@ -77,9 +101,15 @@ internal struct Lock {
fileprivate static func unlock(_ platformLock: PlatformLock) {
#if canImport(Darwin)
os_unfair_lock_unlock(platformLock)
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#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
@@ -151,6 +181,10 @@ struct ManagedCriticalState<State> {
return try critical(&header.pointee)
}
}
func withLock<R>(_ critical: (inout State) throws -> R) rethrows -> R {
return try withCriticalRegion(critical)
}
}
extension ManagedCriticalState: @unchecked Sendable where State: Sendable {}
@@ -0,0 +1,728 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2023 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)
/// An error that is thrown from the various `send` methods of the
/// ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// This error is thrown when the channel is already finished when
/// trying to send new elements to the source.
@available(AsyncAlgorithms 1.1, *)
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error {
@usableFromInline
init() {}
}
/// A multi-producer single-consumer channel.
///
/// The ``MultiProducerSingleConsumerAsyncChannel`` provides a ``MultiProducerSingleConsumerAsyncChannel/Source`` to
/// send values to the channel. The channel supports different back pressure strategies to control the
/// buffering and demand. The channel will buffer values until its backpressure strategy decides that the
/// producer have to wait.
///
/// This channel is also suitable for the single-producer single-consumer use-case
///
/// ## Using a MultiProducerSingleConsumerAsyncChannel
///
/// To use a ``MultiProducerSingleConsumerAsyncChannel`` you have to create a new channel with its source first by calling
/// the ``MultiProducerSingleConsumerAsyncChannel/makeChannel(of:throwing:backpressureStrategy:)`` method.
/// Afterwards, you can pass the source to the producer and the channel to the consumer.
///
/// ```
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 2, high: 4)
/// )
///
/// // The channel and source can be extracted from the returned type
/// let channel = consume channelAndSource.channel
/// let source = consume channelAndSource.source
/// ```
///
/// ### Asynchronous producing
///
/// Values can be send to the source from asynchronous contexts using ``MultiProducerSingleConsumerAsyncChannel/Source/send(contentsOf:)-1h7t9``
/// and ``MultiProducerSingleConsumerAsyncChannel/Source/send(_:)->()``. Backpressure results in calls
/// to the `send` methods to be suspended. Once more elements should be produced the `send` methods will be resumed.
///
/// ```
/// try await withThrowingTaskGroup(of: Void.self) { group in
/// group.addTask {
/// try await source.send(1)
/// try await source.send(2)
/// try await source.send(3)
/// }
///
/// for await element in channel {
/// print(element)
/// }
/// }
/// ```
///
/// ### Synchronous produceing
///
/// Values can also be send to the source from synchronous context. Backpressure is also exposed on the synchronous contexts; however,
/// it is up to the caller to decide how to properly translate the backpressure to underlying producer e.g. by blocking the thread.
///
/// ```swift
/// do {
/// let sendResult = try source.send(contentsOf: sequence)
///
/// switch sendResult {
/// case .produceMore:
/// // Trigger more production in the underlying system
///
/// case .enqueueCallback(let callbackHandle):
/// // There are enough values in the channel already. We need to enqueue
/// // a callback to get notified when we should produce more.
/// callbackHandle.enqueueCallback(onProduceMore: { result in
/// switch result {
/// case .success:
/// // Trigger more production in the underlying system
/// case .failure(let error):
/// // Terminate the underlying producer
/// }
/// })
/// }
/// } catch {
/// // `send(contentsOf:)` throws if the channel already terminated
/// }
/// ```
///
/// ### Multiple producers
///
/// To support multiple producers the source offers a ``Source/makeAdditionalSource()`` method to produce a new source.
///
/// ### Terminating the production of values
///
/// The consumer can be terminated through multiple ways:
/// - Calling ``Source/finish(throwing:)``.
/// - Deiniting all sources.
///
/// In both cases, if there are still elements buffered by the channel, then the consumer will receive
/// all buffered elements. Afterwards it will be terminated.
///
/// ### Observing termination of the consumer
///
/// When the consumer stops consumption by either deiniting the channel or the task calling ``next(isolation:)``
/// getting cancelled, the source will get notified about the termination if a termination callback has been set
/// before by calling ``Source/setOnTerminationCallback(_:)``.
@available(AsyncAlgorithms 1.1, *)
public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>: ~Copyable {
/// The backing storage.
@usableFromInline
let storage: _Storage
/// A struct containing the initialized channel and source.
///
/// This struct can be deconstructed by consuming the individual
/// components from it.
///
/// ```swift
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 5, high: 10)
/// )
/// var channel = consume channelAndSource.channel
/// var source = consume channelAndSource.source
/// ```
@frozen
public struct ChannelAndStream: ~Copyable {
/// The channel.
@usableFromInline
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 {
var channel = self.channel.swap(newValue: nil)
return channel.take()!
}
/// The source.
public var source: Source
init(
channel: consuming sending MultiProducerSingleConsumerAsyncChannel,
source: consuming Source
) {
self.channel = Disconnected(value: channel)
self.source = source
}
}
/// Initializes a new ``MultiProducerSingleConsumerAsyncChannel`` and an ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// - Parameters:
/// - elementType: The element type of the channel.
/// - failureType: The failure type of the channel.
/// - backpressureStrategy: The backpressure strategy that the channel should use.
/// - Returns: A struct containing the channel and its source. The source should be passed to the
/// producer while the channel should be passed to the consumer.
public static func makeChannel(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy
) -> sending ChannelAndStream {
let storage = _Storage(
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
)
let source = Source(storage: storage)
return .init(channel: .init(storage: storage), source: source)
}
init(storage: _Storage) {
self.storage = storage
}
deinit {
self.storage.channelDeinitialized()
}
/// Returns the next element.
///
/// If this method returns `nil` it indicates that no further values can ever
/// be returned. The channel automatically closes when all sources have been deinited.
///
/// If there are no elements and the channel has not been finished yet, this method will
/// suspend until an element is send to the channel.
///
/// If the task calling this method is cancelled this method will return `nil`.
///
/// - Parameter isolation: The callers isolation.
/// - Returns: The next buffered element.
@inlinable
public mutating func next(
isolation: isolated (any Actor)? = #isolation
) async throws(Failure) -> Element? {
do {
return try await self.storage.next()
} catch {
// This force-cast is safe since we only allow closing the source with this failure
// We only need this force cast since continuations don't support typed throws yet.
throw error as! Failure
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// A struct to send values to the channel.
///
/// Use this source to provide elements to the channel by calling one of the `send` methods.
public struct Source: ~Copyable {
/// A struct representing the backpressure of the channel.
public struct BackpressureStrategy: Sendable {
var internalBackpressureStrategy: _InternalBackpressureStrategy
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: nil)
)
)
}
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
/// - waterLevelForElement: A closure used to compute the contribution of each buffered element to the current water level.
///
/// - Important: `waterLevelForElement` will be called during a lock on each element when it is written into the source and when
/// it is consumed from the channel, so it must be side-effect free and at best constant in time.
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)
)
)
}
}
/// A type that indicates the result of sending elements to the source.
public enum SendResult: ~Copyable, Sendable {
/// A handle that is returned when the channel's backpressure strategy indicated that production should
/// be suspended. Use this handle to enqueue a callback by calling the ``CallbackHandle/enqueueCallback(onProduceMore:)`` method.
///
/// - Important: ``CallbackHandle/enqueueCallback(onProduceMore:)`` and ``CallbackHandle/cancelCallback()`` must
/// only be called once.
public struct CallbackHandle: Sendable, Hashable {
@usableFromInline
let _id: UInt64
@usableFromInline
let _storage: _Storage
@usableFromInline
init(id: UInt64, storage: _Storage) {
self._id = id
self._storage = storage
}
/// Enqueues a callback that will be invoked once more elements should be produced.
///
/// - Important: Calling enqueue more than once is **not allowed**.
///
/// - Parameters:
/// - onProduceMore: The callback which gets invoked once more elements should be produced.
@inlinable
public mutating func enqueueCallback(
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
) {
self._storage.enqueueProducer(callbackToken: self._id, onProduceMore: onProduceMore)
}
/// Cancel an enqueued callback.
///
/// - Note: This methods supports being called before ``enqueueCallback(onProduceMore:)`` is called.
///
/// - Important: Calling enqueue more than once is **not allowed**.
@inlinable
public mutating func cancelCallback() {
self._storage.cancelProducer(callbackToken: self._id)
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs._id == rhs._id
}
@inlinable
public func hash(into hasher: inout Hasher) {
hasher.combine(self._id)
}
}
/// Indicates that more elements should be produced and send to the source.
case produceMore
/// Indicates that a callback should be enqueued.
case enqueueCallback(CallbackHandle)
}
@usableFromInline
let _storage: _Storage
@usableFromInline
let _id: UInt64
internal init(
storage: _Storage
) {
self._storage = storage
self._id = self._storage.sourceInitialized()
}
deinit {
self._storage.sourceDeinitialized()
}
/// Sets a callback to invoke when the channel terminated.
///
/// This is called after the last element has been consumed by the channel.
/// If the channel has already terminated this callback is called immediately.
///
/// - Important: Only one termination callback can be set per source. Setting a callback if
/// a previous one has been set will override the previous one.
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
}
/// Creates a new source which can be used to send elements to the channel concurrently.
///
/// The channel will only automatically be finished if all existing sources have been deinited.
///
/// - Returns: A new source for sending elements to the channel.
public mutating func makeAdditionalSource() -> sending Self {
.init(storage: self._storage)
}
/// Sends 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.
///
/// - Parameter sequence: The elements to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
@inlinable
public mutating func send<S>(
contentsOf sequence: consuming sending S
) throws -> SendResult where Element == S.Element, S: Sequence, Element: Copyable {
try self._storage.send(contentsOf: sequence)
}
/// Send the 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.
///
/// - Parameter element: The element to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
@inlinable
public mutating func send(_ element: consuming sending Element) throws -> SendResult {
try self._storage.send(contentsOf: CollectionOfOne(element))
}
/// Send new elements to the channel and provide a callback which will be invoked once more elements should be produced.
///
/// 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 `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(contentsOf:onProduceMore:)``.
@inlinable
public mutating func send<S>(
contentsOf sequence: consuming sending S,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) where Element == S.Element, S: Sequence, Element: Copyable {
do {
let sendResult = try self.send(contentsOf: sequence)
switch consume sendResult {
case .produceMore:
onProduceMore(Result<Void, Error>.success(()))
case .enqueueCallback(var callbackHandle):
callbackHandle.enqueueCallback(onProduceMore: onProduceMore)
}
} catch {
onProduceMore(.failure(error))
}
}
/// Sends the 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 `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - element: The element to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(_:onProduceMore:)``.
@inlinable
public mutating func send(
_ element: consuming sending Element,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) {
do {
let sendResult = try self.send(element)
switch consume sendResult {
case .produceMore:
onProduceMore(Result<Void, Error>.success(()))
case .enqueueCallback(var callbackHandle):
callbackHandle.enqueueCallback(onProduceMore: onProduceMore)
}
} catch {
onProduceMore(.failure(error))
}
}
#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
/// 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 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 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 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))
}
}
#endif
/// Indicates that the production terminated.
///
/// After all buffered elements are consumed the subsequent call to ``MultiProducerSingleConsumerAsyncChannel/next(isolation:)`` will return
/// `nil` or throw an error.
///
/// Calling this function more than once has no effect. After calling finish, the channel enters a terminal state and doesn't accept
/// new elements.
///
/// - Parameters:
/// - error: The error to throw, or `nil`, to finish normally.
@inlinable
public consuming func finish(throwing error: Failure? = nil) {
self._storage.finish(error)
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel where Element: Copyable {
struct ChannelAsyncSequence: AsyncSequence {
@usableFromInline
final class _Backing: Sendable {
@usableFromInline
let storage: MultiProducerSingleConsumerAsyncChannel._Storage
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self.storage = storage
self.storage.sequenceInitialized()
}
deinit {
self.storage.sequenceDeinitialized()
}
}
@usableFromInline
let _backing: _Backing
public func makeAsyncIterator() -> Self.Iterator {
.init(storage: self._backing.storage)
}
}
/// Converts the channel to an asynchronous sequence for consumption.
///
/// - Important: The returned asynchronous sequence only supports a single iterator to be created and
/// will fatal error at runtime on subsequent calls to `makeAsyncIterator`.
public consuming func elements() -> some (AsyncSequence<Element, Failure> & Sendable) {
ChannelAsyncSequence(_backing: .init(storage: self.storage))
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel.ChannelAsyncSequence where Element: Copyable {
struct Iterator: AsyncIteratorProtocol {
@usableFromInline
final class _Backing {
@usableFromInline
let storage: MultiProducerSingleConsumerAsyncChannel._Storage
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self.storage = storage
self.storage.iteratorInitialized()
}
deinit {
self.storage.iteratorDeinitialized()
}
}
@usableFromInline
let _backing: _Backing
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self._backing = .init(storage: storage)
}
@inlinable
mutating func next() async throws -> Element? {
do {
return try await self._backing.storage.next(isolation: nil)
} catch {
throw error as! Failure
}
}
@inlinable
mutating func next(
isolation actor: isolated (any Actor)? = #isolation
) async throws(Failure) -> Element? {
do {
return try await self._backing.storage.next(isolation: actor)
} catch {
throw error as! Failure
}
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel.ChannelAsyncSequence: Sendable {}
#endif
+1 -1
View File
@@ -13,7 +13,7 @@ import AsyncAlgorithms
@available(AsyncAlgorithms 1.0, *)
extension AsyncSequenceValidationDiagram {
public struct Clock {
public struct Clock: Sendable {
let queue: WorkQueue
init(queue: WorkQueue) {
@@ -19,6 +19,8 @@ import Glibc
import Musl
#elseif canImport(Bionic)
import Bionic
#elseif canImport(wasi_pthread)
import wasi_pthread
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#else
@@ -31,7 +33,7 @@ func start_thread(_ raw: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer? {
Unmanaged<TaskDriver>.fromOpaque(raw).takeRetainedValue().run()
return nil
}
#elseif (canImport(Glibc) && !os(Android)) || canImport(Musl)
#elseif (canImport(Glibc) && !os(Android)) || canImport(Musl) || canImport(wasi_pthread)
@available(AsyncAlgorithms 1.0, *)
func start_thread(_ raw: UnsafeMutableRawPointer?) -> UnsafeMutableRawPointer? {
Unmanaged<TaskDriver>.fromOpaque(raw!).takeRetainedValue().run()
@@ -48,24 +50,26 @@ func start_thread(_ raw: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer {
#endif
@available(AsyncAlgorithms 1.0, *)
final class TaskDriver {
let work: (TaskDriver) -> Void
final class TaskDriver: Sendable {
let work: @Sendable (TaskDriver) -> Void
let queue: WorkQueue
#if canImport(Darwin)
var thread: pthread_t?
#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)
var thread = pthread_t()
nonisolated(unsafe) var thread = pthread_t()
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#endif
init(queue: WorkQueue, _ work: @escaping (TaskDriver) -> Void) {
init(queue: WorkQueue, _ work: @Sendable @escaping (TaskDriver) -> Void) {
self.queue = queue
self.work = work
}
func start() {
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic)
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
pthread_create(
&thread,
nil,
@@ -85,7 +89,7 @@ final class TaskDriver {
}
func join() {
#if canImport(Darwin)
#if canImport(Darwin) || canImport(wasi_pthread)
pthread_join(thread!, nil)
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
pthread_join(thread, nil)
+5 -5
View File
@@ -122,7 +122,7 @@ extension AsyncSequenceValidationDiagram {
}
}
private static let _executor: AnyObject = {
private static let _executor: AnyObject & Sendable = {
guard #available(macOS 14.0, iOS 17.0, watchOS 10.0, tvOS 17.0, *) else {
return ClockExecutor_Pre5_9()
}
@@ -134,13 +134,13 @@ extension AsyncSequenceValidationDiagram {
}
#endif
static var clock: Clock?
nonisolated(unsafe) static var clock: Clock?
static var driver: TaskDriver?
nonisolated(unsafe) static var driver: TaskDriver?
static var currentJob: Job?
nonisolated(unsafe) static var currentJob: Job?
static var specificationFailures = [ExpectationFailure]()
nonisolated(unsafe) static var specificationFailures = [ExpectationFailure]()
}
enum ActualResult {
@@ -0,0 +1,92 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
import BasicContainers
/// An error indicating that the reader produced more elements than the specified collection limit.
///
/// This error occurs when calling ``AsyncReader/collect(upTo:body:)`` and the reader's buffer
/// contains more elements than the allowed limit.
public struct AsyncReaderLeftOverElementsError: Error, Hashable {
public init() {}
}
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Collects elements from the reader up to a specified limit and processes them.
///
/// This method continuously reads elements from the async reader, accumulating them in an
/// internal buffer until either it reaches the end of the stream or the specified limit.
/// Once collection completes, it passes the accumulated elements to the provided body
/// closure as an `InputSpan` for processing.
///
/// - Parameters:
/// - limit: The maximum number of elements to collect. This prevents unbounded memory
/// growth when reading from potentially infinite streams.
/// - body: A closure that receives an `InputSpan` containing all collected elements and returns
/// a result of type `Result`.
///
/// - Returns: The value returned by the body closure after processing the collected elements.
///
/// - Throws: An `EitherError` wrapping either a read failure (which itself may be an
/// ``AsyncReaderLeftOverElementsError`` if the reader produces more elements than the limit),
/// or a `Failure` from the body closure.
///
/// ## Example
///
/// ```swift
/// var reader: SomeAsyncReader = ...
///
/// let processedData = try await reader.collect(upTo: 1000) { span in
/// // Process all collected elements
/// }
/// ```
public mutating func collect<Result, Failure: Error>(
upTo limit: Int,
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result {
// TODO: In the future we might want to use a temporary allocation instead
// but those don't support async closures yet.
var collectedBuffer = UniqueArray<ReadElement>()
collectedBuffer.reserveCapacity(limit)
var shouldContinue = true
do {
while shouldContinue {
try await self.read { (buffer: inout Buffer) throws(AsyncReaderLeftOverElementsError) -> Void in
guard buffer.count > 0 else {
shouldContinue = false
return
}
if limit - collectedBuffer.count < buffer.count {
throw AsyncReaderLeftOverElementsError()
}
var consumer = buffer.consumeAll()
while let element = consumer.next() {
collectedBuffer.append(element)
}
}
}
} catch {
throw .first(error)
}
do {
var consumer = collectedBuffer.consumeAll()
return try await body(consumer.drainNext())
} catch {
throw .second(error)
}
}
}
#endif
@@ -0,0 +1,97 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
// swift-format-ignore: AmbiguousTrailingClosureOverload
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Iterates over all chunks from the reader, executing the provided body for each buffer.
///
/// This method continuously reads chunks from the async reader until the stream ends,
/// executing the provided closure for each buffer of elements read. The iteration terminates
/// when the reader produces an empty buffer, indicating the end of the stream.
///
/// - Parameter body: An asynchronous closure that processes each buffer of elements read
/// from the stream.
///
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
/// or a `Failure` from the body closure.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// try await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
public consuming func forEachBuffer<Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Void
) async throws(EitherError<ReadFailure, Failure>) {
var shouldContinue = true
while shouldContinue {
try await self.read { (next) throws(Failure) -> Void in
guard next.count > 0 else {
shouldContinue = false
return
}
try await body(&next)
}
}
}
/// Iterates over all chunks from a non-failing reader, executing the provided body for each buffer.
///
/// This method continuously reads chunks from the async reader until the stream ends,
/// executing the provided closure for each buffer of elements read. The iteration terminates
/// when the reader produces an empty buffer, indicating the end of the stream.
///
/// Use this overload when the reader's ``AsyncReader/ReadFailure`` type is `Never`.
///
/// - Parameter body: An asynchronous closure that processes each buffer of elements read
/// from the stream.
///
/// ## Example
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// await fileReader.forEachBuffer { buffer in
/// print("Processing \(buffer.count) elements")
/// }
/// ```
@inlinable
public consuming func forEachBuffer(
body: (inout Buffer) async -> Void
) async where ReadFailure == Never {
var shouldContinue = true
while shouldContinue {
do {
try await self.read { (next) -> Void in
guard next.count > 0 else {
shouldContinue = false
return
}
await body(&next)
}
} catch {
fatalError()
}
}
}
}
#endif
@@ -0,0 +1,58 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
/// Reads elements asynchronously from a source using callee-managed buffering.
///
/// Adopt ``AsyncReader`` when you need callee-managed buffering,
/// where the reader controls the buffer and passes it to the caller
/// through the `body` closure.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
public protocol AsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
associatedtype ReadElement: ~Copyable
/// The container type the reader uses to pass elements to the caller.
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// Reads elements from the underlying source and passes them to the provided body closure.
///
/// This method asynchronously reads elements from the source into a buffer,
/// then passes the buffer to `body` for processing. When the buffer is empty,
/// the stream has ended.
///
/// ```swift
/// var fileReader: FileAsyncReader = ...
///
/// let result = try await fileReader.read { buffer in
/// guard buffer.count > 0 else {
/// return 0
/// }
/// return buffer.count
/// }
/// ```
///
/// - Parameter body: A closure that receives a mutable reference to the buffer
/// of read elements and returns a value of type `Return`. When the buffer
/// is empty, it indicates the end of the stream.
/// - Returns: The value the body closure returns after processing the read elements.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
/// or a `Failure` from the body closure.
mutating func read<Return: ~Copyable, Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
#endif
@@ -0,0 +1,61 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
/// Writes elements asynchronously to a destination using callee-managed buffering.
///
/// Adopt ``AsyncWriter`` when you need callee-managed buffering,
/// where the writer supplies a buffer that the caller fills
/// with elements to write.
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
public protocol AsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
associatedtype WriteElement: ~Copyable
/// The container type the writer uses to receive elements from the caller.
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer that `body` uses to append elements.
/// The writer manages the buffer allocation and handles the writing
/// operation once `body` completes.
///
/// - Parameter body: A closure that receives a buffer for appending elements
/// to write. The closure returns a result of type `Return`.
///
/// - Returns: The value the body closure returns.
///
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
/// or a `Failure` from the body closure.
///
/// ## Example
///
/// ```swift
/// var writer: SomeAsyncWriter = ...
///
/// try await writer.write { buffer in
/// for item in items {
/// buffer.append(item)
/// }
/// return buffer.count
/// }
/// ```
mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
}
#endif
@@ -0,0 +1,39 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
/// Reads elements asynchronously into a caller-provided buffer.
///
/// Adopt ``CallerAsyncReader`` when you need caller-managed buffering,
/// where the caller supplies a buffer that the reader fills
/// with elements.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
public protocol CallerAsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements this reader reads.
associatedtype ReadElement: ~Copyable
/// The error type that reading operations throw.
associatedtype ReadFailure: Error
/// Reads elements from the source into the provided buffer.
///
/// This method appends elements into `buffer`. When the read operation
/// reaches the end of the source, it appends no elements.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Throws: A `ReadFailure` from the underlying read operation.
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable
}
#endif
@@ -0,0 +1,49 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
public import ContainersPreview
/// Writes elements asynchronously from a caller-provided buffer.
///
/// Adopt ``CallerAsyncWriter`` when you need caller-managed buffering,
/// where the caller provides a buffer of elements for the writer
/// to consume.
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements this writer writes.
associatedtype WriteElement: ~Copyable
/// The error type that writing operations throw.
associatedtype WriteFailure: Error
/// Writes elements from the provided buffer to the underlying destination.
///
/// This method asynchronously writes all elements from the provided buffer to the destination
/// the writer represents.
///
/// - Parameter buffer: The buffer of elements to write.
///
/// - Throws: A `WriteFailure` from the underlying write operation.
///
/// ## Example
///
/// ```swift
/// var fileWriter: FileAsyncWriter = ...
/// var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
///
/// try await fileWriter.write(buffer: &data)
/// ```
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
}
#endif
+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,829 @@
# Generalized asynchronous streaming
* Proposal: [SE-NNNN](NNNN-async-streaming.md)
* Authors: [Franz Busch](https://github.com/FranzBusch), [Karoy
Lorentey](https://github.com/lorentey), [David
Smith](https://github.com/Catfish-Man)
* Review Manager: TBD
* Status: **Awaiting implementation**
* Implementation: …
* Review: ([pitch](https://forums.swift.org/...))
## Summary of changes
Introduces four protocols for asynchronous streaming with caller- and
callee-managed buffer ownership for both reading and writing. Supports
noncopyable types, bulk/chunked access, and bidirectional streaming while
maintaining structured concurrency. Provides bridging extensions between
`AsyncReader` and `AsyncSequence`.
## Motivation
`AsyncSequence` (SE-0298) gave Swift a concurrency-compatible model for streams
of values arriving over time. It has served us well but has a number of
important limitations that become apparent when building high-performance,
bidirectional I/O systems.
### Values arrive one at a time
When each value is computationally "large", the overhead of calling `next()` is
negligible. But for simple types like bytes, that per-element overhead can dwarf
the actual work. This forces library authors into tricky, not-fully-general
workarounds with inline functions (as seen in `AsyncBufferedByteIterator`) or
into giving up on the `AsyncSequence` abstraction entirely.
The standard solution is buffering: read or write many elements at once. But
buffering introduces its own set of challenges — more on that below.
### Noncopyable types cannot be streamed
`AsyncSequence` was introduced before noncopyable types existed and requires its
`Element` to be `Copyable`. Streaming types are conceptually about moving values
from one place to another, and many important types such as move-only buffers
are noncopyable by nature.
### The iterator pattern is a poor fit for asynchronous streams
`AsyncSequence` followed the design of its synchronous counterpart `Sequence` by
using an iterator pattern. While iterators work well for synchronous
collections, they are a poor fit for asynchronous streams for two reasons:
* **Most asynchronous sequences do not support multiple iterators.** Unlike an
`Array`, which can be iterated multiple times independently, a network socket
or file stream produces each value exactly once.
* **Most asynchronous sequences are not replayable.** The iterator pattern
suggests that calling `makeAsyncIterator()` again would restart iteration
from the beginning, but this is almost never true for asynchronous sources.
### There is no protocol for the write side of a stream
During the design of APIs supporting bidirectional streaming — such as HTTP or
gRPC — it became apparent that `AsyncSequence`'s pull-based model only works for
one side. Trying to express both sides as an `AsyncSequence` forces the
introduction of unstructured tasks, breaking structured concurrency guarantees:
```swift
func bidirectionalStreaming(
input: some AsyncSequence<UInt8, Never>
) async throws -> some AsyncSequence<UInt8, Never> {
// The output sequence can produce values before input is fully consumed.
// This forces an unstructured task to continue iterating the input
// after this method returns.
Task {
for await byte in input {
// Send byte
}
}
return SomeOutputSequence()
}
```
A dedicated write protocol eliminates this problem by giving the output side a
push-based interface that can be driven within the same structured scope as the
input side.
### Buffer management has no single optimal strategy
Given the limitations above, we need new streaming protocols. Addressing the
per-element overhead requires buffering, but someone must be responsible for
creating and managing each buffer. There are two fundamental choices:
* **The caller provides the buffer.** The stream fills (for reads) or drains
(for writes) the caller's buffer.
* **The callee provides the buffer.** The stream lends a filled buffer (for
reads) or an empty buffer (for writes) to the caller via a scoped closure.
Each strategy is optimal in different situations, and neither can be eliminated
without imposing unnecessary overhead on important use cases:
**Callee-owned read is optimal when data arrives from an external source.** When
doing interprocess communication, the kernel's virtual memory system can re-map
a buffer from one process to another with zero copying. If the read stream takes
a buffer from its caller, this zero-copy transfer still incurs a copy to move
data from the remapped buffer to the client's buffer. With callee-owned read,
the data can be used in-place. The same applies to kernel-managed buffer schemes
where the operating system shares buffers directly with userspace.
**Caller-owned read is optimal when reading into an existing buffer.** If the
caller wants to initialize a subrange of an existing allocation by reading into
it, having the stream produce its own buffer — even a pre-allocated one — forces
at least a copy from the stream's buffer into the target region. With
caller-owned read, the stream fills the target region directly.
**Caller-owned write is optimal when the data already exists in a buffer.**
Writing the contents of an `Array` to disk via a stream that uses the `write()`
syscall internally requires no intermediate buffer if the caller hands the
array's storage directly to the stream. If the stream (callee) provided its own
buffer, the caller would have to copy the array's elements into it first.
**Callee-owned write is optimal when the destination already has storage.** In
many situations the writer already owns a buffer — a kernel-shared memory
region, a pre-registered I/O buffer, or the backing storage of a collection
being initialized. With callee-owned write, the writer exposes that existing
storage directly, letting the producer write into it in-place with no
intermediate buffer and no copy.
Caller-owned read and write are also important for Embedded Swift and other
resource-constrained environments, where the caller provides one buffer up front
and nothing else in the system ever needs to allocate.
If buffers cannot be reused, memory management overhead often dominates
performance. This motivates a design where the compiler enforces that buffers
are not stored after the operation completes, enabling safe reuse.
## Proposed solution
We propose a family of four protocols representing the possible combinations of
the 2×2 possibility matrix:
{ Caller Buffers, Callee Buffers } × { Read, Write }
These protocols use generic buffer types constrained to `RangeReplaceableContainer`
from the Swift Collections library. For the callee-owned variants, a closure-scoped
API with `inout` access ensures the caller can process elements without taking
ownership of the buffer, enabling safe reuse.
The bite-sized pseudocode:
```
protocol AsyncReader {
// Callee provides a full buffer; caller drains it
func read(body: (inout buffer) throws -> R) throws -> R
}
protocol CallerAsyncReader {
// Caller provides an empty buffer; callee fills it
func read(into buffer: inout buffer) throws
}
protocol CallerAsyncWriter {
// Caller provides a full buffer; callee drains it
func write(buffer: inout buffer) throws
}
protocol AsyncWriter {
// Callee provides an empty buffer; caller fills it
func write(body: (inout buffer) throws -> R) throws -> R
}
```
### Progressive disclosure
Four protocols is a little daunting to newcomers, and immediately raises the
question "which one(s) should my type conform to?". We believe that applying
"streams flow downhill" as a rule of thumb gets the best results in the majority
of situations:
> If you are not sure, pick callee-owned (`AsyncReader`) for read streams and
> caller-owned (`CallerAsyncWriter`) for write streams.
The intuition: data produced by the callee flows toward the caller on the read
side, so the callee is the natural owner of the buffer. On the write side, data
produced by the caller flows toward the callee, so the caller is the natural
owner. The "other" pair exists for cases where the default imposes unnecessary
overhead.
By documenting this rule and following it in our own types, we expect developers
to naturally reach for `AsyncReader` and `CallerAsyncWriter`, leaving
`CallerAsyncReader` and `AsyncWriter` for the specialized situations that
truly need them.
### Bridging with `AsyncSequence`
Rather than reparenting `AsyncSequence`, we provide bidirectional bridging
extensions that allow converting freely between the two abstractions:
```swift
// AsyncReader → AsyncSequence
let sequence = someReader.asyncSequence
// AsyncSequence → AsyncReader
let reader = someSequence.asyncReader
```
This approach avoids requiring the protocol reparenting language feature while
giving developers a clear migration path. Existing `AsyncSequence`-based APIs
can be consumed by code expecting an `AsyncReader`, and new `AsyncReader`-based
APIs can interoperate with the existing `AsyncSequence` ecosystem.
## Detailed design
### Support types
```swift
/// A type-safe wrapper around one of two distinct error types.
///
/// Use ``EitherError`` when an operation can fail with errors from two
/// different sources, such as a read failure and a body closure failure.
@frozen
public enum EitherError<First: Error, Second: Error>: Error {
/// An error of the first type.
///
/// The associated value contains the specific error instance of type `First`.
case first(First)
/// An error of the second type.
///
/// The associated value contains the specific error instance of type `Second`.
case second(Second)
/// Throws the underlying error, unwrapping this either error.
///
/// This method extracts and throws the error in the either error,
/// whether it's the first or second type. Use this when you need to propagate
/// the original error without the either error wrapper.
///
/// - Throws: The underlying error, either of type `First` or `Second`.
///
/// ## Example
///
/// ```swift
/// do {
/// // Some operation that returns EitherError
/// let result = try await operation()
/// } catch let eitherError as EitherError<NetworkError, ParseError> {
/// try eitherError.unwrap() // Throws the original error
/// }
/// ```
public func unwrap() throws {
switch self {
case .first(let first):
throw first
case .second(let second):
throw second
}
}
}
extension EitherError where Second == Never {
public func unwrap() throws(First) { ... }
}
extension EitherError where First == Never {
public func unwrap() throws(Second) { ... }
}
```
The `EitherError` type exists because the callee-owned protocols have two
distinct failure domains: the underlying stream operation can fail, and the
caller's body closure can also fail. These are logically independent error
types, and conflating them would lose information. The `Never`-constrained
extensions allow ergonomic use when one side cannot fail.
### Callee-owned async reader (preferred read type)
The callee-owned reader controls the buffer and passes a mutable reference to it
through a scoped closure. This is the preferred protocol for read streams.
```swift
public protocol AsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be read.
associatedtype ReadElement: ~Copyable
/// The container type the reader uses to pass elements to the caller.
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
/// The type of error thrown during reading.
associatedtype ReadFailure: Error
/// Reads elements from the source and passes them to the body closure.
///
/// The reader fills an internal buffer from its source and passes a mutable
/// reference to it to `body`. When the buffer is empty, the stream
/// has ended.
///
/// - Parameter body: A closure that processes the read elements.
/// - Returns: The value returned by the body closure.
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read
/// operation or a `Failure` from the body closure.
mutating func read<Return, Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
```
### Caller-owned async reader
The caller provides a buffer that the reader fills with elements from the
source.
```swift
public protocol CallerAsyncReader<ReadElement, ReadFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be read.
associatedtype ReadElement: ~Copyable
/// The type of error thrown during reading.
associatedtype ReadFailure: Error
/// Reads elements from the source into the provided buffer.
///
/// Appends elements into `buffer`. When the read operation reaches the
/// end of the source, no elements are appended.
///
/// - Parameter buffer: The buffer to fill with read elements.
/// - Throws: A `ReadFailure` from the underlying read operation.
mutating func read<Buffer: RangeReplaceableContainer<ReadElement>>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable
}
```
### Caller-owned async writer (preferred write type)
The caller provides a buffer of elements for the writer to consume. This is the
preferred protocol for write streams.
```swift
public protocol CallerAsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be written.
associatedtype WriteElement: ~Copyable
/// The type of error thrown during writing.
associatedtype WriteFailure: Error
/// Writes elements from the provided buffer to the destination.
///
/// Asynchronously writes all elements from the provided buffer.
///
/// - Parameter buffer: The buffer of elements to write.
/// - Throws: A `WriteFailure` from the underlying write operation.
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable
}
```
### Callee-owned async writer
The writer provides a buffer that the caller fills with elements to write.
```swift
public protocol AsyncWriter<WriteElement, WriteFailure>: ~Copyable, ~Escapable {
/// The type of elements that can be written.
associatedtype WriteElement: ~Copyable
/// The container type the writer uses to receive elements from the caller.
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
/// The type of error thrown during writing.
associatedtype WriteFailure: Error
/// Provides a buffer for writing elements to the destination.
///
/// The writer supplies a buffer that the `body` closure fills with
/// elements. After the closure returns, the writer handles the actual
/// write operation.
///
/// - Parameter body: A closure that receives a mutable buffer to fill.
/// - Returns: The value returned by the body closure.
/// - Throws: An `EitherError` containing either a `WriteFailure` from the
/// write operation or a `Failure` from the body closure.
mutating func write<Return, Failure: Error>(
_ body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<WriteFailure, Failure>) -> Return
}
```
### Bridging between `AsyncReader` and `AsyncSequence`
We provide extensions for converting between `AsyncReader` and `AsyncSequence`
in both directions. These require `Element: Copyable` since `AsyncSequence` does
not support noncopyable elements.
#### `AsyncReader` to `AsyncSequence`
```swift
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: Copyable {
/// Returns an `AsyncSequence` that yields the elements of this reader
/// one at a time.
///
/// The returned sequence calls `read` on the underlying reader and
/// yields the elements from each buffer individually.
public var asyncSequence: AsyncReaderSequence<Self> { get }
}
/// An `AsyncSequence` adapter over an `AsyncReader`.
public struct AsyncReaderSequence<
Reader: AsyncReader & ~Copyable & ~Escapable
>: AsyncSequence where Reader.ReadElement: Copyable {
public typealias Element = Reader.ReadElement
public typealias Failure = Reader.ReadFailure
public struct AsyncIterator: AsyncIteratorProtocol {
public mutating func next() async throws(Failure) -> Element?
}
public func makeAsyncIterator() -> AsyncIterator
}
```
#### `AsyncSequence` to `AsyncReader`
```swift
extension AsyncSequence {
/// Returns an `AsyncReader` that reads elements from this sequence.
///
/// Each call to `read` on the returned reader advances the sequence's
/// iterator and passes available elements to the body closure as a buffer.
public var asyncReader: AsyncSequenceReader<Self> { get }
}
/// An `AsyncReader` adapter over an `AsyncSequence`.
public struct AsyncSequenceReader<
Base: AsyncSequence
>: AsyncReader {
public typealias ReadElement = Base.Element
public typealias ReadFailure = Base.Failure
public mutating func read<Return, Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Return
) async throws(EitherError<ReadFailure, Failure>) -> Return
}
```
These bridging types allow incremental adoption: existing `AsyncSequence`-based
APIs can be consumed by code expecting an `AsyncReader`, and new
`AsyncReader`-based APIs remain accessible to code that expects an
`AsyncSequence`.
## Source compatibility
This proposal is purely additive. It introduces new protocols, types, and
extensions without modifying any existing declarations.
## ABI compatibility
This proposal is purely an extension of the ABI of the standard library and does
not change any existing features.
## Implications on adoption
Like almost all new types, these protocols do not support back deployment.
Library authors adopting these protocols can do so additively. Conforming a type
to one of the new protocols does not affect existing API or ABI. The conformance
can be removed later without breaking source or ABI compatibility, subject to
normal API evolution considerations.
## Future directions
### Convenience extensions
The core protocol signatures are general but unwieldy for types that have no
interest in bulk access. Convenience extensions would simplify common usage
patterns, for example:
* Simplified error handling when one side cannot fail (`Failure == Never` or a
non-throwing body closure).
* Single-element access via a `next()` method for callee-owned readers.
* Adapting a callee-owned reader to a caller-owned buffer (at the cost of a
copy) for interoperability between the two buffer ownership strategies.
These extensions are straightforward to add in a follow-up proposal once the
core protocols are established.
### Iteration and collection helpers
Two common patterns emerge immediately when working with `AsyncReader`: iterating
over all chunks until the stream ends, and collecting elements into a buffer up
to a specified limit. We envision convenience extensions for both:
```swift
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
/// Iterates over all chunks, executing `body` for each buffer until the
/// stream ends.
public consuming func forEachBuffer<Failure: Error>(
body: (inout Buffer) async throws(Failure) -> Void
) async throws(EitherError<ReadFailure, Failure>)
}
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
/// Collects elements up to `limit`, then passes the accumulated
/// elements to `body` as an `InputSpan`.
public mutating func collect<Result, Failure: Error>(
upTo limit: Int,
body: (consuming InputSpan<ReadElement>) async throws(Failure) -> Result
) async throws(EitherError<EitherError<ReadFailure, AsyncReaderLeftOverElementsError>, Failure>) -> Result
}
```
`forEachBuffer` provides a simple way to consume an entire stream without manually
looping over `read` calls and checking for empty buffers. `collect` accumulates
elements from multiple reads into a single buffer before processing, which is
useful when an algorithm needs all data in contiguous memory (for example,
parsing a complete message frame).
These helpers are intentionally excluded from this proposal because their error
handling semantics (particularly `collect`'s nested `EitherError` and the
`AsyncReaderLeftOverElementsError` overflow behavior) benefit from real-world
usage feedback before stabilization.
### Owned buffer transfer protocols
The four protocols in this proposal all use generic `RangeReplaceableContainer`
buffers with closure-scoped `inout` access. This is optimal for high-throughput
streaming where buffer reuse matters — the caller processes elements in-place
without taking ownership, enabling safe reuse without copies.
However, there are important message-oriented I/O patterns where the caller
needs to take ownership of the data with an independent lifetime. Consider an
HTTP/2 proxy: the proxy decodes a DATA frame, which internally allocates a
buffer to hold the frame payload. With the closure-scoped protocols, the proxy
receives a mutable reference and must copy the data if it needs to store it for
retry or fan-out to multiple downstream connections.
An owned buffer transfer protocol would let the decoder hand over its
internally-allocated buffer by value. The proxy can store it, retry a failed
send, or pass it to multiple consumers — all without copying:
```swift
// Conceptual sketch — not part of this proposal
protocol OwnedAsyncReader<Buffer, Failure>: ~Copyable, ~Escapable {
associatedtype Buffer: ~Copyable
associatedtype Failure: Error
mutating func read() async throws(Failure) -> Buffer?
}
```
This differs fundamentally from the caller/callee distinction in this proposal.
The closure-scoped protocols are about **who manages a reusable buffer during a
streaming operation**. Owned buffer transfer is about **transferring
independently-allocated data with a lifecycle decoupled from the stream**. This
is the distinction between stream-oriented I/O (TCP byte streams, file reads)
and message-oriented I/O (HTTP frames, protocol messages).
Several open design questions remain for owned buffer transfer:
* **What type should the buffer be?** An associated type bounded by a protocol
(similar to how the `http-body` crate in other ecosystems uses an associated
`Data` type bounded by a `Buf` trait) provides maximum flexibility — each
conforming type can yield its own buffer type (`Array`, `UniqueArray`,
`Data`, or a custom reference-counted immutable buffer). The protocol bound
would provide basic operations: count, access to underlying bytes, and
possibly zero-copy slicing.
* **Copyable or noncopyable?** For message-oriented patterns where cheap
sharing matters (proxy retry, fan-out, logging), a copy-on-write `Copyable`
type like `Array` is the natural default. For kernel-shared or DMA-mapped
buffers where copying is meaningless or dangerous, a `~Copyable` type
enforces single-ownership. The associated type should be bounded as
`~Copyable` to allow both.
Because owned buffer transfer has fundamentally different semantics — it returns
owned values rather than providing scoped access — it requires its own
protocols. The four protocols proposed here are stable and orthogonal to this
future addition.
### Vectored I/O protocols (scatter/gather)
Operating systems provide scatter/gather I/O operations (`readv`/`writev` on
POSIX, `WSARecv`/`WSASend` on Windows) that read into or write from multiple
non-contiguous buffers in a single system call. This is important for network
interfaces that may have many separately allocated packets ready to deliver, or
for protocols that produce headers and payloads in separate buffers.
A vectored variant would operate on a collection of spans rather than a single
contiguous span. The central design challenge is **sizing**: how many span
entries can the collection hold?
* A fixed-size inline array (e.g., `InlineArray<N, InputSpan<Element>>`) avoids
heap allocation but requires choosing N at compile time. Too small limits
flexibility; too large wastes stack space.
* A dynamically-sized array heap-allocates on every I/O operation, which is
unacceptable on hot paths.
* A small-vector optimization (inline N, then spill to heap) adds branching and
complexity.
The callee-owned pattern from this proposal suggests a solution: the entity
closest to the system call knows the right sizing. A file writer wrapping
`writev` knows it needs at most `IOV_MAX` (typically 1024) entries. A TLS writer
knows it produces at most 2 segments. A UDP socket sends one segment per
datagram. By having the callee manage the vectored span's backing storage —
using inline arrays, pooled allocations, or `withUnsafeTemporaryAllocation` as
appropriate — the sizing problem is delegated to the entity with the most
information.
Because vectored I/O operates on a fundamentally different data structure (a
collection of non-contiguous spans rather than a single contiguous span),
grafting it onto the existing protocols would complicate the common
single-buffer case for all users. It is best served by its own protocols. The
four protocols proposed here are stable and orthogonal to this future addition.
### Synchronous versions of the protocols
The engineers working on the ["future of
serialization"](https://forums.swift.org/t/the-future-of-serialization-deserialization-apis/78585)
project have indicated that async-only is unpalatable for uses like theirs.
Synchronous equivalents of these protocols would be valuable, but the design for
synchronous noncopyable iteration and container types is still in flux. We
should wait to see how best to integrate with that work.
### Structured algorithms with scoped lifetime
Some algorithms in `swift-async-algorithms` — such as `merge`, `zip`, and
`buffer` — currently require unstructured tasks because reading from an upstream
sequence must outlive a single call to the iterator's `next()` method. For
example, `merge` races multiple base sequences on each call to `next`; when one
base produces a value, iteration of the other bases must continue independently.
The use of unstructured tasks means cancellation, priority escalation, task
executor preference, and task locals must all be propagated manually — a fragile
and error-prone pattern.
These algorithms could instead be redesigned as scoped, `with`-style operations
or types with an explicit `run` method that manages the concurrent iteration
within a structured child task:
```swift
await merge(first, second) { merged in
for await element in merged {
// process element
}
}
```
This is an independent concern from the streaming protocols proposed here, but
the new protocols provide a better foundation for such redesigns.
## Alternatives considered
### Only supporting a subset of the buffer ownership options
For simplicity, it would be nice to have fewer protocols. We could support only
callee-owned read and caller-owned write (the "preferred" pair), or only
caller-owned for both directions.
We decided that since no single buffer ownership strategy is optimal for all
cases (as demonstrated in the Motivation section), the full 2×2 matrix is
necessary. With clear signposting of which protocols are "preferred," the
developer experience remains approachable for the majority while not tying the
hands of those with specialized requirements.
### Not using closures to provide temporary access to buffers
The callee-owned read and write APIs use closures that receive a span, which
introduces the complexity of `EitherError` (since both the stream operation and
the closure can throw independent error types). It would be simpler to return a
span directly.
However, without closures (or equivalent coroutine support like generators),
there would be no way for the callee to perform cleanup work when the caller is
done with the buffer. This makes the design incompatible with buffer pools,
where the callee must reclaim the buffer after use. The closure-scoped pattern
ensures the callee maintains control over buffer lifecycle.
### Just extending `AsyncSequence` with bulk transfer support
This was the original plan. However, recent developments on `Sequence` have
shown that supporting noncopyable types requires a new protocol regardless.
Given that a new protocol is needed anyway, designing the full streaming family
from scratch allows us to address all the limitations at once.
### Reparenting `AsyncSequence`
Instead of bridging extensions, we could use protocol reparenting to
retroactively make `AsyncSequence` a subtype of `AsyncReader`. This would give
every existing `AsyncSequence` conformance automatic participation in the new
streaming ecosystem without any code changes.
However, would also force an `AsyncReader`/`AsyncReaderIterator` split to match
`AsyncSequence`'s existing `makeAsyncIterator()` pattern, complicating the
`AsyncReader` protocol for all users. The bridging approach achieves the same
interoperability with explicit, discoverable conversions and a simpler protocol
definition.
### Using a concrete type rather than protocols
We could define concrete streaming types instead of protocols. This would
simplify some aspects of the design but would prevent adapting existing types to
the new abstraction. Protocols give library authors the flexibility to implement
streaming over their own storage and I/O backends.
### Using `throws` rather than typed throws
Embedded Swift environments do not support allocating boxes for existential
errors. Using typed throws (`throws(Failure)`) allows these protocols to be used
in resource-constrained environments, which is an explicit goal of this design.
### Having split stream/iterator types
For symmetry with `AsyncSequence`'s `makeAsyncIterator()` pattern, we considered
adding an iterator split to some or all of the streaming protocols. This would
be necessary if we chose to reparent `AsyncSequence` (see above). Since we use
bridging extensions instead, none of the four protocols need an iterator split,
resulting in a simpler and more uniform design.
### Async generators
Asynchronous generators could provide an alternative to `AsyncSequence` and
`AsyncReader` by allowing a function to `yield` values over time. However,
generators would require significant compiler work and would primarily address
only the read side. The write side — which is essential for bidirectional
streaming — would still need a separate push-based protocol. Generators may
complement this proposal in the future, but they do not replace the need for the
protocols proposed here.
### Approaches in other ecosystems
Other language ecosystems have explored the same problem space of async I/O
buffer management.
#### Go
Go's I/O model is built on two minimal interfaces: `io.Reader` with `Read(p
[]byte) (n int, err error)` and `io.Writer` with `Write(p []byte) (n int, err
error)`. **Buffer ownership is strictly caller-owned in both directions.** The
documentation states "implementations must not retain p" but this is enforced
only by convention — Go has no lifetime or borrowing annotations.
Go has no general-purpose callee-owned buffer interface. The `bufio.Reader` type
provides `Peek()` and `ReadSlice()` methods that return views into an internal
buffer, but only as concrete methods on a specific type, not as an interface
abstraction. When data arrives from the kernel or IPC in an existing buffer, the
caller-only model forces a copy into the caller's `[]byte` — there is no
standard way for the reader to say "here is data I already have."
Go's goroutine model — where blocking I/O suspends a goroutine rather than an OS
thread — means there is less pressure to model async operations at the type
level. The `io.Reader`/`io.Writer` interfaces are synchronous, and concurrency
comes from running readers and writers in separate goroutines. This simplifies
interface signatures but means cancellation is handled separately via
`context.Context`, outside the I/O interfaces themselves.
For scatter/gather I/O, `net.Buffers` (a `[][]byte`) dispatches to `writev` on
supported connections, but only for writes — there is no equivalent for vectored
reads.
#### .NET
.NET's classic `System.IO.Stream` uses caller-owned buffers, like Go:
`ReadAsync(Memory<byte> buffer)` and `WriteAsync(ReadOnlyMemory<byte> buffer)`.
Limitations observed in high-performance server code (ASP.NET Core's Kestrel)
motivated a redesign.
`System.IO.Pipelines` (2018) introduces `PipeReader` and `PipeWriter` as
separate types with distinct buffer ownership strategies:
* **`PipeReader` is callee-owned read.** `ReadAsync()` returns a `ReadResult`
containing a `ReadOnlySequence<byte>` — a linked list of memory segments
owned by the pipe. The caller examines the data in-place, then calls
`AdvanceTo(consumed, examined)` to signal how much was processed. This
enables partial consumption without copying and provides .NET's answer to
non-contiguous buffers: segments from multiple network reads are chained
together without coalescing into a single contiguous buffer.
* **`PipeWriter` is callee-owned write.** The writer exposes its internal
buffer via `GetMemory()`/`GetSpan()`, the caller fills it, then calls
`Advance()` to commit. This is formalized as the `IBufferWriter<T>`
interface. `PipeWriter` also offers `WriteAsync(ReadOnlyMemory<byte>)` as a
caller-owned convenience that internally copies into the pipe's buffer.
Pipelines includes built-in backpressure: when unconsumed data exceeds a
configurable threshold, `FlushAsync()` suspends the writer until the reader
catches up. Buffer pooling is integrated via `MemoryPool<T>`.
The lifetime safety of buffer access in Pipelines is enforced at runtime — using
a `ReadOnlySequence<byte>` after calling `AdvanceTo` is undefined behavior.
.NET's `Span<T>` (a stack-only ref struct that cannot survive across `await`
points) provides some compile-time safety, but `Memory<T>` (the heap-storable
counterpart needed for async code) does not.
#### Rust
In the Rust ecosystem, the `AsyncRead` and `AsyncWrite` traits use borrowed
buffers (`&mut [u8]`), which works for readiness-based I/O but is fundamentally
incompatible with completion-based I/O where the kernel holds the buffer for an
indeterminate period. This led to a fragmented ecosystem: readiness-based
runtimes (tokio, async-std) use one set of traits, while completion-based
runtimes (tokio-uring, monoio, compio) use a different set of ownership-transfer
traits (`IoBuf`/`IoBufMut`).
A major contributor to this fragmentation is the interaction between Rust's
`Future` trait (where futures can be dropped at any suspension point) and
completion-based I/O (where the kernel may still hold a buffer when a future is
cancelled). This creates potential use-after-free scenarios that require complex
workarounds: ownership transfer, buffer graveyards, or the still-unresolved
async destructor RFC.
#### What Swift's design learns from these ecosystems
Swift's structured concurrency model avoids the cancellation and buffer lifetime
problems that fragment Rust's ecosystem: structured concurrency guarantees that
child tasks complete before the parent scope exits, and cancellation is
cooperative. The closure-scoped design of the callee-owned protocols provides
compiler-enforced safety — the `Buffer` associated type is `~Copyable`, and the
`inout` closure pattern ensures buffers cannot be stored beyond the closure scope.
This is stronger than Go's convention-based "must not retain p" and .NET's
runtime-only enforcement after `AdvanceTo`.
The proposal's 2×2 matrix of {caller, callee} × {read, write} is unique among
these ecosystems. Go provides only caller-owned for both directions. .NET
Pipelines provides callee-owned for both directions (with a caller-owned write
convenience) but not caller-owned read as a first-class abstraction. The Swift
proposal provides all four combinations, informed by the observation that each
is optimal in distinct situations.
We studied these ecosystems' experiences to validate the design space
decomposition, and to confirm that owned buffer transfer and vectored I/O (both
listed as future directions) are genuinely separate concerns that warrant their
own protocols rather than being forced into the caller/callee framework.
@@ -241,8 +241,10 @@
typedef struct _Job* JobRef;
#define NONISOLATED_UNSAFE __attribute__((swift_attr("nonisolated(unsafe)")))
typedef SWIFT_CC(swift) void (*swift_task_enqueueGlobal_original)(JobRef _Nonnull job);
SWIFT_EXPORT_FROM(swift_Concurrency)
SWIFT_CC(swift) void (* _Nullable swift_task_enqueueGlobal_hook)(
NONISOLATED_UNSAFE SWIFT_CC(swift) void (* _Nullable swift_task_enqueueGlobal_hook)(
JobRef _Nonnull job, swift_task_enqueueGlobal_original _Nonnull original);
@@ -10,6 +10,7 @@
//===----------------------------------------------------------------------===//
public struct GatedSequence<Element> {
public typealias Failure = Never
let elements: [Element]
let gates: [Gate]
var index = 0
@@ -44,6 +45,15 @@ extension GatedSequence: AsyncSequence {
await gate.enter()
return element
}
public mutating func next(isolation actor: isolated (any Actor)?) async throws(Never) -> Element? {
guard gatedElements.count > 0 else {
return nil
}
let (element, gate) = gatedElements.removeFirst()
await gate.enter()
return element
}
}
public func makeAsyncIterator() -> Iterator {
@@ -0,0 +1,30 @@
//===----------------------------------------------------------------------===//
//
// 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)
import DequeModule
import Synchronization
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
final class ManualTaskExecutor: TaskExecutor {
private let jobs = Mutex<Deque<UnownedJob>>(.init())
func enqueue(_ job: UnownedJob) {
self.jobs.withLock { $0.append(job) }
}
func run() {
while let job = self.jobs.withLock({ $0.popFirst() }) {
job.runSynchronously(on: self.asUnownedTaskExecutor())
}
}
}
#endif
@@ -108,6 +108,7 @@ final class TestBuffer: XCTestCase {
XCTAssertNil(pastFailure)
}
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_given_a_base_sequence_when_bufferingOldest_then_the_policy_is_applied() async {
validate {
"X-12- 34- 5 |"
@@ -171,6 +172,7 @@ final class TestBuffer: XCTestCase {
"X,,,,,,[45^]"
}
}
#endif
func
test_given_a_buffered_with_unbounded_sequence_when_cancelling_consumer_then_the_iteration_finishes_and_the_base_is_cancelled()
@@ -325,6 +327,7 @@ final class TestBuffer: XCTestCase {
await fulfillment(of: [finished], timeout: 1.0)
}
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_given_a_base_sequence_when_bounded_with_limit_0_then_the_policy_is_transparent() async {
validate {
"X-12- 34 -5|"
@@ -332,4 +335,5 @@ final class TestBuffer: XCTestCase {
"X-12- 34 -5|"
}
}
#endif
}
@@ -10,6 +10,9 @@
//===----------------------------------------------------------------------===//
import XCTest
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
import AsyncSequenceValidation
import AsyncAlgorithms
@@ -334,3 +337,5 @@ final class TestChunk: XCTestCase {
}
}
}
#endif
@@ -13,6 +13,7 @@ import XCTest
import AsyncAlgorithms
final class TestDebounce: XCTestCase {
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_delayingValues() throws {
guard #available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *) else {
throw XCTSkip("Skipped due to Clock/Instant/Duration availability")
@@ -67,6 +68,7 @@ final class TestDebounce: XCTestCase {
"----|"
}
}
#endif
func test_Rethrows() async throws {
guard #available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *) else {
@@ -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
@@ -170,6 +170,7 @@ final class TestMerge2: XCTestCase {
XCTAssertEqual(collected.intersection(expected), expected)
}
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_merge_makes_sequence_with_ordered_elements_when_sources_follow_a_timeline() {
validate {
"a-c-e-g-|"
@@ -178,6 +179,7 @@ final class TestMerge2: XCTestCase {
"abcdefgh|"
}
}
#endif
func test_merge_finishes_when_iteration_task_is_cancelled() async {
let source1 = Indefinite(value: "test1")
@@ -508,6 +510,7 @@ final class TestMerge3: XCTestCase {
XCTAssertEqual(collected.intersection(expected), expected)
}
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_merge_makes_sequence_with_ordered_elements_when_sources_follow_a_timeline() {
validate {
"a---e---|"
@@ -517,6 +520,7 @@ final class TestMerge3: XCTestCase {
"abcdefgh|"
}
}
#endif
func test_merge_finishes_when_iteration_task_is_cancelled() async {
let source1 = Indefinite(value: "test1")
+632
View File
@@ -0,0 +1,632 @@
//===----------------------------------------------------------------------===//
//
// 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 compiler(>=6.2)
import XCTest
import AsyncAlgorithms
import Synchronization
@available(macOS 15.0, *)
final class TestShare: XCTestCase {
// MARK: - Basic Functionality Tests
func test_share_delivers_elements_to_multiple_consumers() async {
let source = [1, 2, 3, 4, 5]
let shared = source.async.share()
let gate1 = Gate()
let gate2 = Gate()
async let consumer1 = Task.detached {
var results = [Int]()
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
while let value = await iterator.next(isolation: nil) {
results.append(value)
}
return results
}
async let consumer2 = Task.detached {
var results = [Int]()
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
while let value = await iterator.next(isolation: nil) {
results.append(value)
}
return results
}
let results1 = await consumer1.value
let results2 = await consumer2.value
XCTAssertEqual(results1, [1, 2, 3, 4, 5])
XCTAssertEqual(results2, [1, 2, 3, 4, 5])
}
func test_share_with_single_consumer() async {
let source = [1, 2, 3, 4, 5]
let shared = source.async.share()
var results = [Int]()
for await value in shared {
results.append(value)
}
XCTAssertEqual(results, [1, 2, 3, 4, 5])
}
func test_share_with_empty_source() async {
let source = [Int]()
let shared = source.async.share()
var results = [Int]()
for await value in shared {
results.append(value)
}
XCTAssertEqual(results, [])
}
// MARK: - Buffering Policy Tests
func test_share_with_bounded_buffering() async {
var gated = GatedSequence([1, 2, 3, 4, 5])
let shared = gated.share(bufferingPolicy: .bounded(2))
let results1 = Mutex([Int]())
let results2 = Mutex([Int]())
let gate1 = Gate()
let gate2 = Gate()
let consumer1 = Task {
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
// Consumer 1 reads first element
if let value = await iterator.next(isolation: nil) {
results1.withLock { $0.append(value) }
}
// Delay to allow consumer 2 to get ahead
try? await Task.sleep(for: .milliseconds(10))
// Continue reading
while let value = await iterator.next(isolation: nil) {
results1.withLock { $0.append(value) }
}
}
let consumer2 = Task {
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
// Consumer 2 reads all elements quickly
while let value = await iterator.next(isolation: nil) {
results2.withLock { $0.append(value) }
}
}
// Advance the gated sequence to make elements available
gated.advance() // 1
gated.advance() // 2
gated.advance() // 3
gated.advance() // 4
gated.advance() // 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() 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)
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))
}
}
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) }
}
}
await consumer1.value
await consumer2.value
XCTAssertEqual(results1.withLock { $0 }, [1, 2, 3, 4, 5])
XCTAssertEqual(results2.withLock { $0 }, [1, 2, 3, 4, 5])
}
func test_share_with_bufferingLatest_buffering() async {
var gated = GatedSequence([1, 2, 3, 4, 5])
let shared = gated.share(bufferingPolicy: .bufferingLatest(2))
let fastResults = Mutex([Int]())
let slowResults = Mutex([Int]())
let gate1 = Gate()
let gate2 = Gate()
let fastConsumer = Task.detached {
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
while let value = await iterator.next(isolation: nil) {
fastResults.withLock { $0.append(value) }
}
}
let slowConsumer = Task.detached {
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
// Read first element immediately
if let value = await iterator.next(isolation: nil) {
slowResults.withLock { $0.append(value) }
}
// Add significant delay to let buffer fill up and potentially overflow
try? await Task.sleep(for: .milliseconds(50))
// Continue reading remaining elements
while let value = await iterator.next(isolation: nil) {
slowResults.withLock { $0.append(value) }
}
}
// Release all elements quickly to test buffer overflow behavior
gated.advance() // 1
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 2
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 3
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 4
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 5
await fastConsumer.value
await slowConsumer.value
let slowResultsArray = slowResults.withLock { $0 }
// Slow consumer should get the first element plus the latest elements in buffer
// With bufferingLatest(2), when buffer overflows, older elements are discarded
XCTAssertTrue(slowResultsArray.count >= 1, "Should have at least the first element")
XCTAssertEqual(slowResultsArray.first, 1, "Should start with first element")
// Due to bufferingLatest policy, the slow consumer should favor newer elements
// It may miss some middle elements but should get the latest ones
let receivedSet = Set(slowResultsArray)
XCTAssertTrue(receivedSet.isSubset(of: Set([1, 2, 3, 4, 5])))
// With bufferingLatest, we expect the slow consumer to get newer elements
// when it finally catches up after the delay
if slowResultsArray.count > 1 {
let laterElements = Set(slowResultsArray.dropFirst())
// Should have received some of the later elements (4, 5) due to bufferingLatest
XCTAssertTrue(
laterElements.contains(4) || laterElements.contains(5) || laterElements.contains(3),
"BufferingLatest should favor keeping newer elements"
)
}
}
func test_share_with_bufferingOldest_buffering() async {
var gated = GatedSequence([1, 2, 3, 4, 5])
let shared = gated.share(bufferingPolicy: .bufferingOldest(2))
let fastResults = Mutex([Int]())
let slowResults = Mutex([Int]())
let gate1 = Gate()
let gate2 = Gate()
let fastConsumer = Task {
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
while let value = await iterator.next(isolation: nil) {
fastResults.withLock { $0.append(value) }
}
}
let slowConsumer = Task {
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
// Read first element immediately
if let value = await iterator.next(isolation: nil) {
slowResults.withLock { $0.append(value) }
}
// Add significant delay to let buffer fill up and potentially overflow
try? await Task.sleep(for: .milliseconds(50))
// Continue reading remaining elements
while let value = await iterator.next(isolation: nil) {
slowResults.withLock { $0.append(value) }
}
}
// Release all elements quickly to test buffer overflow behavior
gated.advance() // 1
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 2
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 3
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 4
try? await Task.sleep(for: .milliseconds(5))
gated.advance() // 5
await fastConsumer.value
await slowConsumer.value
let slowResultsArray = slowResults.withLock { $0 }
// Slow consumer should get the first element plus the oldest elements that fit in buffer
// With bufferingOldest(2), when buffer overflows, newer elements are ignored
XCTAssertTrue(slowResultsArray.count >= 1, "Should have at least the first element")
XCTAssertEqual(slowResultsArray.first, 1, "Should start with first element")
// Due to bufferingOldest policy, the slow consumer should favor older elements
let receivedSet = Set(slowResultsArray)
XCTAssertTrue(receivedSet.isSubset(of: Set([1, 2, 3, 4, 5])))
// With bufferingOldest, when the buffer is full, newer elements are ignored
// So the slow consumer should be more likely to receive earlier elements
if slowResultsArray.count > 1 {
let laterElements = Array(slowResultsArray.dropFirst())
// Should have received earlier elements due to bufferingOldest policy
// Elements 4 and 5 are less likely to be received since they're newer
let hasEarlierElements = laterElements.contains(2) || laterElements.contains(3)
let hasLaterElements = laterElements.contains(4) && laterElements.contains(5)
// BufferingOldest should favor keeping older elements when buffer is full
// So we should be more likely to see earlier elements than later ones
XCTAssertTrue(
hasEarlierElements || !hasLaterElements,
"BufferingOldest should favor keeping older elements over newer ones"
)
}
}
// MARK: - Cancellation Tests
func test_share_cancellation_of_single_consumer() async {
let shared = Indefinite(value: 42).async.share()
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
for await _ in shared {
if !firstIteration {
firstIteration = true
iterated.fulfill()
}
}
finished.fulfill()
}
// Wait for the task to start iterating
await fulfillment(of: [iterated], timeout: 1.0)
// Cancel the task
task.cancel()
// Verify the task finishes
await fulfillment(of: [finished], timeout: 1.0)
}
func test_share_cancellation_with_multiple_consumers() async {
let shared = Indefinite(value: 42).async.share()
let consumer1Finished = expectation(description: "consumer1Finished")
let consumer2Finished = expectation(description: "consumer2Finished")
let consumer1Iterated = expectation(description: "consumer1Iterated")
let consumer2Iterated = expectation(description: "consumer2Iterated")
let consumer1 = Task {
var firstIteration = false
for await _ in shared {
if !firstIteration {
firstIteration = true
consumer1Iterated.fulfill()
}
}
consumer1Finished.fulfill()
}
let consumer2 = Task {
var firstIteration = false
for await _ in shared {
if !firstIteration {
firstIteration = true
consumer2Iterated.fulfill()
}
}
consumer2Finished.fulfill()
}
// Wait for both consumers to start
await fulfillment(of: [consumer1Iterated, consumer2Iterated], timeout: 1.0)
// Cancel only consumer1
consumer1.cancel()
// Consumer1 should finish
await fulfillment(of: [consumer1Finished], timeout: 1.0)
// Consumer2 should still be running, so cancel it too
consumer2.cancel()
await fulfillment(of: [consumer2Finished], timeout: 1.0)
}
func test_share_cancellation_cancels_source_when_no_consumers() async {
let source = Indefinite(value: 1).async
let shared = source.share()
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var iterator = shared.makeAsyncIterator()
if await iterator.next(isolation: nil) != nil {
iterated.fulfill()
}
// Task will be cancelled here, so iteration should stop
while await iterator.next(isolation: nil) != nil {
// Continue iterating until cancelled
}
finished.fulfill()
}
await fulfillment(of: [iterated], timeout: 1.0)
task.cancel()
await fulfillment(of: [finished], timeout: 1.0)
}
// MARK: - Error Handling Tests
func test_share_propagates_errors_to_all_consumers() async {
let source = [1, 2, 3, 4, 5].async.map { value in
if value == 3 {
throw TestError.failure
}
return value
}
let shared = source.share()
let consumer1Results = Mutex([Int]())
let consumer2Results = Mutex([Int]())
let consumer1Error = Mutex<Error?>(nil)
let consumer2Error = Mutex<Error?>(nil)
let gate1 = Gate()
let gate2 = Gate()
let consumer1 = Task {
do {
var iterator = shared.makeAsyncIterator()
gate2.open()
await gate1.enter()
while let value = try await iterator.next() {
consumer1Results.withLock { $0.append(value) }
}
} catch {
consumer1Error.withLock { $0 = error }
}
}
let consumer2 = Task {
do {
var iterator = shared.makeAsyncIterator()
gate1.open()
await gate2.enter()
while let value = try await iterator.next() {
consumer2Results.withLock { $0.append(value) }
}
} catch {
consumer2Error.withLock { $0 = error }
}
}
await consumer1.value
await consumer2.value
// Both consumers should receive the first two elements
XCTAssertEqual(consumer1Results.withLock { $0 }, [1, 2])
XCTAssertEqual(consumer2Results.withLock { $0 }, [1, 2])
// Both consumers should receive the error
XCTAssertTrue(consumer1Error.withLock { $0 is TestError })
XCTAssertTrue(consumer2Error.withLock { $0 is TestError })
}
// MARK: - Timing and Race Condition Tests
func test_share_with_late_joining_consumer() async {
var gated = GatedSequence([1, 2, 3, 4, 5])
let shared = gated.share(bufferingPolicy: .unbounded)
let earlyResults = Mutex([Int]())
let lateResults = Mutex([Int]())
// Start early consumer
let earlyConsumer = Task {
var iterator = shared.makeAsyncIterator()
while let value = await iterator.next(isolation: nil) {
earlyResults.withLock { $0.append(value) }
}
}
// Advance some elements
gated.advance() // 1
gated.advance() // 2
// Give early consumer time to consume
try? await Task.sleep(for: .milliseconds(10))
// Start late consumer
let lateConsumer = Task {
var iterator = shared.makeAsyncIterator()
while let value = await iterator.next(isolation: nil) {
lateResults.withLock { $0.append(value) }
}
}
// Advance remaining elements
gated.advance() // 3
gated.advance() // 4
gated.advance() // 5
await earlyConsumer.value
await lateConsumer.value
// Early consumer gets all elements
XCTAssertEqual(earlyResults.withLock { $0 }, [1, 2, 3, 4, 5])
// Late consumer only gets elements from when it joined
XCTAssertTrue(lateResults.withLock { $0.count <= 5 })
}
func test_share_iterator_independence() async {
let source = [1, 2, 3, 4, 5]
let shared = source.async.share()
var iterator1 = shared.makeAsyncIterator()
var iterator2 = shared.makeAsyncIterator()
// Both iterators should independently get the same elements
let value1a = await iterator1.next(isolation: nil)
let value2a = await iterator2.next(isolation: nil)
let value1b = await iterator1.next(isolation: nil)
let value2b = await iterator2.next(isolation: nil)
XCTAssertEqual(value1a, 1)
XCTAssertEqual(value2a, 1)
XCTAssertEqual(value1b, 2)
XCTAssertEqual(value2b, 2)
}
// MARK: - Memory and Resource Management Tests
func test_share_cleans_up_when_all_consumers_finish() async {
let source = [1, 2, 3]
let shared = source.async.share()
var results = [Int]()
for await value in shared {
results.append(value)
}
XCTAssertEqual(results, [1, 2, 3])
// Create a new iterator after the sequence finished
var newIterator = shared.makeAsyncIterator()
let value = await newIterator.next(isolation: nil)
XCTAssertNil(value) // Should return nil since source is exhausted
}
func test_share_multiple_sequential_consumers() async {
let source = [1, 2, 3, 4, 5]
let shared = source.async.share(bufferingPolicy: .unbounded)
// First consumer
var results1 = [Int]()
for await value in shared {
results1.append(value)
}
// Second consumer (starting after first finished)
var results2 = [Int]()
for await value in shared {
results2.append(value)
}
XCTAssertEqual(results1, [1, 2, 3, 4, 5])
XCTAssertEqual(results2, []) // Should be empty since source is exhausted
}
}
// MARK: - Helper Types
private enum TestError: Error, Equatable {
case failure
}
#endif
@@ -13,6 +13,7 @@ import XCTest
import AsyncAlgorithms
final class TestThrottle: XCTestCase {
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
func test_rate_0() throws {
guard #available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *) else {
throw XCTSkip("Skipped due to Clock/Instant/Duration availability")
@@ -188,4 +189,5 @@ final class TestThrottle: XCTestCase {
"a--d--g--j--[l|]"
}
}
#endif
}
@@ -10,6 +10,9 @@
//===----------------------------------------------------------------------===//
import XCTest
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
import AsyncAlgorithms
import AsyncSequenceValidation
@@ -57,3 +60,5 @@ final class TestTimer: XCTestCase {
}
}
}
#endif
@@ -10,6 +10,9 @@
//===----------------------------------------------------------------------===//
import XCTest
#if canImport(Darwin) || canImport(Glibc) || canImport(Musl) || canImport(Bionic) || canImport(wasi_pthread)
import AsyncAlgorithms
import AsyncSequenceValidation
@testable import AsyncAlgorithms_XCTest
@@ -354,3 +357,5 @@ struct LaggingAsyncSequence<Base: AsyncSequence, C: Clock>: AsyncSequence {
self.clock = clock
}
}
#endif
@@ -0,0 +1,89 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct AsyncReaderCollectTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func collectAllElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try await reader.collect(upTo: 10) { span in
return Array(span)
}
#expect(result == [1, 2, 3, 4, 5])
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func collectWithExactLimit() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try await reader.collect(upTo: 5) { span in
return Array(span)
}
#expect(result == [1, 2, 3, 4, 5])
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func collectEmptyReader() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
let result = try await reader.collect(upTo: 10) { span in
return span.count
}
#expect(result == 0)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func collectProcessesAllElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
let result = try await reader.collect(upTo: 10) { span in
var sum = 0
for i in span.indices {
sum += span[i]
}
return sum
}
#expect(result == 60)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func collectThrowsLeftOverElements() async throws {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
let expectedError = EitherError<EitherError<Never, AsyncReaderLeftOverElementsError>, Never>.first(
.second(AsyncReaderLeftOverElementsError())
)
await #expect(throws: expectedError) {
try await reader.collect(upTo: 1) { span in
return span.count
}
}
}
}
#endif
@@ -0,0 +1,119 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct AsyncReaderforEachBufferTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferIteratesAllSpans() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
var elementCount = 0
await reader.forEachBuffer { buffer in
elementCount += buffer.count
}
#expect(elementCount == 5)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferProcessesElements() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
var sum = 0
await reader.forEachBuffer { buffer in
for i in buffer.indices {
sum += buffer[i]
}
}
#expect(sum == 60)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferWithEmptyReader() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
var callCount = 0
await reader.forEachBuffer { buffer in
callCount += 1
}
#expect(callCount == 0)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferWithThrowingBody() async {
enum TestError: Error {
case failed
}
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
do {
try await reader.forEachBuffer { (_) throws(TestError) -> Void in
throw TestError.failed
}
Issue.record("Expected error to be thrown")
} catch {
#expect(error == EitherError.second(TestError.failed))
}
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferWithNeverFailingReader() async {
enum TestError: Error {
case failed
}
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var count = 0
do {
try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
count += buffer.count
}
} catch {
Issue.record("No error should be thrown from reader")
}
#expect(count == 3)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func forEachBufferWithAsyncWork() async throws {
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
var results: [Int] = []
await reader.forEachBuffer { buffer in
await Task.yield()
for i in buffer.indices {
results.append(buffer[i])
}
}
#expect(results == [1, 2, 3])
}
}
#endif
@@ -0,0 +1,57 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct AsyncReaderTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func read() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
let result = try! await reader.read { buffer in
return buffer.clone()
}
#expect(result.count == 5)
#expect(result[0] == 1)
#expect(result[1] == 2)
#expect(result[2] == 3)
#expect(result[3] == 4)
#expect(result[4] == 5)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func readEmptyAtEnd() async {
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
// Read all data
let first = try! await reader.read { buffer in
return buffer.count
}
#expect(first == 3)
// Next read should return empty span
let second = try! await reader.read { buffer in
return buffer.count
}
#expect(second == 0)
}
}
#endif
@@ -0,0 +1,103 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct AsyncWriterTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeElements() async {
var writer = UniqueArrayAsyncWriter()
try! await writer.write { buffer in
buffer.append(1)
buffer.append(2)
buffer.append(3)
}
#expect(writer.storage.count == 3)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeEmptyBuffer() async {
var writer = UniqueArrayAsyncWriter()
try! await writer.write { _ in }
#expect(writer.storage.count == 0)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeReturnsValue() async {
var writer = UniqueArrayAsyncWriter()
let count = try! await writer.write { buffer in
buffer.append(10)
buffer.append(20)
return buffer.count
}
#expect(count == 2)
#expect(writer.storage.count == 2)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeWithThrowingBody() async {
enum TestError: Error, Equatable {
case failed
}
var writer = UniqueArrayAsyncWriter()
do {
try await writer.write { (_) throws(TestError) -> Void in
throw TestError.failed
}
Issue.record("Expected error to be thrown")
} catch {
#expect(error == EitherError<Never, TestError>.second(TestError.failed))
}
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeMultipleTimes() async {
var writer = UniqueArrayAsyncWriter()
try! await writer.write { buffer in
buffer.append(1)
buffer.append(2)
}
try! await writer.write { buffer in
buffer.append(3)
buffer.append(4)
}
#expect(writer.storage.count == 4)
#expect(writer.storage[0] == 1)
#expect(writer.storage[1] == 2)
#expect(writer.storage[2] == 3)
#expect(writer.storage[3] == 4)
}
}
#endif
@@ -0,0 +1,93 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct CallerAsyncReaderTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func readIntoBuffer() async {
var reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
)
var buffer = UniqueArray<Int>(minimumCapacity: 10)
await reader.read(into: &buffer)
#expect(buffer.count == 5)
#expect(buffer[0] == 1)
#expect(buffer[1] == 2)
#expect(buffer[2] == 3)
#expect(buffer[3] == 4)
#expect(buffer[4] == 5)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func readIntoBufferAtEnd() async {
var reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 0, copying: [])
)
var buffer = UniqueArray<Int>(minimumCapacity: 10)
await reader.read(into: &buffer)
#expect(buffer.count == 0)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func readIntoBufferRespectsCapacity() async {
var reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 10, copying: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
)
var buffer = UniqueArray<Int>(minimumCapacity: 3)
await reader.read(into: &buffer)
#expect(buffer.count == 3)
#expect(buffer[0] == 1)
#expect(buffer[1] == 2)
#expect(buffer[2] == 3)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func readMultipleTimes() async {
var reader = UniqueArrayCallerAsyncReader(
storage: UniqueArray(capacity: 6, copying: [1, 2, 3, 4, 5, 6])
)
var buffer1 = UniqueArray<Int>(minimumCapacity: 3)
await reader.read(into: &buffer1)
#expect(buffer1.count == 3)
#expect(buffer1[0] == 1)
#expect(buffer1[1] == 2)
#expect(buffer1[2] == 3)
var buffer2 = UniqueArray<Int>(minimumCapacity: 3)
await reader.read(into: &buffer2)
#expect(buffer2.count == 3)
#expect(buffer2[0] == 4)
#expect(buffer2[1] == 5)
#expect(buffer2[2] == 6)
var buffer3 = UniqueArray<Int>(minimumCapacity: 3)
await reader.read(into: &buffer3)
#expect(buffer3.count == 0)
}
}
#endif
@@ -0,0 +1,53 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
import Testing
@Suite
struct CallerAsyncWriterTests {
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeBuffer() async {
var writer = UniqueArrayCallerAsyncWriter()
var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
await writer.write(buffer: &data)
#expect(writer.storage.count == 5)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeEmptyBuffer() async {
var writer = UniqueArrayCallerAsyncWriter()
var data = UniqueArray<Int>()
await writer.write(buffer: &data)
#expect(writer.storage.count == 0)
}
@Test
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
func writeLargeBuffer() async {
var writer = UniqueArrayCallerAsyncWriter(capacity: 100)
var data = UniqueArray(capacity: 5, copying: Array(1...50))
await writer.write(buffer: &data)
#expect(writer.storage.count == 50)
}
}
#endif
@@ -0,0 +1,68 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import Testing
@Suite
struct EitherErrorTests {
enum FirstError: Error, Equatable, Hashable {
case one
case two
}
enum SecondError: Error, Equatable, Hashable {
case alpha
case beta
}
@Test
func unwrapFirst() throws {
let error: EitherError<FirstError, SecondError> = .first(.one)
#expect(throws: FirstError.one) {
try error.unwrap()
}
}
@Test
func unwrapSecond() throws {
let error: EitherError<FirstError, SecondError> = .second(.alpha)
#expect(throws: SecondError.alpha) {
try error.unwrap()
}
}
@Test
func equatable() {
let a: EitherError<FirstError, SecondError> = .first(.one)
let b: EitherError<FirstError, SecondError> = .first(.one)
let c: EitherError<FirstError, SecondError> = .first(.two)
let d: EitherError<FirstError, SecondError> = .second(.alpha)
#expect(a == b)
#expect(a != c)
#expect(a != d)
}
@Test
func hashable() {
let a: EitherError<FirstError, SecondError> = .first(.one)
let b: EitherError<FirstError, SecondError> = .first(.one)
let c: EitherError<FirstError, SecondError> = .second(.alpha)
#expect(a.hashValue == b.hashValue)
#expect(a.hashValue != c.hashValue)
}
}
#endif
@@ -0,0 +1,43 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import BasicContainers
import ContainersPreview
extension Array {
init(_ span: Span<Element>) {
self.init()
for index in span.indices {
self.append(span[index])
}
}
init(_ inputSpan: borrowing InputSpan<Element>) {
self.init()
for index in inputSpan.indices {
self.append(inputSpan[index])
}
}
mutating func append(span: Span<Element>) {
for index in span.indices {
self.append(span[index])
}
}
mutating func append(inputSpan: borrowing InputSpan<Element>) {
for index in inputSpan.indices {
self.append(inputSpan[index])
}
}
}
#endif
@@ -0,0 +1,37 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
struct UniqueArrayAsyncReader: ~Copyable, AsyncReader {
typealias ReadElement = Int
typealias Buffer = UniqueArray<Int>
typealias ReadFailure = Never
var storage: UniqueArray<Int>
mutating func read<Return: ~Copyable, Failure: Error>(
body: (inout UniqueArray<Int>) async throws(Failure) -> Return
) async throws(EitherError<Never, Failure>) -> Return {
do {
var uniqueArray = self.storage.clone()
self.storage = .init()
return try await body(&uniqueArray)
} catch {
throw .second(error)
}
}
}
#endif
@@ -0,0 +1,42 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
typealias WriteElement = Int
typealias Buffer = UniqueArray<Int>
typealias WriteFailure = Never
var storage: UniqueArray<Int>
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
}
mutating func write<Return: ~Copyable, Failure: Error>(
_ body: (inout UniqueArray<Int>) async throws(Failure) -> Return
) async throws(EitherError<Never, Failure>) -> Return {
var buffer = UniqueArray<Int>(minimumCapacity: 64)
do {
let result = try await body(&buffer)
self.storage.append(copying: buffer)
return result
} catch {
throw .second(error)
}
}
}
#endif
@@ -0,0 +1,36 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
struct UniqueArrayCallerAsyncReader: ~Copyable, CallerAsyncReader {
typealias ReadElement = Int
typealias ReadFailure = Never
var storage: UniqueArray<Int>
var position: Int = 0
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
into buffer: inout Buffer
) async throws(ReadFailure) where Buffer.Element: ~Copyable {
guard position < storage.count else { return }
let count = min(buffer.freeCapacity, storage.count - position)
for i in 0..<count {
buffer.append(storage[position + i])
}
position += count
}
}
#endif
@@ -0,0 +1,37 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2026 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if UnstableAsyncStreaming && compiler(>=6.4)
import AsyncStreaming
import BasicContainers
import ContainersPreview
struct WriterCapacityError: Error {}
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
typealias WriteElement = Int
typealias WriteFailure = Never
var storage: UniqueArray<Int>
init(capacity: Int = 100) {
self.storage = UniqueArray(minimumCapacity: capacity)
}
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
buffer: inout Buffer
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
self.storage.reserveCapacity(buffer.count)
self.storage.append(copying: buffer)
}
}
#endif