mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
4c3ea81f81 | ||
|
|
5c8bd186f4 | ||
|
|
2503842d68 | ||
|
|
e83857ca55 | ||
|
|
6ae9a051f7 | ||
|
|
46b4464735 | ||
|
|
d162617838 | ||
|
|
14729ea7f9 | ||
|
|
da4e36f865 | ||
|
|
5bbdcc1d37 | ||
|
|
cb417003f9 | ||
|
|
8cfdf03b51 | ||
|
|
6360ca0344 | ||
|
|
0a3866daec | ||
|
|
260e198221 | ||
|
|
f56556930f | ||
|
|
220f86f792 | ||
|
|
c889832c64 | ||
|
|
6dfbfd5e49 | ||
|
|
281e27c5d0 | ||
|
|
4a1fb99f00 | ||
|
|
b0ec4694d2 | ||
|
|
e639e5c889 | ||
|
|
7ac31f979f | ||
|
|
f5d5fb6483 | ||
|
|
df46b4c235 | ||
|
|
07a0c1ee08 | ||
|
|
adb12bfccc | ||
|
|
2ace7010e9 | ||
|
|
a42b72ad84 | ||
|
|
156bb4bf49 | ||
|
|
936a68d012 | ||
|
|
92747901e0 | ||
|
|
ac9309b2ac | ||
|
|
b3394663fd | ||
|
|
0c00af2372 | ||
|
|
9d83fff5b8 | ||
|
|
e6b21d2a6d | ||
|
|
7e45005473 | ||
|
|
ffa6ee9f0b | ||
|
|
9cfed92b02 | ||
|
|
ca2ac60495 | ||
|
|
bf0ec24bde | ||
|
|
0ebc8058fc | ||
|
|
a07a3f41b5 | ||
|
|
e7b9b6039d | ||
|
|
3f12423c47 | ||
|
|
aed5422380 | ||
|
|
b6dff00602 | ||
|
|
4ba079747d | ||
|
|
7586d2060f | ||
|
|
fb15375758 | ||
|
|
5656338b5d | ||
|
|
9abd029409 | ||
|
|
dd97b564ae | ||
|
|
0174f58455 | ||
|
|
ae26222e86 | ||
|
|
ed0b086089 | ||
|
|
8f5e8cee42 | ||
|
|
6c6ed33514 | ||
|
|
2cfb16691a | ||
|
|
cc0621eb1b | ||
|
|
f32328ac6f | ||
|
|
3890885e80 | ||
|
|
cf70e78632 | ||
|
|
be681c12e3 | ||
|
|
c21ee2d706 | ||
|
|
aedcb785a4 | ||
|
|
9d427ce159 | ||
|
|
081ca79161 | ||
|
|
76b27aebef | ||
|
|
1bd073999c | ||
|
|
314b10c634 | ||
|
|
4feeb83d13 | ||
|
|
af9ce91db4 | ||
|
|
f05e450f0b | ||
|
|
2b5fbf3c91 | ||
|
|
68c8dc285b | ||
|
|
cba18c3f88 | ||
|
|
c0fdfdb8aa | ||
|
|
e3a18a0353 | ||
|
|
b92ba058d8 | ||
|
|
f44d02eb26 | ||
|
|
57072e617a | ||
|
|
45aa5b950c | ||
|
|
6ff1f1b411 | ||
|
|
2a211e18be | ||
|
|
9baff2ad3d | ||
|
|
6df7fcdd10 | ||
|
|
8a355f015f | ||
|
|
816cf644af | ||
|
|
cca423ff03 | ||
|
|
9a3e94d440 | ||
|
|
07b8d74cc7 | ||
|
|
434591a571 | ||
|
|
6e9a5757bc | ||
|
|
a973b06d06 | ||
|
|
6b59cfb8d0 | ||
|
|
d185b2068b | ||
|
|
bbbe08d331 | ||
|
|
6d5d6319f4 | ||
|
|
047ab6abef | ||
|
|
d2164b9ef6 | ||
|
|
b3d4ffb94c | ||
|
|
5b78eaf423 | ||
|
|
a3576e669b | ||
|
|
94a7ecec28 | ||
|
|
6a8aec2a1f | ||
|
|
9d03d90a13 | ||
|
|
c174e4603e | ||
|
|
b6755e6313 | ||
|
|
18749897a8 | ||
|
|
6971c8fc67 | ||
|
|
f1581d0973 | ||
|
|
442d20e8c8 | ||
|
|
b8a8d5d2ae | ||
|
|
b136d48e7f | ||
|
|
4b5a3ef050 | ||
|
|
9ce65b089c | ||
|
|
fac138c517 | ||
|
|
a8bba84598 | ||
|
|
739815f65d | ||
|
|
0dfb244b1b | ||
|
|
f9369af30c | ||
|
|
1656fd8839 | ||
|
|
db847ef410 | ||
|
|
21f20e9030 | ||
|
|
df97fdaced | ||
|
|
98d4229317 | ||
|
|
f9d0911c0c | ||
|
|
33494899af | ||
|
|
718d647945 | ||
|
|
d4bdb34283 | ||
|
|
11d7cfe1c9 | ||
|
|
b11a32fe4e | ||
|
|
f560d1c61f | ||
|
|
7f3df92863 | ||
|
|
bcd0ee1e50 | ||
|
|
37ad908591 | ||
|
|
b8b04919e4 | ||
|
|
4d4022e91b | ||
|
|
e87e9ddd02 | ||
|
|
3447a342ac | ||
|
|
5ac8bb4d07 | ||
|
|
571bfd1a60 | ||
|
|
822ca9365c | ||
|
|
ed1d2a04cf | ||
|
|
7545f0b7d2 | ||
|
|
9d46190d67 | ||
|
|
6ba2c05cfa | ||
|
|
f0f348a680 | ||
|
|
de73225ecc | ||
|
|
0fda7f3e0b | ||
|
|
09803ec7f9 | ||
|
|
8ae8027341 | ||
|
|
307118031e | ||
|
|
4b11faad62 | ||
|
|
624eea0387 | ||
|
|
fee904ba10 | ||
|
|
a52b55c8ac | ||
|
|
2722655bdb | ||
|
|
625ac79d5f | ||
|
|
325923a5e6 | ||
|
|
61bc878106 | ||
|
|
9377b4de58 | ||
|
|
d90945abc8 | ||
|
|
7b62584d99 | ||
|
|
2683ddc9c3 | ||
|
|
b8242c4a6b | ||
|
|
eb0ddf54cc | ||
|
|
4c35512ba6 | ||
|
|
7969001299 | ||
|
|
a6ad9b82e9 | ||
|
|
5bfab6f07a | ||
|
|
17bca92f90 | ||
|
|
aebc7af342 | ||
|
|
46b3bb088b | ||
|
|
d96606e7f7 | ||
|
|
303e6a9b15 | ||
|
|
f20f7fbe85 | ||
|
|
47aa4ccba6 | ||
|
|
f91de2e1f3 | ||
|
|
2de7a14d32 | ||
|
|
c2c73ecffe | ||
|
|
5c34eadcc0 | ||
|
|
aed374f1f6 | ||
|
|
d905d2a465 | ||
|
|
0e37dffc8c | ||
|
|
845d11a3bd | ||
|
|
c147131251 | ||
|
|
a4d279df70 | ||
|
|
1dbed37b56 | ||
|
|
91aa4a85d4 | ||
|
|
7e3b1c1164 | ||
|
|
91968fa3e9 | ||
|
|
18fcfe8e29 | ||
|
|
27e6645329 | ||
|
|
ad2d2fca7e | ||
|
|
4c93fa2c87 | ||
|
|
21520e710c | ||
|
|
b015c5e49e | ||
|
|
76785b34e4 | ||
|
|
8c93e6ba6c | ||
|
|
34682caadf | ||
|
|
3883a4033b | ||
|
|
b515cd8458 | ||
|
|
f614b51e55 | ||
|
|
431393dc68 | ||
|
|
93b868b59a | ||
|
|
450f2d6827 | ||
|
|
8295e01ac8 | ||
|
|
205414d19d | ||
|
|
0316ac34f3 | ||
|
|
d1a8f225eb | ||
|
|
73b29b9cbf | ||
|
|
402f59efb4 | ||
|
|
e71fe66e29 | ||
|
|
8419f51fa6 | ||
|
|
e7dc87d00c | ||
|
|
8a1078810c | ||
|
|
b2aad0be7d | ||
|
|
beb509d829 | ||
|
|
1c11d4a7c8 | ||
|
|
1c08de7680 | ||
|
|
2b4f602320 | ||
|
|
361c7926d1 | ||
|
|
7f073235cb | ||
|
|
4c0a02a63c | ||
|
|
d1155eca5c |
No files matched your search
+11
@@ -0,0 +1,11 @@
|
||||
.DS_Store
|
||||
/.build
|
||||
/Packages
|
||||
/*.xcodeproj
|
||||
xcuserdata/
|
||||
DerivedData/
|
||||
.swiftpm/config/registries.json
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
.swiftpm
|
||||
Package.resolved
|
||||
@@ -0,0 +1,5 @@
|
||||
version: 1
|
||||
builder:
|
||||
configs:
|
||||
- documentation_targets: [AsyncAlgorithms]
|
||||
swift_version: 5.8
|
||||
@@ -0,0 +1,25 @@
|
||||
# file options
|
||||
|
||||
--swiftversion 5.7
|
||||
--exclude .build
|
||||
|
||||
# format options
|
||||
|
||||
--self insert
|
||||
--patternlet inline
|
||||
--ranges nospace
|
||||
--stripunusedargs unnamed-only
|
||||
--ifdef no-indent
|
||||
--extensionacl on-declarations
|
||||
--disable typeSugar # https://github.com/nicklockwood/SwiftFormat/issues/636
|
||||
--disable andOperator
|
||||
--disable wrapMultilineStatementBraces
|
||||
--disable enumNamespaces
|
||||
--disable redundantExtensionACL
|
||||
--disable redundantReturn
|
||||
--disable preferKeyPath
|
||||
--disable sortedSwitchCases
|
||||
--disable hoistAwait
|
||||
--disable hoistTry
|
||||
|
||||
# rules
|
||||
@@ -0,0 +1,5 @@
|
||||
# Code of Conduct
|
||||
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
|
||||
<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
|
||||
@@ -0,0 +1,10 @@
|
||||
By submitting a pull request, you represent that you have the right to license
|
||||
your contribution to Apple and the community, and agree by submitting the patch
|
||||
that your contributions are licensed under the [Swift
|
||||
license](https://swift.org/LICENSE.txt).
|
||||
|
||||
---
|
||||
|
||||
Before submitting the pull request, please make sure you have tested your
|
||||
changes and that they follow the Swift project [guidelines for contributing
|
||||
code](https://swift.org/contributing/#contributing-code).
|
||||
@@ -0,0 +1,67 @@
|
||||
# Feature name
|
||||
|
||||
* Proposal: [NNNN](NNNN-filename.md)
|
||||
* Authors: [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
|
||||
* Review Manager: TBD
|
||||
* Status: **Awaiting implementation**
|
||||
|
||||
*During the review process, add the following fields as needed:*
|
||||
|
||||
* Implementation: [apple/swift-async-algorithms#NNNNN](https://github.com/apple/swift-async-algorithms/pull/NNNNN)
|
||||
* Decision Notes: [Rationale](https://forums.swift.org/), [Additional Commentary](https://forums.swift.org/)
|
||||
* Bugs: [NNNN](https://github.com/apple/swift-async-algorithms/issues)
|
||||
|
||||
## Introduction
|
||||
|
||||
A short description of what the feature is. Try to keep it to a
|
||||
single-paragraph "elevator pitch" so the reader understands what
|
||||
problem this proposal is addressing.
|
||||
|
||||
Swift forums thread: [Discussion thread topic for that proposal](https://forums.swift.org/)
|
||||
|
||||
## Motivation
|
||||
|
||||
Describe the problems that this proposal seeks to address. If the
|
||||
problem is that some common pattern is currently hard to express, show
|
||||
how one can currently get a similar effect and describe its
|
||||
drawbacks. If it's completely new functionality that cannot be
|
||||
emulated, motivate why this new functionality would help Swift
|
||||
developers create better Swift code.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
Describe your solution to the problem. Provide examples and describe
|
||||
how they work. Show how your solution is better than current
|
||||
workarounds: is it cleaner, safer, or more efficient?
|
||||
|
||||
## Detailed design
|
||||
|
||||
Describe the design of the solution in detail. If it involves new
|
||||
syntax in the language, show the additions and changes to the Swift
|
||||
grammar. If it's a new API, show the full API and its documentation
|
||||
comments detailing what it does. The detail in this section should be
|
||||
sufficient for someone who is *not* one of the authors to be able to
|
||||
reasonably implement the feature.
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
API resilience describes the changes one can make to a public API
|
||||
without breaking its ABI. Does this proposal introduce features that
|
||||
would become part of a public API? If so, what kinds of changes can be
|
||||
made without breaking ABI? Can this feature be added/removed without
|
||||
breaking ABI? For more information about the resilience model, see the
|
||||
[library evolution
|
||||
document](https://github.com/apple/swift/blob/master/docs/LibraryEvolution.rst)
|
||||
in the Swift repository.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
Describe alternative approaches to addressing the same problem, and
|
||||
why you chose this approach instead.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
If significant changes or improvements suggested by members of the
|
||||
community were incorporated into the proposal as it developed, take a
|
||||
moment here to thank them for their contributions. Swift evolution is a
|
||||
collaborative process, and everyone's input should receive recognition!
|
||||
@@ -0,0 +1,108 @@
|
||||
# Zip
|
||||
|
||||
* Proposal: [SAA-0001](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0001-zip.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestZip.swift)]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
The swift standard library has a function that allows for the combining of two sequences into one sequence of tuples of the elements of the base sequences. This concept can be achieved for `AsyncSequence` with the iteration being asynchronous but also each side being concurrently iterated while still rethrowing potential failures. This proposal covers that parity between `AsyncSequence` and `Sequence`. It is often times useful to describe asynchronous sequences of events as paired occurrences. The fundamental algorithm for this is zip.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Zip combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines
|
||||
let nasdaqFeed = URL(string: "http://www.example.com/ticker?symbol=^IXIC")!.lines
|
||||
|
||||
for try await (apple, nasdaq) in zip(appleFeed, nasdaqFeed) {
|
||||
print("APPL: \(apple) NASDAQ: \(nasdaq)")
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following zipped events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | combined output |
|
||||
| ----------- | --------- | ---------- | ----------------------------- |
|
||||
| 11:40 AM | 173.91 | | |
|
||||
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncZip2Sequence<Base1, Base2>
|
||||
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncZip3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `zip(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncZipSequence` which is an asynchronous sequence.
|
||||
|
||||
Each iteration of an `AsyncZipSequence` will await for all base iterators to produce a value. This iteration will be done concurrently to produce a singular tuple result. If any of the base iterations terminates by returning `nil` from its iteration, the `AsyncZipSequence` iteration is immediately considered unsatisfiable and returns `nil` and all iterations of other bases will be cancelled. If any iteration of the bases throws an error, then the other iterations concurrently running are cancelled and the produced error is rethrown, terminating the iteration.
|
||||
|
||||
`AsyncZipSequence` requires that the iterations are done concurrently. This means that the base sequences, their elements, and iterators must all be `Sendable`. That makes `AsyncZipSequence` inherently `Sendable`.
|
||||
|
||||
The source of throwing of `AsyncZipSequence` is determined by its bases. That means that if any base can throw an error then the iteration of the `AsyncZipSequence` can throw. If no bases can throw, then the `AsyncZipSequence` does not throw.
|
||||
|
||||
### Naming
|
||||
|
||||
The `zip(_:...)` function takes its name from the Swift standard library function of the same name. The `AsyncZipSequence` family of types take their name from the same family from the standard library for the type returned by `zip(_:_:)`. The one difference is that this asynchronous version allows for the affordance of recognizing the eventual variadic generic need of expanding a zip of more than just two sources.
|
||||
|
||||
It is common in some libraries to have a `ZipMap` or some other combination of `zip` and `map`. This is a common usage pattern, but leaving a singular type for composition feels considerably more approachable.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
**Swift** The swift standard library has an [API definition of zip](https://developer.apple.com/documentation/swift/1541125-zip) as a top level function for combining two sequences.
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of Zip](https://reactivex.io/documentation/operators/zip.html) as a top level function for combining Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of zip](https://developer.apple.com/documentation/combine/publisher/zip(_:)/) as an operator style method for combining Publishers.
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
### `@frozen` and `@inlinable`
|
||||
|
||||
These types utilize rethrowing mechanisms that are awaiting an implementation in the compiler for supporting implementation based rethrows. So none of them are marked as frozen or marked as inlinable. This feature (discussed as `rethrows(unsafe)` or `rethrows(SourceOfRethrowyness)` has not yet been reviewed or implemented. The current implementation takes liberties with an internal protocol to accomplish this task. Future revisions will remove that protocol trick to replace it with proper rethrows semantics at the actual call site. The types are expected to be stable boundaries to prevent that workaround for the compilers yet to be supported rethrowing (or TaskGroup rethrowing) mechanisms. As soon as that feature is resolved; a more detailed investigation on performance impact of inlining and frozen should be done before 1.0.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
It was considered to have zip be shaped as an extension method on `AsyncSequence` however that infers a "primary-ness" of one `AsyncSequence` over another. Since the standard library spells this as a global function (which infers no preference to one side or another) it was decided that having symmetry between the asynchronous version and the synchronous version inferred the right connotations.
|
||||
|
||||
There are other methods with similar behavior that could be controlled by options passed in. This concept has merit but was initially disregarded since that would complicate the interface. Design-wise this is still an open question if having a "zip-behavior-options" parameter to encompass combining the latest values or zipping based upon a preference to a "primary" side or not is meaningful.
|
||||
|
||||
It is common to have a zip+map to create structures instead of tuples, however that was disregarded since that concept could easily be expressed by composing zip and map.
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# Merge
|
||||
|
||||
* Proposal: [SAA-0002](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0002-merge.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestMerge.swift)]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
In the category of combinations of asynchronous sequences there are a few different potential behaviors. This category all take two or more `AsyncSequence` types and produce one `AsyncSequence`. One fundamental behavior is taking all values produced by the inputs and resuming the iteration of the singular downstream `AsyncSequence` with those values. This shape is called merge.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Merge takes two or more asynchronous sequences sharing the same element type and combines them into one singular asynchronous sequence of those elements.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines.map { "AAPL: " + $0 }
|
||||
let nasdaqFeed = URL(string:"http://www.example.com/ticker?symbol=^IXIC")!.lines.map { "^IXIC: " + $0 }
|
||||
|
||||
for try await ticker in merge(appleFeed, nasdaqFeed) {
|
||||
print(ticker)
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following merged events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | merged output |
|
||||
| ----------- | --------- | ---------- | --------------- |
|
||||
| 11:40 AM | 173.91 | | AAPL: 173.91 |
|
||||
| 12:25 AM | | 14236.78 | ^IXIC: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | ^IXIC: 14218.34 |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 |
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
|
||||
|
||||
public func merge<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncMerge3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncMerge2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element, Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `merge(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncMergeSequence` which is an asynchronous sequence.
|
||||
|
||||
Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`.
|
||||
|
||||
When iterating a `AsyncMergeSequence`, the sequence terminates when all of the base asynchronous sequences terminate, since this means there is no potential for any further elements to be produced.
|
||||
|
||||
The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
|
||||
|
||||
### Naming
|
||||
|
||||
Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence, the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of Merge](https://reactivex.io/documentation/operators/merge.html) as a top level function for merging Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of merge(with:)](https://developer.apple.com/documentation/combine/publisher/merge(with:)-7qt71/) as an operator style method for merging Publishers.
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
### `@frozen` and `@inlinable`
|
||||
|
||||
These types utilize rethrowing mechanisms that are awaiting an implementation in the compiler for supporting implementation based rethrows. So none of them are marked as frozen or marked as inlinable. This feature (discussed as `rethrows(unsafe)` or `rethrows(SourceOfRethrowyness)` has not yet been reviewed or implemented. The current implementation takes liberties with an internal protocol to accomplish this task. Future revisions will remove that protocol trick to replace it with proper rethrows semantics at the actual call site. The types are expected to be stable boundaries to prevent that workaround for the compilers yet to be supported rethrowing (or TaskGroup rethrowing) mechanisms. As soon as that feature is resolved; a more detailed investigation on performance impact of inlining and frozen should be done before 1.0.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
It was considered to have merge be shaped as an extension method on `AsyncSequence` however that infers a "primary-ness" of one `AsyncSequence` over another. Since the behavior of this as a global function (which infers no preference to one side or another) it was decided that having symmetry between the asynchronous version and the synchronous version inferred the right connotations.
|
||||
@@ -0,0 +1,61 @@
|
||||
# Compacted
|
||||
|
||||
* Proposal: [SAA-0003](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0003-compacted.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
|
||||
* Implementation: [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCompactedSequence.swift)
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCompacted.swift)
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Similar to the Swift Algorithms package we propose that a new method be added to `AsyncSequence` to fit this need.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
|
||||
where Element == Unwrapped?
|
||||
}
|
||||
```
|
||||
|
||||
This is equivalent to writing `.compactMap { $0 }` from a behavioral standpoint but is easier to reason about and is more efficient since it does not need to execute or store a closure.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `AsyncCompactedSequence` type from an effects standpoint works just like `AsyncCompactMapSequence`. When the base asynchronous sequence throws, the iteration of `AsyncCompactedSequence` can throw. Likewise if the base does not throw then the iteration of `AsyncCompactedSequence` does not throw. This type is conditionally `Sendable` when the base, base element, and base iterator are `Sendable.
|
||||
|
||||
```swift
|
||||
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
|
||||
where Base.Element == Element? {
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncCompactedSequence: Sendable
|
||||
where
|
||||
Base: Sendable, Base.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncCompactedSequence.Iterator: Sendable
|
||||
where
|
||||
Base: Sendable, Base.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
Compacted has a trivial implementation and is marked as `@frozen` and `@inlinable`. This removes the ability of this type and functions to be ABI resilient boundaries at the benefit of being highly optimizable.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
None; shy of potentially eliding this since the functionality is so trivial. However the utility of this function aides in ease of use and approachability along with parity with the Swift Algorithms package.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md)
|
||||
@@ -0,0 +1,67 @@
|
||||
# Joined
|
||||
|
||||
* Proposal: [SAA-0004](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0004-joined.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Review Manager: [Franz Busch](https://github.com/FranzBusch)
|
||||
* Status: **Accepted**
|
||||
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncJoinedSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestJoin.swift)]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
The `joined()` and `joined(separator:)` algorithms on `AsyncSequence`s provide APIs to concatenate an `AsyncSequence` of `AsyncSequence`s.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
public func joined() -> AsyncJoinedSequence<Self>
|
||||
}
|
||||
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator>
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
These algorithms iterate over the elements of each `AsyncSequence` one bye one, i.e. only after the iteration of one `AsyncSequence` has finished the next one will be started.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
|
||||
|
||||
for try await line in [appleFeed, nasdaqFeed].async.joined() {
|
||||
print("\(line)")
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following combined events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | output |
|
||||
| ----------- | --------- | ---------- | ----------------------------- |
|
||||
| 11:40 AM | 173.91 | | 173.91 |
|
||||
| 12:25 AM | | 14236.78 | |
|
||||
| 12:40 AM | | 14218.34 | |
|
||||
| 1:15 PM | 173.00 | | 173.00 |
|
||||
| 1:15 PM | | | 14236.78 |
|
||||
| 1:15 PM | | | 14218.34 |
|
||||
|
||||
|
||||
The `joined()` and `joined(separator:)` methods are available on `AsyncSequence`s with elements that are `AsyncSequence`s themselves and produce either an `AsyncJoinedSequence` or an `AsyncJoinedBySeparatorSequence`.
|
||||
|
||||
As soon as an inner `AsyncSequence` returns `nil` the algorithm continues with iterating the next inner `AsyncSequence`.
|
||||
|
||||
The throwing behaviour of `AsyncJoinedSequence` and `AsyncJoinedBySeparatorSequence` is that if any of the inner `AsyncSequence`s throws, then the composed sequence throws on its iteration.
|
||||
|
||||
### Naming
|
||||
|
||||
The naming follows to current method naming of the standard library's [`joined`](https://developer.apple.com/documentation/swift/array/joined(separator:)-7uber) method.
|
||||
Prior art in the reactive community often names this method `concat`; however, we think that an alignment with the current method on `Sequence` is better.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of Concat](https://reactivex.io/documentation/operators/concat.html) as a top level function for concatenating Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of append](https://developer.apple.com/documentation/combine/publisher/append(_:)-5yh02) which offers similar functionality but limited to concatenating two individual `Publisher`s.
|
||||
@@ -0,0 +1,55 @@
|
||||
# AdjacentPairs
|
||||
|
||||
* Proposal: [SAA-0005](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0005-adjacent-pairs.md)
|
||||
* Author(s): [László Teveli](https://github.com/tevelee)
|
||||
* Review Manager: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAdjacentPairsSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestAdjacentPairs.swift)]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
The `adjacentPairs()` API serve the purpose of collecting adjacent values. This operation is available for any `AsyncSequence` by calling the `adjacentPairs()` method.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `adjacentPairs()` algorithm produces elements of tuple (size of 2), containing a pair of the original `Element` type.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types. The returned `AsyncAdjacentPairsSequence` conditionally conforms to `Sendable`.
|
||||
|
||||
Its iterator keeps track of the previous element returned in the `next()` function and updates it in every turn.
|
||||
|
||||
```swift
|
||||
for await (first, second) in (1...5).async.adjacentPairs() {
|
||||
print("First: \(first), Second: \(second)")
|
||||
}
|
||||
|
||||
// First: 1, Second: 2
|
||||
// First: 2, Second: 3
|
||||
// First: 3, Second: 4
|
||||
// First: 4, Second: 5
|
||||
```
|
||||
|
||||
It composes well with the [Dictionary.init(_:uniquingKeysWith:)](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Collections.md) API that deals with `AsyncSequence` of tuples.
|
||||
|
||||
```swift
|
||||
Dictionary(uniqueKeysWithValues: url.lines.adjacentPairs())
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
This functionality is often written as a `zip` of a sequence together with itself, dropping its first element (`zip(source, source.dropFirst())`).
|
||||
|
||||
It's such a dominant use-case, the [swift-algorithms](https://github.com/apple/swift-algorithms) package also [introduced](https://github.com/apple/swift-algorithms/pull/119) it to its collection of algorithms.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The synchronous counterpart in [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md).
|
||||
@@ -0,0 +1,93 @@
|
||||
# Combine Latest
|
||||
|
||||
* Proposal: [SAA-0006](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0006-combineLatest.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
|
||||
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCombineLatest.swift)]
|
||||
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
Similar to the `zip` algorithm there is a need to combine the latest values from multiple input asynchronous sequences. Since `AsyncSequence` augments the concept of sequence with the characteristic of time it means that the composition of elements may not just be pairwise emissions but instead be temporal composition. This means that it is useful to emit a new tuple _when_ a value is produced. The `combineLatest` algorithm provides precisely that.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This algorithm combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
|
||||
|
||||
for try await (apple, nasdaq) in combineLatest(appleFeed, nasdaqFeed) {
|
||||
print("AAPL: \(apple) NASDAQ: \(nasdaq)")
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following combined events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | combined output |
|
||||
| ----------- | --------- | ---------- | ----------------------------- |
|
||||
| 11:40 AM | 173.91 | | |
|
||||
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | AAPL: 173.91 NASDAQ: 14218.34 |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2>
|
||||
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncCombineLatest2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncCombineLatestSequence` which is an asynchronous sequence.
|
||||
|
||||
Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must all be `Sendable`.
|
||||
|
||||
If any of the bases terminate before the first element is produced, then the `AsyncCombineLatestSequence` iteration can never be satisfied. So, if a base's iterator returns `nil` at the first iteration, then the `AsyncCombineLatestSequence` iterator immediately returns `nil` to signify a terminal state. In this particular case, any outstanding iteration of other bases will be cancelled. After the first element is produced ,this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the bases, the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
|
||||
|
||||
The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point (within the first iteration or afterwards), an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
|
||||
|
||||
### Naming
|
||||
|
||||
Since the inherent behavior of `combineLatest(_:...)` combines the latest values from multiple streams into a tuple the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
Combine latest often appears in libraries developed for processing events over time since the event ordering of a concept of "latest" only occurs when asynchrony is involved.
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of CombineLatest](https://reactivex.io/documentation/operators/combinelatest.html) as a top level function for combining Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of combineLatest](https://developer.apple.com/documentation/combine/publisher/combinelatest(_:)/) has an operator style method for combining Publishers.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Chain
|
||||
|
||||
* Proposal: [SAA-0007](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0007-chain.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChain.swift)]
|
||||
|
||||
## Introduction
|
||||
|
||||
Combining asynchronous sequences can occur in multiple ways. One such way that is common for non asynchronous sequences is iterating a prefix sequence and then iterating a suffix sequence. The asynchronous version is just as useful and common. This algorithm has been dubbed `chain` in the swift algorithms package.
|
||||
|
||||
The chain algorithm brings together two or more asynchronous sequences together sequentially where the elements from the resulting asynchronous sequence are comprised in order from the elements of the first asynchronous sequence and then the second (and so on) or until an error occurs.
|
||||
|
||||
This operation is available for all `AsyncSequence` types who share the same `Element` type.
|
||||
|
||||
```swift
|
||||
let preamble = [
|
||||
"// Some header to add as a preamble",
|
||||
"//",
|
||||
""
|
||||
].async
|
||||
let lines = chain(preamble, URL(fileURLWithPath: "/tmp/Sample.swift").lines)
|
||||
|
||||
for try await line in lines {
|
||||
print(line)
|
||||
}
|
||||
```
|
||||
|
||||
The above example shows how two `AsyncSequence` types can be chained together. In this case it prepends a preamble to the `lines` content of the file.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element
|
||||
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> where Base1.Element == Base2.Element {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
|
||||
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
|
||||
|
||||
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
|
||||
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
The `chain(_:...)` function takes two or more sequences as arguments.
|
||||
|
||||
The resulting `AsyncChainSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments also conform to it.
|
||||
|
||||
When any of the asynchronous sequences being chained together come to their end of iteration, the `AsyncChainSequence` iteration proceeds to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration, the `AsyncChainSequence` then ends its iteration.
|
||||
|
||||
At any point in time, if one of the comprising asynchronous sequences throws an error during iteration, the resulting `AsyncChainSequence` iteration will throw that error and end iteration. The throwing behavior of `AsyncChainSequence` is that it will throw when any of its comprising bases throw, and will not throw when all of its comprising bases do not throw.
|
||||
|
||||
### Naming
|
||||
|
||||
This function's and type's name match the term of art used in other languages and libraries.
|
||||
|
||||
This combinator function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md).
|
||||
@@ -0,0 +1,59 @@
|
||||
# AsyncBufferedByteIterator
|
||||
|
||||
* Proposal: [SAA-0008](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0008-bytes.md)
|
||||
* Authors: [David Smith](https://github.com/Catfish-Man), [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncBufferedByteIterator.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestBufferedByteIterator.swift)]
|
||||
|
||||
## Introduction
|
||||
|
||||
Sources of bytes are a common point of asynchrony; reading from files, reading from the network, or other such tasks. Having an easy to use, uniform, and performant utility to make this approachable is key to unlocking highly scalable byte handling. This has proven useful for `FileHandle`, `URL`, and a number of others in Foundation.
|
||||
|
||||
This type provides infrastructure for creating `AsyncSequence` types with an `Element` of `UInt8` backed by file descriptors or similar read sources.
|
||||
|
||||
```swift
|
||||
struct AsyncBytes: AsyncSequence {
|
||||
public typealias Element = UInt8
|
||||
var handle: ReadableThing
|
||||
|
||||
internal init(_ readable: ReadableThing) {
|
||||
handle = readable
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
||||
return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
||||
// This runs once every 16384 invocations of next()
|
||||
return try await handle.read(into: buffer)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
```swift
|
||||
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol {
|
||||
public typealias Element = UInt8
|
||||
|
||||
public init(
|
||||
capacity: Int,
|
||||
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
||||
)
|
||||
|
||||
public mutating func next() async throws -> UInt8?
|
||||
}
|
||||
```
|
||||
|
||||
For each invocation of `next`, the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes, a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled, the read function is invoked to acquire the next filled buffer, at which point it takes a byte out of that buffer.
|
||||
|
||||
If the read function returns `0`, indicating it didn't read any more bytes, the iterator is decided to be finished and no additional invocations to the read function are made.
|
||||
|
||||
If the read function throws, the error will be thrown by the iteration. Subsequent invocations to the iterator will then return `nil` without invoking the read function.
|
||||
|
||||
If the task is cancelled during the iteration, the iteration will check the cancellation only in passes where the read function is invoked, and will throw a `CancellationError`.
|
||||
|
||||
### Naming
|
||||
|
||||
This type was named precisely for what it does: it is an asynchronous iterator that buffers bytes.
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# AsyncSyncSequence
|
||||
|
||||
* Proposal: [SAA-0009](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0009-async.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Implemented**
|
||||
|
||||
* Implementation:
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncSyncSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)
|
||||
|
||||
## Introduction
|
||||
|
||||
`AsyncSyncSequence` converts a non-asynchronous sequence into an asynchronous one.
|
||||
|
||||
This operation is available for all `Sequence` types.
|
||||
|
||||
```swift
|
||||
let numbers = [1, 2, 3, 4].async
|
||||
let characters = "abcde".async
|
||||
```
|
||||
|
||||
This transformation can be useful to test operations specifically available on `AsyncSequence` but also is useful
|
||||
to combine with other `AsyncSequence` types to provide well known sources of data.
|
||||
|
||||
The `.async` property returns an `AsyncSyncSequence` that is generic upon the base `Sequence` it was constructed from.
|
||||
|
||||
```swift
|
||||
extension Sequence {
|
||||
public var async: AsyncSyncSequence<Self> { get }
|
||||
}
|
||||
|
||||
public struct AsyncSyncSequence<Base: Sequence>: AsyncSequence {
|
||||
...
|
||||
}
|
||||
|
||||
extension AsyncSyncSequence: Sendable where Base: Sendable { }
|
||||
extension AsyncSyncSequence.Iterator: Sendable where Base.Iterator: Sendable { }
|
||||
```
|
||||
|
||||
### Naming
|
||||
|
||||
This property's and type's name match the naming approaches in the Swift standard library. The property is named with a
|
||||
succinct name in inspiration from `.lazy`, and the type is named in reference to the lazy behavior of the constructed
|
||||
`AsyncSequence`.
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
`AsyncSyncSequence` has a trivial implementation and is marked as `@frozen` and `@inlinable`. This removes the ability of this type and functions to be ABI resilient boundaries at the benefit of being highly optimizable.
|
||||
@@ -0,0 +1,114 @@
|
||||
# Buffer
|
||||
|
||||
* Proposal: [SAA-0010](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0010-buffer.md)
|
||||
* Author(s): [Thibault Wittemberg](https://github.com/twittemb)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Buffer/AsyncBufferSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestBuffer.swift)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
Buffering is a technique that balances supply and demand by temporarily storing elements to even out fluctuations in production and consumption rates. `AsyncStream` facilitates this process by allowing you to control the size of the buffer and the strategy for handling elements that exceed that size. However, this approach may not be suitable for all situations, and it doesn't provide a way to adapt other `AsyncSequence` types to incorporate buffering.
|
||||
|
||||
This proposal presents a new type that addresses these more advanced requirements and offers a comprehensive solution for buffering in asynchronous sequences.
|
||||
|
||||
## Motivation
|
||||
|
||||
As an `AsyncSequence` operates as a pull system, the production of elements is directly tied to the demand expressed by the consumer. The slower the consumer is in requesting elements, the slower the production of these elements will be. This can negatively impact the software that produces the elements, as demonstrated in the following example.
|
||||
|
||||
Consider an `AsyncSequence` that reads and returns a line from a file every time a new element is requested. To ensure exclusive access to the file, a lock is maintained while reading. Ideally, the lock should be held for as short a duration as possible to allow other processes to access the file. However, if the consumer is slow in processing received lines or has a fluctuating pace, the lock will be maintained for an extended period, reducing the performance of the system.
|
||||
|
||||
To mitigate this issue, a buffer operator can be employed to streamline the consumption of the `AsyncSequence`. This operator allows an internal iteration of the `AsyncSequence` independently from the consumer. Each element would then be made available for consumption by using a queuing mechanism.
|
||||
|
||||
By applying the buffer operator to the previous example, the file can be read as efficiently as possible, allowing the lock to be released in a timely manner. This results in improved performance, as the consumer can consume elements at its own pace without negatively affecting the system. The buffer operator ensures that the production of elements is not limited by the pace of the consumer, allowing both the producer and consumer to operate at optimal levels.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
We propose to extend `AsyncSequence` with a `buffer()` operator. This operator will return an `AsyncBufferSequence` that wraps the source `AsyncSequence` and handle the buffering mechanism.
|
||||
|
||||
This operator will accept an `AsyncBufferSequencePolicy`. The policy will dictate the behaviour in case of a buffer overflow.
|
||||
|
||||
As of now we propose 4 different behaviours:
|
||||
|
||||
```swift
|
||||
public struct AsyncBufferSequencePolicy: Sendable {
|
||||
public static func bounded(_ limit: Int)
|
||||
public static var unbounded
|
||||
public static func bufferingLatest(_ limit: Int)
|
||||
public static func bufferingOldest(_ limit: Int)
|
||||
}
|
||||
```
|
||||
|
||||
And the public API of `AsyncBufferSequence` will be:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
public func buffer(
|
||||
policy: AsyncBufferSequencePolicy
|
||||
) -> AsyncBufferSequence<Self> {
|
||||
AsyncBufferSequence<Self>(base: self, policy: policy)
|
||||
}
|
||||
}
|
||||
|
||||
public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncBufferSequence: Sendable where Base: Sendable { }
|
||||
```
|
||||
|
||||
## Notes on Sendable
|
||||
|
||||
Since all buffering means that the base asynchronous sequence must be iterated independently of the consumption (to resolve the production versus consumption issue) the base `AsyncSequence` needs to be able to be sent across task boundaries (the iterator does not need this requirement).
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The choice of the buffering policy is made through an enumeration whose values are related to a storage type. To date, two types of storage are implemented:
|
||||
|
||||
- `BoundedBufferStorage` backing the `AsyncBufferSequencePolicy.bounded(_:)` policy,
|
||||
- `UnboundedBufferStorage` backing the `AsyncBufferSequencePolicy.unbounded`, `AsyncBufferSequencePolicy.bufferingNewest(_:)` and `AsyncBufferSequencePolicy.bufferingLatest(_:)` policies.
|
||||
|
||||
Both storage types rely on a Mealy state machine stored in a `ManagedCriticalState`. They drive the mutations of the internal buffer, while ensuring that concurrent access to the state are safe.
|
||||
|
||||
### BoundedBufferStorage
|
||||
|
||||
`BoundedBufferStorage` is instantiated with the upstream `AsyncSequence` and a buffer maximum size. Upon the first call to the `next()` method, a task is spawned to support the iteration over this `AsyncSequence`. The iteration retrieves elements and adds them to an internal buffer as long as the buffer limit has not been reached. Meanwhile, the downstream `AsyncSequence` can access and consume these elements from the buffer. If the rate of consumption is slower than the rate of production, the buffer will eventually become full. In this case, the iteration is temporarily suspended until additional space becomes available.
|
||||
|
||||
### UnboundedBufferStorage
|
||||
|
||||
`UnboundedBufferStorage` is instantiated with the upstream `AsyncSequence` and a buffering policy. Upon the first call to the `next()` method, a task is spawned to support the iteration over this `AsyncSequence`.
|
||||
|
||||
From there the behaviour will depend on the buffering policy.
|
||||
|
||||
#### Unbounded
|
||||
If the policy is `unbounded`, the iteration retrieves elements and adds them to an internal buffer until the upstream `AsyncSequence` finishes or fails. Meanwhile, the downstream `AsyncSequence` can access and consume these elements from the buffer.
|
||||
|
||||
#### BufferingLatest
|
||||
If the policy is `bufferingLatest(_:)`, the iteration retrieves elements and adds them to an internal buffer. Meanwhile, the downstream `AsyncSequence` can access and consume these elements from the buffer. If the rate of consumption is slower than the rate of production, the buffer will eventually become full. In this case the oldest buffered elements will be removed from the buffer and the latest ones will be added.
|
||||
|
||||
#### BufferingOldest
|
||||
If the policy is `bufferingOldest(_:)`, the iteration retrieves elements and adds them to an internal buffer. Meanwhile, the downstream `AsyncSequence` can access and consume these elements from the buffer. If the rate of consumption is slower than the rate of production, the buffer will eventually become full. In this case the latest element will be discarded and never added to the buffer.
|
||||
|
||||
### Terminal events and cancellation
|
||||
|
||||
Terminal events from the upstream `AsyncSequence`, such as normal completion or failure, are delayed, ensuring that the consumer will receive all the elements before receiving the termination.
|
||||
|
||||
If the consuming `Task` is cancelled, so will be the `Task` supporting the iteration of the upstream `AsyncSequence`.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
The buffering mechanism was originally thought to rely on an open implementation of an `AsyncBuffer` protocol, which would be constrained to an `Actor` conformance. It was meant for developers to be able to provide their own implementation of a buffering algorithm. This buffer was designed to control the behavior of elements when pushed and popped, in an isolated manner.
|
||||
|
||||
A default implementation was provided to offers a queuing strategy for buffering elements, with options for unbounded, oldest-first, or newest-first buffering.
|
||||
|
||||
This implementation was eventually discarded due to the potentially higher cost of calling isolated functions on an `Actor`, compared to using a low-level locking mechanism like the one employed in other operators through the use of the `ManagedCriticalState`.
|
||||
@@ -0,0 +1,319 @@
|
||||
# Feature name
|
||||
|
||||
* Proposal: [SAA-0011](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0011-interspersed.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Review Manager: [Franz Busch](https://github.com/FranzBusch)
|
||||
* Status: **Implemented**
|
||||
|
||||
* Implementation:
|
||||
[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/TestLazy.swift)
|
||||
|
||||
## Motivation
|
||||
|
||||
A common transformation that is applied to async sequences is to intersperse the elements with
|
||||
a separator element.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
We propose to add a new method on `AsyncSequence` that allows to intersperse
|
||||
a separator between every n emitted element. This proposed API looks like this
|
||||
|
||||
```swift
|
||||
public extension AsyncSequence {
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: The value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
func interspersed(every: Int = 1, with separator: Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
func interspersed(every: Int = 1, with separator: @Sendable @escaping () -> Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
func interspersed(every: Int = 1, with separator: @Sendable @escaping () async -> Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () throws -> Element) -> AsyncThrowingInterspersedSequence<Self> {
|
||||
AsyncThrowingInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () async throws -> Element) -> AsyncThrowingInterspersedSequence<Self> {
|
||||
AsyncThrowingInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed design
|
||||
|
||||
The bulk of the implementation of the new `interspersed` method is inside the new
|
||||
`AsyncInterspersedSequence` struct. It constructs an iterator to the base async sequence
|
||||
inside its own iterator. The `AsyncInterspersedSequence.Iterator.next()` is forwarding the demand
|
||||
to the base iterator.
|
||||
|
||||
Below is the implementation of the `AsyncInterspersedSequence`.
|
||||
```swift
|
||||
/// An asynchronous sequence that presents the elements of a base asynchronous sequence of
|
||||
/// elements with a separator between each of those elements.
|
||||
public struct AsyncInterspersedSequence<Base: AsyncSequence> {
|
||||
@usableFromInline
|
||||
internal enum Separator {
|
||||
case element(Element)
|
||||
case syncClosure(@Sendable () -> Element)
|
||||
case asyncClosure(@Sendable () async -> Element)
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal let base: Base
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .element(separator)
|
||||
self.every = every
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .syncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () async -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .asyncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInterspersedSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncInterspersedSequence` asynchronous sequence.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
internal enum State {
|
||||
case start(Element?)
|
||||
case element(Int)
|
||||
case separator
|
||||
case finished
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal var state = State.start(nil)
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ iterator: Base.AsyncIterator, every: Int, separator: Separator) {
|
||||
self.iterator = iterator
|
||||
self.separator = separator
|
||||
self.every = every
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Base.Element? {
|
||||
// After the start, the state flips between element and separator. Before
|
||||
// returning a separator, a check is made for the next element as a
|
||||
// separator is only returned between two elements. The next element is
|
||||
// stored to allow it to be returned in the next iteration. However, if
|
||||
// the checking the next element throws, the separator is emitted before
|
||||
// rethrowing that error.
|
||||
switch state {
|
||||
case var .start(element):
|
||||
do {
|
||||
if element == nil {
|
||||
element = try await self.iterator.next()
|
||||
}
|
||||
|
||||
if let element = element {
|
||||
if every == 1 {
|
||||
state = .separator
|
||||
} else {
|
||||
state = .element(1)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .separator:
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
state = .start(element)
|
||||
switch separator {
|
||||
case let .element(element):
|
||||
return element
|
||||
|
||||
case let .syncClosure(closure):
|
||||
return closure()
|
||||
|
||||
case let .asyncClosure(closure):
|
||||
return await closure()
|
||||
}
|
||||
} else {
|
||||
state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case let .element(count):
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
let newCount = count + 1
|
||||
if every == newCount {
|
||||
state = .separator
|
||||
} else {
|
||||
state = .element(newCount)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .finished:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> AsyncInterspersedSequence<Base>.Iterator {
|
||||
Iterator(base.makeAsyncIterator(), every: every, separator: separator)
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,86 @@
|
||||
# Channel
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChannel.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrowingChannel.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChannel.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
`AsyncStream` introduced a mechanism to send buffered elements from a context that doesn't use Swift concurrency into one that does. That design only addressed a portion of the potential use cases; the missing portion was the back pressure excerpted across two concurrency domains.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
To achieve a system that supports back pressure and allows for the communication of more than one value from one task to another we are introducing a new type, the _channel_. The channel will be a reference-type asynchronous sequence with an asynchronous sending capability that awaits the consumption of iteration. Each value sent by the channel will await the consumption of that value by iteration. That awaiting behavior will allow for the affordance of back pressure applied from the consumption site to be transmitted to the production site. This means that the rate of production cannot exceed the rate of consumption, and that the rate of consumption cannot exceed the rate of production. Sending a terminal event to the channel will instantly resume all pending operations for every producers and consumers.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Similar to the `AsyncStream` and `AsyncThrowingStream` types, the type for sending elements via back pressure will come in two versions. These two versions will account for the throwing nature or non-throwing nature of the elements being produced.
|
||||
|
||||
Each type will have functions to send elements and to send terminal events.
|
||||
|
||||
```swift
|
||||
public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async -> Element?
|
||||
}
|
||||
|
||||
public init(element elementType: Element.Type = Element.self)
|
||||
|
||||
public func send(_ element: Element) async
|
||||
public func finish()
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public init(element elementType: Element.Type = Element.self, failure failureType: Failure.Type = Failure.self)
|
||||
|
||||
public func send(_ element: Element) async
|
||||
public func fail(_ error: Error) where Failure == Error
|
||||
public func finish()
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
Channels are intended to be used as communication types between tasks. Particularly when one task produces values and another task consumes said values. On the one hand, the back pressure applied by `send(_:)` via the suspension/resume ensures that the production of values does not exceed the consumption of values from iteration. This method suspends after enqueuing the event and is resumed when the next call to `next()` on the `Iterator` is made. On the other hand, the call to `finish()` or `fail(_:)` immediately resumes all the pending operations for every producers and consumers. Thus, every suspended `send(_:)` operations instantly resume, so as every suspended `next()` operations by producing a nil value, or by throwing an error, indicating the termination of the iterations. Further calls to `send(_:)` will immediately resume. The calls to `send(:)` and `next()` will immediately resume when their supporting task is cancelled, other operations from other tasks will remain active.
|
||||
|
||||
```swift
|
||||
let channel = AsyncChannel<String>()
|
||||
Task {
|
||||
while let resultOfLongCalculation = doLongCalculations() {
|
||||
await channel.send(resultOfLongCalculation)
|
||||
}
|
||||
channel.finish()
|
||||
}
|
||||
|
||||
for await calculationResult in channel {
|
||||
print(calculationResult)
|
||||
}
|
||||
```
|
||||
|
||||
The example above uses a task to perform intense calculations; each of which are sent to the other task via the `send(_:)` method. That call to `send(_:)` returns when the next iteration of the channel is invoked.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
The use of the name "subject" was considered, due to its heritage as a name for a sync-to-async adapter type.
|
||||
|
||||
It was considered to make `AsyncChannel` and `AsyncThrowingChannel` actors, however due to the cancellation internals it would imply that these types would need to create new tasks to handle cancel events. The advantages of an actor in this particular case did not outweigh the impact of adjusting the implementations to be actors.
|
||||
|
||||
## Future Directions
|
||||
|
||||
`AsyncChannel` and `AsyncThrowingChannel` are just the prominent members of the channel-like behavior algorithms. It is reasonable to have as its own distinct type a buffering channel that provides more [tuned back pressure per a given buffer of elements](https://forums.swift.org/t/asyncchannel-should-we-allow-to-buffer/60876). These other members of the same category of algorithm should be considered on their own as distinct proposals.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
`AsyncChannel` and `AsyncThrowingChannel` was heavily inspired from `Subject` but with the key difference that it uses Swift concurrency to apply back pressure.
|
||||
|
||||
https://developer.apple.com/documentation/combine/subject/
|
||||
@@ -0,0 +1,356 @@
|
||||
# Chunked & Timer
|
||||
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-chunk.md)
|
||||
* Author(s): [Kevin Perry](https://github.com/kperryua), [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Implemented**
|
||||
* 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),
|
||||
[Count and signal](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountAndSignalSequence.swift)
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChunk.swift)
|
||||
]
|
||||
[
|
||||
[Timer](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncTimerSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestTimer.swift)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
Grouping of values from an asynchronous sequence is often useful for tasks that involve writing those values efficiently or useful to handle specific structured data inputs.
|
||||
|
||||
The groupings may be controlled by different ways but one most notable is to control them by regular intervals. Producing elements at regular intervals can be useful for composing with other algorithms. These can range from invoking code at specific times to using those regular intervals as a delimiter of events. There are other cases this exists in APIs however those do not currently interact with Swift concurrency. These existing APIs are ones like `Timer` or `DispatchTimer` but are bound to internal clocks that are not extensible.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Chunking operations can be broken down into a few distinct categories: grouping according to a binary predicate used to determine whether consecutive elements belong to the same group, projecting an element's property to determine the element's chunk membership, by discrete count, by another signal asynchronous sequence which indicates when the chunk should be delimited, or by a combination of count and signal.
|
||||
|
||||
To satisfy the specific grouping by inteervals we propose to add a new type; `AsyncTimerSequence` which utilizes the new `Clock`, `Instant` and `Duration` types. This allows the interaction of the timer to custom implementations of types adopting `Clock`.
|
||||
|
||||
This asynchronous sequence will produce elements of the clock's `Instant` type after the interval has elapsed. That instant will be the `now` at the time that the sleep has resumed. For each invocation to `next()` the `AsyncTimerSequence.Iterator` will calculate the next deadline to resume and pass that and the tolerance to the clock. If at any point in time the task executing that iteration is cancelled the iteration will return `nil` from the call to `next()`.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
### Grouping
|
||||
|
||||
Group chunks are determined by passing two consecutive elements to a closure which tests whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator receives the first element from the base sequence, it will immediately be added to a group. When it receives the second item, it tests whether the previous item and the current item belong to the same group. If they are not in the same group, then the iterator emits the first item's group and a new group is created containing the second item. Items declared to be in the same group accumulate until a new group is declared, or the iterator finds the end of the base sequence. When the base sequence terminates, the final group is emitted. If the base sequence throws an error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard any current group.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Collected: RangeReplaceableCollection>(
|
||||
into: Collected.Type,
|
||||
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
|
||||
) -> AsyncChunkedByGroupSequence<Self, Collected>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked(
|
||||
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
|
||||
) -> AsyncChunkedByGroupSequence<Self, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
Consider an example where an asynchronous sequence emits the following values: `10, 20, 30, 10, 40, 40, 10, 20`. Given the chunked operation to be defined as follows:
|
||||
|
||||
```swift
|
||||
let chunks = numbers.chunked { $0 <= $1 }
|
||||
for await numberChunk in chunks {
|
||||
print(numberChunk)
|
||||
}
|
||||
```
|
||||
|
||||
That snippet will produce the following values:
|
||||
|
||||
```swift
|
||||
[10, 20, 30]
|
||||
[10, 40, 40]
|
||||
[10, 20]
|
||||
```
|
||||
|
||||
While `Array` is the default type for chunks, thanks to the overload that takes a `RangeReplaceableCollection` type, the same sample can be chunked into instances of `ContiguousArray`, or any other `RangeReplaceableCollection` instead.
|
||||
|
||||
```swift
|
||||
let chunks = numbers.chunked(into: ContiguousArray.self) { $0 <= $1 }
|
||||
for await numberChunk in chunks {
|
||||
print(numberChunk)
|
||||
}
|
||||
```
|
||||
|
||||
That variant is the funnel method for the main implementation, which passes `[Element].self` in as the parameter.
|
||||
|
||||
### Projection
|
||||
|
||||
In some scenarios, chunks are determined not by comparing different elements, but by the element itself. This may be the case when the element has some sort of discriminator that can determine the chunk it belongs to. When two consecutive elements have different projections, the current chunk is emitted and a new chunk is created for the new element.
|
||||
|
||||
When the `AsyncChunkedOnProjectionSequence`'s iterator receives `nil` from the base sequence, it emits the final chunk. When the base sequence throws an error, the iterator discards the current chunk and rethrows that error.
|
||||
|
||||
Similarly to the `chunked(by:)` method this algorithm has an optional specification for the `RangeReplaceableCollection` which is used as the type of each chunk.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(
|
||||
into: Collected.Type,
|
||||
on projection: @escaping @Sendable (Element) -> Subject
|
||||
) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected>
|
||||
|
||||
public func chunked<Subject : Equatable>(
|
||||
on projection: @escaping @Sendable (Element) -> Subject
|
||||
) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
The following example shows how a sequence of names can be chunked together by their first characters.
|
||||
|
||||
```swift
|
||||
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
|
||||
let groupedNames = names.chunked(on: \.first!)
|
||||
for try await (firstLetter, names) in groupedNames {
|
||||
print(firstLetter)
|
||||
for name in names {
|
||||
print(" ", name)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A special property of this kind of projection chunking is that when an asynchronous sequence's elements are known to be ordered, the output of the chunking asynchronous sequence is suitable for initializing dictionaries using the `AsyncSequence` initializer for `Dictionary`. This is because the projection can be easily designed to match the sorting characteristics and thereby guarantee that the output matches the pattern of an array of pairs of unique "keys" with the chunks as the "values".
|
||||
|
||||
In the example above, if the names are known to be ordered then you can take advantage of the uniqueness of each "first character" projection to initialize a `Dictionary` like so:
|
||||
|
||||
```swift
|
||||
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
|
||||
let nameDirectory = try await Dictionary(uniqueKeysWithValues: names.chunked(on: \.first!))
|
||||
```
|
||||
|
||||
### Count or Signal
|
||||
|
||||
Sometimes chunks are determined not by the elements themselves, but by external factors. This final category enables limiting chunks to a specific size and/or delimiting them by another asynchronous sequence which is referred to as a "signal". This particular chunking family is useful for scenarios where the elements are more efficiently processed as chunks than individual elements, regardless of their values.
|
||||
|
||||
This family is broken down into two sub-families of methods: ones that employ a signal plus an optional count (which return an `AsyncChunksOfCountOrSignalSequence`), and the ones that only deal with counts (which return an `AsyncChunksOfCountSequence`). Both sub-families have `Collected` as their element type, or `Array` if unspecified. These sub-families have rethrowing behaviors; if the base `AsyncSequence` can throw then the chunks sequence can also throw. Likewise if the base `AsyncSequence` cannot throw then the chunks sequence also cannot throw.
|
||||
|
||||
##### Count only
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunks<Collected: RangeReplaceableCollection>(
|
||||
ofCount count: Int,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountSequence<Self, Collected>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunks(
|
||||
ofCount count: Int
|
||||
) -> AsyncChunksOfCountSequence<Self, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
If a chunk size limit is specified via an `ofCount` parameter, the sequence will produce chunks of type `Collected` with at most the specified number of elements. When a chunk reaches the given size, the asynchronous sequence will emit it immediately.
|
||||
|
||||
For example, an asynchronous sequence of `UInt8` bytes can be chunked into at most 1024-byte `Data` instances like so:
|
||||
|
||||
```swift
|
||||
let packets = bytes.chunks(ofCount: 1024, into: Data.self)
|
||||
for try await packet in packets {
|
||||
write(packet)
|
||||
}
|
||||
```
|
||||
|
||||
##### Signal only
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Signal, Collected: RangeReplaceableCollection>(
|
||||
by signal: Signal,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<Signal>(
|
||||
by signal: Signal
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
|
||||
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
|
||||
by timer: AsyncTimerSequence<C>,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<C: Clock>(
|
||||
by timer: AsyncTimerSequence<C>
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
|
||||
}
|
||||
```
|
||||
|
||||
If a signal asynchronous sequence is specified, the chunking asynchronous sequence emits chunks whenever the signal emits. The signals element values are ignored. If the chunking asynchronous sequence hasn't accumulated any elements since its previous emission, then no value is emitted in response to the signal.
|
||||
|
||||
Since time is a frequent method of signaling desired delineations of chunks, there is a pre-specialized set of overloads that take `AsyncTimerSequence`. These allow shorthand initialization by using `AsyncTimerSequence`'s static member initializers.
|
||||
|
||||
As an example, an asynchronous sequence of log messages can be chunked into arrays of logs in four second segments like so:
|
||||
|
||||
```swift
|
||||
let fourSecondsOfLogs = logs.chunked(by: .repeating(every: .seconds(4)))
|
||||
for await chunk in fourSecondsOfLogs {
|
||||
send(chunk)
|
||||
}
|
||||
```
|
||||
|
||||
##### Count or Signal
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunks<Signal, Collected: RangeReplaceableCollection>(
|
||||
ofCount count: Int,
|
||||
or signal: Signal,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunks<Signal>(
|
||||
ofCount count: Int,
|
||||
or signal: Signal
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
|
||||
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
|
||||
by timer: AsyncTimerSequence<C>,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<C: Clock>(
|
||||
by timer: AsyncTimerSequence<C>
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
|
||||
}
|
||||
```
|
||||
|
||||
If both count and signal are specified, the chunking asynchronous sequence emits chunks whenever *either* the chunk reaches the specified size *or* the signal asynchronous sequence emits. When a signal causes a chunk to be emitted, the accumulated element count is reset back to zero. When an `AsyncTimerSequence` is used as a signal, the timer is started from the moment `next()` is called for the first time on `AsyncChunksOfCountOrSignalSequence`'s iterator, and it emits on a regular cadence from that moment. Note that the scheduling of the timer's emission is unaffected by any chunks emitted based on count.
|
||||
|
||||
Like the example above, this code emits up to 1024-byte `Data` instances, but a chunk will also be emitted every second.
|
||||
|
||||
```swift
|
||||
let packets = bytes.chunks(ofCount: 1024 or: .repeating(every: .seconds(1)), into: Data.self)
|
||||
for try await packet in packets {
|
||||
write(packet)
|
||||
}
|
||||
```
|
||||
|
||||
In any configuration of any of the chunking families, when the base asynchronous sequence terminates, one of two things will happen: 1) a partial chunk will be emitted, or 2) no chunk will be emitted (i.e. the iterator received no elements since the emission of the previous chunk). No elements from the base asynchronous sequence are ever discarded, except in the case of a thrown error.
|
||||
|
||||
## Interfaces
|
||||
|
||||
### Grouping
|
||||
|
||||
```swift
|
||||
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunkedByGroupSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
extension AsyncChunkedByGroupSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
```
|
||||
|
||||
### Projection
|
||||
|
||||
```swift
|
||||
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
public typealias Element = (Subject, Collected)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> (Subject, Collected)?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunkedOnProjectionSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Subject: Sendable { }
|
||||
```
|
||||
|
||||
### Count
|
||||
|
||||
```swift
|
||||
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
|
||||
|
||||
```
|
||||
|
||||
### Count or Signal
|
||||
|
||||
```swift
|
||||
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable
|
||||
where
|
||||
Collected.Element == Base.Element,
|
||||
Base: Sendable, Signal: Sendable,
|
||||
Base.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable,
|
||||
Base.Element: Sendable, Signal.Element: Sendable {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
### Timer
|
||||
|
||||
```swift
|
||||
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
|
||||
public typealias Element = C.Instant
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async -> C.Instant?
|
||||
}
|
||||
|
||||
public init(
|
||||
interval: C.Instant.Duration,
|
||||
tolerance: C.Instant.Duration? = nil,
|
||||
clock: C
|
||||
)
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncTimerSequence where C == SuspendingClock {
|
||||
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock>
|
||||
}
|
||||
|
||||
extension AsyncTimerSequence: Sendable { }
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
It was considered to make the chunked element to be an `AsyncSequence` instead of allowing collection into a `RangeReplaceableCollection` however it was determined that the throwing behavior of that would be complex to understand. If that hurdle could be overcome then that might be a future direction/consideration that would be worth exploring.
|
||||
|
||||
Variants of `chunked(by:)` (grouping) and `chunked(on:)` (projection) methods could be added that take delimiting `Signal` and `AsyncTimerSequence` inputs similar to `chunked(byCount:or:)`. However, it was decided that such functionality was likely to be underutilized and not worth the complication to the already broad surface area of `chunked` methods.
|
||||
|
||||
The naming of this family was considered to be `collect` which is used in APIs like `Combine`. This family of functions has distinct similarity to those APIs.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
This transformation function is a heavily inspired analog of the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md)
|
||||
|
||||
https://developer.apple.com/documentation/foundation/timer
|
||||
|
||||
https://developer.apple.com/documentation/foundation/timer/timerpublisher
|
||||
@@ -0,0 +1,157 @@
|
||||
# Rate Limiting
|
||||
|
||||
* Proposal: [SAA-NNNN]()
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Implemented**
|
||||
* Implementation:
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncDebounceSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestDebounce.swift)
|
||||
]
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrottleSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestThrottle.swift)
|
||||
]
|
||||
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to only emit values after a given period of time of inactivity, or "quiescence", has elapsed. This algorithm is commonly referred to as debouncing. A very close relative is an approach to emit values after a given period has elapsed. These emitted values can be reduced from the values encountered during the waiting period. This algorithm is commonly referred to as throttling.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The debounce algorithm produces elements after a particular duration has passed between events. It transacts within a given tolerance applied to a clock. If values are produced by the base `AsyncSequence` during this quiet period, the debounce does not resume its next iterator until the period has elapsed with no values are produced or unless a terminal event is encountered.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types where the base type, iterator, and element are `Sendable`, since this algorithm will inherently create tasks to manage their timing of events. A shorthand implementation will be offered where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func debounce<C: Clock>(
|
||||
for interval: C.Instant.Duration,
|
||||
tolerance: C.Instant.Duration? = nil,
|
||||
clock: C
|
||||
) -> AsyncDebounceSequence<Self, C>
|
||||
|
||||
public func debounce(
|
||||
for interval: Duration,
|
||||
tolerance: Duration? = nil
|
||||
) -> AsyncDebounceSequence<Self, ContinuousClock>
|
||||
}
|
||||
```
|
||||
|
||||
This all boils down to a terse description of how to transform the asynchronous sequence over time.
|
||||
|
||||
```swift
|
||||
fastEvents.debounce(for: .seconds(1))
|
||||
```
|
||||
|
||||
In this case it transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second with no events to elapse before emitting a value.
|
||||
|
||||
The throttle algorithm produces elements such that at least a specific interval has elapsed between them. It transacts by measuring against a specific clock. If values are produced by the base `AsyncSequence` the throttle does not resume its next iterator until the period has elapsed or unless a terminal event is encountered.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types. Unlike other algorithms like `debounce`, the throttle algorithm does not need to create additional tasks or require any sort of tolerance because the interval is just measured. A shorthand implementation will be offered in conjunction where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values. An additional shorthand is offered to reduce the values such that it provides a "latest" or "earliest" value, representing the leading or trailing edge of a throttled region of production of events.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func throttle<C: Clock, Reduced>(
|
||||
for interval: C.Instant.Duration,
|
||||
clock: C,
|
||||
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
|
||||
) -> AsyncThrottleSequence<Self, C, Reduced>
|
||||
|
||||
public func throttle<Reduced>(
|
||||
for interval: Duration,
|
||||
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
|
||||
) -> AsyncThrottleSequence<Self, ContinuousClock, Reduced>
|
||||
|
||||
public func throttle<C: Clock>(
|
||||
for interval: C.Instant.Duration,
|
||||
clock: C,
|
||||
latest: Bool = true
|
||||
) -> AsyncThrottleSequence<Self, C, Element>
|
||||
|
||||
public func throttle(
|
||||
for interval: Duration,
|
||||
latest: Bool = true
|
||||
) -> AsyncThrottleSequence<Self, ContinuousClock, Element>
|
||||
}
|
||||
```
|
||||
|
||||
This all boils down to a terse description of how to transform the asynchronous sequence over time.
|
||||
|
||||
```swift
|
||||
fastEvents.throttle(for: .seconds(1))
|
||||
```
|
||||
|
||||
In this case, the throttle transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second to elapse before emitting a value.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
### Debounce
|
||||
|
||||
The type that implements the algorithm for debounce emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
|
||||
|
||||
```swift
|
||||
public struct AsyncDebounceSequence<Base: AsyncSequence, C: Clock>: Sendable
|
||||
where Base.Element: Sendable, Base: Sendable {
|
||||
}
|
||||
|
||||
extension AsyncDebounceSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Base.Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
Since the stored types comprising `AsyncDebounceSequence` must be `Sendable`; `AsyncDebounceSequence` is unconditionally always `Sendable`. It is worth noting that the iterators are not required to be Sendable.
|
||||
|
||||
### Throttle
|
||||
|
||||
The type that implements the algorithm for throttle emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
|
||||
|
||||
```swift
|
||||
public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
|
||||
}
|
||||
|
||||
extension AsyncThrottleSequence: AsyncSequence {
|
||||
public typealias Element = Reduced
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Reduced?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrottleSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
```
|
||||
|
||||
The `AsyncThrottleSequence` is conditionally `Sendable` if the base types comprising it are `Sendable`.
|
||||
|
||||
The time in which events are measured are from the previous emission if present. If a duration has elapsed between the last emission and the point in time the throttle is measured then that duration is counted as elapsed. The first element is considered not throttled because no interval can be constructed from the start to the first element.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
An alternative form of `debounce` could exist similar to the reductions of `throttle`, where a closure would be invoked for each value being set as the latest, and reducing a new value to produce for the debounce.
|
||||
|
||||
It was considered to only provide the "latest" style APIs, however the reduction version grants more flexibility and can act as a funnel to the implementations of `latest`.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The naming for debounce comes as a term of art; originally this term was inspired by electronic circuitry. When a physical switch closes a circuit it can easily have a "bouncing" behavior (also called chatter) that is caused by electrical contact resistance and the physical bounce of springs associated with switches. That phenomenon is often addressed with additional circuits to de-bounce (removing the bouncing) by ensuring a certain quiescence occurs.
|
||||
|
||||
http://reactivex.io/documentation/operators/debounce.html
|
||||
|
||||
https://developer.apple.com/documentation/combine/publishers/debounce/
|
||||
|
||||
http://reactivex.io/documentation/operators/sample.html
|
||||
|
||||
https://developer.apple.com/documentation/combine/publishers/throttle/
|
||||
|
||||
@@ -0,0 +1,196 @@
|
||||
# Reductions
|
||||
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-reductions.md)
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Implemented**
|
||||
* 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)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
The family of algorithms for reduce are useful for converting a sequence or asynchronous sequence into a single value, but that can elide important intermediate information. The _reductions_ algorithm is often called "scan", but this name does not convey its heritage to the family of reducing.
|
||||
|
||||
There are two strategies that are usable for creating continuous reductions: exclusive reductions and inclusive reductions:
|
||||
|
||||
* Exclusive reductions take a value and incorporate values into that initial value. A common example is reductions by appending to an array.
|
||||
* Inclusive reductions transact only on the values provided. A common example is adding numbers.
|
||||
|
||||
There are also common specializations of this algorithm that are worth offering as a shorthand. Particularly removing duplications that is a common task of reducing a sequence. When processing values over time it is definitely possible that the same value may occur in a row. When the distinctness of the presence value is not needed it is useful to consider the values over time that are differing from the last. Particularly this can be expressed as removing duplicate values either in the case as they are directly `Equatable` or by a predicate.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Exclusive reductions come in two variants: transforming by application, or transformation via mutation. This replicates the same interface as `reduce(_:_:)` and `reduce(into:_:)`. Unlike the `reduce` algorithms, the `reductions` algorithm also comes in two flavors: throwing or non throwing transformations.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func reductions<Result>(
|
||||
_ initial: Result,
|
||||
_ transform: @Sendable @escaping (Result, Element) async -> Result
|
||||
) -> AsyncExclusiveReductionsSequence<Self, Result>
|
||||
|
||||
public func reductions<Result>(
|
||||
into initial: Result,
|
||||
_ transform: @Sendable @escaping (inout Result, Element) async -> Void
|
||||
) -> AsyncExclusiveReductionsSequence<Self, Result>
|
||||
}
|
||||
|
||||
extension AsyncSequence {
|
||||
public func reductions<Result>(
|
||||
_ initial: Result,
|
||||
_ transform: @Sendable @escaping (Result, Element) async throws -> Result
|
||||
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
|
||||
|
||||
public func reductions<Result>(
|
||||
into initial: Result,
|
||||
_ transform: @Sendable @escaping (inout Result, Element) async throws -> Void
|
||||
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
|
||||
}
|
||||
```
|
||||
|
||||
These APIs can be used to reduce an initial value progressively or reduce into an initial value via mutation. In practice, a common use case for reductions is to mutate a collection by appending values.
|
||||
|
||||
```swift
|
||||
characters.reductions(into: "") { $0.append($1) }
|
||||
```
|
||||
|
||||
If the characters being produced asynchronously are `"a", "b", "c"`, then the iteration of the reductions is `"a", "ab", "abc"`.
|
||||
|
||||
Inclusive reductions do not have an initial value and therefore do not need an additional variations beyond the throwing and non throwing flavors.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async -> Element
|
||||
) -> AsyncInclusiveReductionsSequence<Self>
|
||||
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
|
||||
) -> AsyncThrowingInclusiveReductionsSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
This is often used for scenarios like a running tally or other similar cases.
|
||||
|
||||
```swift
|
||||
numbers.reductions { $0 + $1 }
|
||||
```
|
||||
|
||||
In the above example, if the numbers are a sequence of `1, 2, 3, 4`, the produced values would be `1, 3, 6, 10`.
|
||||
|
||||
The `removeDuplicates()` and `removeDuplicates(by:)` APIs serve this purpose of removing duplicate values that occur. These are special case optimizations in the family of the reductions APIs. These algorithms test against the previous value and if the latest iteration of the base `AsyncSequence` is the same as the last it invokes `next()` again. The resulting `AsyncRemoveDuplicatesSequence` will ensure that no duplicate values occur next to each other. This should not be confused with only emitting unique new values; where each value is tested against a collected set of values.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: Equatable {
|
||||
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self>
|
||||
}
|
||||
|
||||
extension AsyncSequence {
|
||||
public func removeDuplicates(
|
||||
by predicate: @escaping @Sendable (Element, Element) async -> Bool
|
||||
) -> AsyncRemoveDuplicatesSequence<Self>
|
||||
|
||||
public func removeDuplicates(
|
||||
by predicate: @escaping @Sendable (Element, Element) async throws -> Bool
|
||||
) -> AsyncThrowingRemoveDuplicatesSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
The `removeDuplicates` family comes in three variants. One variant is conditional upon the `Element` type being `Equatable`. This variation is a shorthand for writing `.removeDuplicates { $0 == $1 }`. The next variation is the closure version that allows for custom predicates to be applied. This algorithm allows for the cases where the elements themselves may not be equatable but portions of the element may be compared. Lastly is the variation that allows for comparison when the comparison method may throw.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
#### Reductions
|
||||
|
||||
The exclusive reduction variants come in two distinct cases: non-throwing and throwing. These both have corresponding types to encompass that throwing behavior.
|
||||
|
||||
For non-throwing exclusive reductions, the element type of the sequence is the result of the reduction transform. `AsyncExclusiveReductionsSequence` will throw if the base asynchronous sequence throws, and will not throw if the base does not throws.
|
||||
|
||||
```swift
|
||||
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: AsyncSequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
The sendability behavior of `AsyncExclusiveReductionsSequence` is such that when the base, base iterator, and element are `Sendable` then `AsyncExclusiveReductionsSequence` is `Sendable`.
|
||||
|
||||
```swift
|
||||
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
#### Remove Duplicates
|
||||
|
||||
In the cases where the `Element` type is `Equatable` or the non-trowing predicate variant these utilize the type `AsyncRemoveDuplicatesSequence`. The throwing predicate variant uses `AsyncThrowingRemoveDuplicatesSequence`. Both of these types are conditionally `Sendable` when the base, base element, and base iterator are `Sendable`
|
||||
|
||||
The `AsyncRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and will not throw if the base asynchronous sequence does not throw.
|
||||
|
||||
```swift
|
||||
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncRemoveDuplicatesSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
The `AsyncThrowingRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and still may throw if the base asynchronous sequence does not throw due to the predicate having the potential of throwing.
|
||||
|
||||
```swift
|
||||
|
||||
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrowingRemoveDuplicatesSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
One alternate name for `reductions` was to name it `scan`; however the naming from the Swift Algorithms package offers considerably more inference to the heritage of what family of functions this algorithm belongs to.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md)
|
||||
+211
@@ -0,0 +1,211 @@
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
|
||||
|
||||
## Runtime Library Exception to the Apache 2.0 License: ##
|
||||
|
||||
|
||||
As an exception, if you use this Software to compile your source code and
|
||||
portions of this Software are embedded into the binary product as a result,
|
||||
you may redistribute such product without providing attribution as would
|
||||
otherwise be required by Sections 4(a), 4(b) and 4(d) of the License.
|
||||
@@ -0,0 +1,61 @@
|
||||
// swift-tools-version: 5.8
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-async-algorithms",
|
||||
platforms: [
|
||||
.macOS("10.15"),
|
||||
.iOS("13.0"),
|
||||
.tvOS("13.0"),
|
||||
.watchOS("6.0")
|
||||
],
|
||||
products: [
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "AsyncAlgorithms",
|
||||
dependencies: [
|
||||
.product(name: "OrderedCollections", package: "swift-collections"),
|
||||
.product(name: "DequeModule", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete"),
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete"),
|
||||
]
|
||||
),
|
||||
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete"),
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "AsyncAlgorithmsTests",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"],
|
||||
swiftSettings: [
|
||||
.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"),
|
||||
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
|
||||
]
|
||||
} else {
|
||||
package.dependencies += [
|
||||
.package(path: "../swift-collections"),
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
// swift-tools-version: 5.6
|
||||
|
||||
import PackageDescription
|
||||
|
||||
let package = Package(
|
||||
name: "swift-async-algorithms",
|
||||
platforms: [
|
||||
.macOS("10.15"),
|
||||
.iOS("13.0"),
|
||||
.tvOS("13.0"),
|
||||
.watchOS("6.0")
|
||||
],
|
||||
products: [
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]),
|
||||
.library(name: "AsyncSequenceValidation", targets: ["AsyncSequenceValidation"]),
|
||||
.library(name: "_CAsyncSequenceValidationSupport", type: .static, targets: ["AsyncSequenceValidation"]),
|
||||
.library(name: "AsyncAlgorithms_XCTest", targets: ["AsyncAlgorithms_XCTest"]),
|
||||
],
|
||||
dependencies: [
|
||||
.package(url: "https://github.com/apple/swift-collections.git", from: "1.0.4"),
|
||||
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "AsyncAlgorithms",
|
||||
dependencies: [.product(name: "Collections", package: "swift-collections")]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"]),
|
||||
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"]),
|
||||
.testTarget(
|
||||
name: "AsyncAlgorithmsTests",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"]),
|
||||
]
|
||||
)
|
||||
@@ -0,0 +1,105 @@
|
||||
# swift-async-algorithms
|
||||
|
||||
**Swift Async Algorithms** is an open-source package of asynchronous sequence and advanced algorithms that involve concurrency, along with their related types.
|
||||
|
||||
This package has three main goals:
|
||||
|
||||
- First-class integration with `async/await`
|
||||
- Provide a home for time-based algorithms
|
||||
- Be cross-platform and open source
|
||||
|
||||
## Motivation
|
||||
|
||||
AsyncAlgorithms is a package for algorithms that work with *values over time*. That includes those primarily about *time*, like `debounce` and `throttle`, but also algorithms about *order* like `combineLatest` and `merge`. Operations that work with multiple inputs (like `zip` does on `Sequence`) can be surprisingly complex to implement, with subtle behaviors and many edge cases to consider. A shared package can get these details correct, with extensive testing and documentation, for the benefit of all Swift apps.
|
||||
|
||||
The foundation for AsyncAlgorithms was included in Swift 5.5 from [AsyncSequence](https://github.com/apple/swift-evolution/blob/main/proposals/0298-asyncsequence.md). Swift 5.5 also brings the ability to use a natural `for/in` loop with `await` to process the values in an `AsyncSequence` and `Sequence`-equivalent API like `map` and `filter`. Structured concurrency allows us to write code where intermediate state is simply a local variable, `try` can be used directly on functions that `throw`, and generally treat the logic for asynchronous code similar to that of synchronous code.
|
||||
|
||||
This package is the home for these APIs. Development and API design take place on [GitHub](https://github.com/apple/swift-async-algorithms) and the [Swift Forums](https://forums.swift.org/c/related-projects/swift-async-algorithms).
|
||||
|
||||
## Contents
|
||||
|
||||
#### Combining asynchronous sequences
|
||||
|
||||
- [`chain(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Chain.md): Concatenates two or more asynchronous sequences with the same element type.
|
||||
- [`combineLatest(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/CombineLatest.md): Combines two or more asynchronous sequences into an asynchronous sequence producing a tuple of elements from those base asynchronous sequences that updates when any of the base sequences produce a value.
|
||||
- [`merge(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Merge.md): Merges two or more asynchronous sequence into a single asynchronous sequence producing the elements of all of the underlying asynchronous sequences.
|
||||
- [`zip(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Zip.md): Creates an asynchronous sequence of pairs built out of underlying asynchronous sequences.
|
||||
- [`joined(separator:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Joined.md): Concatenated elements of an asynchronous sequence of asynchronous sequences, inserting the given separator between each element.
|
||||
|
||||
#### Creating asynchronous sequences
|
||||
|
||||
- [`async`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Lazy.md): Create an asynchronous sequence composed from a synchronous sequence.
|
||||
- [`AsyncChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics.
|
||||
- [`AsyncThrowingChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics that can emit failures.
|
||||
|
||||
#### Performance optimized asynchronous iterators
|
||||
|
||||
- [`AsyncBufferedByteIterator`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/BufferedBytes.md): A highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
|
||||
|
||||
#### Other useful asynchronous sequences
|
||||
- [`adjacentPairs()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/AdjacentPairs.md): Collects tuples of adjacent elements.
|
||||
- [`chunks(...)` and `chunked(...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Chunked.md): Collect values into chunks.
|
||||
- [`compacted()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Compacted.md): Remove nil values from an asynchronous sequence.
|
||||
- [`removeDuplicates()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/RemoveDuplicates.md): Remove sequentially adjacent duplicate values.
|
||||
- [`interspersed(with:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Intersperse.md): Place a value between every two elements of an asynchronous sequence.
|
||||
|
||||
#### Asynchronous Sequences that transact in time
|
||||
|
||||
- [`debounce(for:tolerance:clock:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Debounce.md): Emit values after a quiescence period has been reached.
|
||||
- [`throttle(for:clock:reducing:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Throttle.md): Ensure a minimum interval has elapsed between events.
|
||||
- [`AsyncTimerSequence`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Timer.md): Emit the value of now at a given interval repeatedly.
|
||||
|
||||
#### Obtaining all values from an asynchronous sequence
|
||||
|
||||
- [`RangeReplaceableCollection.init(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new instance of a collection containing the elements of an asynchronous sequence.
|
||||
- [`Dictionary.init(uniqueKeysWithValues:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary from the key-value pairs in the given asynchronous sequence.
|
||||
- [`Dictionary.init(_:uniquingKeysWith:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary from the key-value pairs in the given asynchronous sequence, using a combining closure to determine the value for any duplicate keys.
|
||||
- [`Dictionary.init(grouping:by:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary whose keys are the groupings returned by the given closure and whose values are arrays of the elements that returned each key.
|
||||
- [`SetAlgebra.init(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new set from an asynchronous sequence of items.
|
||||
|
||||
#### Effects
|
||||
|
||||
Each algorithm has specific behavioral effects. For throwing effects these can either be if the sequence throws, does not throw, or rethrows errors. Sendability effects in some asynchronous sequences are conditional whereas others require the composed parts to all be sendable to satisfy a requirement of `Sendable`. The effects are [listed here](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Effects.md).
|
||||
|
||||
## Adding Swift Async Algorithms as a Dependency
|
||||
|
||||
To use the `AsyncAlgorithms` library in a SwiftPM project,
|
||||
add the following line to the dependencies in your `Package.swift` file:
|
||||
|
||||
```swift
|
||||
.package(url: "https://github.com/apple/swift-async-algorithms", from: "1.0.0"),
|
||||
```
|
||||
|
||||
Include `"AsyncAlgorithms"` as a dependency for your executable target:
|
||||
|
||||
```swift
|
||||
.target(name: "<target>", dependencies: [
|
||||
.product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
|
||||
]),
|
||||
```
|
||||
|
||||
Finally, add `import AsyncAlgorithms` to your source code.
|
||||
|
||||
## Getting Started
|
||||
|
||||
⚠️ Please note that this package requires Xcode 14 on macOS hosts. Previous versions of Xcode do not contain the required Swift version.
|
||||
|
||||
### Building/Testing Using Xcode on macOS
|
||||
|
||||
1. In the `swift-async-algorithms` directory run `swift build` or `swift test` accordingly
|
||||
|
||||
### Building/Testing on Linux
|
||||
|
||||
1. Download the most recent development toolchain for your Linux distribution
|
||||
2. Decompress the archive to a path in which the `swift` executable is in the binary search path environment variable (`$PATH`)
|
||||
3. In the `swift-async-algorithms` directory run `swift build` or `swift test` accordingly
|
||||
|
||||
## Source Stability
|
||||
|
||||
The Swift Async Algorithms package has a goal of being source stable as soon as possible; version numbers will follow [Semantic Versioning](https://semver.org/). Source breaking changes to public API can only land in a new major version.
|
||||
|
||||
The public API of version 1.0 of the `swift-async-algorithms` package will consist of non-underscored declarations that are marked `public` in the `AsyncAlgorithms` module. Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
|
||||
|
||||
Future minor versions of the package may introduce changes to these rules as needed.
|
||||
|
||||
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump.
|
||||
@@ -0,0 +1,89 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// An `AsyncSequence` that iterates over the adjacent pairs of the original
|
||||
/// original `AsyncSequence`.
|
||||
///
|
||||
/// ```
|
||||
/// for await (first, second) in (1...5).async.adjacentPairs() {
|
||||
/// print("First: \(first), Second: \(second)")
|
||||
/// }
|
||||
///
|
||||
/// // First: 1, Second: 2
|
||||
/// // First: 2, Second: 3
|
||||
/// // First: 3, Second: 4
|
||||
/// // First: 4, Second: 5
|
||||
/// ```
|
||||
///
|
||||
/// - Returns: An `AsyncSequence` where the element is a tuple of two adjacent elements
|
||||
/// or the original `AsyncSequence`.
|
||||
@inlinable
|
||||
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self> {
|
||||
AsyncAdjacentPairsSequence(self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that iterates over the adjacent pairs of the original
|
||||
/// `AsyncSequence`.
|
||||
@frozen
|
||||
public struct AsyncAdjacentPairsSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = (Base.Element, Base.Element)
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
/// The iterator for an `AsyncAdjacentPairsSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public typealias Element = (Base.Element, Base.Element)
|
||||
|
||||
@usableFromInline
|
||||
var base: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal var previousElement: Base.Element?
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base.AsyncIterator) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> (Base.Element, Base.Element)? {
|
||||
if previousElement == nil {
|
||||
previousElement = try await base.next()
|
||||
}
|
||||
|
||||
guard let previous = previousElement, let next = try await base.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
previousElement = next
|
||||
return (previous, next)
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncAdjacentPairsSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncAdjacentPairsSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,35 @@
|
||||
# ``AsyncAlgorithms``
|
||||
|
||||
**Swift Async Algorithms** is an open-source package of asynchronous sequence and advanced algorithms that involve concurrency, along with their related types.
|
||||
|
||||
## Overview
|
||||
|
||||
This package has three main goals:
|
||||
|
||||
- First-class integration with `async/await`
|
||||
- Provide a home for time-based algorithms
|
||||
- Be cross-platform and open source
|
||||
|
||||
## Topics
|
||||
|
||||
### Getting Started
|
||||
|
||||
- <doc:AdjacentPairs>
|
||||
- <doc:BufferedBytes>
|
||||
- <doc:Chain>
|
||||
- <doc:Channel>
|
||||
- <doc:Chunked>
|
||||
- <doc:Collections>
|
||||
- <doc:CombineLatest>
|
||||
- <doc:Compacted>
|
||||
- <doc:Debounce>
|
||||
- <doc:Effects>
|
||||
- <doc:Intersperse>
|
||||
- <doc:Joined>
|
||||
- <doc:Lazy>
|
||||
- <doc:Merge>
|
||||
- <doc:Reductions>
|
||||
- <doc:RemoveDuplicates>
|
||||
- <doc:Throttle>
|
||||
- <doc:Timer>
|
||||
- <doc:Zip>
|
||||
@@ -0,0 +1,49 @@
|
||||
# AdjacentPairs
|
||||
|
||||
* Author(s): [László Teveli](https://github.com/tevelee)
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAdjacentPairsSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestAdjacentPairs.swift)]
|
||||
|
||||
The `adjacentPairs()` API serve the purpose of collecting adjacent values. This operation is available for any `AsyncSequence` by calling the `adjacentPairs()` method.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `adjacentPairs()` algorithm produces elements of tuple (size of 2), containing a pair of the original `Element` type.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types. The returned `AsyncAdjacentPairsSequence` conditionally conforms to `Sendable`.
|
||||
|
||||
Its iterator keeps track of the previous element returned in the `next()` function and updates it in every turn.
|
||||
|
||||
```swift
|
||||
for await (first, second) in (1...5).async.adjacentPairs() {
|
||||
print("First: \(first), Second: \(second)")
|
||||
}
|
||||
|
||||
// First: 1, Second: 2
|
||||
// First: 2, Second: 3
|
||||
// First: 3, Second: 4
|
||||
// First: 4, Second: 5
|
||||
```
|
||||
|
||||
It composes well with the [Dictionary.init(_:uniquingKeysWith:)](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Collections.md) API that deals with `AsyncSequence` of tuples.
|
||||
|
||||
```swift
|
||||
Dictionary(uniqueKeysWithValues: url.lines.adjacentPairs())
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
This functionality is often written as a `zip` of a sequence together with itself, dropping its first element (`zip(source, source.dropFirst())`).
|
||||
|
||||
It's such a dominant use-case, the [swift-algorithms](https://github.com/apple/swift-algorithms) package also [introduced](https://github.com/apple/swift-algorithms/pull/119) it to its collection of algorithms.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The synchronous counterpart in [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md).
|
||||
@@ -0,0 +1,54 @@
|
||||
# AsyncBufferedByteIterator
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncBufferedByteIterator.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestBufferedByteIterator.swift)]
|
||||
|
||||
Provides a highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
|
||||
|
||||
This type provides infrastructure for creating `AsyncSequence` types with an `Element` of `UInt8` backed by file descriptors or similar read sources.
|
||||
|
||||
```swift
|
||||
struct AsyncBytes: AsyncSequence {
|
||||
public typealias Element = UInt8
|
||||
var handle: ReadableThing
|
||||
|
||||
internal init(_ readable: ReadableThing) {
|
||||
handle = readable
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
||||
return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
||||
// This runs once every 16384 invocations of next()
|
||||
return try await handle.read(into: buffer)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
```swift
|
||||
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
|
||||
public typealias Element = UInt8
|
||||
|
||||
public init(
|
||||
capacity: Int,
|
||||
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
||||
)
|
||||
|
||||
public mutating func next() async throws -> UInt8?
|
||||
}
|
||||
```
|
||||
|
||||
For each invocation of `next`, the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes, a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled, the read function is invoked to acquire the next filled buffer, at which point it takes a byte out of that buffer.
|
||||
|
||||
If the read function returns `0`, indicating it didn't read any more bytes, the iterator is decided to be finished and no additional invocations to the read function are made.
|
||||
|
||||
If the read function throws, the error will be thrown by the iteration. Subsequent invocations to the iterator will then return `nil` without invoking the read function.
|
||||
|
||||
If the task is cancelled during the iteration, the iteration will check the cancellation only in passes where the read function is invoked, and will throw a `CancellationError`.
|
||||
|
||||
### Naming
|
||||
|
||||
This type was named precisely for what it does: it is an asynchronous iterator that buffers bytes.
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Chain
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChain.swift)]
|
||||
|
||||
Chains two or more asynchronous sequences together sequentially where the elements from the resulting asynchronous sequence are comprised in order from the elements of the first asynchronous sequence and then the second (and so on) or until an error occurs.
|
||||
|
||||
This operation is available for all `AsyncSequence` types who share the same `Element` type.
|
||||
|
||||
```swift
|
||||
let preamble = [
|
||||
"// Some header to add as a preamble",
|
||||
"//",
|
||||
""
|
||||
].async
|
||||
let lines = chain(preamble, URL(fileURLWithPath: "/tmp/Sample.swift").lines)
|
||||
|
||||
for try await line in lines {
|
||||
print(line)
|
||||
}
|
||||
```
|
||||
|
||||
The above example shows how two `AsyncSequence` types can be chained together. In this case it prepends a preamble to the `lines` content of the file.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element
|
||||
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> where Base1.Element == Base2.Element {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
|
||||
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
|
||||
|
||||
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
|
||||
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
The `chain(_:...)` function takes two or more sequences as arguments.
|
||||
|
||||
The resulting `AsyncChainSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments also conform to it.
|
||||
|
||||
When any of the asynchronous sequences being chained together come to their end of iteration, the `AsyncChainSequence` iteration proceeds to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration, the `AsyncChainSequence` then ends its iteration.
|
||||
|
||||
At any point in time, if one of the comprising asynchronous sequences throws an error during iteration, the resulting `AsyncChainSequence` iteration will throw that error and end iteration. The throwing behavior of `AsyncChainSequence` is that it will throw when any of its comprising bases throw, and will not throw when all of its comprising bases do not throw.
|
||||
|
||||
### Naming
|
||||
|
||||
This function's and type's name match the term of art used in other languages and libraries.
|
||||
|
||||
This combinator function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md).
|
||||
@@ -0,0 +1,82 @@
|
||||
# Channel
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Channels/AsyncChannel.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Channels/AsyncThrowingChannel.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChannel.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
`AsyncStream` introduced a mechanism to send buffered elements from a context that doesn't use Swift concurrency into one that does. That design only addressed a portion of the potential use cases; the missing portion was the back pressure excerpted across two concurrency domains.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
To achieve a system that supports back pressure and allows for the communication of more than one value from one task to another we are introducing a new type, the _channel_. The channel will be a reference-type asynchronous sequence with an asynchronous sending capability that awaits the consumption of iteration. Each value sent by the channel will await the consumption of that value by iteration. That awaiting behavior will allow for the affordance of back pressure applied from the consumption site to be transmitted to the production site. This means that the rate of production cannot exceed the rate of consumption, and that the rate of consumption cannot exceed the rate of production. Sending a terminal event to the channel will instantly resume all pending operations for every producers and consumers.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Similar to the `AsyncStream` and `AsyncThrowingStream` types, the type for sending elements via back pressure will come in two versions. These two versions will account for the throwing nature or non-throwing nature of the elements being produced.
|
||||
|
||||
Each type will have functions to send elements and to send terminal events.
|
||||
|
||||
```swift
|
||||
public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async -> Element?
|
||||
}
|
||||
|
||||
public init(element elementType: Element.Type = Element.self)
|
||||
|
||||
public func send(_ element: Element) async
|
||||
public func finish()
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public init(element elementType: Element.Type = Element.self, failure failureType: Failure.Type = Failure.self)
|
||||
|
||||
public func send(_ element: Element) async
|
||||
public func fail(_ error: Error) where Failure == Error
|
||||
public func finish()
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
Channels are intended to be used as communication types between tasks. Particularly when one task produces values and another task consumes said values. On the one hand, the back pressure applied by `send(_:)` via the suspension/resume ensures that the production of values does not exceed the consumption of values from iteration. This method suspends after enqueuing the event and is resumed when the next call to `next()` on the `Iterator` is made. On the other hand, the call to `finish()` or `fail(_:)` immediately resumes all the pending operations for every producers and consumers. Thus, every suspended `send(_:)` operations instantly resume, so as every suspended `next()` operations by producing a nil value, or by throwing an error, indicating the termination of the iterations. Further calls to `send(_:)` will immediately resume. The calls to `send(:)` and `next()` will immediately resume when their supporting task is cancelled, other operations from other tasks will remain active.
|
||||
|
||||
```swift
|
||||
let channel = AsyncChannel<String>()
|
||||
Task {
|
||||
while let resultOfLongCalculation = doLongCalculations() {
|
||||
await channel.send(resultOfLongCalculation)
|
||||
}
|
||||
channel.finish()
|
||||
}
|
||||
|
||||
for await calculationResult in channel {
|
||||
print(calculationResult)
|
||||
}
|
||||
```
|
||||
|
||||
The example above uses a task to perform intense calculations; each of which are sent to the other task via the `send(_:)` method. That call to `send(_:)` returns when the next iteration of the channel is invoked.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
The use of the name "subject" was considered, due to its heritage as a name for a sync-to-async adapter type.
|
||||
|
||||
It was considered to make `AsyncChannel` and `AsyncThrowingChannel` actors, however due to the cancellation internals it would imply that these types would need to create new tasks to handle cancel events. The advantages of an actor in this particular case did not outweigh the impact of adjusting the implementations to be actors.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
`AsyncChannel` and `AsyncThrowingChannel` was heavily inspired from `Subject` but with the key difference that it uses Swift concurrency to apply back pressure.
|
||||
|
||||
https://developer.apple.com/documentation/combine/subject/
|
||||
@@ -0,0 +1,314 @@
|
||||
# Chunked
|
||||
|
||||
* Author(s): [Kevin Perry](https://github.com/kperryua)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedByGroupSequence.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountAndSignalSequence.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChunk.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
Grouping of values from an asynchronous sequence is often useful for tasks that involve writing those values efficiently or useful to handle specific structured data inputs.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Chunking operations can be broken down into a few distinct categories: grouping according to a binary predicate used to determine whether consecutive elements belong to the same group, projecting an element's property to determine the element's chunk membership, by discrete count, by another signal asynchronous sequence which indicates when the chunk should be delimited, or by a combination of count and signal.
|
||||
|
||||
### Grouping
|
||||
|
||||
Group chunks are determined by passing two consecutive elements to a closure which tests whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator receives the first element from the base sequence, it will immediately be added to a group. When it receives the second item, it tests whether the previous item and the current item belong to the same group. If they are not in the same group, then the iterator emits the first item's group and a new group is created containing the second item. Items declared to be in the same group accumulate until a new group is declared, or the iterator finds the end of the base sequence. When the base sequence terminates, the final group is emitted. If the base sequence throws an error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard any current group.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Collected: RangeReplaceableCollection>(
|
||||
into: Collected.Type,
|
||||
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
|
||||
) -> AsyncChunkedByGroupSequence<Self, Collected>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked(
|
||||
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
|
||||
) -> AsyncChunkedByGroupSequence<Self, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
Consider an example where an asynchronous sequence emits the following values: `10, 20, 30, 10, 40, 40, 10, 20`. Given the chunked operation to be defined as follows:
|
||||
|
||||
```swift
|
||||
let chunks = numbers.chunked { $0 <= $1 }
|
||||
for await numberChunk in chunks {
|
||||
print(numberChunk)
|
||||
}
|
||||
```
|
||||
|
||||
That snippet will produce the following values:
|
||||
|
||||
```swift
|
||||
[10, 20, 30]
|
||||
[10, 40, 40]
|
||||
[10, 20]
|
||||
```
|
||||
|
||||
While `Array` is the default type for chunks, thanks to the overload that takes a `RangeReplaceableCollection` type, the same sample can be chunked into instances of `ContiguousArray`, or any other `RangeReplaceableCollection` instead.
|
||||
|
||||
```swift
|
||||
let chunks = numbers.chunked(into: ContiguousArray.self) { $0 <= $1 }
|
||||
for await numberChunk in chunks {
|
||||
print(numberChunk)
|
||||
}
|
||||
```
|
||||
|
||||
That variant is the funnel method for the main implementation, which passes `[Element].self` in as the parameter.
|
||||
|
||||
### Projection
|
||||
|
||||
In some scenarios, chunks are determined not by comparing different elements, but by the element itself. This may be the case when the element has some sort of discriminator that can determine the chunk it belongs to. When two consecutive elements have different projections, the current chunk is emitted and a new chunk is created for the new element.
|
||||
|
||||
When the `AsyncChunkedOnProjectionSequence`'s iterator receives `nil` from the base sequence, it emits the final chunk. When the base sequence throws an error, the iterator discards the current chunk and rethrows that error.
|
||||
|
||||
Similarly to the `chunked(by:)` method this algorithm has an optional specification for the `RangeReplaceableCollection` which is used as the type of each chunk.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(
|
||||
into: Collected.Type,
|
||||
on projection: @escaping @Sendable (Element) -> Subject
|
||||
) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected>
|
||||
|
||||
public func chunked<Subject : Equatable>(
|
||||
on projection: @escaping @Sendable (Element) -> Subject
|
||||
) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
The following example shows how a sequence of names can be chunked together by their first characters.
|
||||
|
||||
```swift
|
||||
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
|
||||
let groupedNames = names.chunked(on: \.first!)
|
||||
for try await (firstLetter, names) in groupedNames {
|
||||
print(firstLetter)
|
||||
for name in names {
|
||||
print(" ", name)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A special property of this kind of projection chunking is that when an asynchronous sequence's elements are known to be ordered, the output of the chunking asynchronous sequence is suitable for initializing dictionaries using the `AsyncSequence` initializer for `Dictionary`. This is because the projection can be easily designed to match the sorting characteristics and thereby guarantee that the output matches the pattern of an array of pairs of unique "keys" with the chunks as the "values".
|
||||
|
||||
In the example above, if the names are known to be ordered then you can take advantage of the uniqueness of each "first character" projection to initialize a `Dictionary` like so:
|
||||
|
||||
```swift
|
||||
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
|
||||
let nameDirectory = try await Dictionary(uniqueKeysWithValues: names.chunked(on: \.first!))
|
||||
```
|
||||
|
||||
### Count or Signal
|
||||
|
||||
Sometimes chunks are determined not by the elements themselves, but by external factors. This final category enables limiting chunks to a specific size and/or delimiting them by another asynchronous sequence which is referred to as a "signal". This particular chunking family is useful for scenarios where the elements are more efficiently processed as chunks than individual elements, regardless of their values.
|
||||
|
||||
This family is broken down into two sub-families of methods: ones that employ a signal plus an optional count (which return an `AsyncChunksOfCountOrSignalSequence`), and the ones that only deal with counts (which return an `AsyncChunksOfCountSequence`). Both sub-families have `Collected` as their element type, or `Array` if unspecified. These sub-families have rethrowing behaviors; if the base `AsyncSequence` can throw then the chunks sequence can also throw. Likewise if the base `AsyncSequence` cannot throw then the chunks sequence also cannot throw.
|
||||
|
||||
##### Count only
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunks<Collected: RangeReplaceableCollection>(
|
||||
ofCount count: Int,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountSequence<Self, Collected>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunks(
|
||||
ofCount count: Int
|
||||
) -> AsyncChunksOfCountSequence<Self, [Element]>
|
||||
}
|
||||
```
|
||||
|
||||
If a chunk size limit is specified via an `ofCount` parameter, the sequence will produce chunks of type `Collected` with at most the specified number of elements. When a chunk reaches the given size, the asynchronous sequence will emit it immediately.
|
||||
|
||||
For example, an asynchronous sequence of `UInt8` bytes can be chunked into at most 1024-byte `Data` instances like so:
|
||||
|
||||
```swift
|
||||
let packets = bytes.chunks(ofCount: 1024, into: Data.self)
|
||||
for try await packet in packets {
|
||||
write(packet)
|
||||
}
|
||||
```
|
||||
|
||||
##### Signal only
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunked<Signal, Collected: RangeReplaceableCollection>(
|
||||
by signal: Signal,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<Signal>(
|
||||
by signal: Signal
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
|
||||
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
|
||||
by timer: AsyncTimerSequence<C>,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<C: Clock>(
|
||||
by timer: AsyncTimerSequence<C>
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
|
||||
}
|
||||
```
|
||||
|
||||
If a signal asynchronous sequence is specified, the chunking asynchronous sequence emits chunks whenever the signal emits. The signals element values are ignored. If the chunking asynchronous sequence hasn't accumulated any elements since its previous emission, then no value is emitted in response to the signal.
|
||||
|
||||
Since time is a frequent method of signaling desired delineations of chunks, there is a pre-specialized set of overloads that take `AsyncTimerSequence`. These allow shorthand initialization by using `AsyncTimerSequence`'s static member initializers.
|
||||
|
||||
As an example, an asynchronous sequence of log messages can be chunked into arrays of logs in four second segments like so:
|
||||
|
||||
```swift
|
||||
let fourSecondsOfLogs = logs.chunked(by: .repeating(every: .seconds(4)))
|
||||
for await chunk in fourSecondsOfLogs {
|
||||
send(chunk)
|
||||
}
|
||||
```
|
||||
|
||||
##### Count or Signal
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func chunks<Signal, Collected: RangeReplaceableCollection>(
|
||||
ofCount count: Int,
|
||||
or signal: Signal,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunks<Signal>(
|
||||
ofCount count: Int,
|
||||
or signal: Signal
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
|
||||
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
|
||||
by timer: AsyncTimerSequence<C>,
|
||||
into: Collected.Type
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
|
||||
where Collected.Element == Element
|
||||
|
||||
public func chunked<C: Clock>(
|
||||
by timer: AsyncTimerSequence<C>
|
||||
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
|
||||
}
|
||||
```
|
||||
|
||||
If both count and signal are specified, the chunking asynchronous sequence emits chunks whenever *either* the chunk reaches the specified size *or* the signal asynchronous sequence emits. When a signal causes a chunk to be emitted, the accumulated element count is reset back to zero. When an `AsyncTimerSequence` is used as a signal, the timer is started from the moment `next()` is called for the first time on `AsyncChunksOfCountOrSignalSequence`'s iterator, and it emits on a regular cadence from that moment. Note that the scheduling of the timer's emission is unaffected by any chunks emitted based on count.
|
||||
|
||||
Like the example above, this code emits up to 1024-byte `Data` instances, but a chunk will also be emitted every second.
|
||||
|
||||
```swift
|
||||
let packets = bytes.chunks(ofCount: 1024, or: .repeating(every: .seconds(1)), into: Data.self)
|
||||
for try await packet in packets {
|
||||
write(packet)
|
||||
}
|
||||
```
|
||||
|
||||
In any configuration of any of the chunking families, when the base asynchronous sequence terminates, one of two things will happen: 1) a partial chunk will be emitted, or 2) no chunk will be emitted (i.e. the iterator received no elements since the emission of the previous chunk). No elements from the base asynchronous sequence are ever discarded, except in the case of a thrown error.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
### Grouping
|
||||
|
||||
```swift
|
||||
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunkedByGroupSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
extension AsyncChunkedByGroupSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
```
|
||||
|
||||
### Projection
|
||||
|
||||
```swift
|
||||
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
public typealias Element = (Subject, Collected)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> (Subject, Collected)?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunkedOnProjectionSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable { }
|
||||
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Subject: Sendable { }
|
||||
```
|
||||
|
||||
### Count
|
||||
|
||||
```swift
|
||||
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
|
||||
|
||||
```
|
||||
|
||||
### Count or Signal
|
||||
|
||||
```swift
|
||||
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable
|
||||
where
|
||||
Collected.Element == Base.Element,
|
||||
Base: Sendable, Signal: Sendable,
|
||||
Base.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable,
|
||||
Base.Element: Sendable, Signal.Element: Sendable {
|
||||
public typealias Element = Collected
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async rethrows -> Collected?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
It was considered to make the chunked element to be an `AsyncSequence` instead of allowing collection into a `RangeReplaceableCollection` however it was determined that the throwing behavior of that would be complex to understand. If that hurdle could be overcome then that might be a future direction/consideration that would be worth exploring.
|
||||
|
||||
Variants of `chunked(by:)` (grouping) and `chunked(on:)` (projection) methods could be added that take delimiting `Signal` and `AsyncTimerSequence` inputs similar to `chunked(byCount:or:)`. However, it was decided that such functionality was likely to be underutilized and not worth the complication to the already broad surface area of `chunked` methods.
|
||||
|
||||
The naming of this family was considered to be `collect` which is used in APIs like `Combine`. This family of functions has distinct similarity to those APIs.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
This transformation function is a heavily inspired analog of the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md)
|
||||
@@ -0,0 +1,104 @@
|
||||
# Collection Initializers
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Dictionary.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/RangeReplaceableCollection.swift),
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/SetAlgebra.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestDictionary.swift),
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestRangeReplaceableCollection.swift),
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestSetAlgebra.swift),
|
||||
]
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
`Array`, `Dictionary` and `Set` are some of the most commonly-used data structures for storing collections of elements. Having a way to transition from an `AsyncSequence` to a collection is not only a useful shorthand but a powerful way of expressing direct intent for how to consume an `AsyncSequence`.
|
||||
|
||||
This type of functionality can be useful for examples and testing, and also for interfacing with existing APIs that expect a fully-formed collection before processing it.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Three categories of initializers will be added to provide initializers for those three primary types: `Array`, `Dictionary` and `Set`. However these initializers can be written in a generic fashion such that they can apply to all similar collections.
|
||||
|
||||
`RangeReplaceableCollection` will gain a new initializer that constructs a collection given an `AsyncSequence`. This will allow for creating arrays from asynchronous sequences but also allow for creating types like `Data` or `ContiguousArray`. Because of the nature of asynchronous sequences, this initializer must be asynchronous and declare that it rethrows errors from the base asynchronous sequence.
|
||||
|
||||
```swift
|
||||
extension RangeReplaceableCollection {
|
||||
public init<Source: AsyncSequence>(
|
||||
_ source: Source
|
||||
) async rethrows
|
||||
where Source.Element == Element
|
||||
}
|
||||
```
|
||||
|
||||
`Dictionary` will gain a family of new asynchronous, rethrowing initializers to parallel the existing `Sequence`-based initializers. The initializers will be asynchronous to facilitate uniquing keys and other tasks that may be asynchronous, in addition to the asynchronous initialization of the dictionaries.
|
||||
|
||||
```swift
|
||||
extension Dictionary {
|
||||
public init<S: AsyncSequence>(
|
||||
uniqueKeysWithValues keysAndValues: S
|
||||
) async rethrows
|
||||
where S.Element == (Key, Value)
|
||||
|
||||
public init<S: AsyncSequence>(
|
||||
_ keysAndValues: S,
|
||||
uniquingKeysWith combine: (Value, Value) async throws -> Value
|
||||
) async rethrows
|
||||
where S.Element == (Key, Value)
|
||||
|
||||
public init<S: AsyncSequence>(
|
||||
grouping values: S,
|
||||
by keyForValue: (S.Element) async throws -> Key
|
||||
) async rethrows
|
||||
where Value == [S.Element]
|
||||
}
|
||||
```
|
||||
|
||||
`SetAlgebra` will gain a new asynchronous, rethrowing initializer that constructs a `SetAlgebra` type given an `AsyncSequence`. This will allow for creating sets from asynchronous sequences and allow for creating types like `OptionSet` types or `IndexSet`.
|
||||
|
||||
```swift
|
||||
extension SetAlgebra {
|
||||
public init<Source: AsyncSequence>(
|
||||
_ source: Source
|
||||
) async rethrows
|
||||
where Source.Element == Element
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Each of the initializers is intended for uses where the `AsyncSequence` being used for initialization is known to be finite. Common uses include:
|
||||
|
||||
* Reading from files via the `AsyncBytes` style sequences or `lines` accessors.
|
||||
* Gathering elements produced by a `TaskGroup`.
|
||||
* Accessing a prefix of an indefinite `AsyncSequence`.
|
||||
|
||||
Each of the initializers will use the `for`-`await`-`in`/`for`-`try`-`await`-`in` syntax to iterate the sequence directly in the initializer. In addition each initializer relies on the `AsyncSequence` being passed in to properly respect cancellation. In the cases where cancellation is a potential, developers should be ready to either check immediately or be ready for initialization based on a partial sequence, depending on the behavior of the `AsyncSequence` being used.
|
||||
|
||||
### RangeReplaceableCollection
|
||||
|
||||
```swift
|
||||
let contents = try await Data(URL(fileURLWithPath: "/tmp/example.bin").resourceBytes)
|
||||
```
|
||||
|
||||
### Dictionary
|
||||
|
||||
```swift
|
||||
let table = await Dictionary(uniqueKeysWithValues: zip(keys, values))
|
||||
```
|
||||
|
||||
### SetAlgebra
|
||||
|
||||
```swift
|
||||
let allItems = await Set(items.prefix(10))
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
The spelling of these initializers could be expressed as a trailing conversion. However, that can lead to hard-to-read chains of operations. Functionally these all belong to the `reduce` family of functions, but due to source readability concerns they are more ergonomic for understanding what the code does by using the initializer patterns.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The direct inspiration for each initialization is from their standard library counterparts.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Combine Latest
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCombineLatest.swift)]
|
||||
|
||||
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
|
||||
|
||||
for try await (apple, nasdaq) in combineLatest(appleFeed, nasdaqFeed) {
|
||||
print("AAPL: \(apple) NASDAQ: \(nasdaq)")
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following combined events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | combined output |
|
||||
| ----------- | --------- | ---------- | ----------------------------- |
|
||||
| 11:40 AM | 173.91 | | |
|
||||
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | AAPL: 173.91 NASDAQ: 14218.34 |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2>
|
||||
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncCombineLatest2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncCombineLatestSequence` which is an asynchronous sequence.
|
||||
|
||||
Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must all be `Sendable`.
|
||||
|
||||
If any of the bases terminate before the first element is produced, then the `AsyncCombineLatestSequence` iteration can never be satisfied. So, if a base's iterator returns `nil` at the first iteration, then the `AsyncCombineLatestSequence` iterator immediately returns `nil` to signify a terminal state. In this particular case, any outstanding iteration of other bases will be cancelled. After the first element is produced ,this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the bases, the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
|
||||
|
||||
The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point (within the first iteration or afterwards), an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
|
||||
|
||||
### Naming
|
||||
|
||||
Since the inherent behavior of `combineLatest(_:...)` combines the latest values from multiple streams into a tuple the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
Combine latest often appears in libraries developed for processing events over time since the event ordering of a concept of "latest" only occurs when asynchrony is involved.
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of CombineLatest](https://reactivex.io/documentation/operators/combinelatest.html) as a top level function for combining Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of combineLatest](https://developer.apple.com/documentation/combine/publisher/combinelatest(_:)/) has an operator style method for combining Publishers.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Compacted
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCompactedSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCompacted.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
Just as it is common for `Sequence` types that contain optional values to need to `.compactMap { $0 }`, `AsyncSequence` types have the same use cases. This common task means that the type must employ a closure to test the optional value. This can be done more efficiently for both execution performance as well as API efficiency of typing.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Similar to the Swift Algorithms package we propose that a new method be added to `AsyncSequence` to fit this need.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
|
||||
where Element == Unwrapped?
|
||||
}
|
||||
```
|
||||
|
||||
This is equivalent to writing `.compactMap { $0 }` from a behavioral standpoint but is easier to reason about and is more efficient since it does not need to execute or store a closure.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `AsyncCompactedSequence` type from an effects standpoint works just like `AsyncCompactMapSequence`. When the base asynchronous sequence throws, the iteration of `AsyncCompactedSequence` can throw. Likewise if the base does not throw then the iteration of `AsyncCompactedSequence` does not throw. This type is conditionally `Sendable` when the base, base element, and base iterator are `Sendable.
|
||||
|
||||
```swift
|
||||
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
|
||||
where Base.Element == Element? {
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncCompactedSequence: Sendable
|
||||
where
|
||||
Base: Sendable, Base.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncCompactedSequence.Iterator: Sendable
|
||||
where
|
||||
Base: Sendable, Base.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md)
|
||||
@@ -0,0 +1,75 @@
|
||||
# Debounce
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Debounce/AsyncDebounceSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestDebounce.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to only emit values after a given period of time of inactivity, or "quiescence", has elapsed. This algorithm is commonly referred to as debouncing.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The debounce algorithm produces elements after a particular duration has passed between events. It transacts within a given tolerance applied to a clock. If values are produced by the base `AsyncSequence` during this quiet period, the debounce does not resume its next iterator until the period has elapsed with no values are produced or unless a terminal event is encountered.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types where the base type, iterator, and element are `Sendable`, since this algorithm will inherently create tasks to manage their timing of events. A shorthand implementation will be offered where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func debounce<C: Clock>(
|
||||
for interval: C.Instant.Duration,
|
||||
tolerance: C.Instant.Duration? = nil,
|
||||
clock: C
|
||||
) -> AsyncDebounceSequence<Self, C>
|
||||
|
||||
public func debounce(
|
||||
for interval: Duration,
|
||||
tolerance: Duration? = nil
|
||||
) -> AsyncDebounceSequence<Self, ContinuousClock>
|
||||
}
|
||||
```
|
||||
|
||||
This all boils down to a terse description of how to transform the asynchronous sequence over time.
|
||||
|
||||
```swift
|
||||
fastEvents.debounce(for: .seconds(1))
|
||||
```
|
||||
|
||||
In this case it transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second with no events to elapse before emitting a value.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm for debounce emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
|
||||
|
||||
```swift
|
||||
public struct AsyncDebounceSequence<Base: AsyncSequence, C: Clock>: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Base: Sendable {
|
||||
}
|
||||
|
||||
extension AsyncDebounceSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public mutating func next() async rethrows -> Base.Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
Since the stored types comprising `AsyncDebounceSequence` must be `Sendable`; `AsyncDebounceSequence` is unconditionally always `Sendable`.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
An alternative form of `debounce` could exist similar to the reductions of `throttle`, where a closure would be invoked for each value being set as the latest, and reducing a new value to produce for the debounce.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The naming for debounce comes as a term of art; originally this term was inspired by electronic circuitry. When a physical switch closes a circuit it can easily have a "bouncing" behavior (also called chatter) that is caused by electrical contact resistance and the physical bounce of springs associated with switches. That phenomenon is often addressed with additional circuits to de-bounce (removing the bouncing) by ensuring a certain quiescence occurs.
|
||||
|
||||
http://reactivex.io/documentation/operators/debounce.html
|
||||
|
||||
https://developer.apple.com/documentation/combine/publishers/debounce/
|
||||
@@ -0,0 +1,59 @@
|
||||
| Type | Throws | Sendability |
|
||||
|-----------------------------------------------------|--------------|-------------|
|
||||
| `AsyncAdjacentPairsSequence` | rethrows | Conditional |
|
||||
| `AsyncBufferedByteIterator` | throws | Not Sendable|
|
||||
| `AsyncBufferSequence` | rethrows | Conditional |
|
||||
| `AsyncBufferSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChain2Sequence` | rethrows | Conditional |
|
||||
| `AsyncChain2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChain3Sequence` | rethrows | Conditional |
|
||||
| `AsyncChain3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChannel` | non-throwing | Sendable |
|
||||
| `AsyncChannel.Iterator` | non-throwing | Not Sendable|
|
||||
| `AsyncChunkedByGroupSequence` | rethrows | Conditional |
|
||||
| `AsyncChunkedByGroupSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunkedOnProjectionSequence` | rethrows | Conditional |
|
||||
| `AsyncChunkedOnProjectionSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunksOfCountOrSignalSequence` | rethrows | Sendable |
|
||||
| `AsyncChunksOfCountOrSignalSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunksOfCountSequence` | rethrows | Conditional |
|
||||
| `AsyncChunksOfCountSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCombineLatest2Sequence` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCombineLatest3Sequence` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCompactedSequence` | rethrows | Conditional |
|
||||
| `AsyncCompactedSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncDebounceSequence` | rethrows | Sendable |
|
||||
| `AsyncDebounceSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncExclusiveReductionsSequence` | rethrows | Conditional |
|
||||
| `AsyncExclusiveReductionsSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncInclusiveReductionsSequence` | rethrows | Conditional |
|
||||
| `AsyncInclusiveReductionsSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncInterspersedSequence` | rethrows | Conditional |
|
||||
| `AsyncInterspersedSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncJoinedSequence` | rethrows | Conditional |
|
||||
| `AsyncJoinedSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncSyncSequence` | non-throwing | Conditional |
|
||||
| `AsyncSyncSequence.Iterator` | non-throwing | Not Sendable|
|
||||
| `AsyncLimitBuffer` | non-throwing | Sendable |
|
||||
| `AsyncMerge2Sequence` | rethrows | Sendable |
|
||||
| `AsyncMerge2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncMerge3Sequence` | rethrows | Sendable |
|
||||
| `AsyncMerge3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncRemoveDuplicatesSequence` | rethrows | Conditional |
|
||||
| `AsyncRemoveDuplicatesSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncThrottleSequence` | rethrows | Conditional |
|
||||
| `AsyncThrottleSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncThrowingChannel` | throws | Sendable |
|
||||
| `AsyncThrowingChannel.Iterator` | throws | Not Sendable|
|
||||
| `AsyncThrowingExclusiveReductionsSequence` | throws | Conditional |
|
||||
| `AsyncThrowingExclusiveReductionsSequence.Iterator` | throws | Not Sendable|
|
||||
| `AsyncThrowingInclusiveReductionsSequence` | throws | Conditional |
|
||||
| `AsyncThrowingInclusiveReductionsSequence.Iterator` | throws | Not Sendable|
|
||||
| `AsyncTimerSequence` | non-throwing | Sendable |
|
||||
| `AsyncTimerSequence.Iterator` | non-throwing | Not Sendable|
|
||||
| `AsyncZip2Sequence` | rethrows | Sendable |
|
||||
| `AsyncZip2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncZip3Sequence` | rethrows | Sendable |
|
||||
| `AsyncZip3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
@@ -0,0 +1,60 @@
|
||||
# Intersperse
|
||||
|
||||
[[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)]
|
||||
|
||||
Places a given value in between each element of the asynchronous sequence.
|
||||
|
||||
```swift
|
||||
let numbers = [1, 2, 3].async.interspersed(with: 0)
|
||||
for await number in numbers {
|
||||
print(number)
|
||||
}
|
||||
// prints 1 0 2 0 3
|
||||
|
||||
let empty = [].async.interspersed(with: 0)
|
||||
// await Array(empty) == []
|
||||
```
|
||||
|
||||
`interspersed(with:)` takes a separator value and inserts it in between every
|
||||
element in the asynchronous sequence.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
A new method is added to `AsyncSequence`:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
func interspersed(with separator: Element) -> AsyncInterspersedSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
The new `AsyncInterspersedSequence` type represents the asynchronous sequence
|
||||
when the separator is inserted between each element.
|
||||
|
||||
When the base asynchronous sequence can throw on iteration, `AsyncInterspersedSequence`
|
||||
will throw on iteration. When the base does not throw, the iteration of
|
||||
`AsyncInterspersedSequence` does not throw either.
|
||||
|
||||
`AsyncInterspersedSequence` is conditionally `Sendable` when the base asynchronous
|
||||
sequence is `Sendable` and the element is also `Sendable`.
|
||||
|
||||
### Naming
|
||||
|
||||
This method’s and type’s name match the term of art used in other languages
|
||||
and libraries.
|
||||
|
||||
This method is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Intersperse.md).
|
||||
|
||||
### Comparison with other languages
|
||||
|
||||
**[Haskell][Haskell]:** Has an `intersperse` function which takes an element
|
||||
and a list and 'intersperses' that element between the elements of the list.
|
||||
|
||||
**[Rust][Rust]:** Has a function called `intersperse` to insert a particular
|
||||
value between each element.
|
||||
|
||||
<!-- Link references for other languages -->
|
||||
|
||||
[Haskell]: https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-List.html#v:intersperse
|
||||
[Rust]: https://docs.rs/itertools/0.9.0/itertools/trait.Itertools.html#method.intersperse
|
||||
@@ -0,0 +1,127 @@
|
||||
# Joined
|
||||
|
||||
* Author(s): [Kevin Perry](https://github.com/kperryua)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncJoinedSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestJoin.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
Concatenates an asynchronous sequence of asynchronous sequences that share an `Element` type together sequentially where the elements from the resulting asynchronous sequence are comprised in order from the elements of the first asynchronous sequence and then the second (and so on) or until an error occurs. Similar to `chain()`, except the number of asynchronous sequences to concatenate is not known up front.
|
||||
|
||||
Optionally allows inserting the elements of a separator asynchronous sequence in between each of the other sequences.
|
||||
|
||||
```swift
|
||||
let sequenceOfURLs: AsyncSequence<URL> = ...
|
||||
let sequenceOfLines = sequenceOfURLs.map { $0.lines }
|
||||
let joinedWithSeparator = sequenceOfLines.joined(separator: ["===================="].async)
|
||||
|
||||
for try await lineOrSeparator in joinedWithSeparator {
|
||||
print(lineOrSeparator)
|
||||
}
|
||||
```
|
||||
|
||||
This example shows how an `AsyncSequence` of `URL`s can be turned into an `AsyncSequence` of the lines of each of those files in sequence, with a separator line in between each file.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
public func joined() -> AsyncJoinedSequence<Self> {
|
||||
return AsyncJoinedSequence(self)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
|
||||
return AsyncJoinedBySeparatorSequence(self, separator: separator)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
```swift
|
||||
public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
|
||||
public typealias Element = Base.Element.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Base.Element.Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncJoinedSequence: Sendable
|
||||
where
|
||||
Base: Sendable,
|
||||
Base.Element: Sendable,
|
||||
Base.Element.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable,
|
||||
Base.Element.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncJoinedSequence.Iterator: Sendable
|
||||
where
|
||||
Base: Sendable,
|
||||
Base.Element: Sendable,
|
||||
Base.Element.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable,
|
||||
Base.Element.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
```swift
|
||||
public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: AsyncSequence>: AsyncSequence
|
||||
where Base.Element: AsyncSequence, Separator.Element == Base.Element.Element {
|
||||
public typealias Element = Base.Element.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Base.Element.Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncJoinedBySeparatorSequence: Sendable
|
||||
where
|
||||
Base: Sendable,
|
||||
Base.Element: Sendable,
|
||||
Base.Element.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable,
|
||||
Separator: Sendable,
|
||||
Separator.AsyncIterator: Sendable,
|
||||
Base.Element.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncJoinedBySeparatorSequence.Iterator: Sendable
|
||||
where
|
||||
Base: Sendable,
|
||||
Base.Element: Sendable,
|
||||
Base.Element.Element: Sendable,
|
||||
Base.AsyncIterator: Sendable,
|
||||
Separator: Sendable,
|
||||
Separator.AsyncIterator: Sendable,
|
||||
Base.Element.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
The resulting `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments conform.
|
||||
|
||||
When any of the asynchronous sequences being joined together come to their end of iteration, the `Joined` sequence iteration proceeds to the separator asynchronous sequence, if any. When the separator asynchronous sequence terminates, or if no separator was specified, it proceeds on to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration the `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` then ends its iteration. At any point in time if one of the comprising asynchronous sequences ever throws an error during iteration the `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` iteration will throw that error and end iteration.
|
||||
|
||||
## Future Directions
|
||||
|
||||
The Swift Algorithms package has [additional synchronous variants of `joined()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Joined.md). It is conceivable to bring asynchronous variants of those over to `AsyncSequence`.
|
||||
|
||||
The variant that takes a single element as a separator is straightforward, but can be trivially replicated with `[element].async`. However, it may be beneficial for performance to reimplement this directly.
|
||||
|
||||
There is another variant that takes a closure that allows one to customize the separator based on the return value of a closure. That closure is passed each of the two consecutive asynchronous sequences (not the two neighboring elements in consecutive sequences). This variant arguably has the greatest utility when the sequence type conforms to `Collection`, allowing either the `count` or any arbitrary element to be obtained directly. With `AsyncSequence`, it is less likely that this function with provide a similar level of utility, so it has been omitted.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
Because `joined()` is essentially identical to `flatMap { $0 }`, it was considered that this should be called `flatten()` instead. However, it is preferable to follow the lead of the Swift standard library's `joined()` method.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The Swift standard library has functions on synchronous sequences ([`joined()`](https://developer.apple.com/documentation/swift/sequence/1641166-joined), [`joined(separator:)`](https://developer.apple.com/documentation/swift/sequence/2431985-joined)) that perform similar (but synchronous) tasks.
|
||||
@@ -0,0 +1,39 @@
|
||||
# AsyncSyncSequence
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncSyncSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)]
|
||||
|
||||
Converts a non-asynchronous sequence into an asynchronous one.
|
||||
|
||||
This operation is available for all `Sequence` types.
|
||||
|
||||
```swift
|
||||
let numbers = [1, 2, 3, 4].async
|
||||
let characters = "abcde".async
|
||||
```
|
||||
|
||||
This transformation can be useful to test operations specifically available on `AsyncSequence` but also is useful
|
||||
to combine with other `AsyncSequence` types to provide well known sources of data.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `.async` property returns an `AsyncSyncSequence` that is generic upon the base `Sequence` it was constructed from.
|
||||
|
||||
```swift
|
||||
extension Sequence {
|
||||
public var async: AsyncSyncSequence<Self> { get }
|
||||
}
|
||||
|
||||
public struct AsyncSyncSequence<Base: Sequence>: AsyncSequence {
|
||||
...
|
||||
}
|
||||
|
||||
extension AsyncSyncSequence: Sendable where Base: Sendable { }
|
||||
extension AsyncSyncSequence.Iterator: Sendable where Base.Iterator: Sendable { }
|
||||
```
|
||||
|
||||
### Naming
|
||||
|
||||
This property's and type's name match the naming approaches in the Swift standard library. The property is named with a
|
||||
succinct name in inspiration from `.lazy`, and the type is named in reference to the lazy behavior of the constructed
|
||||
`AsyncSequence`.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Merge
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestMerge.swift)]
|
||||
|
||||
Merges two or more asynchronous sequences sharing the same element type into one singular asynchronous sequence.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines.map { "AAPL: " + $0 }
|
||||
let nasdaqFeed = URL(string:"http://www.example.com/ticker?symbol=^IXIC")!.lines.map { "^IXIC: " + $0 }
|
||||
|
||||
for try await ticker in merge(appleFeed, nasdaqFeed) {
|
||||
print(ticker)
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following merged events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | merged output |
|
||||
| ----------- | --------- | ---------- | --------------- |
|
||||
| 11:40 AM | 173.91 | | AAPL: 173.91 |
|
||||
| 12:25 AM | | 14236.78 | ^IXIC: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | ^IXIC: 14218.34 |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 |
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
|
||||
|
||||
public func merge<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncMerge3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncMerge2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element, Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `merge(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncMergeSequence` which is an asynchronous sequence.
|
||||
|
||||
Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`.
|
||||
|
||||
When iterating a `AsyncMergeSequence`, the sequence terminates when all of the base asynchronous sequences terminate, since this means there is no potential for any further elements to be produced.
|
||||
|
||||
The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
|
||||
|
||||
### Naming
|
||||
|
||||
Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence, the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of Merge](https://reactivex.io/documentation/operators/merge.html) as a top level function for merging Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of merge(with:)](https://developer.apple.com/documentation/combine/publisher/merge(with:)-7qt71/) as an operator style method for merging Publishers.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Reductions
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[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)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
The family of algorithms for reduce are useful for converting a sequence or asynchronous sequence into a single value, but that can elide important intermediate information. The _reductions_ algorithm is often called "scan", but this name does not convey its heritage to the family of reducing.
|
||||
|
||||
There are two strategies that are usable for creating continuous reductions: exclusive reductions and inclusive reductions:
|
||||
|
||||
* Exclusive reductions take a value and incorporate values into that initial value. A common example is reductions by appending to an array.
|
||||
* Inclusive reductions transact only on the values provided. A common example is adding numbers.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Exclusive reductions come in two variants: transforming by application, or transformation via mutation. This replicates the same interface as `reduce(_:_:)` and `reduce(into:_:)`. Unlike the `reduce` algorithms, the `reductions` algorithm also comes in two flavors: throwing or non throwing transformations.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func reductions<Result>(
|
||||
_ initial: Result,
|
||||
_ transform: @Sendable @escaping (Result, Element) async -> Result
|
||||
) -> AsyncExclusiveReductionsSequence<Self, Result>
|
||||
|
||||
public func reductions<Result>(
|
||||
into initial: Result,
|
||||
_ transform: @Sendable @escaping (inout Result, Element) async -> Void
|
||||
) -> AsyncExclusiveReductionsSequence<Self, Result>
|
||||
}
|
||||
|
||||
extension AsyncSequence {
|
||||
public func reductions<Result>(
|
||||
_ initial: Result,
|
||||
_ transform: @Sendable @escaping (Result, Element) async throws -> Result
|
||||
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
|
||||
|
||||
public func reductions<Result>(
|
||||
into initial: Result,
|
||||
_ transform: @Sendable @escaping (inout Result, Element) async throws -> Void
|
||||
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
|
||||
}
|
||||
```
|
||||
|
||||
These APIs can be used to reduce an initial value progressively or reduce into an initial value via mutation. In practice, a common use case for reductions is to mutate a collection by appending values.
|
||||
|
||||
```swift
|
||||
characters.reductions(into: "") { $0.append($1) }
|
||||
```
|
||||
|
||||
If the characters being produced asynchronously are `"a", "b", "c"`, then the iteration of the reductions is `"a", "ab", "abc"`.
|
||||
|
||||
Inclusive reductions do not have an initial value and therefore do not need an additional variations beyond the throwing and non throwing flavors.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async -> Element
|
||||
) -> AsyncInclusiveReductionsSequence<Self>
|
||||
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
|
||||
) -> AsyncThrowingInclusiveReductionsSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
This is often used for scenarios like a running tally or other similar cases.
|
||||
|
||||
```swift
|
||||
numbers.reductions { $0 + $1 }
|
||||
```
|
||||
|
||||
In the above example, if the numbers are a sequence of `1, 2, 3, 4`, the produced values would be `1, 3, 6, 10`.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The exclusive reduction variants come in two distinct cases: non-throwing and throwing. These both have corresponding types to encompass that throwing behavior.
|
||||
|
||||
For non-throwing exclusive reductions, the element type of the sequence is the result of the reduction transform. `AsyncExclusiveReductionsSequence` will throw if the base asynchronous sequence throws, and will not throw if the base does not throws.
|
||||
|
||||
```swift
|
||||
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: AsyncSequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
|
||||
extension AsyncExclusiveReductionsSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Element: Sendable { }
|
||||
```
|
||||
|
||||
The sendability behavior of `AsyncExclusiveReductionsSequence` is such that when the base, base iterator, and element are `Sendable` then `AsyncExclusiveReductionsSequence` is `Sendable`.
|
||||
|
||||
```swift
|
||||
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable, Element: Sendable { }
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
One alternate name for `reductions` was to name it `scan`; however the naming from the Swift Algorithms package offers considerably more inference to the heritage of what family of functions this algorithm belongs to.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md)
|
||||
@@ -0,0 +1,93 @@
|
||||
# RemoveDuplicates
|
||||
|
||||
* Author(s): [Kevin Perry](https://github.com/kperryua)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncRemoveDuplicatesSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestRemoveDuplicates.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
When processing values over time it is definitely possible that the same value may occur in a row. When the distinctness of the presence value is not needed it is useful to consider the values over time that are differing from the last. Particularly this can be expressed as removing duplicate values either in the case as they are directly `Equatable` or by a predicate.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The `removeDuplicates()` and `removeDuplicates(by:)` APIs serve this purpose of removing duplicate values that occur. These algorithms test against the previous value and if the latest iteration of the base `AsyncSequence` is the same as the last it invokes `next()` again. The resulting `AsyncRemoveDuplicatesSequence` will ensure that no duplicate values occur next to each other. This should not be confused with only emitting unique new values; where each value is tested against a collected set of values.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: Equatable {
|
||||
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self>
|
||||
}
|
||||
|
||||
extension AsyncSequence {
|
||||
public func removeDuplicates(
|
||||
by predicate: @escaping @Sendable (Element, Element) async -> Bool
|
||||
) -> AsyncRemoveDuplicatesSequence<Self>
|
||||
|
||||
public func removeDuplicates(
|
||||
by predicate: @escaping @Sendable (Element, Element) async throws -> Bool
|
||||
) -> AsyncThrowingRemoveDuplicatesSequence<Self>
|
||||
}
|
||||
```
|
||||
|
||||
The `removeDuplicates` family comes in three variants. One variant is conditional upon the `Element` type being `Equatable`. This variation is a shorthand for writing `.removeDuplicates { $0 == $1 }`. The next variation is the closure version that allows for custom predicates to be applied. This algorithm allows for the cases where the elements themselves may not be equatable but portions of the element may be compared. Lastly is the variation that allows for comparison when the comparison method may throw.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
In the cases where the `Element` type is `Equatable` or the non-trowing predicate variant these utilize the type `AsyncRemoveDuplicatesSequence`. The throwing predicate variant uses `AsyncThrowingRemoveDuplicatesSequence`. Both of these types are conditionally `Sendable` when the base, base element, and base iterator are `Sendable`
|
||||
|
||||
The `AsyncRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and will not throw if the base asynchronous sequence does not throw.
|
||||
|
||||
```swift
|
||||
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncRemoveDuplicatesSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncRemoveDuplicatesSequence.Iterator: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
The `AsyncThrowingRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and still may throw if the base asynchronous sequence does not throw due to the predicate having the potential of throwing.
|
||||
|
||||
```swift
|
||||
|
||||
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrowingRemoveDuplicatesSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
|
||||
extension AsyncThrowingRemoveDuplicatesSequence.Iterator: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
|
||||
```
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
An alternative algorithm for uniqueness was considered but was discounted since it does not directly belong to this particular family of methods.
|
||||
|
||||
The name of this method could be considered to belong to the `filter` family and could refer directly to the repetitions. There is distinct merit to considering the name to be `filterRepetitions` or `removeRepetitions`. Likewise the terminology of `drop` also has merit.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
The Combine framework has a [function for publishers](https://developer.apple.com/documentation/combine/publisher/removeduplicates()/) that performs a similar task.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Throttle
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrottleSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestThrottle.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to emit values after a given period has elapsed. These emitted values can be reduced from the values encountered during the waiting period. This algorithm is commonly referred to as throttling.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The throttle algorithm produces elements such that at least a specific interval has elapsed between them. It transacts by measuring against a specific clock. If values are produced by the base `AsyncSequence` the throttle does not resume its next iterator until the period has elapsed or unless a terminal event is encountered.
|
||||
|
||||
The interface for this algorithm is available on all `AsyncSequence` types. Unlike other algorithms like `debounce`, the throttle algorithm does not need to create additional tasks or require any sort of tolerance because the interval is just measured. A shorthand implementation will be offered in conjunction where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values. An additional shorthand is offered to reduce the values such that it provides a "latest" or "earliest" value, representing the leading or trailing edge of a throttled region of production of events.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func throttle<C: Clock, Reduced>(
|
||||
for interval: C.Instant.Duration,
|
||||
clock: C,
|
||||
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
|
||||
) -> AsyncThrottleSequence<Self, C, Reduced>
|
||||
|
||||
public func throttle<Reduced>(
|
||||
for interval: Duration,
|
||||
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
|
||||
) -> AsyncThrottleSequence<Self, ContinuousClock, Reduced>
|
||||
|
||||
public func throttle<C: Clock>(
|
||||
for interval: C.Instant.Duration,
|
||||
clock: C,
|
||||
latest: Bool = true
|
||||
) -> AsyncThrottleSequence<Self, C, Element>
|
||||
|
||||
public func throttle(
|
||||
for interval: Duration,
|
||||
latest: Bool = true
|
||||
) -> AsyncThrottleSequence<Self, ContinuousClock, Element>
|
||||
}
|
||||
```
|
||||
|
||||
This all boils down to a terse description of how to transform the asynchronous sequence over time.
|
||||
|
||||
```swift
|
||||
fastEvents.throttle(for: .seconds(1))
|
||||
```
|
||||
|
||||
In this case, the throttle transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second to elapse before emitting a value.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm for throttle emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
|
||||
|
||||
```swift
|
||||
public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
|
||||
}
|
||||
|
||||
extension AsyncThrottleSequence: AsyncSequence {
|
||||
public typealias Element = Reduced
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Reduced?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncThrottleSequence: Sendable
|
||||
where Base: Sendable, Element: Sendable { }
|
||||
extension AsyncThrottleSequence.Iterator: Sendable
|
||||
where Base.AsyncIterator: Sendable { }
|
||||
```
|
||||
|
||||
The `AsyncThrottleSequence` and its `Iterator` are conditionally `Sendable` if the base types comprising it are `Sendable`.
|
||||
|
||||
The time in which events are measured are from the previous emission if present. If a duration has elapsed between the last emission and the point in time the throttle is measured then that duration is counted as elapsed. The first element is considered not throttled because no interval can be constructed from the start to the first element.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
It was considered to only provide the "latest" style APIs, however the reduction version grants more flexibility and can act as a funnel to the implementations of `latest`.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
http://reactivex.io/documentation/operators/sample.html
|
||||
|
||||
https://developer.apple.com/documentation/combine/publishers/throttle/
|
||||
@@ -0,0 +1,51 @@
|
||||
# Timer
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncTimerSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestTimer.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
Producing elements at regular intervals can be useful for composing with other algorithms. These can range from invoking code at specific times to using those regular intervals as a delimiter of events. There are other cases this exists in APIs however those do not currently interact with Swift concurrency. These existing APIs are ones like `Timer` or `DispatchTimer` but are bound to internal clocks that are not extensible.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
We propose to add a new type; `AsyncTimerSequence` which utilizes the new `Clock`, `Instant` and `Duration` types. This allows the interaction of the timer to custom implementations of types adopting `Clock`.
|
||||
|
||||
This asynchronous sequence will produce elements of the clock's `Instant` type after the interval has elapsed. That instant will be the `now` at the time that the sleep has resumed. For each invocation to `next()` the `AsyncTimerSequence.Iterator` will calculate the next deadline to resume and pass that and the tolerance to the clock. If at any point in time the task executing that iteration is cancelled the iteration will return `nil` from the call to `next()`.
|
||||
|
||||
```swift
|
||||
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
|
||||
public typealias Element = C.Instant
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async -> C.Instant?
|
||||
}
|
||||
|
||||
public init(
|
||||
interval: C.Instant.Duration,
|
||||
tolerance: C.Instant.Duration? = nil,
|
||||
clock: C
|
||||
)
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
extension AsyncTimerSequence where C == SuspendingClock {
|
||||
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock>
|
||||
}
|
||||
|
||||
extension AsyncTimerSequence: Sendable { }
|
||||
extension AsyncTimerSequence.Iterator: Sendable { }
|
||||
```
|
||||
|
||||
Since all the types comprising `AsyncTimerSequence` are `Sendable` these types are also `Sendable`.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
https://developer.apple.com/documentation/foundation/timer
|
||||
|
||||
https://developer.apple.com/documentation/foundation/timer/timerpublisher
|
||||
@@ -0,0 +1,85 @@
|
||||
# Zip
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip3Sequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestZip.swift)]
|
||||
|
||||
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
|
||||
|
||||
```swift
|
||||
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines
|
||||
let nasdaqFeed = URL(string: "http://www.example.com/ticker?symbol=^IXIC")!.lines
|
||||
|
||||
for try await (apple, nasdaq) in zip(appleFeed, nasdaqFeed) {
|
||||
print("APPL: \(apple) NASDAQ: \(nasdaq)")
|
||||
}
|
||||
```
|
||||
|
||||
Given some sample inputs the following zipped events can be expected.
|
||||
|
||||
| Timestamp | appleFeed | nasdaqFeed | combined output |
|
||||
| ----------- | --------- | ---------- | ----------------------------- |
|
||||
| 11:40 AM | 173.91 | | |
|
||||
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
|
||||
| 12:40 AM | | 14218.34 | |
|
||||
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
|
||||
|
||||
## Detailed Design
|
||||
|
||||
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
|
||||
|
||||
```swift
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncZip2Sequence<Base1, Base2>
|
||||
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncZip3Sequence<Base1, Base2, Base3>
|
||||
|
||||
public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable
|
||||
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async rethrows -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `zip(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncZipSequence` which is an asynchronous sequence.
|
||||
|
||||
Each iteration of an `AsyncZipSequence` will await for all base iterators to produce a value. This iteration will be done concurrently to produce a singular tuple result. If any of the base iterations terminates by returning `nil` from its iteration, the `AsyncZipSequence` iteration is immediately considered unsatisfiable and returns `nil` and all iterations of other bases will be cancelled. If any iteration of the bases throws an error, then the other iterations concurrently running are cancelled and the produced error is rethrown, terminating the iteration.
|
||||
|
||||
`AsyncZipSequence` requires that the iterations are done concurrently. This means that the base sequences, their elements, and iterators must all be `Sendable`. That makes `AsyncZipSequence` inherently `Sendable`.
|
||||
|
||||
The source of throwing of `AsyncZipSequence` is determined by its bases. That means that if any base can throw an error then the iteration of the `AsyncZipSequence` can throw. If no bases can throw, then the `AsyncZipSequence` does not throw.
|
||||
|
||||
### Naming
|
||||
|
||||
The `zip(_:...)` function takes its name from the Swift standard library function of the same name. The `AsyncZipSequence` family of types take their name from the same family from the standard library for the type returned by `zip(_:_:)`. The one difference is that this asynchronous version allows for the affordance of recognizing the eventual variadic generic need of expanding a zip of more than just two sources.
|
||||
|
||||
It is common in some libraries to have a `ZipMap` or some other combination of `zip` and `map`. This is a common usage pattern, but leaving a singular type for composition feels considerably more approachable.
|
||||
|
||||
### Comparison with other libraries
|
||||
|
||||
**Swift** The swift standard library has an [API definition of zip](https://developer.apple.com/documentation/swift/1541125-zip) as a top level function for combining two sequences.
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of Zip](https://reactivex.io/documentation/operators/zip.html) as a top level function for combining Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of zip](https://developer.apple.com/documentation/combine/publisher/zip(_:)/) as an operator style method for combining Publishers.
|
||||
@@ -0,0 +1,141 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// An `AsyncIterator` that provides a convenient and high-performance implementation
|
||||
/// of a common architecture for `AsyncSequence` of `UInt8`, otherwise known as byte streams.
|
||||
///
|
||||
/// Bytes are read into an internal buffer of `capacity` bytes via the
|
||||
/// `readFunction`. Invoking `next()` returns bytes from the internal buffer until it's
|
||||
/// empty, and then suspends and awaits another invocation of `readFunction` to
|
||||
/// refill. If `readFunction` returns 0 (indicating nothing was read), `next()` will
|
||||
/// return `nil` from then on. Cancellation is checked before each invocation of
|
||||
/// `readFunction`, which means that many calls to `next()` will not check for
|
||||
/// cancellation.
|
||||
///
|
||||
/// A typical use of `AsyncBufferedByteIterator` looks something like this:
|
||||
///
|
||||
/// struct AsyncBytes: AsyncSequence {
|
||||
/// public typealias Element = UInt8
|
||||
/// var handle: ReadableThing
|
||||
///
|
||||
/// internal init(_ readable: ReadableThing) {
|
||||
/// handle = readable
|
||||
/// }
|
||||
///
|
||||
/// public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
||||
/// return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
||||
/// // This runs once every 16384 invocations of next()
|
||||
/// return try await handle.read(into: buffer)
|
||||
/// }
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
///
|
||||
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol {
|
||||
public typealias Element = UInt8
|
||||
@usableFromInline var buffer: _AsyncBytesBuffer
|
||||
|
||||
/// Creates an asynchronous buffered byte iterator with a specified capacity and read function.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - capacity: The maximum number of bytes that a single invocation of `readFunction` may produce.
|
||||
/// This is the allocated capacity of the backing buffer for iteration; the value must be greater than 0.
|
||||
/// - readFunction: The function for refilling the buffer.
|
||||
public init(
|
||||
capacity: Int,
|
||||
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
||||
) {
|
||||
buffer = _AsyncBytesBuffer(capacity: capacity, readFunction: readFunction)
|
||||
}
|
||||
|
||||
/// Reads a byte out of the buffer if available. When no bytes are available, this will trigger
|
||||
/// the read function to reload the buffer and then return the next byte from that buffer.
|
||||
@inlinable @inline(__always)
|
||||
public mutating func next() async throws -> UInt8? {
|
||||
return try await buffer.next()
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncBufferedByteIterator: Sendable { }
|
||||
|
||||
@frozen @usableFromInline
|
||||
internal struct _AsyncBytesBuffer {
|
||||
@usableFromInline
|
||||
final class Storage {
|
||||
fileprivate let buffer: UnsafeMutableRawBufferPointer
|
||||
|
||||
init(
|
||||
capacity: Int
|
||||
) {
|
||||
precondition(capacity > 0)
|
||||
buffer = UnsafeMutableRawBufferPointer.allocate(
|
||||
byteCount: capacity,
|
||||
alignment: MemoryLayout<AnyObject>.alignment
|
||||
)
|
||||
}
|
||||
|
||||
deinit {
|
||||
buffer.deallocate()
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline internal let storage: Storage
|
||||
@usableFromInline internal var nextPointer: UnsafeRawPointer
|
||||
@usableFromInline internal var endPointer: UnsafeRawPointer
|
||||
|
||||
internal let readFunction: @Sendable (UnsafeMutableRawBufferPointer) async throws -> Int
|
||||
internal var finished = false
|
||||
|
||||
@usableFromInline init(
|
||||
capacity: Int,
|
||||
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
|
||||
) {
|
||||
let s = Storage(capacity: capacity)
|
||||
self.readFunction = readFunction
|
||||
storage = s
|
||||
nextPointer = UnsafeRawPointer(s.buffer.baseAddress!)
|
||||
endPointer = nextPointer
|
||||
}
|
||||
|
||||
@inline(never) @usableFromInline
|
||||
internal mutating func reloadBufferAndNext() async throws -> UInt8? {
|
||||
if finished {
|
||||
return nil
|
||||
}
|
||||
try Task.checkCancellation()
|
||||
do {
|
||||
let readSize: Int = try await readFunction(storage.buffer)
|
||||
if readSize == 0 {
|
||||
finished = true
|
||||
nextPointer = endPointer
|
||||
return nil
|
||||
}
|
||||
nextPointer = UnsafeRawPointer(storage.buffer.baseAddress!)
|
||||
endPointer = nextPointer + readSize
|
||||
} catch {
|
||||
finished = true
|
||||
nextPointer = endPointer
|
||||
throw error
|
||||
}
|
||||
return try await next()
|
||||
}
|
||||
|
||||
@inlinable @inline(__always)
|
||||
internal mutating func next() async throws -> UInt8? {
|
||||
if _fastPath(nextPointer != endPointer) {
|
||||
let byte = nextPointer.load(fromByteOffset: 0, as: UInt8.self)
|
||||
nextPointer = nextPointer + 1
|
||||
return byte
|
||||
}
|
||||
return try await reloadBufferAndNext()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Returns a new asynchronous sequence that iterates over the two given asynchronous sequences, one
|
||||
/// followed by the other.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - s1: The first asynchronous sequence.
|
||||
/// - s2: The second asynchronous sequence.
|
||||
/// - Returns: An asynchronous sequence that iterates first over the elements of `s1`, and
|
||||
/// then over the elements of `s2`.
|
||||
@inlinable
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element {
|
||||
AsyncChain2Sequence(s1, s2)
|
||||
}
|
||||
|
||||
/// A concatenation of two asynchronous sequences with the same element type.
|
||||
@frozen
|
||||
public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> where Base1.Element == Base2.Element {
|
||||
@usableFromInline
|
||||
let base1: Base1
|
||||
|
||||
@usableFromInline
|
||||
let base2: Base2
|
||||
|
||||
@usableFromInline
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain2Sequence: AsyncSequence {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
/// The iterator for a `AsyncChain2Sequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var base1: Base1.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
var base2: Base2.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
do {
|
||||
if let value = try await base1?.next() {
|
||||
return value
|
||||
} else {
|
||||
base1 = nil
|
||||
}
|
||||
return try await base2?.next()
|
||||
} catch {
|
||||
base1 = nil
|
||||
base2 = nil
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChain2Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,100 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Returns a new asynchronous sequence that iterates over the three given asynchronous sequences, one
|
||||
/// followed by the other.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - s1: The first asynchronous sequence.
|
||||
/// - s2: The second asynchronous sequence.
|
||||
/// - s3: The third asynchronous sequence.
|
||||
/// - Returns: An asynchronous sequence that iterates first over the elements of `s1`, and
|
||||
/// then over the elements of `s2`, and then over the elements of `s3`
|
||||
@inlinable
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3> {
|
||||
AsyncChain3Sequence(s1, s2, s3)
|
||||
}
|
||||
|
||||
/// A concatenation of three asynchronous sequences with the same element type.
|
||||
@frozen
|
||||
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
|
||||
@usableFromInline
|
||||
let base1: Base1
|
||||
|
||||
@usableFromInline
|
||||
let base2: Base2
|
||||
|
||||
@usableFromInline
|
||||
let base3: Base3
|
||||
|
||||
@usableFromInline
|
||||
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain3Sequence: AsyncSequence {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
/// The iterator for a `AsyncChain3Sequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var base1: Base1.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
var base2: Base2.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
var base3: Base3.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator, _ base3: Base3.AsyncIterator) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
do {
|
||||
if let value = try await base1?.next() {
|
||||
return value
|
||||
} else {
|
||||
base1 = nil
|
||||
}
|
||||
if let value = try await base2?.next() {
|
||||
return value
|
||||
} else {
|
||||
base2 = nil
|
||||
}
|
||||
return try await base3?.next()
|
||||
} catch {
|
||||
base1 = nil
|
||||
base2 = nil
|
||||
base3 = nil
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChain3Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,122 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2021 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection`
|
||||
/// type by testing if elements belong in the same group.
|
||||
@inlinable
|
||||
public func chunked<Collected: RangeReplaceableCollection>(into: Collected.Type, by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool) -> AsyncChunkedByGroupSequence<Self, Collected> where Collected.Element == Element {
|
||||
AsyncChunkedByGroupSequence(self, grouping: belongInSameGroup)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks by testing if elements belong in the same group.
|
||||
@inlinable
|
||||
public func chunked(by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool) -> AsyncChunkedByGroupSequence<Self, [Element]> {
|
||||
chunked(into: [Element].self, by: belongInSameGroup)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that chunks by testing if two elements belong to the same group.
|
||||
///
|
||||
/// Group chunks are determined by passing two consecutive elements to a closure which tests
|
||||
/// whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator
|
||||
/// receives the first element from the base sequence, it will immediately be added to a group. When
|
||||
/// it receives the second item, it tests whether the previous item and the current item belong to the
|
||||
/// same group. If they are not in the same group, then the iterator emits the first item's group and a
|
||||
/// new group is created containing the second item. Items declared to be in the same group
|
||||
/// accumulate until a new group is declared, or the iterator finds the end of the base sequence.
|
||||
/// When the base sequence terminates, the final group is emitted. If the base sequence throws an
|
||||
/// error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard
|
||||
/// any current group.
|
||||
///
|
||||
/// let numbers = [10, 20, 30, 10, 40, 40, 10, 20].async
|
||||
/// let chunks = numbers.chunked { $0 <= $1 }
|
||||
/// for await numberChunk in chunks {
|
||||
/// print(numberChunk)
|
||||
/// }
|
||||
/// // prints
|
||||
/// // [10, 20, 30]
|
||||
/// // [10, 40, 40]
|
||||
/// // [10, 20]
|
||||
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
/// The iterator for a `AsyncChunkedByGroupSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@usableFromInline
|
||||
var base: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
let grouping: @Sendable (Base.Element, Base.Element) -> Bool
|
||||
|
||||
@usableFromInline
|
||||
init(base: Base.AsyncIterator, grouping: @escaping @Sendable (Base.Element, Base.Element) -> Bool) {
|
||||
self.base = base
|
||||
self.grouping = grouping
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
var hangingNext: Base.Element?
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Collected? {
|
||||
var firstOpt = hangingNext
|
||||
if firstOpt == nil {
|
||||
firstOpt = try await base.next()
|
||||
} else {
|
||||
hangingNext = nil
|
||||
}
|
||||
|
||||
guard let first = firstOpt else {
|
||||
return nil
|
||||
}
|
||||
|
||||
var result: Collected = .init()
|
||||
result.append(first)
|
||||
|
||||
var prev = first
|
||||
while let next = try await base.next() {
|
||||
if grouping(prev, next) {
|
||||
result.append(next)
|
||||
prev = next
|
||||
} else {
|
||||
hangingNext = next
|
||||
break
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
|
||||
@usableFromInline
|
||||
let grouping : @Sendable (Base.Element, Base.Element) -> Bool
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base, grouping: @escaping @Sendable (Base.Element, Base.Element) -> Bool) {
|
||||
self.base = base
|
||||
self.grouping = grouping
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base: base.makeAsyncIterator(), grouping: grouping)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunkedByGroupSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunkedByGroupSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,102 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2021 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type on the uniqueness of a given subject.
|
||||
@inlinable
|
||||
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(into: Collected.Type, on projection: @escaping @Sendable (Element) -> Subject) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected> {
|
||||
AsyncChunkedOnProjectionSequence(self, projection: projection)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks on the uniqueness of a given subject.
|
||||
@inlinable
|
||||
public func chunked<Subject : Equatable>(on projection: @escaping @Sendable (Element) -> Subject) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]> {
|
||||
chunked(into: [Element].self, on: projection)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that chunks on a subject when it differs from the last element.
|
||||
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
public typealias Element = (Subject, Collected)
|
||||
|
||||
/// The iterator for a `AsyncChunkedOnProjectionSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@usableFromInline
|
||||
var base: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
let projection: @Sendable (Base.Element) -> Subject
|
||||
|
||||
@usableFromInline
|
||||
init(base: Base.AsyncIterator, projection: @escaping @Sendable (Base.Element) -> Subject) {
|
||||
self.base = base
|
||||
self.projection = projection
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
var hangingNext: (Subject, Base.Element)?
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> (Subject, Collected)? {
|
||||
var firstOpt = hangingNext
|
||||
if firstOpt == nil {
|
||||
let nextOpt = try await base.next()
|
||||
if let next = nextOpt {
|
||||
firstOpt = (projection(next), next)
|
||||
}
|
||||
} else {
|
||||
hangingNext = nil
|
||||
}
|
||||
|
||||
guard let first = firstOpt else {
|
||||
return nil
|
||||
}
|
||||
|
||||
var result: Collected = .init()
|
||||
result.append(first.1)
|
||||
|
||||
while let next = try await base.next() {
|
||||
let subj = projection(next)
|
||||
if subj == first.0 {
|
||||
result.append(next)
|
||||
} else {
|
||||
hangingNext = (subj, next)
|
||||
break
|
||||
}
|
||||
}
|
||||
return (first.0, result)
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
|
||||
@usableFromInline
|
||||
let projection : @Sendable (Base.Element) -> Subject
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base, projection: @escaping @Sendable (Base.Element) -> Subject) {
|
||||
self.base = base
|
||||
self.projection = projection
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base: base.makeAsyncIterator(), projection: projection)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunkedOnProjectionSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,133 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2021 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type of a given count or when a signal `AsyncSequence` produces an element.
|
||||
public func chunks<Signal, Collected: RangeReplaceableCollection>(ofCount count: Int, or signal: Signal, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal> where Collected.Element == Element {
|
||||
AsyncChunksOfCountOrSignalSequence(self, count: count, signal: signal)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given count or when a signal `AsyncSequence` produces an element.
|
||||
public func chunks<Signal>(ofCount count: Int, or signal: Signal) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal> {
|
||||
chunks(ofCount: count, or: signal, into: [Element].self)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type when a signal `AsyncSequence` produces an element.
|
||||
public func chunked<Signal, Collected: RangeReplaceableCollection>(by signal: Signal, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal> where Collected.Element == Element {
|
||||
AsyncChunksOfCountOrSignalSequence(self, count: nil, signal: signal)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks when a signal `AsyncSequence` produces an element.
|
||||
public func chunked<Signal>(by signal: Signal) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal> {
|
||||
chunked(by: signal, into: [Element].self)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type of a given count or when an `AsyncTimerSequence` fires.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func chunks<C: Clock, Collected: RangeReplaceableCollection>(ofCount count: Int, or timer: AsyncTimerSequence<C>, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>> where Collected.Element == Element {
|
||||
AsyncChunksOfCountOrSignalSequence(self, count: count, signal: timer)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given count or when an `AsyncTimerSequence` fires.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func chunks<C: Clock>(ofCount count: Int, or timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
|
||||
chunks(ofCount: count, or: timer, into: [Element].self)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type when an `AsyncTimerSequence` fires.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(by timer: AsyncTimerSequence<C>, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>> where Collected.Element == Element {
|
||||
AsyncChunksOfCountOrSignalSequence(self, count: nil, signal: timer)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks when an `AsyncTimerSequence` fires.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func chunked<C: Clock>(by timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
|
||||
chunked(by: timer, into: [Element].self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that chunks elements into collected `RangeReplaceableCollection` instances by either count or a signal from another `AsyncSequence`.
|
||||
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable where Collected.Element == Base.Element, Base: Sendable, Signal: Sendable, Base.Element: Sendable, Signal.Element: Sendable {
|
||||
|
||||
public typealias Element = Collected
|
||||
|
||||
enum Either {
|
||||
case element(Base.Element)
|
||||
case terminal
|
||||
case signal
|
||||
}
|
||||
|
||||
/// The iterator for a `AsyncChunksOfCountOrSignalSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
typealias EitherMappedBase = AsyncMapSequence<Base, Either>
|
||||
typealias EitherMappedSignal = AsyncMapSequence<Signal, Either>
|
||||
typealias ChainedBase = AsyncChain2Sequence<EitherMappedBase, AsyncSyncSequence<[Either]>>
|
||||
typealias Merged = AsyncMerge2Sequence<ChainedBase, EitherMappedSignal>
|
||||
|
||||
let count: Int?
|
||||
var iterator: Merged.AsyncIterator
|
||||
var terminated = false
|
||||
|
||||
init(iterator: Merged.AsyncIterator, count: Int?) {
|
||||
self.count = count
|
||||
self.iterator = iterator
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Collected? {
|
||||
guard !terminated else {
|
||||
return nil
|
||||
}
|
||||
var result: Collected?
|
||||
while let next = try await iterator.next() {
|
||||
switch next {
|
||||
case .element(let element):
|
||||
if result == nil {
|
||||
result = Collected()
|
||||
}
|
||||
result!.append(element)
|
||||
if result?.count == count {
|
||||
return result
|
||||
}
|
||||
case .terminal:
|
||||
terminated = true
|
||||
return result
|
||||
case .signal:
|
||||
if result != nil {
|
||||
return result
|
||||
}
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
let base: Base
|
||||
let signal: Signal
|
||||
let count: Int?
|
||||
init(_ base: Base, count: Int?, signal: Signal) {
|
||||
if let count = count {
|
||||
precondition(count > 0)
|
||||
}
|
||||
|
||||
self.base = base
|
||||
self.count = count
|
||||
self.signal = signal
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
|
||||
return Iterator(iterator: merge(chain(base.map { Either.element($0) }, [.terminal].async), signal.map { _ in Either.signal }).makeAsyncIterator(), count: count)
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunksOfCountOrSignalSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,92 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2021 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` of a given count.
|
||||
@inlinable
|
||||
public func chunks<Collected: RangeReplaceableCollection>(ofCount count: Int, into: Collected.Type) -> AsyncChunksOfCountSequence<Self, Collected> where Collected.Element == Element {
|
||||
AsyncChunksOfCountSequence(self, count: count)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that creates chunks of a given count.
|
||||
@inlinable
|
||||
public func chunks(ofCount count: Int) -> AsyncChunksOfCountSequence<Self, [Element]> {
|
||||
chunks(ofCount: count, into: [Element].self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that chunks elements into `RangeReplaceableCollection` instances of at least a given count.
|
||||
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
/// The iterator for a `AsyncChunksOfCountSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@usableFromInline
|
||||
var base: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
let count: Int
|
||||
|
||||
@usableFromInline
|
||||
init(base: Base.AsyncIterator, count: Int) {
|
||||
self.base = base
|
||||
self.count = count
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Collected? {
|
||||
guard let first = try await base.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
if count == 1 {
|
||||
return Collected(CollectionOfOne(first))
|
||||
}
|
||||
|
||||
var result: Collected = .init()
|
||||
result.append(first)
|
||||
|
||||
while let next = try await base.next() {
|
||||
result.append(next)
|
||||
if result.count == count {
|
||||
break
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
|
||||
@usableFromInline
|
||||
let count : Int
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base, count: Int) {
|
||||
precondition(count > 0)
|
||||
self.base = base
|
||||
self.count = count
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base: base.makeAsyncIterator(), count: count)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunksOfCountSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,72 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Returns a new `AsyncSequence` that iterates over every non-nil element from the
|
||||
/// original `AsyncSequence`.
|
||||
///
|
||||
/// Produces the same result as `c.compactMap { $0 }`.
|
||||
///
|
||||
/// - Returns: An `AsyncSequence` where the element is the unwrapped original
|
||||
/// element and iterates over every non-nil element from the original
|
||||
/// `AsyncSequence`.
|
||||
@inlinable
|
||||
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
|
||||
where Element == Unwrapped? {
|
||||
AsyncCompactedSequence(self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that iterates over every non-nil element from the original
|
||||
/// `AsyncSequence`.
|
||||
@frozen
|
||||
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
|
||||
where Base.Element == Element? {
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
/// The iterator for an `AsyncCompactedSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var base: Base.AsyncIterator
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base.AsyncIterator) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
while let wrapped = try await base.next() {
|
||||
guard let some = wrapped else { continue }
|
||||
return some
|
||||
}
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncCompactedSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncCompactedSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,117 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
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.
|
||||
///
|
||||
/// - 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.
|
||||
@inlinable
|
||||
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async -> Result) -> AsyncExclusiveReductionsSequence<Self, Result> {
|
||||
reductions(into: initial) { result, element in
|
||||
result = await transform(result, element)
|
||||
}
|
||||
}
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// - 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.
|
||||
@inlinable
|
||||
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async -> Void) -> AsyncExclusiveReductionsSequence<Self, Result> {
|
||||
AsyncExclusiveReductionsSequence(self, initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence of applying a transform to the element of an asynchronous sequence and the
|
||||
/// previously transformed result.
|
||||
@frozen
|
||||
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let initial: Element
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (inout Element, Base.Element) async -> Void
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async -> Void) {
|
||||
self.base = base
|
||||
self.initial = initial
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: AsyncSequence {
|
||||
/// The iterator for an `AsyncExclusiveReductionsSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
var current: Element?
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (inout Element, Base.Element) async -> Void
|
||||
|
||||
@inlinable
|
||||
init(_ iterator: Base.AsyncIterator, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async -> Void) {
|
||||
self.iterator = iterator
|
||||
self.current = initial
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
guard let result = current else { return nil }
|
||||
let value = try await iterator.next()
|
||||
if let value = value {
|
||||
var result = result
|
||||
await transform(&result, value)
|
||||
current = result
|
||||
return result
|
||||
} else {
|
||||
current = nil
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncExclusiveReductionsSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,90 @@
|
||||
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
|
||||
/// producing an asynchronous sequence consisting of the initial value followed
|
||||
/// by these results.
|
||||
///
|
||||
/// ```
|
||||
/// let runningTotal = [1, 2, 3, 4].async.reductions(+)
|
||||
/// print(await Array(runningTotal))
|
||||
///
|
||||
/// // prints [1, 3, 6, 10]
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter transform: A closure that combines the previously reduced
|
||||
/// result and the next element in the receiving sequence, and returns
|
||||
/// the result.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@inlinable
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async -> Element
|
||||
) -> AsyncInclusiveReductionsSequence<Self> {
|
||||
AsyncInclusiveReductionsSequence(self, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using a given closure.
|
||||
@frozen
|
||||
public struct AsyncInclusiveReductionsSequence<Base: AsyncSequence> {
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (Base.Element, Base.Element) async -> Base.Element
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base, transform: @Sendable @escaping (Base.Element, Base.Element) async -> Base.Element) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInclusiveReductionsSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncInclusiveReductionsSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal var element: Base.Element?
|
||||
|
||||
@usableFromInline
|
||||
internal let transform: @Sendable (Base.Element, Base.Element) async -> Base.Element
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
_ iterator: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Element, Base.Element) async -> Base.Element
|
||||
) {
|
||||
self.iterator = iterator
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Base.Element? {
|
||||
guard let previous = element else {
|
||||
element = try await iterator.next()
|
||||
return element
|
||||
}
|
||||
guard let next = try await iterator.next() else { return nil }
|
||||
element = await transform(previous, next)
|
||||
return element
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInclusiveReductionsSequence: Sendable where Base: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncInclusiveReductionsSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,147 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements with a separator.
|
||||
@inlinable
|
||||
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
|
||||
return AsyncJoinedBySeparatorSequence(self, separator: separator)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that concatenates `AsyncSequence` elements with a separator.
|
||||
public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence, Separator.Element == Base.Element.Element {
|
||||
public typealias Element = Base.Element.Element
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
/// The iterator for an `AsyncJoinedBySeparatorSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
enum State {
|
||||
@usableFromInline
|
||||
enum SeparatorState {
|
||||
case initial(Separator)
|
||||
case partialAsync(Separator.AsyncIterator, ContiguousArray<Element>)
|
||||
case cached(ContiguousArray<Element>)
|
||||
case partialCached(ContiguousArray<Element>.Iterator, ContiguousArray<Element>)
|
||||
|
||||
@usableFromInline
|
||||
func startSeparator() -> SeparatorState {
|
||||
switch self {
|
||||
case .initial(let separatorSequence):
|
||||
return .partialAsync(separatorSequence.makeAsyncIterator(), [])
|
||||
case .cached(let array):
|
||||
return .partialCached(array.makeIterator(), array)
|
||||
default:
|
||||
fatalError("Invalid separator sequence state")
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
func next() async rethrows -> (Element?, SeparatorState) {
|
||||
switch self {
|
||||
case .partialAsync(var separatorIterator, var cache):
|
||||
guard let next = try await separatorIterator.next() else {
|
||||
return (nil, .cached(cache))
|
||||
}
|
||||
cache.append(next)
|
||||
return (next, .partialAsync(separatorIterator, cache))
|
||||
case .partialCached(var cacheIterator, let cache):
|
||||
guard let next = cacheIterator.next() else {
|
||||
return (nil, .cached(cache))
|
||||
}
|
||||
return (next, .partialCached(cacheIterator, cache))
|
||||
default:
|
||||
fatalError("Invalid separator sequence state")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
case initial(Base.AsyncIterator, Separator)
|
||||
case sequence(Base.AsyncIterator, Base.Element.AsyncIterator, SeparatorState)
|
||||
case separator(Base.AsyncIterator, SeparatorState, Base.Element)
|
||||
case terminal
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
var state: State
|
||||
|
||||
@usableFromInline
|
||||
init(_ iterator: Base.AsyncIterator, separator: Separator) {
|
||||
state = .initial(iterator, separator)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Base.Element.Element? {
|
||||
do {
|
||||
switch state {
|
||||
case .terminal:
|
||||
return nil
|
||||
case .initial(var outerIterator, let separator):
|
||||
guard let innerSequence = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
let innerIterator = innerSequence.makeAsyncIterator()
|
||||
state = .sequence(outerIterator, innerIterator, .initial(separator))
|
||||
return try await next()
|
||||
case .sequence(var outerIterator, var innerIterator, let separatorState):
|
||||
if let item = try await innerIterator.next() {
|
||||
state = .sequence(outerIterator, innerIterator, separatorState)
|
||||
return item
|
||||
}
|
||||
|
||||
guard let nextInner = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
|
||||
state = .separator(outerIterator, separatorState.startSeparator(), nextInner)
|
||||
return try await next()
|
||||
case .separator(let iterator, let separatorState, let nextBase):
|
||||
let (itemOpt, newSepState) = try await separatorState.next()
|
||||
guard let item = itemOpt else {
|
||||
state = .sequence(iterator, nextBase.makeAsyncIterator(), newSepState)
|
||||
return try await next()
|
||||
}
|
||||
state = .separator(iterator, newSepState, nextBase)
|
||||
return item
|
||||
}
|
||||
} catch {
|
||||
state = .terminal
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base, separator: Separator) {
|
||||
self.base = base
|
||||
self.separator = separator
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base.makeAsyncIterator(), separator: separator)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncJoinedBySeparatorSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, Separator: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncJoinedBySeparatorSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,97 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements
|
||||
@inlinable
|
||||
public func joined() -> AsyncJoinedSequence<Self> {
|
||||
return AsyncJoinedSequence(self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that concatenates`AsyncSequence` elements
|
||||
@frozen
|
||||
public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
|
||||
public typealias Element = Base.Element.Element
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
/// The iterator for an `AsyncJoinedSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
enum State {
|
||||
case initial(Base.AsyncIterator)
|
||||
case sequence(Base.AsyncIterator, Base.Element.AsyncIterator)
|
||||
case terminal
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
var state: State
|
||||
|
||||
@inlinable
|
||||
init(_ iterator: Base.AsyncIterator) {
|
||||
state = .initial(iterator)
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Base.Element.Element? {
|
||||
do {
|
||||
switch state {
|
||||
case .terminal:
|
||||
return nil
|
||||
case .initial(var outerIterator):
|
||||
guard let innerSequence = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
let innerIterator = innerSequence.makeAsyncIterator()
|
||||
state = .sequence(outerIterator, innerIterator)
|
||||
return try await next()
|
||||
case .sequence(var outerIterator, var innerIterator):
|
||||
if let item = try await innerIterator.next() {
|
||||
state = .sequence(outerIterator, innerIterator)
|
||||
return item
|
||||
}
|
||||
|
||||
guard let nextInner = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
|
||||
state = .sequence(outerIterator, nextInner.makeAsyncIterator())
|
||||
return try await next()
|
||||
}
|
||||
} catch {
|
||||
state = .terminal
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncJoinedSequence: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncJoinedSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,151 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence where Element: Equatable {
|
||||
/// Creates an asynchronous sequence that omits repeated elements.
|
||||
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self> {
|
||||
AsyncRemoveDuplicatesSequence(self) { lhs, rhs in
|
||||
lhs == rhs
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that omits repeated elements by testing them with a predicate.
|
||||
public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async -> Bool) -> AsyncRemoveDuplicatesSequence<Self> {
|
||||
return AsyncRemoveDuplicatesSequence(self, predicate: predicate)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that omits repeated elements by testing them with an error-throwing predicate.
|
||||
public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async throws -> Bool) -> AsyncThrowingRemoveDuplicatesSequence<Self> {
|
||||
return AsyncThrowingRemoveDuplicatesSequence(self, predicate: predicate)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that omits repeated elements by testing them with a predicate.
|
||||
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncRemoveDuplicatesSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@usableFromInline
|
||||
var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
let predicate: @Sendable (Element, Element) async -> Bool
|
||||
|
||||
@usableFromInline
|
||||
var last: Element?
|
||||
|
||||
@usableFromInline
|
||||
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
|
||||
self.iterator = iterator
|
||||
self.predicate = predicate
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
guard let last = last else {
|
||||
last = try await iterator.next()
|
||||
return last
|
||||
}
|
||||
while let element = try await iterator.next() {
|
||||
if await !predicate(last, element) {
|
||||
self.last = element
|
||||
return element
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let predicate: @Sendable (Element, Element) async -> Bool
|
||||
|
||||
init(_ base: Base, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
|
||||
self.base = base
|
||||
self.predicate = predicate
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that omits repeated elements by testing them with an error-throwing predicate.
|
||||
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncThrowingRemoveDuplicatesSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@usableFromInline
|
||||
var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
let predicate: @Sendable (Element, Element) async throws -> Bool
|
||||
|
||||
@usableFromInline
|
||||
var last: Element?
|
||||
|
||||
@usableFromInline
|
||||
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async throws -> Bool) {
|
||||
self.iterator = iterator
|
||||
self.predicate = predicate
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async throws -> Element? {
|
||||
guard let last = last else {
|
||||
last = try await iterator.next()
|
||||
return last
|
||||
}
|
||||
while let element = try await iterator.next() {
|
||||
if try await !predicate(last, element) {
|
||||
self.last = element
|
||||
return element
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let predicate: @Sendable (Element, Element) async throws -> Bool
|
||||
|
||||
init(_ base: Base, predicate: @escaping @Sendable (Element, Element) async throws -> Bool) {
|
||||
self.base = base
|
||||
self.predicate = predicate
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
extension AsyncRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
|
||||
extension AsyncThrowingRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncRemoveDuplicatesSequence.Iterator: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingRemoveDuplicatesSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,72 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension Sequence {
|
||||
/// An asynchronous sequence containing the same elements as this sequence,
|
||||
/// but on which operations, such as `map` and `filter`, are
|
||||
/// implemented asynchronously.
|
||||
@inlinable
|
||||
public var async: AsyncSyncSequence<Self> {
|
||||
AsyncSyncSequence(self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence composed from a synchronous sequence.
|
||||
///
|
||||
/// Asynchronous lazy sequences can be used to interface existing or pre-calculated
|
||||
/// data to interoperate with other asynchronous sequences and algorithms based on
|
||||
/// asynchronous sequences.
|
||||
///
|
||||
/// This functions similarly to `LazySequence` by accessing elements sequentially
|
||||
/// in the iterator's `next()` method.
|
||||
@frozen
|
||||
public struct AsyncSyncSequence<Base: Sequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var iterator: Base.Iterator?
|
||||
|
||||
@usableFromInline
|
||||
init(_ iterator: Base.Iterator) {
|
||||
self.iterator = iterator
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async -> Base.Element? {
|
||||
if !Task.isCancelled, let value = iterator?.next() {
|
||||
return value
|
||||
} else {
|
||||
iterator = nil
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncSyncSequence: Sendable where Base: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncSyncSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,116 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2021 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func _throttle<C: Clock, Reduced>(for interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> _AsyncThrottleSequence<Self, C, Reduced> {
|
||||
_AsyncThrottleSequence(self, interval: interval, clock: clock, reducing: reducing)
|
||||
}
|
||||
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func _throttle<Reduced>(for interval: Duration, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> _AsyncThrottleSequence<Self, ContinuousClock, Reduced> {
|
||||
_throttle(for: interval, clock: .continuous, reducing: reducing)
|
||||
}
|
||||
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func _throttle<C: Clock>(for interval: C.Instant.Duration, clock: C, latest: Bool = true) -> _AsyncThrottleSequence<Self, C, Element> {
|
||||
_throttle(for: interval, clock: clock) { previous, element in
|
||||
if latest {
|
||||
return element
|
||||
} else {
|
||||
return previous ?? element
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func _throttle(for interval: Duration, latest: Bool = true) -> _AsyncThrottleSequence<Self, ContinuousClock, Element> {
|
||||
_throttle(for: interval, clock: .continuous, latest: latest)
|
||||
}
|
||||
}
|
||||
|
||||
/// A rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public struct _AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
|
||||
let base: Base
|
||||
let interval: C.Instant.Duration
|
||||
let clock: C
|
||||
let reducing: @Sendable (Reduced?, Base.Element) async -> Reduced
|
||||
|
||||
init(_ base: Base, interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Base.Element) async -> Reduced) {
|
||||
self.base = base
|
||||
self.interval = interval
|
||||
self.clock = clock
|
||||
self.reducing = reducing
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension _AsyncThrottleSequence: AsyncSequence {
|
||||
public typealias Element = Reduced
|
||||
|
||||
/// The iterator for an `AsyncThrottleSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
var base: Base.AsyncIterator
|
||||
var last: C.Instant?
|
||||
let interval: C.Instant.Duration
|
||||
let clock: C
|
||||
let reducing: @Sendable (Reduced?, Base.Element) async -> Reduced
|
||||
|
||||
init(_ base: Base.AsyncIterator, interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Base.Element) async -> Reduced) {
|
||||
self.base = base
|
||||
self.interval = interval
|
||||
self.clock = clock
|
||||
self.reducing = reducing
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Reduced? {
|
||||
var reduced: Reduced?
|
||||
let start = last ?? clock.now
|
||||
repeat {
|
||||
guard let element = try await base.next() else {
|
||||
if reduced != nil, let last {
|
||||
// ensure the rate of elements never exceeds the given interval
|
||||
let amount = interval - last.duration(to: clock.now)
|
||||
if amount > .zero {
|
||||
try? await clock.sleep(until: clock.now.advanced(by: amount), tolerance: nil)
|
||||
}
|
||||
}
|
||||
// the last value is unable to have any subsequent
|
||||
// values so always return the last reduction
|
||||
return reduced
|
||||
}
|
||||
let reduction = await reducing(reduced, element)
|
||||
let now = clock.now
|
||||
if start.duration(to: now) >= interval || last == nil {
|
||||
last = now
|
||||
return reduction
|
||||
} else {
|
||||
reduced = reduction
|
||||
}
|
||||
} while true
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), interval: interval, clock: clock, reducing: reducing)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension _AsyncThrottleSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension _AsyncThrottleSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,124 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
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.
|
||||
///
|
||||
/// - 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.
|
||||
@inlinable
|
||||
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async throws -> Result) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
|
||||
reductions(into: initial) { result, element in
|
||||
result = try await transform(result, element)
|
||||
}
|
||||
}
|
||||
|
||||
/// 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.
|
||||
///
|
||||
/// - 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. If the closure throws an
|
||||
/// error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
@inlinable
|
||||
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async throws -> Void) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
|
||||
AsyncThrowingExclusiveReductionsSequence(self, initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence of applying an error-throwing transform to the element of
|
||||
/// an asynchronous sequence and the previously transformed result.
|
||||
@frozen
|
||||
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let initial: Element
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (inout Element, Base.Element) async throws -> Void
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async throws -> Void) {
|
||||
self.base = base
|
||||
self.initial = initial
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
|
||||
/// The iterator for an `AsyncThrowingExclusiveReductionsSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
var current: Element?
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (inout Element, Base.Element) async throws -> Void
|
||||
|
||||
@inlinable
|
||||
init(_ iterator: Base.AsyncIterator, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async throws -> Void) {
|
||||
self.iterator = iterator
|
||||
self.current = initial
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async throws -> Element? {
|
||||
guard let result = current else { return nil }
|
||||
let value = try await iterator.next()
|
||||
if let value = value {
|
||||
var result = result
|
||||
do {
|
||||
try await transform(&result, value)
|
||||
current = result
|
||||
return result
|
||||
} catch {
|
||||
current = nil
|
||||
throw error
|
||||
}
|
||||
} else {
|
||||
current = nil
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,105 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
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.
|
||||
///
|
||||
/// ```
|
||||
/// let runningTotal = [1, 2, 3, 4].async.reductions(+)
|
||||
/// print(await Array(runningTotal))
|
||||
///
|
||||
/// // prints [1, 3, 6, 10]
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter transform: A closure that combines the previously reduced
|
||||
/// result and the next element in the receiving sequence. If the closure
|
||||
/// throws an error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@inlinable
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
|
||||
) -> AsyncThrowingInclusiveReductionsSequence<Self> {
|
||||
AsyncThrowingInclusiveReductionsSequence(self, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using a given error-throwing closure.
|
||||
@frozen
|
||||
public struct AsyncThrowingInclusiveReductionsSequence<Base: AsyncSequence> {
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let transform: @Sendable (Base.Element, Base.Element) async throws -> Base.Element
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base, transform: @Sendable @escaping (Base.Element, Base.Element) async throws -> Base.Element) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncThrowingInclusiveReductionsSequence` instance.
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator?
|
||||
|
||||
@usableFromInline
|
||||
internal var element: Base.Element?
|
||||
|
||||
@usableFromInline
|
||||
internal let transform: @Sendable (Base.Element, Base.Element) async throws -> Base.Element
|
||||
|
||||
@inlinable
|
||||
init(
|
||||
_ iterator: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Element, Base.Element) async throws -> Base.Element
|
||||
) {
|
||||
self.iterator = iterator
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public mutating func next() async throws -> Base.Element? {
|
||||
guard let previous = element else {
|
||||
element = try await iterator?.next()
|
||||
return element
|
||||
}
|
||||
guard let next = try await iterator?.next() else { return nil }
|
||||
do {
|
||||
element = try await transform(previous, next)
|
||||
} catch {
|
||||
iterator = nil
|
||||
throw error
|
||||
}
|
||||
return element
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingInclusiveReductionsSequence: Sendable where Base: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingInclusiveReductionsSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,84 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// An `AsyncSequence` that produces elements at regular intervals.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
|
||||
public typealias Element = C.Instant
|
||||
|
||||
/// The iterator for an `AsyncTimerSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
var clock: C?
|
||||
let interval: C.Instant.Duration
|
||||
let tolerance: C.Instant.Duration?
|
||||
var last: C.Instant?
|
||||
|
||||
init(interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
|
||||
self.clock = clock
|
||||
self.interval = interval
|
||||
self.tolerance = tolerance
|
||||
}
|
||||
|
||||
public mutating func next() async -> C.Instant? {
|
||||
guard let clock = self.clock else {
|
||||
return nil
|
||||
}
|
||||
|
||||
let next = (self.last ?? clock.now).advanced(by: self.interval)
|
||||
do {
|
||||
try await clock.sleep(until: next, tolerance: self.tolerance)
|
||||
} catch {
|
||||
self.clock = nil
|
||||
return nil
|
||||
}
|
||||
let now = clock.now
|
||||
self.last = next
|
||||
return now
|
||||
}
|
||||
}
|
||||
|
||||
let clock: C
|
||||
let interval: C.Instant.Duration
|
||||
let tolerance: C.Instant.Duration?
|
||||
|
||||
/// Create an `AsyncTimerSequence` with a given repeating interval.
|
||||
public init(interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) {
|
||||
self.clock = clock
|
||||
self.interval = interval
|
||||
self.tolerance = tolerance
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(interval: interval, tolerance: tolerance, clock: clock)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncTimerSequence {
|
||||
/// Create an `AsyncTimerSequence` with a given repeating interval.
|
||||
public static func repeating(every interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncTimerSequence<C> {
|
||||
return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: clock)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncTimerSequence where C == SuspendingClock {
|
||||
/// Create an `AsyncTimerSequence` with a given repeating interval.
|
||||
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock> {
|
||||
return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: SuspendingClock())
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncTimerSequence: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncTimerSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,131 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
/// Creates an asynchronous sequence that buffers elements.
|
||||
///
|
||||
/// The buffering behaviour is dictated by the policy:
|
||||
/// - bounded: will buffer elements until the limit is reached. Then it will suspend the upstream async sequence.
|
||||
/// - unbounded: will buffer elements without limit.
|
||||
/// - bufferingNewest: will buffer elements until the limit is reached. Then it will discard the oldest elements.
|
||||
/// - bufferingOldest: will buffer elements until the limit is reached. Then it will discard the newest elements.
|
||||
///
|
||||
/// - Parameter policy: A policy that drives the behaviour of the ``AsyncBufferSequence``
|
||||
/// - Returns: An asynchronous sequence that buffers elements up to a given limit.
|
||||
public func buffer(
|
||||
policy: AsyncBufferSequencePolicy
|
||||
) -> AsyncBufferSequence<Self> {
|
||||
AsyncBufferSequence<Self>(base: self, policy: policy)
|
||||
}
|
||||
}
|
||||
|
||||
/// A policy dictating the buffering behaviour of an ``AsyncBufferSequence``
|
||||
public struct AsyncBufferSequencePolicy: Sendable {
|
||||
enum _Policy {
|
||||
case bounded(Int)
|
||||
case unbounded
|
||||
case bufferingNewest(Int)
|
||||
case bufferingOldest(Int)
|
||||
}
|
||||
|
||||
let policy: _Policy
|
||||
|
||||
/// A policy for buffering elements until the limit is reached.
|
||||
/// Then consumption of the upstream `AsyncSequence` will be paused until elements are consumed from the buffer.
|
||||
/// If the limit is zero then no buffering policy is applied.
|
||||
public static func bounded(_ limit: Int) -> Self {
|
||||
precondition(limit >= 0, "The limit should be positive or equal to 0.")
|
||||
return Self(policy: .bounded(limit))
|
||||
}
|
||||
|
||||
/// A policy for buffering elements without limit.
|
||||
public static var unbounded: Self {
|
||||
return Self(policy: .unbounded)
|
||||
}
|
||||
|
||||
/// A policy for buffering elements until the limit is reached.
|
||||
/// After the limit is reached and a new element is produced by the upstream, the oldest buffered element will be discarded.
|
||||
/// If the limit is zero then no buffering policy is applied.
|
||||
public static func bufferingLatest(_ limit: Int) -> Self {
|
||||
precondition(limit >= 0, "The limit should be positive or equal to 0.")
|
||||
return Self(policy: .bufferingNewest(limit))
|
||||
}
|
||||
|
||||
/// A policy for buffering elements until the limit is reached.
|
||||
/// After the limit is reached and a new element is produced by the upstream, the latest buffered element will be discarded.
|
||||
/// If the limit is zero then no buffering policy is applied.
|
||||
public static func bufferingOldest(_ limit: Int) -> Self {
|
||||
precondition(limit >= 0, "The limit should be positive or equal to 0.")
|
||||
return Self(policy: .bufferingOldest(limit))
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that buffers elements in regard to a policy.
|
||||
public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence {
|
||||
enum StorageType {
|
||||
case transparent(Base.AsyncIterator)
|
||||
case bounded(storage: BoundedBufferStorage<Base>)
|
||||
case unbounded(storage: UnboundedBufferStorage<Base>)
|
||||
}
|
||||
|
||||
public typealias Element = Base.Element
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let base: Base
|
||||
let policy: AsyncBufferSequencePolicy
|
||||
|
||||
init(
|
||||
base: Base,
|
||||
policy: AsyncBufferSequencePolicy
|
||||
) {
|
||||
self.base = base
|
||||
self.policy = policy
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
let storageType: StorageType
|
||||
switch self.policy.policy {
|
||||
case .bounded(...0), .bufferingNewest(...0), .bufferingOldest(...0):
|
||||
storageType = .transparent(self.base.makeAsyncIterator())
|
||||
case .bounded(let limit):
|
||||
storageType = .bounded(storage: BoundedBufferStorage(base: self.base, limit: limit))
|
||||
case .unbounded:
|
||||
storageType = .unbounded(storage: UnboundedBufferStorage(base: self.base, policy: .unlimited))
|
||||
case .bufferingNewest(let limit):
|
||||
storageType = .unbounded(storage: UnboundedBufferStorage(base: self.base, policy: .bufferingNewest(limit)))
|
||||
case .bufferingOldest(let limit):
|
||||
storageType = .unbounded(storage: UnboundedBufferStorage(base: self.base, policy: .bufferingOldest(limit)))
|
||||
}
|
||||
return Iterator(storageType: storageType)
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
var storageType: StorageType
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
switch self.storageType {
|
||||
case .transparent(var iterator):
|
||||
let element = try await iterator.next()
|
||||
self.storageType = .transparent(iterator)
|
||||
return element
|
||||
case .bounded(let storage):
|
||||
return try await storage.next()?._rethrowGet()
|
||||
case .unbounded(let storage):
|
||||
return try await storage.next()?._rethrowGet()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncBufferSequence: Sendable where Base: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncBufferSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,316 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
struct BoundedBufferStateMachine<Base: AsyncSequence> {
|
||||
typealias Element = Base.Element
|
||||
typealias SuspendedProducer = UnsafeContinuation<Void, Never>
|
||||
typealias SuspendedConsumer = UnsafeContinuation<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
|
||||
// since next is not marked as transferring the return value.
|
||||
fileprivate enum State {
|
||||
case initial(base: Base)
|
||||
case buffering(
|
||||
task: Task<Void, Never>,
|
||||
buffer: Deque<Result<UnsafeTransfer<Element>, Error>>,
|
||||
suspendedProducer: SuspendedProducer?,
|
||||
suspendedConsumer: SuspendedConsumer?
|
||||
)
|
||||
case modifying
|
||||
case finished(buffer: Deque<Result<UnsafeTransfer<Element>, Error>>)
|
||||
}
|
||||
|
||||
private var state: State
|
||||
private let limit: Int
|
||||
|
||||
init(base: Base, limit: Int) {
|
||||
self.state = .initial(base: base)
|
||||
self.limit = limit
|
||||
}
|
||||
|
||||
var task: Task<Void, Never>? {
|
||||
switch self.state {
|
||||
case .buffering(let task, _, _, _):
|
||||
return task
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskStarted(task: Task<Void, Never>) {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
self.state = .buffering(task: task, buffer: [], suspendedProducer: nil, suspendedConsumer: nil)
|
||||
|
||||
case .buffering:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
preconditionFailure("Invalid state.")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func shouldSuspendProducer() -> Bool {
|
||||
switch state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already be started.")
|
||||
|
||||
case .buffering(_, let buffer, .none, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// if there are free slots, we should directly request the next element
|
||||
return buffer.count >= self.limit
|
||||
|
||||
case .buffering(_, _, .none, .some):
|
||||
// we have an awaiting consumer, we should not suspended the producer, we should
|
||||
// directly request the next element
|
||||
return false
|
||||
|
||||
case .buffering(_, _, .some, _):
|
||||
preconditionFailure("Invalid state. There is already a suspended producer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
enum ProducerSuspendedAction {
|
||||
case none
|
||||
case resumeProducer
|
||||
}
|
||||
|
||||
mutating func producerSuspended(continuation: SuspendedProducer) -> ProducerSuspendedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already be started.")
|
||||
|
||||
case .buffering(let task, let buffer, .none, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// if the buffer is available we resume the producer so it can we can request the next element
|
||||
// otherwise we confirm the suspension
|
||||
if buffer.count < limit {
|
||||
return .resumeProducer
|
||||
} else {
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: continuation, suspendedConsumer: nil)
|
||||
return .none
|
||||
}
|
||||
|
||||
case .buffering(_, let buffer, .none, .some):
|
||||
// we have an awaiting consumer, we can resume the producer so the next element can be requested
|
||||
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty as we have an awaiting consumer already.")
|
||||
return .resumeProducer
|
||||
|
||||
case .buffering(_, _, .some, _):
|
||||
preconditionFailure("Invalid state. There is already a suspended producer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return .resumeProducer
|
||||
}
|
||||
}
|
||||
|
||||
enum ElementProducedAction {
|
||||
case none
|
||||
case resumeConsumer(continuation: SuspendedConsumer, result: Result<Element, Error>)
|
||||
}
|
||||
|
||||
mutating func elementProduced(element: Element) -> ElementProducedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already be started.")
|
||||
|
||||
case .buffering(let task, var buffer, .none, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// we have to stack the new element or suspend the producer if the buffer is full
|
||||
precondition(buffer.count < limit, "Invalid state. The buffer should be available for stacking a new element.")
|
||||
self.state = .modifying
|
||||
buffer.append(.success(.init(element)))
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
|
||||
return .none
|
||||
|
||||
case .buffering(let task, let buffer, .none, .some(let suspendedConsumer)):
|
||||
// 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))
|
||||
|
||||
case .buffering(_, _, .some, _):
|
||||
preconditionFailure("Invalid state. There should not be a suspended producer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum FinishAction {
|
||||
case none
|
||||
case resumeConsumer(
|
||||
continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func finish(error: Error?) -> FinishAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already be started.")
|
||||
|
||||
case .buffering(_, var buffer, .none, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// if we have an error we stack it in the buffer so it can be consumed later
|
||||
if let error {
|
||||
buffer.append(.failure(error))
|
||||
}
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .none
|
||||
|
||||
case .buffering(_, let buffer, .none, .some(let suspendedConsumer)):
|
||||
// we have an awaiting consumer, we can resume it
|
||||
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
|
||||
self.state = .finished(buffer: [])
|
||||
return .resumeConsumer(continuation: suspendedConsumer)
|
||||
|
||||
case .buffering(_, _, .some, _):
|
||||
preconditionFailure("Invalid state. There should not be a suspended producer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum NextAction {
|
||||
case startTask(base: Base)
|
||||
case suspend
|
||||
case returnResult(producerContinuation: UnsafeContinuation<Void, Never>?, result: Result<Element, Error>?)
|
||||
}
|
||||
|
||||
mutating func next() -> NextAction {
|
||||
switch state {
|
||||
case .initial(let base):
|
||||
return .startTask(base: base)
|
||||
|
||||
case .buffering(_, let buffer, .none, .none) where buffer.isEmpty:
|
||||
// we are idle, we must suspend the consumer
|
||||
return .suspend
|
||||
|
||||
case .buffering(let task, var buffer, let suspendedProducer, .none):
|
||||
// we have values in the buffer, we unstack the oldest one and resume a potential suspended producer
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
|
||||
return .returnResult(producerContinuation: suspendedProducer, result: result.map { $0.wrapped })
|
||||
|
||||
case .buffering(_, _, _, .some):
|
||||
preconditionFailure("Invalid states. There is already a suspended consumer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished(let buffer) where buffer.isEmpty:
|
||||
return .returnResult(producerContinuation: nil, result: nil)
|
||||
|
||||
case .finished(var buffer):
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .returnResult(producerContinuation: nil, result: result.map { $0.wrapped })
|
||||
}
|
||||
}
|
||||
|
||||
enum NextSuspendedAction {
|
||||
case none
|
||||
case returnResult(producerContinuation: UnsafeContinuation<Void, Never>?, result: Result<Element, Error>?)
|
||||
}
|
||||
|
||||
mutating func nextSuspended(continuation: SuspendedConsumer) -> NextSuspendedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already be started.")
|
||||
|
||||
case .buffering(let task, let buffer, .none, .none) where buffer.isEmpty:
|
||||
// we are idle, we confirm the suspension of the consumer
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: continuation)
|
||||
return .none
|
||||
|
||||
case .buffering(let task, var buffer, let suspendedProducer, .none):
|
||||
// we have values in the buffer, we unstack the oldest one and resume a potential suspended producer
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
|
||||
return .returnResult(producerContinuation: suspendedProducer, result: result.map { $0.wrapped })
|
||||
|
||||
case .buffering(_, _, _, .some):
|
||||
preconditionFailure("Invalid states. There is already a suspended consumer.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished(let buffer) where buffer.isEmpty:
|
||||
return .returnResult(producerContinuation: nil, result: nil)
|
||||
|
||||
case .finished(var buffer):
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .returnResult(producerContinuation: nil, result: result.map { $0.wrapped })
|
||||
}
|
||||
}
|
||||
|
||||
enum InterruptedAction {
|
||||
case none
|
||||
case resumeProducerAndConsumer(
|
||||
task: Task<Void, Never>,
|
||||
producerContinuation: UnsafeContinuation<Void, Never>?,
|
||||
consumerContinuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func interrupted() -> InterruptedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
self.state = .finished(buffer: [])
|
||||
return .none
|
||||
|
||||
case .buffering(let task, _, let suspendedProducer, let suspendedConsumer):
|
||||
self.state = .finished(buffer: [])
|
||||
return .resumeProducerAndConsumer(
|
||||
task: task,
|
||||
producerContinuation: suspendedProducer,
|
||||
consumerContinuation: suspendedConsumer
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
self.state = .finished(buffer: [])
|
||||
return .none
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension BoundedBufferStateMachine: Sendable where Base: Sendable { }
|
||||
extension BoundedBufferStateMachine.State: Sendable where Base: Sendable { }
|
||||
@@ -0,0 +1,155 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Sendable {
|
||||
private let stateMachine: ManagedCriticalState<BoundedBufferStateMachine<Base>>
|
||||
|
||||
init(base: Base, limit: Int) {
|
||||
self.stateMachine = ManagedCriticalState(BoundedBufferStateMachine(base: base, limit: limit))
|
||||
}
|
||||
|
||||
func next() async -> Result<Base.Element, Error>? {
|
||||
return await withTaskCancellationHandler {
|
||||
let action: BoundedBufferStateMachine<Base>.NextAction? = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
let action = stateMachine.next()
|
||||
switch action {
|
||||
case .startTask(let base):
|
||||
self.startTask(stateMachine: &stateMachine, base: base)
|
||||
return nil
|
||||
|
||||
case .suspend:
|
||||
return action
|
||||
case .returnResult:
|
||||
return action
|
||||
}
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .startTask:
|
||||
// We are handling the startTask in the lock already because we want to avoid
|
||||
// other inputs interleaving while starting the task
|
||||
fatalError("Internal inconsistency")
|
||||
|
||||
case .suspend:
|
||||
break
|
||||
|
||||
case .returnResult(let producerContinuation, let result):
|
||||
producerContinuation?.resume()
|
||||
return result
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
return await withUnsafeContinuation { (continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.nextSuspended(continuation: continuation)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .returnResult(let producerContinuation, let result):
|
||||
producerContinuation?.resume()
|
||||
continuation.resume(returning: result)
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(
|
||||
stateMachine: inout BoundedBufferStateMachine<Base>,
|
||||
base: Base
|
||||
) {
|
||||
let task = Task {
|
||||
do {
|
||||
var iterator = base.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
let shouldSuspend = self.stateMachine.withCriticalRegion { stateMachine -> Bool in
|
||||
return stateMachine.shouldSuspendProducer()
|
||||
}
|
||||
|
||||
if shouldSuspend {
|
||||
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.producerSuspended(continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeProducer:
|
||||
continuation.resume()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
guard let element = try await iterator.next() else {
|
||||
// the upstream is finished
|
||||
break loop
|
||||
}
|
||||
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced(element: element)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation, let result):
|
||||
continuation.resume(returning: result)
|
||||
}
|
||||
}
|
||||
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.finish(error: nil)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: nil)
|
||||
}
|
||||
} catch {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.finish(error: error)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: .failure(error))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stateMachine.taskStarted(task: task)
|
||||
}
|
||||
|
||||
func interrupted() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.interrupted()
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeProducerAndConsumer(let task, let producerContinuation, let consumerContinuation):
|
||||
task.cancel()
|
||||
producerContinuation?.resume()
|
||||
consumerContinuation?.resume(returning: nil)
|
||||
}
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,258 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
struct UnboundedBufferStateMachine<Base: AsyncSequence> {
|
||||
typealias Element = Base.Element
|
||||
typealias SuspendedConsumer = UnsafeContinuation<Result<Element, Error>?, Never>
|
||||
|
||||
enum Policy {
|
||||
case unlimited
|
||||
case bufferingNewest(Int)
|
||||
case bufferingOldest(Int)
|
||||
}
|
||||
|
||||
// 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
|
||||
// since next is not marked as transferring the return value.
|
||||
fileprivate enum State {
|
||||
case initial(base: Base)
|
||||
case buffering(
|
||||
task: Task<Void, Never>,
|
||||
buffer: Deque<Result<UnsafeTransfer<Element>, Error>>,
|
||||
suspendedConsumer: SuspendedConsumer?
|
||||
)
|
||||
case modifying
|
||||
case finished(buffer: Deque<Result<UnsafeTransfer<Element>, Error>>)
|
||||
}
|
||||
|
||||
private var state: State
|
||||
private let policy: Policy
|
||||
|
||||
init(base: Base, policy: Policy) {
|
||||
self.state = .initial(base: base)
|
||||
self.policy = policy
|
||||
}
|
||||
|
||||
var task: Task<Void, Never>? {
|
||||
switch self.state {
|
||||
case .buffering(let task, _, _):
|
||||
return task
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskStarted(task: Task<Void, Never>) {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
self.state = .buffering(task: task, buffer: [], suspendedConsumer: nil)
|
||||
|
||||
case .buffering:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
preconditionFailure("Invalid state.")
|
||||
}
|
||||
}
|
||||
|
||||
enum ElementProducedAction {
|
||||
case none
|
||||
case resumeConsumer(
|
||||
continuation: SuspendedConsumer,
|
||||
result: Result<Element, Error>
|
||||
)
|
||||
}
|
||||
|
||||
mutating func elementProduced(element: Element) -> ElementProducedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already by started.")
|
||||
|
||||
case .buffering(let task, var buffer, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// we have to apply the policy when stacking the new element
|
||||
self.state = .modifying
|
||||
switch self.policy {
|
||||
case .unlimited:
|
||||
buffer.append(.success(.init(element)))
|
||||
case .bufferingNewest(let limit):
|
||||
if buffer.count >= limit {
|
||||
_ = buffer.popFirst()
|
||||
}
|
||||
buffer.append(.success(.init(element)))
|
||||
case .bufferingOldest(let limit):
|
||||
if buffer.count < limit {
|
||||
buffer.append(.success(.init(element)))
|
||||
}
|
||||
}
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
|
||||
return .none
|
||||
|
||||
case .buffering(let task, let buffer, .some(let suspendedConsumer)):
|
||||
// we have an awaiting consumer, we can resume it with the element
|
||||
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
|
||||
return .resumeConsumer(
|
||||
continuation: suspendedConsumer,
|
||||
result: .success(element)
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum FinishAction {
|
||||
case none
|
||||
case resumeConsumer(continuation: SuspendedConsumer?)
|
||||
}
|
||||
|
||||
mutating func finish(error: Error?) -> FinishAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already by started.")
|
||||
|
||||
case .buffering(_, var buffer, .none):
|
||||
// we are either idle or the buffer is already in use (no awaiting consumer)
|
||||
// if we have an error we stack it in the buffer so it can be consumed later
|
||||
if let error {
|
||||
buffer.append(.failure(error))
|
||||
}
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .none
|
||||
|
||||
case .buffering(_, let buffer, let suspendedConsumer):
|
||||
// we have an awaiting consumer, we can resume it with nil or the error
|
||||
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
|
||||
self.state = .finished(buffer: [])
|
||||
return .resumeConsumer(continuation: suspendedConsumer)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum NextAction {
|
||||
case startTask(base: Base)
|
||||
case suspend
|
||||
case returnResult(Result<Element, Error>?)
|
||||
}
|
||||
|
||||
mutating func next() -> NextAction {
|
||||
switch self.state {
|
||||
case .initial(let base):
|
||||
return .startTask(base: base)
|
||||
|
||||
case .buffering(_, let buffer, let suspendedConsumer) where buffer.isEmpty:
|
||||
// we are idle, we have to suspend the consumer
|
||||
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
|
||||
return .suspend
|
||||
|
||||
case .buffering(let task, var buffer, let suspendedConsumer):
|
||||
// the buffer is already in use, we can unstack a value and directly resume the consumer
|
||||
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
|
||||
return .returnResult(result.map { $0.wrapped })
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished(let buffer) where buffer.isEmpty:
|
||||
return .returnResult(nil)
|
||||
|
||||
case .finished(var buffer):
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .returnResult(result.map { $0.wrapped })
|
||||
}
|
||||
}
|
||||
|
||||
enum NextSuspendedAction {
|
||||
case none
|
||||
case resumeConsumer(Result<Element, Error>?)
|
||||
}
|
||||
|
||||
mutating func nextSuspended(continuation: SuspendedConsumer) -> NextSuspendedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Invalid state. The task should already by started.")
|
||||
|
||||
case .buffering(let task, let buffer, let suspendedConsumer) where buffer.isEmpty:
|
||||
// we are idle, we confirm the suspension of the consumer
|
||||
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: continuation)
|
||||
return .none
|
||||
|
||||
case .buffering(let task, var buffer, let suspendedConsumer):
|
||||
// the buffer is already in use, we can unstack a value and directly resume the consumer
|
||||
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
|
||||
return .resumeConsumer(result.map { $0.wrapped })
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished(let buffer) where buffer.isEmpty:
|
||||
return .resumeConsumer(nil)
|
||||
|
||||
case .finished(var buffer):
|
||||
self.state = .modifying
|
||||
let result = buffer.popFirst()!
|
||||
self.state = .finished(buffer: buffer)
|
||||
return .resumeConsumer(result.map { $0.wrapped })
|
||||
}
|
||||
}
|
||||
|
||||
enum InterruptedAction {
|
||||
case none
|
||||
case resumeConsumer(task: Task<Void, Never>, continuation: SuspendedConsumer?)
|
||||
}
|
||||
|
||||
mutating func interrupted() -> InterruptedAction {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
state = .finished(buffer: [])
|
||||
return .none
|
||||
|
||||
case .buffering(let task, _, let suspendedConsumer):
|
||||
self.state = .finished(buffer: [])
|
||||
return .resumeConsumer(task: task, continuation: suspendedConsumer)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state.")
|
||||
|
||||
case .finished:
|
||||
self.state = .finished(buffer: [])
|
||||
return .none
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension UnboundedBufferStateMachine: Sendable where Base: Sendable { }
|
||||
extension UnboundedBufferStateMachine.State: Sendable where Base: Sendable { }
|
||||
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Sendable {
|
||||
private let stateMachine: ManagedCriticalState<UnboundedBufferStateMachine<Base>>
|
||||
|
||||
init(base: Base, policy: UnboundedBufferStateMachine<Base>.Policy) {
|
||||
self.stateMachine = ManagedCriticalState(UnboundedBufferStateMachine<Base>(base: base, policy: policy))
|
||||
}
|
||||
|
||||
func next() async -> Result<Base.Element, Error>? {
|
||||
return await withTaskCancellationHandler {
|
||||
|
||||
let action: UnboundedBufferStateMachine<Base>.NextAction? = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
let action = stateMachine.next()
|
||||
switch action {
|
||||
case .startTask(let base):
|
||||
self.startTask(stateMachine: &stateMachine, base: base)
|
||||
return nil
|
||||
case .suspend:
|
||||
return action
|
||||
case .returnResult:
|
||||
return action
|
||||
}
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .startTask:
|
||||
// We are handling the startTask in the lock already because we want to avoid
|
||||
// other inputs interleaving while starting the task
|
||||
fatalError("Internal inconsistency")
|
||||
case .suspend:
|
||||
break
|
||||
case .returnResult(let result):
|
||||
return result
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
return await withUnsafeContinuation { (continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.nextSuspended(continuation: continuation)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let result):
|
||||
continuation.resume(returning: result)
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(
|
||||
stateMachine: inout UnboundedBufferStateMachine<Base>,
|
||||
base: Base
|
||||
) {
|
||||
let task = Task {
|
||||
do {
|
||||
for try await element in base {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced(element: element)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation, let result):
|
||||
continuation.resume(returning: result)
|
||||
}
|
||||
}
|
||||
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.finish(error: nil)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: nil)
|
||||
}
|
||||
} catch {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.finish(error: error)
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: .failure(error))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stateMachine.taskStarted(task: task)
|
||||
}
|
||||
|
||||
func interrupted() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.interrupted()
|
||||
}
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let task, let continuation):
|
||||
task.cancel()
|
||||
continuation?.resume(returning: nil)
|
||||
}
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,63 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A channel for sending elements from one task to another with back pressure.
|
||||
///
|
||||
/// The `AsyncChannel` class is intended to be used as a communication type between tasks,
|
||||
/// particularly when one task produces values and another task consumes those values. The back
|
||||
/// pressure applied by `send(_:)` via the suspension/resume ensures that
|
||||
/// the production of values does not exceed the consumption of values from iteration. This method
|
||||
/// suspends after enqueuing the event and is resumed when the next call to `next()`
|
||||
/// on the `Iterator` is made, or when `finish()` is called from another Task.
|
||||
/// As `finish()` induces a terminal state, there is no more need for a back pressure management.
|
||||
/// This function does not suspend and will finish all the pending iterations.
|
||||
public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
|
||||
public typealias Element = Element
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let storage: ChannelStorage<Element, Never>
|
||||
|
||||
public init() {
|
||||
self.storage = ChannelStorage()
|
||||
}
|
||||
|
||||
/// Sends an element to an awaiting iteration. This function will resume when the next call to `next()` is made
|
||||
/// or when a call to `finish()` is made from another task.
|
||||
/// If the channel is already finished then this returns immediately.
|
||||
/// If the task is cancelled, this function will resume without sending the element.
|
||||
/// Other sending operations from other tasks will remain active.
|
||||
public func send(_ element: Element) async {
|
||||
await self.storage.send(element: element)
|
||||
}
|
||||
|
||||
/// Immediately resumes all the suspended operations.
|
||||
/// All subsequent calls to `next(_:)` will resume immediately.
|
||||
public func finish() {
|
||||
self.storage.finish()
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(storage: self.storage)
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
let storage: ChannelStorage<Element, Never>
|
||||
|
||||
public mutating func next() async -> Element? {
|
||||
// Although the storage can throw, its usage in the context of an `AsyncChannel` guarantees it cannot.
|
||||
// There is no public way of sending a failure to it.
|
||||
try! await self.storage.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChannel.Iterator: Sendable { }
|
||||
@@ -0,0 +1,66 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// An error-throwing channel for sending elements from on task to another with back pressure.
|
||||
///
|
||||
/// The `AsyncThrowingChannel` class is intended to be used as a communication types between tasks,
|
||||
/// particularly when one task produces values and another task consumes those values. The back
|
||||
/// pressure applied by `send(_:)` via suspension/resume ensures that the production of values does
|
||||
/// not exceed the consumption of values from iteration. This method suspends after enqueuing the event
|
||||
/// and is resumed when the next call to `next()` on the `Iterator` is made, or when `finish()`/`fail(_:)` is called
|
||||
/// from another Task. As `finish()` and `fail(_:)` induce a terminal state, there is no more need for a back pressure management.
|
||||
/// Those functions do not suspend and will finish all the pending iterations.
|
||||
public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
|
||||
public typealias Element = Element
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let storage: ChannelStorage<Element, Failure>
|
||||
|
||||
public init() {
|
||||
self.storage = ChannelStorage()
|
||||
}
|
||||
|
||||
/// Sends an element to an awaiting iteration. This function will resume when the next call to `next()` is made
|
||||
/// or when a call to `finish()` or `fail` is made from another task.
|
||||
/// If the channel is already finished then this returns immediately.
|
||||
/// If the task is cancelled, this function will resume without sending the element.
|
||||
/// Other sending operations from other tasks will remain active.
|
||||
public func send(_ element: Element) async {
|
||||
await self.storage.send(element: element)
|
||||
}
|
||||
|
||||
/// Sends an error to all awaiting iterations.
|
||||
/// All subsequent calls to `next(_:)` will resume immediately.
|
||||
public func fail(_ error: Error) where Failure == Error {
|
||||
self.storage.finish(error: error)
|
||||
}
|
||||
|
||||
/// Immediately resumes all the suspended operations.
|
||||
/// All subsequent calls to `next(_:)` will resume immediately.
|
||||
public func finish() {
|
||||
self.storage.finish()
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(storage: self.storage)
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
let storage: ChannelStorage<Element, Failure>
|
||||
|
||||
public mutating func next() async throws -> Element? {
|
||||
try await self.storage.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingChannel.Iterator: Sendable { }
|
||||
@@ -0,0 +1,344 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 OrderedCollections
|
||||
|
||||
struct ChannelStateMachine<Element: Sendable, Failure: Error>: Sendable {
|
||||
private struct SuspendedProducer: Hashable, Sendable {
|
||||
let id: UInt64
|
||||
let continuation: UnsafeContinuation<Void, Never>?
|
||||
let element: Element?
|
||||
|
||||
func hash(into hasher: inout Hasher) {
|
||||
hasher.combine(self.id)
|
||||
}
|
||||
|
||||
static func == (_ lhs: SuspendedProducer, _ rhs: SuspendedProducer) -> Bool {
|
||||
return lhs.id == rhs.id
|
||||
}
|
||||
|
||||
static func placeHolder(id: UInt64) -> SuspendedProducer {
|
||||
SuspendedProducer(id: id, continuation: nil, element: nil)
|
||||
}
|
||||
}
|
||||
|
||||
private struct SuspendedConsumer: Hashable, Sendable {
|
||||
let id: UInt64
|
||||
let continuation: UnsafeContinuation<Element?, any Error>?
|
||||
|
||||
func hash(into hasher: inout Hasher) {
|
||||
hasher.combine(self.id)
|
||||
}
|
||||
|
||||
static func == (_ lhs: SuspendedConsumer, _ rhs: SuspendedConsumer) -> Bool {
|
||||
return lhs.id == rhs.id
|
||||
}
|
||||
|
||||
static func placeHolder(id: UInt64) -> SuspendedConsumer {
|
||||
SuspendedConsumer(id: id, continuation: nil)
|
||||
}
|
||||
}
|
||||
|
||||
private enum Termination {
|
||||
case finished
|
||||
case failed(Error)
|
||||
}
|
||||
|
||||
private enum State: Sendable {
|
||||
case channeling(
|
||||
suspendedProducers: OrderedSet<SuspendedProducer>,
|
||||
cancelledProducers: Set<SuspendedProducer>,
|
||||
suspendedConsumers: OrderedSet<SuspendedConsumer>,
|
||||
cancelledConsumers: Set<SuspendedConsumer>
|
||||
)
|
||||
case terminated(Termination)
|
||||
}
|
||||
|
||||
private var state: State = .channeling(suspendedProducers: [], cancelledProducers: [], suspendedConsumers: [], cancelledConsumers: [])
|
||||
|
||||
enum SendAction {
|
||||
case resumeConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
|
||||
case suspend
|
||||
}
|
||||
|
||||
mutating func send() -> SendAction {
|
||||
switch self.state {
|
||||
case .channeling(_, _, let suspendedConsumers, _) where suspendedConsumers.isEmpty:
|
||||
// we are idle or waiting for consumers, we have to suspend the producer
|
||||
return .suspend
|
||||
|
||||
case .channeling(let suspendedProducers, let cancelledProducers, var suspendedConsumers, let cancelledConsumers):
|
||||
// we are waiting for producers, we can resume the first available consumer
|
||||
let suspendedConsumer = suspendedConsumers.removeFirst()
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeConsumer(continuation: suspendedConsumer.continuation)
|
||||
|
||||
case .terminated:
|
||||
return .resumeConsumer(continuation: nil)
|
||||
}
|
||||
}
|
||||
|
||||
enum SendSuspendedAction {
|
||||
case resumeProducer
|
||||
case resumeProducerAndConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
|
||||
}
|
||||
|
||||
mutating func sendSuspended(
|
||||
continuation: UnsafeContinuation<Void, Never>,
|
||||
element: Element,
|
||||
producerID: UInt64
|
||||
) -> SendSuspendedAction? {
|
||||
switch self.state {
|
||||
case .channeling(var suspendedProducers, var cancelledProducers, var suspendedConsumers, let cancelledConsumers):
|
||||
let suspendedProducer = SuspendedProducer(id: producerID, continuation: continuation, element: element)
|
||||
if let _ = cancelledProducers.remove(suspendedProducer) {
|
||||
// the producer was already cancelled, we resume it
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeProducer
|
||||
}
|
||||
|
||||
if suspendedConsumers.isEmpty {
|
||||
// we are idle or waiting for consumers
|
||||
// we stack the incoming producer in a suspended state
|
||||
suspendedProducers.append(suspendedProducer)
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .none
|
||||
} else {
|
||||
// we are waiting for producers
|
||||
// we resume the first consumer
|
||||
let suspendedConsumer = suspendedConsumers.removeFirst()
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeProducerAndConsumer(continuation: suspendedConsumer.continuation)
|
||||
}
|
||||
|
||||
case .terminated:
|
||||
return .resumeProducer
|
||||
}
|
||||
}
|
||||
|
||||
enum SendCancelledAction {
|
||||
case none
|
||||
case resumeProducer(continuation: UnsafeContinuation<Void, Never>?)
|
||||
}
|
||||
|
||||
mutating func sendCancelled(producerID: UInt64) -> SendCancelledAction {
|
||||
switch self.state {
|
||||
case .channeling(var suspendedProducers, var cancelledProducers, let suspendedConsumers, let cancelledConsumers):
|
||||
// the cancelled producer might be part of the waiting list
|
||||
let placeHolder = SuspendedProducer.placeHolder(id: producerID)
|
||||
|
||||
if let removed = suspendedProducers.remove(placeHolder) {
|
||||
// the producer was cancelled after being added to the suspended ones, we resume it
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeProducer(continuation: removed.continuation)
|
||||
}
|
||||
|
||||
// the producer was cancelled before being added to the suspended ones
|
||||
cancelledProducers.update(with: placeHolder)
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .none
|
||||
|
||||
case .terminated:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum FinishAction {
|
||||
case none
|
||||
case resumeProducersAndConsumers(
|
||||
producerSontinuations: [UnsafeContinuation<Void, Never>?],
|
||||
consumerContinuations: [UnsafeContinuation<Element?, any Error>?]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func finish(error: Failure?) -> FinishAction {
|
||||
switch self.state {
|
||||
case .channeling(let suspendedProducers, _, let suspendedConsumers, _):
|
||||
// no matter if we are idle, waiting for producers or waiting for consumers, we resume every thing that is suspended
|
||||
if let error {
|
||||
if suspendedConsumers.isEmpty {
|
||||
self.state = .terminated(.failed(error))
|
||||
} else {
|
||||
self.state = .terminated(.finished)
|
||||
}
|
||||
} else {
|
||||
self.state = .terminated(.finished)
|
||||
}
|
||||
return .resumeProducersAndConsumers(
|
||||
producerSontinuations: suspendedProducers.map { $0.continuation },
|
||||
consumerContinuations: suspendedConsumers.map { $0.continuation }
|
||||
)
|
||||
|
||||
case .terminated:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
enum NextAction {
|
||||
case resumeProducer(continuation: UnsafeContinuation<Void, Never>?, result: Result<Element?, Error>)
|
||||
case suspend
|
||||
}
|
||||
|
||||
mutating func next() -> NextAction {
|
||||
switch self.state {
|
||||
case .channeling(let suspendedProducers, _, _, _) where suspendedProducers.isEmpty:
|
||||
// we are idle or waiting for producers, we must suspend
|
||||
return .suspend
|
||||
|
||||
case .channeling(var suspendedProducers, let cancelledProducers, let suspendedConsumers, let cancelledConsumers):
|
||||
// we are waiting for consumers, we can resume the first awaiting producer
|
||||
let suspendedProducer = suspendedProducers.removeFirst()
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeProducer(
|
||||
continuation: suspendedProducer.continuation,
|
||||
result: .success(suspendedProducer.element)
|
||||
)
|
||||
|
||||
case .terminated(.failed(let error)):
|
||||
self.state = .terminated(.finished)
|
||||
return .resumeProducer(continuation: nil, result: .failure(error))
|
||||
|
||||
case .terminated:
|
||||
return .resumeProducer(continuation: nil, result: .success(nil))
|
||||
}
|
||||
}
|
||||
|
||||
enum NextSuspendedAction {
|
||||
case resumeConsumer(element: Element?)
|
||||
case resumeConsumerWithError(error: Error)
|
||||
case resumeProducerAndConsumer(continuation: UnsafeContinuation<Void, Never>?, element: Element?)
|
||||
}
|
||||
|
||||
mutating func nextSuspended(
|
||||
continuation: UnsafeContinuation<Element?, any Error>,
|
||||
consumerID: UInt64
|
||||
) -> NextSuspendedAction? {
|
||||
switch self.state {
|
||||
case .channeling(var suspendedProducers, let cancelledProducers, var suspendedConsumers, var cancelledConsumers):
|
||||
let suspendedConsumer = SuspendedConsumer(id: consumerID, continuation: continuation)
|
||||
if let _ = cancelledConsumers.remove(suspendedConsumer) {
|
||||
// the consumer was already cancelled, we resume it
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeConsumer(element: nil)
|
||||
}
|
||||
|
||||
if suspendedProducers.isEmpty {
|
||||
// we are idle or waiting for producers
|
||||
// we stack the incoming consumer in a suspended state
|
||||
suspendedConsumers.append(suspendedConsumer)
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .none
|
||||
} else {
|
||||
// we are waiting for consumers
|
||||
// we resume the first producer
|
||||
let suspendedProducer = suspendedProducers.removeFirst()
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeProducerAndConsumer(
|
||||
continuation: suspendedProducer.continuation,
|
||||
element: suspendedProducer.element
|
||||
)
|
||||
}
|
||||
|
||||
case .terminated(.finished):
|
||||
return .resumeConsumer(element: nil)
|
||||
|
||||
case .terminated(.failed(let error)):
|
||||
self.state = .terminated(.finished)
|
||||
return .resumeConsumerWithError(error: error)
|
||||
}
|
||||
}
|
||||
|
||||
enum NextCancelledAction {
|
||||
case none
|
||||
case resumeConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
|
||||
}
|
||||
|
||||
mutating func nextCancelled(consumerID: UInt64) -> NextCancelledAction {
|
||||
switch self.state {
|
||||
case .channeling(let suspendedProducers, let cancelledProducers, var suspendedConsumers, var cancelledConsumers):
|
||||
// the cancelled consumer might be part of the suspended ones
|
||||
let placeHolder = SuspendedConsumer.placeHolder(id: consumerID)
|
||||
|
||||
if let removed = suspendedConsumers.remove(placeHolder) {
|
||||
// the consumer was cancelled after being added to the suspended ones, we resume it
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .resumeConsumer(continuation: removed.continuation)
|
||||
}
|
||||
|
||||
// the consumer was cancelled before being added to the suspended ones
|
||||
cancelledConsumers.update(with: placeHolder)
|
||||
self.state = .channeling(
|
||||
suspendedProducers: suspendedProducers,
|
||||
cancelledProducers: cancelledProducers,
|
||||
suspendedConsumers: suspendedConsumers,
|
||||
cancelledConsumers: cancelledConsumers
|
||||
)
|
||||
return .none
|
||||
|
||||
case .terminated:
|
||||
return .none
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,142 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
struct ChannelStorage<Element: Sendable, Failure: Error>: Sendable {
|
||||
private let stateMachine: ManagedCriticalState<ChannelStateMachine<Element, Failure>>
|
||||
private let ids = ManagedCriticalState<UInt64>(0)
|
||||
|
||||
init() {
|
||||
self.stateMachine = ManagedCriticalState(ChannelStateMachine())
|
||||
}
|
||||
|
||||
func generateId() -> UInt64 {
|
||||
self.ids.withCriticalRegion { ids in
|
||||
defer { ids &+= 1 }
|
||||
return ids
|
||||
}
|
||||
}
|
||||
|
||||
func send(element: Element) async {
|
||||
// check if a suspension is needed
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.send()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .suspend:
|
||||
break
|
||||
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: element)
|
||||
return
|
||||
}
|
||||
|
||||
let producerID = self.generateId()
|
||||
|
||||
await withTaskCancellationHandler {
|
||||
// a suspension is needed
|
||||
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.sendSuspended(continuation: continuation, element: element, producerID: producerID)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeProducer:
|
||||
continuation.resume()
|
||||
case .resumeProducerAndConsumer(let consumerContinuation):
|
||||
continuation.resume()
|
||||
consumerContinuation?.resume(returning: element)
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.sendCancelled(producerID: producerID)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeProducer(let continuation):
|
||||
continuation?.resume()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func finish(error: Failure? = nil) {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.finish(error: error)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeProducersAndConsumers(let producerContinuations, let consumerContinuations):
|
||||
producerContinuations.forEach { $0?.resume() }
|
||||
if let error {
|
||||
consumerContinuations.forEach { $0?.resume(throwing: error) }
|
||||
} else {
|
||||
consumerContinuations.forEach { $0?.resume(returning: nil) }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func next() async throws -> Element? {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.next()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .suspend:
|
||||
break
|
||||
|
||||
case .resumeProducer(let producerContinuation, let result):
|
||||
producerContinuation?.resume()
|
||||
return try result._rethrowGet()
|
||||
}
|
||||
|
||||
let consumerID = self.generateId()
|
||||
|
||||
return try await withTaskCancellationHandler {
|
||||
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Element?, any Error>) in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.nextSuspended(
|
||||
continuation: continuation,
|
||||
consumerID: consumerID
|
||||
)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let element):
|
||||
continuation.resume(returning: element)
|
||||
case .resumeConsumerWithError(let error):
|
||||
continuation.resume(throwing: error)
|
||||
case .resumeProducerAndConsumer(let producerContinuation, let element):
|
||||
producerContinuation?.resume()
|
||||
continuation.resume(returning: element)
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.nextCancelled(consumerID: consumerID)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .none:
|
||||
break
|
||||
case .resumeConsumer(let continuation):
|
||||
continuation?.resume(returning: nil)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Creates an asynchronous sequence that combines the latest values from two `AsyncSequence` types
|
||||
/// by emitting a tuple of the values. ``combineLatest(_:_:)`` only emits a value whenever any of the base `AsyncSequence`s
|
||||
/// emit a value (so long as each of the bases have emitted at least one value).
|
||||
///
|
||||
/// Finishes:
|
||||
/// ``combineLatest(_:_:)`` finishes when one of the bases finishes before emitting any value or
|
||||
/// when all bases finished.
|
||||
///
|
||||
/// Throws:
|
||||
/// ``combineLatest(_:_:)`` throws when one of the bases throws. If one of the bases threw any buffered and not yet consumed
|
||||
/// values will be dropped.
|
||||
public func combineLatest<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence
|
||||
>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2> where
|
||||
Base1: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2: Sendable,
|
||||
Base2.Element: Sendable {
|
||||
AsyncCombineLatest2Sequence(base1, base2)
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that combines the latest values produced from two asynchronous sequences into an asynchronous sequence of tuples.
|
||||
public struct AsyncCombineLatest2Sequence<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence
|
||||
>: AsyncSequence, Sendable where
|
||||
Base1: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2: Sendable,
|
||||
Base2.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncIterator {
|
||||
Iterator(storage: .init(self.base1, self.base2, nil))
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
final class InternalClass {
|
||||
private let storage: CombineLatestStorage<Base1, Base2, Base2>
|
||||
|
||||
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base2>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
guard let element = try await self.storage.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
return (element.0, element.1)
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base2>) {
|
||||
self.internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await self.internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncCombineLatest2Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,102 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Creates an asynchronous sequence that combines the latest values from three `AsyncSequence` types
|
||||
/// by emitting a tuple of the values. ``combineLatest(_:_:_:)`` only emits a value whenever any of the base `AsyncSequence`s
|
||||
/// emit a value (so long as each of the bases have emitted at least one value).
|
||||
///
|
||||
/// Finishes:
|
||||
/// ``combineLatest(_:_:_:)`` finishes when one of the bases finishes before emitting any value or
|
||||
/// when all bases finished.
|
||||
///
|
||||
/// Throws:
|
||||
/// ``combineLatest(_:_:_:)`` throws when one of the bases throws. If one of the bases threw any buffered and not yet consumed
|
||||
/// values will be dropped.
|
||||
public func combineLatest<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3> where
|
||||
Base1: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
AsyncCombineLatest3Sequence(base1, base2, base3)
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that combines the latest values produced from three asynchronous sequences into an asynchronous sequence of tuples.
|
||||
public struct AsyncCombineLatest3Sequence<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: AsyncSequence, Sendable where
|
||||
Base1: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
let base3: Base3
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncIterator {
|
||||
Iterator(storage: .init(self.base1, self.base2, self.base3)
|
||||
)
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
final class InternalClass {
|
||||
private let storage: CombineLatestStorage<Base1, Base2, Base3>
|
||||
|
||||
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base3>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
guard let element = try await self.storage.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
// This force unwrap is safe since there must be a third element.
|
||||
return (element.0, element.1, element.2!)
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base3>) {
|
||||
self.internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await self.internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncCombineLatest3Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,723 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
/// State machine for combine latest
|
||||
struct CombineLatestStateMachine<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: Sendable where
|
||||
Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base3: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
typealias DownstreamContinuation = UnsafeContinuation<Result<(
|
||||
Base1.Element,
|
||||
Base2.Element,
|
||||
Base3.Element?
|
||||
)?, Error>, Never>
|
||||
|
||||
private enum State: Sendable {
|
||||
/// Small wrapper for the state of an upstream sequence.
|
||||
struct Upstream<Element: Sendable>: Sendable {
|
||||
/// The upstream continuation.
|
||||
var continuation: UnsafeContinuation<Void, Error>?
|
||||
/// The produced upstream element.
|
||||
var element: Element?
|
||||
/// Indicates wether the upstream finished/threw already
|
||||
var isFinished: Bool
|
||||
}
|
||||
|
||||
/// The initial state before a call to `next` happened.
|
||||
case initial(base1: Base1, base2: Base2, base3: Base3?)
|
||||
|
||||
/// The state while we are waiting for downstream demand.
|
||||
case waitingForDemand(
|
||||
task: Task<Void, Never>,
|
||||
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
|
||||
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
|
||||
)
|
||||
|
||||
/// The state while we are consuming the upstream and waiting until we get a result from all upstreams.
|
||||
case combining(
|
||||
task: Task<Void, Never>,
|
||||
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
|
||||
)
|
||||
|
||||
case upstreamsFinished(
|
||||
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
|
||||
)
|
||||
|
||||
case upstreamThrew(
|
||||
error: Error
|
||||
)
|
||||
|
||||
/// The state once the downstream consumer stopped, i.e. by dropping all references
|
||||
/// or by getting their `Task` cancelled.
|
||||
case finished
|
||||
|
||||
/// Internal state to avoid CoW.
|
||||
case modifying
|
||||
}
|
||||
|
||||
private var state: State
|
||||
|
||||
private let numberOfUpstreamSequences: Int
|
||||
|
||||
/// Initializes a new `StateMachine`.
|
||||
init(
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?
|
||||
) {
|
||||
self.state = .initial(
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3
|
||||
)
|
||||
|
||||
if base3 == nil {
|
||||
self.numberOfUpstreamSequences = 2
|
||||
} else {
|
||||
self.numberOfUpstreamSequences = 3
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `iteratorDeinitialized()`.
|
||||
enum IteratorDeinitializedAction {
|
||||
/// Indicates that the `Task` needs to be cancelled and
|
||||
/// the upstream continuations need to be resumed with a `CancellationError`.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Nothing to do here. No demand was signalled until now
|
||||
return .none
|
||||
|
||||
case .combining:
|
||||
// An iterator was deinitialized while we have a suspended continuation.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreams, _):
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now and need to clean everything up.
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .upstreamThrew, .upstreamsFinished:
|
||||
// The iterator was dropped so we can transition to finished now.
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// We are already finished so there is nothing left to clean up.
|
||||
// This is just the references dropping afterwards.
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskIsStarted(
|
||||
task: Task<Void, Never>,
|
||||
downstreamContinuation: DownstreamContinuation
|
||||
) {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// The user called `next` and we are starting the `Task`
|
||||
// to consume the upstream sequences
|
||||
self.state = .combining(
|
||||
task: task,
|
||||
upstreams: (.init(isFinished: false), .init(isFinished: false), .init(isFinished: false)),
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
buffer: .init()
|
||||
)
|
||||
|
||||
case .combining, .waitingForDemand, .upstreamThrew, .upstreamsFinished, .finished:
|
||||
// We only allow a single task to be created so this must never happen.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `childTaskSuspended()`.
|
||||
enum ChildTaskSuspendedAction {
|
||||
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
|
||||
case resumeContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>
|
||||
)
|
||||
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
|
||||
case resumeContinuationWithError(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>,
|
||||
error: Error
|
||||
)
|
||||
}
|
||||
|
||||
mutating func childTaskSuspended(baseIndex: Int, continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `zipping`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .upstreamsFinished:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams, let buffer):
|
||||
self.state = .modifying
|
||||
|
||||
switch baseIndex {
|
||||
case 0:
|
||||
upstreams.0.continuation = continuation
|
||||
|
||||
case 1:
|
||||
upstreams.1.continuation = continuation
|
||||
|
||||
case 2:
|
||||
upstreams.2.continuation = continuation
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
|
||||
}
|
||||
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .combining:
|
||||
// We are currently combining and need to resume any upstream until we transition to waitingForDemand
|
||||
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
|
||||
case .upstreamThrew, .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks are still getting
|
||||
// suspended even though we already cancelled them. We must tolerate this and just resume
|
||||
// the continuation with an error.
|
||||
return .resumeContinuationWithError(
|
||||
upstreamContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `elementProduced()`.
|
||||
enum ElementProducedAction {
|
||||
/// Indicates that the downstream continuation should be resumed with the element.
|
||||
case resumeContinuation(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
|
||||
)
|
||||
}
|
||||
|
||||
mutating func elementProduced(_ result: (Base1.Element?, Base2.Element?, Base3.Element?)) -> ElementProducedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks that are producing elements are only created after we transitioned to `zipping`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case .upstreamsFinished:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams, var buffer):
|
||||
// We got an element in late. This can happen since we race the upstreams.
|
||||
// We have to store the new tuple in our buffer and remember the upstream states.
|
||||
|
||||
self.state = .modifying
|
||||
|
||||
switch result {
|
||||
case (.some(let first), .none, .none):
|
||||
buffer.append((first, upstreams.1.element!, upstreams.2.element))
|
||||
upstreams.0.element = first
|
||||
|
||||
case (.none, .some(let second), .none):
|
||||
buffer.append((upstreams.0.element!, second, upstreams.2.element))
|
||||
upstreams.1.element = second
|
||||
|
||||
case (.none, .none, .some(let third)):
|
||||
buffer.append((upstreams.0.element!, upstreams.1.element!, third))
|
||||
upstreams.2.element = third
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
}
|
||||
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .combining(let task, var upstreams, let downstreamContinuation, let buffer):
|
||||
precondition(buffer.isEmpty, "Internal inconsistency current state \(self.state) and the buffer is not empty")
|
||||
self.state = .modifying
|
||||
|
||||
switch result {
|
||||
case (.some(let first), .none, .none):
|
||||
upstreams.0.element = first
|
||||
|
||||
case (.none, .some(let second), .none):
|
||||
upstreams.1.element = second
|
||||
|
||||
case (.none, .none, .some(let third)):
|
||||
upstreams.2.element = third
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
}
|
||||
|
||||
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
|
||||
if let first = upstreams.0.element,
|
||||
let second = upstreams.1.element,
|
||||
let third = upstreams.2.element {
|
||||
// We got an element from each upstream so we can resume the downstream now
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
result: .success((first, second, third))
|
||||
)
|
||||
|
||||
} else if let first = upstreams.0.element,
|
||||
let second = upstreams.1.element,
|
||||
self.numberOfUpstreamSequences == 2 {
|
||||
// We got an element from each upstream so we can resume the downstream now
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
result: .success((first, second, nil))
|
||||
)
|
||||
} else {
|
||||
// We are still waiting for one of the upstreams to produce an element
|
||||
self.state = .combining(
|
||||
task: task,
|
||||
upstreams: (
|
||||
.init(continuation: upstreams.0.continuation, element: upstreams.0.element, isFinished: upstreams.0.isFinished),
|
||||
.init(continuation: upstreams.1.continuation, element: upstreams.1.element, isFinished: upstreams.1.isFinished),
|
||||
.init(continuation: upstreams.2.continuation, element: upstreams.2.element, isFinished: upstreams.2.isFinished)
|
||||
),
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .none
|
||||
}
|
||||
|
||||
case .upstreamThrew, .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks
|
||||
// are still producing elements after we finished.
|
||||
// We are just going to drop them since there is nothing we can do
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamFinished()`.
|
||||
enum UpstreamFinishedAction {
|
||||
/// Indicates the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamFinished(baseIndex: Int) -> UpstreamFinishedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .upstreamsFinished:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams, let buffer):
|
||||
// One of the upstreams finished.
|
||||
|
||||
self.state = .modifying
|
||||
|
||||
switch baseIndex {
|
||||
case 0:
|
||||
upstreams.0.isFinished = true
|
||||
|
||||
case 1:
|
||||
upstreams.1.isFinished = true
|
||||
|
||||
case 2:
|
||||
upstreams.2.isFinished = true
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished() with base index \(baseIndex)")
|
||||
}
|
||||
|
||||
if upstreams.0.isFinished && upstreams.1.isFinished && upstreams.2.isFinished {
|
||||
// All upstreams finished we can transition to either finished or upstreamsFinished now
|
||||
if buffer.isEmpty {
|
||||
self.state = .finished
|
||||
} else {
|
||||
self.state = .upstreamsFinished(buffer: buffer)
|
||||
}
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
} else if upstreams.0.isFinished && upstreams.1.isFinished && self.numberOfUpstreamSequences == 2 {
|
||||
// All upstreams finished we can transition to either finished or upstreamsFinished now
|
||||
if buffer.isEmpty {
|
||||
self.state = .finished
|
||||
} else {
|
||||
self.state = .upstreamsFinished(buffer: buffer)
|
||||
}
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
} else {
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
return .none
|
||||
}
|
||||
|
||||
case .combining(let task, var upstreams, let downstreamContinuation, let buffer):
|
||||
// One of the upstreams finished.
|
||||
|
||||
self.state = .modifying
|
||||
|
||||
// We need to track if an empty upstream finished.
|
||||
// If that happens we can transition to finish right away.
|
||||
let emptyUpstreamFinished: Bool
|
||||
switch baseIndex {
|
||||
case 0:
|
||||
upstreams.0.isFinished = true
|
||||
emptyUpstreamFinished = upstreams.0.element == nil
|
||||
|
||||
case 1:
|
||||
upstreams.1.isFinished = true
|
||||
emptyUpstreamFinished = upstreams.1.element == nil
|
||||
|
||||
case 2:
|
||||
upstreams.2.isFinished = true
|
||||
emptyUpstreamFinished = upstreams.2.element == nil
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished() with base index \(baseIndex)")
|
||||
}
|
||||
|
||||
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
|
||||
if emptyUpstreamFinished {
|
||||
// All upstreams finished
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
} else if upstreams.0.isFinished && upstreams.1.isFinished && upstreams.2.isFinished {
|
||||
// All upstreams finished
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
} else if upstreams.0.isFinished && upstreams.1.isFinished && self.numberOfUpstreamSequences == 2 {
|
||||
// All upstreams finished
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
} else {
|
||||
self.state = .combining(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
buffer: buffer
|
||||
)
|
||||
return .none
|
||||
}
|
||||
|
||||
case .upstreamThrew, .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamThrew()`.
|
||||
enum UpstreamThrewAction {
|
||||
/// Indicates the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with the `error` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
error: Error,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .upstreamsFinished:
|
||||
// We need to tolerate multiple upstreams failing
|
||||
return .none
|
||||
|
||||
case .waitingForDemand(let task, let upstreams, _):
|
||||
// An upstream threw. We can cancel everything now and transition to finished.
|
||||
// We just need to store the error for the next downstream demand
|
||||
self.state = .upstreamThrew(
|
||||
error: error
|
||||
)
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .combining(let task, let upstreams, let downstreamContinuation, _):
|
||||
// One of our upstreams threw. We need to transition to finished ourselves now
|
||||
// and resume the downstream continuation with the error. Furthermore, we need to cancel all of
|
||||
// the upstream work.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
error: error,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .upstreamThrew, .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `cancelled()`.
|
||||
enum CancelledAction {
|
||||
/// Indicates that the downstream continuation needs to be resumed and
|
||||
/// task and the upstream continuations should be cancelled.
|
||||
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func cancelled() -> CancelledAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .waitingForDemand(let task, let upstreams, _):
|
||||
// The downstream task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .combining(let task, let upstreams, let downstreamContinuation, _):
|
||||
// The downstream Task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .upstreamsFinished:
|
||||
// We can transition to finished now
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .upstreamThrew, .finished:
|
||||
// We are already finished so nothing to do here:
|
||||
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `next()`.
|
||||
enum NextAction {
|
||||
/// Indicates that a new `Task` should be created that consumes the sequence.
|
||||
case startTask(Base1, Base2, Base3?)
|
||||
/// Indicates that all upstream continuations should be resumed.
|
||||
case resumeUpstreamContinuations(
|
||||
upstreamContinuation: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with the result.
|
||||
case resumeContinuation(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil`.
|
||||
case resumeDownstreamContinuationWithNil(DownstreamContinuation)
|
||||
}
|
||||
|
||||
mutating func next(for continuation: DownstreamContinuation) -> NextAction {
|
||||
switch self.state {
|
||||
case .initial(let base1, let base2, let base3):
|
||||
// This is the first time we get demand singalled so we have to start the task
|
||||
// The transition to the next state is done in the taskStarted method
|
||||
return .startTask(base1, base2, base3)
|
||||
|
||||
case .combining:
|
||||
// We already got demand signalled and have suspended the downstream task
|
||||
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams, var buffer):
|
||||
// We got demand signalled now we have to check if there is anything buffered.
|
||||
// If not we have to transition to combining and need to resume all upstream continuations now
|
||||
self.state = .modifying
|
||||
|
||||
if let element = buffer.popFirst() {
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: continuation,
|
||||
result: .success(element)
|
||||
)
|
||||
} else {
|
||||
let upstreamContinuations = [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
upstreams.0.continuation = nil
|
||||
upstreams.1.continuation = nil
|
||||
upstreams.2.continuation = nil
|
||||
|
||||
self.state = .combining(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: continuation,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .resumeUpstreamContinuations(
|
||||
upstreamContinuation: upstreamContinuations
|
||||
)
|
||||
}
|
||||
|
||||
case .upstreamsFinished(var buffer):
|
||||
self.state = .modifying
|
||||
|
||||
if let element = buffer.popFirst() {
|
||||
self.state = .upstreamsFinished(buffer: buffer)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: continuation,
|
||||
result: .success(element)
|
||||
)
|
||||
} else {
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNil(continuation)
|
||||
}
|
||||
|
||||
case .upstreamThrew(let error):
|
||||
// One of the upstreams threw and we have to return this error now.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuation(downstreamContinuation: continuation, result: .failure(error))
|
||||
|
||||
case .finished:
|
||||
// We are already finished so we are just returning `nil`
|
||||
return .resumeDownstreamContinuationWithNil(continuation)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,376 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
final class CombineLatestStorage<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: Sendable where
|
||||
Base1: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
typealias StateMachine = CombineLatestStateMachine<Base1, Base2, Base3>
|
||||
|
||||
private let stateMachine: ManagedCriticalState<StateMachine>
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2, _ base3: Base3?) {
|
||||
self.stateMachine = .init(.init(base1: base1, base2: base2, base3: base3))
|
||||
}
|
||||
|
||||
func iteratorDeinitialized() {
|
||||
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
|
||||
|
||||
switch action {
|
||||
case .cancelTaskAndUpstreamContinuations(
|
||||
let task,
|
||||
let upstreamContinuation
|
||||
):
|
||||
upstreamContinuation.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element?)? {
|
||||
try await withTaskCancellationHandler {
|
||||
let result = await withUnsafeContinuation { continuation in
|
||||
let action: StateMachine.NextAction? = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
let action = stateMachine.next(for: continuation)
|
||||
switch action {
|
||||
case .startTask(let base1, let base2, let base3):
|
||||
// first iteration, we start one child task per base to iterate over them
|
||||
self.startTask(
|
||||
stateMachine: &stateMachine,
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
return nil
|
||||
|
||||
case .resumeContinuation:
|
||||
return action
|
||||
|
||||
case .resumeUpstreamContinuations:
|
||||
return action
|
||||
|
||||
case .resumeDownstreamContinuationWithNil:
|
||||
return action
|
||||
}
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .startTask:
|
||||
// We are handling the startTask in the lock already because we want to avoid
|
||||
// other inputs interleaving while starting the task
|
||||
fatalError("Internal inconsistency")
|
||||
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .resumeUpstreamContinuations(let upstreamContinuations):
|
||||
// bases can be iterated over for 1 iteration so their next value can be retrieved
|
||||
upstreamContinuations.forEach { $0.resume() }
|
||||
|
||||
case .resumeDownstreamContinuationWithNil(let continuation):
|
||||
// the async sequence is already finished, immediately resuming
|
||||
continuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
return try result._rethrowGet()
|
||||
|
||||
} onCancel: {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.cancelled()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(
|
||||
stateMachine: inout StateMachine,
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?,
|
||||
downstreamContinuation: StateMachine.DownstreamContinuation
|
||||
) {
|
||||
// This creates a new `Task` that is iterating the upstream
|
||||
// sequences. We must store it to cancel it at the right times.
|
||||
let task = Task {
|
||||
await withThrowingTaskGroup(of: Void.self) { group in
|
||||
// For each upstream sequence we are adding a child task that
|
||||
// is consuming the upstream sequence
|
||||
group.addTask {
|
||||
var base1Iterator = base1.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 0, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element1 = try await base1Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((element1, nil, nil))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished(baseIndex: 0)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
break loop
|
||||
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
break loop
|
||||
|
||||
case .none:
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
group.addTask {
|
||||
var base1Iterator = base2.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 1, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element2 = try await base1Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((nil, element2, nil))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished(baseIndex: 1)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
break loop
|
||||
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
break loop
|
||||
|
||||
case .none:
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if let base3 = base3 {
|
||||
group.addTask {
|
||||
var base1Iterator = base3.makeAsyncIterator()
|
||||
|
||||
loop: while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 2, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element3 = try await base1Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((nil, nil, element3))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished(baseIndex: 2)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
break loop
|
||||
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
break loop
|
||||
|
||||
case .none:
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
while !group.isEmpty {
|
||||
do {
|
||||
try await group.next()
|
||||
} catch {
|
||||
// One of the upstream sequences threw an error
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamThrew(error)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let error,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
downstreamContinuation.resume(returning: .failure(error))
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
group.cancelAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stateMachine.taskIsStarted(task: task, downstreamContinuation: downstreamContinuation)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that emits the latest element after a given quiescence period
|
||||
/// has elapsed by using a specified Clock.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func debounce<C: Clock>(for interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncDebounceSequence<Self, C> where Self: Sendable, Self.Element: Sendable {
|
||||
AsyncDebounceSequence(self, interval: interval, tolerance: tolerance, clock: clock)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that emits the latest element after a given quiescence period
|
||||
/// has elapsed.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public func debounce(for interval: Duration, tolerance: Duration? = nil) -> AsyncDebounceSequence<Self, ContinuousClock> where Self: Sendable, Self.Element: Sendable {
|
||||
self.debounce(for: interval, tolerance: tolerance, clock: .continuous)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that emits the latest element after a given quiescence period
|
||||
/// has elapsed.
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public struct AsyncDebounceSequence<Base: AsyncSequence & Sendable, C: Clock>: Sendable where Base.Element: Sendable {
|
||||
private let base: Base
|
||||
private let clock: C
|
||||
private let interval: C.Instant.Duration
|
||||
private let tolerance: C.Instant.Duration?
|
||||
|
||||
/// Initializes a new ``AsyncDebounceSequence``.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - base: The base sequence.
|
||||
/// - interval: The interval to debounce.
|
||||
/// - tolerance: The tolerance of the clock.
|
||||
/// - clock: The clock.
|
||||
init(_ base: Base, interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
|
||||
self.base = base
|
||||
self.interval = interval
|
||||
self.tolerance = tolerance
|
||||
self.clock = clock
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncDebounceSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
let storage = DebounceStorage(
|
||||
base: self.base,
|
||||
interval: self.interval,
|
||||
tolerance: self.tolerance,
|
||||
clock: self.clock
|
||||
)
|
||||
return Iterator(storage: storage)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncDebounceSequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
|
||||
///
|
||||
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
|
||||
final class InternalClass: Sendable {
|
||||
private let storage: DebounceStorage<Base, C>
|
||||
|
||||
fileprivate init(storage: DebounceStorage<Base, C>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
try await self.storage.next()
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: DebounceStorage<Base, C>) {
|
||||
self.internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await self.internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncDebounceSequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,706 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
struct DebounceStateMachine<Base: AsyncSequence & Sendable, C: Clock>: Sendable where Base.Element: Sendable {
|
||||
typealias Element = Base.Element
|
||||
|
||||
private enum State: Sendable {
|
||||
/// The initial state before a call to `next` happened.
|
||||
case initial(base: Base)
|
||||
|
||||
/// The state while we are waiting for downstream demand.
|
||||
case waitingForDemand(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
|
||||
bufferedElement: (element: Element, deadline: C.Instant)?
|
||||
)
|
||||
|
||||
/// The state once the downstream signalled demand but before we received
|
||||
/// the first element from the upstream.
|
||||
case demandSignalled(
|
||||
task: Task<Void, Never>,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>
|
||||
)
|
||||
|
||||
/// The state while we are consuming the upstream and waiting for the Clock.sleep to finish.
|
||||
case debouncing(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
currentElement: (element: Element, deadline: C.Instant)
|
||||
)
|
||||
|
||||
/// The state once any of the upstream sequences threw an `Error`.
|
||||
case upstreamFailure(
|
||||
error: Error
|
||||
)
|
||||
|
||||
/// The state once all upstream sequences finished or the downstream consumer stopped, i.e. by dropping all references
|
||||
/// or by getting their `Task` cancelled.
|
||||
case finished
|
||||
}
|
||||
|
||||
/// The state machine's current state.
|
||||
private var state: State
|
||||
/// The interval to debounce.
|
||||
private let interval: C.Instant.Duration
|
||||
/// The clock.
|
||||
private let clock: C
|
||||
|
||||
init(base: Base, clock: C, interval: C.Instant.Duration) {
|
||||
self.state = .initial(base: base)
|
||||
self.clock = clock
|
||||
self.interval = interval
|
||||
}
|
||||
|
||||
/// Actions returned by `iteratorDeinitialized()`.
|
||||
enum IteratorDeinitializedAction {
|
||||
/// Indicates that the `Task` needs to be cancelled and
|
||||
/// the upstream and clock continuation need to be resumed with a `CancellationError`.
|
||||
case cancelTaskAndUpstreamAndClockContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Nothing to do here. No demand was signalled until now
|
||||
return .none
|
||||
|
||||
case .debouncing, .demandSignalled:
|
||||
// An iterator was deinitialized while we have a suspended continuation.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, _):
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now and need to clean everything up.
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamAndClockContinuations(
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now. The cleanup already happened when we
|
||||
// transitioned to `upstreamFailure`.
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// We are already finished so there is nothing left to clean up.
|
||||
// This is just the references dropping afterwards.
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskStarted(_ task: Task<Void, Never>, downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>) {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// The user called `next` and we are starting the `Task`
|
||||
// to consume the upstream sequence
|
||||
self.state = .demandSignalled(
|
||||
task: task,
|
||||
clockContinuation: nil,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
|
||||
case .debouncing, .demandSignalled, .waitingForDemand, .upstreamFailure, .finished:
|
||||
// We only a single iterator to be created so this must never happen.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamTaskSuspended()`.
|
||||
enum UpstreamTaskSuspendedAction {
|
||||
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
|
||||
case resumeContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>
|
||||
)
|
||||
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
|
||||
case resumeContinuationWithError(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>,
|
||||
error: Error
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> UpstreamTaskSuspendedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(_, .some, _, _), .debouncing(_, .some, _, _):
|
||||
// We already have an upstream continuation so we can never get a second one
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .upstreamFailure:
|
||||
// The upstream already failed so it should never suspend again since the child task
|
||||
// should have exited
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(let task, .none, let clockContinuation, let bufferedElement):
|
||||
// The upstream task is ready to consume the next element
|
||||
// we are just waiting to get demand
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreamContinuation: continuation,
|
||||
clockContinuation: clockContinuation,
|
||||
bufferedElement: bufferedElement
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .demandSignalled:
|
||||
// It can happen that the demand got signalled before our upstream suspended for the first time
|
||||
// We need to resume it right away to demand the first element from the upstream
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
|
||||
case .debouncing(_, .none, _, _):
|
||||
// We are currently debouncing and the upstream task suspended again
|
||||
// We need to resume the continuation right away so that it continues to
|
||||
// consume new elements from the upstream
|
||||
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks are still getting
|
||||
// suspended even though we already cancelled them. We must tolerate this and just resume
|
||||
// the continuation with an error.
|
||||
return .resumeContinuationWithError(
|
||||
upstreamContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `elementProduced()`.
|
||||
enum ElementProducedAction {
|
||||
/// Indicates that the clock continuation should be resumed to start the `Clock.sleep`.
|
||||
case resumeClockContinuation(
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
|
||||
deadline: C.Instant
|
||||
)
|
||||
}
|
||||
|
||||
mutating func elementProduced(_ element: Element, deadline: C.Instant) -> ElementProducedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks that are producing elements are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case .waitingForDemand(_, _, _, .some):
|
||||
// We can only ever buffer one element because of the race of both child tasks
|
||||
// After that element got buffered we are not resuming the upstream continuation
|
||||
// and should never get another element until we get downstream demand signalled
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case .upstreamFailure:
|
||||
// The upstream already failed so it should never have produced another element
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, .none):
|
||||
// We got an element even though we don't have an outstanding demand
|
||||
// this can happen because we race the upstream and Clock child tasks
|
||||
// and the upstream might finish after the Clock. We just need
|
||||
// to buffer the element for the next demand.
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: clockContinuation,
|
||||
bufferedElement: (element, deadline)
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
|
||||
// This is the first element that got produced after we got demand signalled
|
||||
// We can now transition to debouncing and start the Clock.sleep
|
||||
self.state = .debouncing(
|
||||
task: task,
|
||||
upstreamContinuation: nil,
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
currentElement: (element, deadline)
|
||||
)
|
||||
|
||||
let deadline = self.clock.now.advanced(by: self.interval)
|
||||
return .resumeClockContinuation(
|
||||
clockContinuation: clockContinuation,
|
||||
deadline: deadline
|
||||
)
|
||||
|
||||
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
|
||||
// We just got another element and the Clock hasn't finished sleeping yet
|
||||
// We just need to store the new element
|
||||
self.state = .debouncing(
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
currentElement: (element, deadline)
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks
|
||||
// are still producing elements after we finished.
|
||||
// We are just going to drop them since there is nothing we can do
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamFinished()`.
|
||||
enum UpstreamFinishedAction {
|
||||
/// Indicates that the task and the clock continuation should be cancelled.
|
||||
case cancelTaskAndClockContinuation(
|
||||
task: Task<Void, Never>,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil` and
|
||||
/// the task and the upstream continuation should be cancelled.
|
||||
case resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil` and
|
||||
/// the task and the upstream continuation should be cancelled.
|
||||
case resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
element: Element,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamFinished() -> UpstreamFinishedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .waitingForDemand(_, .some, _, _):
|
||||
// We will never receive an upstream finished and have an outstanding continuation
|
||||
// since we only receive finish after resuming the upstream continuation
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .waitingForDemand(_, .none, _, .some):
|
||||
// We will never receive an upstream finished while we have a buffered element
|
||||
// To get there we would need to have received the buffered element and then
|
||||
// received upstream finished all while waiting for demand; however, we should have
|
||||
// never demanded the next element from upstream in the first place
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .upstreamFailure:
|
||||
// The upstream already failed so it should never have finished again
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(let task, .none, let clockContinuation, .none):
|
||||
// We don't have any buffered element so we can just go ahead
|
||||
// and transition to finished and cancel everything
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndClockContinuation(
|
||||
task: task,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
|
||||
// We demanded the next element from the upstream after we got signalled demand
|
||||
// and the upstream finished. This means we need to resume the downstream with nil
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuation: nil,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, let currentElement):
|
||||
// We are debouncing and the upstream finished. At this point
|
||||
// we can just resume the downstream continuation with element and cancel everything else
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
element: currentElement.element,
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: nil
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamThrew()`.
|
||||
enum UpstreamThrewAction {
|
||||
/// Indicates that the task and the clock continuation should be cancelled.
|
||||
case cancelTaskAndClockContinuation(
|
||||
task: Task<Void, Never>,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with the `error` and
|
||||
/// the task and the upstream continuation should be cancelled.
|
||||
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
error: Error,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .waitingForDemand(_, .some, _, _):
|
||||
// We will never receive an upstream threw and have an outstanding continuation
|
||||
// since we only receive threw after resuming the upstream continuation
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .waitingForDemand(_, .none, _, .some):
|
||||
// We will never receive an upstream threw while we have a buffered element
|
||||
// To get there we would need to have received the buffered element and then
|
||||
// received upstream threw all while waiting for demand; however, we should have
|
||||
// never demanded the next element from upstream in the first place
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .upstreamFailure:
|
||||
// We need to tolerate multiple upstreams failing
|
||||
return .none
|
||||
|
||||
case .waitingForDemand(let task, .none, let clockContinuation, .none):
|
||||
// We don't have any buffered element so we can just go ahead
|
||||
// and transition to finished and cancel everything
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndClockContinuation(
|
||||
task: task,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
|
||||
// We demanded the next element from the upstream after we got signalled demand
|
||||
// and the upstream threw. This means we need to resume the downstream with the error
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
error: error,
|
||||
task: task,
|
||||
upstreamContinuation: nil,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
|
||||
// We are debouncing and the upstream threw. At this point
|
||||
// we can just resume the downstream continuation with error and cancel everything else
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
error: error,
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: nil
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `clockTaskSuspended()`.
|
||||
enum ClockTaskSuspendedAction {
|
||||
/// Indicates that the continuation should be resumed which will lead to calling `sleep` on the Clock.
|
||||
case resumeContinuation(
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>,
|
||||
deadline: C.Instant
|
||||
)
|
||||
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
|
||||
case resumeContinuationWithError(
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>,
|
||||
error: Error
|
||||
)
|
||||
}
|
||||
|
||||
mutating func clockTaskSuspended(_ continuation: UnsafeContinuation<C.Instant, Error>) -> ClockTaskSuspendedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(_, _, .some, _):
|
||||
// We already have a clock continuation so we can never get a second one
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
|
||||
|
||||
case .demandSignalled(_, .some, _):
|
||||
// We already have a clock continuation so we can never get a second one
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreamContinuation, .none, let bufferedElement):
|
||||
// The clock child task suspended and we just need to store the continuation until
|
||||
// demand is signalled
|
||||
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: continuation,
|
||||
bufferedElement: bufferedElement
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .demandSignalled(let task, .none, let downstreamContinuation):
|
||||
// The demand was signalled but we haven't gotten the first element from the upstream yet
|
||||
// so we need to stay in this state and do nothing
|
||||
self.state = .demandSignalled(
|
||||
task: task,
|
||||
clockContinuation: continuation,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .debouncing(_, _, _, let currentElement):
|
||||
// We are currently debouncing and the Clock task suspended
|
||||
// We need to resume the continuation right away.
|
||||
return .resumeContinuation(
|
||||
clockContinuation: continuation,
|
||||
deadline: currentElement.deadline
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// The upstream failed while we were waiting to suspend the clock task again
|
||||
// The task should have already been cancelled and we just need to cancel the continuation
|
||||
return .resumeContinuationWithError(
|
||||
clockContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks are still getting
|
||||
// suspended even though we already cancelled them. We must tolerate this and just resume
|
||||
// the continuation with an error.
|
||||
return .resumeContinuationWithError(
|
||||
clockContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `clockSleepFinished()`.
|
||||
enum ClockSleepFinishedAction {
|
||||
/// Indicates that the downstream continuation should be resumed with the given element.
|
||||
case resumeDownstreamContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
element: Element
|
||||
)
|
||||
}
|
||||
|
||||
mutating func clockSleepFinished() -> ClockSleepFinishedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
|
||||
|
||||
case .waitingForDemand:
|
||||
// This can never happen since we kicked-off the Clock.sleep because we got signalled demand.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
|
||||
|
||||
case .demandSignalled:
|
||||
// This can never happen since we are still waiting for the first element until we resume the Clock sleep.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
|
||||
|
||||
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, let currentElement):
|
||||
if currentElement.deadline <= self.clock.now {
|
||||
// The deadline for the last produced element expired and we can forward it to the downstream
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: nil,
|
||||
bufferedElement: nil
|
||||
)
|
||||
|
||||
return .resumeDownstreamContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
element: currentElement.element
|
||||
)
|
||||
} else {
|
||||
// The deadline is still in the future so we need to sleep again
|
||||
return .none
|
||||
}
|
||||
|
||||
case .upstreamFailure:
|
||||
// The upstream failed before the Clock.sleep finished
|
||||
// We already cleaned everything up so nothing left to do here.
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// The upstream failed before the Clock.sleep finished
|
||||
// We already cleaned everything up so nothing left to do here.
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `cancelled()`.
|
||||
enum CancelledAction {
|
||||
/// Indicates that the downstream continuation needs to be resumed and
|
||||
/// task and the upstream continuations should be cancelled.
|
||||
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?
|
||||
)
|
||||
}
|
||||
|
||||
mutating func cancelled() -> CancelledAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
state = .finished
|
||||
return .none
|
||||
|
||||
case .waitingForDemand:
|
||||
// We got cancelled before we event got any demand. This can happen if a cancelled task
|
||||
// calls next and the onCancel handler runs first. We can transition to finished right away.
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
|
||||
// We got cancelled while we were waiting for the first upstream element
|
||||
// We can cancel everything at this point and return nil
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuation: nil,
|
||||
clockContinuation: clockContinuation
|
||||
)
|
||||
|
||||
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
|
||||
// We got cancelled while debouncing.
|
||||
// We can cancel everything at this point and return nil
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: nil
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// An upstream already threw and we cancelled everything already.
|
||||
// We should stay in the upstream failure state until the error is consumed
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// We are already finished so nothing to do here:
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `next()`.
|
||||
enum NextAction {
|
||||
/// Indicates that a new `Task` should be created that consumes the sequence.
|
||||
case startTask(Base)
|
||||
case resumeUpstreamContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?
|
||||
)
|
||||
case resumeUpstreamAndClockContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>?,
|
||||
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
|
||||
deadline: C.Instant
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil`.
|
||||
case resumeDownstreamContinuationWithNil(UnsafeContinuation<Result<Element?, Error>, Never>)
|
||||
/// Indicates that the downstream continuation should be resumed with the error.
|
||||
case resumeDownstreamContinuationWithError(
|
||||
UnsafeContinuation<Result<Element?, Error>, Never>,
|
||||
Error
|
||||
)
|
||||
}
|
||||
|
||||
mutating func next(for continuation: UnsafeContinuation<Result<Element?, Error>, Never>) -> NextAction {
|
||||
switch self.state {
|
||||
case .initial(let base):
|
||||
// This is the first time we get demand singalled so we have to start the task
|
||||
// The transition to the next state is done in the taskStarted method
|
||||
return .startTask(base)
|
||||
|
||||
case .demandSignalled, .debouncing:
|
||||
// We already got demand signalled and have suspended the downstream task
|
||||
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, let bufferedElement):
|
||||
if let bufferedElement = bufferedElement {
|
||||
// We already got an element from the last buffered one
|
||||
// We can kick of the clock and upstream consumption right away and transition to debouncing
|
||||
self.state = .debouncing(
|
||||
task: task,
|
||||
upstreamContinuation: nil,
|
||||
downstreamContinuation: continuation,
|
||||
currentElement: bufferedElement
|
||||
)
|
||||
|
||||
return .resumeUpstreamAndClockContinuation(
|
||||
upstreamContinuation: upstreamContinuation,
|
||||
clockContinuation: clockContinuation,
|
||||
deadline: bufferedElement.deadline
|
||||
)
|
||||
} else {
|
||||
// We don't have a buffered element so have to resume the upstream continuation
|
||||
// to get the first one and transition to demandSignalled
|
||||
self.state = .demandSignalled(
|
||||
task: task,
|
||||
clockContinuation: clockContinuation,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
|
||||
return .resumeUpstreamContinuation(upstreamContinuation: upstreamContinuation)
|
||||
}
|
||||
|
||||
case .upstreamFailure(let error):
|
||||
// The upstream threw and haven't delivered the error yet
|
||||
// Let's deliver it and transition to finished
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithError(continuation, error)
|
||||
|
||||
case .finished:
|
||||
// We are already finished so we are just returning `nil`
|
||||
return .resumeDownstreamContinuationWithNil(continuation)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,322 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
final class DebounceStorage<Base: AsyncSequence & Sendable, C: Clock>: Sendable where Base.Element: Sendable {
|
||||
typealias Element = Base.Element
|
||||
|
||||
/// The state machine protected with a lock.
|
||||
private let stateMachine: ManagedCriticalState<DebounceStateMachine<Base, C>>
|
||||
/// The interval to debounce.
|
||||
private let interval: C.Instant.Duration
|
||||
/// The tolerance for the clock.
|
||||
private let tolerance: C.Instant.Duration?
|
||||
/// The clock.
|
||||
private let clock: C
|
||||
|
||||
init(base: Base, interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
|
||||
self.stateMachine = .init(.init(base: base, clock: clock, interval: interval))
|
||||
self.interval = interval
|
||||
self.tolerance = tolerance
|
||||
self.clock = clock
|
||||
}
|
||||
|
||||
func iteratorDeinitialized() {
|
||||
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
|
||||
|
||||
switch action {
|
||||
case .cancelTaskAndUpstreamAndClockContinuations(
|
||||
let task,
|
||||
let upstreamContinuation,
|
||||
let clockContinuation
|
||||
):
|
||||
upstreamContinuation?.resume(throwing: CancellationError())
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
// We need to handle cancellation here because we are creating a continuation
|
||||
// and because we need to cancel the `Task` we created to consume the upstream
|
||||
return try await withTaskCancellationHandler {
|
||||
// We always suspend since we can never return an element right away
|
||||
|
||||
let result: Result<Element?, Error> = await withUnsafeContinuation { continuation in
|
||||
let action: DebounceStateMachine<Base, C>.NextAction? = self.stateMachine.withCriticalRegion {
|
||||
let action = $0.next(for: continuation)
|
||||
|
||||
switch action {
|
||||
case .startTask(let base):
|
||||
self.startTask(
|
||||
stateMachine: &$0,
|
||||
base: base,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
return nil
|
||||
|
||||
case .resumeUpstreamContinuation:
|
||||
return action
|
||||
|
||||
case .resumeUpstreamAndClockContinuation:
|
||||
return action
|
||||
|
||||
case .resumeDownstreamContinuationWithNil:
|
||||
return action
|
||||
|
||||
case .resumeDownstreamContinuationWithError:
|
||||
return action
|
||||
}
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .startTask:
|
||||
// We are handling the startTask in the lock already because we want to avoid
|
||||
// other inputs interleaving while starting the task
|
||||
fatalError("Internal inconsistency")
|
||||
|
||||
case .resumeUpstreamContinuation(let upstreamContinuation):
|
||||
// This is signalling the upstream task that is consuming the upstream
|
||||
// sequence to signal demand.
|
||||
upstreamContinuation?.resume(returning: ())
|
||||
|
||||
case .resumeUpstreamAndClockContinuation(let upstreamContinuation, let clockContinuation, let deadline):
|
||||
// This is signalling the upstream task that is consuming the upstream
|
||||
// sequence to signal demand and start the clock task.
|
||||
upstreamContinuation?.resume(returning: ())
|
||||
clockContinuation?.resume(returning: deadline)
|
||||
|
||||
case .resumeDownstreamContinuationWithNil(let continuation):
|
||||
continuation.resume(returning: .success(nil))
|
||||
|
||||
case .resumeDownstreamContinuationWithError(let continuation, let error):
|
||||
continuation.resume(returning: .failure(error))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
return try result._rethrowGet()
|
||||
} onCancel: {
|
||||
let action = self.stateMachine.withCriticalRegion { $0.cancelled() }
|
||||
|
||||
switch action {
|
||||
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuation,
|
||||
let clockContinuation
|
||||
):
|
||||
upstreamContinuation?.resume(throwing: CancellationError())
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(
|
||||
stateMachine: inout DebounceStateMachine<Base, C>,
|
||||
base: Base,
|
||||
downstreamContinuation: UnsafeContinuation<Result<Base.Element?, Error>, Never>
|
||||
) {
|
||||
let task = Task {
|
||||
await withThrowingTaskGroup(of: Void.self) { group in
|
||||
// The task that consumes the upstream sequence
|
||||
group.addTask {
|
||||
var iterator = base.makeAsyncIterator()
|
||||
|
||||
// This is our upstream consumption loop
|
||||
loop: while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand
|
||||
// and until the Clock sleep finished.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { $0.upstreamTaskSuspended(continuation) }
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let continuation):
|
||||
// This happens if there is outstanding demand
|
||||
// and we need to demand from upstream right away
|
||||
continuation.resume(returning: ())
|
||||
|
||||
case .resumeContinuationWithError(let continuation, let error):
|
||||
// This happens if the task got cancelled.
|
||||
continuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
// We got signalled from the downstream that we have demand so let's
|
||||
// request a new element from the upstream
|
||||
if let element = try await iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion {
|
||||
let deadline = self.clock.now.advanced(by: self.interval)
|
||||
return $0.elementProduced(element, deadline: deadline)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeClockContinuation(let clockContinuation, let deadline):
|
||||
clockContinuation?.resume(returning: deadline)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
// The upstream returned `nil` which indicates that it finished
|
||||
let action = self.stateMachine.withCriticalRegion { $0.upstreamFinished() }
|
||||
|
||||
// All of this is mostly cleanup around the Task and the outstanding
|
||||
// continuations used for signalling.
|
||||
switch action {
|
||||
case .cancelTaskAndClockContinuation(let task, let clockContinuation):
|
||||
task.cancel()
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
|
||||
break loop
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuation,
|
||||
let clockContinuation
|
||||
):
|
||||
upstreamContinuation?.resume(throwing: CancellationError())
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
break loop
|
||||
|
||||
case .resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
|
||||
let downstreamContinuation,
|
||||
let element,
|
||||
let task,
|
||||
let upstreamContinuation,
|
||||
let clockContinuation
|
||||
):
|
||||
upstreamContinuation?.resume(throwing: CancellationError())
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(element))
|
||||
|
||||
break loop
|
||||
|
||||
case .none:
|
||||
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
group.addTask {
|
||||
// This is our clock scheduling loop
|
||||
loop: while true {
|
||||
do {
|
||||
// We are creating a continuation sleeping on the Clock.
|
||||
// This continuation is only resumed if the downstream consumer called `next`.
|
||||
let deadline: C.Instant = try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { $0.clockTaskSuspended(continuation) }
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let continuation, let deadline):
|
||||
// This happens if there is outstanding demand
|
||||
// and we need to demand from upstream right away
|
||||
continuation.resume(returning: deadline)
|
||||
|
||||
case .resumeContinuationWithError(let continuation, let error):
|
||||
// This happens if the task got cancelled.
|
||||
continuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
try await self.clock.sleep(until: deadline, tolerance: self.tolerance)
|
||||
|
||||
let action = self.stateMachine.withCriticalRegion { $0.clockSleepFinished() }
|
||||
|
||||
switch action {
|
||||
case .resumeDownstreamContinuation(let downstreamContinuation, let element):
|
||||
downstreamContinuation.resume(returning: .success(element))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} catch {
|
||||
// The only error that we expect is the `CancellationError`
|
||||
// thrown from the Clock.sleep or from the withUnsafeContinuation.
|
||||
// This happens if we are cleaning everything up. We can just drop that error and break our loop
|
||||
precondition(error is CancellationError, "Received unexpected error \(error) in the Clock loop")
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
while !group.isEmpty {
|
||||
do {
|
||||
try await group.next()
|
||||
} catch {
|
||||
// One of the upstream sequences threw an error
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamThrew(error)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
|
||||
let downstreamContinuation,
|
||||
let error,
|
||||
let task,
|
||||
let upstreamContinuation,
|
||||
let clockContinuation
|
||||
):
|
||||
upstreamContinuation?.resume(throwing: CancellationError())
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .failure(error))
|
||||
|
||||
case .cancelTaskAndClockContinuation(
|
||||
let task,
|
||||
let clockContinuation
|
||||
):
|
||||
clockContinuation?.resume(throwing: CancellationError())
|
||||
task.cancel()
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
group.cancelAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stateMachine.taskStarted(task, downstreamContinuation: downstreamContinuation)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension Dictionary {
|
||||
/// Creates a new dictionary from the key-value pairs in the given asynchronous sequence.
|
||||
///
|
||||
/// You use this initializer to create a dictionary when you have an asynchronous sequence
|
||||
/// of key-value tuples with unique keys. Passing an asynchronous sequence with duplicate
|
||||
/// keys to this initializer results in a runtime error. If your
|
||||
/// asynchronous sequence might have duplicate keys, use the
|
||||
/// `Dictionary(_:uniquingKeysWith:)` initializer instead.
|
||||
///
|
||||
/// - Parameter keysAndValues: An asynchronous sequence of key-value pairs to use for
|
||||
/// the new dictionary. Every key in `keysAndValues` must be unique.
|
||||
/// - Returns: A new dictionary initialized with the elements of
|
||||
/// `keysAndValues`.
|
||||
/// - Precondition: The sequence must not have duplicate keys.
|
||||
@inlinable
|
||||
public init<S: AsyncSequence>(uniqueKeysWithValues keysAndValues: S) async rethrows where S.Element == (Key, Value) {
|
||||
self.init(uniqueKeysWithValues: try await Array(keysAndValues))
|
||||
}
|
||||
|
||||
/// Creates a new dictionary from the key-value pairs in the given asynchronous sequence,
|
||||
/// using a combining closure to determine the value for any duplicate keys.
|
||||
///
|
||||
/// You use this initializer to create a dictionary when you have a sequence
|
||||
/// of key-value tuples that might have duplicate keys. As the dictionary is
|
||||
/// built, the initializer calls the `combine` closure with the current and
|
||||
/// new values for any duplicate keys. Pass a closure as `combine` that
|
||||
/// returns the value to use in the resulting dictionary: The closure can
|
||||
/// choose between the two values, combine them to produce a new value, or
|
||||
/// even throw an error.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - keysAndValues: An asynchronous sequence of key-value pairs to use for the new
|
||||
/// dictionary.
|
||||
/// - combine: A closure that is called with the values for any duplicate
|
||||
/// keys that are encountered. The closure returns the desired value for
|
||||
/// the final dictionary, or throws an error if building the dictionary
|
||||
/// can't proceed.
|
||||
@inlinable
|
||||
public init<S: AsyncSequence>(_ keysAndValues: S, uniquingKeysWith combine: (Value, Value) async throws -> Value) async rethrows where S.Element == (Key, Value) {
|
||||
self.init()
|
||||
for try await (key, value) in keysAndValues {
|
||||
if let existing = self[key] {
|
||||
self[key] = try await combine(existing, value)
|
||||
} else {
|
||||
self[key] = value
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a new dictionary whose keys are the groupings returned by the
|
||||
/// given closure and whose values are arrays of the elements that returned
|
||||
/// each key.
|
||||
///
|
||||
/// The arrays in the "values" position of the new dictionary each contain at
|
||||
/// least one element, with the elements in the same order as the source
|
||||
/// asynchronous sequence.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - values: An asynchronous sequence of values to group into a dictionary.
|
||||
/// - keyForValue: A closure that returns a key for each element in
|
||||
/// `values`.
|
||||
@inlinable
|
||||
public init<S: AsyncSequence>(grouping values: S, by keyForValue: (S.Element) async throws -> Key) async rethrows where Value == [S.Element] {
|
||||
self.init()
|
||||
for try await value in values {
|
||||
let key = try await keyForValue(value)
|
||||
self[key, default: []].append(value)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,444 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension AsyncSequence {
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: "-")
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: The value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: { "-" })
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () -> Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: { "-" })
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () async -> Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: { "-" })
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () throws -> Element) -> AsyncThrowingInterspersedSequence<Self> {
|
||||
AsyncThrowingInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
|
||||
/// Returns a new asynchronous sequence containing the elements of this asynchronous sequence, inserting
|
||||
/// the given separator between each element.
|
||||
///
|
||||
/// Any value of this asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// The following example shows how an async sequences of `String`s can be interspersed using `-` as the separator:
|
||||
///
|
||||
/// ```
|
||||
/// let input = ["A", "B", "C"].async
|
||||
/// let interspersed = input.interspersed(with: { "-" })
|
||||
/// for await element in interspersed {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// // Prints "A" "-" "B" "-" "C"
|
||||
/// ```
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - every: Dictates after how many elements a separator should be inserted.
|
||||
/// - separator: A closure that produces the value to insert in between each of this async sequence’s elements.
|
||||
/// - Returns: The interspersed asynchronous sequence of elements.
|
||||
@inlinable
|
||||
public func interspersed(every: Int = 1, with separator: @Sendable @escaping () async throws -> Element) -> AsyncThrowingInterspersedSequence<Self> {
|
||||
AsyncThrowingInterspersedSequence(self, every: every, separator: separator)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that presents the elements of a base asynchronous sequence of
|
||||
/// elements with a separator between each of those elements.
|
||||
public struct AsyncInterspersedSequence<Base: AsyncSequence> {
|
||||
@usableFromInline
|
||||
internal enum Separator {
|
||||
case element(Element)
|
||||
case syncClosure(@Sendable () -> Element)
|
||||
case asyncClosure(@Sendable () async -> Element)
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal let base: Base
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .element(separator)
|
||||
self.every = every
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .syncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () async -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .asyncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInterspersedSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncInterspersedSequence` asynchronous sequence.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
internal enum State {
|
||||
case start(Element?)
|
||||
case element(Int)
|
||||
case separator
|
||||
case finished
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal var state = State.start(nil)
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ iterator: Base.AsyncIterator, every: Int, separator: Separator) {
|
||||
self.iterator = iterator
|
||||
self.separator = separator
|
||||
self.every = every
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Base.Element? {
|
||||
switch self.state {
|
||||
case .start(var element):
|
||||
do {
|
||||
if element == nil {
|
||||
element = try await self.iterator.next()
|
||||
}
|
||||
|
||||
if let element = element {
|
||||
if self.every == 1 {
|
||||
self.state = .separator
|
||||
} else {
|
||||
self.state = .element(1)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .separator:
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
self.state = .start(element)
|
||||
switch self.separator {
|
||||
case .element(let element):
|
||||
return element
|
||||
|
||||
case .syncClosure(let closure):
|
||||
return closure()
|
||||
|
||||
case .asyncClosure(let closure):
|
||||
return await closure()
|
||||
}
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .element(let count):
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
let newCount = count + 1
|
||||
if self.every == newCount {
|
||||
self.state = .separator
|
||||
} else {
|
||||
self.state = .element(newCount)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .finished:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(self.base.makeAsyncIterator(), every: self.every, separator: self.separator)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that presents the elements of a base asynchronous sequence of
|
||||
/// elements with a separator between each of those elements.
|
||||
public struct AsyncThrowingInterspersedSequence<Base: AsyncSequence> {
|
||||
@usableFromInline
|
||||
internal enum Separator {
|
||||
case syncClosure(@Sendable () throws -> Element)
|
||||
case asyncClosure(@Sendable () async throws -> Element)
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal let base: Base
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () throws -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .syncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ base: Base, every: Int, separator: @Sendable @escaping () async throws -> Element) {
|
||||
precondition(every > 0, "Separators can only be interspersed every 1+ elements")
|
||||
self.base = base
|
||||
self.separator = .asyncClosure(separator)
|
||||
self.every = every
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingInterspersedSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for an `AsyncInterspersedSequence` asynchronous sequence.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
internal enum State {
|
||||
case start(Element?)
|
||||
case element(Int)
|
||||
case separator
|
||||
case finished
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Separator
|
||||
|
||||
@usableFromInline
|
||||
internal let every: Int
|
||||
|
||||
@usableFromInline
|
||||
internal var state = State.start(nil)
|
||||
|
||||
@usableFromInline
|
||||
internal init(_ iterator: Base.AsyncIterator, every: Int, separator: Separator) {
|
||||
self.iterator = iterator
|
||||
self.separator = separator
|
||||
self.every = every
|
||||
}
|
||||
|
||||
public mutating func next() async throws -> Base.Element? {
|
||||
switch self.state {
|
||||
case .start(var element):
|
||||
do {
|
||||
if element == nil {
|
||||
element = try await self.iterator.next()
|
||||
}
|
||||
|
||||
if let element = element {
|
||||
if self.every == 1 {
|
||||
self.state = .separator
|
||||
} else {
|
||||
self.state = .element(1)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .separator:
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
self.state = .start(element)
|
||||
switch self.separator {
|
||||
case .syncClosure(let closure):
|
||||
return try closure()
|
||||
|
||||
case .asyncClosure(let closure):
|
||||
return try await closure()
|
||||
}
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .element(let count):
|
||||
do {
|
||||
if let element = try await iterator.next() {
|
||||
let newCount = count + 1
|
||||
if self.every == newCount {
|
||||
self.state = .separator
|
||||
} else {
|
||||
self.state = .element(newCount)
|
||||
}
|
||||
return element
|
||||
} else {
|
||||
self.state = .finished
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
self.state = .finished
|
||||
throw error
|
||||
}
|
||||
|
||||
case .finished:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(self.base.makeAsyncIterator(), every: self.every, separator: self.separator)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInterspersedSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
extension AsyncInterspersedSequence.Separator: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
extension AsyncThrowingInterspersedSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
extension AsyncThrowingInterspersedSequence.Separator: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncInterspersedSequence.Iterator: Sendable {}
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingInterspersedSequence.Iterator: Sendable {}
|
||||
@@ -0,0 +1,156 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 canImport(Darwin)
|
||||
import Darwin
|
||||
#elseif canImport(Glibc)
|
||||
import Glibc
|
||||
#elseif canImport(Musl)
|
||||
import Musl
|
||||
#elseif canImport(WinSDK)
|
||||
import WinSDK
|
||||
#elseif canImport(Bionic)
|
||||
import Bionic
|
||||
#else
|
||||
#error("Unsupported platform")
|
||||
#endif
|
||||
|
||||
internal struct Lock {
|
||||
#if canImport(Darwin)
|
||||
typealias Primitive = os_unfair_lock
|
||||
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
|
||||
typealias Primitive = pthread_mutex_t
|
||||
#elseif canImport(WinSDK)
|
||||
typealias Primitive = SRWLOCK
|
||||
#else
|
||||
#error("Unsupported platform")
|
||||
#endif
|
||||
|
||||
typealias PlatformLock = UnsafeMutablePointer<Primitive>
|
||||
let platformLock: PlatformLock
|
||||
|
||||
private init(_ platformLock: PlatformLock) {
|
||||
self.platformLock = platformLock
|
||||
}
|
||||
|
||||
fileprivate static func initialize(_ platformLock: PlatformLock) {
|
||||
#if canImport(Darwin)
|
||||
platformLock.initialize(to: os_unfair_lock())
|
||||
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
|
||||
let result = pthread_mutex_init(platformLock, nil)
|
||||
precondition(result == 0, "pthread_mutex_init failed")
|
||||
#elseif canImport(WinSDK)
|
||||
InitializeSRWLock(platformLock)
|
||||
#else
|
||||
#error("Unsupported platform")
|
||||
#endif
|
||||
}
|
||||
|
||||
fileprivate static func deinitialize(_ platformLock: PlatformLock) {
|
||||
#if canImport(Glibc) || canImport(Musl) || canImport(Bionic)
|
||||
let result = pthread_mutex_destroy(platformLock)
|
||||
precondition(result == 0, "pthread_mutex_destroy failed")
|
||||
#endif
|
||||
platformLock.deinitialize(count: 1)
|
||||
}
|
||||
|
||||
fileprivate static func lock(_ platformLock: PlatformLock) {
|
||||
#if canImport(Darwin)
|
||||
os_unfair_lock_lock(platformLock)
|
||||
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
|
||||
pthread_mutex_lock(platformLock)
|
||||
#elseif canImport(WinSDK)
|
||||
AcquireSRWLockExclusive(platformLock)
|
||||
#else
|
||||
#error("Unsupported platform")
|
||||
#endif
|
||||
}
|
||||
|
||||
fileprivate static func unlock(_ platformLock: PlatformLock) {
|
||||
#if canImport(Darwin)
|
||||
os_unfair_lock_unlock(platformLock)
|
||||
#elseif canImport(Glibc) || canImport(Musl) || canImport(Bionic)
|
||||
let result = pthread_mutex_unlock(platformLock)
|
||||
precondition(result == 0, "pthread_mutex_unlock failed")
|
||||
#elseif canImport(WinSDK)
|
||||
ReleaseSRWLockExclusive(platformLock)
|
||||
#else
|
||||
#error("Unsupported platform")
|
||||
#endif
|
||||
}
|
||||
|
||||
static func allocate() -> Lock {
|
||||
let platformLock = PlatformLock.allocate(capacity: 1)
|
||||
initialize(platformLock)
|
||||
return Lock(platformLock)
|
||||
}
|
||||
|
||||
func deinitialize() {
|
||||
Lock.deinitialize(platformLock)
|
||||
platformLock.deallocate()
|
||||
}
|
||||
|
||||
func lock() {
|
||||
Lock.lock(platformLock)
|
||||
}
|
||||
|
||||
func unlock() {
|
||||
Lock.unlock(platformLock)
|
||||
}
|
||||
|
||||
/// Acquire the lock for the duration of the given block.
|
||||
///
|
||||
/// This convenience method should be preferred to `lock` and `unlock` in
|
||||
/// most situations, as it ensures that the lock will be released regardless
|
||||
/// of how `body` exits.
|
||||
///
|
||||
/// - Parameter body: The block to execute while holding the lock.
|
||||
/// - Returns: The value returned by the block.
|
||||
func withLock<T>(_ body: () throws -> T) rethrows -> T {
|
||||
self.lock()
|
||||
defer {
|
||||
self.unlock()
|
||||
}
|
||||
return try body()
|
||||
}
|
||||
|
||||
// specialise Void return (for performance)
|
||||
func withLockVoid(_ body: () throws -> Void) rethrows -> Void {
|
||||
try self.withLock(body)
|
||||
}
|
||||
}
|
||||
|
||||
struct ManagedCriticalState<State> {
|
||||
private final class LockedBuffer: ManagedBuffer<State, Lock.Primitive> {
|
||||
deinit {
|
||||
withUnsafeMutablePointerToElements { Lock.deinitialize($0) }
|
||||
}
|
||||
}
|
||||
|
||||
private let buffer: ManagedBuffer<State, Lock.Primitive>
|
||||
|
||||
init(_ initial: State) {
|
||||
buffer = LockedBuffer.create(minimumCapacity: 1) { buffer in
|
||||
buffer.withUnsafeMutablePointerToElements { Lock.initialize($0) }
|
||||
return initial
|
||||
}
|
||||
}
|
||||
|
||||
func withCriticalRegion<R>(_ critical: (inout State) throws -> R) rethrows -> R {
|
||||
try buffer.withUnsafeMutablePointers { header, lock in
|
||||
Lock.lock(lock)
|
||||
defer { Lock.unlock(lock) }
|
||||
return try critical(&header.pointee)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension ManagedCriticalState: @unchecked Sendable where State: Sendable { }
|
||||
@@ -0,0 +1,97 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
/// Creates an asynchronous sequence of elements from two underlying asynchronous sequences
|
||||
public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
return AsyncMerge2Sequence(base1, base2)
|
||||
}
|
||||
|
||||
/// An ``Swift/AsyncSequence`` that takes two upstream ``Swift/AsyncSequence``s and combines their elements.
|
||||
public struct AsyncMerge2Sequence<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence
|
||||
>: Sendable where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
private let base1: Base1
|
||||
private let base2: Base2
|
||||
|
||||
/// Initializes a new ``AsyncMerge2Sequence``.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - base1: The first upstream ``Swift/AsyncSequence``.
|
||||
/// - base2: The second upstream ``Swift/AsyncSequence``.
|
||||
init(
|
||||
_ base1: Base1,
|
||||
_ base2: Base2
|
||||
) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncMerge2Sequence: AsyncSequence {
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
let storage = MergeStorage<Base1, Base2, Base1>(
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: nil
|
||||
)
|
||||
return Iterator(storage: storage)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncMerge2Sequence {
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
|
||||
///
|
||||
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
|
||||
final class InternalClass: Sendable {
|
||||
private let storage: MergeStorage<Base1, Base2, Base1>
|
||||
|
||||
fileprivate init(storage: MergeStorage<Base1, Base2, Base1>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
try await storage.next()
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: MergeStorage<Base1, Base2, Base1>) {
|
||||
internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncMerge2Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,108 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
/// Creates an asynchronous sequence of elements from two underlying asynchronous sequences
|
||||
public func merge<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncMerge3Sequence<Base1, Base2, Base3>
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
return AsyncMerge3Sequence(base1, base2, base3)
|
||||
}
|
||||
|
||||
/// An ``Swift/AsyncSequence`` that takes three upstream ``Swift/AsyncSequence``s and combines their elements.
|
||||
public struct AsyncMerge3Sequence<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: Sendable where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
private let base1: Base1
|
||||
private let base2: Base2
|
||||
private let base3: Base3
|
||||
|
||||
/// Initializes a new ``AsyncMerge2Sequence``.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - base1: The first upstream ``Swift/AsyncSequence``.
|
||||
/// - base2: The second upstream ``Swift/AsyncSequence``.
|
||||
/// - base3: The third upstream ``Swift/AsyncSequence``.
|
||||
init(
|
||||
_ base1: Base1,
|
||||
_ base2: Base2,
|
||||
_ base3: Base3
|
||||
) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncMerge3Sequence: AsyncSequence {
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
let storage = MergeStorage(
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3
|
||||
)
|
||||
return Iterator(storage: storage)
|
||||
}
|
||||
}
|
||||
|
||||
public extension AsyncMerge3Sequence {
|
||||
struct Iterator: AsyncIteratorProtocol {
|
||||
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
|
||||
///
|
||||
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
|
||||
final class InternalClass: Sendable {
|
||||
private let storage: MergeStorage<Base1, Base2, Base3>
|
||||
|
||||
fileprivate init(storage: MergeStorage<Base1, Base2, Base3>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
try await storage.next()
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: MergeStorage<Base1, Base2, Base3>) {
|
||||
internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncMerge3Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,629 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 DequeModule
|
||||
|
||||
/// The state machine for any of the `merge` operator.
|
||||
///
|
||||
/// Right now this state machine supports 3 upstream `AsyncSequences`; however, this can easily be extended.
|
||||
/// Once variadic generic land we should migrate this to use them instead.
|
||||
struct MergeStateMachine<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
> where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
typealias Element = Base1.Element
|
||||
|
||||
private enum State {
|
||||
/// The initial state before a call to `makeAsyncIterator` happened.
|
||||
case initial(
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?
|
||||
)
|
||||
|
||||
/// The state after `makeAsyncIterator` was called and we created our `Task` to consume the upstream.
|
||||
case merging(
|
||||
task: Task<Void, Never>,
|
||||
buffer: Deque<Element>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>],
|
||||
upstreamsFinished: Int,
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>?
|
||||
)
|
||||
|
||||
/// The state once any of the upstream sequences threw an `Error`.
|
||||
case upstreamFailure(
|
||||
buffer: Deque<Element>,
|
||||
error: Error
|
||||
)
|
||||
|
||||
/// The state once all upstream sequences finished or the downstream consumer stopped, i.e. by dropping all references
|
||||
/// or by getting their `Task` cancelled.
|
||||
case finished
|
||||
|
||||
/// Internal state to avoid CoW.
|
||||
case modifying
|
||||
}
|
||||
|
||||
/// The state machine's current state.
|
||||
private var state: State
|
||||
|
||||
private let numberOfUpstreamSequences: Int
|
||||
|
||||
/// Initializes a new `StateMachine`.
|
||||
init(
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?
|
||||
) {
|
||||
state = .initial(
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3
|
||||
)
|
||||
|
||||
if base3 == nil {
|
||||
self.numberOfUpstreamSequences = 2
|
||||
} else {
|
||||
self.numberOfUpstreamSequences = 3
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `iteratorDeinitialized()`.
|
||||
enum IteratorDeinitializedAction {
|
||||
/// Indicates that the `Task` needs to be cancelled and
|
||||
/// all upstream continuations need to be resumed with a `CancellationError`.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
// Nothing to do here. No demand was signalled until now
|
||||
return .none
|
||||
|
||||
case .merging(_, _, _, _, .some):
|
||||
// An iterator was deinitialized while we have a suspended continuation.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
|
||||
|
||||
case let .merging(task, _, upstreamContinuations, _, .none):
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now and need to clean everything up.
|
||||
state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now. The cleanup already happened when we
|
||||
// transitioned to `upstreamFailure`.
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// We are already finished so there is nothing left to clean up.
|
||||
// This is just the references dropping afterwards.
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskStarted(_ task: Task<Void, Never>) {
|
||||
switch state {
|
||||
case .initial:
|
||||
// The user called `makeAsyncIterator` and we are starting the `Task`
|
||||
// to consume the upstream sequences
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: .init(),
|
||||
upstreamContinuations: [], // This should reserve capacity in the variadic generics case
|
||||
upstreamsFinished: 0,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
case .merging, .upstreamFailure, .finished:
|
||||
// We only a single iterator to be created so this must never happen.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `childTaskSuspended()`.
|
||||
enum ChildTaskSuspendedAction {
|
||||
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
|
||||
case resumeContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>
|
||||
)
|
||||
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
|
||||
case resumeContinuationWithError(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>,
|
||||
error: Error
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func childTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .merging(_, _, _, _, .some):
|
||||
// We have outstanding demand so request the next element
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
|
||||
case .merging(let task, let buffer, var upstreamContinuations, let upstreamsFinished, .none):
|
||||
// There is no outstanding demand from the downstream
|
||||
// so we are storing the continuation and resume it once there is demand.
|
||||
state = .modifying
|
||||
|
||||
upstreamContinuations.append(continuation)
|
||||
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .upstreamFailure:
|
||||
// Another upstream already threw so we just need to throw from this continuation
|
||||
// which will end the consumption of the upstream.
|
||||
|
||||
return .resumeContinuationWithError(
|
||||
upstreamContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks are still getting
|
||||
// suspended even though we already cancelled them. We must tolerate this and just resume
|
||||
// the continuation with an error.
|
||||
return .resumeContinuationWithError(
|
||||
upstreamContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `elementProduced()`.
|
||||
enum ElementProducedAction {
|
||||
/// Indicates that the downstream continuation should be resumed with the element.
|
||||
case resumeContinuation(
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>,
|
||||
element: Element
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func elementProduced(_ element: Element) -> ElementProducedAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
// Child tasks that are producing elements are only created after we transitioned to `merging`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case let .merging(task, buffer, upstreamContinuations, upstreamsFinished, .some(downstreamContinuation)):
|
||||
// We produced an element and have an outstanding downstream continuation
|
||||
// this means we can go right ahead and resume the continuation with that element
|
||||
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
|
||||
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
element: element
|
||||
)
|
||||
|
||||
case .merging(let task, var buffer, let upstreamContinuations, let upstreamsFinished, .none):
|
||||
// There is not outstanding downstream continuation so we must buffer the element
|
||||
// This happens if we race our upstream sequences to produce elements
|
||||
// and the _losers_ are signalling their produced element
|
||||
state = .modifying
|
||||
|
||||
buffer.append(element)
|
||||
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .upstreamFailure:
|
||||
// Another upstream already produced an error so we just drop the new element
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks
|
||||
// are still producing elements after we finished.
|
||||
// We are just going to drop them since there is nothing we can do
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamFinished()`.
|
||||
enum UpstreamFinishedAction {
|
||||
/// Indicates that the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func upstreamFinished() -> UpstreamFinishedAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .merging(let task, let buffer, let upstreamContinuations, var upstreamsFinished, let .some(downstreamContinuation)):
|
||||
// One of the upstreams finished
|
||||
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
|
||||
|
||||
// First we increment our counter of finished upstreams
|
||||
upstreamsFinished += 1
|
||||
|
||||
if upstreamsFinished == self.numberOfUpstreamSequences {
|
||||
// All of our upstreams have finished and we can transition to finished now
|
||||
// We also need to cancel the tasks and any outstanding continuations
|
||||
state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
} else {
|
||||
// There are still upstreams that haven't finished so we are just storing our new
|
||||
// counter of finished upstreams
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
|
||||
return .none
|
||||
}
|
||||
|
||||
case .merging(let task, let buffer, let upstreamContinuations, var upstreamsFinished, .none):
|
||||
// First we increment our counter of finished upstreams
|
||||
upstreamsFinished += 1
|
||||
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
if upstreamsFinished == self.numberOfUpstreamSequences {
|
||||
// All of our upstreams have finished; however, we are only transitioning to
|
||||
// finished once our downstream calls `next` again.
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
} else {
|
||||
// There are still upstreams that haven't finished.
|
||||
return .none
|
||||
}
|
||||
|
||||
case .upstreamFailure:
|
||||
// Another upstream threw already so we can just ignore this finish
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamThrew()`.
|
||||
enum UpstreamThrewAction {
|
||||
/// Indicates that the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with the `error` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>,
|
||||
error: Error,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case let .merging(task, buffer, upstreamContinuations, _, .some(downstreamContinuation)):
|
||||
// An upstream threw an error and we have a downstream continuation.
|
||||
// We just need to resume the downstream continuation with the error and cancel everything
|
||||
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
|
||||
|
||||
// We can transition to finished right away because we are returning the error
|
||||
state = .finished
|
||||
|
||||
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
error: error,
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case let .merging(task, buffer, upstreamContinuations, _, .none):
|
||||
// An upstream threw an error and we don't have a downstream continuation.
|
||||
// We need to store the error and wait for the downstream to consume the
|
||||
// rest of the buffer and the error. However, we can already cancel the task
|
||||
// and the other upstream continuations since we won't need any more elements.
|
||||
state = .upstreamFailure(
|
||||
buffer: buffer,
|
||||
error: error
|
||||
)
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// Another upstream threw already so we can just ignore this error
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `cancelled()`.
|
||||
enum CancelledAction {
|
||||
/// Indicates that the downstream continuation needs to be resumed and
|
||||
/// task and the upstream continuations should be cancelled.
|
||||
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: UnsafeContinuation<Element?, Error>,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that nothing should be done.
|
||||
case none
|
||||
}
|
||||
|
||||
mutating func cancelled() -> CancelledAction {
|
||||
switch state {
|
||||
case .initial:
|
||||
// Since we are only transitioning to merging when the task is started we
|
||||
// can be cancelled already.
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case let .merging(task, _, upstreamContinuations, _, .some(downstreamContinuation)):
|
||||
// The downstream Task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case let .merging(task, _, upstreamContinuations, _, .none):
|
||||
// The downstream Task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case .upstreamFailure:
|
||||
// An upstream already threw and we cancelled everything already.
|
||||
// We can just transition to finished now
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .finished:
|
||||
// We are already finished so nothing to do here:
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `next()`.
|
||||
enum NextAction {
|
||||
/// Indicates that a new `Task` should be created that consumes the sequence and the downstream must be supsended
|
||||
case startTaskAndSuspendDownstreamTask(Base1, Base2, Base3?)
|
||||
/// Indicates that the `element` should be returned.
|
||||
case returnElement(Result<Element, Error>)
|
||||
/// Indicates that `nil` should be returned.
|
||||
case returnNil
|
||||
/// Indicates that the `error` should be thrown.
|
||||
case throwError(Error)
|
||||
/// Indicates that the downstream task should be suspended.
|
||||
case suspendDownstreamTask
|
||||
}
|
||||
|
||||
mutating func next() -> NextAction {
|
||||
switch state {
|
||||
case .initial(let base1, let base2, let base3):
|
||||
// This is the first time we got demand signalled. We need to start the task now
|
||||
// We are transitioning to merging in the taskStarted method.
|
||||
return .startTaskAndSuspendDownstreamTask(base1, base2, base3)
|
||||
|
||||
case .merging(_, _, _, _, .some):
|
||||
// We have multiple AsyncIterators iterating the sequence
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
|
||||
|
||||
case .merging(let task, var buffer, let upstreamContinuations, let upstreamsFinished, .none):
|
||||
state = .modifying
|
||||
|
||||
if let element = buffer.popFirst() {
|
||||
// We have an element buffered already so we can just return that.
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
return .returnElement(.success(element))
|
||||
} else {
|
||||
// There was nothing in the buffer so we have to suspend the downstream task
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: upstreamContinuations,
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: nil
|
||||
)
|
||||
|
||||
return .suspendDownstreamTask
|
||||
}
|
||||
|
||||
case .upstreamFailure(var buffer, let error):
|
||||
state = .modifying
|
||||
|
||||
if let element = buffer.popFirst() {
|
||||
// There was still a left over element that we need to return
|
||||
state = .upstreamFailure(
|
||||
buffer: buffer,
|
||||
error: error
|
||||
)
|
||||
|
||||
return .returnElement(.success(element))
|
||||
} else {
|
||||
// The buffer is empty and we can now throw the error
|
||||
// that an upstream produced
|
||||
state = .finished
|
||||
|
||||
return .throwError(error)
|
||||
}
|
||||
|
||||
case .finished:
|
||||
// We are already finished so we are just returning `nil`
|
||||
return .returnNil
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `next(for)`.
|
||||
enum NextForAction {
|
||||
/// Indicates that the upstream continuations should be resumed to demand new elements.
|
||||
case resumeUpstreamContinuations(
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func next(for continuation: UnsafeContinuation<Element?, Error>) -> NextForAction {
|
||||
switch state {
|
||||
case .initial,
|
||||
.merging(_, _, _, _, .some),
|
||||
.upstreamFailure,
|
||||
.finished:
|
||||
// All other states are handled by `next` already so we should never get in here with
|
||||
// any of those
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received next(for:)")
|
||||
|
||||
case let .merging(task, buffer, upstreamContinuations, upstreamsFinished, .none):
|
||||
// We suspended the task and need signal the upstreams
|
||||
state = .merging(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
upstreamContinuations: [], // TODO: don't alloc new array here
|
||||
upstreamsFinished: upstreamsFinished,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
|
||||
return .resumeUpstreamContinuations(
|
||||
upstreamContinuations: upstreamContinuations
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,288 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
final class MergeStorage<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: @unchecked Sendable where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable
|
||||
{
|
||||
typealias Element = Base1.Element
|
||||
|
||||
/// The lock that protects our state.
|
||||
private let lock = Lock.allocate()
|
||||
/// The state machine.
|
||||
private var stateMachine: MergeStateMachine<Base1, Base2, Base3>
|
||||
|
||||
init(
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?
|
||||
) {
|
||||
stateMachine = .init(base1: base1, base2: base2, base3: base3)
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.lock.deinitialize()
|
||||
}
|
||||
|
||||
func iteratorDeinitialized() {
|
||||
let action = lock.withLock { self.stateMachine.iteratorDeinitialized() }
|
||||
|
||||
switch action {
|
||||
case let .cancelTaskAndUpstreamContinuations(
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
// We need to handle cancellation here because we are creating a continuation
|
||||
// and because we need to cancel the `Task` we created to consume the upstream
|
||||
try await withTaskCancellationHandler {
|
||||
self.lock.lock()
|
||||
let action = self.stateMachine.next()
|
||||
|
||||
switch action {
|
||||
case .startTaskAndSuspendDownstreamTask(let base1, let base2, let base3):
|
||||
self.startTask(
|
||||
stateMachine: &self.stateMachine,
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3
|
||||
)
|
||||
// It is safe to hold the lock across this method
|
||||
// since the closure is guaranteed to be run straight away
|
||||
return try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.next(for: continuation)
|
||||
self.lock.unlock()
|
||||
|
||||
switch action {
|
||||
case let .resumeUpstreamContinuations(upstreamContinuations):
|
||||
// This is signalling the child tasks that are consuming the upstream
|
||||
// sequences to signal demand.
|
||||
upstreamContinuations.forEach { $0.resume(returning: ()) }
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
case let .returnElement(element):
|
||||
self.lock.unlock()
|
||||
|
||||
return try element._rethrowGet()
|
||||
|
||||
case .returnNil:
|
||||
self.lock.unlock()
|
||||
return nil
|
||||
|
||||
case let .throwError(error):
|
||||
self.lock.unlock()
|
||||
throw error
|
||||
|
||||
case .suspendDownstreamTask:
|
||||
// It is safe to hold the lock across this method
|
||||
// since the closure is guaranteed to be run straight away
|
||||
return try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.next(for: continuation)
|
||||
self.lock.unlock()
|
||||
|
||||
switch action {
|
||||
case let .resumeUpstreamContinuations(upstreamContinuations):
|
||||
// This is signalling the child tasks that are consuming the upstream
|
||||
// sequences to signal demand.
|
||||
upstreamContinuations.forEach { $0.resume(returning: ()) }
|
||||
}
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
let action = self.lock.withLock { self.stateMachine.cancelled() }
|
||||
|
||||
switch action {
|
||||
case let .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation,
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: nil)
|
||||
|
||||
case let .cancelTaskAndUpstreamContinuations(
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(stateMachine: inout MergeStateMachine<Base1, Base2, Base3>, base1: Base1, base2: Base2, base3: Base3?) {
|
||||
// This creates a new `Task` that is iterating the upstream
|
||||
// sequences. We must store it to cancel it at the right times.
|
||||
let task = Task {
|
||||
await withThrowingTaskGroup(of: Void.self) { group in
|
||||
self.iterateAsyncSequence(base1, in: &group)
|
||||
self.iterateAsyncSequence(base2, in: &group)
|
||||
|
||||
// Copy from the above just using the base3 sequence
|
||||
if let base3 = base3 {
|
||||
self.iterateAsyncSequence(base3, in: &group)
|
||||
}
|
||||
|
||||
while !group.isEmpty {
|
||||
do {
|
||||
try await group.next()
|
||||
} catch {
|
||||
// One of the upstream sequences threw an error
|
||||
let action = self.lock.withLock {
|
||||
self.stateMachine.upstreamThrew(error)
|
||||
}
|
||||
switch action {
|
||||
case let .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation,
|
||||
error,
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(throwing: error)
|
||||
case let .cancelTaskAndUpstreamContinuations(
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
group.cancelAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// We need to inform our state machine that we started the Task
|
||||
stateMachine.taskStarted(task)
|
||||
}
|
||||
|
||||
private func iterateAsyncSequence<AsyncSequence: _Concurrency.AsyncSequence>(
|
||||
_ base: AsyncSequence,
|
||||
in taskGroup: inout ThrowingTaskGroup<Void, Error>
|
||||
) where AsyncSequence.Element == Base1.Element, AsyncSequence: Sendable {
|
||||
// For each upstream sequence we are adding a child task that
|
||||
// is consuming the upstream sequence
|
||||
taskGroup.addTask {
|
||||
var iterator = base.makeAsyncIterator()
|
||||
|
||||
// This is our upstream consumption loop
|
||||
loop: while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.lock.withLock {
|
||||
self.stateMachine.childTaskSuspended(continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case let .resumeContinuation(continuation):
|
||||
// This happens if there is outstanding demand
|
||||
// and we need to demand from upstream right away
|
||||
continuation.resume(returning: ())
|
||||
|
||||
case let .resumeContinuationWithError(continuation, error):
|
||||
// This happens if another upstream already failed or if
|
||||
// the task got cancelled.
|
||||
continuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
// We got signalled from the downstream that we have demand so let's
|
||||
// request a new element from the upstream
|
||||
if let element1 = try await iterator.next() {
|
||||
let action = self.lock.withLock {
|
||||
self.stateMachine.elementProduced(element1)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case let .resumeContinuation(continuation, element):
|
||||
// We had an outstanding demand and where the first
|
||||
// upstream to produce an element so we can forward it to
|
||||
// the downstream
|
||||
continuation.resume(returning: element)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
} else {
|
||||
// The upstream returned `nil` which indicates that it finished
|
||||
let action = self.lock.withLock {
|
||||
self.stateMachine.upstreamFinished()
|
||||
}
|
||||
|
||||
// All of this is mostly cleanup around the Task and the outstanding
|
||||
// continuations used for signalling.
|
||||
switch action {
|
||||
case let .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation,
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: nil)
|
||||
|
||||
break loop
|
||||
|
||||
case let .cancelTaskAndUpstreamContinuations(
|
||||
task,
|
||||
upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
break loop
|
||||
case .none:
|
||||
|
||||
break loop
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension RangeReplaceableCollection {
|
||||
/// Creates a new instance of a collection containing the elements of an asynchronous sequence.
|
||||
///
|
||||
/// - Parameter source: The asynchronous sequence of elements for the new collection.
|
||||
@inlinable
|
||||
public init<Source: AsyncSequence>(_ source: Source) async rethrows where Source.Element == Element {
|
||||
self.init()
|
||||
for try await item in source {
|
||||
append(item)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
// This is a hack around the fact that we don't have generic effects
|
||||
// alternatively in the use cases we would want `rethrows(unsafe)`
|
||||
// or something like that to avoid this nifty hack...
|
||||
|
||||
@rethrows
|
||||
internal protocol _ErrorMechanism {
|
||||
associatedtype Output
|
||||
func get() throws -> Output
|
||||
}
|
||||
|
||||
extension _ErrorMechanism {
|
||||
// rethrow an error only in the cases where it is known to be reachable
|
||||
internal func _rethrowError() rethrows -> Never {
|
||||
_ = try _rethrowGet()
|
||||
fatalError("materialized error without being in a throwing context")
|
||||
}
|
||||
|
||||
internal func _rethrowGet() rethrows -> Output {
|
||||
return try get()
|
||||
}
|
||||
}
|
||||
|
||||
extension Result: _ErrorMechanism { }
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
extension SetAlgebra {
|
||||
/// Creates a new set from an asynchronous sequence of items.
|
||||
///
|
||||
/// Use this initializer to create a new set from an asynchronous sequence
|
||||
///
|
||||
/// - Parameter source: The elements to use as members of the new set.
|
||||
@inlinable
|
||||
public init<Source: AsyncSequence>(_ source: Source) async rethrows where Source.Element == Element {
|
||||
self.init()
|
||||
for try await item in source {
|
||||
insert(item)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2024 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// A wrapper struct to unconditionally to transfer an non-Sendable value.
|
||||
struct UnsafeTransfer<Element>: @unchecked Sendable {
|
||||
let wrapped: Element
|
||||
|
||||
init(_ wrapped: Element) {
|
||||
self.wrapped = wrapped
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Creates an asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
|
||||
/// and emits a tuple of the values.
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(
|
||||
_ base1: Base1,
|
||||
_ base2: Base2
|
||||
) -> AsyncZip2Sequence<Base1, Base2> {
|
||||
AsyncZip2Sequence(base1, base2)
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
|
||||
/// and emits a tuple of the values.
|
||||
public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: AsyncSequence, Sendable
|
||||
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncIterator {
|
||||
Iterator(storage: .init(self.base1, self.base2, nil))
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
final class InternalClass {
|
||||
private let storage: ZipStorage<Base1, Base2, Base2>
|
||||
|
||||
fileprivate init(storage: ZipStorage<Base1, Base2, Base2>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
guard let element = try await self.storage.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
return (element.0, element.1)
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: ZipStorage<Base1, Base2, Base2>) {
|
||||
self.internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await self.internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncZip2Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,79 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// Creates an asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
|
||||
/// and emits a tuple of the values.
|
||||
public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(
|
||||
_ base1: Base1,
|
||||
_ base2: Base2,
|
||||
_ base3: Base3
|
||||
) -> AsyncZip3Sequence<Base1, Base2, Base3> {
|
||||
AsyncZip3Sequence(base1, base2, base3)
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
|
||||
/// and emits a tuple of the values.
|
||||
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: AsyncSequence, Sendable
|
||||
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable, Base3: Sendable, Base3.Element: Sendable {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
public typealias AsyncIterator = Iterator
|
||||
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
let base3: Base3
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncIterator {
|
||||
Iterator(storage: .init(self.base1, self.base2, self.base3)
|
||||
)
|
||||
}
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
final class InternalClass {
|
||||
private let storage: ZipStorage<Base1, Base2, Base3>
|
||||
|
||||
fileprivate init(storage: ZipStorage<Base1, Base2, Base3>) {
|
||||
self.storage = storage
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.storage.iteratorDeinitialized()
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
guard let element = try await self.storage.next() else {
|
||||
return nil
|
||||
}
|
||||
|
||||
// This force unwrap is safe since there must be a third element.
|
||||
return (element.0, element.1, element.2!)
|
||||
}
|
||||
}
|
||||
|
||||
let internalClass: InternalClass
|
||||
|
||||
fileprivate init(storage: ZipStorage<Base1, Base2, Base3>) {
|
||||
self.internalClass = InternalClass(storage: storage)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
try await self.internalClass.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncZip3Sequence.Iterator: Sendable { }
|
||||
@@ -0,0 +1,550 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// State machine for zip
|
||||
struct ZipStateMachine<
|
||||
Base1: AsyncSequence,
|
||||
Base2: AsyncSequence,
|
||||
Base3: AsyncSequence
|
||||
>: Sendable where
|
||||
Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base3: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
typealias DownstreamContinuation = UnsafeContinuation<Result<(
|
||||
Base1.Element,
|
||||
Base2.Element,
|
||||
Base3.Element?
|
||||
)?, Error>, Never>
|
||||
|
||||
private enum State: Sendable {
|
||||
/// Small wrapper for the state of an upstream sequence.
|
||||
struct Upstream<Element: Sendable>: Sendable {
|
||||
/// The upstream continuation.
|
||||
var continuation: UnsafeContinuation<Void, Error>?
|
||||
/// The produced upstream element.
|
||||
var element: Element?
|
||||
}
|
||||
|
||||
/// The initial state before a call to `next` happened.
|
||||
case initial(base1: Base1, base2: Base2, base3: Base3?)
|
||||
|
||||
/// The state while we are waiting for downstream demand.
|
||||
case waitingForDemand(
|
||||
task: Task<Void, Never>,
|
||||
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>)
|
||||
)
|
||||
|
||||
/// The state while we are consuming the upstream and waiting until we get a result from all upstreams.
|
||||
case zipping(
|
||||
task: Task<Void, Never>,
|
||||
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
|
||||
downstreamContinuation: DownstreamContinuation
|
||||
)
|
||||
|
||||
/// The state once one upstream sequences finished/threw or the downstream consumer stopped, i.e. by dropping all references
|
||||
/// or by getting their `Task` cancelled.
|
||||
case finished
|
||||
|
||||
/// Internal state to avoid CoW.
|
||||
case modifying
|
||||
}
|
||||
|
||||
private var state: State
|
||||
|
||||
private let numberOfUpstreamSequences: Int
|
||||
|
||||
/// Initializes a new `StateMachine`.
|
||||
init(
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?
|
||||
) {
|
||||
self.state = .initial(
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3
|
||||
)
|
||||
|
||||
if base3 == nil {
|
||||
self.numberOfUpstreamSequences = 2
|
||||
} else {
|
||||
self.numberOfUpstreamSequences = 3
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `iteratorDeinitialized()`.
|
||||
enum IteratorDeinitializedAction {
|
||||
/// Indicates that the `Task` needs to be cancelled and
|
||||
/// the upstream continuations need to be resumed with a `CancellationError`.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Nothing to do here. No demand was signalled until now
|
||||
return .none
|
||||
|
||||
case .zipping:
|
||||
// An iterator was deinitialized while we have a suspended continuation.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
|
||||
|
||||
case .waitingForDemand(let task, let upstreams):
|
||||
// The iterator was dropped which signals that the consumer is finished.
|
||||
// We can transition to finished now and need to clean everything up.
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// We are already finished so there is nothing left to clean up.
|
||||
// This is just the references dropping afterwards.
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
mutating func taskIsStarted(
|
||||
task: Task<Void, Never>,
|
||||
downstreamContinuation: DownstreamContinuation
|
||||
) {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// The user called `next` and we are starting the `Task`
|
||||
// to consume the upstream sequences
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: (.init(), .init(), .init()),
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
|
||||
case .zipping, .waitingForDemand, .finished:
|
||||
// We only allow a single task to be created so this must never happen.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `childTaskSuspended()`.
|
||||
enum ChildTaskSuspendedAction {
|
||||
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
|
||||
case resumeContinuation(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>
|
||||
)
|
||||
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
|
||||
case resumeContinuationWithError(
|
||||
upstreamContinuation: UnsafeContinuation<Void, Error>,
|
||||
error: Error
|
||||
)
|
||||
}
|
||||
|
||||
mutating func childTaskSuspended(baseIndex: Int, continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks are only created after we transitioned to `zipping`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams):
|
||||
self.state = .modifying
|
||||
|
||||
switch baseIndex {
|
||||
case 0:
|
||||
upstreams.0.continuation = continuation
|
||||
|
||||
case 1:
|
||||
upstreams.1.continuation = continuation
|
||||
|
||||
case 2:
|
||||
upstreams.2.continuation = continuation
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
|
||||
}
|
||||
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams
|
||||
)
|
||||
|
||||
return .none
|
||||
|
||||
case .zipping(let task, var upstreams, let downstreamContinuation):
|
||||
// We are currently zipping. If we have a buffered element from the base
|
||||
// already then we store the continuation otherwise we just go ahead and resume it
|
||||
switch baseIndex {
|
||||
case 0:
|
||||
if upstreams.0.element == nil {
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
} else {
|
||||
self.state = .modifying
|
||||
upstreams.0.continuation = continuation
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
return .none
|
||||
}
|
||||
|
||||
case 1:
|
||||
if upstreams.1.element == nil {
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
} else {
|
||||
self.state = .modifying
|
||||
upstreams.1.continuation = continuation
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
return .none
|
||||
}
|
||||
|
||||
case 2:
|
||||
if upstreams.2.element == nil {
|
||||
return .resumeContinuation(upstreamContinuation: continuation)
|
||||
} else {
|
||||
self.state = .modifying
|
||||
upstreams.2.continuation = continuation
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
return .none
|
||||
}
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
|
||||
}
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks are still getting
|
||||
// suspended even though we already cancelled them. We must tolerate this and just resume
|
||||
// the continuation with an error.
|
||||
return .resumeContinuationWithError(
|
||||
upstreamContinuation: continuation,
|
||||
error: CancellationError()
|
||||
)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `elementProduced()`.
|
||||
enum ElementProducedAction {
|
||||
/// Indicates that the downstream continuation should be resumed with the element.
|
||||
case resumeContinuation(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
|
||||
)
|
||||
}
|
||||
|
||||
mutating func elementProduced(_ result: (Base1.Element?, Base2.Element?, Base3.Element?)) -> ElementProducedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
// Child tasks that are producing elements are only created after we transitioned to `zipping`
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case .waitingForDemand:
|
||||
// We are only issuing demand when we get signalled by the downstream.
|
||||
// We should never receive an element when we are waiting for demand.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
|
||||
case .zipping(let task, var upstreams, let downstreamContinuation):
|
||||
self.state = .modifying
|
||||
|
||||
switch result {
|
||||
case (.some(let first), .none, .none):
|
||||
precondition(upstreams.0.element == nil)
|
||||
upstreams.0.element = first
|
||||
|
||||
case (.none, .some(let second), .none):
|
||||
precondition(upstreams.1.element == nil)
|
||||
upstreams.1.element = second
|
||||
|
||||
case (.none, .none, .some(let third)):
|
||||
precondition(upstreams.2.element == nil)
|
||||
upstreams.2.element = third
|
||||
|
||||
default:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
|
||||
}
|
||||
|
||||
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
|
||||
if let first = upstreams.0.element,
|
||||
let second = upstreams.1.element,
|
||||
let third = upstreams.2.element {
|
||||
// We got an element from each upstream so we can resume the downstream now
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: (
|
||||
.init(continuation: upstreams.0.continuation),
|
||||
.init(continuation: upstreams.1.continuation),
|
||||
.init(continuation: upstreams.2.continuation)
|
||||
)
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
result: .success((first, second, third))
|
||||
)
|
||||
|
||||
} else if let first = upstreams.0.element,
|
||||
let second = upstreams.1.element,
|
||||
self.numberOfUpstreamSequences == 2 {
|
||||
// We got an element from each upstream so we can resume the downstream now
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: (
|
||||
.init(continuation: upstreams.0.continuation),
|
||||
.init(continuation: upstreams.1.continuation),
|
||||
.init(continuation: upstreams.2.continuation)
|
||||
)
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
result: .success((first, second, nil))
|
||||
)
|
||||
} else {
|
||||
// We are still waiting for one of the upstreams to produce an element
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: (
|
||||
.init(continuation: upstreams.0.continuation, element: upstreams.0.element),
|
||||
.init(continuation: upstreams.1.continuation, element: upstreams.1.element),
|
||||
.init(continuation: upstreams.2.continuation, element: upstreams.2.element)
|
||||
),
|
||||
downstreamContinuation: downstreamContinuation
|
||||
)
|
||||
|
||||
return .none
|
||||
}
|
||||
|
||||
case .finished:
|
||||
// Since cancellation is cooperative it might be that child tasks
|
||||
// are still producing elements after we finished.
|
||||
// We are just going to drop them since there is nothing we can do
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamFinished()`.
|
||||
enum UpstreamFinishedAction {
|
||||
/// Indicates that the downstream continuation should be resumed with `nil` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamFinished() -> UpstreamFinishedAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .waitingForDemand:
|
||||
// This can't happen. We are only issuing demand for a single element each time.
|
||||
// There must never be outstanding demand to an upstream while we have no demand ourselves.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
|
||||
|
||||
case .zipping(let task, let upstreams, let downstreamContinuation):
|
||||
// One of our upstreams finished. We need to transition to finished ourselves now
|
||||
// and resume the downstream continuation with nil. Furthermore, we need to cancel all of
|
||||
// the upstream work.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `upstreamThrew()`.
|
||||
enum UpstreamThrewAction {
|
||||
/// Indicates that the downstream continuation should be resumed with the `error` and
|
||||
/// the task and the upstream continuations should be cancelled.
|
||||
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
error: Error,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .waitingForDemand:
|
||||
// This can't happen. We are only issuing demand for a single element each time.
|
||||
// There must never be outstanding demand to an upstream while we have no demand ourselves.
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
|
||||
|
||||
case .zipping(let task, let upstreams, let downstreamContinuation):
|
||||
// One of our upstreams threw. We need to transition to finished ourselves now
|
||||
// and resume the downstream continuation with the error. Furthermore, we need to cancel all of
|
||||
// the upstream work.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
error: error,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// This is just everything finishing up, nothing to do here
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `cancelled()`.
|
||||
enum CancelledAction {
|
||||
/// Indicates that the downstream continuation needs to be resumed and
|
||||
/// task and the upstream continuations should be cancelled.
|
||||
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: DownstreamContinuation,
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the task and the upstream continuations should be cancelled.
|
||||
case cancelTaskAndUpstreamContinuations(
|
||||
task: Task<Void, Never>,
|
||||
upstreamContinuations: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
}
|
||||
|
||||
mutating func cancelled() -> CancelledAction? {
|
||||
switch self.state {
|
||||
case .initial:
|
||||
state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .waitingForDemand(let task, let upstreams):
|
||||
// The downstream task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
self.state = .finished
|
||||
|
||||
return .cancelTaskAndUpstreamContinuations(
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .zipping(let task, let upstreams, let downstreamContinuation):
|
||||
// The downstream Task got cancelled so we need to cancel our upstream Task
|
||||
// and resume all continuations. We can also transition to finished.
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
downstreamContinuation: downstreamContinuation,
|
||||
task: task,
|
||||
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// We are already finished so nothing to do here:
|
||||
self.state = .finished
|
||||
|
||||
return .none
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
|
||||
/// Actions returned by `next()`.
|
||||
enum NextAction {
|
||||
/// Indicates that a new `Task` should be created that consumes the sequence.
|
||||
case startTask(Base1, Base2, Base3?)
|
||||
case resumeUpstreamContinuations(
|
||||
upstreamContinuation: [UnsafeContinuation<Void, Error>]
|
||||
)
|
||||
/// Indicates that the downstream continuation should be resumed with `nil`.
|
||||
case resumeDownstreamContinuationWithNil(DownstreamContinuation)
|
||||
}
|
||||
|
||||
mutating func next(for continuation: DownstreamContinuation) -> NextAction {
|
||||
switch self.state {
|
||||
case .initial(let base1, let base2, let base3):
|
||||
// This is the first time we get demand singalled so we have to start the task
|
||||
// The transition to the next state is done in the taskStarted method
|
||||
return .startTask(base1, base2, base3)
|
||||
|
||||
case .zipping:
|
||||
// We already got demand signalled and have suspended the downstream task
|
||||
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
|
||||
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
|
||||
|
||||
case .waitingForDemand(let task, var upstreams):
|
||||
// We got demand signalled now and can transition to zipping.
|
||||
// We also need to resume all upstream continuations now
|
||||
self.state = .modifying
|
||||
|
||||
let upstreamContinuations = [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
|
||||
upstreams.0.continuation = nil
|
||||
upstreams.1.continuation = nil
|
||||
upstreams.2.continuation = nil
|
||||
|
||||
self.state = .zipping(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
|
||||
return .resumeUpstreamContinuations(
|
||||
upstreamContinuation: upstreamContinuations
|
||||
)
|
||||
|
||||
case .finished:
|
||||
// We are already finished so we are just returning `nil`
|
||||
return .resumeDownstreamContinuationWithNil(continuation)
|
||||
|
||||
case .modifying:
|
||||
preconditionFailure("Invalid state")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,337 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
final class ZipStorage<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
|
||||
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable, Base3: Sendable, Base3.Element: Sendable {
|
||||
typealias StateMachine = ZipStateMachine<Base1, Base2, Base3>
|
||||
|
||||
private let stateMachine: ManagedCriticalState<StateMachine>
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2, _ base3: Base3?) {
|
||||
self.stateMachine = .init(.init(base1: base1, base2: base2, base3: base3))
|
||||
}
|
||||
|
||||
func iteratorDeinitialized() {
|
||||
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
|
||||
|
||||
switch action {
|
||||
case .cancelTaskAndUpstreamContinuations(
|
||||
let task,
|
||||
let upstreamContinuation
|
||||
):
|
||||
upstreamContinuation.forEach { $0.resume(throwing: CancellationError()) }
|
||||
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element?)? {
|
||||
try await withTaskCancellationHandler {
|
||||
let result = await withUnsafeContinuation { continuation in
|
||||
let action: StateMachine.NextAction? = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
let action = stateMachine.next(for: continuation)
|
||||
switch action {
|
||||
case .startTask(let base1, let base2, let base3):
|
||||
// first iteration, we start one child task per base to iterate over them
|
||||
self.startTask(
|
||||
stateMachine: &stateMachine,
|
||||
base1: base1,
|
||||
base2: base2,
|
||||
base3: base3,
|
||||
downstreamContinuation: continuation
|
||||
)
|
||||
return nil
|
||||
|
||||
case .resumeUpstreamContinuations:
|
||||
return action
|
||||
|
||||
case .resumeDownstreamContinuationWithNil:
|
||||
return action
|
||||
}
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .startTask:
|
||||
// We are handling the startTask in the lock already because we want to avoid
|
||||
// other inputs interleaving while starting the task
|
||||
fatalError("Internal inconsistency")
|
||||
|
||||
case .resumeUpstreamContinuations(let upstreamContinuations):
|
||||
// bases can be iterated over for 1 iteration so their next value can be retrieved
|
||||
upstreamContinuations.forEach { $0.resume() }
|
||||
|
||||
case .resumeDownstreamContinuationWithNil(let continuation):
|
||||
// the async sequence is already finished, immediately resuming
|
||||
continuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
return try result._rethrowGet()
|
||||
|
||||
} onCancel: {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.cancelled()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private func startTask(
|
||||
stateMachine: inout StateMachine,
|
||||
base1: Base1,
|
||||
base2: Base2,
|
||||
base3: Base3?,
|
||||
downstreamContinuation: StateMachine.DownstreamContinuation
|
||||
) {
|
||||
// This creates a new `Task` that is iterating the upstream
|
||||
// sequences. We must store it to cancel it at the right times.
|
||||
let task = Task {
|
||||
await withThrowingTaskGroup(of: Void.self) { group in
|
||||
// For each upstream sequence we are adding a child task that
|
||||
// is consuming the upstream sequence
|
||||
group.addTask {
|
||||
var base1Iterator = base1.makeAsyncIterator()
|
||||
|
||||
while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 0, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element1 = try await base1Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((element1, nil, nil))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
group.addTask {
|
||||
var base2Iterator = base2.makeAsyncIterator()
|
||||
|
||||
while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 1, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element2 = try await base2Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((nil, element2, nil))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if let base3 = base3 {
|
||||
group.addTask {
|
||||
var base3Iterator = base3.makeAsyncIterator()
|
||||
|
||||
while true {
|
||||
// We are creating a continuation before requesting the next
|
||||
// element from upstream. This continuation is only resumed
|
||||
// if the downstream consumer called `next` to signal his demand.
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.childTaskSuspended(baseIndex: 2, continuation: continuation)
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let upstreamContinuation):
|
||||
upstreamContinuation.resume()
|
||||
|
||||
case .resumeContinuationWithError(let upstreamContinuation, let error):
|
||||
upstreamContinuation.resume(throwing: error)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if let element3 = try await base3Iterator.next() {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.elementProduced((nil, nil, element3))
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuation(let downstreamContinuation, let result):
|
||||
downstreamContinuation.resume(returning: result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
} else {
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamFinished()
|
||||
}
|
||||
|
||||
switch action {
|
||||
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .success(nil))
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
while !group.isEmpty {
|
||||
do {
|
||||
try await group.next()
|
||||
} catch {
|
||||
// One of the upstream sequences threw an error
|
||||
let action = self.stateMachine.withCriticalRegion { stateMachine in
|
||||
stateMachine.upstreamThrew(error)
|
||||
}
|
||||
switch action {
|
||||
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
|
||||
let downstreamContinuation,
|
||||
let error,
|
||||
let task,
|
||||
let upstreamContinuations
|
||||
):
|
||||
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
|
||||
task.cancel()
|
||||
|
||||
downstreamContinuation.resume(returning: .failure(error))
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
group.cancelAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
stateMachine.taskIsStarted(task: task, downstreamContinuation: downstreamContinuation)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,76 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
import AsyncSequenceValidation
|
||||
|
||||
extension XCTestCase {
|
||||
func recordFailure(_ description: String, system: Bool = false, at location: AsyncSequenceValidation.SourceLocation) {
|
||||
#if canImport(Darwin)
|
||||
let context = XCTSourceCodeContext(location: XCTSourceCodeLocation(filePath: location.file.description, lineNumber: Int(location.line)))
|
||||
let issue = XCTIssue(type: system ? .system : .assertionFailure, compactDescription: description, detailedDescription: nil, sourceCodeContext: context, associatedError: nil, attachments: [])
|
||||
record(issue)
|
||||
#else
|
||||
XCTFail(description, file: location.file, line: location.line)
|
||||
#endif
|
||||
}
|
||||
|
||||
func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, expectedFailures: Set<String>, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
|
||||
var expectations = expectedFailures
|
||||
var result: AsyncSequenceValidationDiagram.ExpectationResult?
|
||||
var failures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
|
||||
let baseLoc = AsyncSequenceValidation.SourceLocation(file: file, line: line)
|
||||
var accountedFailures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
|
||||
do {
|
||||
(result, failures) = try AsyncSequenceValidationDiagram.test(theme: theme, build)
|
||||
for failure in failures {
|
||||
if expectations.remove(failure.description) == nil {
|
||||
recordFailure(failure.description, at: failure.specification?.location ?? baseLoc)
|
||||
} else {
|
||||
accountedFailures.append(failure)
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
if expectations.remove("\(error)") == nil {
|
||||
recordFailure("\(error)", system: true, at: (error as? SourceFailure)?.location ?? baseLoc)
|
||||
}
|
||||
}
|
||||
// If no failures were expected and the result reconstitues to something different
|
||||
// than what was expected, dump that out as a failure for easier diagnostics, this
|
||||
// likely should be done via attachments but that does not display inline code
|
||||
// nicely. Ideally we would want to have this display as a runtime warning but those
|
||||
// do not have source line attribution; for now XCTFail is good enough.
|
||||
if let result = result, expectedFailures.count == 0 {
|
||||
let expected = result.reconstituteExpected(theme: theme)
|
||||
let actual = result.reconstituteActual(theme: theme)
|
||||
if expected != actual {
|
||||
XCTFail("Validation failure:\nExpected:\n\(expected)\nActual:\n\(actual)", file: file, line: line)
|
||||
}
|
||||
}
|
||||
// any remaining expectations are failures that were expected but did not happen
|
||||
for expectation in expectations {
|
||||
XCTFail("Expected failure: \(expectation) did not occur.", file: file, line: line)
|
||||
}
|
||||
}
|
||||
|
||||
func validate<Test: AsyncSequenceValidationTest>(expectedFailures: Set<String>, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
|
||||
validate(theme: .ascii, expectedFailures: expectedFailures, build, file: file, line: line)
|
||||
}
|
||||
|
||||
public func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
|
||||
validate(theme: theme, expectedFailures: [], build, file: file, line: line)
|
||||
}
|
||||
|
||||
public func validate<Test: AsyncSequenceValidationTest>(@AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
|
||||
validate(theme: .ascii, expectedFailures: [], build, file: file, line: line)
|
||||
}
|
||||
}
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
# ``AsyncSequenceValidation``
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
Testing is a critical area of focus for any package to make it robust, catch bugs, and explain the expected behaviors in a documented manner. Testing things that are asynchronous can be difficult, testing things that are asynchronous multiple times can be even more difficult.
|
||||
|
||||
Types that implement `AsyncSequence` can often be described in deterministic actions given particular inputs. For the inputs, the events can be described as a discrete set: values, errors being thrown, the terminal state of returning a `nil` value from the iterator, or advancing in time and not doing anything. Likewise, the expected output has a discrete set of events: values, errors being caught, the terminal state of receiving a `nil` value from the iterator, or advancing in time and not doing anything.
|
||||
|
||||
## Topics
|
||||
|
||||
### Getting Started
|
||||
|
||||
- <doc:Validation>
|
||||
@@ -0,0 +1,343 @@
|
||||
# AsyncSequence Validation
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
* Implementation: [AsyncSequenceValidation](https://github.com/apple/swift-async-algorithms/tree/main/Sources/AsyncSequenceValidation)
|
||||
|
||||
## Introduction
|
||||
|
||||
Testing is a critical area of focus for any package to make it robust, catch bugs, and explain the expected behaviors in a documented manner. Testing things that are asynchronous can be difficult, testing things that are asynchronous multiple times can be even more difficult.
|
||||
|
||||
Types that implement `AsyncSequence` can often be described in deterministic actions given particular inputs. For the inputs, the events can be described as a discrete set: values, errors being thrown, the terminal state of returning a `nil` value from the iterator, or advancing in time and not doing anything. Likewise, the expected output has a discrete set of events: values, errors being caught, the terminal state of receiving a `nil` value from the iterator, or advancing in time and not doing anything.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
By restricting the domain space of values to `String` we can describe the events as a domain specific language, and with monospaced characters that domain space can be used to show values over time for both the input to an `AsyncSequence` but also the expected output.
|
||||
|
||||
```swift
|
||||
validate {
|
||||
"a--b--c---|"
|
||||
$0.inputs[0].map { $0.capitalized }
|
||||
"A--B--C---|"
|
||||
}
|
||||
```
|
||||
|
||||
This syntax can be accomplished with a confluence of utilizing some of the advanced features of XCTest, the concurrency runtime, and result builders. The diagram as listed flows as if each event that would propagate is an event flowing along a column but also it shows the expression progressed over time; describing each event.
|
||||
|
||||
By utilizing result builders, this same function can accommodate more than one input specification for testing things like `merge`.
|
||||
|
||||
```swift
|
||||
validate {
|
||||
"a-c--f-|"
|
||||
"-b-de-g|"
|
||||
merge($0.inputs[0], $0.inputs[1])
|
||||
"abcdefg|"
|
||||
}
|
||||
```
|
||||
|
||||
Normally testing a function like `merge` would result in either limited expectations or be stochastic in nature. Those approaches are to account for the potential ordering not being deterministic. Taking the approach of having explicit ordering of time defined by the diagram allows for the test to be predictable. That determinism is sourced directly from the input sequences and the expected correlative output sequence. In short, the syntax of the test inputs and expectations make the execution reliable.
|
||||
|
||||
The syntax is trivially parsable (and consequently customizable). By default, the events require only a limited subset of characters for control; such as the advancing in time `-`, or the termination of a sequence by returning nil `|`. However some events may produce strings greater than just one character, other events may happen at the same time, and there is also the cancellation event. This all culminates into a test theme definition of:
|
||||
|
||||
| Symbol | Description | Example |
|
||||
| ------- | ----------------- | ---------- |
|
||||
| `-` | Advance time | `"a--b--"` |
|
||||
| `\|` | Termination | `"ab-\|"` |
|
||||
| `^` | Thrown error | `"ab-^"` |
|
||||
| `;` | Cancellation | `"ab;-"` |
|
||||
| `[` | Begin group | `"[ab]-"` |
|
||||
| `]` | End group | `"[ab]-"` |
|
||||
| `'` | Begin/End Value | `"'foo'-"` |
|
||||
| `,` | Delay next | `",[a,]b"` |
|
||||
|
||||
Because some events may take up more than one character and the alignment is important to the visual progression of events, spaces are not counted as part of the parsed events. A space means that no time is advanced and not event is produced or expected. This means that the string `"a - -b- -"` is equivalent to `"a--b--"`.
|
||||
|
||||
Defining a custom theme can then be trivial, since the list of expected interactions are well known. For example an emoji based diagram can be easily constructed:
|
||||
|
||||
```swift
|
||||
struct EmojiTokens: AsyncSequenceValidationTheme {
|
||||
func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token {
|
||||
switch character {
|
||||
case "➖": return .step
|
||||
case "❗️": return .error
|
||||
case "❌": return .finish
|
||||
case "➡️": return .beginValue
|
||||
case "⬅️": return .endValue
|
||||
case "⏳": return .delayNext
|
||||
case " ": return .skip
|
||||
default: return .value(String(character))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
validate(theme: EmojiTokens()) {
|
||||
"➖🔴➖🟠➖🟡➖🟢➖❌"
|
||||
$0.inputs[0]
|
||||
"➖🔴➖🟠➖🟡➖🟢➖❌"
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The public interface for this system comes in two parts: the `AsyncSequenceValidationDiagram` subsystem and the `XCTest` extensions. The most commonly interacted-with and most approachable portion is the `XCTest` extension.
|
||||
|
||||
```swift
|
||||
extension XCTestCase {
|
||||
public func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, @AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line)
|
||||
|
||||
public func validate<Test: AsyncSequenceValidationTest>(@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line)
|
||||
}
|
||||
```
|
||||
|
||||
These two methods break down to usage like some of the previously used examples. However, the reality of how it works is perhaps the more important portion. For example, the code listed below has some points of interest worth mentioning.
|
||||
|
||||
```swift
|
||||
validate {
|
||||
"a--b--c---|"
|
||||
$0.inputs[0].map { item in await Task { item.capitalized }.value }
|
||||
"A--B--C---|"
|
||||
}
|
||||
```
|
||||
|
||||
The progression of the input sequence can be derived from the `$0.inputs[0]`. This is an `AsyncSequence` with the `Element` type of `String` which at the given input emits an `"a"` at tick 0, a `"b"` at tick 3, a `"c"` at tick 6 and a finish event at tick 10. The output of the middle expression `$0.inputs[0].map { item in await Task { item.capitalized }.value }` is expected to emit an `"A"` at tick 0, a `"B"` at tick 3, a `"C"` at tick 6 and a finish event at tick 10.
|
||||
|
||||
Careful readers may immediately recognize that the `map` function is asynchronous and schedules work on a separate task. Normally, this would pose a distinct hazard to deterministic testing for timing of events. However, the `validate` utilizes a specialized hook into the Swift concurrency runtime to schedule the events stepwise and deterministically. This works in a two-fold manner: first, it uses a custom `Clock` to schedule events. Second, it ties that clock into a task driver that ensures enqueued jobs are executed in lockstep with that clock.
|
||||
|
||||
The underpinnings to make that work are the actual `AsyncSequenceValidationDiagram` subsystem. The `XCTest` interface does offer a considerably more simple surface area so the diagrams will be broken down into a few key sections for approachability. Those sections are the result builder, the diagram clock, the inputs, themes, and expectations/tests.
|
||||
|
||||
### Result Builder
|
||||
|
||||
The result builder syntax allows for simple and concise diagrams to be built. Those diagrams can come in a few forms, ranging from no inputs to three inputs. It is worth noting the implementation is not limited to just three inputs and can easily be expanded to more as we deem it needed. The builder itself uses the multiple parameter build block functions to ensure the proper ordering of inputs, tested sequences, and outputs.
|
||||
|
||||
```swift
|
||||
@resultBuilder
|
||||
public struct AsyncSequenceValidationDiagram : Sendable {
|
||||
public static func buildBlock<Operation: AsyncSequence>(
|
||||
_ sequence: Operation,
|
||||
_ output: String
|
||||
) -> some AsyncSequenceValidationTest where Operation.Element == String
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(
|
||||
_ input: String,
|
||||
_ sequence: Operation,
|
||||
_ output: String
|
||||
) -> some AsyncSequenceValidationTest where Operation.Element == String
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(
|
||||
_ input1: String,
|
||||
_ input2: String,
|
||||
_ sequence: Operation,
|
||||
_ output: String
|
||||
) -> some AsyncSequenceValidationTest where Operation.Element == String
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(
|
||||
_ input1: String,
|
||||
_ input2: String,
|
||||
_ input3: String,
|
||||
_ sequence: Operation,
|
||||
_ output: String
|
||||
) -> some AsyncSequenceValidationTest where Operation.Element == String
|
||||
|
||||
public var inputs: InputList { get }
|
||||
public var clock: Clock { get }
|
||||
}
|
||||
```
|
||||
|
||||
The `AsyncSequenceValidationTest`, `InputList`, and `Clock` will be covered in subsequent sections.
|
||||
|
||||
### Validation Diagram Clock
|
||||
|
||||
One of the key functionalities of the validation diagrams is being able to control time. For proper usage of this testing infrastructure, all clock sources must be tied to the `AsyncSequenceValidationDiagram.Clock` that is exposed on the diagram itself. This is the heartbeat of how each columnar input and expectation are produced and consumed. It measures time in an integral manner of `steps`. One step is advanced per event symbol; in the default ASCII diagrams that means:
|
||||
|
||||
* `-`, `;`, `|`, `^`, and any character value event.
|
||||
* Quoted values like `"'foo'"`.
|
||||
* Grouped events like `"[ab]"`.
|
||||
|
||||
```swift
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public struct Clock { }
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationDiagram.Clock: Clock {
|
||||
public struct Step: DurationProtocol, Hashable, CustomStringConvertible {
|
||||
public static func + (lhs: Step, rhs: Step) -> Step
|
||||
public static func - (lhs: Step, rhs: Step) -> Step
|
||||
public static func / (lhs: Step, rhs: Int) -> Step
|
||||
public static func * (lhs: Step, rhs: Int) -> Step
|
||||
public static func / (lhs: Step, rhs: Step) -> Double
|
||||
public static func < (lhs: Step, rhs: Step) -> Bool
|
||||
|
||||
public static var zero: Step
|
||||
|
||||
public static func steps(_ amount: Int) -> Step
|
||||
}
|
||||
|
||||
public struct Instant: InstantProtocol, CustomStringConvertible {
|
||||
public func advanced(by duration: Step) -> Instant
|
||||
|
||||
public func duration(to other: Instant) -> Step
|
||||
}
|
||||
|
||||
public var now: Instant { get }
|
||||
public var minimumResolution: Step { get }
|
||||
|
||||
public func sleep(
|
||||
until deadline: Instant,
|
||||
tolerance: Step? = nil
|
||||
) async throws
|
||||
}
|
||||
```
|
||||
|
||||
Key notes: the `minimumResolution` of the `AsyncSequenceValidationDiagram.Clock` is fixed at `.steps(1)`, and the tolerance to the `sleep` function is ignored. These two behaviors were chosen because there is no sub-step granularity besides the order of execution and any coalescing due to tolerance would detract from the explicit expectations of deterministic execution order.
|
||||
|
||||
### Inputs
|
||||
|
||||
The inputs to the validation diagram are lazily constructed with the input parameters built by the result builder syntax. The inputs are `Sendable` and `AsyncSequence` conforming types that have their `Element` defined as `String`. The elements are produced as defined by the input specification in the result builder. This means that on each tick that an element is defined, the `next` function will resume to return that element (or return `nil` or throw an error, depending on the input specification). The `InputList` grants access to the defined inputs lazily.
|
||||
|
||||
```swift
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public struct Input: AsyncSequence, Sendable {
|
||||
public typealias Element = String
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
public mutating func next() async throws -> String?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
|
||||
public struct InputList: RandomAccessCollection, Sendable {
|
||||
public typealias Element = Input
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Access to the validation diagram input list is done through calls such as `$0.inputs[0]` seen in other examples. This access fetches lazily the first input specification and creates an `Input` `AsyncSequence` out of that domain specific language symbology.
|
||||
|
||||
### Themes
|
||||
|
||||
| Symbol | Token | Description | Example |
|
||||
| ------- | ------------------------- | ----------------- | ---------- |
|
||||
| `-` | `.step` | Advance time | `"a--b--"` |
|
||||
| `\|` | `.finish` | Termination | `"ab-\|"` |
|
||||
| `^` | `.error` | Thrown error | `"ab-^"` |
|
||||
| `;` | `.cancel` | Cancellation | `"ab;-"` |
|
||||
| `[` | `.beginGroup` | Begin group | `"[ab]-"` |
|
||||
| `]` | `.endGroup` | End group | `"[ab]-"` |
|
||||
| `'` | `.beginValue` `.endValue` | Begin/End Value | `"'foo'-"` |
|
||||
| `,` | `.delayNext` | Delay next | `",[a,]b"` |
|
||||
| ` ` | `.skip` | Skip/Ignore | `"a b- \|"` |
|
||||
| | `.value` | Values. | `"ab-\|"` |
|
||||
|
||||
There are some diagram input specifications that are not valid. The three cases are:
|
||||
|
||||
* A step being specified in a group (`"[a-]b|"`).
|
||||
* A nested group (`"[[ab]]|"`).
|
||||
* An unbalanced nesting (`"[ab|"`).
|
||||
|
||||
```swift
|
||||
public protocol AsyncSequenceValidationTheme {
|
||||
func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationTheme where Self == AsyncSequenceValidationDiagram.ASCIITheme {
|
||||
public static var ascii: AsyncSequenceValidationDiagram.ASCIITheme
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public enum Token {
|
||||
case step
|
||||
case error
|
||||
case finish
|
||||
case cancel
|
||||
case delayNext
|
||||
case beginValue
|
||||
case endValue
|
||||
case beginGroup
|
||||
case endGroup
|
||||
case skip
|
||||
case value(String)
|
||||
}
|
||||
|
||||
public struct ASCIITheme: AsyncSequenceValidationTheme {
|
||||
public func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Expectations and Tests
|
||||
|
||||
This set of interfaces are the primary mechanism in which the simplified XCTest extension rests upon.
|
||||
|
||||
Expectations defined by the domain specific language symbology can be roughly expressed as expected results and actual results. This notably avoids cancellation and steps, since those are better expressed through the failure reporting system. The expectation failures can express the combination of these expected and actual values. This can also show when the expectation failure occurred and the kind of expectation failure that happened, along with the payload of the actual and expected values.
|
||||
|
||||
```swift
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public struct ExpectationResult {
|
||||
public var expected: [(Clock.Instant, Result<String?, Error>)]
|
||||
public var actual: [(Clock.Instant, Result<String?, Error>)]
|
||||
}
|
||||
|
||||
public struct ExpectationFailure: CustomStringConvertible {
|
||||
public enum Kind {
|
||||
case expectedFinishButGotValue(String)
|
||||
case expectedMismatch(String, String)
|
||||
case expectedValueButGotFinished(String)
|
||||
case expectedFailureButGotValue(Error, String)
|
||||
case expectedFailureButGotFinish(Error)
|
||||
case expectedValueButGotFailure(String, Error)
|
||||
case expectedFinishButGotFailure(Error)
|
||||
case expectedValue(String)
|
||||
case expectedFinish
|
||||
case expectedFailure(Error)
|
||||
case unexpectedValue(String)
|
||||
case unexpectedFinish
|
||||
case unexpectedFailure(Error)
|
||||
}
|
||||
|
||||
public var when: Clock.Instant
|
||||
public var kind: Kind
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The testing itself reduces down to two methods, one being a default theme parameter of `.ascii`. The test methods execute the validation diagram using a custom scheduling hook from the concurrency runtime such that all events are sequentially processed on a single cooperatively-multitasking executed thread. That thread is responsible for ensuring the ordering of the events and the execution of each time delineation such that the order of emissions of any input events are sequential top to bottom: input 0 is emitted first, then input 1, etc. After the ordering of input events, the jobs enqueued onto that task driver thread are executed in order of receipt. This ensures the overall order of execution is stable and deterministic but, most importantly, predictable.
|
||||
|
||||
```swift
|
||||
public protocol AsyncSequenceValidationTest: Sendable {
|
||||
var inputs: [String] { get }
|
||||
var output: String { get }
|
||||
|
||||
func test(_ event: (String) -> Void) async throws
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public static func test<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(
|
||||
theme: Theme,
|
||||
@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test
|
||||
) throws -> (ExpectationResult, [ExpectationFailure])
|
||||
|
||||
public static func test<Test: AsyncSequenceValidationTest>(
|
||||
@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test
|
||||
) throws -> (ExpectationResult, [ExpectationFailure])
|
||||
}
|
||||
```
|
||||
|
||||
## Future Directions/Improvements
|
||||
|
||||
The emoji diagram theme could be made to be a built-in system. It makes for really flashy slides/demos and makes it really easy to see what is going on, but at the cost of being slightly harder to type.
|
||||
|
||||
The testing infrastructure could support (with minor alteration) testing iteration beyond the terminal cases, either errors being thrown from the iterator or past the first `nil` return value from `next`. This could help enforce some of the semantical expectations of `AsyncSequence`.
|
||||
|
||||
In addition to hooking into the runtime for execution of jobs, the deferred execution of jobs could also be hooked so that a time scale conversion could be made such that any sleep using any clock could map directly to the validation diagram internal clock ticks.
|
||||
|
||||
The testing infrastructure could also have support for testing for values that do not have specified order for a given tick. Some race conditions from external systems not under the control of the concurrency runtime may not be accountable. If that were to be a consideration, unordered group tokens could be added. For example the symbols `{` and `}` could be used to represent a group that is unordered. However, since there are not any cases where this really seems useful for the swift-async-algorithms package, this is not a priority at this time.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
The validation diagram system could be retrofitted to accommodate other value types other than strings, however most use cases can easily be expressed in a readable form with minor adjustments to use strings.
|
||||
|
||||
The builder functions could pass in N-ary variants of the diagram to enforce the inputs to be specific instead of accessed via the lazy `InputList`. As we may potentially add additional numbers of inputs in the future this seems like a less maintainable implementation even though it may offer slightly more safety and only marginally better spelling, i.e., `$0.inputs[0]` versus `$0.input0` etc.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
Some of the major sources of inspiration for the validation diagram system were https://rxjs.dev/guide/testing/marble-testing and the graphical representations from https://rxmarbles.com. Both of these were immensely useful to help discuss the expected behaviors of how asynchronous sequences should behave.
|
||||
@@ -0,0 +1,115 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 _CAsyncSequenceValidationSupport
|
||||
|
||||
@resultBuilder
|
||||
public struct AsyncSequenceValidationDiagram : Sendable {
|
||||
public struct Component<T> {
|
||||
var component: T
|
||||
var location: SourceLocation
|
||||
}
|
||||
|
||||
public struct AccumulatedInputs {
|
||||
var inputs: [Specification] = []
|
||||
}
|
||||
|
||||
public struct AccumulatedInputsWithOperation<Operation: AsyncSequence> where Operation.Element == String {
|
||||
var inputs: [Specification]
|
||||
var operation: Operation
|
||||
}
|
||||
|
||||
public static func buildExpression(_ expr: String, file: StaticString = #file, line: UInt = #line) -> Component<String> {
|
||||
Component(component: expr, location: SourceLocation(file: file, line: line))
|
||||
}
|
||||
|
||||
public static func buildExpression<S: AsyncSequence>(_ expr: S, file: StaticString = #file, line: UInt = #line) -> Component<S> {
|
||||
Component(component: expr, location: SourceLocation(file: file, line: line))
|
||||
}
|
||||
|
||||
public static func buildPartialBlock(first input: Component<String>) -> AccumulatedInputs {
|
||||
return AccumulatedInputs(inputs: [Specification(specification: input.component, location: input.location)])
|
||||
}
|
||||
|
||||
public static func buildPartialBlock<Operation: AsyncSequence>(first operation: Component<Operation>) -> AccumulatedInputsWithOperation<Operation> where Operation.Element == String {
|
||||
return AccumulatedInputsWithOperation(inputs: [], operation: operation.component)
|
||||
}
|
||||
|
||||
public static func buildPartialBlock(accumulated: AccumulatedInputs, next input: Component<String>) -> AccumulatedInputs {
|
||||
return AccumulatedInputs(inputs: accumulated.inputs + [Specification(specification: input.component, location: input.location)])
|
||||
}
|
||||
|
||||
public static func buildPartialBlock<Operation: AsyncSequence>(accumulated: AccumulatedInputs, next operation: Component<Operation>) -> AccumulatedInputsWithOperation<Operation> {
|
||||
return AccumulatedInputsWithOperation(inputs: accumulated.inputs, operation: operation.component)
|
||||
}
|
||||
|
||||
public static func buildPartialBlock<Operation: AsyncSequence>(accumulated: AccumulatedInputsWithOperation<Operation>, next output: Component<String>) -> some AsyncSequenceValidationTest {
|
||||
return Test(inputs: accumulated.inputs, sequence: accumulated.operation, output: Specification(specification: output.component, location: output.location))
|
||||
}
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(_ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
|
||||
let part1 = buildPartialBlock(first: sequence)
|
||||
let part2 = buildPartialBlock(accumulated: part1, next: output)
|
||||
return part2
|
||||
}
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
|
||||
let part1 = buildPartialBlock(first: input1)
|
||||
let part2 = buildPartialBlock(accumulated: part1, next: sequence)
|
||||
let part3 = buildPartialBlock(accumulated: part2, next: output)
|
||||
return part3
|
||||
}
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
|
||||
let part1 = buildPartialBlock(first: input1)
|
||||
let part2 = buildPartialBlock(accumulated: part1, next: input2)
|
||||
let part3 = buildPartialBlock(accumulated: part2, next: sequence)
|
||||
let part4 = buildPartialBlock(accumulated: part3, next: output)
|
||||
return part4
|
||||
}
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ input3: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
|
||||
let part1 = buildPartialBlock(first: input1)
|
||||
let part2 = buildPartialBlock(accumulated: part1, next: input2)
|
||||
let part3 = buildPartialBlock(accumulated: part2, next: input3)
|
||||
let part4 = buildPartialBlock(accumulated: part3, next: sequence)
|
||||
let part5 = buildPartialBlock(accumulated: part4, next: output)
|
||||
return part5
|
||||
}
|
||||
|
||||
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ input3: Component<String>, _ input4: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
|
||||
let part1 = buildPartialBlock(first: input1)
|
||||
let part2 = buildPartialBlock(accumulated: part1, next: input2)
|
||||
let part3 = buildPartialBlock(accumulated: part2, next: input3)
|
||||
let part4 = buildPartialBlock(accumulated: part3, next: input3)
|
||||
let part5 = buildPartialBlock(accumulated: part4, next: sequence)
|
||||
let part6 = buildPartialBlock(accumulated: part5, next: output)
|
||||
return part6
|
||||
}
|
||||
|
||||
let queue: WorkQueue
|
||||
let _clock: Clock
|
||||
|
||||
public var inputs: InputList
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
public var clock: Clock {
|
||||
_clock
|
||||
}
|
||||
|
||||
internal init() {
|
||||
let queue = WorkQueue()
|
||||
self.queue = queue
|
||||
self.inputs = InputList(queue: queue)
|
||||
self._clock = Clock(queue: queue)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 AsyncAlgorithms
|
||||
|
||||
extension AsyncSequenceValidationDiagram {
|
||||
public struct Clock {
|
||||
let queue: WorkQueue
|
||||
|
||||
init(queue: WorkQueue) {
|
||||
self.queue = queue
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
public protocol TestClock: Sendable {
|
||||
associatedtype Instant: TestInstant
|
||||
|
||||
var now: Instant { get }
|
||||
|
||||
func sleep(until deadline: Self.Instant, tolerance: Self.Instant.Duration?) async throws
|
||||
}
|
||||
|
||||
public protocol TestInstant: Equatable {
|
||||
associatedtype Duration
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationDiagram.Clock {
|
||||
public struct Step: DurationProtocol, Hashable, CustomStringConvertible {
|
||||
internal var rawValue: Int
|
||||
|
||||
internal init(_ rawValue: Int) {
|
||||
self.rawValue = rawValue
|
||||
}
|
||||
|
||||
public static func + (lhs: Step, rhs: Step) -> Step {
|
||||
return .init(lhs.rawValue + rhs.rawValue)
|
||||
}
|
||||
|
||||
public static func - (lhs: Step, rhs: Step) -> Step {
|
||||
.init(lhs.rawValue - rhs.rawValue)
|
||||
}
|
||||
|
||||
public static func / (lhs: Step, rhs: Int) -> Step {
|
||||
.init(lhs.rawValue / rhs)
|
||||
}
|
||||
|
||||
public static func * (lhs: Step, rhs: Int) -> Step {
|
||||
.init(lhs.rawValue * rhs)
|
||||
}
|
||||
|
||||
public static func / (lhs: Step, rhs: Step) -> Double {
|
||||
Double(lhs.rawValue) / Double(rhs.rawValue)
|
||||
}
|
||||
|
||||
public static func < (lhs: Step, rhs: Step) -> Bool {
|
||||
lhs.rawValue < rhs.rawValue
|
||||
}
|
||||
|
||||
public static var zero: Step { .init(0) }
|
||||
|
||||
public static func steps(_ amount: Int) -> Step {
|
||||
return Step(amount)
|
||||
}
|
||||
|
||||
public var description: String {
|
||||
return "step \(rawValue)"
|
||||
}
|
||||
}
|
||||
|
||||
public struct Instant: CustomStringConvertible {
|
||||
public typealias Duration = Step
|
||||
|
||||
let when: Step
|
||||
|
||||
public func advanced(by duration: Step) -> Instant {
|
||||
Instant(when: when + duration)
|
||||
}
|
||||
|
||||
public func duration(to other: Instant) -> Step {
|
||||
other.when - when
|
||||
}
|
||||
|
||||
public static func < (lhs: Instant, rhs: Instant) -> Bool {
|
||||
lhs.when < rhs.when
|
||||
}
|
||||
|
||||
public var description: String {
|
||||
// the raw value is 1 indexed in execution but we should report it as 0 indexed
|
||||
return "tick \(when.rawValue - 1)"
|
||||
}
|
||||
}
|
||||
|
||||
public var now: Instant {
|
||||
queue.now
|
||||
}
|
||||
|
||||
public var minimumResolution: Step {
|
||||
.steps(1)
|
||||
}
|
||||
|
||||
public func sleep(
|
||||
until deadline: Instant,
|
||||
tolerance: Step? = nil
|
||||
) async throws {
|
||||
let token = queue.prepare()
|
||||
try await withTaskCancellationHandler {
|
||||
try await withUnsafeThrowingContinuation { continuation in
|
||||
queue.enqueue(AsyncSequenceValidationDiagram.Context.currentJob, deadline: deadline, continuation: continuation, token: token)
|
||||
}
|
||||
} onCancel: {
|
||||
queue.cancel(token)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncSequenceValidationDiagram.Clock.Instant: TestInstant { }
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncSequenceValidationDiagram.Clock.Instant: InstantProtocol { }
|
||||
|
||||
extension AsyncSequenceValidationDiagram.Clock: TestClock { }
|
||||
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncSequenceValidationDiagram.Clock: Clock { }
|
||||
|
||||
// placeholders to avoid warnings
|
||||
extension AsyncSequenceValidationDiagram.Clock.Instant: Hashable { }
|
||||
extension AsyncSequenceValidationDiagram.Clock.Instant: Comparable { }
|
||||
Loaded 100 of 154 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user