mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
789dcf1f3d | ||
|
|
11645b8feb | ||
|
|
a5195afbd5 | ||
|
|
46b3cc3a4e | ||
|
|
3da39bbc4e | ||
|
|
c8a9349238 | ||
|
|
e81438119c | ||
|
|
8ee3d2be19 | ||
|
|
8e16632775 | ||
|
|
f4177dcc17 | ||
|
|
268087d1de | ||
|
|
3bd2de010e | ||
|
|
b2beeb25b4 | ||
|
|
d0b4a06d0f | ||
|
|
6a92272e13 | ||
|
|
6783e0f2d2 | ||
|
|
d14a83b31f | ||
|
|
0a5f92d159 | ||
|
|
be2467e0c0 | ||
|
|
9d349bcc32 | ||
|
|
5043186441 | ||
|
|
2971dd5d9f | ||
|
|
103f5e5bea | ||
|
|
b8006a9de0 | ||
|
|
2de50036f6 | ||
|
|
ba540240d3 | ||
|
|
65ed06871b | ||
|
|
d98a48b8c2 | ||
|
|
6c050d5ef8 | ||
|
|
2773d41253 | ||
|
|
4686d2edd3 | ||
|
|
24bd5acc81 | ||
|
|
26111a6fb7 | ||
|
|
daf3c0d723 | ||
|
|
70c36ce9a1 | ||
|
|
ca38935fc0 | ||
|
|
18e2398481 | ||
|
|
c537393339 | ||
|
|
6dcb3acddd | ||
|
|
3997ce3255 |
No files matched your search
@@ -0,0 +1,8 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
@@ -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
@@ -8,4 +8,6 @@ DerivedData/
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
.swiftpm
|
||||
Package.resolved
|
||||
Package.resolved
|
||||
.swift-version
|
||||
test_output.log
|
||||
@@ -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
|
||||
@@ -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 behaviors 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 referred 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,49 @@
|
||||
# Map Error
|
||||
|
||||
* Proposal: [SAA-0017](0017-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 participate 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.
|
||||
@@ -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.
|
||||
+124
-33
@@ -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,26 @@ let package = Package(
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncStreaming",
|
||||
dependencies: [
|
||||
.product(name: "BasicContainers", package: "swift-collections"),
|
||||
.product(name: "ContainersPreview", package: "swift-collections"),
|
||||
.product(name: "DequeModule", package: "swift-collections"),
|
||||
],
|
||||
exclude: ["NNNN-async-streaming.md"],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
|
||||
.enableExperimentalFeature("LifetimeDependence"),
|
||||
.enableExperimentalFeature("Lifetimes"),
|
||||
.enableUpcomingFeature("LifetimeDependence"),
|
||||
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
|
||||
.enableUpcomingFeature("InferIsolatedConformances"),
|
||||
.enableUpcomingFeature("ExistentialAny"),
|
||||
.enableUpcomingFeature("MemberImportVisibility"),
|
||||
.enableUpcomingFeature("InternalImportsByDefault"),
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
|
||||
@@ -66,18 +100,75 @@ 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"),
|
||||
.product(name: "SpanPreview", 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.7.0",
|
||||
traits: [.trait(name: "UnstableContainersPreview", condition: .when(traits: ["UnstableAsyncStreaming"]))]
|
||||
)
|
||||
]
|
||||
} else {
|
||||
package.dependencies += [
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
// swift-tools-version: 5.6
|
||||
// swift-tools-version: 5.7
|
||||
|
||||
import PackageDescription
|
||||
|
||||
|
||||
@@ -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 behaviors 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 referred 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.
|
||||
|
||||
|
||||
@@ -14,15 +14,18 @@ extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously-reduced result and
|
||||
/// the next element in the receiving asynchronous sequence, which it returns.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(
|
||||
@@ -37,16 +40,19 @@ extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously-reduced result and
|
||||
/// the next element in the receiving asynchronous sequence, mutating the
|
||||
/// previous result instead of returning a value.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(
|
||||
|
||||
@@ -0,0 +1,106 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if compiler(>=6.0)
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncSequence {
|
||||
|
||||
/// Converts any failure into a new error.
|
||||
///
|
||||
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
|
||||
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
|
||||
///
|
||||
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
public func mapError<MappedError: Error>(
|
||||
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
|
||||
) -> some AsyncSequence<Self.Element, MappedError> {
|
||||
AsyncMapErrorSequence(base: self, transform: transform)
|
||||
}
|
||||
|
||||
/// Converts any failure into a new error.
|
||||
///
|
||||
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
|
||||
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
|
||||
///
|
||||
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
public func mapError<MappedError: Error>(
|
||||
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
|
||||
) -> (some AsyncSequence<Self.Element, MappedError> & Sendable) where Self: Sendable, Self.Element: Sendable {
|
||||
AsyncMapErrorSequence(base: self, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that converts any failure into a new error.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
struct AsyncMapErrorSequence<Base: AsyncSequence, MappedError: Error> {
|
||||
typealias Element = Base.Element
|
||||
typealias Failure = MappedError
|
||||
|
||||
private let base: Base
|
||||
private let transform: @Sendable (Base.Failure) async -> MappedError
|
||||
|
||||
init(
|
||||
base: Base,
|
||||
transform: @Sendable @escaping (Base.Failure) async -> MappedError
|
||||
) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncMapErrorSequence: AsyncSequence {
|
||||
|
||||
/// The iterator that produces elements of the map sequence.
|
||||
struct Iterator: AsyncIteratorProtocol {
|
||||
typealias Element = Base.Element
|
||||
|
||||
private var base: Base.AsyncIterator
|
||||
|
||||
private let transform: @Sendable (Base.Failure) async -> MappedError
|
||||
|
||||
init(
|
||||
base: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Failure) async -> MappedError
|
||||
) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
mutating func next() async throws(MappedError) -> Element? {
|
||||
try await self.next(isolation: nil)
|
||||
}
|
||||
|
||||
mutating func next(isolation actor: isolated (any Actor)?) async throws(MappedError) -> Element? {
|
||||
do {
|
||||
return try await base.next(isolation: actor)
|
||||
} catch {
|
||||
throw await transform(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func makeAsyncIterator() -> Iterator {
|
||||
Iterator(
|
||||
base: base.makeAsyncIterator(),
|
||||
transform: transform
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncMapErrorSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncMapErrorSequence.Iterator: Sendable {}
|
||||
#endif
|
||||
@@ -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
|
||||
@@ -14,16 +14,19 @@ extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given error-throwing closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously reduced result and
|
||||
/// the next element in the receiving asynchronous sequence and returns
|
||||
/// the result. If the closure throws an error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(
|
||||
@@ -38,8 +41,12 @@ extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given error-throwing closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
@@ -47,8 +54,7 @@ extension AsyncSequence {
|
||||
/// the next element in the receiving asynchronous sequence, mutating the
|
||||
/// previous result instead of returning a value. If the closure throws an
|
||||
/// error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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 {}
|
||||
+1801
File diff suppressed because it is too large.
Load diff
+728
@@ -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
|
||||
@@ -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)
|
||||
|
||||
@@ -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,160 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
public import ContainersPreview
|
||||
|
||||
/// An error that indicates the reader produced more elements than the
|
||||
/// destination container could accept.
|
||||
public struct AsyncReaderLeftOverElementsError: Error, Hashable {
|
||||
public init() {}
|
||||
}
|
||||
|
||||
/// An error that indicates the reader signaled end-of-stream before producing
|
||||
/// enough elements to fill the destination container.
|
||||
public struct AsyncReaderInsufficientElementsError: Error, Hashable {
|
||||
public init() {}
|
||||
}
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, ReadElement: ~Copyable {
|
||||
/// Collects elements from the reader into the provided container, up to the
|
||||
/// container's available space.
|
||||
///
|
||||
/// Reads chunks from the reader and moves them into `target` until the reader
|
||||
/// signals end-of-stream. The reader can deliver fewer elements than
|
||||
/// `target.freeCapacity`; the container needn't be full when the stream ends.
|
||||
/// If the reader produces more elements than `target` can accept, the method
|
||||
/// throws ``AsyncReaderLeftOverElementsError``.
|
||||
///
|
||||
/// - Parameter target: The container that receives the collected elements.
|
||||
/// The method preserves the container's existing contents and appends
|
||||
/// collected elements to the end.
|
||||
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
|
||||
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure`` or
|
||||
/// an ``AsyncReaderLeftOverElementsError`` if the reader produced more
|
||||
/// elements than `target` could accept.
|
||||
public consuming func collect<Container: RangeReplaceableContainer<ReadElement> & ~Copyable & ~Escapable>(
|
||||
into target: inout Container
|
||||
) async throws(EitherError<ReadFailure, AsyncReaderLeftOverElementsError>) -> FinalElement {
|
||||
var reader = self
|
||||
var finalElement: FinalElement? = nil
|
||||
while finalElement == nil {
|
||||
try await reader.read { (buffer, final) throws(AsyncReaderLeftOverElementsError) -> Void in
|
||||
if buffer.count > target.freeCapacity {
|
||||
throw AsyncReaderLeftOverElementsError()
|
||||
}
|
||||
target.append(moving: buffer.startIndex..<buffer.endIndex, from: &buffer)
|
||||
if let final {
|
||||
finalElement = final
|
||||
}
|
||||
}
|
||||
}
|
||||
// The force-unwrap is safe since final element must be set at this point
|
||||
return finalElement!
|
||||
}
|
||||
|
||||
/// Collects elements from the reader into the provided container, requiring
|
||||
/// that the reader fill the container exactly.
|
||||
///
|
||||
/// Reads chunks from the reader and moves them into `target` until either the
|
||||
/// reader signals end-of-stream or the container becomes full. The reader
|
||||
/// must produce exactly `target.freeCapacity` elements. If it produces fewer
|
||||
/// before signaling end-of-stream, the method throws
|
||||
/// ``AsyncReaderInsufficientElementsError``. If it produces more, it throws
|
||||
/// ``AsyncReaderLeftOverElementsError``.
|
||||
///
|
||||
/// - Parameter target: The container to fill exactly. The method appends
|
||||
/// collected elements to the container's existing contents.
|
||||
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
|
||||
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure``
|
||||
/// or an `EitherError` wrapping
|
||||
/// ``AsyncReaderLeftOverElementsError`` (too many elements) or
|
||||
/// ``AsyncReaderInsufficientElementsError`` (too few elements).
|
||||
public consuming func collect<Container: RangeReplaceableContainer<ReadElement> & ~Copyable & ~Escapable>(
|
||||
exactlyInto target: inout Container
|
||||
) async throws(EitherError<
|
||||
ReadFailure, EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
|
||||
>) -> FinalElement {
|
||||
var reader = self
|
||||
var finalElement: FinalElement? = nil
|
||||
while finalElement == nil {
|
||||
try await reader.read {
|
||||
(
|
||||
buffer,
|
||||
final
|
||||
) throws(EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>) -> Void in
|
||||
if buffer.count > target.freeCapacity {
|
||||
throw .first(AsyncReaderLeftOverElementsError())
|
||||
}
|
||||
if final != nil, buffer.count < target.freeCapacity {
|
||||
throw .second(AsyncReaderInsufficientElementsError())
|
||||
}
|
||||
target.append(moving: buffer.startIndex..<buffer.endIndex, from: &buffer)
|
||||
if let final {
|
||||
finalElement = final
|
||||
}
|
||||
}
|
||||
}
|
||||
// The force-unwrap is safe since final element must be set at this point
|
||||
return finalElement!
|
||||
}
|
||||
|
||||
/// Collects elements from the reader into the provided dynamic container,
|
||||
/// growing it up to the specified maximum size.
|
||||
///
|
||||
/// Reads chunks from the reader and appends them to `target`, which grows as
|
||||
/// elements arrive. The reader can deliver fewer than `maximumSize` elements
|
||||
/// before signaling end-of-stream; if it delivers more, the method throws
|
||||
/// ``AsyncReaderLeftOverElementsError``.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - target: The dynamic container that receives the collected elements.
|
||||
/// The method appends collected elements to the container's existing
|
||||
/// contents.
|
||||
/// - maximumSize: The maximum number of elements to append to `target`.
|
||||
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
|
||||
/// - Throws: An `EitherError` wrapping either a ``AsyncReader/ReadFailure`` or
|
||||
/// an ``AsyncReaderLeftOverElementsError`` if the reader produced more than
|
||||
/// `maximumSize` elements.
|
||||
public consuming func collect<Container: DynamicContainer<ReadElement> & ~Copyable>(
|
||||
into target: inout Container,
|
||||
maximumSize: Int
|
||||
) async throws(EitherError<ReadFailure, AsyncReaderLeftOverElementsError>) -> FinalElement {
|
||||
precondition(maximumSize >= 0, "maximumSize must be non-negative")
|
||||
var reader = self
|
||||
var finalElement: FinalElement? = nil
|
||||
var remaining = maximumSize
|
||||
while finalElement == nil {
|
||||
try await reader.read { (buffer, final) throws(AsyncReaderLeftOverElementsError) -> Void in
|
||||
let chunkCount = buffer.count
|
||||
if chunkCount > remaining {
|
||||
throw AsyncReaderLeftOverElementsError()
|
||||
}
|
||||
if chunkCount > 0 {
|
||||
var consumer = buffer.consumeAll()
|
||||
while let element = consumer.next() {
|
||||
target.append(element)
|
||||
}
|
||||
remaining -= chunkCount
|
||||
}
|
||||
if let final {
|
||||
finalElement = final
|
||||
}
|
||||
}
|
||||
}
|
||||
// The force-unwrap is safe since final element must be set at this point
|
||||
return finalElement!
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,95 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
public import ContainersPreview
|
||||
|
||||
// swift-format-ignore: AmbiguousTrailingClosureOverload
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable {
|
||||
/// Iterates over all chunks from the reader, executing the provided body for
|
||||
/// each buffer until the stream signals end-of-stream.
|
||||
///
|
||||
/// This method continuously reads chunks from the async reader, executing
|
||||
/// `body` for every chunk — including the terminal one — and terminates the
|
||||
/// loop when the reader delivers a non-`nil` ``AsyncReader/FinalElement``.
|
||||
/// The returned value is that ``AsyncReader/FinalElement``.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileReader: FileAsyncReader = ...
|
||||
///
|
||||
/// _ = try await fileReader.forEachBuffer { buffer in
|
||||
/// print("Processing \(buffer.count) elements")
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter body: An asynchronous closure that processes each buffer of
|
||||
/// elements read from the stream.
|
||||
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal
|
||||
/// chunk, or `nil` if none was observed.
|
||||
/// - Throws: An `EitherError` containing either a `ReadFailure` from the
|
||||
/// read operation or a `Failure` from the body closure.
|
||||
public consuming func forEachBuffer<Failure: Error>(
|
||||
body: (inout Buffer) async throws(Failure) -> Void
|
||||
) async throws(EitherError<ReadFailure, Failure>) -> FinalElement? {
|
||||
var final: FinalElement? = nil
|
||||
var done = false
|
||||
while !done {
|
||||
try await self.read { (next, finalElement) throws(Failure) -> Void in
|
||||
if !next.isEmpty {
|
||||
try await body(&next)
|
||||
}
|
||||
if let finalElement {
|
||||
final = finalElement
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
return final
|
||||
}
|
||||
|
||||
/// Iterates over all chunks from a non-failing reader, executing the
|
||||
/// provided body for each buffer until the stream signals end-of-stream.
|
||||
///
|
||||
/// Use this overload when the reader's ``AsyncReader/ReadFailure`` type is `Never`.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileReader: FileAsyncReader = ...
|
||||
///
|
||||
/// _ = await fileReader.forEachBuffer { buffer in
|
||||
/// print("Processing \(buffer.count) elements")
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter body: An asynchronous closure that processes each buffer of
|
||||
/// elements read from the stream.
|
||||
/// - Returns: The ``AsyncReader/FinalElement`` delivered with the terminal chunk.
|
||||
@inlinable
|
||||
public consuming func forEachBuffer(
|
||||
body: (inout Buffer) async -> Void
|
||||
) async -> FinalElement where ReadFailure == Never {
|
||||
do {
|
||||
let final: FinalElement? = try await self.forEachBuffer { (buffer) async throws(Never) -> Void in
|
||||
await body(&buffer)
|
||||
}
|
||||
// The force-unwrap is safe since final element must be set at this point
|
||||
return final!
|
||||
} catch {
|
||||
fatalError()
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,164 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import ContainersPreview
|
||||
|
||||
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
|
||||
// should additionally be constrained `& ~Escapable`. We currently can't express
|
||||
// that because of a Swift lifetime-checker limitation: with `FinalElement:
|
||||
// ~Copyable`, the `consuming FinalElement?` parameter on the read closure
|
||||
// changes the closure's lifetime category, and capturing a `~Escapable Writer`
|
||||
// inside that closure (which `pipe` does, via the `writerOpt` Optional that
|
||||
// alternates between `write` and `finish` calls) trips
|
||||
// "lifetime-dependent variable 'writer' escapes its scope". When that
|
||||
// restriction is relaxed (or `pipe` is restructured to avoid capturing the
|
||||
// writer across the read closure boundary) the constraint should be added
|
||||
// back so `pipe` works for `~Escapable` writers too.
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
extension AsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
|
||||
/// Pipes all elements from this reader into the given writer, fusing the
|
||||
/// terminal chunk with a `finish` on the writer.
|
||||
///
|
||||
/// Consumes both the reader and the writer. Each chunk the reader produces is
|
||||
/// forwarded with `writer.write(buffer:)` until the reader signals
|
||||
/// end-of-stream by delivering a non-`nil` ``AsyncReader/FinalElement``. The
|
||||
/// terminal chunk is fused with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let dataReader: DataAsyncReader = ...
|
||||
/// let fileWriter: FileCallerAsyncWriter = ...
|
||||
///
|
||||
/// // Copy all data from reader to writer and finish the writer.
|
||||
/// try await dataReader.pipe(into: fileWriter)
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter writer: A ``CallerAsyncWriter`` to receive the elements. The
|
||||
/// writer is consumed; its ``CallerAsyncWriter/finish(buffer:finalElement:)``
|
||||
/// method is called with the reader's terminal chunk and ``AsyncReader/FinalElement``.
|
||||
///
|
||||
/// - Throws: An error originating from the read or write operations.
|
||||
public consuming func pipe<Writer>(
|
||||
into writer: consuming Writer
|
||||
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
|
||||
where
|
||||
Writer: CallerAsyncWriter & ~Copyable,
|
||||
Writer.WriteElement == ReadElement,
|
||||
Writer.FinalElement == FinalElement
|
||||
{
|
||||
var reader = self
|
||||
var writerOpt: Writer? = .some(writer)
|
||||
var done = false
|
||||
while !done {
|
||||
try await reader.read { (buffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
|
||||
if let finalElement {
|
||||
let w = writerOpt.take()!
|
||||
try await w.finish(buffer: &buffer, finalElement: finalElement)
|
||||
done = true
|
||||
} else {
|
||||
try await writerOpt!.write(buffer: &buffer)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Pipes all elements from this reader into the given writer, copying each
|
||||
/// element from the reader's buffer into the writer's buffer.
|
||||
///
|
||||
/// Consumes both the reader and the writer. Because both protocols supply
|
||||
/// their own buffer, each element is transferred between them. The writer's
|
||||
/// buffer may be smaller than the reader's, in which case multiple `write`
|
||||
/// calls are issued per chunk produced by the reader.
|
||||
///
|
||||
/// On the terminal chunk this method drains all bytes through `write` calls
|
||||
/// first and then calls ``AsyncWriter/finish(finalElement:)`` carrying
|
||||
/// only the ``AsyncReader/FinalElement`` payload.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let dataReader: DataAsyncReader = ...
|
||||
/// let fileWriter: FileAsyncWriter = ...
|
||||
///
|
||||
/// try await dataReader.pipe(copyingInto: fileWriter)
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
|
||||
/// writer is consumed; its ``AsyncWriter/finish(finalElement:)`` method
|
||||
/// is called with the reader's ``AsyncReader/FinalElement`` payload.
|
||||
///
|
||||
/// - Throws: An error originating from the read or write operations.
|
||||
public consuming func pipe<Writer>(
|
||||
copyingInto writer: consuming Writer
|
||||
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
|
||||
where
|
||||
Writer: AsyncWriter & ~Copyable,
|
||||
Writer.WriteElement == ReadElement,
|
||||
Writer.FinalElement == FinalElement
|
||||
{
|
||||
var reader = self
|
||||
var writerOpt: Writer? = .some(writer)
|
||||
var done = false
|
||||
while !done {
|
||||
try await reader.read {
|
||||
(readerBuffer: inout Buffer, finalElement: FinalElement?) throws(Writer.WriteFailure) -> Void in
|
||||
try await Self.drain(readerBuffer: &readerBuffer, into: &writerOpt!)
|
||||
if let finalElement {
|
||||
let w = writerOpt.take()!
|
||||
try await w.finish(finalElement: finalElement)
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Drains `readerBuffer` into `writer` across as many `write` calls as
|
||||
/// required to move every element. Used by ``pipe(copyingInto:)`` to share
|
||||
/// the multi-write loop between mid-stream and terminal chunks.
|
||||
private static func drain<Writer>(
|
||||
readerBuffer: inout Buffer,
|
||||
into writer: inout Writer
|
||||
) async throws(Writer.WriteFailure)
|
||||
where
|
||||
Writer: AsyncWriter & ~Copyable,
|
||||
Writer.WriteElement == ReadElement
|
||||
{
|
||||
var consumer = readerBuffer.consumeAll()
|
||||
while let firstElement = consumer.next() {
|
||||
var pending: ReadElement? = firstElement
|
||||
do throws(EitherError<Writer.WriteFailure, Never>) {
|
||||
try await writer.write { (writerBuffer: inout Writer.Buffer) in
|
||||
switch consume pending {
|
||||
case .some(let element):
|
||||
writerBuffer.append(element)
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
pending = nil
|
||||
while writerBuffer.freeCapacity > 0 {
|
||||
guard let element = consumer.next() else { return }
|
||||
writerBuffer.append(element)
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
switch error {
|
||||
case .first(let writeFailure): throw writeFailure
|
||||
case .second: fatalError("Unreachable")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,90 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
|
||||
/// Reads elements asynchronously from a source using callee-managed buffering.
|
||||
///
|
||||
/// Adopt ``AsyncReader`` when you need callee-managed buffering,
|
||||
/// where the reader controls the buffer and passes it to the caller
|
||||
/// through the `body` closure.
|
||||
///
|
||||
/// ## Signaling end of stream
|
||||
///
|
||||
/// The reader signals end-of-stream by passing a non-`nil` value for the
|
||||
/// `finalElement` parameter of the `body` closure. This call may also carry a
|
||||
/// final chunk of elements in the buffer, allowing the reader to fuse the last
|
||||
/// chunk with the end signal in a single operation.
|
||||
///
|
||||
/// The ``FinalElement`` associated type controls what data, if any, the reader
|
||||
/// delivers alongside the end signal. The default is `Void`, which means the
|
||||
/// signal carries no payload. Set ``FinalElement`` to a custom type when the
|
||||
/// reader needs to deliver structured data with the terminator. Set it to `Never` to indicate
|
||||
/// that the stream never ends — the `finalElement` parameter will always be `nil`.
|
||||
///
|
||||
/// After the reader has emitted a non-`nil` `finalElement`, calling
|
||||
/// ``read(body:)`` again is a programmer error.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
public protocol AsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
|
||||
/// The type of elements this reader reads.
|
||||
// TODO: Check if we should support ~Escapable elements
|
||||
associatedtype ReadElement: ~Copyable
|
||||
|
||||
/// The container type the reader uses to pass elements to the caller.
|
||||
// TODO: Check if we should support ~Escapable buffer
|
||||
associatedtype Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable
|
||||
|
||||
/// The error type that reading operations throw.
|
||||
associatedtype ReadFailure: Error
|
||||
|
||||
/// The data the reader delivers alongside the end-of-stream signal.
|
||||
///
|
||||
/// Defaults to `Void`. Use a custom type to carry data along with the
|
||||
/// end signal. Use `Never` for streams that never end.
|
||||
// TODO: Check if we should support ~Escapable final elements
|
||||
associatedtype FinalElement: ~Copyable = Void
|
||||
|
||||
/// Reads elements from the underlying source and passes them to the provided body closure.
|
||||
///
|
||||
/// This method asynchronously reads elements from the source into a buffer,
|
||||
/// then passes the buffer and an optional `finalElement` to `body` for
|
||||
/// processing.
|
||||
///
|
||||
/// A `nil` value for `finalElement` means more data may follow. A non-`nil`
|
||||
/// value (which is the only way a stream of `FinalElement == Void` signals
|
||||
/// end) marks this chunk as the last one and delivers the final payload.
|
||||
/// The terminal chunk's buffer may be empty or contain a final batch of
|
||||
/// elements; the caller must process both.
|
||||
///
|
||||
/// After the reader has emitted a non-`nil` `finalElement`, calling
|
||||
/// ``read(body:)`` again is a programmer error.
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileReader: FileAsyncReader = ...
|
||||
///
|
||||
/// let result = try await fileReader.read { buffer, finalElement in
|
||||
/// let processed = buffer.count
|
||||
/// return (processed, finalElement != nil)
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter body: A closure that receives a mutable reference to the buffer
|
||||
/// of read elements together with the optional end-of-stream payload and
|
||||
/// returns a value of type `Return`.
|
||||
/// - Returns: The value the body closure returns after processing the read elements.
|
||||
/// - Throws: An `EitherError` containing either a `ReadFailure` from the read operation
|
||||
/// or a `Failure` from the body closure.
|
||||
mutating func read<Return: ~Copyable, Failure: Error>(
|
||||
body: (inout Buffer, consuming FinalElement?) async throws(Failure) -> Return
|
||||
) async throws(EitherError<ReadFailure, Failure>) -> Return
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,104 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
|
||||
/// Writes elements asynchronously to a destination using callee-managed buffering.
|
||||
///
|
||||
/// Adopt ``AsyncWriter`` when you need callee-managed buffering,
|
||||
/// where the writer supplies a buffer that the caller fills
|
||||
/// with elements to write.
|
||||
///
|
||||
/// ## Signaling end of stream
|
||||
///
|
||||
/// The writer is terminated by a call to ``finish(finalElement:)``.
|
||||
/// Bulk transfer happens through ``write(_:)`` calls; ``finish(finalElement:)``
|
||||
/// only carries the ``FinalElement`` payload.
|
||||
///
|
||||
/// The ``FinalElement`` associated type controls what data, if any, the writer
|
||||
/// transmits alongside the end signal. The default is `Void`. Use a custom
|
||||
/// type to carry data along with the end signal, or `Never` for endless
|
||||
/// streams. When ``FinalElement`` is `Never`, ``finish(finalElement:)`` cannot
|
||||
/// be called and the writer can be written to indefinitely.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
public protocol AsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
|
||||
/// The type of elements this writer writes.
|
||||
// TODO: Check if we should support ~Escapable elements
|
||||
associatedtype WriteElement: ~Copyable
|
||||
|
||||
/// The container type the writer uses to receive elements from the caller.
|
||||
// TODO: Check if we should support ~Escapable buffer
|
||||
associatedtype Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable
|
||||
|
||||
/// The error type that writing operations throw.
|
||||
associatedtype WriteFailure: Error
|
||||
|
||||
/// The data the writer delivers alongside the end-of-stream signal.
|
||||
///
|
||||
/// Defaults to `Void`. Use a custom type to carry data along with the end
|
||||
/// signal.
|
||||
// TODO: Check if we should support ~Escapable final element
|
||||
associatedtype FinalElement: ~Copyable = Void
|
||||
|
||||
/// Provides a buffer for writing elements to the destination.
|
||||
///
|
||||
/// The writer supplies a buffer, sized by the implementation, that
|
||||
/// `body` uses to append elements. The writer manages the buffer
|
||||
/// allocation and handles the writing operation once `body` completes.
|
||||
/// Oversized payloads are split across multiple calls.
|
||||
///
|
||||
/// - Parameter body: A closure that receives a buffer for appending elements
|
||||
/// to write. The closure returns a result of type `Return`.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var writer: SomeAsyncWriter = ...
|
||||
///
|
||||
/// try await writer.write { buffer in
|
||||
/// for item in items {
|
||||
/// buffer.append(item)
|
||||
/// }
|
||||
/// return buffer.count
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// - Returns: The value the body closure returns.
|
||||
///
|
||||
/// - Throws: An `EitherError` containing either a `WriteFailure` from the write operation
|
||||
/// or a `Failure` from the body closure.
|
||||
mutating func write<Return: ~Copyable, Failure: Error>(
|
||||
_ body: (inout Buffer) async throws(Failure) -> Return
|
||||
) async throws(EitherError<WriteFailure, Failure>) -> Return
|
||||
|
||||
/// Closes the writer, delivering a ``FinalElement`` payload alongside the
|
||||
/// end-of-stream signal.
|
||||
///
|
||||
/// - Parameter finalElement: The ``FinalElement`` payload to deliver with
|
||||
/// the end signal.
|
||||
/// - Throws: A ``WriteFailure`` from the underlying write operation.
|
||||
consuming func finish(
|
||||
finalElement: consuming FinalElement
|
||||
) async throws(WriteFailure)
|
||||
}
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
extension AsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
|
||||
/// Concludes the writer with no payload.
|
||||
///
|
||||
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
|
||||
/// ``finish(finalElement:)`` with `()`.
|
||||
public consuming func finish() async throws(WriteFailure) {
|
||||
try await self.finish(finalElement: ())
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,98 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
|
||||
/// A ``CallerAsyncWriter`` that is implemented in terms of an
|
||||
/// ``AsyncWriter``.
|
||||
///
|
||||
/// Each ``write(buffer:)`` call drains the caller's buffer through one
|
||||
/// or more ``AsyncWriter/write(_:)`` closures on the underlying writer.
|
||||
/// When the underlying writer's buffer fills before the caller's empties,
|
||||
/// the adapter loops with another closure call to continue draining.
|
||||
///
|
||||
/// The adapter introduces no buffer of its own — elements move directly
|
||||
/// from the caller-supplied buffer into the underlying writer's
|
||||
/// closure-supplied buffer. The underlying writer's deferred-flush
|
||||
/// behavior, if any, is preserved.
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
public struct AsyncWriterCallerAsyncWriterAdapter<
|
||||
Underlying: AsyncWriter & ~Copyable
|
||||
>: ~Copyable, CallerAsyncWriter {
|
||||
public typealias WriteElement = Underlying.WriteElement
|
||||
public typealias WriteFailure = Underlying.WriteFailure
|
||||
public typealias FinalElement = Underlying.FinalElement
|
||||
|
||||
@usableFromInline
|
||||
var underlying: Underlying
|
||||
|
||||
@inlinable
|
||||
init(underlying: consuming Underlying) {
|
||||
self.underlying = underlying
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws(WriteFailure) {
|
||||
var consumer = buffer.consumeAll()
|
||||
while let head = consumer.next() {
|
||||
var pending: WriteElement? = head
|
||||
do throws(EitherError<WriteFailure, Never>) {
|
||||
try await self.underlying.write {
|
||||
(innerBuffer: inout Underlying.Buffer) async throws(Never) -> Void in
|
||||
if case .some(let element) = pending.take() {
|
||||
innerBuffer.append(element)
|
||||
}
|
||||
while innerBuffer.freeCapacity > 0 {
|
||||
guard let element = consumer.next() else { return }
|
||||
innerBuffer.append(element)
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
switch error {
|
||||
case .first(let writeFailure): throw writeFailure
|
||||
case .second: fatalError("Unreachable")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer,
|
||||
finalElement: consuming FinalElement
|
||||
) async throws(WriteFailure) {
|
||||
try await self.write(buffer: &buffer)
|
||||
try await self.underlying.finish(finalElement: finalElement)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension AsyncWriter where Self: ~Copyable {
|
||||
/// Adapts this ``AsyncWriter`` to a ``CallerAsyncWriter``.
|
||||
///
|
||||
/// The returned adapter accepts caller-supplied buffers via
|
||||
/// ``CallerAsyncWriter/write(buffer:)`` and drains them through this
|
||||
/// writer's closure-based ``AsyncWriter/write(_:)``. When this
|
||||
/// writer's buffer fills before the caller's empties, the adapter
|
||||
/// loops with another closure call.
|
||||
///
|
||||
/// The adapter introduces no buffer of its own.
|
||||
///
|
||||
/// - Returns: An adapter that conforms to ``CallerAsyncWriter``.
|
||||
@inlinable
|
||||
public consuming func asCallerAsyncWriter() -> AsyncWriterCallerAsyncWriterAdapter<Self> {
|
||||
.init(underlying: self)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,143 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import ContainersPreview
|
||||
import BasicContainers
|
||||
|
||||
// TODO: The `Writer` generic parameter on every `pipe` variant in this file
|
||||
// should additionally be constrained `& ~Escapable`. We currently can't
|
||||
// express that because of a Swift lifetime-checker limitation: with
|
||||
// `FinalElement: ~Copyable`, the `consuming FinalElement?` parameter on the
|
||||
// reader's `read` closure changes the closure's lifetime category, and
|
||||
// capturing a `~Escapable Writer` inside that closure (which `pipe` does, via
|
||||
// the `writerOpt` Optional that alternates between `write` and `finish`
|
||||
// calls) trips "lifetime-dependent variable 'writer' escapes its scope".
|
||||
// When that restriction is relaxed (or `pipe` is restructured to avoid
|
||||
// capturing the writer across the closure boundary) the constraint should be
|
||||
// added back so `pipe` works for `~Escapable` writers too.
|
||||
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
extension CallerAsyncReader where Self: ~Copyable, Self: ~Escapable, Self.ReadElement: ~Copyable {
|
||||
/// Pipes all elements from this reader into the given writer, then signals
|
||||
/// end-of-stream with a `finish` call on the writer.
|
||||
///
|
||||
/// Consumes both the reader and the writer. The reader fills the writer's
|
||||
/// buffer on each iteration; once the reader signals end-of-stream, the
|
||||
/// writer's ``AsyncWriter/finish(finalElement:)`` is called with the reader's
|
||||
/// ``CallerAsyncReader/FinalElement``.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let dataReader: DataCallerAsyncReader = ...
|
||||
/// let fileWriter: FileAsyncWriter = ...
|
||||
///
|
||||
/// try await dataReader.pipe(into: fileWriter)
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter writer: An ``AsyncWriter`` to receive the elements. The
|
||||
/// writer is consumed.
|
||||
///
|
||||
/// - Throws: An error originating from the read or write operations.
|
||||
public consuming func pipe<Writer>(
|
||||
into writer: consuming Writer
|
||||
) async throws(EitherError<Writer.WriteFailure, ReadFailure>)
|
||||
where
|
||||
Writer: AsyncWriter & ~Copyable,
|
||||
Writer.WriteElement == ReadElement,
|
||||
Writer.FinalElement == FinalElement
|
||||
{
|
||||
var reader = self
|
||||
var writerOpt: Writer? = .some(writer)
|
||||
var done = false
|
||||
while !done {
|
||||
var pendingFinal: FinalElement? = nil
|
||||
try await writerOpt!
|
||||
.write { (buffer: inout Writer.Buffer) throws(ReadFailure) -> Void in
|
||||
pendingFinal = try await reader.read(into: &buffer)
|
||||
}
|
||||
if let final = pendingFinal {
|
||||
let w = writerOpt.take()!
|
||||
do throws(Writer.WriteFailure) {
|
||||
try await w.finish(finalElement: final)
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Pipes all elements from this reader into the given writer through an intermediate buffer.
|
||||
///
|
||||
/// Consumes both the reader and the writer. Because neither protocol supplies
|
||||
/// a buffer, this method allocates an intermediate buffer of the requested
|
||||
/// capacity and reuses it across iterations. The terminal chunk is fused
|
||||
/// with the writer's ``CallerAsyncWriter/finish(buffer:finalElement:)``.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// let dataReader: DataCallerAsyncReader = ...
|
||||
/// let fileWriter: FileCallerAsyncWriter = ...
|
||||
///
|
||||
/// try await dataReader.pipe(bufferingInto: fileWriter, intermediateCapacity: 4096)
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - writer: A ``CallerAsyncWriter`` to receive the elements. The writer
|
||||
/// is consumed.
|
||||
/// - intermediateCapacity: The capacity of the intermediate buffer that
|
||||
/// mediates between the reader and writer.
|
||||
///
|
||||
/// - Throws: An error originating from the read or write operations.
|
||||
public consuming func pipe<Writer>(
|
||||
bufferingInto writer: consuming Writer,
|
||||
intermediateCapacity: Int
|
||||
) async throws(EitherError<ReadFailure, Writer.WriteFailure>)
|
||||
where
|
||||
Writer: CallerAsyncWriter & ~Copyable,
|
||||
Writer.WriteElement == ReadElement,
|
||||
Writer.FinalElement == FinalElement
|
||||
{
|
||||
var reader = self
|
||||
var writerOpt: Writer? = .some(writer)
|
||||
var buffer = UniqueArray<ReadElement>(minimumCapacity: intermediateCapacity)
|
||||
var done = false
|
||||
while !done {
|
||||
let final: FinalElement?
|
||||
do throws(ReadFailure) {
|
||||
final = try await reader.read(into: &buffer)
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
if let final {
|
||||
let w = writerOpt.take()!
|
||||
do throws(Writer.WriteFailure) {
|
||||
try await w.finish(buffer: &buffer, finalElement: final)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
done = true
|
||||
} else if buffer.count > 0 {
|
||||
do throws(Writer.WriteFailure) {
|
||||
try await writerOpt!.write(buffer: &buffer)
|
||||
assert(buffer.count == 0, "CallerAsyncWriter must drain the buffer during write(buffer:)")
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,69 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
|
||||
/// Reads elements asynchronously into a caller-provided buffer.
|
||||
///
|
||||
/// Adopt ``CallerAsyncReader`` when you need caller-managed buffering,
|
||||
/// where the caller supplies a buffer that the reader fills
|
||||
/// with elements.
|
||||
///
|
||||
/// ## Signaling end of stream
|
||||
///
|
||||
/// The reader signals end-of-stream by returning a non-`nil` ``FinalElement``
|
||||
/// from ``read(into:)``. The same call may also append a final batch of
|
||||
/// elements to the caller's buffer, allowing the reader to fuse the last
|
||||
/// chunk with the end signal.
|
||||
///
|
||||
/// The ``FinalElement`` associated type controls what data, if any, the reader
|
||||
/// delivers alongside the end signal. The default is `Void`. Use a custom type
|
||||
/// to carry data along with the end signal, or `Never` for streams that never
|
||||
/// end.
|
||||
///
|
||||
/// After the reader has returned a non-`nil` `FinalElement`, calling
|
||||
/// ``read(into:)`` again is a programmer error.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
public protocol CallerAsyncReader<ReadElement, ReadFailure, FinalElement>: ~Copyable, ~Escapable {
|
||||
/// The type of elements this reader reads.
|
||||
// TODO: Check if we should support ~Escapable elements
|
||||
associatedtype ReadElement: ~Copyable
|
||||
|
||||
/// The error type that reading operations throw.
|
||||
associatedtype ReadFailure: Error
|
||||
|
||||
/// The data the reader delivers alongside the end-of-stream signal.
|
||||
///
|
||||
/// Defaults to `Void`. Use a custom type to carry data along with the end
|
||||
/// signal, or `Never` for streams that never end.
|
||||
// TODO: Check if we should support ~Escapable final element
|
||||
associatedtype FinalElement: ~Copyable = Void
|
||||
|
||||
/// Reads elements from the source into the provided buffer.
|
||||
///
|
||||
/// This method appends elements into `buffer`. A non-`nil` return value
|
||||
/// signals end-of-stream and delivers the final payload. The call may
|
||||
/// also append a final batch of elements before signaling end.
|
||||
///
|
||||
/// After the reader has returned a non-`nil` `FinalElement`, calling
|
||||
/// ``read(into:)`` again is a programmer error.
|
||||
///
|
||||
/// - Parameter buffer: The buffer to fill with read elements.
|
||||
/// - Returns: A non-`nil` ``FinalElement`` if this call delivered the
|
||||
/// end-of-stream signal; `nil` if more elements may follow.
|
||||
/// - Throws: A `ReadFailure` from the underlying read operation.
|
||||
// TODO: Check if we should support ~Escapable buffer
|
||||
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
|
||||
into buffer: inout Buffer
|
||||
) async throws(ReadFailure) -> FinalElement? where Buffer.Element: ~Copyable
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,104 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
import BasicContainers
|
||||
|
||||
/// Writes elements asynchronously from a caller-provided buffer.
|
||||
///
|
||||
/// Adopt ``CallerAsyncWriter`` when you need caller-managed buffering,
|
||||
/// where the caller provides a buffer of elements for the writer
|
||||
/// to consume.
|
||||
///
|
||||
/// ## Signaling end of stream
|
||||
///
|
||||
/// The writer is terminated by a call to ``finish(buffer:finalElement:)``.
|
||||
/// The `finish` call communicates a final buffer (if any) and the
|
||||
/// ``FinalElement`` payload, allowing implementations to fuse the last data
|
||||
/// frame with the end signal on transports that support it.
|
||||
///
|
||||
/// The ``FinalElement`` associated type controls what data, if any, the writer
|
||||
/// transmits alongside the end signal. The default is `Void`. Use a custom
|
||||
/// type to carry data along with the end signal, or `Never` for endless
|
||||
/// streams. When ``FinalElement`` is `Never`, ``finish(buffer:finalElement:)``
|
||||
/// cannot be called and the writer can be written to indefinitely.
|
||||
///
|
||||
/// Conformers must accept zero, one, or many `write(buffer:)` calls, optionally
|
||||
/// followed by a single `finish(buffer:finalElement:)` call. After `finish`
|
||||
/// returns, the writer is consumed and no further calls are valid.
|
||||
@available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, *)
|
||||
public protocol CallerAsyncWriter<WriteElement, WriteFailure, FinalElement>: ~Copyable, ~Escapable {
|
||||
/// The type of elements this writer writes.
|
||||
// TODO: Check if we should support ~Escapable elements
|
||||
associatedtype WriteElement: ~Copyable
|
||||
|
||||
/// The error type that writing operations throw.
|
||||
associatedtype WriteFailure: Error
|
||||
|
||||
/// The data the writer delivers alongside the end-of-stream signal.
|
||||
///
|
||||
/// Defaults to `Void`.
|
||||
// TODO: Check if we should support ~Escapable final element
|
||||
associatedtype FinalElement: ~Copyable = Void
|
||||
|
||||
/// Writes elements from the provided buffer to the underlying destination.
|
||||
///
|
||||
/// This method asynchronously writes all elements from the provided buffer
|
||||
/// to the underlying destination.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// var fileWriter: FileAsyncWriter = ...
|
||||
/// var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
///
|
||||
/// try await fileWriter.write(buffer: &data)
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter buffer: The buffer of elements to write.
|
||||
///
|
||||
/// - Throws: A `WriteFailure` from the underlying write operation.
|
||||
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable
|
||||
|
||||
/// Sends the final buffer and ``FinalElement`` payload, and signals
|
||||
/// end-of-stream to the destination.
|
||||
///
|
||||
/// The buffer may be empty if there is no remaining content to emit
|
||||
/// alongside the terminator. When ``FinalElement`` is `Void`, use the
|
||||
/// closure-less ``finish()`` convenience instead of passing `()` explicitly.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - buffer: The buffer of remaining elements to write alongside the
|
||||
/// terminator.
|
||||
/// - finalElement: The ``FinalElement`` payload to deliver with the end
|
||||
/// signal.
|
||||
/// - Throws: A `WriteFailure` from the underlying write operation.
|
||||
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer,
|
||||
finalElement: consuming FinalElement
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable
|
||||
}
|
||||
|
||||
@available(macOS 26.2, iOS 26.2, watchOS 26.2, tvOS 26.2, visionOS 26.2, *)
|
||||
extension CallerAsyncWriter where Self: ~Copyable, Self: ~Escapable, FinalElement == Void {
|
||||
/// Concludes the writer with no final buffer and no extra payload.
|
||||
///
|
||||
/// Available only when ``FinalElement`` is `Void`. Equivalent to calling
|
||||
/// ``finish(buffer:finalElement:)`` with an empty buffer and `()`.
|
||||
public consuming func finish() async throws(WriteFailure) {
|
||||
var empty = UniqueArray<WriteElement>()
|
||||
try await self.finish(buffer: &empty, finalElement: ())
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,118 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import ContainersPreview
|
||||
public import BasicContainers
|
||||
|
||||
/// An ``AsyncWriter`` that is implemented in terms of a ``CallerAsyncWriter``.
|
||||
///
|
||||
/// The adapter allocates a fresh buffer for each ``write(_:)`` call, runs
|
||||
/// the body to fill it, and immediately drains it into the underlying
|
||||
/// ``CallerAsyncWriter``. Writes are flushed *eagerly*: the adapter does
|
||||
/// not defer the most recent buffer to fuse it with ``finish(finalElement:)``.
|
||||
///
|
||||
/// Eager flushing keeps request/response patterns deadlock-free — a write
|
||||
/// is observable to the peer as soon as the underlying writer accepts it.
|
||||
/// The trade-off is that fused close (HTTP/2 DATA+END_STREAM coalescing,
|
||||
/// and similar) is not available through this adapter; the underlying
|
||||
/// ``CallerAsyncWriter/finish(buffer:finalElement:)`` always receives an
|
||||
/// empty buffer. Conformers that need fused close should implement
|
||||
/// ``AsyncWriter`` directly rather than going through this adapter.
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
public struct CallerAsyncWriterAsyncWriterAdapter<
|
||||
Underlying: CallerAsyncWriter & ~Copyable,
|
||||
Buffer: DynamicContainer<Underlying.WriteElement> & ~Copyable
|
||||
>: ~Copyable, AsyncWriter {
|
||||
public typealias WriteElement = Underlying.WriteElement
|
||||
public typealias WriteFailure = Underlying.WriteFailure
|
||||
public typealias FinalElement = Underlying.FinalElement
|
||||
|
||||
@usableFromInline
|
||||
var underlying: Underlying
|
||||
|
||||
@usableFromInline
|
||||
let initialCapacity: Int
|
||||
|
||||
@inlinable
|
||||
init(underlying: consuming Underlying, initialCapacity: Int) {
|
||||
self.underlying = underlying
|
||||
self.initialCapacity = initialCapacity
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func write<Return: ~Copyable, Failure: Error>(
|
||||
_ body: (inout Buffer) async throws(Failure) -> Return
|
||||
) async throws(EitherError<WriteFailure, Failure>) -> Return {
|
||||
var buffer = Buffer(minimumCapacity: self.initialCapacity)
|
||||
let result: Return
|
||||
do throws(Failure) {
|
||||
result = try await body(&buffer)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
do throws(WriteFailure) {
|
||||
try await self.underlying.write(buffer: &buffer)
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public consuming func finish(
|
||||
finalElement: consuming FinalElement
|
||||
) async throws(WriteFailure) {
|
||||
var empty = Buffer()
|
||||
try await self.underlying.finish(buffer: &empty, finalElement: finalElement)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension CallerAsyncWriter where Self: ~Copyable {
|
||||
/// Adapts this ``CallerAsyncWriter`` to an ``AsyncWriter``, using
|
||||
/// ``UniqueArray`` as the buffer container.
|
||||
///
|
||||
/// Each ``AsyncWriter/write(_:)`` call on the returned adapter
|
||||
/// allocates a fresh buffer, runs the closure to fill it, and
|
||||
/// immediately drains it into this writer. Writes are flushed
|
||||
/// eagerly — see ``CallerAsyncWriterAsyncWriterAdapter`` for the
|
||||
/// trade-off this implies for fused close.
|
||||
///
|
||||
/// - Parameter initialCapacity: The capacity reserved on each
|
||||
/// freshly allocated buffer.
|
||||
/// - Returns: An adapter that conforms to ``AsyncWriter``.
|
||||
@inlinable
|
||||
public consuming func asAsyncWriter(
|
||||
initialCapacity: Int = 4096
|
||||
) -> CallerAsyncWriterAsyncWriterAdapter<Self, UniqueArray<WriteElement>> {
|
||||
.init(underlying: self, initialCapacity: initialCapacity)
|
||||
}
|
||||
|
||||
/// Adapts this ``CallerAsyncWriter`` to an ``AsyncWriter`` with a
|
||||
/// caller-chosen buffer container type.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - bufferType: The container type for buffers handed to the
|
||||
/// ``AsyncWriter/write(_:)`` body.
|
||||
/// - initialCapacity: The capacity reserved on each freshly
|
||||
/// allocated buffer.
|
||||
/// - Returns: An adapter that conforms to ``AsyncWriter``.
|
||||
@inlinable
|
||||
public consuming func asAsyncWriter<Buffer>(
|
||||
bufferOf bufferType: Buffer.Type,
|
||||
initialCapacity: Int = 4096
|
||||
) -> CallerAsyncWriterAsyncWriterAdapter<Self, Buffer>
|
||||
where Buffer: DynamicContainer<WriteElement> & ~Copyable {
|
||||
.init(underlying: self, initialCapacity: initialCapacity)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,532 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import DequeModule
|
||||
public import ContainersPreview
|
||||
|
||||
/// A bidirectional, in-memory duplex channel with four connected handles.
|
||||
///
|
||||
/// Each call to ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
|
||||
/// creates two ``Writer``s and two ``Reader``s connected by a pair of
|
||||
/// internal ``MultiProducerSingleConsumerAsyncChannel`` storages — one
|
||||
/// per direction:
|
||||
///
|
||||
/// ```
|
||||
/// forward
|
||||
/// writerA ────────────────────────────────────────> readerB
|
||||
///
|
||||
/// reverse
|
||||
/// readerA <──────────────────────────────────────── writerB
|
||||
/// ```
|
||||
///
|
||||
/// The four handles are independent `~Copyable` values so each can be
|
||||
/// sent to its own task without an intermediate decomposition step.
|
||||
///
|
||||
/// Each direction applies backpressure independently using the configured
|
||||
/// ``BackpressureStrategy``: writes suspend when the per-direction buffer
|
||||
/// rises above the high watermark and resume once it drops below the low
|
||||
/// watermark.
|
||||
///
|
||||
///
|
||||
/// To scope the channel and its handles to a structured-concurrency
|
||||
/// region, use
|
||||
/// ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``.
|
||||
/// When `body` returns, both directions are finalized and any remaining
|
||||
/// suspended producers are resumed with an error.
|
||||
///
|
||||
/// The ``FinalElement`` and ``Failure`` types apply to both directions.
|
||||
/// Each direction's writer terminates its half of the channel
|
||||
/// independently by calling ``Writer/finish(finalElement:)`` or
|
||||
/// ``Writer/finish(throwing:)``.
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
public struct DuplexAsyncChannel<
|
||||
Element: Sendable,
|
||||
FinalElement: Sendable,
|
||||
Failure: Error
|
||||
>: ~Copyable {
|
||||
/// Creates a new duplex channel with four connected handles and runs
|
||||
/// `body` with all four.
|
||||
///
|
||||
/// The handles are paired by side:
|
||||
///
|
||||
/// - `writerA` and `readerA` belong to side A. Elements `writerA`
|
||||
/// sends are observed on `readerB`; `readerA` observes elements
|
||||
/// `writerB` sends.
|
||||
/// - `writerB` and `readerB` belong to side B, mirrored.
|
||||
///
|
||||
/// After `body` returns, the duplex finalizes both directions and
|
||||
/// resumes any remaining suspended producers with an error.
|
||||
///
|
||||
/// The handles are noncopyable and have no `deinit`-based cleanup. To
|
||||
/// terminate one direction before the scope ends, call
|
||||
/// ``Writer/finish(finalElement:)`` or ``Writer/finish(throwing:)`` on
|
||||
/// the corresponding writer. Otherwise `withDuplex` finalizes both
|
||||
/// directions when `body` returns.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - elementType: The element type of both directions.
|
||||
/// - finalElementType: The end-of-stream payload type of both
|
||||
/// directions.
|
||||
/// - failureType: The failure type of both directions.
|
||||
/// - backpressureStrategy: The backpressure strategy applied
|
||||
/// independently to each direction.
|
||||
/// - isolation: The actor isolation in which `body` runs. Defaults to
|
||||
/// the caller's isolation.
|
||||
/// - body: A closure that receives ownership of the four connected
|
||||
/// handles, in order: side A's writer, side A's reader, side B's
|
||||
/// writer, side B's reader.
|
||||
/// - Returns: The value returned from `body`.
|
||||
@inlinable
|
||||
public static func withDuplex<Result: ~Copyable, BodyFailure: Error>(
|
||||
of elementType: Element.Type = Element.self,
|
||||
withFinalElement finalElementType: FinalElement.Type,
|
||||
throwing failureType: Failure.Type = Never.self,
|
||||
backpressureStrategy: BackpressureStrategy,
|
||||
isolation: isolated (any Actor)? = #isolation,
|
||||
body: (
|
||||
consuming sending Writer,
|
||||
consuming sending Reader,
|
||||
consuming sending Writer,
|
||||
consuming sending Reader
|
||||
) async throws(BodyFailure) -> sending Result
|
||||
) async throws(BodyFailure) -> sending Result {
|
||||
let forward = MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage(
|
||||
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
|
||||
)
|
||||
let reverse = MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage(
|
||||
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
|
||||
)
|
||||
|
||||
let writerA = Writer(storage: forward)
|
||||
let readerA = Reader(storage: reverse)
|
||||
let writerB = Writer(storage: reverse)
|
||||
let readerB = Reader(storage: forward)
|
||||
|
||||
let result: Result
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(writerA, readerA, writerB, readerB)
|
||||
} catch {
|
||||
forward.finish(throwing: nil, finalElement: nil)
|
||||
reverse.finish(throwing: nil, finalElement: nil)
|
||||
forward.channelDeinitialized()
|
||||
reverse.channelDeinitialized()
|
||||
throw error
|
||||
}
|
||||
forward.finish(throwing: nil, finalElement: nil)
|
||||
reverse.finish(throwing: nil, finalElement: nil)
|
||||
forward.channelDeinitialized()
|
||||
reverse.channelDeinitialized()
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension DuplexAsyncChannel where FinalElement == Void {
|
||||
/// Creates a new duplex channel with a `Void` end-of-stream payload and
|
||||
/// runs `body` with all four handles.
|
||||
///
|
||||
/// This overload is available when ``FinalElement`` is `Void`. It's
|
||||
/// equivalent to calling
|
||||
/// ``withDuplex(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
|
||||
/// with `withFinalElement: Void.self`.
|
||||
@inlinable
|
||||
public static func withDuplex<Result: ~Copyable, BodyFailure: Error>(
|
||||
of elementType: Element.Type = Element.self,
|
||||
throwing failureType: Failure.Type = Never.self,
|
||||
backpressureStrategy: BackpressureStrategy,
|
||||
isolation: isolated (any Actor)? = #isolation,
|
||||
body: (
|
||||
consuming sending Writer,
|
||||
consuming sending Reader,
|
||||
consuming sending Writer,
|
||||
consuming sending Reader
|
||||
) async throws(BodyFailure) -> sending Result
|
||||
) async throws(BodyFailure) -> sending Result {
|
||||
try await self.withDuplex(
|
||||
of: elementType,
|
||||
withFinalElement: Void.self,
|
||||
throwing: failureType,
|
||||
backpressureStrategy: backpressureStrategy,
|
||||
isolation: isolation,
|
||||
body: body
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Backpressure strategy
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension DuplexAsyncChannel {
|
||||
/// A backpressure strategy applied independently to each direction of
|
||||
/// the duplex.
|
||||
public struct BackpressureStrategy: Sendable {
|
||||
@usableFromInline
|
||||
var internalBackpressureStrategy:
|
||||
MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._InternalBackpressureStrategy
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
internalBackpressureStrategy:
|
||||
MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._InternalBackpressureStrategy
|
||||
) {
|
||||
self.internalBackpressureStrategy = internalBackpressureStrategy
|
||||
}
|
||||
|
||||
/// A backpressure strategy that suspends and resumes producers based
|
||||
/// on high and low watermarks.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the buffered element count drops below this
|
||||
/// watermark, the channel resumes suspended producers in that
|
||||
/// direction.
|
||||
/// - high: When the buffered element count rises above this
|
||||
/// watermark, the channel suspends new writes in that direction.
|
||||
@inlinable
|
||||
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
|
||||
.init(
|
||||
internalBackpressureStrategy: .watermark(
|
||||
.init(low: low, high: high, waterLevelForElement: nil)
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
/// A backpressure strategy that suspends and resumes producers based
|
||||
/// on high and low watermarks, weighted by a per-element water level.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the water level drops below this watermark, the
|
||||
/// channel resumes suspended producers in that direction.
|
||||
/// - high: When the water level rises above this watermark, the
|
||||
/// channel suspends new writes in that direction.
|
||||
/// - waterLevelForElement: A closure that returns the water-level
|
||||
/// contribution of a single element. The channel calls this
|
||||
/// closure while holding its lock, so the closure must be free of
|
||||
/// side effects and should run in constant time.
|
||||
@inlinable
|
||||
public static func watermark(
|
||||
low: Int,
|
||||
high: Int,
|
||||
waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int
|
||||
) -> BackpressureStrategy {
|
||||
.init(
|
||||
internalBackpressureStrategy: .watermark(
|
||||
.init(low: low, high: high, waterLevelForElement: waterLevelForElement)
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Writer
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension DuplexAsyncChannel {
|
||||
/// The writer half of one side of a ``DuplexAsyncChannel``.
|
||||
///
|
||||
/// Conforms to ``CallerAsyncWriter``: callers provide their own
|
||||
/// ``RangeReplaceableContainer``-conforming buffer that the writer
|
||||
/// drains.
|
||||
///
|
||||
/// Elements written here travel the channel's forward or reverse
|
||||
/// direction and are observed on the peer side's ``Reader``. The writer
|
||||
/// applies backpressure: ``write(buffer:)`` suspends when the
|
||||
/// destination's buffer rises above the configured high watermark.
|
||||
///
|
||||
/// Writers can be cloned with ``clone()`` to produce concurrently from
|
||||
/// multiple tasks. Terminate the direction with
|
||||
/// ``finish(buffer:finalElement:)``, ``finish(finalElement:)``, or
|
||||
/// ``finish(throwing:)``.
|
||||
public struct Writer: ~Copyable, CallerAsyncWriter {
|
||||
public typealias WriteElement = Element
|
||||
public typealias WriteFailure = any Error
|
||||
@usableFromInline
|
||||
let _storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
|
||||
|
||||
@usableFromInline
|
||||
let _id: UInt64
|
||||
|
||||
@usableFromInline
|
||||
init(
|
||||
storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
|
||||
) {
|
||||
self._storage = storage
|
||||
self._id = storage.sourceInitialized()
|
||||
}
|
||||
|
||||
/// Sets a callback to invoke when this direction terminates.
|
||||
///
|
||||
/// The duplex calls `callback` after the peer's reader observes its
|
||||
/// last element on this direction. If the direction has already
|
||||
/// terminated, the duplex invokes `callback` immediately.
|
||||
///
|
||||
/// - Important: A writer supports a single termination callback.
|
||||
/// Setting a new callback replaces any previous one.
|
||||
@inlinable
|
||||
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
|
||||
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
|
||||
}
|
||||
|
||||
/// Creates an additional writer for this direction so multiple
|
||||
/// producers can send concurrently.
|
||||
///
|
||||
/// The cloned writer terminates the direction independently — the
|
||||
/// direction stays open until every clone has finished or been
|
||||
/// dropped, mirroring ``MultiProducerSingleConsumerAsyncChannel/Source/clone()``.
|
||||
@inlinable
|
||||
public mutating func clone() -> sending Self {
|
||||
.init(storage: self._storage)
|
||||
}
|
||||
|
||||
/// Terminates this direction with the supplied error.
|
||||
///
|
||||
/// After the peer reader consumes all buffered elements on this
|
||||
/// direction, its next ``Reader/read(body:)`` call throws `error`.
|
||||
/// This path delivers no ``FinalElement`` payload to the peer.
|
||||
///
|
||||
/// To terminate this direction cleanly with an end-of-stream payload,
|
||||
/// call ``finish(finalElement:)`` instead. When ``FinalElement`` is
|
||||
/// `Void`, you can also call the ``finish()`` convenience.
|
||||
@inlinable
|
||||
public consuming func finish(throwing error: Failure) {
|
||||
self._storage.finish(throwing: error, finalElement: nil)
|
||||
}
|
||||
|
||||
/// Finishes this direction with a ``FinalElement`` payload.
|
||||
///
|
||||
/// The peer reader observes end-of-stream as a non-`nil` `finalElement`
|
||||
/// argument to the body of its next ``Reader/read(body:)`` call. The
|
||||
/// channel delivers any elements still buffered from earlier
|
||||
/// ``write(buffer:)`` calls before the terminator.
|
||||
///
|
||||
/// - Note: This method delivers only the end-of-stream signal. To
|
||||
/// send a final batch of elements alongside the terminator, call
|
||||
/// ``write(buffer:)`` first and then ``finish(finalElement:)``.
|
||||
@inlinable
|
||||
public consuming func finish(finalElement: consuming sending FinalElement) {
|
||||
self._storage.finish(throwing: nil, finalElement: finalElement)
|
||||
}
|
||||
|
||||
/// Writes every element of `buffer` to this direction.
|
||||
///
|
||||
/// On success the call drains `buffer` completely. If the
|
||||
/// direction's backpressure strategy signals that production should
|
||||
/// pause, the call suspends until the peer reader drains enough of
|
||||
/// the channel to fall below the low watermark.
|
||||
///
|
||||
/// - Throws: ``MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError``
|
||||
/// if this direction has already finished, or `CancellationError`
|
||||
/// if the task is canceled while suspended on backpressure.
|
||||
@inlinable
|
||||
public mutating func write<Buffer: RangeReplaceableContainer<Element> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws {
|
||||
// Move the caller's buffer into a `nonisolated(unsafe)` local so we
|
||||
// can hand it to the storage's `inout sending` API. Safe because
|
||||
// the elements are Sendable and we have the buffer inout so an exclusive
|
||||
// ownership.
|
||||
nonisolated(unsafe) var localBuffer = consume buffer
|
||||
let sendResult: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>.Source._SendResult
|
||||
do {
|
||||
sendResult = try self._storage.write(buffer: &localBuffer)
|
||||
} catch {
|
||||
buffer = consume localBuffer
|
||||
throw error
|
||||
}
|
||||
buffer = consume localBuffer
|
||||
|
||||
switch consume sendResult {
|
||||
case .produceMore:
|
||||
return
|
||||
|
||||
case .enqueueCallback(let token):
|
||||
let storage = self._storage
|
||||
do {
|
||||
try await withTaskCancellationHandler {
|
||||
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Void, any Error>) in
|
||||
storage.enqueueProducer(callbackToken: token, continuation: continuation)
|
||||
}
|
||||
} onCancel: {
|
||||
storage.cancelProducer(callbackToken: token)
|
||||
}
|
||||
} catch {
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Drains `buffer` to the peer, then signals end-of-stream with the
|
||||
/// ``FinalElement`` payload. Consumes the writer.
|
||||
///
|
||||
/// This is the ``CallerAsyncWriter`` protocol entry point. The
|
||||
/// duplex's in-memory transport doesn't fuse the last write with the
|
||||
/// end-of-stream signal — `write(buffer:)` and `finish` are issued
|
||||
/// sequentially. The observable result for the peer reader matches
|
||||
/// the fused contract: the peer sees the trailing buffer's elements
|
||||
/// and the `finalElement` together on its terminal `read`.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - buffer: A buffer of remaining elements to write before
|
||||
/// signaling end-of-stream.
|
||||
/// - finalElement: The payload to deliver alongside the
|
||||
/// end-of-stream signal.
|
||||
/// - Throws: Any error thrown while draining `buffer`. If draining
|
||||
/// fails, the direction is left unterminated; the scope's
|
||||
/// finalizer terminates it on body return.
|
||||
@inlinable
|
||||
public consuming func finish<Buffer: RangeReplaceableContainer<Element> & ~Copyable>(
|
||||
buffer: inout Buffer,
|
||||
finalElement: consuming FinalElement
|
||||
) async throws {
|
||||
try await self.write(buffer: &buffer)
|
||||
self._storage.finish(throwing: nil, finalElement: finalElement)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension DuplexAsyncChannel.Writer where FinalElement == Void {
|
||||
/// Finishes this direction with an empty `Void` end-of-stream payload.
|
||||
///
|
||||
/// This method is equivalent to calling ``finish(finalElement:)`` with
|
||||
/// `()`. The peer reader observes end-of-stream as a non-`nil`
|
||||
/// `finalElement` argument to the body of its next read.
|
||||
@inlinable
|
||||
public consuming func finish() {
|
||||
self._storage.finish(throwing: nil, finalElement: ())
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Reader
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension DuplexAsyncChannel {
|
||||
/// The reader half of one side of a ``DuplexAsyncChannel``.
|
||||
///
|
||||
/// Conforms to ``AsyncReader``: the reader hands a noncopyable
|
||||
/// ``UniqueDeque`` of elements to the body closure alongside an
|
||||
/// optional ``FinalElement`` payload that signals end-of-stream when
|
||||
/// present.
|
||||
///
|
||||
/// Reads elements written by the peer side's ``Writer``.
|
||||
public struct Reader: ~Copyable, AsyncReader {
|
||||
public typealias ReadElement = Element
|
||||
public typealias Buffer = UniqueDeque<Element>
|
||||
public typealias ReadFailure = EitherError<Failure, CancellationError>
|
||||
@usableFromInline
|
||||
let _storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
|
||||
|
||||
@usableFromInline
|
||||
init(
|
||||
storage: MultiProducerSingleConsumerAsyncChannel<Element, FinalElement, Failure>._Storage
|
||||
) {
|
||||
self._storage = storage
|
||||
}
|
||||
|
||||
/// Reads the next chunk of elements from this direction.
|
||||
///
|
||||
/// The reader passes the buffered elements to `body` along with an
|
||||
/// optional ``FinalElement`` payload. A non-`nil` `finalElement`
|
||||
/// marks the chunk as terminal and delivers the end-of-stream signal.
|
||||
/// The terminal chunk's buffer may be empty or contain a final batch
|
||||
/// of elements.
|
||||
///
|
||||
/// - Throws: An ``EitherError`` whose outer `.first` arm carries a
|
||||
/// read-side error — either the duplex's `Failure` (when the peer
|
||||
/// writer called ``Writer/finish(throwing:)``) or a
|
||||
/// `CancellationError` (when the task is canceled while suspended
|
||||
/// in `read`) — and whose outer `.second` arm carries the failure
|
||||
/// thrown by `body`.
|
||||
///
|
||||
/// - Important: After the reader observes a non-`nil` `finalElement` or
|
||||
/// `read(body:)` throws a read-side error, calling `read(body:)` again is
|
||||
/// a programmer error.
|
||||
@inlinable
|
||||
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
|
||||
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
|
||||
) async throws(EitherError<EitherError<Failure, CancellationError>, BodyFailure>) -> Return {
|
||||
while true {
|
||||
let action = self._storage.readAvailable()
|
||||
switch consume action {
|
||||
case .returnElements(let disconnected):
|
||||
var buffer = disconnected.take()
|
||||
let result: Return
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(&buffer, nil)
|
||||
let buffer = buffer
|
||||
self._storage.returnCachedReadBuffer(buffer)
|
||||
} catch {
|
||||
let buffer = buffer
|
||||
self._storage.returnCachedReadBuffer(buffer)
|
||||
throw .second(error)
|
||||
}
|
||||
return result
|
||||
|
||||
case .returnElementsAndResumeProducers(let disconnected, let producers):
|
||||
var buffer = disconnected.take()
|
||||
for producer in producers {
|
||||
switch producer {
|
||||
case .closure(let onProduceMore):
|
||||
onProduceMore(Result<Void, any Error>.success(()))
|
||||
case .continuation(let continuation):
|
||||
continuation.resume()
|
||||
}
|
||||
}
|
||||
let result: Return
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(&buffer, nil)
|
||||
let buffer = buffer
|
||||
self._storage.returnCachedReadBuffer(buffer)
|
||||
} catch {
|
||||
let buffer = buffer
|
||||
self._storage.returnCachedReadBuffer(buffer)
|
||||
throw .second(error)
|
||||
}
|
||||
return result
|
||||
|
||||
case .returnTerminalChunk(let disconnectedBuffer, let disconnectedFinal, let onTerminations):
|
||||
for (_, callback) in onTerminations { callback() }
|
||||
var buffer = disconnectedBuffer.take()
|
||||
let final = disconnectedFinal.take()
|
||||
do throws(BodyFailure) {
|
||||
return try await body(&buffer, final)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
|
||||
case .throwFailure(let failure, let onTerminations):
|
||||
for (_, callback) in onTerminations { callback() }
|
||||
if let failure {
|
||||
throw .first(.first(failure))
|
||||
}
|
||||
var empty = UniqueDeque<Element>()
|
||||
do throws(BodyFailure) {
|
||||
return try await body(&empty, nil)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
|
||||
case .throwCancellation:
|
||||
throw .first(.second(CancellationError()))
|
||||
|
||||
case .suspend:
|
||||
do {
|
||||
try await self._storage.suspendRead()
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
continue
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,54 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2022 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
/// A type-safe wrapper around one of two distinct error types.
|
||||
///
|
||||
/// Use ``EitherError`` when an operation can fail with errors from two
|
||||
/// different sources, such as a read failure and a body closure failure.
|
||||
@frozen
|
||||
public enum EitherError<First: Error, Second: Error>: Error {
|
||||
/// An error of the first type.
|
||||
case first(First)
|
||||
|
||||
/// An error of the second type.
|
||||
case second(Second)
|
||||
|
||||
/// Throws the underlying error, unwrapping this ``EitherError``.
|
||||
///
|
||||
/// This method extracts and throws the contained error,
|
||||
/// whether it's the first or second type. Use this when you need to propagate
|
||||
/// the original error without the ``EitherError`` wrapper.
|
||||
///
|
||||
/// - Throws: The underlying error, either of type `First` or `Second`.
|
||||
///
|
||||
/// ## Example
|
||||
///
|
||||
/// ```swift
|
||||
/// do {
|
||||
/// let result = try await operation()
|
||||
/// } catch let eitherError as EitherError<NetworkError, ParseError> {
|
||||
/// try eitherError.unwrap()
|
||||
/// }
|
||||
/// ```
|
||||
public func unwrap() throws {
|
||||
switch self {
|
||||
case .first(let first):
|
||||
throw first
|
||||
case .second(let second):
|
||||
throw second
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension EitherError: Equatable where First: Equatable, Second: Equatable {}
|
||||
extension EitherError: Hashable where First: Hashable, Second: Hashable {}
|
||||
#endif
|
||||
+1065
File diff suppressed because it is too large.
Load diff
+417
@@ -0,0 +1,417 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
public import DequeModule
|
||||
public import ContainersPreview
|
||||
|
||||
/// A multi-producer single-consumer channel.
|
||||
///
|
||||
/// This is the streaming-oriented variant of
|
||||
/// ``AsyncAlgorithms.MultiProducerSingleConsumerAsyncChannel``. Instead of
|
||||
/// exposing the consumer side as an `AsyncSequence`, it offers a chunked
|
||||
/// ``read(body:)`` method that delivers a noncopyable ``UniqueDeque`` buffer
|
||||
/// to the caller, so elements move through the channel without copying.
|
||||
///
|
||||
/// The channel applies backpressure to producers: it suspends writes when
|
||||
/// the buffer rises above the high watermark and resumes them once the
|
||||
/// buffer drops below the low watermark.
|
||||
///
|
||||
/// To scope the channel and its initial source to a structured-concurrency
|
||||
/// region, use ``withChannel(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``.
|
||||
///
|
||||
/// The channel takes a ``FinalElement`` type that it delivers alongside the
|
||||
/// end-of-stream signal. A producer terminates the channel by calling
|
||||
/// either ``Source/finish(finalElement:)`` to signal end-of-stream
|
||||
/// or ``Source/finish(throwing:)`` to terminate with a failure.
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
public struct MultiProducerSingleConsumerAsyncChannel<
|
||||
Element,
|
||||
FinalElement,
|
||||
Failure: Error
|
||||
>: ~Copyable {
|
||||
@usableFromInline
|
||||
let storage: _Storage
|
||||
|
||||
@usableFromInline
|
||||
init(storage: _Storage) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
/// Creates a new channel and runs `body` with the channel and its initial
|
||||
/// source. After `body` returns, the channel finalizes itself and resumes
|
||||
/// any remaining suspended producers with an error.
|
||||
///
|
||||
/// The channel and source are noncopyable and have no `deinit`-based
|
||||
/// cleanup. To terminate the channel before its scope ends, call
|
||||
/// ``Source/finish(finalElement:)`` or ``Source/finish(throwing:)`` on a
|
||||
/// source. Otherwise `withChannel` finalizes the channel when `body`
|
||||
/// returns.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - elementType: The element type of the channel.
|
||||
/// - finalElementType: The end-of-stream payload type of the channel.
|
||||
/// - failureType: The failure type of the channel.
|
||||
/// - backpressureStrategy: The backpressure strategy that the channel uses.
|
||||
/// - isolation: The actor isolation in which `body` runs. Defaults to the caller's isolation.
|
||||
/// - body: A closure that receives ownership of the channel and its initial source.
|
||||
/// - Returns: The value returned from `body`.
|
||||
@inlinable
|
||||
public static func withChannel<Result: ~Copyable, BodyFailure: Error>(
|
||||
of elementType: Element.Type = Element.self,
|
||||
withFinalElement finalElementType: FinalElement.Type,
|
||||
throwing failureType: Failure.Type = Never.self,
|
||||
backpressureStrategy: Source.BackpressureStrategy,
|
||||
isolation: isolated (any Actor)? = #isolation,
|
||||
body: (
|
||||
consuming sending MultiProducerSingleConsumerAsyncChannel,
|
||||
consuming sending Source
|
||||
) async throws(BodyFailure) -> sending Result
|
||||
) async throws(BodyFailure) -> sending Result {
|
||||
let storage = _Storage(
|
||||
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
|
||||
)
|
||||
let channel = MultiProducerSingleConsumerAsyncChannel(storage: storage)
|
||||
let source = Source(storage: storage)
|
||||
let result: Result
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(channel, source)
|
||||
} catch {
|
||||
storage.finish(throwing: nil, finalElement: nil)
|
||||
storage.channelDeinitialized()
|
||||
throw error
|
||||
}
|
||||
storage.finish(throwing: nil, finalElement: nil)
|
||||
storage.channelDeinitialized()
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel where FinalElement == Void {
|
||||
/// Creates a new channel with a `Void` end-of-stream payload and runs
|
||||
/// `body` with the channel and its initial source.
|
||||
///
|
||||
/// This overload is available when ``FinalElement`` is `Void`. It's
|
||||
/// equivalent to calling
|
||||
/// ``withChannel(of:withFinalElement:throwing:backpressureStrategy:isolation:body:)``
|
||||
/// with `withFinalElement: Void.self`.
|
||||
public static func withChannel<Result: ~Copyable, BodyFailure: Error>(
|
||||
of elementType: Element.Type = Element.self,
|
||||
throwing failureType: Failure.Type = Never.self,
|
||||
backpressureStrategy: Source.BackpressureStrategy,
|
||||
isolation: isolated (any Actor)? = #isolation,
|
||||
body: (
|
||||
consuming sending MultiProducerSingleConsumerAsyncChannel,
|
||||
consuming sending Source
|
||||
) async throws(BodyFailure) -> sending Result
|
||||
) async throws(BodyFailure) -> sending Result {
|
||||
try await self.withChannel(
|
||||
of: elementType,
|
||||
withFinalElement: Void.self,
|
||||
throwing: failureType,
|
||||
backpressureStrategy: backpressureStrategy,
|
||||
isolation: isolation,
|
||||
body: body
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel {
|
||||
/// A handle for sending elements to the channel.
|
||||
public struct Source: ~Copyable, Sendable {
|
||||
/// A backpressure strategy for the channel.
|
||||
public struct BackpressureStrategy: Sendable {
|
||||
@usableFromInline
|
||||
var internalBackpressureStrategy: _InternalBackpressureStrategy
|
||||
|
||||
@inlinable
|
||||
init(internalBackpressureStrategy: _InternalBackpressureStrategy) {
|
||||
self.internalBackpressureStrategy = internalBackpressureStrategy
|
||||
}
|
||||
|
||||
/// A backpressure strategy that suspends and resumes producers based on
|
||||
/// high and low watermarks.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the buffered element count drops below this watermark, the channel resumes suspended producers.
|
||||
/// - high: When the buffered element count rises above this watermark, the channel suspends new writes.
|
||||
@inlinable
|
||||
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
|
||||
.init(
|
||||
internalBackpressureStrategy: .watermark(
|
||||
.init(low: low, high: high, waterLevelForElement: nil)
|
||||
)
|
||||
)
|
||||
}
|
||||
|
||||
/// A backpressure strategy that suspends and resumes producers based on
|
||||
/// high and low watermarks, weighted by a per-element water level.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the water level drops below this watermark, the channel resumes suspended producers.
|
||||
/// - high: When the water level rises above this watermark, the channel suspends new writes.
|
||||
/// - waterLevelForElement: A closure that returns the water-level
|
||||
/// contribution of a single element. The channel calls this closure
|
||||
/// while holding its lock, so the closure must be free of side
|
||||
/// effects and should run in constant time.
|
||||
@inlinable
|
||||
public static func watermark(
|
||||
low: Int,
|
||||
high: Int,
|
||||
waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int
|
||||
) -> BackpressureStrategy {
|
||||
.init(
|
||||
internalBackpressureStrategy: .watermark(
|
||||
.init(low: low, high: high, waterLevelForElement: waterLevelForElement)
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
enum _SendResult: ~Copyable, Sendable {
|
||||
case produceMore
|
||||
case enqueueCallback(callbackToken: UInt64)
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let _storage: _Storage
|
||||
|
||||
@usableFromInline
|
||||
let _id: UInt64
|
||||
|
||||
@usableFromInline
|
||||
init(storage: _Storage) {
|
||||
self._storage = storage
|
||||
self._id = self._storage.sourceInitialized()
|
||||
}
|
||||
|
||||
/// Sets a callback to invoke when the channel terminates.
|
||||
///
|
||||
/// The channel calls `callback` after the reader observes its last element.
|
||||
/// If the channel has already terminated, the channel invokes `callback`
|
||||
/// immediately.
|
||||
///
|
||||
/// - Important: A source supports a single termination callback. Setting a
|
||||
/// new callback replaces any previous one.
|
||||
@inlinable
|
||||
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
|
||||
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
|
||||
}
|
||||
|
||||
/// Creates an additional source for sending elements to the channel
|
||||
/// concurrently from multiple producers.
|
||||
@inlinable
|
||||
public mutating func clone() -> sending Self {
|
||||
.init(storage: self._storage)
|
||||
}
|
||||
|
||||
/// Terminates the channel with the supplied error.
|
||||
///
|
||||
/// After the reader consumes all buffered elements, the next call to
|
||||
/// ``MultiProducerSingleConsumerAsyncChannel/read(body:)`` throws `error`.
|
||||
/// This path delivers no ``FinalElement`` payload to the reader.
|
||||
///
|
||||
/// To terminate the channel cleanly with an end-of-stream payload, call
|
||||
/// ``finish(finalElement:)`` instead. When ``FinalElement`` is `Void`,
|
||||
/// you can also call the ``finish()`` convenience.
|
||||
@inlinable
|
||||
public consuming func finish(throwing error: Failure) {
|
||||
self._storage.finish(throwing: error, finalElement: nil)
|
||||
}
|
||||
|
||||
/// Finishes the channel with a ``FinalElement`` payload.
|
||||
///
|
||||
/// The reader observes end-of-stream as a non-`nil` `finalElement`
|
||||
/// argument to the body of its next
|
||||
/// ``MultiProducerSingleConsumerAsyncChannel/read(body:)`` call. The
|
||||
/// channel delivers any elements still buffered from earlier
|
||||
/// ``write(buffer:)`` calls before the terminator.
|
||||
///
|
||||
/// - Note: This method delivers only the end-of-stream signal. To send a
|
||||
/// final batch of elements alongside the terminator, call
|
||||
/// ``write(buffer:)`` first and then ``finish(finalElement:)``.
|
||||
@inlinable
|
||||
public consuming func finish(finalElement: consuming sending FinalElement) {
|
||||
self._storage.finish(throwing: nil, finalElement: finalElement)
|
||||
}
|
||||
|
||||
/// Writes every element of `buffer` to the channel.
|
||||
///
|
||||
/// On success the call drains `buffer` completely. If the channel's
|
||||
/// backpressure strategy signals that production should pause, the call
|
||||
/// suspends until the reader drains enough of the channel to fall below
|
||||
/// the low watermark.
|
||||
///
|
||||
/// - Throws: ``MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError``
|
||||
/// if the channel has already finished, or `CancellationError` if the
|
||||
/// task is canceled while suspended on backpressure.
|
||||
@inlinable
|
||||
public mutating func write<Buffer: RangeReplaceableContainer<Element> & ~Copyable & Sendable>(
|
||||
buffer: inout sending Buffer
|
||||
) async throws {
|
||||
let sendResult: _SendResult
|
||||
do {
|
||||
sendResult = try self._storage.write(buffer: &buffer)
|
||||
} catch {
|
||||
throw error
|
||||
}
|
||||
|
||||
switch consume sendResult {
|
||||
case .produceMore:
|
||||
return
|
||||
|
||||
case .enqueueCallback(let token):
|
||||
let storage = self._storage
|
||||
do {
|
||||
try await withTaskCancellationHandler {
|
||||
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Void, any Error>) in
|
||||
storage.enqueueProducer(callbackToken: token, continuation: continuation)
|
||||
}
|
||||
} onCancel: {
|
||||
storage.cancelProducer(callbackToken: token)
|
||||
}
|
||||
} catch {
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel.Source where FinalElement == Void {
|
||||
/// Finishes the channel with an empty `Void` end-of-stream payload.
|
||||
///
|
||||
/// This method is equivalent to calling ``finish(finalElement:)`` with
|
||||
/// `()`. The reader observes end-of-stream as a non-`nil`
|
||||
/// `finalElement` argument to the body of its next read.
|
||||
@inlinable
|
||||
public consuming func finish() {
|
||||
self._storage.finish(throwing: nil, finalElement: ())
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Reading
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel {
|
||||
/// Reads the next chunk of elements from the channel.
|
||||
///
|
||||
/// The channel passes the buffered elements to `body` along with an
|
||||
/// optional ``FinalElement`` payload. A non-`nil` `finalElement` marks
|
||||
/// the chunk as terminal and delivers the end-of-stream signal. The
|
||||
/// terminal chunk's buffer may be empty or contain a final batch of
|
||||
/// elements.
|
||||
///
|
||||
/// - Throws: An ``EitherError`` whose outer `.first` arm carries a
|
||||
/// read-side error — either the channel's `Failure` (when a producer
|
||||
/// called ``Source/finish(throwing:)``) or a `CancellationError` (when
|
||||
/// the task is canceled while suspended in `read`) — and whose outer
|
||||
/// `.second` arm carries the failure thrown by `body`.
|
||||
///
|
||||
/// - Important: After the reader observes a non-`nil` `finalElement` or
|
||||
/// `read(body:)` throws a read-side error, calling `read(body:)` again is
|
||||
/// a programmer error.
|
||||
@inlinable
|
||||
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
|
||||
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
|
||||
) async throws(EitherError<EitherError<Failure, CancellationError>, BodyFailure>) -> Return {
|
||||
while true {
|
||||
let action = self.storage.readAvailable()
|
||||
switch consume action {
|
||||
case .returnElements(let disconnected):
|
||||
var buffer = disconnected.take()
|
||||
let result: Return
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(&buffer, nil)
|
||||
// TODO: This should not be necessary
|
||||
nonisolated(unsafe) let buffer = buffer
|
||||
self.storage.returnCachedReadBuffer(buffer)
|
||||
} catch {
|
||||
// TODO: This should not be necessary
|
||||
nonisolated(unsafe) let buffer = buffer
|
||||
self.storage.returnCachedReadBuffer(buffer)
|
||||
throw .second(error)
|
||||
}
|
||||
return result
|
||||
|
||||
case .returnElementsAndResumeProducers(let disconnected, let producers):
|
||||
var buffer = disconnected.take()
|
||||
for producer in producers {
|
||||
switch producer {
|
||||
case .closure(let onProduceMore):
|
||||
onProduceMore(Result<Void, any Error>.success(()))
|
||||
case .continuation(let continuation):
|
||||
continuation.resume()
|
||||
}
|
||||
}
|
||||
let result: Return
|
||||
do throws(BodyFailure) {
|
||||
result = try await body(&buffer, nil)
|
||||
// TODO: This should not be necessary
|
||||
nonisolated(unsafe) let buffer = buffer
|
||||
self.storage.returnCachedReadBuffer(buffer)
|
||||
} catch {
|
||||
// TODO: This should not be necessary
|
||||
nonisolated(unsafe) let buffer = buffer
|
||||
self.storage.returnCachedReadBuffer(buffer)
|
||||
throw .second(error)
|
||||
}
|
||||
return result
|
||||
|
||||
case .returnTerminalChunk(let disconnectedBuffer, let disconnectedFinal, let onTerminations):
|
||||
for (_, callback) in onTerminations { callback() }
|
||||
var buffer = disconnectedBuffer.take()
|
||||
let final = disconnectedFinal.take()
|
||||
do throws(BodyFailure) {
|
||||
return try await body(&buffer, final)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
|
||||
case .throwFailure(let failure, let onTerminations):
|
||||
for (_, callback) in onTerminations { callback() }
|
||||
if let failure {
|
||||
throw .first(.first(failure))
|
||||
}
|
||||
var empty = UniqueDeque<Element>()
|
||||
do throws(BodyFailure) {
|
||||
return try await body(&empty, nil)
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
|
||||
case .throwCancellation:
|
||||
throw .first(.second(CancellationError()))
|
||||
|
||||
case .suspend:
|
||||
do {
|
||||
try await self.storage.suspendRead()
|
||||
} catch {
|
||||
throw .first(error)
|
||||
}
|
||||
continue
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// An error that ``MultiProducerSingleConsumerAsyncChannel/Source/write(buffer:)``
|
||||
/// throws when its source has already finished.
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error {
|
||||
@usableFromInline
|
||||
init() {}
|
||||
}
|
||||
#endif
|
||||
File diff suppressed because it is too large.
Load diff
@@ -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);
|
||||
|
||||
+1128
File diff suppressed because it is too large.
Load diff
@@ -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")
|
||||
|
||||
@@ -27,6 +27,34 @@ final class TestReductions: XCTestCase {
|
||||
XCTAssertNil(pastEnd)
|
||||
}
|
||||
|
||||
func test_reductions_empty() async {
|
||||
let sequence = [Int]().async.reductions("") { partial, value in
|
||||
partial + "\(value)"
|
||||
}
|
||||
var iterator = sequence.makeAsyncIterator()
|
||||
var collected = [String]()
|
||||
while let item = await iterator.next() {
|
||||
collected.append(item)
|
||||
}
|
||||
XCTAssertEqual(collected, [])
|
||||
let pastEnd = await iterator.next()
|
||||
XCTAssertNil(pastEnd)
|
||||
}
|
||||
|
||||
func test_throwing_reductions_empty() async throws {
|
||||
let sequence = [Int]().async.reductions("") { (partial, value) throws -> String in
|
||||
partial + "\(value)"
|
||||
}
|
||||
var iterator = sequence.makeAsyncIterator()
|
||||
var collected = [String]()
|
||||
while let item = try await iterator.next() {
|
||||
collected.append(item)
|
||||
}
|
||||
XCTAssertEqual(collected, [])
|
||||
let pastEnd = try await iterator.next()
|
||||
XCTAssertNil(pastEnd)
|
||||
}
|
||||
|
||||
func test_inclusive_reductions() async {
|
||||
let sequence = [1, 2, 3, 4].async.reductions { $0 + $1 }
|
||||
var iterator = sequence.makeAsyncIterator()
|
||||
|
||||
@@ -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,172 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderCollectIntoTests {
|
||||
@Test
|
||||
func collectFillsTargetWhenReaderHasFewerElements() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var target = RigidArray<Int>(capacity: 10)
|
||||
|
||||
try await reader.collect(into: &target)
|
||||
|
||||
var collected: [Int] = []
|
||||
var c = target.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [1, 2, 3])
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectFillsTargetWhenReaderHasExactlyFreeCapacityElements() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var target = RigidArray<Int>(capacity: 3)
|
||||
|
||||
try await reader.collect(into: &target)
|
||||
|
||||
#expect(target.count == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectThrowsWhenReaderProducesMoreThanFreeCapacity() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
var target = RigidArray<Int>(capacity: 2)
|
||||
|
||||
do {
|
||||
try await reader.collect(into: &target)
|
||||
Issue.record("Expected error")
|
||||
} catch {
|
||||
let expected = EitherError<Never, AsyncReaderLeftOverElementsError>.second(AsyncReaderLeftOverElementsError())
|
||||
#expect(error == expected)
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectIntoEmptyReader() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
|
||||
try await reader.collect(into: &target)
|
||||
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderCollectExactlyTests {
|
||||
@Test
|
||||
func collectExactlyFillsTargetWhenReaderProducesExactCount() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var target = RigidArray<Int>(capacity: 3)
|
||||
|
||||
try await reader.collect(exactlyInto: &target)
|
||||
|
||||
var collected: [Int] = []
|
||||
var c = target.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [1, 2, 3])
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectExactlyThrowsWhenReaderProducesFewer() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
|
||||
do {
|
||||
try await reader.collect(exactlyInto: &target)
|
||||
Issue.record("Expected error")
|
||||
} catch {
|
||||
let expected = EitherError<
|
||||
Never,
|
||||
EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
|
||||
>.second(.second(AsyncReaderInsufficientElementsError()))
|
||||
#expect(error == expected)
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectExactlyThrowsWhenReaderProducesMore() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
var target = RigidArray<Int>(capacity: 2)
|
||||
|
||||
do {
|
||||
try await reader.collect(exactlyInto: &target)
|
||||
Issue.record("Expected error")
|
||||
} catch {
|
||||
let expected = EitherError<
|
||||
Never,
|
||||
EitherError<AsyncReaderLeftOverElementsError, AsyncReaderInsufficientElementsError>
|
||||
>.second(.first(AsyncReaderLeftOverElementsError()))
|
||||
#expect(error == expected)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderCollectIntoMaximumSizeTests {
|
||||
@Test
|
||||
func collectGrowsContainerWhenReaderHasFewerThanMaximum() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var target = UniqueArray<Int>()
|
||||
|
||||
try await reader.collect(into: &target, maximumSize: 10)
|
||||
|
||||
var collected: [Int] = []
|
||||
var c = target.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [1, 2, 3])
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectFillsContainerExactlyAtMaximum() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
|
||||
var target = UniqueArray<Int>()
|
||||
|
||||
try await reader.collect(into: &target, maximumSize: 3)
|
||||
|
||||
#expect(target.count == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectThrowsWhenReaderProducesMoreThanMaximum() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
var target = UniqueArray<Int>()
|
||||
|
||||
do {
|
||||
try await reader.collect(into: &target, maximumSize: 2)
|
||||
Issue.record("Expected error")
|
||||
} catch {
|
||||
let expected = EitherError<Never, AsyncReaderLeftOverElementsError>.second(AsyncReaderLeftOverElementsError())
|
||||
#expect(error == expected)
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func collectAppendsToExistingContents() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 2, copying: [3, 4]))
|
||||
var target = UniqueArray<Int>(capacity: 2, copying: [1, 2])
|
||||
|
||||
try await reader.collect(into: &target, maximumSize: 10)
|
||||
|
||||
var collected: [Int] = []
|
||||
var c = target.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [1, 2, 3, 4])
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,140 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderforEachBufferTests {
|
||||
@Test
|
||||
func forEachBufferIteratesAllSpans() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
var elementCount = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
elementCount += buffer.count
|
||||
}
|
||||
|
||||
#expect(elementCount == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferProcessesElements() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [10, 20, 30]))
|
||||
var sum = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
for i in buffer.indices {
|
||||
sum += buffer[i]
|
||||
}
|
||||
}
|
||||
|
||||
#expect(sum == 60)
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferWithEmptyReader() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
var callCount = 0
|
||||
|
||||
await reader.forEachBuffer { buffer in
|
||||
callCount += 1
|
||||
}
|
||||
|
||||
// The reader signals end-of-stream with an empty buffer; body should not be called.
|
||||
#expect(callCount == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferDoesNotInvokeBodyWithEmptyTerminalBuffer() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
var observedCounts: [Int] = []
|
||||
|
||||
_ = await reader.forEachBuffer { buffer in
|
||||
observedCounts.append(buffer.count)
|
||||
}
|
||||
|
||||
#expect(observedCounts.allSatisfy { $0 > 0 })
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferThrowingDoesNotInvokeBodyWithEmptyTerminalBuffer() async throws {
|
||||
enum TestError: Error {}
|
||||
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 0, copying: []))
|
||||
var observedCounts: [Int] = []
|
||||
|
||||
_ = try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
|
||||
observedCounts.append(buffer.count)
|
||||
}
|
||||
|
||||
#expect(observedCounts.allSatisfy { $0 > 0 })
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferWithThrowingBody() async {
|
||||
enum TestError: Error {
|
||||
case failed
|
||||
}
|
||||
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
|
||||
do {
|
||||
_ = try await reader.forEachBuffer { (_) throws(TestError) -> Void in
|
||||
throw TestError.failed
|
||||
}
|
||||
Issue.record("Expected error to be thrown")
|
||||
} catch {
|
||||
#expect(error == EitherError.second(TestError.failed))
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferWithNeverFailingReader() async {
|
||||
enum TestError: Error {
|
||||
case failed
|
||||
}
|
||||
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var count = 0
|
||||
|
||||
do {
|
||||
_ = try await reader.forEachBuffer { (buffer) throws(TestError) -> Void in
|
||||
count += buffer.count
|
||||
}
|
||||
} catch {
|
||||
Issue.record("No error should be thrown from reader")
|
||||
}
|
||||
|
||||
#expect(count == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
func forEachBufferWithAsyncWork() async throws {
|
||||
let reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
var results: [Int] = []
|
||||
|
||||
_ = await reader.forEachBuffer { buffer in
|
||||
await Task.yield()
|
||||
for i in buffer.indices {
|
||||
results.append(buffer[i])
|
||||
}
|
||||
}
|
||||
|
||||
#expect(results == [1, 2, 3])
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
@@ -0,0 +1,162 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderPipeTests {
|
||||
// MARK: - pipe(into:) — into a CallerAsyncWriter
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoCopiesAllElements() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
var array = UniqueArray(copying: [1, 2, 3, 4, 5])
|
||||
try await writerA.write(buffer: &array)
|
||||
writerA.finish()
|
||||
try await readerB.pipe(into: writerB)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoWithEmptyReader() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
let writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
writerA.finish()
|
||||
try await readerB.pipe(into: writerB)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoPreservesElementOrder() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 16, high: 100)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
let elements = Array(1...50)
|
||||
var array = UniqueArray(copying: elements)
|
||||
try await writerA.write(buffer: &array)
|
||||
writerA.finish()
|
||||
try await readerB.pipe(into: writerB)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 50)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == elements)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - pipe(copyingInto:) — into an AsyncWriter via the adapter
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeCopyingIntoCopiesAllElements() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
var array = UniqueArray(copying: [1, 2, 3, 4, 5])
|
||||
try await writerA.write(buffer: &array)
|
||||
writerA.finish()
|
||||
try await readerB.pipe(copyingInto: writerB.asAsyncWriter())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeCopyingIntoWithEmptyReader() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
let writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
writerA.finish()
|
||||
try await readerB.pipe(copyingInto: writerB.asAsyncWriter())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeCopyingIntoChunksTerminalChunkAcrossMultipleWrites() async throws {
|
||||
// 200 elements through a small (16-element) AsyncWriter buffer
|
||||
// forces the pipe loop to drain across multiple writes.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 32, high: 256)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
let readerB = readerB
|
||||
|
||||
let elements = Array(1...200)
|
||||
var array = UniqueArray(copying: elements)
|
||||
try await writerA.write(buffer: &array)
|
||||
writerA.finish()
|
||||
try await readerB.pipe(copyingInto: writerB.asAsyncWriter(initialCapacity: 16))
|
||||
|
||||
var target = RigidArray<Int>(capacity: 200)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == elements)
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,53 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncReaderTests {
|
||||
@Test
|
||||
func read() async {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5]))
|
||||
|
||||
var observedFinal = false
|
||||
let result: UniqueArray<Int> = try! await reader.read { (buffer, finalElement) in
|
||||
observedFinal = finalElement != nil
|
||||
return buffer.clone()
|
||||
}
|
||||
|
||||
#expect(result.count == 5)
|
||||
#expect(result[0] == 1)
|
||||
#expect(result[1] == 2)
|
||||
#expect(result[2] == 3)
|
||||
#expect(result[3] == 4)
|
||||
#expect(result[4] == 5)
|
||||
#expect(observedFinal)
|
||||
}
|
||||
|
||||
@Test
|
||||
func readDeliversTerminator() async {
|
||||
var reader = UniqueArrayAsyncReader(storage: UniqueArray(capacity: 3, copying: [1, 2, 3]))
|
||||
|
||||
var observedFinal = false
|
||||
let count: Int = try! await reader.read { (buffer, finalElement) in
|
||||
observedFinal = finalElement != nil
|
||||
return buffer.count
|
||||
}
|
||||
|
||||
#expect(count == 3)
|
||||
#expect(observedFinal)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,118 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncWriterCallerAsyncWriterAdapterTests {
|
||||
// The adapter wraps an AsyncWriter and exposes a CallerAsyncWriter.
|
||||
// We can't get an AsyncWriter from the duplex directly (its Writer is
|
||||
// a CallerAsyncWriter), so we wrap the duplex's Writer first via
|
||||
// asAsyncWriter() to get an AsyncWriter, then wrap THAT via
|
||||
// asCallerAsyncWriter() to exercise this adapter end-to-end.
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeAndFinishRoundTrip() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
var callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
|
||||
var buf = UniqueArray(copying: [1, 2, 3])
|
||||
try await callerWriter.write(buffer: &buf)
|
||||
var empty = UniqueArray<Int>()
|
||||
try await callerWriter.finish(buffer: &empty, finalElement: ())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeLoopsAcrossMultipleUnderlyingBuffers() async throws {
|
||||
// The CallerAsyncWriterAsyncWriterAdapter underneath uses a
|
||||
// 4096-element default buffer. We use a small initialCapacity to
|
||||
// force the inverse adapter to drive multiple underlying writes.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 32, high: 256)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
var callerWriter =
|
||||
writerB
|
||||
.asAsyncWriter(initialCapacity: 16)
|
||||
.asCallerAsyncWriter()
|
||||
|
||||
let elements = Array(1...100)
|
||||
var buf = UniqueArray(copying: elements)
|
||||
try await callerWriter.write(buffer: &buf)
|
||||
var empty = UniqueArray<Int>()
|
||||
try await callerWriter.finish(buffer: &empty, finalElement: ())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 100)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == elements)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func finishWithoutWriteDeliversEmptyTerminator() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
|
||||
var empty = UniqueArray<Int>()
|
||||
try await callerWriter.finish(buffer: &empty, finalElement: ())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func finishDeliversTrailingBufferAndPayload() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let callerWriter = writerB.asAsyncWriter().asCallerAsyncWriter()
|
||||
var trailing = UniqueArray(copying: [42, 43, 44])
|
||||
try await callerWriter.finish(buffer: &trailing, finalElement: ())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(Array(draining: &target) == [42, 43, 44])
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,110 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct AsyncWriterTests {
|
||||
@Test
|
||||
func writeElements() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(1)
|
||||
buffer.append(2)
|
||||
buffer.append(3)
|
||||
}
|
||||
|
||||
#expect(writer.storage.count == 3)
|
||||
#expect(writer.storage[0] == 1)
|
||||
#expect(writer.storage[1] == 2)
|
||||
#expect(writer.storage[2] == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeEmptyBuffer() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { _ in }
|
||||
|
||||
#expect(writer.storage.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeReturnsValue() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
let count = try! await writer.write { buffer in
|
||||
buffer.append(10)
|
||||
buffer.append(20)
|
||||
return buffer.count
|
||||
}
|
||||
|
||||
#expect(count == 2)
|
||||
#expect(writer.storage.count == 2)
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeWithThrowingBody() async {
|
||||
enum TestError: Error, Equatable {
|
||||
case failed
|
||||
}
|
||||
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
do {
|
||||
try await writer.write { (_) throws(TestError) -> Void in
|
||||
throw TestError.failed
|
||||
}
|
||||
Issue.record("Expected error to be thrown")
|
||||
} catch {
|
||||
#expect(error == EitherError<Never, TestError>.second(TestError.failed))
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeMultipleTimes() async {
|
||||
var writer = UniqueArrayAsyncWriter()
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(1)
|
||||
buffer.append(2)
|
||||
}
|
||||
|
||||
try! await writer.write { buffer in
|
||||
buffer.append(3)
|
||||
buffer.append(4)
|
||||
}
|
||||
|
||||
#expect(writer.storage.count == 4)
|
||||
#expect(writer.storage[0] == 1)
|
||||
#expect(writer.storage[1] == 2)
|
||||
#expect(writer.storage[2] == 3)
|
||||
#expect(writer.storage[3] == 4)
|
||||
}
|
||||
|
||||
@Test
|
||||
func finishVoidConvenience() async {
|
||||
let writer = UniqueArrayAsyncWriter()
|
||||
await writer.finish()
|
||||
}
|
||||
|
||||
@Test
|
||||
func finishDeliversFinalElement() async {
|
||||
let writer = UniqueArrayAsyncWriter()
|
||||
await writer.finish(finalElement: ())
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,152 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncReaderPipeTests {
|
||||
// MARK: - pipe(into:) — into an AsyncWriter via the adapter
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoCopiesAllElements() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let source = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(copying: [1, 2, 3, 4, 5])
|
||||
)
|
||||
try await source.pipe(into: writerB.asAsyncWriter())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoWithEmptyReader() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let source = UniqueArrayCallerAsyncReader(storage: UniqueArray<Int>())
|
||||
try await source.pipe(into: writerB.asAsyncWriter())
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeIntoLoopsAcrossMultipleBuffers() async throws {
|
||||
// 200 elements through a small AsyncWriter buffer forces the pipe
|
||||
// loop to iterate multiple times.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 32, high: 256)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let elements = Array(1...200)
|
||||
let source = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(copying: elements)
|
||||
)
|
||||
try await source.pipe(into: writerB.asAsyncWriter(initialCapacity: 16))
|
||||
|
||||
var target = RigidArray<Int>(capacity: 200)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == elements)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - pipe(bufferingInto:) — into a CallerAsyncWriter
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeBufferingIntoCopiesAllElements() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let source = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(copying: [1, 2, 3, 4, 5])
|
||||
)
|
||||
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeBufferingIntoWithEmptyReader() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let source = UniqueArrayCallerAsyncReader(storage: UniqueArray<Int>())
|
||||
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func pipeBufferingIntoReusesIntermediateBufferAcrossMultipleIterations() async throws {
|
||||
// 100 elements through a 16-element intermediate buffer forces the
|
||||
// pipe loop to iterate the buffer many times.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 16, high: 200)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let elements = Array(1...100)
|
||||
let source = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(copying: elements)
|
||||
)
|
||||
try await source.pipe(bufferingInto: writerB, intermediateCapacity: 16)
|
||||
|
||||
var target = RigidArray<Int>(capacity: 100)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == elements)
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,85 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncReaderTests {
|
||||
@Test
|
||||
func readIntoBuffer() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 10)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 5)
|
||||
#expect(buffer[0] == 1)
|
||||
#expect(buffer[1] == 2)
|
||||
#expect(buffer[2] == 3)
|
||||
#expect(buffer[3] == 4)
|
||||
#expect(buffer[4] == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
func readIntoBufferAtEnd() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 0, copying: [])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 10)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
func readIntoBufferRespectsCapacity() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 10, copying: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
|
||||
)
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 3)
|
||||
|
||||
await reader.read(into: &buffer)
|
||||
|
||||
#expect(buffer.count == 3)
|
||||
#expect(buffer[0] == 1)
|
||||
#expect(buffer[1] == 2)
|
||||
#expect(buffer[2] == 3)
|
||||
}
|
||||
|
||||
@Test
|
||||
func readMultipleTimes() async {
|
||||
var reader = UniqueArrayCallerAsyncReader(
|
||||
storage: UniqueArray(capacity: 6, copying: [1, 2, 3, 4, 5, 6])
|
||||
)
|
||||
|
||||
var buffer1 = UniqueArray<Int>(minimumCapacity: 3)
|
||||
await reader.read(into: &buffer1)
|
||||
#expect(buffer1.count == 3)
|
||||
#expect(buffer1[0] == 1)
|
||||
#expect(buffer1[1] == 2)
|
||||
#expect(buffer1[2] == 3)
|
||||
|
||||
var buffer2 = UniqueArray<Int>(minimumCapacity: 3)
|
||||
await reader.read(into: &buffer2)
|
||||
#expect(buffer2.count == 3)
|
||||
#expect(buffer2[0] == 4)
|
||||
#expect(buffer2[1] == 5)
|
||||
#expect(buffer2[2] == 6)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
+130
@@ -0,0 +1,130 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncWriterAsyncWriterAdapterTests {
|
||||
// The adapter wraps a CallerAsyncWriter and exposes an AsyncWriter, so
|
||||
// we drive it through the duplex's CallerAsyncWriter side and verify
|
||||
// the elements arrive on the peer reader.
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeAndFinishRoundTrip() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
var asyncWriter = writerB.asAsyncWriter()
|
||||
try await asyncWriter.write { buffer in
|
||||
buffer.append(1)
|
||||
buffer.append(2)
|
||||
buffer.append(3)
|
||||
}
|
||||
try await asyncWriter.finish()
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3])
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func multipleWritesAreFlushedEagerly() async throws {
|
||||
// The adapter must NOT defer the most recent write — each write call
|
||||
// should flush before returning, so the peer can observe progress
|
||||
// before close. We verify by reading back after each write.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
var readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
var asyncWriter = writerB.asAsyncWriter()
|
||||
|
||||
try await asyncWriter.write { $0.append(10) }
|
||||
// Reader sees the first write before any second write or finish.
|
||||
try await readerA.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 10)
|
||||
}
|
||||
|
||||
try await asyncWriter.write { $0.append(20) }
|
||||
try await readerA.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 20)
|
||||
}
|
||||
|
||||
try await asyncWriter.finish()
|
||||
try await readerA.read { buffer, finalElement in
|
||||
#expect(buffer.count == 0)
|
||||
#expect(finalElement != nil)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func finishWithoutWriteDeliversEmptyTerminator() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
let asyncWriter = writerB.asAsyncWriter()
|
||||
try await asyncWriter.finish()
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(into: &target)
|
||||
#expect(target.count == 0)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func customBufferTypePreservesElements() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 8, high: 32)
|
||||
) { _, readerA, writerB, _ in
|
||||
let readerA = readerA
|
||||
let writerB = writerB
|
||||
|
||||
var asyncWriter = writerB.asAsyncWriter(
|
||||
bufferOf: UniqueArray<Int>.self,
|
||||
initialCapacity: 16
|
||||
)
|
||||
try await asyncWriter.write { buffer in
|
||||
for v in 1...5 { buffer.append(v) }
|
||||
}
|
||||
try await asyncWriter.finish()
|
||||
|
||||
var target = RigidArray<Int>(capacity: 5)
|
||||
try await readerA.collect(exactlyInto: &target)
|
||||
#expect(Array(draining: &target) == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,50 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct CallerAsyncWriterTests {
|
||||
@Test
|
||||
func writeBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter()
|
||||
var data = UniqueArray(capacity: 5, copying: [1, 2, 3, 4, 5])
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 5)
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeEmptyBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter()
|
||||
var data = UniqueArray<Int>()
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 0)
|
||||
}
|
||||
|
||||
@Test
|
||||
func writeLargeBuffer() async {
|
||||
var writer = UniqueArrayCallerAsyncWriter(capacity: 100)
|
||||
var data = UniqueArray(capacity: 5, copying: Array(1...50))
|
||||
|
||||
await writer.write(buffer: &data)
|
||||
|
||||
#expect(writer.storage.count == 50)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,527 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import DequeModule
|
||||
import Testing
|
||||
|
||||
@Suite(.serialized)
|
||||
struct DuplexAsyncChannelTests {
|
||||
// MARK: - Round-trip
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func roundTripForwardDirection() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 10)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerB = readerB
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 5)
|
||||
for v in [1, 2, 3, 4, 5] { buf.append(v) }
|
||||
try await writerA.write(buffer: &buf)
|
||||
|
||||
try await readerB.read { buffer, _ in
|
||||
#expect(buffer.count == 5)
|
||||
var c = buffer.consumeAll()
|
||||
var collected: [Int] = []
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func roundTripReverseDirection() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 10)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 3)
|
||||
for v in [10, 20, 30] { buf.append(v) }
|
||||
try await writerB.write(buffer: &buf)
|
||||
|
||||
try await readerA.read { buffer, _ in
|
||||
#expect(buffer.count == 3)
|
||||
var c = buffer.consumeAll()
|
||||
var collected: [Int] = []
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [10, 20, 30])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func directionsAreIndependent() async throws {
|
||||
// Bytes sent on the forward direction must NOT appear on the side that
|
||||
// sent them.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
var readerB = readerB
|
||||
|
||||
var fwdBuf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
fwdBuf.append(1)
|
||||
try await writerA.write(buffer: &fwdBuf)
|
||||
|
||||
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
revBuf.append(99)
|
||||
try await writerB.write(buffer: &revBuf)
|
||||
|
||||
// readerB sees the forward write.
|
||||
try await readerB.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 1)
|
||||
}
|
||||
|
||||
// readerA sees the reverse write, and only that.
|
||||
try await readerA.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 99)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func concurrentReadsOnBothDirections() async throws {
|
||||
try await withThrowingTaskGroup(of: [Int].self) { group in
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 20)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
var readerB = readerB
|
||||
|
||||
group.addTask {
|
||||
var collected: [Int] = []
|
||||
var done = false
|
||||
while !done {
|
||||
try await readerA.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
if finalElement != nil { done = true }
|
||||
}
|
||||
}
|
||||
return collected
|
||||
}
|
||||
|
||||
// Forward: write 0..<10 from main scope.
|
||||
var fwd = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for i in 0..<10 { fwd.append(i) }
|
||||
try await writerA.write(buffer: &fwd)
|
||||
writerA.finish()
|
||||
|
||||
// Reverse: write 100..<110 from main scope.
|
||||
var rev = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for i in 100..<110 { rev.append(i) }
|
||||
try await writerB.write(buffer: &rev)
|
||||
writerB.finish()
|
||||
|
||||
// Drain forward from the main scope.
|
||||
var forwardCollected: [Int] = []
|
||||
var done = false
|
||||
while !done {
|
||||
try await readerB.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { forwardCollected.append(v) }
|
||||
if finalElement != nil { done = true }
|
||||
}
|
||||
}
|
||||
#expect(forwardCollected == Array(0..<10))
|
||||
|
||||
let reverseCollected = try await group.next() ?? []
|
||||
#expect(reverseCollected == Array(100..<110))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Half-close
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func finishingOneDirectionLeavesTheOtherOpen() async throws {
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
var readerB = readerB
|
||||
|
||||
// Close forward direction.
|
||||
var fwdBuf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
fwdBuf.append(7)
|
||||
try await writerA.write(buffer: &fwdBuf)
|
||||
writerA.finish()
|
||||
|
||||
// Reverse direction still works.
|
||||
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
revBuf.append(8)
|
||||
try await writerB.write(buffer: &revBuf)
|
||||
|
||||
// Forward EOS is fused with the buffered element on the same read.
|
||||
var sawForwardFinal = false
|
||||
try await readerB.read { buffer, finalElement in
|
||||
#expect(buffer.count == 1)
|
||||
if finalElement != nil { sawForwardFinal = true }
|
||||
buffer.removeAll()
|
||||
}
|
||||
#expect(sawForwardFinal)
|
||||
|
||||
// Reverse still delivers elements after forward is closed.
|
||||
try await readerA.read { buffer, finalElement in
|
||||
#expect(buffer.count == 1)
|
||||
#expect(finalElement == nil)
|
||||
buffer.removeAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Final element
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func finalElementDeliveredOnFinish() async throws {
|
||||
try await DuplexAsyncChannel<Int, String, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
withFinalElement: String.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 8)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerB = readerB
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 3)
|
||||
for v in [1, 2, 3] { buf.append(v) }
|
||||
try await writerA.write(buffer: &buf)
|
||||
writerA.finish(finalElement: "trailers")
|
||||
|
||||
var collected: [Int] = []
|
||||
var trailerSeen: String? = nil
|
||||
var done = false
|
||||
while !done {
|
||||
try await readerB.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
if let f = finalElement {
|
||||
trailerSeen = f
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
#expect(collected == [1, 2, 3])
|
||||
#expect(trailerSeen == "trailers")
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Failure isolation
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func failureOnOneDirectionDoesNotPoisonTheOther() async throws {
|
||||
struct TestError: Error, Equatable {}
|
||||
|
||||
try await DuplexAsyncChannel<Int, Void, TestError>.withDuplex(
|
||||
of: Int.self,
|
||||
throwing: TestError.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
var readerB = readerB
|
||||
|
||||
// Send a final element on reverse so we can verify it survives.
|
||||
var revBuf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
revBuf.append(42)
|
||||
try await writerB.write(buffer: &revBuf)
|
||||
writerB.finish()
|
||||
|
||||
// Fail forward direction.
|
||||
writerA.finish(throwing: TestError())
|
||||
|
||||
// readerB sees the forward failure.
|
||||
do {
|
||||
try await readerB.read { _, _ in }
|
||||
Issue.record("expected throw on forward direction")
|
||||
} catch let EitherError<EitherError<TestError, CancellationError>, Never>.first(.first(err)) {
|
||||
#expect(err == TestError())
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
|
||||
// readerA still gets the reverse element + EOS unaffected. The EOS
|
||||
// is fused with the buffered element on the same read.
|
||||
var sawFinal = false
|
||||
try await readerA.read { buffer, finalElement in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 42)
|
||||
if finalElement != nil { sawFinal = true }
|
||||
}
|
||||
#expect(sawFinal)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Backpressure isolation
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func backpressureOnOneDirectionDoesNotBlockTheOther() async throws {
|
||||
// Forward writer is suspended on backpressure (writes more than the
|
||||
// high watermark with no concurrent reader). Reverse must still
|
||||
// accept writes and deliver them while forward is stuck.
|
||||
try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerA = readerA
|
||||
var writerB = writerB
|
||||
var readerB = readerB
|
||||
|
||||
// Forward writer: 4 elements with high=2 → suspends mid-batch.
|
||||
group.addTask {
|
||||
var fwd = UniqueArray<Int>(minimumCapacity: 4)
|
||||
for i in 0..<4 { fwd.append(i) }
|
||||
try await writerA.write(buffer: &fwd)
|
||||
}
|
||||
|
||||
// Even with forward backpressured, reverse fully works.
|
||||
var rev = UniqueArray<Int>(minimumCapacity: 1)
|
||||
rev.append(99)
|
||||
try await writerB.write(buffer: &rev)
|
||||
try await readerA.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
var c = buffer.consumeAll()
|
||||
#expect(c.next() == 99)
|
||||
}
|
||||
|
||||
// Drain forward (4 elements) so the suspended writer task can
|
||||
// complete and we can join it before exiting the scope.
|
||||
var collected: [Int] = []
|
||||
while collected.count < 4 {
|
||||
try await readerB.read { buffer, _ in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
}
|
||||
}
|
||||
#expect(collected == [0, 1, 2, 3])
|
||||
try await group.waitForAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Multi-producer per direction
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func clonedWriterCanProduceConcurrently() async throws {
|
||||
// Two writes happen sequentially through the original writer and its
|
||||
// clone, demonstrating both share the same direction. We can't issue
|
||||
// `finish()` from inside an escaping closure (it consumes the writer),
|
||||
// so we keep the multi-producer demonstration sequential here.
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 50)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerB = readerB
|
||||
_ = readerA
|
||||
_ = writerB
|
||||
|
||||
var clone = writerA.clone()
|
||||
|
||||
var buf1 = UniqueArray<Int>(minimumCapacity: 5)
|
||||
for v in 0..<5 { buf1.append(v) }
|
||||
try await writerA.write(buffer: &buf1)
|
||||
|
||||
var buf2 = UniqueArray<Int>(minimumCapacity: 5)
|
||||
for v in 100..<105 { buf2.append(v) }
|
||||
try await clone.write(buffer: &buf2)
|
||||
|
||||
// Either writer can close the direction independently. The other
|
||||
// writer is still alive but the channel is now finishing.
|
||||
writerA.finish()
|
||||
clone.finish()
|
||||
|
||||
nonisolated(unsafe) var collected = Set<Int>()
|
||||
var done = false
|
||||
while !done {
|
||||
try await readerB.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.insert(v) }
|
||||
if finalElement != nil { done = true }
|
||||
}
|
||||
}
|
||||
#expect(collected == Set([0, 1, 2, 3, 4, 100, 101, 102, 103, 104]))
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Body-error wrapping
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readBodyErrorsWrappedInSecond() async throws {
|
||||
struct BodyError: Error, Equatable {}
|
||||
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerB = readerB
|
||||
_ = readerA
|
||||
_ = writerB
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 1)
|
||||
buf.append(1)
|
||||
try await writerA.write(buffer: &buf)
|
||||
|
||||
do {
|
||||
try await readerB.read { _, _ throws(BodyError) in
|
||||
throw BodyError()
|
||||
}
|
||||
Issue.record("expected throw")
|
||||
} catch let EitherError<EitherError<Never, CancellationError>, BodyError>.second(err) {
|
||||
#expect(err == BodyError())
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Scope cleanup
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func scopeFinalizesBothDirectionsOnReturn() async throws {
|
||||
nonisolated(unsafe) var aTerminated = false
|
||||
nonisolated(unsafe) var bTerminated = false
|
||||
await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
writerA.setOnTerminationCallback { aTerminated = true }
|
||||
writerB.setOnTerminationCallback { bTerminated = true }
|
||||
_ = readerA
|
||||
_ = readerB
|
||||
}
|
||||
#expect(aTerminated)
|
||||
#expect(bTerminated)
|
||||
}
|
||||
|
||||
// MARK: - Protocol conformance
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writerConformsToCallerAsyncWriter() async throws {
|
||||
// Exercise CallerAsyncWriter.finish(buffer:finalElement:) by calling
|
||||
// it through a generic function that only sees the protocol.
|
||||
func finishViaProtocol<W: CallerAsyncWriter & ~Copyable>(
|
||||
_ writer: consuming W,
|
||||
finalElement: consuming W.FinalElement
|
||||
) async throws(W.WriteFailure) where W.WriteElement == Int {
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 3)
|
||||
buf.append(7)
|
||||
buf.append(8)
|
||||
buf.append(9)
|
||||
try await writer.finish(buffer: &buf, finalElement: finalElement)
|
||||
}
|
||||
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 50)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var readerB = readerB
|
||||
_ = readerA
|
||||
_ = writerB
|
||||
|
||||
try await finishViaProtocol(writerA, finalElement: ())
|
||||
|
||||
var collected: [Int] = []
|
||||
var sawFinal = false
|
||||
var done = false
|
||||
while !done {
|
||||
try await readerB.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
if finalElement != nil {
|
||||
sawFinal = true
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
#expect(collected == [7, 8, 9])
|
||||
#expect(sawFinal)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readerConformsToAsyncReader() async throws {
|
||||
// Exercise AsyncReader.read through a generic function that only
|
||||
// sees the protocol.
|
||||
func readOneChunk<R: AsyncReader & ~Copyable & ~Escapable>(
|
||||
_ reader: inout R
|
||||
) async throws -> [Int] where R.ReadElement == Int, R.Buffer == UniqueDeque<Int> {
|
||||
nonisolated(unsafe) var collected: [Int] = []
|
||||
do throws(EitherError<R.ReadFailure, Never>) {
|
||||
try await reader.read { (buffer: inout R.Buffer, _: consuming R.FinalElement?) in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
}
|
||||
} catch {
|
||||
// Swallow read-side errors for the test.
|
||||
}
|
||||
return collected
|
||||
}
|
||||
|
||||
try await DuplexAsyncChannel<Int, Void, Never>.withDuplex(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 10)
|
||||
) { writerA, readerA, writerB, readerB in
|
||||
var writerA = writerA
|
||||
var readerB = readerB
|
||||
_ = readerA
|
||||
_ = writerB
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 3)
|
||||
for v in [11, 22, 33] { buf.append(v) }
|
||||
try await writerA.write(buffer: &buf)
|
||||
|
||||
let collected = try await readOneChunk(&readerB)
|
||||
#expect(collected == [11, 22, 33])
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,68 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import Testing
|
||||
|
||||
@Suite
|
||||
struct EitherErrorTests {
|
||||
enum FirstError: Error, Equatable, Hashable {
|
||||
case one
|
||||
case two
|
||||
}
|
||||
|
||||
enum SecondError: Error, Equatable, Hashable {
|
||||
case alpha
|
||||
case beta
|
||||
}
|
||||
|
||||
@Test
|
||||
func unwrapFirst() throws {
|
||||
let error: EitherError<FirstError, SecondError> = .first(.one)
|
||||
|
||||
#expect(throws: FirstError.one) {
|
||||
try error.unwrap()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func unwrapSecond() throws {
|
||||
let error: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(throws: SecondError.alpha) {
|
||||
try error.unwrap()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func equatable() {
|
||||
let a: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let b: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let c: EitherError<FirstError, SecondError> = .first(.two)
|
||||
let d: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(a == b)
|
||||
#expect(a != c)
|
||||
#expect(a != d)
|
||||
}
|
||||
|
||||
@Test
|
||||
func hashable() {
|
||||
let a: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let b: EitherError<FirstError, SecondError> = .first(.one)
|
||||
let c: EitherError<FirstError, SecondError> = .second(.alpha)
|
||||
|
||||
#expect(a.hashValue == b.hashValue)
|
||||
#expect(a.hashValue != c.hashValue)
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,52 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
import SpanPreview
|
||||
|
||||
extension Array {
|
||||
init(_ span: Span<Element>) {
|
||||
self.init()
|
||||
for index in span.indices {
|
||||
self.append(span[index])
|
||||
}
|
||||
}
|
||||
|
||||
init(_ inputSpan: borrowing InputSpan<Element>) {
|
||||
self.init()
|
||||
for index in inputSpan.indices {
|
||||
self.append(inputSpan[index])
|
||||
}
|
||||
}
|
||||
|
||||
init<C: RangeReplaceableContainer<Element> & ~Copyable & ~Escapable>(draining container: inout C) {
|
||||
self.init()
|
||||
var consumer = container.consumeAll()
|
||||
while let value = consumer.next() {
|
||||
self.append(value)
|
||||
}
|
||||
}
|
||||
|
||||
mutating func append(span: Span<Element>) {
|
||||
for index in span.indices {
|
||||
self.append(span[index])
|
||||
}
|
||||
}
|
||||
|
||||
mutating func append(inputSpan: borrowing InputSpan<Element>) {
|
||||
for index in inputSpan.indices {
|
||||
self.append(inputSpan[index])
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,40 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
struct UniqueArrayAsyncReader: ~Copyable, AsyncReader {
|
||||
typealias ReadElement = Int
|
||||
typealias Buffer = UniqueArray<Int>
|
||||
typealias ReadFailure = Never
|
||||
typealias FinalElement = Void
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
var didEmitFinal: Bool = false
|
||||
|
||||
mutating func read<Return: ~Copyable, Failure: Error>(
|
||||
body: (inout UniqueArray<Int>, Void?) async throws(Failure) -> Return
|
||||
) async throws(EitherError<Never, Failure>) -> Return {
|
||||
precondition(!self.didEmitFinal, "read called after end-of-stream")
|
||||
self.didEmitFinal = true
|
||||
do {
|
||||
var uniqueArray = self.storage.clone()
|
||||
self.storage = .init()
|
||||
return try await body(&uniqueArray, .some(()))
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,49 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
struct UniqueArrayAsyncWriter: ~Copyable, AsyncWriter {
|
||||
typealias WriteElement = Int
|
||||
typealias Buffer = UniqueArray<Int>
|
||||
typealias WriteFailure = Never
|
||||
typealias FinalElement = Void
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
var didFinish: Bool = false
|
||||
|
||||
init(capacity: Int = 100) {
|
||||
self.storage = UniqueArray(minimumCapacity: capacity)
|
||||
}
|
||||
|
||||
mutating func write<Return: ~Copyable, Failure: Error>(
|
||||
_ body: (inout UniqueArray<Int>) async throws(Failure) -> Return
|
||||
) async throws(EitherError<Never, Failure>) -> Return {
|
||||
var buffer = UniqueArray<Int>(minimumCapacity: 64)
|
||||
do {
|
||||
let result = try await body(&buffer)
|
||||
self.storage.append(copying: buffer)
|
||||
return result
|
||||
} catch {
|
||||
throw .second(error)
|
||||
}
|
||||
}
|
||||
|
||||
consuming func finish(
|
||||
finalElement: consuming Void
|
||||
) async throws(Never) {
|
||||
self.didFinish = true
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,42 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
struct UniqueArrayCallerAsyncReader: ~Copyable, CallerAsyncReader {
|
||||
typealias ReadElement = Int
|
||||
typealias ReadFailure = Never
|
||||
typealias FinalElement = Void
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
var position: Int = 0
|
||||
var didEmitFinal: Bool = false
|
||||
|
||||
mutating func read<Buffer: RangeReplaceableContainer<ReadElement> & ~Copyable>(
|
||||
into buffer: inout Buffer
|
||||
) async throws(ReadFailure) -> Void? where Buffer.Element: ~Copyable {
|
||||
precondition(!self.didEmitFinal, "read called after end-of-stream")
|
||||
let count = min(buffer.freeCapacity, storage.count - position)
|
||||
for i in 0..<count {
|
||||
buffer.append(storage[position + i])
|
||||
}
|
||||
position += count
|
||||
if position >= storage.count {
|
||||
self.didEmitFinal = true
|
||||
return .some(())
|
||||
}
|
||||
return nil
|
||||
}
|
||||
}
|
||||
#endif
|
||||
@@ -0,0 +1,53 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
|
||||
struct WriterCapacityError: Error {}
|
||||
|
||||
struct UniqueArrayCallerAsyncWriter: ~Copyable, CallerAsyncWriter {
|
||||
typealias WriteElement = Int
|
||||
typealias WriteFailure = Never
|
||||
typealias FinalElement = Void
|
||||
|
||||
var storage: UniqueArray<Int>
|
||||
var didFinish: Bool = false
|
||||
|
||||
init(capacity: Int = 100) {
|
||||
self.storage = UniqueArray(minimumCapacity: capacity)
|
||||
}
|
||||
|
||||
mutating func write<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
|
||||
self.storage.reserveCapacity(buffer.count)
|
||||
var consumer = buffer.consumeAll()
|
||||
while let element = consumer.next() {
|
||||
self.storage.append(element)
|
||||
}
|
||||
}
|
||||
|
||||
consuming func finish<Buffer: RangeReplaceableContainer<WriteElement> & ~Copyable>(
|
||||
buffer: inout Buffer,
|
||||
finalElement: consuming Void
|
||||
) async throws(WriteFailure) where Buffer.Element: ~Copyable {
|
||||
self.storage.reserveCapacity(buffer.count)
|
||||
var consumer = buffer.consumeAll()
|
||||
while let element = consumer.next() {
|
||||
self.storage.append(element)
|
||||
}
|
||||
self.didFinish = true
|
||||
}
|
||||
}
|
||||
#endif
|
||||
+600
@@ -0,0 +1,600 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if UnstableAsyncStreaming && compiler(>=6.4)
|
||||
|
||||
import AsyncStreaming
|
||||
import BasicContainers
|
||||
import ContainersPreview
|
||||
import DequeModule
|
||||
import Testing
|
||||
|
||||
private struct MultiProducerSingleConsumerAsyncChannelTestError: Error {}
|
||||
|
||||
@Suite(.serialized)
|
||||
struct MultiProducerSingleConsumerAsyncChannelTests {
|
||||
// MARK: - AsyncReader.read
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readReturnsAllBufferedElementsInOrder() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 10)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
|
||||
for v in [1, 2, 3, 4, 5] { writeBuffer.append(v) }
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 5)
|
||||
var consumer = buffer.consumeAll()
|
||||
var actual: [Int] = []
|
||||
while let v = consumer.next() { actual.append(v) }
|
||||
#expect(actual == [1, 2, 3, 4, 5])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readSuspendsUntilElementArrives() async throws {
|
||||
try await withThrowingTaskGroup(of: [Int].self) { group in
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
group.addTask {
|
||||
var collected: [Int] = []
|
||||
try await channel.read { buffer, _ in
|
||||
var consumer = buffer.consumeAll()
|
||||
while let v = consumer.next() { collected.append(v) }
|
||||
}
|
||||
return collected
|
||||
}
|
||||
try await Task.sleep(nanoseconds: 10_000_000)
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
|
||||
writeBuffer.append(42)
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
let result = try await group.next()
|
||||
#expect(result == [42])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readThrowsCancellationWhenTaskStartsCancelled() async {
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.cancelAll()
|
||||
// A child added to an already-cancelled group starts cancelled, so the
|
||||
// cancellation handler runs before the reader continuation is installed.
|
||||
group.addTask {
|
||||
await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
_ = consume source
|
||||
|
||||
do {
|
||||
_ = try await channel.read { _, _ in
|
||||
Issue.record("read body must not run after cancellation")
|
||||
}
|
||||
Issue.record("expected CancellationError")
|
||||
} catch let EitherError<EitherError<Never, CancellationError>, Never>.first(.second(error)) {
|
||||
_ = error
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
}
|
||||
await group.waitForAll()
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readDoesNotThrowCancellationWhenSourceFinishes() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
let source = source
|
||||
source.finish()
|
||||
|
||||
var sawFinalElement = false
|
||||
try await channel.read { buffer, finalElement in
|
||||
#expect(buffer.count == 0)
|
||||
sawFinalElement = finalElement != nil
|
||||
}
|
||||
#expect(sawFinalElement)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readAfterCancellationPreconditions() async {
|
||||
await #expect(processExitsWith: .failure) {
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.cancelAll()
|
||||
group.addTask {
|
||||
await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
_ = consume source
|
||||
|
||||
try? await channel.read { _, _ in }
|
||||
try? await channel.read { _, _ in }
|
||||
}
|
||||
}
|
||||
await group.waitForAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readAfterFinalElementPreconditions() async {
|
||||
await #expect(processExitsWith: .failure) {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
let source = source
|
||||
source.finish()
|
||||
|
||||
try await channel.read { _, finalElement in
|
||||
#expect(finalElement != nil)
|
||||
}
|
||||
try await channel.read { _, _ in }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readAfterFailurePreconditions() async {
|
||||
await #expect(processExitsWith: .failure) {
|
||||
await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
throwing: MultiProducerSingleConsumerAsyncChannelTestError.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
let source = source
|
||||
source.finish(throwing: MultiProducerSingleConsumerAsyncChannelTestError())
|
||||
|
||||
try? await channel.read { _, _ in }
|
||||
try? await channel.read { _, _ in }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readReturnsEmptyBufferAndFinalElementOnEOSAfterFinish() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
|
||||
writeBuffer.append(1)
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
|
||||
try await channel.read { buffer, finalElement in
|
||||
#expect(buffer.count == 1)
|
||||
#expect(finalElement == nil)
|
||||
buffer.removeAll()
|
||||
}
|
||||
source.finish()
|
||||
|
||||
try await channel.read { buffer, finalElement in
|
||||
#expect(buffer.count == 0)
|
||||
#expect(finalElement != nil)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readThrowsFailureAfterFinishWithError() async throws {
|
||||
struct TestError: Error, Equatable {}
|
||||
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
throwing: TestError.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
|
||||
writeBuffer.append(1)
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
source.finish(throwing: TestError())
|
||||
|
||||
// First read still delivers the buffered element.
|
||||
try? await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
buffer.removeAll()
|
||||
}
|
||||
// Second read throws the queued failure through EitherError.first.
|
||||
do {
|
||||
try await channel.read { _, _ in }
|
||||
Issue.record("expected throw")
|
||||
} catch let EitherError<EitherError<TestError, CancellationError>, Never>.first(.first(err)) {
|
||||
#expect(err == TestError())
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readBodyErrorsWrappedInSecond() async throws {
|
||||
struct BodyError: Error, Equatable {}
|
||||
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
|
||||
writeBuffer.append(1)
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
|
||||
do {
|
||||
try await channel.read { _, _ throws(BodyError) in
|
||||
throw BodyError()
|
||||
}
|
||||
Issue.record("expected throw")
|
||||
} catch let EitherError<EitherError<Never, CancellationError>, BodyError>.second(err) {
|
||||
#expect(err == BodyError())
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readPartialConsumptionRemainsVisibleOnNextRead() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 10)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
|
||||
for v in [1, 2, 3, 4, 5] { writeBuffer.append(v) }
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
|
||||
try await channel.read { buffer, _ in
|
||||
var consumer = buffer.consumeFirst(2)
|
||||
#expect(consumer.next() == 1)
|
||||
#expect(consumer.next() == 2)
|
||||
}
|
||||
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 3)
|
||||
var consumer = buffer.consumeAll()
|
||||
var collected: [Int] = []
|
||||
while let v = consumer.next() { collected.append(v) }
|
||||
#expect(collected == [3, 4, 5])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readResumesSuspendedProducersWhenWaterLevelDrops() async throws {
|
||||
try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
group.addTask {
|
||||
// Fill to exactly the high watermark - this write suspends.
|
||||
var firstBatch = UniqueArray<Int>(minimumCapacity: 4)
|
||||
for v in [1, 2, 3, 4] { firstBatch.append(v) }
|
||||
try await source.write(buffer: &firstBatch)
|
||||
// Then send the 5th element once backpressure is relieved.
|
||||
var secondBatch = UniqueArray<Int>(minimumCapacity: 1)
|
||||
secondBatch.append(5)
|
||||
try await source.write(buffer: &secondBatch)
|
||||
}
|
||||
|
||||
// Wait until the producer suspends after appending the first batch.
|
||||
try await Task.sleep(nanoseconds: 10_000_000)
|
||||
// Drain the buffered elements - the water level drops below the low
|
||||
// watermark and wakes the producer.
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 4)
|
||||
buffer.removeAll()
|
||||
}
|
||||
try await group.next()
|
||||
// The 5th element produced after the producer resumed.
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 1)
|
||||
buffer.removeAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readWaterLevelForElementCalledPerElementInBatch() async throws {
|
||||
nonisolated(unsafe) var callCount = 0
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(
|
||||
low: 5,
|
||||
high: 100,
|
||||
waterLevelForElement: { _ in
|
||||
callCount += 1
|
||||
return 1
|
||||
}
|
||||
)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 4)
|
||||
for v in [1, 2, 3, 4] { writeBuffer.append(v) }
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
let afterSend = callCount
|
||||
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 4)
|
||||
buffer.removeAll()
|
||||
}
|
||||
// Called once per element on send, once per element on consume.
|
||||
#expect(afterSend == 4)
|
||||
#expect(callCount == 8)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readBufferIsReusedAcrossReads() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 100)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
// The channel alternates two internal buffers across reads (swap
|
||||
// design): on each read the producer-side buffer is handed to the
|
||||
// reader and the previously-handed-back buffer becomes the new
|
||||
// producer-side. Verify that two reads of the same size land on
|
||||
// matching capacities, i.e. the channel is reusing storage rather than
|
||||
// allocating a fresh buffer per read.
|
||||
var firstBatch = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for v in 0..<10 { firstBatch.append(v) }
|
||||
try await source.write(buffer: &firstBatch)
|
||||
nonisolated(unsafe) var firstCapacity = 0
|
||||
try await channel.read { buffer, _ in
|
||||
firstCapacity = buffer.capacity
|
||||
var c = buffer.consumeAll()
|
||||
while c.next() != nil {}
|
||||
}
|
||||
#expect(firstCapacity >= 10)
|
||||
|
||||
// Second read of the same size lands on the alternate buffer; after
|
||||
// the first round trip both buffers have grown to at least the
|
||||
// workload's capacity, so this read should see at least as much.
|
||||
var secondBatch = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for v in 0..<10 { secondBatch.append(v) }
|
||||
try await source.write(buffer: &secondBatch)
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.capacity >= firstCapacity)
|
||||
var c = buffer.consumeAll()
|
||||
while c.next() != nil {}
|
||||
}
|
||||
|
||||
// A third read of the same size should reuse the original buffer
|
||||
// (capacity matches first read's exactly).
|
||||
var thirdBatch = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for v in 0..<10 { thirdBatch.append(v) }
|
||||
try await source.write(buffer: &thirdBatch)
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.capacity == firstCapacity)
|
||||
var c = buffer.consumeAll()
|
||||
while c.next() != nil {}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func readDeliversFinalElementOnFinish() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 8)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 3)
|
||||
for v in [1, 2, 3] { writeBuffer.append(v) }
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
source.finish()
|
||||
|
||||
nonisolated(unsafe) var collected: [Int] = []
|
||||
var sawFinal = false
|
||||
var done = false
|
||||
while !done {
|
||||
try await channel.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
if finalElement != nil {
|
||||
sawFinal = true
|
||||
done = true
|
||||
}
|
||||
}
|
||||
}
|
||||
#expect(collected == [1, 2, 3])
|
||||
#expect(sawFinal)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - CallerAsyncWriter.write
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeAppendsAllElementsAndClearsBuffer() async throws {
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 5, high: 100)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 5)
|
||||
writeBuffer.append(10)
|
||||
writeBuffer.append(20)
|
||||
writeBuffer.append(30)
|
||||
|
||||
try await source.write(buffer: &writeBuffer)
|
||||
#expect(writeBuffer.count == 0, "write should drain the caller's buffer")
|
||||
|
||||
try await channel.read { buffer, _ in
|
||||
#expect(buffer.count == 3)
|
||||
var c = buffer.consumeAll()
|
||||
var collected: [Int] = []
|
||||
while let v = c.next() { collected.append(v) }
|
||||
#expect(collected == [10, 20, 30])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeAfterFinishThrows() async throws {
|
||||
await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 4)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
// Keep an additional source around so we can attempt a write after the
|
||||
// channel has been finished by consuming the first source.
|
||||
var extraSource = source.clone()
|
||||
source.finish()
|
||||
|
||||
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
|
||||
writeBuffer.append(1)
|
||||
|
||||
do {
|
||||
try await extraSource.write(buffer: &writeBuffer)
|
||||
Issue.record("expected throw")
|
||||
} catch is MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError {
|
||||
// expected
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
|
||||
// Drain anything still buffered before exiting the scope.
|
||||
try? await channel.read { _, _ in }
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeSuspendsOnBackpressureAndResumesAfterRead() async throws {
|
||||
try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 1, high: 2)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
group.addTask {
|
||||
// Reader drains until it observes the final element.
|
||||
while true {
|
||||
var done = false
|
||||
try await channel.read { buffer, finalElement in
|
||||
buffer.removeAll()
|
||||
done = finalElement != nil
|
||||
}
|
||||
if done { break }
|
||||
}
|
||||
}
|
||||
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 4)
|
||||
for i in 0..<4 { buf.append(i) }
|
||||
try await source.write(buffer: &buf)
|
||||
source.finish()
|
||||
try await group.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
|
||||
@Test
|
||||
func writeReadRoundtripPreservesOrder() async throws {
|
||||
let total = 100
|
||||
try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 10, high: 50)
|
||||
) { channel, source in
|
||||
var channel = channel
|
||||
var source = source
|
||||
|
||||
group.addTask {
|
||||
nonisolated(unsafe) var collected: [Int] = []
|
||||
var done = false
|
||||
while !done {
|
||||
try await channel.read { buffer, finalElement in
|
||||
var c = buffer.consumeAll()
|
||||
while let v = c.next() { collected.append(v) }
|
||||
done = finalElement != nil
|
||||
}
|
||||
}
|
||||
#expect(collected == Array(0..<total))
|
||||
}
|
||||
for start in stride(from: 0, to: total, by: 10) {
|
||||
var buf = UniqueArray<Int>(minimumCapacity: 10)
|
||||
for i in start..<(start + 10) { buf.append(i) }
|
||||
try await source.write(buffer: &buf)
|
||||
}
|
||||
source.finish()
|
||||
try await group.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
#endif
|
||||
Reference in new issue
Block a user