mirror of
https://github.com/apple/swift-async-algorithms
synced 2026-11-22 04:10:40 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
088f92a30c | ||
|
|
74a48bddc6 | ||
|
|
ba5872bfcb | ||
|
|
cbde9aed74 | ||
|
|
d9c26817af | ||
|
|
822cfb8331 | ||
|
|
13713a4ffd | ||
|
|
789dcf1f3d | ||
|
|
11645b8feb | ||
|
|
a5195afbd5 | ||
|
|
46b3cc3a4e | ||
|
|
3da39bbc4e | ||
|
|
c8a9349238 | ||
|
|
e81438119c | ||
|
|
8ee3d2be19 | ||
|
|
8e16632775 | ||
|
|
f4177dcc17 | ||
|
|
268087d1de | ||
|
|
3bd2de010e | ||
|
|
b2beeb25b4 | ||
|
|
d0b4a06d0f | ||
|
|
6a92272e13 | ||
|
|
6783e0f2d2 | ||
|
|
d14a83b31f | ||
|
|
0a5f92d159 | ||
|
|
be2467e0c0 | ||
|
|
9d349bcc32 | ||
|
|
5043186441 | ||
|
|
2971dd5d9f | ||
|
|
103f5e5bea | ||
|
|
b8006a9de0 | ||
|
|
2de50036f6 | ||
|
|
ba540240d3 | ||
|
|
65ed06871b | ||
|
|
d98a48b8c2 | ||
|
|
6c050d5ef8 | ||
|
|
2773d41253 | ||
|
|
4686d2edd3 | ||
|
|
24bd5acc81 | ||
|
|
26111a6fb7 | ||
|
|
daf3c0d723 | ||
|
|
70c36ce9a1 | ||
|
|
ca38935fc0 | ||
|
|
18e2398481 | ||
|
|
c537393339 | ||
|
|
6dcb3acddd | ||
|
|
3997ce3255 | ||
|
|
042e1c4d9d | ||
|
|
57b0814edf | ||
|
|
9fcf11df15 | ||
|
|
08bb1bb014 | ||
|
|
5878737018 | ||
|
|
552856a85c | ||
|
|
ba30f2051b | ||
|
|
d5b49aab17 | ||
|
|
ba33a225e9 | ||
|
|
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 |
No files matched your search
@@ -0,0 +1,8 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
trim_trailing_whitespace = true
|
||||
@@ -0,0 +1,26 @@
|
||||
name: Pull request
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, reopened, synchronize]
|
||||
|
||||
jobs:
|
||||
tests:
|
||||
name: Test
|
||||
uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
|
||||
with:
|
||||
linux_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}, {\"swift_version\": \"5.10\"}]]"
|
||||
windows_exclude_swift_versions: "[{\"swift_version\": \"5.9\"}]"
|
||||
enable_wasm_sdk_build: true
|
||||
swift_flags: "--enable-all-traits"
|
||||
swift_nightly_flags: "--enable-all-traits"
|
||||
|
||||
soundness:
|
||||
name: Soundness
|
||||
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
|
||||
with:
|
||||
license_header_check_project_name: "Swift Async Algorithms"
|
||||
format_check_container_image: "swiftlang/swift:nightly-main-noble" # Needed due to https://github.com/swiftlang/swift-format/issues/1081
|
||||
+3
-1
@@ -8,4 +8,6 @@ DerivedData/
|
||||
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
|
||||
.netrc
|
||||
.swiftpm
|
||||
Package.resolved
|
||||
Package.resolved
|
||||
.swift-version
|
||||
test_output.log
|
||||
@@ -0,0 +1,10 @@
|
||||
@@===----------------------------------------------------------------------===@@
|
||||
@@
|
||||
@@ This source file is part of the Swift Async Algorithms open source project
|
||||
@@
|
||||
@@ Copyright (c) YEARS 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
|
||||
@@
|
||||
@@===----------------------------------------------------------------------===@@
|
||||
@@ -0,0 +1,40 @@
|
||||
.gitignore
|
||||
**/.gitignore
|
||||
.licenseignore
|
||||
.gitattributes
|
||||
.mailfilter
|
||||
.mailmap
|
||||
.spi.yml
|
||||
.swift-format
|
||||
.editorconfig
|
||||
.github/*
|
||||
*.md
|
||||
*.txt
|
||||
*.yml
|
||||
*.yaml
|
||||
*.json
|
||||
Package.swift
|
||||
**/Package.swift
|
||||
Package@-*.swift
|
||||
Package@swift-*.swift
|
||||
**/Package@-*.swift
|
||||
Package.resolved
|
||||
**/Package.resolved
|
||||
Makefile
|
||||
*.modulemap
|
||||
**/*.modulemap
|
||||
**/*.docc/*
|
||||
*.xcprivacy
|
||||
**/*.xcprivacy
|
||||
*.symlink
|
||||
**/*.symlink
|
||||
Dockerfile
|
||||
**/Dockerfile
|
||||
Snippets/*
|
||||
dev/git.commit.template
|
||||
*.crt
|
||||
**/*.crt
|
||||
*.pem
|
||||
**/*.pem
|
||||
*.der
|
||||
**/*.der
|
||||
@@ -0,0 +1,4 @@
|
||||
version: 1
|
||||
builder:
|
||||
configs:
|
||||
- documentation_targets: [AsyncAlgorithms]
|
||||
@@ -0,0 +1,58 @@
|
||||
{
|
||||
"fileScopedDeclarationPrivacy" : {
|
||||
"accessLevel" : "private"
|
||||
},
|
||||
"indentation" : {
|
||||
"spaces" : 2
|
||||
},
|
||||
"indentConditionalCompilationBlocks" : false,
|
||||
"indentSwitchCaseLabels" : false,
|
||||
"lineBreakAroundMultilineExpressionChainComponents" : false,
|
||||
"lineBreakBeforeControlFlowKeywords" : false,
|
||||
"lineBreakBeforeEachArgument" : true,
|
||||
"lineBreakBeforeEachGenericRequirement" : true,
|
||||
"lineLength" : 120,
|
||||
"maximumBlankLines" : 1,
|
||||
"prioritizeKeepingFunctionOutputTogether" : true,
|
||||
"respectsExistingLineBreaks" : true,
|
||||
"rules" : {
|
||||
"AllPublicDeclarationsHaveDocumentation" : false,
|
||||
"AlwaysUseLowerCamelCase" : false,
|
||||
"AmbiguousTrailingClosureOverload" : true,
|
||||
"BeginDocumentationCommentWithOneLineSummary" : false,
|
||||
"DoNotUseSemicolons" : true,
|
||||
"DontRepeatTypeInStaticProperties" : true,
|
||||
"FileScopedDeclarationPrivacy" : true,
|
||||
"FullyIndirectEnum" : true,
|
||||
"GroupNumericLiterals" : true,
|
||||
"IdentifiersMustBeASCII" : true,
|
||||
"NeverForceUnwrap" : false,
|
||||
"NeverUseForceTry" : false,
|
||||
"NeverUseImplicitlyUnwrappedOptionals" : false,
|
||||
"NoAccessLevelOnExtensionDeclaration" : true,
|
||||
"NoAssignmentInExpressions" : true,
|
||||
"NoBlockComments" : true,
|
||||
"NoCasesWithOnlyFallthrough" : true,
|
||||
"NoEmptyTrailingClosureParentheses" : true,
|
||||
"NoLabelsInCasePatterns" : false,
|
||||
"NoLeadingUnderscores" : false,
|
||||
"NoParensAroundConditions" : true,
|
||||
"NoVoidReturnOnFunctionSignature" : true,
|
||||
"OneCasePerLine" : true,
|
||||
"OneVariableDeclarationPerLine" : true,
|
||||
"OnlyOneTrailingClosureArgument" : true,
|
||||
"OrderedImports" : false,
|
||||
"ReturnVoidInsteadOfEmptyTuple" : true,
|
||||
"UseEarlyExits" : true,
|
||||
"UseLetInEveryBoundCaseVariable" : false,
|
||||
"UseShorthandTypeNames" : true,
|
||||
"UseSingleLinePropertyGetter" : false,
|
||||
"UseSynthesizedInitializer" : false,
|
||||
"UseTripleSlashForDocumentationComments" : true,
|
||||
"UseWhereClausesInForLoops" : false,
|
||||
"ValidateDocumentationComments" : false
|
||||
},
|
||||
"spacesAroundRangeFormationOperators" : false,
|
||||
"tabWidth" : 4,
|
||||
"version" : 1
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
extends: default
|
||||
|
||||
rules:
|
||||
line-length: false
|
||||
document-start: false
|
||||
truthy:
|
||||
check-keys: false # Otherwise we get a false positive on GitHub action's `on` key
|
||||
+2
-52
@@ -1,55 +1,5 @@
|
||||
# Code of Conduct
|
||||
To be a truly great community, Swift.org needs to welcome developers from all walks of life,
|
||||
with different backgrounds, and with a wide range of experience. A diverse and friendly
|
||||
community will have more great ideas, more unique perspectives, and produce more great
|
||||
code. We will work diligently to make the Swift community welcoming to everyone.
|
||||
|
||||
To give clarity of what is expected of our members, Swift.org has adopted the code of conduct
|
||||
defined by [contributor-covenant.org](https://www.contributor-covenant.org). This document is used across many open source
|
||||
communities, and we think it articulates our values well. The full text is copied below:
|
||||
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
|
||||
|
||||
### Contributor Code of Conduct v1.3
|
||||
As contributors and maintainers of this project, and in the interest of fostering an open and
|
||||
welcoming community, we pledge to respect all people who contribute through reporting
|
||||
issues, posting feature requests, updating documentation, submitting pull requests or patches,
|
||||
and other activities.
|
||||
|
||||
We are committed to making participation in this project a harassment-free experience for
|
||||
everyone, regardless of level of experience, gender, gender identity and expression, sexual
|
||||
orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or
|
||||
nationality.
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
- The use of sexualized language or imagery
|
||||
- Personal attacks
|
||||
- Trolling or insulting/derogatory comments
|
||||
- Public or private harassment
|
||||
- Publishing other’s private information, such as physical or electronic addresses, without explicit permission
|
||||
- Other unethical or unprofessional conduct
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments,
|
||||
commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of
|
||||
Conduct, or to ban temporarily or permanently any contributor for other behaviors that they
|
||||
deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
By adopting this Code of Conduct, project maintainers commit themselves to fairly and
|
||||
consistently applying these principles to every aspect of managing this project. Project
|
||||
maintainers who do not follow or enforce the Code of Conduct may be permanently removed
|
||||
from the project team.
|
||||
|
||||
This code of conduct applies both within project spaces and in public spaces when an
|
||||
individual is representing the project or its community.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by
|
||||
contacting a project maintainer at [conduct@swift.org](mailto:conduct@swift.org). All complaints will be reviewed and
|
||||
investigated and will result in a response that is deemed necessary and appropriate to the
|
||||
circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter
|
||||
of an incident.
|
||||
|
||||
*This policy is adapted from the Contributor Code of Conduct [version 1.3.0](http://contributor-covenant.org/version/1/3/0/).*
|
||||
|
||||
### Reporting
|
||||
A working group of community members is committed to promptly addressing any [reported
|
||||
issues](mailto:conduct@swift.org). Working group members are volunteers appointed by the project lead, with a
|
||||
preference for individuals with varied backgrounds and perspectives. Membership is expected
|
||||
to change regularly, and may grow or shrink.
|
||||
<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
|
||||
@@ -51,7 +51,7 @@ 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)
|
||||
document](https://github.com/apple/swift/blob/main/docs/LibraryEvolution.rst)
|
||||
in the Swift repository.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -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/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/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/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.
|
||||
|
||||
## 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-0013](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0013-chunk.md)
|
||||
* Author(s): [Kevin Perry](https://github.com/kperryua), [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [
|
||||
[By group](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedByGroupSequence.swift),
|
||||
[On projection](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
|
||||
[Count and signal](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountOrSignalSequence.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-0014](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0014-rate-limits.md)
|
||||
* Authors: [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation:
|
||||
[
|
||||
[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)
|
||||
]
|
||||
[
|
||||
[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-0015](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0015-reductions.md)
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncExclusiveReductionsSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestReductions.swift)
|
||||
]
|
||||
* 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)
|
||||
@@ -0,0 +1,838 @@
|
||||
# MultiProducerSingleConsumerAsyncChannel
|
||||
|
||||
* Proposal: [SAA-0016](0016-multi-producer-single-consumer-channel.md)
|
||||
* Authors: [Franz Busch](https://github.com/FranzBusch)
|
||||
* Status: **Implemented**
|
||||
|
||||
## Revision
|
||||
- 2023/12/18: Migrate proposal from Swift Evolution to Swift Async Algorithms.
|
||||
- 2023/12/19: Add element size dependent strategy
|
||||
- 2024/05/19: Rename to multi producer single consumer channel
|
||||
- 2024/05/28: Add unbounded strategy
|
||||
- 2025/03/24: Adopt `~Copyable` for correct semantics and better performance.
|
||||
|
||||
## Introduction
|
||||
|
||||
[SE-0314](https://github.com/apple/swift-evolution/blob/main/proposals/0314-async-stream.md)
|
||||
introduced new `Async[Throwing]Stream` types which act as root asynchronous
|
||||
sequences. These two types allow bridging from synchronous callbacks such as
|
||||
delegates to an asynchronous sequence. This proposal adds a new root primitive
|
||||
with the goal of modeling asynchronous multi-producer-single-consumer systems.
|
||||
|
||||
## Motivation
|
||||
|
||||
After using the `AsyncSequence` protocol, the `Async[Throwing]Stream` types, and
|
||||
the `Async[Throwing]Channel` types extensively over the past years, we learned
|
||||
that there is a gap in the ecosystem for a type that provides strict
|
||||
multi-producer-single-consumer guarantees with external backpressure support.
|
||||
Additionally, any stream/channel like type needs to have a clear definition
|
||||
about the following behaviors:
|
||||
|
||||
1. Backpressure
|
||||
2. Multi/single consumer support
|
||||
3. Downstream consumer termination
|
||||
4. Upstream producer termination
|
||||
|
||||
The below sections are providing a detailed explanation of each of those.
|
||||
|
||||
### Backpressure
|
||||
|
||||
In general, backpressure is the mechanism that prevents a fast producer from
|
||||
overwhelming a slow consumer. It helps the stability of the overall system by
|
||||
regulating the flow of data between different components. Additionally, it
|
||||
allows us to put an upper bound on the resource consumption of a system. In reality,
|
||||
backpressure is used in almost all networked applications.
|
||||
|
||||
In Swift, asynchronous sequences also have the concept of internal backpressure.
|
||||
This is modeled by the pull-based implementation where a consumer has to call
|
||||
`next` on the `AsyncIterator`. In this model, there is no way for a consumer to
|
||||
overwhelm a producer since the producer controls the rate of pulling elements.
|
||||
|
||||
However, the internal backpressure of an asynchronous sequence isn't the only
|
||||
backpressure in play. There is also the source backpressure that is producing
|
||||
the actual elements. For a backpressured system, it is important that every
|
||||
component of such a system is aware of the backpressure of its consumer and its
|
||||
producer.
|
||||
|
||||
Let's take a quick look at how our current root asynchronous sequences are handling
|
||||
this.
|
||||
|
||||
`Async[Throwing]Stream` aims to support backpressure by providing a configurable
|
||||
buffer and returning `Async[Throwing]Stream.Continuation.YieldResult` which
|
||||
contains the current buffer depth from the `yield()` method. However, only
|
||||
providing the current buffer depth on `yield()` is not enough to bridge a
|
||||
backpressured system into an asynchronous sequence since this can only be used
|
||||
as a "stop" signal, but we are missing a signal to indicate resuming the
|
||||
production. The only viable backpressure strategy that can be implemented with
|
||||
the current API is a timed backoff where we stop producing for some period of
|
||||
time and then speculatively produce again. This is a very inefficient pattern
|
||||
that produces high latencies and inefficient use of resources.
|
||||
|
||||
`Async[Throwing]Channel` is a multi-producer-multi-consumer channel that only
|
||||
supports asynchronous producers. Additionally, the backpressure strategy is
|
||||
fixed by a buffer size of 1 element per producer.
|
||||
|
||||
We are currently lacking a type that supports a configurable backpressure
|
||||
strategy and both asynchronous and synchronous producers.
|
||||
|
||||
### Multi/single consumer support
|
||||
|
||||
The `AsyncSequence` protocol itself makes no assumptions about whether the
|
||||
implementation supports multiple consumers or not. This allows the creation of
|
||||
unicast and multicast asynchronous sequences. The difference between a unicast
|
||||
and multicast asynchronous sequence is if they allow multiple iterators to be
|
||||
created. `AsyncStream` does support the creation of multiple iterators and it
|
||||
does handle multiple consumers correctly. On the other hand,
|
||||
`AsyncThrowingStream` also supports multiple iterators but does `fatalError`
|
||||
when more than one iterator has to suspend. The original proposal states:
|
||||
|
||||
> As with any sequence, iterating over an AsyncStream multiple times, or
|
||||
creating multiple iterators and iterating over them separately, may produce an
|
||||
unexpected series of values.
|
||||
|
||||
While that statement leaves room for any behavior, we learned that a clear distinction
|
||||
of behavior for root asynchronous sequences is beneficial; especially when it comes to
|
||||
how transformation algorithms are applied on top.
|
||||
|
||||
### Downstream consumer termination
|
||||
|
||||
Downstream consumer termination allows the producer to notify the consumer that
|
||||
no more values are going to be produced. `Async[Throwing]Stream` does support
|
||||
this by calling the `finish()` or `finish(throwing:)` methods of the
|
||||
`Async[Throwing]Stream.Continuation`. However, `Async[Throwing]Stream` does not
|
||||
handle the case that the `Continuation` may be `deinit`ed before one of the
|
||||
finish methods is called. This currently leads to async streams that never
|
||||
terminate.
|
||||
|
||||
### Upstream producer termination
|
||||
|
||||
Upstream producer termination is the inverse of downstream consumer termination,
|
||||
where the producer is notified once the consumption has terminated. Currently,
|
||||
`Async[Throwing]Stream` does expose the `onTermination` property on the
|
||||
`Continuation`. The `onTermination` closure is invoked once the consumer has
|
||||
terminated. The consumer can terminate in four separate cases:
|
||||
|
||||
1. The asynchronous sequence was `deinit`ed and no iterator was created.
|
||||
2. The iterator was `deinit`ed and the asynchronous sequence is unicast.
|
||||
3. The consuming task is canceled.
|
||||
4. The asynchronous sequence returned `nil` or threw.
|
||||
|
||||
`Async[Throwing]Stream` currently invokes `onTermination` in all cases; however,
|
||||
since `Async[Throwing]Stream` supports multiple consumers (as discussed in the
|
||||
`Multi/single consumer support` section), a single consumer task being canceled
|
||||
leads to the termination of all consumers. This is not expected from multicast
|
||||
asynchronous sequences in general.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
The above motivation lays out the expected behaviors for any consumer/producer
|
||||
system and compares them to the behaviors of `Async[Throwing]Stream` and
|
||||
`Async[Throwing]Channel`.
|
||||
|
||||
This section proposes a new type called `MultiProducerSingleConsumerAsyncChannel`
|
||||
that implements all of the above-mentioned behaviors. Importantly, this proposed
|
||||
solution is taking advantage of `~Copyable` types to model the
|
||||
multi-producer-single-consumer behavior. While the current `AsyncSequence`
|
||||
protocols are not supporting `~Copyable` types, we provide a way to convert the
|
||||
proposed channel to an asynchronous sequence. This leaves us room to support any
|
||||
potential future asynchronous streaming protocol that supports `~Copyable`.
|
||||
|
||||
### Creating a MultiProducerSingleConsumerAsyncChannel
|
||||
|
||||
You can create an `MultiProducerSingleConsumerAsyncChannel` instance using the
|
||||
`makeChannel(of:backpressureStrategy:)` method. This method returns you the
|
||||
channel and the source. The source can be used to send new values to the
|
||||
asynchronous channel. The new API specifically provides a
|
||||
multi-producer/single-consumer pattern.
|
||||
|
||||
```swift
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
|
||||
// The channel and source can be extracted from the returned type
|
||||
let channel = consume channelAndSource.channel
|
||||
let source = consume channelAndSource.source
|
||||
```
|
||||
|
||||
The new proposed APIs offer two different backpressure strategies:
|
||||
- Watermark: Using a low and high watermark.
|
||||
- Unbounded: Unbounded buffering of the channel. **Only** use this if the
|
||||
production is limited through some other means.
|
||||
|
||||
The source is used to send values to the channel. It provides different APIs for
|
||||
synchronous and asynchronous producers. All of the APIs are relaying the
|
||||
backpressure of the channel. The synchronous multi-step APIs are the foundation
|
||||
for all other APIs. Below is an example of how it can be used:
|
||||
|
||||
```swift
|
||||
do {
|
||||
let sendResult = try source.send(contentsOf: sequence)
|
||||
|
||||
switch sendResult {
|
||||
case .produceMore:
|
||||
// Trigger more production in the underlying system
|
||||
|
||||
case .enqueueCallback(let callbackHandle):
|
||||
// There are enough values in the channel already. We need to enqueue
|
||||
// a callback to get notified when we should produce more.
|
||||
callbackHandle.enqueueCallback(onProduceMore: { result in
|
||||
switch result {
|
||||
case .success:
|
||||
// Trigger more production in the underlying system
|
||||
case .failure(let error):
|
||||
// Terminate the underlying producer
|
||||
}
|
||||
})
|
||||
}
|
||||
} catch {
|
||||
// `send(contentsOf:)` throws if the channel already terminated
|
||||
}
|
||||
```
|
||||
|
||||
The above API offers the most control and highest performance when bridging a
|
||||
synchronous producer to a `MultiProducerSingleConsumerAsyncChannel`. First, you have
|
||||
to send values using the `send(contentsOf:)` which returns a `SendResult`. The
|
||||
result either indicates that more values should be produced or that a callback
|
||||
should be enqueued by calling the `enqueueCallback(onProduceMore:)` method.
|
||||
This callback is invoked once the backpressure strategy
|
||||
decides that more values should be produced. This API aims to offer the most
|
||||
flexibility with the greatest performance. The callback only has to be allocated
|
||||
in the case where the producer needs to pause production.
|
||||
|
||||
Additionally, the above API is the building block for some higher-level and
|
||||
easier-to-use APIs to send values to the channel. Below is an
|
||||
example of the two higher-level APIs.
|
||||
|
||||
```swift
|
||||
// Writing new values and providing a callback when to produce more
|
||||
try source.send(contentsOf: sequence, onProduceMore: { result in
|
||||
switch result {
|
||||
case .success:
|
||||
// Trigger more production
|
||||
case .failure(let error):
|
||||
// Terminate the underlying producer
|
||||
}
|
||||
})
|
||||
|
||||
// This method suspends until more values should be produced
|
||||
try await source.send(contentsOf: sequence)
|
||||
```
|
||||
|
||||
With the above APIs, we should be able to effectively bridge any system into a
|
||||
`MultiProducerSingleConsumerAsyncChannel` regardless of whether the system is callback-based,
|
||||
blocking, or asynchronous.
|
||||
|
||||
### Multi producer
|
||||
|
||||
To support multiple producers, the source offers a `copy` method to produce a new
|
||||
source. The source is returned `sending`, so it is in a disconnected isolation
|
||||
region from the original source, allowing it to be passed into a different isolation
|
||||
region to concurrently produce elements.
|
||||
|
||||
```swift
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 5)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source1 = consume channelAndSource.source
|
||||
var source2 = source1.makeAdditionalSource()
|
||||
|
||||
group.addTask {
|
||||
try await source1.send(1)
|
||||
}
|
||||
|
||||
group.addTask() {
|
||||
try await source2.send(2)
|
||||
}
|
||||
|
||||
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
|
||||
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
|
||||
```
|
||||
|
||||
### Downstream consumer termination
|
||||
|
||||
> When reading the next two examples of termination behavior, keep in mind
|
||||
that the newly proposed APIs are providing a strict single consumer channel.
|
||||
|
||||
Calling `finish()` terminates the downstream consumer. Below is an example of
|
||||
this:
|
||||
|
||||
```swift
|
||||
// Termination through calling finish
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
|
||||
try await source.send(1)
|
||||
source.finish()
|
||||
|
||||
print(await channel.next()) // Prints Optional(1)
|
||||
print(await channel.next()) // Prints nil
|
||||
```
|
||||
|
||||
If the channel has a failure type it can also be finished with an error.
|
||||
|
||||
```swift
|
||||
// Termination through calling finish
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
throwing: SomeError.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
|
||||
try await source.send(1)
|
||||
source.finish(throwing: SomeError)
|
||||
|
||||
print(try await channel.next()) // Prints Optional(1)
|
||||
print(try await channel.next()) // Throws SomeError
|
||||
```
|
||||
|
||||
The other way to terminate the consumer is by deiniting the source. This has the
|
||||
same effect as calling `finish()`. Since the source is a `~Copyable` type, this
|
||||
will happen automatically when the source is last used or explicitly consumed.
|
||||
|
||||
```swift
|
||||
// Termination through deiniting the source
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
|
||||
try await source.send(1)
|
||||
_ = consume source // Explicitly consume the source
|
||||
|
||||
print(await channel.next()) // Prints Optional(1)
|
||||
print(await channel.next()) // Prints nil
|
||||
```
|
||||
|
||||
### Upstream producer termination
|
||||
|
||||
The producer will get notified about termination through the `onTerminate`
|
||||
callback. Termination of the producer happens in the following scenarios:
|
||||
|
||||
```swift
|
||||
// Termination through task cancellation
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
source.setOnTerminationCallback { print("Terminated") }
|
||||
|
||||
let task = Task {
|
||||
await channel.next()
|
||||
}
|
||||
task.cancel() // Prints Terminated
|
||||
```
|
||||
|
||||
```swift
|
||||
// Termination through deiniting the channel
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
source.setOnTerminationCallback { print("Terminated") }
|
||||
_ = consume channel // Prints Terminated
|
||||
```
|
||||
|
||||
```swift
|
||||
// Termination through finishing the source and consuming the last element
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source = consume channelAndSource.source
|
||||
source.setOnTerminationCallback { print("Terminated") }
|
||||
|
||||
_ = try await source.send(1)
|
||||
source.finish()
|
||||
|
||||
print(await channel.next()) // Prints Optional(1)
|
||||
await channel.next() // Prints Terminated
|
||||
```
|
||||
|
||||
```swift
|
||||
// Termination through deiniting the last source and consuming the last element
|
||||
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
of: Int.self,
|
||||
backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
)
|
||||
var channel = consume channelAndSource.channel
|
||||
var source1 = consume channelAndSource.source
|
||||
var source2 = source1.makeAdditionalSource()
|
||||
source1.setOnTerminationCallback { print("Terminated") }
|
||||
|
||||
_ = try await source1.send(1)
|
||||
_ = consume source1
|
||||
_ = try await source2.send(2)
|
||||
|
||||
print(await channel.next()) // Prints Optional(1)
|
||||
print(await channel.next()) // Prints Optional(2)
|
||||
_ = consume source2
|
||||
await channel.next() // Prints Terminated
|
||||
```
|
||||
|
||||
Similar to the downstream consumer termination, trying to send more elements after the
|
||||
producer has been terminated will result in an error thrown from the send methods.
|
||||
|
||||
## Detailed design
|
||||
|
||||
```swift
|
||||
#if compiler(>=6.1)
|
||||
/// An error that is thrown from the various `send` methods of the
|
||||
/// ``MultiProducerSingleConsumerAsyncChannel/Source``.
|
||||
///
|
||||
/// This error is thrown when the channel is already finished when
|
||||
/// trying to send new elements to the source.
|
||||
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error { }
|
||||
|
||||
/// A multi-producer single-consumer channel.
|
||||
///
|
||||
/// The ``MultiProducerSingleConsumerAsyncChannel`` provides a ``MultiProducerSingleConsumerAsyncChannel/Source`` to
|
||||
/// send values to the channel. The channel supports different back pressure strategies to control the
|
||||
/// buffering and demand. The channel will buffer values until its backpressure strategy decides that the
|
||||
/// producer have to wait.
|
||||
///
|
||||
/// This channel is also suitable for the single-producer single-consumer use-case
|
||||
///
|
||||
/// ## Using a MultiProducerSingleConsumerAsyncChannel
|
||||
///
|
||||
/// To use a ``MultiProducerSingleConsumerAsyncChannel`` you have to create a new channel with its source first by calling
|
||||
/// the ``MultiProducerSingleConsumerAsyncChannel/makeChannel(of:throwing:BackpressureStrategy:)`` method.
|
||||
/// Afterwards, you can pass the source to the producer and the channel to the consumer.
|
||||
///
|
||||
/// ```
|
||||
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
/// of: Int.self,
|
||||
/// backpressureStrategy: .watermark(low: 2, high: 4)
|
||||
/// )
|
||||
///
|
||||
/// // The channel and source can be extracted from the returned type
|
||||
/// let channel = consume channelAndSource.channel
|
||||
/// let source = consume channelAndSource.source
|
||||
/// ```
|
||||
///
|
||||
/// ### Asynchronous producing
|
||||
///
|
||||
/// Values can be send to the source from asynchronous contexts using ``MultiProducerSingleConsumerAsyncChannel/Source/send(_:)-8eo96``
|
||||
/// and ``MultiProducerSingleConsumerAsyncChannel/Source/send(contentsOf:)``. Backpressure results in calls
|
||||
/// to the `send` methods to be suspended. Once more elements should be produced the `send` methods will be resumed.
|
||||
///
|
||||
/// ```
|
||||
/// try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
/// group.addTask {
|
||||
/// try await source.send(1)
|
||||
/// try await source.send(2)
|
||||
/// try await source.send(3)
|
||||
/// }
|
||||
///
|
||||
/// for await element in channel {
|
||||
/// print(element)
|
||||
/// }
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ### Synchronous produceing
|
||||
///
|
||||
/// Values can also be send to the source from synchronous context. Backpressure is also exposed on the synchronous contexts; however,
|
||||
/// it is up to the caller to decide how to properly translate the backpressure to underlying producer e.g. by blocking the thread.
|
||||
///
|
||||
/// ```swift
|
||||
/// do {
|
||||
/// let sendResult = try source.send(contentsOf: sequence)
|
||||
///
|
||||
/// switch sendResult {
|
||||
/// case .produceMore:
|
||||
/// // Trigger more production in the underlying system
|
||||
///
|
||||
/// case .enqueueCallback(let callbackHandle):
|
||||
/// // There are enough values in the channel already. We need to enqueue
|
||||
/// // a callback to get notified when we should produce more.
|
||||
/// callbackHandle.enqueueCallback(onProduceMore: { result in
|
||||
/// switch result {
|
||||
/// case .success:
|
||||
/// // Trigger more production in the underlying system
|
||||
/// case .failure(let error):
|
||||
/// // Terminate the underlying producer
|
||||
/// }
|
||||
/// })
|
||||
/// }
|
||||
/// } catch {
|
||||
/// // `send(contentsOf:)` throws if the channel already terminated
|
||||
/// }
|
||||
/// ```
|
||||
///
|
||||
/// ### Multiple producers
|
||||
///
|
||||
/// To support multiple producers the source offers a ``Source/makeAdditionalSource()`` method to produce a new source.
|
||||
///
|
||||
/// ### Terminating the production of values
|
||||
///
|
||||
/// The consumer can be terminated through multiple ways:
|
||||
/// - Calling ``Source/finish(throwing:)``.
|
||||
/// - Deiniting all sources.
|
||||
///
|
||||
/// In both cases, if there are still elements buffered by the channel, then the consumer will receive
|
||||
/// all buffered elements. Afterwards it will be terminated.
|
||||
///
|
||||
/// ### Observing termination of the consumer
|
||||
///
|
||||
/// When the consumer stops consumption by either deiniting the channel or the task calling ``next(isolation:)``
|
||||
/// getting cancelled, the source will get notified about the termination if a termination callback has been set
|
||||
/// before by calling ``Source/setOnTerminationCallback(_:)``.
|
||||
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
|
||||
public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>: ~Copyable {
|
||||
/// A struct containing the initialized channel and source.
|
||||
///
|
||||
/// This struct can be deconstructed by consuming the individual
|
||||
/// components from it.
|
||||
///
|
||||
/// ```swift
|
||||
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
|
||||
/// of: Int.self,
|
||||
/// backpressureStrategy: .watermark(low: 5, high: 10)
|
||||
/// )
|
||||
/// var channel = consume channelAndSource.channel
|
||||
/// var source = consume channelAndSource.source
|
||||
/// ```
|
||||
@frozen
|
||||
public struct ChannelAndStream : ~Copyable {
|
||||
/// The channel.
|
||||
public var channel: MultiProducerSingleConsumerAsyncChannel
|
||||
/// The source.
|
||||
public var source: Source
|
||||
}
|
||||
|
||||
/// Initializes a new ``MultiProducerSingleConsumerAsyncChannel`` and an ``MultiProducerSingleConsumerAsyncChannel/Source``.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - elementType: The element type of the channel.
|
||||
/// - failureType: The failure type of the channel.
|
||||
/// - backpressureStrategy: The backpressure strategy that the channel should use.
|
||||
/// - Returns: A tuple containing the channel and its source. The source should be passed to the
|
||||
/// producer while the channel should be passed to the consumer.
|
||||
public static func makeChannel(
|
||||
of elementType: Element.Type = Element.self,
|
||||
throwing failureType: Failure.Type = Never.self,
|
||||
backpressureStrategy: Source.BackpressureStrategy
|
||||
) -> ChannelAndStream
|
||||
|
||||
/// Returns the next element.
|
||||
///
|
||||
/// If this method returns `nil` it indicates that no further values can ever
|
||||
/// be returned. The channel automatically closes when all sources have been deinited.
|
||||
///
|
||||
/// If there are no elements and the channel has not been finished yet, this method will
|
||||
/// suspend until an element is send to the channel.
|
||||
///
|
||||
/// If the task calling this method is cancelled this method will return `nil`.
|
||||
///
|
||||
/// - Parameter isolation: The callers isolation.
|
||||
/// - Returns: The next buffered element.
|
||||
public func next(isolation: isolated (any Actor)? = #isolation) async throws(Failure) -> Element?
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel {
|
||||
/// A struct to send values to the channel.
|
||||
///
|
||||
/// Use this source to provide elements to the channel by calling one of the `send` methods.
|
||||
public struct Source: ~Copyable, Sendable {
|
||||
/// A struct representing the backpressure of the channel.
|
||||
public struct BackpressureStrategy: Sendable {
|
||||
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
|
||||
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
|
||||
public static func watermark(low: Int, high: Int) -> BackpressureStrategy
|
||||
|
||||
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
|
||||
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
|
||||
/// - waterLevelForElement: A closure used to compute the contribution of each buffered element to the current water level.
|
||||
///
|
||||
/// - Note, `waterLevelForElement` will be called on each element when it is written into the source and when
|
||||
/// it is consumed from the channel, so it is recommended to provide a function that runs in constant time.
|
||||
public static func watermark(low: Int, high: Int, waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int) -> BackpressureStrategy
|
||||
|
||||
/// An unbounded backpressure strategy.
|
||||
///
|
||||
/// - Important: Only use this strategy if the production of elements is limited through some other mean. Otherwise
|
||||
/// an unbounded backpressure strategy can result in infinite memory usage and cause
|
||||
/// your process to run out of memory.
|
||||
public static func unbounded() -> BackpressureStrategy
|
||||
}
|
||||
|
||||
/// A type that indicates the result of sending elements to the source.
|
||||
public enum SendResult: ~Copyable, Sendable {
|
||||
/// A handle that is returned when the channel's backpressure strategy indicated that production should
|
||||
/// be suspended. Use this handle to enqueue a callback by calling the ``CallbackHandle/enqueueCallback(onProduceMore:)`` method.
|
||||
///
|
||||
/// - Important: ``CallbackHandle/enqueueCallback(onProduceMore:)`` and ``CallbackHandle/cancelCallback()`` must
|
||||
/// only be called once.
|
||||
public struct CallbackHandle: Sendable, Hashable {
|
||||
/// Enqueues a callback that will be invoked once more elements should be produced.
|
||||
///
|
||||
/// - Important: Calling enqueue more than once is **not allowed**.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - onProduceMore: The callback which gets invoked once more elements should be produced.
|
||||
@inlinable
|
||||
public mutating func enqueueCallback(
|
||||
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
|
||||
)
|
||||
|
||||
/// Cancel an enqueued callback.
|
||||
///
|
||||
/// - Note: This methods supports being called before ``enqueueCallback(onProduceMore:)`` is called.
|
||||
///
|
||||
/// - Important: Calling enqueue more than once is **not allowed**.
|
||||
@inlinable
|
||||
public mutating func cancelCallback()
|
||||
}
|
||||
|
||||
/// Indicates that more elements should be produced and send to the source.
|
||||
case produceMore
|
||||
|
||||
/// Indicates that a callback should be enqueued.
|
||||
case enqueueCallback(CallbackHandle)
|
||||
}
|
||||
|
||||
/// A callback to invoke when the channel finished.
|
||||
///
|
||||
/// This is called after the last element has been consumed by the channel.
|
||||
public func setOnTerminationCallback(_ callback: @escaping @Sendable () -> Void)
|
||||
|
||||
/// Creates a new source which can be used to send elements to the channel concurrently.
|
||||
///
|
||||
/// The channel will only automatically be finished if all existing sources have been deinited.
|
||||
///
|
||||
/// - Returns: A new source for sending elements to the channel.
|
||||
public mutating func makeAdditionalSource() -> Source
|
||||
|
||||
/// Sends new elements to the channel.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
|
||||
/// indicating the failure.
|
||||
///
|
||||
/// - Parameter sequence: The elements to send to the channel.
|
||||
/// - Returns: The result that indicates if more elements should be produced at this time.
|
||||
public mutating func send<S>(
|
||||
contentsOf sequence: consuming sending S
|
||||
) throws -> SendResult where Element == S.Element, S: Sequence
|
||||
|
||||
/// Send the element to the channel.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// provided element. If the channel already terminated then this method will throw an error
|
||||
/// indicating the failure.
|
||||
///
|
||||
/// - Parameter element: The element to send to the channel.
|
||||
/// - Returns: The result that indicates if more elements should be produced at this time.
|
||||
public mutating func send(_ element: sending consuming Element) throws -> SendResult
|
||||
|
||||
/// Send new elements to the channel and provide a callback which will be invoked once more elements should be produced.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// first element of the provided sequence. If the channel already terminated then `onProduceMore` will be invoked with
|
||||
/// a `Result.failure`.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - sequence: The elements to send to the channel.
|
||||
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
|
||||
/// invoked during the call to ``send(contentsOf:onProduceMore:)``.
|
||||
public mutating func send<S>(
|
||||
contentsOf sequence: consuming sending S,
|
||||
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
|
||||
) where Element == S.Element, S: Sequence
|
||||
|
||||
/// Sends the element to the channel.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// provided element. If the channel already terminated then `onProduceMore` will be invoked with
|
||||
/// a `Result.failure`.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - element: The element to send to the channel.
|
||||
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
|
||||
/// invoked during the call to ``send(_:onProduceMore:)``.
|
||||
public mutating func send(
|
||||
_ element: consuming sending Element,
|
||||
onProduceMore: @escaping @Sendable (Result<Void, Error>
|
||||
) -> Void)
|
||||
|
||||
/// Send new elements to the channel.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
|
||||
/// indicating the failure.
|
||||
///
|
||||
/// This method returns once more elements should be produced.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - sequence: The elements to send to the channel.
|
||||
public mutating func send<S>(
|
||||
contentsOf sequence: consuming sending S
|
||||
) async throws where Element == S.Element, S: Sequence
|
||||
|
||||
/// Send new element to the channel.
|
||||
///
|
||||
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
|
||||
/// provided element. If the channel already terminated then this method will throw an error
|
||||
/// indicating the failure.
|
||||
///
|
||||
/// This method returns once more elements should be produced.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - element: The element to send to the channel.
|
||||
public mutating func send(_ element: consuming sending Element) async throws
|
||||
|
||||
/// Send the elements of the asynchronous sequence to the channel.
|
||||
///
|
||||
/// This method returns once the provided asynchronous sequence or the channel finished.
|
||||
///
|
||||
/// - Important: This method does not finish the source if consuming the upstream sequence terminated.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - sequence: The elements to send to the channel.
|
||||
public mutating func send<S>(
|
||||
contentsOf sequence: consuming sending S
|
||||
) async throws where Element: Sendable, Element == S.Element, S: Sendable, S: AsyncSequence
|
||||
|
||||
/// Indicates that the production terminated.
|
||||
///
|
||||
/// After all buffered elements are consumed the subsequent call to ``MultiProducerSingleConsumerAsyncChannel/next(isolation:)`` will return
|
||||
/// `nil` or throw an error.
|
||||
///
|
||||
/// Calling this function more than once has no effect. After calling finish, the channel enters a terminal state and doesn't accept
|
||||
/// new elements.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - error: The error to throw, or `nil`, to finish normally.
|
||||
public consuming func finish(throwing error: Failure? = nil)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
|
||||
extension MultiProducerSingleConsumerAsyncChannel {
|
||||
/// Converts the channel to an asynchronous sequence for consumption.
|
||||
///
|
||||
/// - Important: The returned asynchronous sequence only supports a single iterator to be created and
|
||||
/// will fatal error at runtime on subsequent calls to `makeAsyncIterator`.
|
||||
public consuming func asyncSequence() -> some (AsyncSequence<Element, Failure> & Sendable)
|
||||
}
|
||||
```
|
||||
|
||||
## Comparison to other root asynchronous primitives
|
||||
|
||||
### swift-async-algorithm: AsyncChannel
|
||||
|
||||
The `AsyncChannel` is a multi-consumer/multi-producer root asynchronous sequence
|
||||
which can be used to communicate between two tasks. It only offers asynchronous
|
||||
production APIs and has an effective buffer of one per producer. This means that
|
||||
any producer will be suspended until its value has been consumed. `AsyncChannel`
|
||||
can handle multiple consumers and resumes them in FIFO order.
|
||||
|
||||
### swift-nio: NIOAsyncSequenceProducer
|
||||
|
||||
The NIO team has created their own root asynchronous sequence with the goal to
|
||||
provide a high-performance sequence that can be used to bridge a NIO `Channel`
|
||||
inbound stream into Concurrency. The `NIOAsyncSequenceProducer` is a highly
|
||||
generic and fully inlinable type and quite unwieldy to use. This proposal is
|
||||
heavily inspired by the learnings from this type but tries to create a more
|
||||
flexible and easier-to-use API that fits into the standard library.
|
||||
|
||||
## Future directions
|
||||
|
||||
### Adaptive backpressure strategy
|
||||
|
||||
The high/low watermark strategy is common in networking code; however, there are
|
||||
other strategies such as an adaptive strategy that we could offer in the future.
|
||||
An adaptive strategy regulates the backpressure based on the rate of
|
||||
consumption and production. With the proposed new APIs, we can easily add further
|
||||
strategies.
|
||||
|
||||
### Support `~Copyable` elements
|
||||
|
||||
In the future, we can extend the channel to support `~Copyable` elements. We
|
||||
only need an underlying buffer primitive that can hold `~Copyable` types, and the
|
||||
continuations need to support `~Copyable` elements as well. By making the
|
||||
channel not directly conform to `AsyncSequence`, we can support this down the
|
||||
road.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
### Provide an `onTermination` callback to the factory method
|
||||
|
||||
During development of the new APIs, I first tried to provide the `onTermination`
|
||||
callback in the `makeChannel` method. However, that showed significant usability
|
||||
problems in scenarios where one wants to store the source in a type and
|
||||
reference `self` in the `onTermination` closure at the same time; hence, I kept
|
||||
the current pattern of setting the `onTermination` closure on the source.
|
||||
|
||||
### Provide a `onConsumerCancellation` callback
|
||||
|
||||
During the pitch phase, it was raised that we should provide a
|
||||
`onConsumerCancellation` callback which gets invoked once the asynchronous
|
||||
channel notices that the consuming task got cancelled. This callback could be
|
||||
used to customize how cancellation is handled by the channel, e.g. one could
|
||||
imagine writing a few more elements to the channel before finishing it. Right now,
|
||||
the channel immediately returns `nil` or throws a `CancellationError` when it
|
||||
notices cancellation. This proposal decided not to provide this customization
|
||||
because it opens up the possibility that asynchronous channels are not terminating
|
||||
when implemented incorrectly. Additionally, asynchronous sequences are not the
|
||||
only place where task cancellation leads to an immediate error being thrown i.e.
|
||||
`Task.sleep()` does the same. Hence, the value of the asynchronous not
|
||||
terminating immediately brings little value when the next call in the iterating
|
||||
task might throw. However, the implementation is flexible enough to add this in
|
||||
the future, and we can just default it to the current behaviour.
|
||||
|
||||
### Create a custom type for the `Result` of the `onProduceMore` callback
|
||||
|
||||
The `onProducerMore` callback takes a `Result<Void, Error>` which is used to
|
||||
indicate if the producer should produce more or if the asynchronous channel
|
||||
finished. We could introduce a new type for this, but the proposal decided
|
||||
against it since it effectively is a result type.
|
||||
|
||||
### Use an initializer instead of factory methods
|
||||
|
||||
Instead of providing a `makeChannel` factory method, we could use an initializer
|
||||
approach that takes a closure which gets the `Source` passed into. A similar API
|
||||
has been offered with the `Continuation` based approach and
|
||||
[SE-0388](https://github.com/apple/swift-evolution/blob/main/proposals/0388-async-stream-factory.md)
|
||||
introduced new factory methods to solve some of the usability ergonomics with
|
||||
the initializer based APIs.
|
||||
|
||||
### Provide the type on older compilers
|
||||
|
||||
To achieve maximum performance, the implementation is using `~Copyable` extensively.
|
||||
On Swift versions before 6.1, there is a https://github.com/swiftlang/swift/issues/78048 when using; hence, this type
|
||||
is only usable with Swift 6.1 and later compilers.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
- [Johannes Weiss](https://github.com/weissi) - For making me aware how
|
||||
important this problem is and providing great ideas on how to shape the API.
|
||||
- [Philippe Hausler](https://github.com/phausler) - For helping me designing the
|
||||
APIs and continuously providing feedback
|
||||
- [George Barnett](https://github.com/glbrntt) - For providing extensive code
|
||||
reviews and testing the implementation.
|
||||
- [Si Beaumont](https://github.com/simonjbeaumont) - For implementing the element size dependent strategy
|
||||
@@ -0,0 +1,197 @@
|
||||
# Share
|
||||
* Proposal: [SAA-0015](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0016-share.md)
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
* Status: **Accepted**
|
||||
* Implementation: [
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncShareSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestShare.swift)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
Many of the AsyncSequence adopting types only permit a one singular consumption. However there are many times that the same produced values are useful in more than one place. Out of that mechanism there are a few approaches to share, distribute, and broadcast those values. This proposal will focus on one concept; sharing. Sharing is where each consumption independently can make forward progress and get the same values but do not replay from the beginning of time.
|
||||
|
||||
## Motivation
|
||||
|
||||
There are many potential usages for the sharing concept of AsyncSequences.
|
||||
|
||||
One such example is the case where a source of data as an asynchronous sequence needs to be consumed by updating UI, logging, and additionally a network connection. This particular case does not matter on which uses but instead that those uses are independent of each other. It would not be expected for networking to block or delay the updates to UI, nor should logging. This example case also illustrates that the isolation of each side might be different and that some of the sides may not tolerate coalescing or dropping values.
|
||||
|
||||
There are many other use cases that have been requested for this family of algorithms. Since the release of AsyncAlgorithms it has perhaps been the most popularly requested set of behaviors as additions to the package.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
AsyncAlgorithms will introduce a new extension function on AsyncSequence that will provide a shareable asynchronous sequence that will produce the same values upon iteration from multiple instances of it's AsyncIterator. Those iterations can take place in multiple isolations.
|
||||
|
||||
When values from a differing isolation cannot be coalesced, the two options available are either awaiting (an exertion of back-pressure across the sequences) or buffering (an internal back-pressure to a buffer). Replaying the values from the beginning of the creation of the sequence is a distinctly different behavior that should be considered a different use case. This then leaves the behavioral characteristic of this particular operation of share as; sharing a buffer of values started from the initialization of a new iteration of the sequence. Control over that buffer should then have options to determine the behavior, similar to how AsyncStream allows that control. It should have options to be unbounded, buffering the oldest count of elements, or buffering the newest count of elements.
|
||||
|
||||
It is critical to identify that this is one algorithm in the family of algorithms for sharing values. It should not attempt to solve all behavioral requirements but instead serve a common set of them that make cohesive sense together. This proposal is not mutually exclusive to the other algorithms in the sharing family.
|
||||
|
||||
## Detailed design
|
||||
|
||||
A new extension will be added to return a `Sendable` `AsyncSequence`. This extension will take a buffering policy to identify how the buffer will be handled when iterations do not consume at the same rate.
|
||||
|
||||
The `Sendable` annotation identifies to the developer that this sequence can be shared and stored in an existental `any`.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: Sendable {
|
||||
public func share(
|
||||
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
|
||||
) -> some AsyncSequence<Element, Failure> & Sendable
|
||||
}
|
||||
```
|
||||
|
||||
The buffer internally to the share algorithm will only extend back to the furthest element available but there will only be a singular buffer shared across all iterators. This ensures that with the application of the buffering policy the storage size is as minimal as possible while still allowing all iterations to avoid dropping values and keeping the memory usage in check. The signature reuses the existing `AsyncBufferSequencePolicy` type to specify the behavior around buffering either responding to how it should limit emitting to the buffer or what should happen when the buffer is exceeded.
|
||||
|
||||
## Runtime Behavior
|
||||
|
||||
The runtime behaviors fall into a few categories; ordering, iteration isolation, cancellation, and lifetimes. To understand the behaviors there are a terms useful to define. Each creation of the AsyncIterator of the sequence and invocation of next will be referred to a side of the share iteration. The back pressure to the system to fetch a new element or termination is referred to as demand. The limit which is the pending gate for awaiting until the buffer has been serviced used for the `AsyncBufferSequencePolicy.bounded(_ : Int)` policy. The last special definition is that of the extent which is specifically in this case the lifetime of the asynchronous sequence itself.
|
||||
|
||||
When the underlying type backing the share algorithm is constructed a new extent is created; this is used for tracking the reference lifetime under the hood and is used to both house the iteration but also to identify the point at which no more sides can be constructed. When no more sides can be constructed and no sides are left to iterate then the backing iteration is canceled. This prevents any un-referenced task backing the iteration to not be leaked by the algorith itself.
|
||||
|
||||
That construction then creates an initial shared state and buffer. No task is started initially; it is only upon the first demand that the task backing the iteration is started; this means on the first call to next a task is spun up servicing all potential sides. The order of which the sides are serviced is not specified and cannot be relied upon, however the order of delivery within a side is always guarenteed to be ordered. The singular task servicing the iteration will be the only place holding any sort of iterator from the base `AsyncSequence`; so that iterator is isolated and not sent from one isolation to another. That iteration first awaits any limit availability and then awaits for a demand given by a side. After-which it then awaits an element or terminal event from the iterator and enqueues the elements to the buffer.
|
||||
|
||||
The buffer itself is only held in one location, each side however has a cursor index into that buffer and when values are consumed it adjusts the indexes accordingly; leaving the buffer usage only as big as the largest deficit. This means that new sides that are started post initial start up will not have a "replay" effect; that is a similar but distinct algorithm and is not addressed by this proposal. Any buffer size sensitive systems that wish to adjust behavior should be aware that specifying a policy is a suggested step. However in common usage similar to other such systems servicing desktop and mobile applications the common behavior is often unbounded. Alternatively desktop or mobile applications will often want `.bounded(1)` since that enforces the slowest consumption to drive the forward progress at most 1 buffered element. All of the use cases have a reasonable default of `.bounded(1)`; mobile, deskop, and server side uses. Leaving this as the default parameter keeps the progressive disclosure of the beahviors - such that the easiest thing to write is correct for all uses, and then more advanced control can be adjusted by passing in a specific policy. This default argument diverges slightly from AsyncStream, but follows a similar behavior to that of Combine's `share`.
|
||||
|
||||
As previously stated, the isolation of the iteration of the upstream/base AsyncSequence is to a detached task, this ensures that individual sides can have independent cancellation. Those cancellations will have the effect of remvoing that side from the shared iteration and cleaning up accordingly (including adjusting the trimming of the internal buffer).
|
||||
|
||||
Representing concurrent access is difficult to express all potential examples but there are a few cases included with this proposal to illustrate some of the behaviors. If a more comprehensive behavioral analysis is needed, it is strongly suggested to try out the pending pull request to identify how specific behaviors work. Please keep in mind that the odering between tasks is not specified, only the order within one side of iteration.
|
||||
|
||||
Practically this all means that a given iteration may be "behind" another and can eventually catch up (provided it is within the buffer limit).
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .unbounded)
|
||||
|
||||
let t1 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 0 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 1", element)
|
||||
}
|
||||
}
|
||||
|
||||
let t2 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 3 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 2", element)
|
||||
}
|
||||
}
|
||||
|
||||
await t1.value
|
||||
await t2.value
|
||||
|
||||
```
|
||||
|
||||
This example will print a possible ordering of the following:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 3
|
||||
Task 2 4
|
||||
Task 1 1
|
||||
Task 1 2
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
```
|
||||
|
||||
The order of the interleaving of the prints are not guaranteed; however the order of the elements per iteration is. Likewise in this buffering case it is guaranteed that all values are represented in the output.
|
||||
|
||||
If the creation were instead altered to the following:
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingLatest(2))
|
||||
```
|
||||
|
||||
The output would print the possible ordering of:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 4
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
```
|
||||
|
||||
Some values are dropped due to the buffering policy, but eventually they reach consistency. Which similarly works for the following:
|
||||
|
||||
```
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingOldest(2))
|
||||
```
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 4
|
||||
Task 1 1
|
||||
Task 1 2
|
||||
```
|
||||
|
||||
However in this particular case the newest values are the dropped elements.
|
||||
|
||||
The `.bounded(N)` policy enforces consumption to prevent any side from being beyond a given amount away from other sides' consumption.
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bounded(1))
|
||||
|
||||
let t1 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 0 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 1", element)
|
||||
}
|
||||
}
|
||||
|
||||
let t2 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 3 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 2", element)
|
||||
}
|
||||
}
|
||||
|
||||
await t1.value
|
||||
await t2.value
|
||||
```
|
||||
|
||||
Will have a potential ordering output of:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 1 0
|
||||
Task 1 1
|
||||
Task 2 2
|
||||
Task 1 2
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
Task 2 3
|
||||
Task 2 4
|
||||
```
|
||||
|
||||
In that example output Task 2 can get element 0 and 1 but must await until task 1 has caught up to the specified buffering. This limit means that no additional iteration (and no values are then dropped) is made until the buffer count is below the specified value.
|
||||
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
This is an additive API and no existing systems are changed, however it will introduce a few new types that will need to be maintained as ABI interfaces. Since the intent of this is to provide a mechanism to store AsyncSequences to a shared context the type must be exposed as ABI (for type sizing).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
It has been considered that the buffering policy would be nested inside the `AsyncShareSequence` type. However since this seems to be something that will be useful for other types it makes sense to use an existing type from a top level type. However if it is determined that a general form of a buffering policy would require additional behaviors this might be a debatable placement to move back to an interior type similar to AsyncStream.
|
||||
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
# Map Error
|
||||
|
||||
* Proposal: [SAA-0017](0017-map-error.md)
|
||||
* Authors: [Clive Liu](https://github.com/clive819) [Philippe Hausler](https://github.com/phausler)
|
||||
* Review Manager: TBD
|
||||
* Status: **Awaiting review**
|
||||
|
||||
## Introduction
|
||||
|
||||
Asynchronous sequences often participate in carefully crafted systems of algorithms spliced together. Some of those algorithms require that both the element type and the failure type are the same as each-other. In order to line those types up for the element we have the map algorithm today, however there are other times at which when using more specific APIs that transforming the Failure type is needed.
|
||||
|
||||
## Motivation
|
||||
|
||||
The `mapError` function empowers developers to elegantly transform errors within asynchronous sequences, enhancing code readability and maintainability.
|
||||
|
||||
Building failure-type-safe versions of zip or other algorithms will need to require that the associated Failure types are the same. Having an effecient and easy to use transformation routine to adjust the failure-types is then key to delivering or interfacing with those failure-type-safe algorithms.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
A new extension and type will be added to transform the failure-types of AsyncSequences.
|
||||
|
||||
## Detailed design
|
||||
|
||||
The method will be applied to all AsyncSequences via an extension with the function name of `mapError`. This is spiritually related to the `mapError` method on `Result` and similar in functionality to other frameworks' methods of the similar naming. This will not return an opaque result since the type needs to be refined for `Sendable`; in that the `AsyncMapERrorSequence` is only `Sendable` when the base `AsyncSequence` is `Sendable`.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence {
|
||||
public func mapError<MappedFailure: Error>(_ transform: @Sendable @escaping (Failure) async -> MappedFailure) -> AsyncMapErrorSequence<Element, MappedFailure>
|
||||
}
|
||||
|
||||
public struct AsyncMapErrorSequence<Base: AsyncSequence, TransformedFailure: Error>: AsyncSequence { }
|
||||
|
||||
extension AsyncMapErrorSequence: Sendable where Base: Sendable { }
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncMapErrorSequence.Iterator: Sendable {}
|
||||
```
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
This cannot be back-deployed to 1.0 since it has a base requirement for the associated `Failure` and requires typed throws.
|
||||
|
||||
## Naming
|
||||
|
||||
The naming follows to current method naming of the Combine [mapError](https://developer.apple.com/documentation/combine/publisher/maperror(_:)) method and similarly the name of the method on `Result`
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
It was initially considered that the return type would be opaque, however the only way to refine that as Sendable would be to have a disfavored overload; this ended up creating more ambiguity than it seemed worth.
|
||||
@@ -0,0 +1,200 @@
|
||||
# FlatMapLatest
|
||||
|
||||
* Proposal: [SAA-00nn](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/00nn-flatMapLatest.md)
|
||||
* Author(s): [Peter Friese](https://github.com/peterfriese)
|
||||
* Status: **Proposed**
|
||||
* Implementation:
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)
|
||||
]
|
||||
* Decision Notes:
|
||||
* Bugs:
|
||||
|
||||
## Introduction
|
||||
|
||||
When transforming elements of an asynchronous sequence into new asynchronous sequences, there are cases where only the results from the most recent transformation are relevant, and previous transformations should be abandoned. This is particularly common in reactive user interfaces where rapid user input triggers asynchronous operations, but only the result of the latest operation matters.
|
||||
|
||||
## Motivation
|
||||
|
||||
Consider a search-as-you-type interface where each keystroke triggers a network request:
|
||||
|
||||
```swift
|
||||
let searchQueries = userInputField.textChanges
|
||||
|
||||
// Without flatMapLatest - all requests complete, wasting resources
|
||||
for await query in searchQueries {
|
||||
let results = try await searchAPI(query)
|
||||
displayResults(results) // May display stale results
|
||||
}
|
||||
```
|
||||
|
||||
Without automatic cancellation, earlier requests continue to completion even though their results are no longer relevant. This wastes network bandwidth, server resources, and may display stale results to the user if a slower request completes after a faster one.
|
||||
|
||||
The `flatMapLatest` operator solves this by automatically cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence:
|
||||
|
||||
```swift
|
||||
let searchResults = searchQueries.flatMapLatest { query in
|
||||
searchAPI(query)
|
||||
}
|
||||
|
||||
for await result in searchResults {
|
||||
displayResults(result) // Only latest results displayed
|
||||
}
|
||||
```
|
||||
|
||||
This pattern is broadly applicable:
|
||||
- **Location-based queries**: Cancel previous location lookups when user moves
|
||||
- **Dynamic configuration**: Restart data loading when settings change
|
||||
- **Auto-save**: Only save the most recent changes when user types rapidly
|
||||
- **Real-time data**: Switch to new data streams based on user selections
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The `flatMapLatest` algorithm transforms each element from the base `AsyncSequence` into a new inner `AsyncSequence` using a transform closure. When a new element is produced by the base sequence, iteration on the current inner sequence is cancelled, and iteration begins on the newly created sequence.
|
||||
|
||||
The interface is available on all `AsyncSequence` types where both the base and inner sequences are `Sendable` along with two disfavored refinements to account for variations of typed throws signatures:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where T.Failure == Failure, T.Element: Sendable, Element: Sendable
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, Failure> & Sendable where T.Failure == Never, T.Element: Sendable, Element: Sendable
|
||||
|
||||
@_disfavoredOverload
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where Failure == Never, T.Element: Sendable, Element: Sendable
|
||||
}
|
||||
```
|
||||
|
||||
This provides a clean API for expressing switching behavior:
|
||||
|
||||
```swift
|
||||
userActions.flatMapLatest { action in
|
||||
performAction(action)
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm emits elements from the inner sequences. It throws when either the base type or any inner sequence throws.
|
||||
|
||||
Since both the base sequence and inner sequences must be `Sendable` (to support concurrent iteration and cancellation), `AsyncFlatMapLatestSequence` is unconditionally `Sendable`.
|
||||
|
||||
### Implementation Strategy
|
||||
|
||||
The implementation uses a state machine pattern to ensure thread-safe operation:
|
||||
|
||||
1. **Generation Tracking**: Each new inner sequence is assigned a generation number. Elements from stale generations are discarded.
|
||||
2. **Explicit Cancellation**: When a new outer element arrives, the previous inner sequence's task is explicitly cancelled and its continuation is resumed with a cancellation error.
|
||||
3. **Lock-Based Coordination**: A `Lock` protects the state machine from concurrent access.
|
||||
4. **Continuation Management**: The storage manages continuations for both upstream (outer/inner sequences) and downstream (consumer) demand.
|
||||
|
||||
This approach eliminates race conditions where cancelled sequences could emit stale values.
|
||||
|
||||
### Behavioral Characteristics
|
||||
|
||||
**Switching**: When the base sequence produces a new element, the current inner sequence iteration is immediately cancelled. Any elements it would have produced are lost.
|
||||
|
||||
**Completion**: The sequence completes when:
|
||||
1. The base sequence finishes producing elements, AND
|
||||
2. The final inner sequence finishes producing elements
|
||||
|
||||
**Error Handling**: If either the base sequence or any inner sequence throws, the error is immediately propagated and all tasks are cancelled.
|
||||
|
||||
**Cancellation**: Cancelling the downstream iteration cancels both the base sequence iteration and the current inner sequence iteration.
|
||||
|
||||
## Example
|
||||
|
||||
```swift
|
||||
let requests = AsyncStream<String> { continuation in
|
||||
continuation.yield("query1")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("query2")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("query3")
|
||||
continuation.finish()
|
||||
}
|
||||
|
||||
let responses = requests.flatMapLatest { query in
|
||||
AsyncStream<String> { continuation in
|
||||
continuation.yield("\(query): loading")
|
||||
try? await Task.sleep(for: .milliseconds(50))
|
||||
continuation.yield("\(query): complete")
|
||||
continuation.finish()
|
||||
}
|
||||
}
|
||||
|
||||
for await response in responses {
|
||||
print(response)
|
||||
}
|
||||
// Output (may vary due to timing):
|
||||
// query1: loading
|
||||
// query2: loading
|
||||
// query3: loading
|
||||
// query3: complete
|
||||
```
|
||||
|
||||
In this example, the earlier queries (query1 and query2) are cancelled before they complete, so only query3 produces its complete response.
|
||||
|
||||
## Effect on API Resilience
|
||||
|
||||
This is an additive API. No existing systems are changed. The new types introduced are:
|
||||
- `AsyncFlatMapLatestSequence<Base, Inner>`: The sequence type
|
||||
- Associated private types for the state machine implementation
|
||||
|
||||
These types will be part of the ABI surface area.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
### Alternative Names
|
||||
|
||||
**`switchMap`**: Used in ReactiveX, but "switch" in Swift has strong association with control flow statements.
|
||||
|
||||
**`switchToLatest`**: Combine's terminology, but `flatMapLatest` is more discoverable alongside other `map` variants.
|
||||
|
||||
**`flatMap(...).latest()`**: Requires a hypothetical `flatMap` first, adding complexity.
|
||||
|
||||
### Delivering All Elements
|
||||
|
||||
An alternative behavior would buffer elements from cancelled sequences and deliver them later. However, this contradicts the core purpose of "latest" semantics and would be better served by a different operator.
|
||||
|
||||
### No Automatic Cancellation
|
||||
|
||||
Requiring manual cancellation would place significant burden on developers and be error-prone. The automatic cancellation is the key value proposition.
|
||||
|
||||
### Shorthand version for async sequences of async sequences
|
||||
|
||||
Mimicing combine a shorthand extension of `switchToLatest` could be added as an extension when the base AsyncSequence's element conforms to AsyncSequence. The implementation of which is trivial:
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Failure, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Never, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
|
||||
@_disfavoredOverload
|
||||
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Failure == Never, Element.Element: Sendable, Element: Sendable {
|
||||
flatMapLatest { $0 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Comparison with Other Libraries
|
||||
|
||||
**ReactiveX**: ReactiveX has an [API definition of switchMap](https://reactivex.io/documentation/operators/flatmap.html) that performs the same operation for Observables, switching to the latest inner Observable.
|
||||
|
||||
**Combine**: Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which subscribes to the most recent Publisher produced by an upstream Publisher of Publishers. `flatMapLatest` combines the map and switch operations into a single convenient operator.
|
||||
|
||||
**RxSwift**: RxSwift calls this operator `flatMapLatest`, which is the naming this proposal adopts.
|
||||
@@ -1,54 +0,0 @@
|
||||
# Task.select
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/TaskSelect.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestTaskSelect.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
A fundamental part of many algorithms is being able to select the first resolved task from a given list of active tasks. This enables algorithms like `debounce` or `merge`.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Selecting the first task to complete from a list of active tasks is a similar algorithm to `select(2)`. This has similar behavior to `TaskGroup` except that instead of child tasks this function transacts upon already running tasks and does not cancel them upon completion of the selection and does not need to await for the completion of all of the tasks in the list to select.
|
||||
|
||||
```swift
|
||||
extension Task {
|
||||
public static func select<Tasks: Sequence & Sendable>(
|
||||
_ tasks: Tasks
|
||||
) async -> Task<Success, Failure>
|
||||
|
||||
public static func select(
|
||||
_ tasks: Task<Success, Failure>...
|
||||
) async -> Task<Success, Failure>
|
||||
}
|
||||
```
|
||||
|
||||
## Detailed Design
|
||||
|
||||
Given any number of `Task` objects that share the same `Success` and `Failure` types; `Task.select` will suspend and await each tasks result and resume when the first task has produced a result. While the calling task of `Task.select` is suspended if that task is cancelled the tasks being selected receive the cancel. This is similar to the family of `TaskGroup` with a few behavioral and structural differences.
|
||||
|
||||
The `withTaskGroup` API will create efficient child tasks.
|
||||
The `Task.select` API takes pre-existing tasks.
|
||||
|
||||
The `withTaskGroup` API will await all child tasks to be finished before returning.
|
||||
The `Task.select` API will await for the first task to be finished before returning.
|
||||
|
||||
The `withTaskGroup` API will cancel all outstanding child tasks upon awaiting its return.
|
||||
The `Task.select` API will let the non selected tasks keep on running.
|
||||
|
||||
The `withTaskGroup` can support having 0 child tasks.
|
||||
The `Task.select` API requires at least 1 task to select over, anything less is a programmer error.
|
||||
|
||||
This means that `withTaskGroup` is highly suited to run work in parallel, whereas `Task.select` is intended to find the first task that provides a value. There is inherent additional cost to the non-child tasks so `Task.select` should not be used as a replacement for anywhere that is more suitable as a group, but offers more potential for advanced algorithms.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
## Future Directions
|
||||
|
||||
|
||||
|
||||
## Credits/Inspiration
|
||||
+161
-20
@@ -1,36 +1,177 @@
|
||||
// swift-tools-version: 5.6
|
||||
// swift-tools-version: 6.2
|
||||
|
||||
import PackageDescription
|
||||
import CompilerPluginSupport
|
||||
|
||||
let AsyncAlgorithms_v1_0 = "AvailabilityMacro=AsyncAlgorithms 1.0:macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0"
|
||||
#if compiler(>=6.0) && swift(>=6.0) // 5.10 doesnt support visionOS availability
|
||||
let AsyncAlgorithms_v1_1 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
let AsyncAlgorithms_v1_2 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
let AsyncAlgorithms_v1_3 =
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.3:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
#else
|
||||
let AsyncAlgorithms_v1_1 = "AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
let AsyncAlgorithms_v1_2 = "AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
let AsyncAlgorithms_v1_3 = "AvailabilityMacro=AsyncAlgorithms 1.3:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0"
|
||||
#endif
|
||||
|
||||
let availabilityMacros: [SwiftSetting] = [
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_0
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_1
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_2
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
AsyncAlgorithms_v1_3
|
||||
),
|
||||
]
|
||||
|
||||
let package = Package(
|
||||
name: "AsyncAlgorithms",
|
||||
platforms: [
|
||||
.macOS("10.15"),
|
||||
.iOS("13.0"),
|
||||
.tvOS("13.0"),
|
||||
.watchOS("6.0")
|
||||
],
|
||||
name: "swift-async-algorithms",
|
||||
products: [
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]),
|
||||
.library(name: "ClockShims", type: .static, targets: ["ClockShims"]),
|
||||
.library(name: "AsyncSequenceValidation", targets: ["AsyncSequenceValidation"]),
|
||||
.library(name: "_CAsyncSequenceValidationSupport", type: .static, targets: ["AsyncSequenceValidation"])
|
||||
.library(name: "AsyncStreaming", targets: ["AsyncStreaming"]),
|
||||
],
|
||||
traits: [
|
||||
.default(
|
||||
enabledTraits: [
|
||||
// "UnstableAsyncStreaming"
|
||||
]
|
||||
),
|
||||
.trait(
|
||||
name: "UnstableAsyncStreaming",
|
||||
description: """
|
||||
Enables source unstable async streaming components in the _AsyncStreaming
|
||||
module. Do not rely on this module in API stable packages.
|
||||
"""
|
||||
),
|
||||
],
|
||||
dependencies: [],
|
||||
targets: [
|
||||
.target(name: "AsyncAlgorithms", dependencies: ["ClockShims"]),
|
||||
.target(name: "ClockShims"),
|
||||
.target(
|
||||
name: "AsyncAlgorithms",
|
||||
dependencies: [
|
||||
.product(name: "OrderedCollections", package: "swift-collections"),
|
||||
.product(name: "DequeModule", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncStreaming",
|
||||
dependencies: [
|
||||
.product(name: "BasicContainers", package: "swift-collections"),
|
||||
.product(name: "ContainersPreview", package: "swift-collections"),
|
||||
.product(name: "DequeModule", package: "swift-collections"),
|
||||
],
|
||||
exclude: ["NNNN-async-streaming.md"],
|
||||
swiftSettings: [
|
||||
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
|
||||
.enableExperimentalFeature("LifetimeDependence"),
|
||||
.enableExperimentalFeature("Lifetimes"),
|
||||
.enableUpcomingFeature("LifetimeDependence"),
|
||||
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
|
||||
.enableUpcomingFeature("InferIsolatedConformances"),
|
||||
.enableUpcomingFeature("ExistentialAny"),
|
||||
.enableUpcomingFeature("MemberImportVisibility"),
|
||||
.enableUpcomingFeature("InternalImportsByDefault"),
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"]),
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "AsyncAlgorithmsTests",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
|
||||
dependencies: [
|
||||
.target(name: "AsyncAlgorithms"),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
condition: .when(platforms: [
|
||||
.macOS,
|
||||
.iOS,
|
||||
.tvOS,
|
||||
.watchOS,
|
||||
.visionOS,
|
||||
.macCatalyst,
|
||||
.android,
|
||||
.linux,
|
||||
.custom("freebsd"),
|
||||
.openbsd,
|
||||
.wasi,
|
||||
])
|
||||
),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
condition: .when(platforms: [
|
||||
.macOS,
|
||||
.iOS,
|
||||
.tvOS,
|
||||
.watchOS,
|
||||
.visionOS,
|
||||
.macCatalyst,
|
||||
.android,
|
||||
.linux,
|
||||
.custom("freebsd"),
|
||||
.openbsd,
|
||||
.wasi,
|
||||
])
|
||||
),
|
||||
],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "AsyncStreamingTests",
|
||||
dependencies: [
|
||||
"AsyncStreaming",
|
||||
.product(name: "BasicContainers", package: "swift-collections"),
|
||||
.product(name: "ContainersPreview", package: "swift-collections"),
|
||||
.product(name: "SpanPreview", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: [
|
||||
.unsafeFlags([
|
||||
"-Xfrontend", "-disable-availability-checking"
|
||||
])
|
||||
]),
|
||||
.enableExperimentalFeature("SuppressedAssociatedTypesWithDefaults"),
|
||||
.enableExperimentalFeature("LifetimeDependence"),
|
||||
.enableExperimentalFeature("Lifetimes"),
|
||||
.enableUpcomingFeature("LifetimeDependence"),
|
||||
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),
|
||||
.enableUpcomingFeature("InferIsolatedConformances"),
|
||||
.enableUpcomingFeature("ExistentialAny"),
|
||||
.enableUpcomingFeature("MemberImportVisibility"),
|
||||
.enableUpcomingFeature("InternalImportsByDefault"),
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
if Context.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
|
||||
package.dependencies += [
|
||||
.package(
|
||||
url: "https://github.com/apple/swift-collections.git",
|
||||
from: "1.7.0",
|
||||
traits: [.trait(name: "UnstableContainersPreview", condition: .when(traits: ["UnstableAsyncStreaming"]))]
|
||||
)
|
||||
]
|
||||
} else {
|
||||
package.dependencies += [
|
||||
.package(path: "../swift-collections")
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
// swift-tools-version: 5.7
|
||||
|
||||
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,104 @@
|
||||
// swift-tools-version: 5.8
|
||||
|
||||
import PackageDescription
|
||||
import CompilerPluginSupport
|
||||
|
||||
// Availability Macros
|
||||
|
||||
let availabilityMacros: [SwiftSetting] = [
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.0:macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0"
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.1:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.2:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
),
|
||||
.enableExperimentalFeature(
|
||||
"AvailabilityMacro=AsyncAlgorithms 1.3:macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0"
|
||||
),
|
||||
]
|
||||
|
||||
let package = Package(
|
||||
name: "swift-async-algorithms",
|
||||
products: [
|
||||
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"])
|
||||
],
|
||||
targets: [
|
||||
.target(
|
||||
name: "AsyncAlgorithms",
|
||||
dependencies: [
|
||||
.product(name: "OrderedCollections", package: "swift-collections"),
|
||||
.product(name: "DequeModule", package: "swift-collections"),
|
||||
],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
.testTarget(
|
||||
name: "AsyncAlgorithmsTests",
|
||||
dependencies: [
|
||||
.target(name: "AsyncAlgorithms"),
|
||||
.target(
|
||||
name: "AsyncSequenceValidation",
|
||||
condition: .when(platforms: [
|
||||
.macOS,
|
||||
.iOS,
|
||||
.tvOS,
|
||||
.watchOS,
|
||||
.visionOS,
|
||||
.macCatalyst,
|
||||
.android,
|
||||
.linux,
|
||||
.openbsd,
|
||||
.wasi,
|
||||
])
|
||||
),
|
||||
.target(
|
||||
name: "AsyncAlgorithms_XCTest",
|
||||
condition: .when(platforms: [
|
||||
.macOS,
|
||||
.iOS,
|
||||
.tvOS,
|
||||
.watchOS,
|
||||
.visionOS,
|
||||
.macCatalyst,
|
||||
.android,
|
||||
.linux,
|
||||
.openbsd,
|
||||
.wasi,
|
||||
])
|
||||
),
|
||||
],
|
||||
swiftSettings: availabilityMacros + [
|
||||
.enableExperimentalFeature("StrictConcurrency=complete")
|
||||
]
|
||||
),
|
||||
]
|
||||
)
|
||||
|
||||
if Context.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
|
||||
package.dependencies += [
|
||||
.package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0")
|
||||
]
|
||||
} else {
|
||||
package.dependencies += [
|
||||
.package(path: "../swift-collections")
|
||||
]
|
||||
}
|
||||
@@ -14,64 +14,60 @@ This package has three main goals:
|
||||
|
||||
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/).
|
||||
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/Guides/Chain.md): Concatenates two or more asynchronous sequences with the same element type.
|
||||
- [`combineLatest(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/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/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/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/Guides/Joined.md): Concatenated elements of an asynchronous sequence of asynchronous sequences, inserting the given separator between each element.
|
||||
- [`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/Guides/Lazy.md): Create an asynchronous sequence composed from a synchronous sequence.
|
||||
- [`AsyncChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics.
|
||||
- [`AsyncThrowingChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics that can emit failures.
|
||||
- [`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/Guides/BufferedBytes.md): A highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
|
||||
- [`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
|
||||
- [`chunks(...)` and `chunked(...)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Chunked.md): Collect values into chunks.
|
||||
- [`compacted()`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Compacted.md): Remove nil values from an asynchronous sequence.
|
||||
- [`removeDuplicates()`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/RemoveDuplicates.md): Remove sequentially adjacent duplicate values.
|
||||
- [`interspersed(with:)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Intersperse.md): Place a value between every two elements of an asynchronous sequence.
|
||||
- [`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/Guides/Debounce.md): Emit values after a quiessence period has been reached.
|
||||
- [`throttle(for:clock:reducing:)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Throttle.md): Ensure a minimum interval has elapsed between events.
|
||||
- [`AsyncTimerSequence`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Timer.md): Emit the value of now at a given interval repeatedly.
|
||||
- [`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/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/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/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/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/Guides/Collections.md): Creates a new set from an asynchronous sequence of items.
|
||||
|
||||
|
||||
#### Task management
|
||||
|
||||
- [`Task.select(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Select.md): Determine the first task to complete of a sequence of tasks.
|
||||
- [`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/Guides/Effects.md).
|
||||
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 Algorithms as a Dependency
|
||||
## 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"),
|
||||
.package(url: "https://github.com/apple/swift-async-algorithms", from: "1.0.0"),
|
||||
```
|
||||
|
||||
Include `"AsyncAlgorithms"` as a dependency for your executable target:
|
||||
@@ -86,18 +82,15 @@ 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. Open the `swift-async-algorithms` package directory in Xcode
|
||||
2. Build or Test in Xcode as normal
|
||||
|
||||
### Building/Testing Using Swift Package Manager
|
||||
|
||||
1. In the `swift-async-algorithms` directory run `swift build` or `swift test` accordingly
|
||||
1. In the `swift-async-algorithms` directory run `swift build` or `swift test` accordingly
|
||||
|
||||
### Building/Testing on Linux
|
||||
|
||||
1. Download the most recent toolchain for your Linux distribution
|
||||
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
|
||||
|
||||
@@ -105,8 +98,6 @@ Finally, add `import AsyncAlgorithms` to your source code.
|
||||
|
||||
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.
|
||||
|
||||
Before the version 1.0 the `swift-async-algorithms` package will not be source or ABI stable. Particularly the shims associated with `Clock`, `Instant` and `Duration` are present just to provide backwards compatability to older toolchains. As soon as this is available widely the shims will be removed; which will be an ABI breaking change.
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
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`.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self> {
|
||||
AsyncAdjacentPairsSequence(self)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that iterates over the adjacent pairs of the original
|
||||
/// `AsyncSequence`.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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())
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncAdjacentPairsSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncAdjacentPairsSequence.Iterator: Sendable {}
|
||||
@@ -0,0 +1,36 @@
|
||||
# ``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:Share>
|
||||
- <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/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/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).
|
||||
+3
-3
@@ -1,10 +1,10 @@
|
||||
# AsyncBufferedByteIterator
|
||||
|
||||
Provides a highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
|
||||
|
||||
[[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
|
||||
@@ -17,7 +17,7 @@ struct AsyncBytes: AsyncSequence {
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
||||
return BufferedAsyncByteIterator(capacity: 16384) { buffer in
|
||||
return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
||||
// This runs once every 16384 invocations of next()
|
||||
return try await handle.read(into: buffer)
|
||||
}
|
||||
@@ -1,5 +1,7 @@
|
||||
# Chain
|
||||
|
||||
Chains two or more asynchronous sequences together sequentially.
|
||||
|
||||
[[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)]
|
||||
|
||||
@@ -9,8 +11,8 @@ This operation is available for all `AsyncSequence` types who share the same `El
|
||||
|
||||
```swift
|
||||
let preamble = [
|
||||
"// Some header to add as a preamble"
|
||||
"//"
|
||||
"// Some header to add as a preamble",
|
||||
"//",
|
||||
""
|
||||
].async
|
||||
let lines = chain(preamble, URL(fileURLWithPath: "/tmp/Sample.swift").lines)
|
||||
@@ -60,7 +62,7 @@ extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Send
|
||||
|
||||
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 conform.
|
||||
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.
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
* 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) |
|
||||
[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)
|
||||
]
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
## 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, or finish transmitted, will await the consumption of that value or event 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.
|
||||
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
|
||||
|
||||
@@ -31,7 +31,7 @@ public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
|
||||
public init(element elementType: Element.Type = Element.self)
|
||||
|
||||
public func send(_ element: Element) async
|
||||
public func finish() async
|
||||
public func finish()
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
@@ -44,14 +44,14 @@ public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: Asyn
|
||||
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) async where Failure == Error
|
||||
public func finish() 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. The back pressure applied by `send(_:)`, `fail(_:)` and `finish()` via the suspension/resume ensure that the production of values does not exceed the consumption of values from iteration. Each of these methods suspend after enqueuing the event and are resumed when the next call to `next()` on the `Iterator` is made.
|
||||
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>()
|
||||
@@ -59,7 +59,7 @@ Task {
|
||||
while let resultOfLongCalculation = doLongCalculations() {
|
||||
await channel.send(resultOfLongCalculation)
|
||||
}
|
||||
await channel.finish()
|
||||
channel.finish()
|
||||
}
|
||||
|
||||
for await calculationResult in channel {
|
||||
@@ -213,7 +213,7 @@ If both count and signal are specified, the chunking asynchronous sequence emits
|
||||
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)
|
||||
let packets = bytes.chunks(ofCount: 1024, or: .repeating(every: .seconds(1)), into: Data.self)
|
||||
for try await packet in packets {
|
||||
write(packet)
|
||||
}
|
||||
+2
-2
@@ -7,7 +7,7 @@
|
||||
[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/TestRangeReplacableCollection.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),
|
||||
]
|
||||
|
||||
@@ -22,7 +22,7 @@ This type of functionality can be useful for examples and testing, and also for
|
||||
|
||||
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 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.
|
||||
`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 {
|
||||
+6
-6
@@ -1,10 +1,10 @@
|
||||
# Combine Latest
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCombineLatest2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/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.
|
||||
|
||||
[[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)]
|
||||
|
||||
```swift
|
||||
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
|
||||
@@ -64,7 +64,7 @@ public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequ
|
||||
|
||||
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 elemnts they produce must all be `Sendable`.
|
||||
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.
|
||||
|
||||
@@ -72,12 +72,12 @@ The throwing behavior of `AsyncCombineLatestSequence` is that if any of the base
|
||||
|
||||
### 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 precident 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.
|
||||
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 combinining Observables.
|
||||
**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.
|
||||
+1
-1
@@ -9,7 +9,7 @@
|
||||
|
||||
## 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 efficeintly for both execution performance as well as API efficiency of typing.
|
||||
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
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncDebounceSequence.swift) |
|
||||
[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)
|
||||
]
|
||||
|
||||
+35
-30
@@ -1,58 +1,63 @@
|
||||
| Type | Throws | Sendablity |
|
||||
# Effects
|
||||
|
||||
Lists the effects of all async algorithms.
|
||||
|
||||
| Type | Throws | Sendability |
|
||||
|-----------------------------------------------------|--------------|-------------|
|
||||
| `AsyncBufferedByteIterator` | throws | Sendable |
|
||||
| `AsyncAdjacentPairsSequence` | rethrows | Conditional |
|
||||
| `AsyncBufferedByteIterator` | throws | Not Sendable|
|
||||
| `AsyncBufferSequence` | rethrows | Conditional |
|
||||
| `AsyncBufferSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncBufferSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChain2Sequence` | rethrows | Conditional |
|
||||
| `AsyncChain2Sequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncChain2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChain3Sequence` | rethrows | Conditional |
|
||||
| `AsyncChain3Sequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncChain3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChannel` | non-throwing | Sendable |
|
||||
| `AsyncChannel.Iterator` | non-throwing | Sendable |
|
||||
| `AsyncChannel.Iterator` | non-throwing | Not Sendable|
|
||||
| `AsyncChunkedByGroupSequence` | rethrows | Conditional |
|
||||
| `AsyncChunkedByGroupSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncChunkedByGroupSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunkedOnProjectionSequence` | rethrows | Conditional |
|
||||
| `AsyncChunkedOnProjectionSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncChunkedOnProjectionSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunksOfCountOrSignalSequence` | rethrows | Sendable |
|
||||
| `AsyncChunksOfCountOrSignalSequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncChunksOfCountOrSignalSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncChunksOfCountSequence` | rethrows | Conditional |
|
||||
| `AsyncChunksOfCountSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncChunksOfCountSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCombineLatest2Sequence` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest2Sequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCombineLatest3Sequence` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest3Sequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncCombineLatest3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncCompactedSequence` | rethrows | Conditional |
|
||||
| `AsyncCompactedSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncCompactedSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncDebounceSequence` | rethrows | Sendable |
|
||||
| `AsyncDebounceSequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncDebounceSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncExclusiveReductionsSequence` | rethrows | Conditional |
|
||||
| `AsyncExclusiveReductionsSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncExclusiveReductionsSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncInclusiveReductionsSequence` | rethrows | Conditional |
|
||||
| `AsyncInclusiveReductionsSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncInclusiveReductionsSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncInterspersedSequence` | rethrows | Conditional |
|
||||
| `AsyncInterspersedSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncInterspersedSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncJoinedSequence` | rethrows | Conditional |
|
||||
| `AsyncJoinedSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncLazySequence` | non-throwing | Conditional |
|
||||
| `AsyncLazySequence.Iterator` | non-throwing | 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 | Sendable |
|
||||
| `AsyncMerge2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncMerge3Sequence` | rethrows | Sendable |
|
||||
| `AsyncMerge3Sequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncMerge3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncRemoveDuplicatesSequence` | rethrows | Conditional |
|
||||
| `AsyncRemoveDuplicatesSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncRemoveDuplicatesSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncThrottleSequence` | rethrows | Conditional |
|
||||
| `AsyncThrottleSequence.Iterator` | rethrows | Conditional |
|
||||
| `AsyncThrottleSequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncThrowingChannel` | throws | Sendable |
|
||||
| `AsyncThrowingChannel.Iterator` | throws | Sendable |
|
||||
| `AsyncThrowingChannel.Iterator` | throws | Not Sendable|
|
||||
| `AsyncThrowingExclusiveReductionsSequence` | throws | Conditional |
|
||||
| `AsyncThrowingExclusiveReductionsSequence.Iterator` | throws | Conditional |
|
||||
| `AsyncThrowingExclusiveReductionsSequence.Iterator` | throws | Not Sendable|
|
||||
| `AsyncThrowingInclusiveReductionsSequence` | throws | Conditional |
|
||||
| `AsyncThrowingInclusiveReductionsSequence.Iterator` | throws | Conditional |
|
||||
| `AsyncThrowingInclusiveReductionsSequence.Iterator` | throws | Not Sendable|
|
||||
| `AsyncTimerSequence` | non-throwing | Sendable |
|
||||
| `AsyncTimerSequence.Iterator` | non-throwing | Sendable |
|
||||
| `AsyncTimerSequence.Iterator` | non-throwing | Not Sendable|
|
||||
| `AsyncZip2Sequence` | rethrows | Sendable |
|
||||
| `AsyncZip2Sequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncZip2Sequence.Iterator` | rethrows | Not Sendable|
|
||||
| `AsyncZip3Sequence` | rethrows | Sendable |
|
||||
| `AsyncZip3Sequence.Iterator` | rethrows | Sendable |
|
||||
| `AsyncZip3Sequence.Iterator` | rethrows | Not Sendable|
|
||||
@@ -0,0 +1,139 @@
|
||||
# FlatMapLatest
|
||||
|
||||
* Author(s): [Peter Friese](https://github.com/peterfriese)
|
||||
|
||||
Transforms elements into asynchronous sequences, emitting elements from only the most recent inner sequence.
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)]
|
||||
|
||||
```swift
|
||||
let searchQuery = AsyncStream<String> { continuation in
|
||||
// User types into search field
|
||||
continuation.yield("swi")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("swift")
|
||||
try? await Task.sleep(for: .milliseconds(100))
|
||||
continuation.yield("swift async")
|
||||
continuation.finish()
|
||||
}
|
||||
|
||||
let searchResults = searchQuery.flatMapLatest { query in
|
||||
performSearch(query) // Returns AsyncSequence<SearchResult>
|
||||
}
|
||||
|
||||
for try await result in searchResults {
|
||||
print(result) // Only shows results from "swift async"
|
||||
}
|
||||
```
|
||||
|
||||
## Introduction
|
||||
|
||||
When transforming elements of an asynchronous sequence into new asynchronous sequences, you often want to abandon previous sequences when new data arrives. This is particularly useful for scenarios like search-as-you-type, where each keystroke triggers a new search request and you only care about results from the most recent query.
|
||||
|
||||
The `flatMapLatest` operator solves this by cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
The `flatMapLatest` algorithm transforms each element from the base `AsyncSequence` into a new inner `AsyncSequence` using the provided `transform` closure. When a new element is produced by the base sequence, iteration on the current inner sequence is cancelled, and iteration begins on the newly created sequence.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Self: Sendable {
|
||||
public func flatMapLatest<T: AsyncSequence & Sendable>(
|
||||
_ transform: @escaping @Sendable (Element) -> T
|
||||
) -> AsyncFlatMapLatestSequence<Self, T>
|
||||
}
|
||||
```
|
||||
|
||||
This creates a concise way to express switching behavior:
|
||||
|
||||
```swift
|
||||
userInput.flatMapLatest { input in
|
||||
fetchDataFromNetwork(input)
|
||||
}
|
||||
```
|
||||
|
||||
In this case, each new user input cancels any ongoing network request and starts a fresh one, ensuring only the latest data is delivered.
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The type that implements the algorithm emits elements from the inner sequences. It throws when either the base type or any inner sequence throws.
|
||||
|
||||
```swift
|
||||
public struct AsyncFlatMapLatestSequence<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: AsyncSequence, Sendable
|
||||
where Base.Element: Sendable, Inner.Element: Sendable {
|
||||
public typealias Element = Inner.Element
|
||||
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
public func next() async throws -> Element?
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator
|
||||
}
|
||||
```
|
||||
|
||||
The implementation uses a state machine to ensure thread-safe operation and generation tracking to prevent stale values from cancelled sequences.
|
||||
|
||||
### Behavior
|
||||
|
||||
- **Switching**: When a new element arrives from the base sequence, the current inner sequence is cancelled immediately
|
||||
- **Completion**: The sequence completes when the base sequence finishes and the final inner sequence completes
|
||||
- **Error Handling**: Errors from either the base or inner sequences are propagated immediately
|
||||
- **Cancellation**: Cancelling iteration cancels both the base and current inner sequence
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Search as You Type
|
||||
|
||||
```swift
|
||||
let searchField = AsyncStream<String> { continuation in
|
||||
// Emit search queries as user types
|
||||
continuation.yield("s")
|
||||
continuation.yield("sw")
|
||||
continuation.yield("swift")
|
||||
}
|
||||
|
||||
let results = searchField.flatMapLatest { query in
|
||||
searchAPI(for: query)
|
||||
}
|
||||
```
|
||||
|
||||
Only the results for "swift" will be emitted, as earlier queries are cancelled.
|
||||
|
||||
### Location-Based Data
|
||||
|
||||
```swift
|
||||
let locationUpdates = CLLocationManager.shared.locationUpdates
|
||||
|
||||
let nearbyPlaces = locationUpdates.flatMapLatest { location in
|
||||
fetchNearbyPlaces(at: location)
|
||||
}
|
||||
```
|
||||
|
||||
Each location update triggers a new search, cancelling any ongoing requests for previous locations.
|
||||
|
||||
### Dynamic Configuration
|
||||
|
||||
```swift
|
||||
let settings = userSettingsStream
|
||||
|
||||
let data = settings.flatMapLatest { config in
|
||||
loadData(with: config)
|
||||
}
|
||||
```
|
||||
|
||||
When settings change, data loading is restarted with the new configuration.
|
||||
|
||||
## Comparison with Other Operators
|
||||
|
||||
**`map`**: Transforms elements synchronously without producing sequences.
|
||||
|
||||
**`flatMap`** (if it existed): Would emit elements from all inner sequences concurrently, not cancelling previous ones.
|
||||
|
||||
**`switchToLatest`** (Combine): Equivalent operator in Combine framework - `flatMapLatest` is the `AsyncSequence` equivalent.
|
||||
|
||||
## Comparison with Other Libraries
|
||||
|
||||
**ReactiveX** ReactiveX has an [API definition of switchMap](https://reactivex.io/documentation/operators/flatmap.html) which performs the same operation for Observables.
|
||||
|
||||
**Combine** Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which flattens a publisher of publishers by subscribing to the most recent one.
|
||||
+3
-3
@@ -1,10 +1,10 @@
|
||||
# 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.
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Interspersed/AsyncInterspersedSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/Interspersed/TestInterspersed.swift)]
|
||||
|
||||
```swift
|
||||
let numbers = [1, 2, 3].async.interspersed(with: 0)
|
||||
for await number in numbers {
|
||||
@@ -108,7 +108,7 @@ extension AsyncJoinedBySeparatorSequence.Iterator: 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 sepaerator 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.
|
||||
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
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
# AsyncLazySequence
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncLazySequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)]
|
||||
|
||||
Converts a non-asynchronous sequence into an asynchronous one.
|
||||
# AsyncSyncSequence
|
||||
|
||||
This operation is available for all `Sequence` types.
|
||||
|
||||
[[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)]
|
||||
|
||||
```swift
|
||||
let numbers = [1, 2, 3, 4].async
|
||||
let characters = "abcde".async
|
||||
@@ -17,19 +15,19 @@ to combine with other `AsyncSequence` types to provide well known sources of dat
|
||||
|
||||
## Detailed Design
|
||||
|
||||
The `.async` property returns an `AsyncLazySequence` that is generic upon the base `Sequence` it was constructed from.
|
||||
The `.async` property returns an `AsyncSyncSequence` that is generic upon the base `Sequence` it was constructed from.
|
||||
|
||||
```swift
|
||||
extension Sequence {
|
||||
public var async: AsyncLazySequence<Self> { get }
|
||||
public var async: AsyncSyncSequence<Self> { get }
|
||||
}
|
||||
|
||||
public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
|
||||
public struct AsyncSyncSequence<Base: Sequence>: AsyncSequence {
|
||||
...
|
||||
}
|
||||
|
||||
extension AsyncLazySequence: Sendable where Base: Sendable { }
|
||||
extension AsyncLazySequence.Iterator: Sendable where Base.Iterator: Sendable { }
|
||||
extension AsyncSyncSequence: Sendable where Base: Sendable { }
|
||||
extension AsyncSyncSequence.Iterator: Sendable where Base.Iterator: Sendable { }
|
||||
```
|
||||
|
||||
### Naming
|
||||
@@ -1,15 +1,15 @@
|
||||
# Merge
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Asyncmerge2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/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("http://www.example.com/ticker?symbol=AAPL").lines.map { "AAPL: " + $0 }
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines.map { "^IXIC: " + $0 }
|
||||
[[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)]
|
||||
|
||||
for try await ticker = merge(appleFeed, nasdaqFeed) {
|
||||
```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)
|
||||
}
|
||||
```
|
||||
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,194 @@
|
||||
# Share
|
||||
|
||||
* Author(s): [Philippe Hausler](https://github.com/phausler)
|
||||
|
||||
[
|
||||
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncShareSequence.swift) |
|
||||
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestShare.swift)
|
||||
]
|
||||
|
||||
## Introduction
|
||||
|
||||
Many of the AsyncSequence adopting types only permit a one singular consumption. However there are many times that the same produced values are useful in more than one place. Out of that mechanism there are a few approaches to share, distribute, and broadcast those values. This proposal will focus on one concept; sharing. Sharing is where each consumption independently can make forward progress and get the same values but do not replay from the beginning of time.
|
||||
|
||||
## Motivation
|
||||
|
||||
There are many potential usages for the sharing concept of AsyncSequences.
|
||||
|
||||
One such example is the case where a source of data as an asynchronous sequence needs to be consumed by updating UI, logging, and additionally a network connection. This particular case does not matter on which uses but instead that those uses are independent of each other. It would not be expected for networking to block or delay the updates to UI, nor should logging. This example case also illustrates that the isolation of each side might be different and that some of the sides may not tolerate coalescing or dropping values.
|
||||
|
||||
There are many other use cases that have been requested for this family of algorithms. Since the release of AsyncAlgorithms it has perhaps been the most popularly requested set of behaviors as additions to the package.
|
||||
|
||||
## Proposed solution
|
||||
|
||||
AsyncAlgorithms will introduce a new extension function on AsyncSequence that will provide a shareable asynchronous sequence that will produce the same values upon iteration from multiple instances of it's AsyncIterator. Those iterations can take place in multiple isolations.
|
||||
|
||||
When values from a differing isolation cannot be coalesced, the two options available are either awaiting (an exertion of back-pressure across the sequences) or buffering (an internal back-pressure to a buffer). Replaying the values from the beginning of the creation of the sequence is a distinctly different behavior that should be considered a different use case. This then leaves the behavioral characteristic of this particular operation of share as; sharing a buffer of values started from the initialization of a new iteration of the sequence. Control over that buffer should then have options to determine the behavior, similar to how AsyncStream allows that control. It should have options to be unbounded, buffering the oldest count of elements, or buffering the newest count of elements.
|
||||
|
||||
It is critical to identify that this is one algorithm in the family of algorithms for sharing values. It should not attempt to solve all behavioral requirements but instead serve a common set of them that make cohesive sense together. This proposal is not mutually exclusive to the other algorithms in the sharing family.
|
||||
|
||||
## Detailed design
|
||||
|
||||
A new extension will be added to return a `Sendable` `AsyncSequence`. This extension will take a buffering policy to identify how the buffer will be handled when iterations do not consume at the same rate.
|
||||
|
||||
The `Sendable` annotation identifies to the developer that this sequence can be shared and stored in an existental `any`.
|
||||
|
||||
```swift
|
||||
extension AsyncSequence where Element: Sendable {
|
||||
public func share(
|
||||
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
|
||||
) -> some AsyncSequence<Element, Failure> & Sendable
|
||||
}
|
||||
```
|
||||
|
||||
The buffer internally to the share algorithm will only extend back to the furthest element available but there will only be a singular buffer shared across all iterators. This ensures that with the application of the buffering policy the storage size is as minimal as possible while still allowing all iterations to avoid dropping values and keeping the memory usage in check. The signature reuses the existing `AsyncBufferSequencePolicy` type to specify the behavior around buffering either responding to how it should limit emitting to the buffer or what should happen when the buffer is exceeded.
|
||||
|
||||
## Runtime Behavior
|
||||
|
||||
The runtime behaviors fall into a few categories; ordering, iteration isolation, cancellation, and lifetimes. To understand the behaviors there are a terms useful to define. Each creation of the AsyncIterator of the sequence and invocation of next will be referred to a side of the share iteration. The back pressure to the system to fetch a new element or termination is referred to as demand. The limit which is the pending gate for awaiting until the buffer has been serviced used for the `AsyncBufferSequencePolicy.bounded(_ : Int)` policy. The last special definition is that of the extent which is specifically in this case the lifetime of the asynchronous sequence itself.
|
||||
|
||||
When the underlying type backing the share algorithm is constructed a new extent is created; this is used for tracking the reference lifetime under the hood and is used to both house the iteration but also to identify the point at which no more sides can be constructed. When no more sides can be constructed and no sides are left to iterate then the backing iteration is canceled. This prevents any un-referenced task backing the iteration to not be leaked by the algorith itself.
|
||||
|
||||
That construction then creates an initial shared state and buffer. No task is started initially; it is only upon the first demand that the task backing the iteration is started; this means on the first call to next a task is spun up servicing all potential sides. The order of which the sides are serviced is not specified and cannot be relied upon, however the order of delivery within a side is always guarenteed to be ordered. The singular task servicing the iteration will be the only place holding any sort of iterator from the base `AsyncSequence`; so that iterator is isolated and not sent from one isolation to another. That iteration first awaits any limit availability and then awaits for a demand given by a side. After-which it then awaits an element or terminal event from the iterator and enqueues the elements to the buffer.
|
||||
|
||||
The buffer itself is only held in one location, each side however has a cursor index into that buffer and when values are consumed it adjusts the indexes accordingly; leaving the buffer usage only as big as the largest deficit. This means that new sides that are started post initial start up will not have a "replay" effect; that is a similar but distinct algorithm and is not addressed by this proposal. Any buffer size sensitive systems that wish to adjust behavior should be aware that specifying a policy is a suggested step. However in common usage similar to other such systems servicing desktop and mobile applications the common behavior is often unbounded. Alternatively desktop or mobile applications will often want `.bounded(1)` since that enforces the slowest consumption to drive the forward progress at most 1 buffered element. All of the use cases have a reasonable default of `.bounded(1)`; mobile, deskop, and server side uses. Leaving this as the default parameter keeps the progressive disclosure of the beahviors - such that the easiest thing to write is correct for all uses, and then more advanced control can be adjusted by passing in a specific policy. This default argument diverges slightly from AsyncStream, but follows a similar behavior to that of Combine's `share`.
|
||||
|
||||
As previously stated, the isolation of the iteration of the upstream/base AsyncSequence is to a detached task, this ensures that individual sides can have independent cancellation. Those cancellations will have the effect of remvoing that side from the shared iteration and cleaning up accordingly (including adjusting the trimming of the internal buffer).
|
||||
|
||||
Representing concurrent access is difficult to express all potential examples but there are a few cases included with this proposal to illustrate some of the behaviors. If a more comprehensive behavioral analysis is needed, it is strongly suggested to try out the pending pull request to identify how specific behaviors work. Please keep in mind that the odering between tasks is not specified, only the order within one side of iteration.
|
||||
|
||||
Practically this all means that a given iteration may be "behind" another and can eventually catch up (provided it is within the buffer limit).
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .unbounded)
|
||||
|
||||
let t1 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 0 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 1", element)
|
||||
}
|
||||
}
|
||||
|
||||
let t2 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 3 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 2", element)
|
||||
}
|
||||
}
|
||||
|
||||
await t1.value
|
||||
await t2.value
|
||||
|
||||
```
|
||||
|
||||
This example will print a possible ordering of the following:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 3
|
||||
Task 2 4
|
||||
Task 1 1
|
||||
Task 1 2
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
```
|
||||
|
||||
The order of the interleaving of the prints are not guaranteed; however the order of the elements per iteration is. Likewise in this buffering case it is guaranteed that all values are represented in the output.
|
||||
|
||||
If the creation were instead altered to the following:
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingLatest(2))
|
||||
```
|
||||
|
||||
The output would print the possible ordering of:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 4
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
```
|
||||
|
||||
Some values are dropped due to the buffering policy, but eventually they reach consistency. Which similarly works for the following:
|
||||
|
||||
```
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bufferingOldest(2))
|
||||
```
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 2 2
|
||||
Task 1 0
|
||||
Task 2 4
|
||||
Task 1 1
|
||||
Task 1 2
|
||||
```
|
||||
|
||||
However in this particular case the newest values are the dropped elements.
|
||||
|
||||
The `.bounded(N)` policy enforces consumption to prevent any side from being beyond a given amount away from other sides' consumption.
|
||||
|
||||
```swift
|
||||
let exampleSource = [0, 1, 2, 3, 4].async.share(bufferingPolicy: .bounded(1))
|
||||
|
||||
let t1 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 0 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 1", element)
|
||||
}
|
||||
}
|
||||
|
||||
let t2 = Task {
|
||||
for await element in exampleSource {
|
||||
if element == 3 {
|
||||
try? await Task.sleep(for: .seconds(1))
|
||||
}
|
||||
print("Task 2", element)
|
||||
}
|
||||
}
|
||||
|
||||
await t1.value
|
||||
await t2.value
|
||||
```
|
||||
|
||||
Will have a potential ordering output of:
|
||||
|
||||
```
|
||||
Task 2 0
|
||||
Task 2 1
|
||||
Task 1 0
|
||||
Task 1 1
|
||||
Task 2 2
|
||||
Task 1 2
|
||||
Task 1 3
|
||||
Task 1 4
|
||||
Task 2 3
|
||||
Task 2 4
|
||||
```
|
||||
|
||||
In that example output Task 2 can get element 0 and 1 but must await until task 1 has caught up to the specified buffering. This limit means that no additional iteration (and no values are then dropped) is made until the buffer count is below the specified value.
|
||||
|
||||
|
||||
## Effect on API resilience
|
||||
|
||||
This is an additive API and no existing systems are changed, however it will introduce a few new types that will need to be maintained as ABI interfaces. Since the intent of this is to provide a mechanism to store AsyncSequences to a shared context the type must be exposed as ABI (for type sizing).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
It has been considered that the buffering policy would be nested inside the `AsyncShareSequence` type. However since this seems to be something that will be useful for other types it makes sense to use an existing type from a top level type. However if it is determined that a general form of a buffering policy would require additional behaviors this might be a debatable placement to move back to an interior type similar to AsyncStream.
|
||||
|
||||
|
||||
@@ -77,6 +77,8 @@ extension AsyncThrottleSequence.Iterator: 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`.
|
||||
@@ -9,7 +9,7 @@
|
||||
|
||||
## 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 delimter 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.
|
||||
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
|
||||
|
||||
@@ -42,7 +42,7 @@ extension AsyncTimerSequence: Sendable { }
|
||||
extension AsyncTimerSequence.Iterator: Sendable { }
|
||||
```
|
||||
|
||||
Since all the types comprising `AsyncTimerSequence` and it's `Iterator` are `Sendable` these types are also `Sendable.
|
||||
Since all the types comprising `AsyncTimerSequence` are `Sendable` these types are also `Sendable`.
|
||||
|
||||
## Credits/Inspiration
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
# Zip
|
||||
|
||||
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncZip2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/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("http://www.example.com/ticker?symbol=AAPL").lines
|
||||
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
|
||||
[[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)]
|
||||
|
||||
for try await (apple, nasdaq) = zip(appleFeed, nasdaqFeed) {
|
||||
```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)")
|
||||
}
|
||||
```
|
||||
@@ -80,6 +80,6 @@ It is common in some libraries to have a `ZipMap` or some other combination of `
|
||||
|
||||
**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 combinining Observables.
|
||||
**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.
|
||||
@@ -1,309 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
actor AsyncBufferState<Input: Sendable, Output: Sendable> {
|
||||
enum TerminationState: Sendable, CustomStringConvertible {
|
||||
case running
|
||||
case baseFailure(Error) // An error from the base sequence has occurred. We need to process any buffered items before throwing the error. We can rely on it not emitting any more items.
|
||||
case baseTermination
|
||||
case terminal
|
||||
|
||||
var description: String {
|
||||
switch self {
|
||||
case .running: return "running"
|
||||
case .baseFailure: return "base failure"
|
||||
case .baseTermination: return "base termination"
|
||||
case .terminal: return "terminal"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
var pending = [UnsafeContinuation<Result<Output?, Error>, Never>]()
|
||||
var terminationState = TerminationState.running
|
||||
|
||||
init() { }
|
||||
|
||||
func drain<Buffer: AsyncBuffer>(buffer: Buffer) async where Buffer.Input == Input, Buffer.Output == Output {
|
||||
guard pending.count > 0 else {
|
||||
return
|
||||
}
|
||||
|
||||
do {
|
||||
if let value = try await buffer.pop() {
|
||||
pending.removeFirst().resume(returning: .success(value))
|
||||
} else {
|
||||
switch terminationState {
|
||||
case .running:
|
||||
// There's no value to report, because it was probably grabbed by next() before we could grab it. The pending continuation was either resumed by next() directly, or will be by a future enqueued value or base termination/failure.
|
||||
break
|
||||
case .baseFailure(let error):
|
||||
// Now that there are no more items in the buffer, we can finally report the base sequence's error and enter terminal state.
|
||||
pending.removeFirst().resume(returning: .failure(error))
|
||||
self.terminate()
|
||||
case .terminal, .baseTermination:
|
||||
self.terminate()
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Errors thrown by the buffer immediately terminate the sequence.
|
||||
pending.removeFirst().resume(returning: .failure(error))
|
||||
self.terminate()
|
||||
}
|
||||
}
|
||||
|
||||
func enqueue<Buffer: AsyncBuffer>(_ item: Input, buffer: Buffer) async where Buffer.Input == Input, Buffer.Output == Output {
|
||||
await buffer.push(item)
|
||||
await drain(buffer: buffer)
|
||||
}
|
||||
|
||||
func fail<Buffer: AsyncBuffer>(_ error: Error, buffer: Buffer) async where Buffer.Input == Input, Buffer.Output == Output {
|
||||
terminationState = .baseFailure(error)
|
||||
await drain(buffer: buffer)
|
||||
}
|
||||
|
||||
func finish<Buffer: AsyncBuffer>(buffer: Buffer) async where Buffer.Input == Input, Buffer.Output == Output {
|
||||
if case .running = terminationState {
|
||||
terminationState = .baseTermination
|
||||
}
|
||||
await drain(buffer: buffer)
|
||||
}
|
||||
|
||||
func terminate() {
|
||||
terminationState = .terminal
|
||||
let oldPending = pending
|
||||
pending = []
|
||||
for continuation in oldPending {
|
||||
continuation.resume(returning: .success(nil))
|
||||
}
|
||||
}
|
||||
|
||||
func next<Buffer: AsyncBuffer>(buffer: Buffer) async throws -> Buffer.Output? where Buffer.Input == Input, Buffer.Output == Output {
|
||||
if case .terminal = terminationState {
|
||||
return nil
|
||||
}
|
||||
|
||||
do {
|
||||
while let value = try await buffer.pop() {
|
||||
if let continuation = pending.first {
|
||||
pending.removeFirst()
|
||||
continuation.resume(returning: .success(value))
|
||||
} else {
|
||||
return value
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
// Errors thrown by the buffer immediately terminate the sequence.
|
||||
self.terminate()
|
||||
throw error
|
||||
}
|
||||
|
||||
switch terminationState {
|
||||
case .running:
|
||||
break
|
||||
case .baseFailure(let error):
|
||||
self.terminate()
|
||||
throw error
|
||||
case .baseTermination, .terminal:
|
||||
self.terminate()
|
||||
return nil
|
||||
}
|
||||
|
||||
let result: Result<Output?, Error> = await withUnsafeContinuation { continuation in
|
||||
pending.append(continuation)
|
||||
}
|
||||
return try result._rethrowGet()
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous buffer storage actor protocol used for buffering
|
||||
/// elements to an `AsyncBufferSequence`.
|
||||
@rethrows
|
||||
public protocol AsyncBuffer: Actor {
|
||||
associatedtype Input: Sendable
|
||||
associatedtype Output: Sendable
|
||||
|
||||
/// Push an element to enqueue to the buffer
|
||||
func push(_ element: Input) async
|
||||
|
||||
/// Pop an element from the buffer.
|
||||
///
|
||||
/// Implementors of `pop()` may throw. In cases where types
|
||||
/// throw from this function, that throwing behavior contributes to
|
||||
/// the rethrowing characteristics of `AsyncBufferSequence`.
|
||||
func pop() async throws -> Output?
|
||||
}
|
||||
|
||||
/// A buffer that limits pushed items by a certain count.
|
||||
public actor AsyncLimitBuffer<Element: Sendable>: AsyncBuffer {
|
||||
/// A policy for buffering elements to an `AsyncLimitBuffer`
|
||||
public enum Policy: Sendable {
|
||||
/// A policy for no bounding limit of pushed elements.
|
||||
case unbounded
|
||||
/// A policy for limiting to a specific number of oldest values.
|
||||
case bufferingOldest(Int)
|
||||
/// A policy for limiting to a specific number of newest values.
|
||||
case bufferingNewest(Int)
|
||||
}
|
||||
|
||||
var buffer = [Element]()
|
||||
let policy: Policy
|
||||
|
||||
init(policy: Policy) {
|
||||
// limits should always be greater than 0 items
|
||||
switch policy {
|
||||
case .bufferingNewest(let limit):
|
||||
precondition(limit > 0)
|
||||
case .bufferingOldest(let limit):
|
||||
precondition(limit > 0)
|
||||
default: break
|
||||
}
|
||||
self.policy = policy
|
||||
}
|
||||
|
||||
/// Push an element to enqueue to the buffer.
|
||||
public func push(_ element: Element) async {
|
||||
switch policy {
|
||||
case .unbounded:
|
||||
buffer.append(element)
|
||||
case .bufferingOldest(let limit):
|
||||
if buffer.count < limit {
|
||||
buffer.append(element)
|
||||
}
|
||||
case .bufferingNewest(let limit):
|
||||
if buffer.count < limit {
|
||||
// there is space available
|
||||
buffer.append(element)
|
||||
} else {
|
||||
// no space is available and this should make some room
|
||||
buffer.removeFirst()
|
||||
buffer.append(element)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Pop an element from the buffer.
|
||||
public func pop() async -> Element? {
|
||||
guard buffer.count > 0 else {
|
||||
return nil
|
||||
}
|
||||
return buffer.removeFirst()
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncSequence where Element: Sendable {
|
||||
/// Creates an asynchronous sequence that buffers elements using a buffer created from a supplied closure.
|
||||
///
|
||||
/// Use the `buffer(_:)` method to account for `AsyncSequence` types that may produce elements faster
|
||||
/// than they are iterated. The `createBuffer` closure returns a backing buffer for storing elements and dealing with
|
||||
/// behavioral charcteristics of the `buffer(_:)` algorithm.
|
||||
///
|
||||
/// - Parameter createBuffer: A closure that constructs a new `AsyncBuffer` actor to store buffered values.
|
||||
/// - Returns: An asynchronous sequence that buffers elements using the specified `AsyncBuffer`.
|
||||
public func buffer<Buffer: AsyncBuffer>(_ createBuffer: @Sendable @escaping () -> Buffer) -> AsyncBufferSequence<Self, Buffer> where Buffer.Input == Element {
|
||||
AsyncBufferSequence(self, createBuffer: createBuffer)
|
||||
}
|
||||
|
||||
/// Creates an asynchronous sequence that buffers elements using a specific policy to limit the number of
|
||||
/// elements that are buffered.
|
||||
///
|
||||
/// - Parameter policy: A limiting policy behavior on the buffering behavior of the `AsyncBufferSequence`
|
||||
/// - Returns: An asynchronous sequence that buffers elements up to a given limit.
|
||||
public func buffer(policy limit: AsyncLimitBuffer<Element>.Policy) -> AsyncBufferSequence<Self, AsyncLimitBuffer<Element>> {
|
||||
buffer {
|
||||
AsyncLimitBuffer(policy: limit)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that buffers elements utilizing an `AsyncBuffer`.
|
||||
public struct AsyncBufferSequence<Base: AsyncSequence, Buffer: AsyncBuffer> where Base.Element == Buffer.Input, Base.AsyncIterator: Sendable {
|
||||
let base: Base
|
||||
let createBuffer: @Sendable () -> Buffer
|
||||
|
||||
init(_ base: Base, createBuffer: @Sendable @escaping () -> Buffer) {
|
||||
self.base = base
|
||||
self.createBuffer = createBuffer
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncBufferSequence: Sendable where Base: Sendable, Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
extension AsyncBufferSequence.Iterator: Sendable where Base: Sendable, Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
|
||||
extension AsyncBufferSequence: AsyncSequence {
|
||||
public typealias Element = Buffer.Output
|
||||
|
||||
/// The iterator for a `AsyncBufferSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
struct Active {
|
||||
var task: Task<Void, Never>?
|
||||
let buffer: Buffer
|
||||
let state: AsyncBufferState<Buffer.Input, Buffer.Output>
|
||||
|
||||
init(_ iterator: Base.AsyncIterator, buffer: Buffer, state: AsyncBufferState<Buffer.Input, Buffer.Output>) {
|
||||
self.buffer = buffer
|
||||
self.state = state
|
||||
task = Task {
|
||||
var iter = iterator
|
||||
do {
|
||||
while let item = try await iter.next() {
|
||||
await state.enqueue(item, buffer: buffer)
|
||||
}
|
||||
await state.finish(buffer: buffer)
|
||||
} catch {
|
||||
await state.fail(error, buffer: buffer)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func next() async rethrows -> Element? {
|
||||
let result: Result<Element?, Error> = await withTaskCancellationHandler {
|
||||
task?.cancel()
|
||||
} operation: {
|
||||
do {
|
||||
let value = try await state.next(buffer: buffer)
|
||||
return .success(value)
|
||||
} catch {
|
||||
task?.cancel()
|
||||
return .failure(error)
|
||||
}
|
||||
}
|
||||
return try result._rethrowGet()
|
||||
}
|
||||
}
|
||||
|
||||
enum State {
|
||||
case idle(Base.AsyncIterator, @Sendable () -> Buffer)
|
||||
case active(Active)
|
||||
}
|
||||
|
||||
var state: State
|
||||
|
||||
init(_ iterator: Base.AsyncIterator, createBuffer: @Sendable @escaping () -> Buffer) {
|
||||
state = .idle(iterator, createBuffer)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
switch state {
|
||||
case .idle(let iterator, let createBuffer):
|
||||
let bufferState = AsyncBufferState<Base.Element, Buffer.Output>()
|
||||
let buffer = Active(iterator, buffer: createBuffer(), state: bufferState)
|
||||
state = .active(buffer)
|
||||
return try await buffer.next()
|
||||
case .active(let buffer):
|
||||
return try await buffer.next()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), createBuffer: createBuffer)
|
||||
}
|
||||
}
|
||||
@@ -31,7 +31,7 @@
|
||||
/// }
|
||||
///
|
||||
/// public func makeAsyncIterator() -> AsyncBufferedByteIterator {
|
||||
/// return BufferedAsyncByteIterator(capacity: 16384) { buffer in
|
||||
/// return AsyncBufferedByteIterator(capacity: 16384) { buffer in
|
||||
/// // This runs once every 16384 invocations of next()
|
||||
/// return try await handle.read(into: buffer)
|
||||
/// }
|
||||
@@ -39,10 +39,11 @@
|
||||
/// }
|
||||
///
|
||||
///
|
||||
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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:
|
||||
@@ -55,7 +56,7 @@ public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
|
||||
) {
|
||||
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)
|
||||
@@ -64,12 +65,16 @@ public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
|
||||
}
|
||||
}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncBufferedByteIterator: Sendable {}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen @usableFromInline
|
||||
internal struct _AsyncBytesBuffer: @unchecked Sendable {
|
||||
internal struct _AsyncBytesBuffer {
|
||||
@usableFromInline
|
||||
final class Storage: Sendable {
|
||||
final class Storage {
|
||||
fileprivate let buffer: UnsafeMutableRawBufferPointer
|
||||
|
||||
|
||||
init(
|
||||
capacity: Int
|
||||
) {
|
||||
@@ -79,19 +84,19 @@ internal struct _AsyncBytesBuffer: @unchecked Sendable {
|
||||
alignment: MemoryLayout<AnyObject>.alignment
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
deinit {
|
||||
buffer.deallocate()
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline internal var storage: Storage
|
||||
|
||||
@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
|
||||
@@ -102,7 +107,7 @@ internal struct _AsyncBytesBuffer: @unchecked Sendable {
|
||||
nextPointer = UnsafeRawPointer(s.buffer.baseAddress!)
|
||||
endPointer = nextPointer
|
||||
}
|
||||
|
||||
|
||||
@inline(never) @usableFromInline
|
||||
internal mutating func reloadBufferAndNext() async throws -> UInt8? {
|
||||
if finished {
|
||||
@@ -125,7 +130,7 @@ internal struct _AsyncBytesBuffer: @unchecked Sendable {
|
||||
}
|
||||
return try await next()
|
||||
}
|
||||
|
||||
|
||||
@inlinable @inline(__always)
|
||||
internal mutating func next() async throws -> UInt8? {
|
||||
if _fastPath(nextPointer != endPointer) {
|
||||
|
||||
@@ -15,22 +15,27 @@
|
||||
/// - Parameters:
|
||||
/// - s1: The first asynchronous sequence.
|
||||
/// - s2: The second asynchronous sequence.
|
||||
/// - Returns: An asynchonous sequence that iterates first over the elements of `s1`, and
|
||||
/// - Returns: An asynchronous sequence that iterates first over the elements of `s1`, and
|
||||
/// then over the elements of `s2`.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
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>(
|
||||
_ 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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
|
||||
@@ -38,24 +43,26 @@ public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> wh
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChain2Sequence: AsyncSequence {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
|
||||
/// The iterator for a `AsyncChain2Sequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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 {
|
||||
@@ -72,12 +79,16 @@ extension AsyncChain2Sequence: AsyncSequence {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
|
||||
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChain2Sequence.Iterator: Sendable {}
|
||||
@@ -16,25 +16,32 @@
|
||||
/// - s1: The first asynchronous sequence.
|
||||
/// - s2: The second asynchronous sequence.
|
||||
/// - s3: The third asynchronous sequence.
|
||||
/// - Returns: An asynchonous sequence that iterates first over the elements of `s1`, and
|
||||
/// - 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`
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3> {
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
|
||||
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
|
||||
@@ -43,28 +50,30 @@ public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Ba
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChain3Sequence: AsyncSequence {
|
||||
public typealias Element = Base1.Element
|
||||
|
||||
|
||||
/// The iterator for a `AsyncChain3Sequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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 {
|
||||
@@ -87,12 +96,16 @@ extension AsyncChain3Sequence: AsyncSequence {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
|
||||
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChain3Sequence.Iterator: Sendable {}
|
||||
@@ -1,210 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 on 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(_:)` and `finish()` via the suspension/resume ensure that
|
||||
/// the production of values does not exceed the consumption of values from iteration. Each of these
|
||||
/// methods suspends after enqueuing the event and is resumed when the next call to `next()`
|
||||
/// on the `Iterator` is made.
|
||||
public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
|
||||
/// The iterator for a `AsyncChannel` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
let channel: AsyncChannel<Element>
|
||||
var active: Bool = true
|
||||
|
||||
init(_ channel: AsyncChannel<Element>) {
|
||||
self.channel = channel
|
||||
}
|
||||
|
||||
/// Await the next sent element or finish.
|
||||
public mutating func next() async -> Element? {
|
||||
guard active else {
|
||||
return nil
|
||||
}
|
||||
let generation = channel.establish()
|
||||
let value: Element? = await withTaskCancellationHandler { [channel] in
|
||||
channel.cancel(generation)
|
||||
} operation: {
|
||||
await channel.next(generation)
|
||||
}
|
||||
|
||||
if let value = value {
|
||||
return value
|
||||
} else {
|
||||
active = false
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct Awaiting: Hashable {
|
||||
var generation: Int
|
||||
var continuation: UnsafeContinuation<Element?, Never>?
|
||||
let cancelled: Bool
|
||||
|
||||
init(generation: Int, continuation: UnsafeContinuation<Element?, Never>) {
|
||||
self.generation = generation
|
||||
self.continuation = continuation
|
||||
cancelled = false
|
||||
}
|
||||
|
||||
init(placeholder generation: Int) {
|
||||
self.generation = generation
|
||||
self.continuation = nil
|
||||
cancelled = false
|
||||
}
|
||||
|
||||
init(cancelled generation: Int) {
|
||||
self.generation = generation
|
||||
self.continuation = nil
|
||||
cancelled = true
|
||||
}
|
||||
|
||||
func hash(into hasher: inout Hasher) {
|
||||
hasher.combine(generation)
|
||||
}
|
||||
|
||||
static func == (_ lhs: Awaiting, _ rhs: Awaiting) -> Bool {
|
||||
return lhs.generation == rhs.generation
|
||||
}
|
||||
}
|
||||
|
||||
enum Emission {
|
||||
case idle
|
||||
case pending([UnsafeContinuation<UnsafeContinuation<Element?, Never>?, Never>])
|
||||
case awaiting(Set<Awaiting>)
|
||||
|
||||
mutating func cancel(_ generation: Int) -> UnsafeContinuation<Element?, Never>? {
|
||||
switch self {
|
||||
case .awaiting(var awaiting):
|
||||
let continuation = awaiting.remove(Awaiting(placeholder: generation))?.continuation
|
||||
self = .awaiting(awaiting)
|
||||
return continuation
|
||||
case .idle:
|
||||
self = .awaiting([Awaiting(cancelled: generation)])
|
||||
return nil
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct State {
|
||||
var emission: Emission = .idle
|
||||
var generation = 0
|
||||
var terminal = false
|
||||
}
|
||||
|
||||
let state = ManagedCriticalState(State())
|
||||
|
||||
/// Create a new `AsyncChannel` given an element type.
|
||||
public init(element elementType: Element.Type = Element.self) { }
|
||||
|
||||
func establish() -> Int {
|
||||
state.withCriticalRegion { state in
|
||||
defer { state.generation &+= 1 }
|
||||
return state.generation
|
||||
}
|
||||
}
|
||||
|
||||
func cancel(_ generation: Int) {
|
||||
state.withCriticalRegion { state in
|
||||
state.emission.cancel(generation)
|
||||
}?.resume(returning: nil)
|
||||
}
|
||||
|
||||
func next(_ generation: Int) async -> Element? {
|
||||
return await withUnsafeContinuation { continuation in
|
||||
var cancelled = false
|
||||
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Never>?, Never>? in
|
||||
switch state.emission {
|
||||
case .idle:
|
||||
state.emission = .awaiting([Awaiting(generation: generation, continuation: continuation)])
|
||||
return nil
|
||||
case .pending(var sends):
|
||||
let send = sends.removeFirst()
|
||||
if sends.count == 0 {
|
||||
state.emission = .idle
|
||||
} else {
|
||||
state.emission = .pending(sends)
|
||||
}
|
||||
return UnsafeResumption(continuation: send, success: continuation)
|
||||
case .awaiting(var nexts):
|
||||
if nexts.update(with: Awaiting(generation: generation, continuation: continuation)) != nil {
|
||||
nexts.remove(Awaiting(placeholder: generation))
|
||||
cancelled = true
|
||||
}
|
||||
state.emission = .awaiting(nexts)
|
||||
return nil
|
||||
}
|
||||
}?.resume()
|
||||
if cancelled {
|
||||
continuation.resume(returning: nil)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func _send(_ result: Result<Element?, Never>) async {
|
||||
let continuation: UnsafeContinuation<Element?, Never>? = await withUnsafeContinuation { continuation in
|
||||
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Never>?, Never>? in
|
||||
if state.terminal {
|
||||
return UnsafeResumption(continuation: continuation, success: nil)
|
||||
}
|
||||
switch result {
|
||||
case .success(let value):
|
||||
if value == nil {
|
||||
state.terminal = true
|
||||
}
|
||||
case .failure:
|
||||
state.terminal = true
|
||||
}
|
||||
switch state.emission {
|
||||
case .idle:
|
||||
state.emission = .pending([continuation])
|
||||
return nil
|
||||
case .pending(var sends):
|
||||
sends.append(continuation)
|
||||
state.emission = .pending(sends)
|
||||
return nil
|
||||
case .awaiting(var nexts):
|
||||
let next = nexts.removeFirst().continuation
|
||||
if nexts.count == 0 {
|
||||
state.emission = .idle
|
||||
} else {
|
||||
state.emission = .awaiting(nexts)
|
||||
}
|
||||
return UnsafeResumption(continuation: continuation, success: next)
|
||||
}
|
||||
}?.resume()
|
||||
}
|
||||
continuation?.resume(with: result)
|
||||
}
|
||||
|
||||
/// Send an element to an awaiting iteration. This function will resume when the next call to `next()` is made.
|
||||
/// If the channel is already finished then this returns immediately
|
||||
public func send(_ element: Element) async {
|
||||
await _send(.success(element))
|
||||
}
|
||||
|
||||
/// Send a finish to an awaiting iteration. This function will resume when the next call to `next()` is made.
|
||||
/// If the channel is already finished then this returns immediately
|
||||
public func finish() async {
|
||||
await _send(.success(nil))
|
||||
}
|
||||
|
||||
/// Create an `Iterator` for iteration of an `AsyncChannel`
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(self)
|
||||
}
|
||||
}
|
||||
@@ -9,17 +9,25 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection`
|
||||
/// type by testing if elements belong in the same group.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
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<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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func chunked(by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool) -> AsyncChunkedByGroupSequence<Self, [Element]> {
|
||||
public func chunked(
|
||||
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
|
||||
) -> AsyncChunkedByGroupSequence<Self, [Element]> {
|
||||
chunked(into: [Element].self, by: belongInSameGroup)
|
||||
}
|
||||
}
|
||||
@@ -37,6 +45,7 @@ extension AsyncSequence {
|
||||
/// 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)
|
||||
@@ -45,7 +54,9 @@ extension AsyncSequence {
|
||||
/// // [10, 20, 30]
|
||||
/// // [10, 40, 40]
|
||||
/// // [10, 20]
|
||||
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
/// The iterator for a `AsyncChunkedByGroupSequence` instance.
|
||||
@@ -75,7 +86,7 @@ public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeR
|
||||
} else {
|
||||
hangingNext = nil
|
||||
}
|
||||
|
||||
|
||||
guard let first = firstOpt else {
|
||||
return nil
|
||||
}
|
||||
@@ -85,25 +96,24 @@ public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeR
|
||||
|
||||
var prev = first
|
||||
while let next = try await base.next() {
|
||||
if grouping(prev, next) {
|
||||
result.append(next)
|
||||
prev = next
|
||||
} else {
|
||||
guard grouping(prev, next) else {
|
||||
hangingNext = next
|
||||
break
|
||||
}
|
||||
result.append(next)
|
||||
prev = next
|
||||
}
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let grouping : @Sendable (Base.Element, Base.Element) -> Bool
|
||||
let grouping: @Sendable (Base.Element, Base.Element) -> Bool
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(_ base: Base, grouping: @escaping @Sendable (Base.Element, Base.Element) -> Bool) {
|
||||
self.base = base
|
||||
self.grouping = grouping
|
||||
@@ -115,5 +125,8 @@ public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeR
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunkedByGroupSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunkedByGroupSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChunkedByGroupSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunkedByGroupSequence.Iterator: Sendable {}
|
||||
@@ -9,22 +9,35 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type on the uniqueness of a given subject.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
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, 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func chunked<Subject : Equatable>(on projection: @escaping @Sendable (Element) -> Subject) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]> {
|
||||
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 {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@@ -67,24 +80,23 @@ public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equ
|
||||
|
||||
while let next = try await base.next() {
|
||||
let subj = projection(next)
|
||||
if subj == first.0 {
|
||||
result.append(next)
|
||||
} else {
|
||||
guard subj == first.0 else {
|
||||
hangingNext = (subj, next)
|
||||
break
|
||||
}
|
||||
result.append(next)
|
||||
}
|
||||
return (first.0, result)
|
||||
}
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let projection : @Sendable (Base.Element) -> Subject
|
||||
let projection: @Sendable (Base.Element) -> Subject
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(_ base: Base, projection: @escaping @Sendable (Base.Element) -> Subject) {
|
||||
self.base = base
|
||||
self.projection = projection
|
||||
@@ -96,6 +108,8 @@ public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equ
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunkedOnProjectionSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunkedOnProjectionSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable, Subject : Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChunkedOnProjectionSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable {}
|
||||
@@ -9,82 +9,140 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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 {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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> {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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 {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
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 {
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func chunks<C: Clock>(ofCount count: Int, or timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(by timer: AsyncTimerSequence<C>, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>> where Collected.Element == Element {
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func chunked<C: Clock>(by timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
|
||||
@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.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable, Base.Element: Sendable, Signal.Element: Sendable {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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, Sendable {
|
||||
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 state: Merge2StateMachine<Base, Signal>
|
||||
init(base: Base.AsyncIterator, count: Int?, signal: Signal.AsyncIterator) {
|
||||
var iterator: Merged.AsyncIterator
|
||||
var terminated = false
|
||||
|
||||
init(iterator: Merged.AsyncIterator, count: Int?) {
|
||||
self.count = count
|
||||
self.state = Merge2StateMachine(base, terminatesOnNil: true, signal)
|
||||
self.iterator = iterator
|
||||
}
|
||||
|
||||
|
||||
public mutating func next() async rethrows -> Collected? {
|
||||
var result : Collected?
|
||||
while let next = try await state.next() {
|
||||
guard !terminated else {
|
||||
return nil
|
||||
}
|
||||
var result: Collected?
|
||||
while let next = try await iterator.next() {
|
||||
switch next {
|
||||
case .first(let element):
|
||||
if result == nil {
|
||||
result = Collected()
|
||||
}
|
||||
result!.append(element)
|
||||
if result?.count == count {
|
||||
return result
|
||||
}
|
||||
case .second(_):
|
||||
if result != nil {
|
||||
return result
|
||||
}
|
||||
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
|
||||
@@ -105,6 +163,16 @@ public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected:
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base: base.makeAsyncIterator(), count: count, signal: signal.makeAsyncIterator())
|
||||
|
||||
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 {}
|
||||
@@ -9,14 +9,20 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` of a given count.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func chunks<Collected: RangeReplaceableCollection>(ofCount count: Int, into: Collected.Type) -> AsyncChunksOfCountSequence<Self, Collected> where Collected.Element == Element {
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func chunks(ofCount count: Int) -> AsyncChunksOfCountSequence<Self, [Element]> {
|
||||
chunks(ofCount: count, into: [Element].self)
|
||||
@@ -24,7 +30,9 @@ extension AsyncSequence {
|
||||
}
|
||||
|
||||
/// 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 {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
|
||||
where Collected.Element == Base.Element {
|
||||
public typealias Element = Collected
|
||||
|
||||
/// The iterator for a `AsyncChunksOfCountSequence` instance.
|
||||
@@ -49,6 +57,10 @@ public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeRe
|
||||
return nil
|
||||
}
|
||||
|
||||
if count == 1 {
|
||||
return Collected(CollectionOfOne(first))
|
||||
}
|
||||
|
||||
var result: Collected = .init()
|
||||
result.append(first)
|
||||
|
||||
@@ -63,12 +75,12 @@ public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeRe
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
let base : Base
|
||||
let base: Base
|
||||
|
||||
@usableFromInline
|
||||
let count : Int
|
||||
let count: Int
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(_ base: Base, count: Int) {
|
||||
precondition(count > 0)
|
||||
self.base = base
|
||||
@@ -81,5 +93,7 @@ public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeRe
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
|
||||
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChunksOfCountSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncChunksOfCountSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable {}
|
||||
@@ -1,309 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2> {
|
||||
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>: Sendable
|
||||
where
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable, Base2.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncCombineLatest2Sequence: AsyncSequence {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
/// The iterator for a `AsyncCombineLatest2Sequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
enum Partial: Sendable {
|
||||
case first(Result<Base1.Element?, Error>, Base1.AsyncIterator)
|
||||
case second(Result<Base2.Element?, Error>, Base2.AsyncIterator)
|
||||
}
|
||||
|
||||
enum State {
|
||||
case initial(Base1.AsyncIterator, Base2.AsyncIterator)
|
||||
case idle(Base1.AsyncIterator, Base2.AsyncIterator, (Base1.Element, Base2.Element))
|
||||
case firstActiveSecondIdle(Task<Partial, Never>, Base2.AsyncIterator, (Base1.Element, Base2.Element))
|
||||
case firstIdleSecondActive(Base1.AsyncIterator, Task<Partial, Never>, (Base1.Element, Base2.Element))
|
||||
case firstTerminalSecondIdle(Base2.AsyncIterator, (Base1.Element, Base2.Element))
|
||||
case firstIdleSecondTerminal(Base1.AsyncIterator, (Base1.Element, Base2.Element))
|
||||
case terminal
|
||||
}
|
||||
|
||||
var state: State
|
||||
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator) {
|
||||
state = .initial(base1, base2)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> (Base1.Element, Base2.Element)? {
|
||||
let task1: Task<Partial, Never>
|
||||
let task2: Task<Partial, Never>
|
||||
var current: (Base1.Element, Base2.Element)
|
||||
|
||||
switch state {
|
||||
case .initial(let iterator1, let iterator2):
|
||||
func iteration(
|
||||
_ group: inout TaskGroup<Partial>,
|
||||
_ value1: inout Base1.Element?,
|
||||
_ value2: inout Base2.Element?,
|
||||
_ iterator1: inout Base1.AsyncIterator?,
|
||||
_ iterator2: inout Base2.AsyncIterator?
|
||||
) async -> Result<(Base1.Element, Base2.Element)?, Error>? {
|
||||
guard let partial = await group.next() else {
|
||||
return .success(nil)
|
||||
}
|
||||
switch partial {
|
||||
case .first(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value1 = value
|
||||
iterator1 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
case .second(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value2 = value
|
||||
iterator2 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let (result, iter1, iter2) = await withTaskGroup(of: Partial.self) { group -> (Result<(Base1.Element, Base2.Element)?, Error>, Base1.AsyncIterator?, Base2.AsyncIterator?) in
|
||||
group.addTask {
|
||||
var iterator = iterator1
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .first(.success(value), iterator)
|
||||
} catch {
|
||||
return .first(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
group.addTask {
|
||||
var iterator = iterator2
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .second(.success(value), iterator)
|
||||
} catch {
|
||||
return .second(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
|
||||
var res1: Base1.Element?
|
||||
var res2: Base2.Element?
|
||||
var iter1: Base1.AsyncIterator?
|
||||
var iter2: Base2.AsyncIterator?
|
||||
|
||||
if let result = await iteration(&group, &res1, &res2, &iter1, &iter2) {
|
||||
return (result, nil, nil)
|
||||
}
|
||||
if let result = await iteration(&group, &res1, &res2, &iter1, &iter2) {
|
||||
return (result, nil, nil)
|
||||
}
|
||||
guard let res1 = res1, let res2 = res2 else {
|
||||
return (.success(nil), nil, nil)
|
||||
}
|
||||
|
||||
return (.success((res1, res2)), iter1, iter2)
|
||||
}
|
||||
do {
|
||||
// make sure to get the result first just in case it has a failure embedded
|
||||
guard let value = try result._rethrowGet() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
guard let iter1 = iter1, let iter2 = iter2 else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
state = .idle(iter1, iter2, value)
|
||||
return value
|
||||
} catch {
|
||||
state = .terminal
|
||||
throw error
|
||||
}
|
||||
case .idle(let iterator1, let iterator2, let value):
|
||||
task1 = Task {
|
||||
var iterator = iterator1
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .first(.success(value), iterator)
|
||||
} catch {
|
||||
return .first(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
task2 = Task {
|
||||
var iterator = iterator2
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .second(.success(value), iterator)
|
||||
} catch {
|
||||
return .second(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
current = value
|
||||
case .firstActiveSecondIdle(let task, let iterator2, let value):
|
||||
task1 = task
|
||||
task2 = Task {
|
||||
var iterator = iterator2
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .second(.success(value), iterator)
|
||||
} catch {
|
||||
return .second(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
current = value
|
||||
case .firstIdleSecondActive(let iterator1, let task, let value):
|
||||
task1 = Task {
|
||||
var iterator = iterator1
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .first(.success(value), iterator)
|
||||
} catch {
|
||||
return .first(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
task2 = task
|
||||
current = value
|
||||
case .firstTerminalSecondIdle(var iterator, var current):
|
||||
do {
|
||||
guard let member = try await iterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
current.1 = member
|
||||
state = .firstTerminalSecondIdle(iterator, current)
|
||||
return current
|
||||
} catch {
|
||||
state = .terminal
|
||||
throw error
|
||||
}
|
||||
case .firstIdleSecondTerminal(var iterator, var current):
|
||||
do {
|
||||
guard let member = try await iterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
current.0 = member
|
||||
state = .firstIdleSecondTerminal(iterator, current)
|
||||
return current
|
||||
} catch {
|
||||
state = .terminal
|
||||
throw error
|
||||
}
|
||||
case .terminal:
|
||||
return nil
|
||||
}
|
||||
switch await Task.select(task1, task2).value {
|
||||
case .first(let result, let iterator):
|
||||
switch result {
|
||||
case .success(let member):
|
||||
if let member = member {
|
||||
current.0 = member
|
||||
state = .firstIdleSecondActive(iterator, task2, current)
|
||||
} else {
|
||||
switch await task2.value {
|
||||
case .first:
|
||||
fatalError()
|
||||
case .second(let result, let iterator):
|
||||
switch result {
|
||||
case .success(let member):
|
||||
if let member = member {
|
||||
current.1 = member
|
||||
state = .firstTerminalSecondIdle(iterator, current)
|
||||
return current
|
||||
} else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
case .failure:
|
||||
state = .terminal
|
||||
try result._rethrowError()
|
||||
}
|
||||
}
|
||||
}
|
||||
case .failure:
|
||||
state = .terminal
|
||||
task2.cancel()
|
||||
try result._rethrowError()
|
||||
}
|
||||
case .second(let result, let iterator):
|
||||
switch result {
|
||||
case .success(let member):
|
||||
if let member = member {
|
||||
current.1 = member
|
||||
state = .firstActiveSecondIdle(task1, iterator, current)
|
||||
} else {
|
||||
switch await task1.value {
|
||||
case .first(let result, let iterator):
|
||||
switch result {
|
||||
case .success(let member):
|
||||
if let member = member {
|
||||
current.0 = member
|
||||
state = .firstIdleSecondTerminal(iterator, current)
|
||||
return current
|
||||
} else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
case .failure:
|
||||
state = .terminal
|
||||
try result._rethrowError()
|
||||
}
|
||||
case .second:
|
||||
fatalError()
|
||||
}
|
||||
}
|
||||
case .failure:
|
||||
state = .terminal
|
||||
task2.cancel()
|
||||
try result._rethrowError()
|
||||
}
|
||||
}
|
||||
return current
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -1,57 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3> {
|
||||
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>: 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 {
|
||||
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
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncCombineLatest3Sequence: AsyncSequence {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
/// The iterator for a `AsyncCombineLatest3Sequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
var iterator: AsyncCombineLatest2Sequence<AsyncCombineLatest2Sequence<Base1, Base2>, Base3>.Iterator
|
||||
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator, _ base3: Base3.AsyncIterator) {
|
||||
iterator = AsyncCombineLatest2Sequence<AsyncCombineLatest2Sequence<Base1, Base2>, Base3>.Iterator(AsyncCombineLatest2Sequence<Base1, Base2>.Iterator(base1, base2), base3)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element)? {
|
||||
guard let value = try await iterator.next() else {
|
||||
return nil
|
||||
}
|
||||
return (value.0.0, value.0.1, value.1)
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -9,15 +9,34 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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`.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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`.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
|
||||
where Base.Element == Element? {
|
||||
where Base.Element == Element? {
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
|
||||
@inlinable
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
@@ -28,12 +47,12 @@ public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequenc
|
||||
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() {
|
||||
@@ -50,23 +69,8 @@ public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequenc
|
||||
}
|
||||
}
|
||||
|
||||
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`.
|
||||
///
|
||||
/// Complexity: O(1)
|
||||
@inlinable
|
||||
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
|
||||
where Element == Unwrapped? {
|
||||
AsyncCompactedSequence(self)
|
||||
}
|
||||
}
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncCompactedSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
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 { }
|
||||
@available(*, unavailable)
|
||||
extension AsyncCompactedSequence.Iterator: Sendable {}
|
||||
@@ -1,121 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 spectified Clock.
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func debounce<C: Clock>(for interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncDebounceSequence<Self, C> {
|
||||
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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func debounce(for interval: Duration, tolerance: Duration? = nil) -> AsyncDebounceSequence<Self, ContinuousClock> {
|
||||
debounce(for: interval, tolerance: tolerance, clock: .continuous)
|
||||
}
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that emits the latest element after a given quiescence period
|
||||
/// has elapsed.
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public struct AsyncDebounceSequence<Base: AsyncSequence, C: Clock>: Sendable
|
||||
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Base: Sendable {
|
||||
let base: Base
|
||||
let interval: C.Instant.Duration
|
||||
let tolerance: C.Instant.Duration?
|
||||
let clock: C
|
||||
|
||||
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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncDebounceSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
/// The iterator for a `AsyncDebounceSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
enum Partial: Sendable {
|
||||
case sleep
|
||||
case produce(Result<Base.Element?, Error>, Base.AsyncIterator)
|
||||
}
|
||||
var iterator: Base.AsyncIterator
|
||||
var produce: Task<Partial, Never>?
|
||||
var terminal = false
|
||||
let interval: C.Instant.Duration
|
||||
let tolerance: C.Instant.Duration?
|
||||
let clock: C
|
||||
|
||||
init(_ base: Base.AsyncIterator, interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
|
||||
self.iterator = base
|
||||
self.interval = interval
|
||||
self.tolerance = tolerance
|
||||
self.clock = clock
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Base.Element? {
|
||||
var last: C.Instant?
|
||||
var lastResult: Result<Element?, Error>?
|
||||
while !terminal {
|
||||
let deadline = (last ?? clock.now).advanced(by: interval)
|
||||
let sleep: Task<Partial, Never> = Task { [tolerance, clock] in
|
||||
try? await clock.sleep(until: deadline, tolerance: tolerance)
|
||||
return .sleep
|
||||
}
|
||||
let produce: Task<Partial, Never> = self.produce ?? Task { [iterator] in
|
||||
var iter = iterator
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .produce(.success(value), iter)
|
||||
} catch {
|
||||
return .produce(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
self.produce = nil
|
||||
switch await Task.select(sleep, produce).value {
|
||||
case .sleep:
|
||||
self.produce = produce
|
||||
if let result = lastResult {
|
||||
return try result._rethrowGet()
|
||||
}
|
||||
break
|
||||
case .produce(let result, let iter):
|
||||
lastResult = result
|
||||
last = clock.now
|
||||
sleep.cancel()
|
||||
self.iterator = iter
|
||||
switch result {
|
||||
case .success(let value):
|
||||
if value == nil {
|
||||
terminal = true
|
||||
return nil
|
||||
}
|
||||
case .failure:
|
||||
terminal = true
|
||||
try result._rethrowError()
|
||||
}
|
||||
break
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), interval: interval, tolerance: tolerance, clock: clock)
|
||||
}
|
||||
}
|
||||
@@ -9,58 +9,74 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously-reduced result and
|
||||
/// the next element in the receiving asynchronous sequence, which it returns.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async -> Result) -> AsyncExclusiveReductionsSequence<Self, Result> {
|
||||
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.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously-reduced result and
|
||||
/// the next element in the receiving asynchronous sequence, mutating the
|
||||
/// previous result instead of returning a value.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async -> Void) -> AsyncExclusiveReductionsSequence<Self, Result> {
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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
|
||||
@@ -69,47 +85,55 @@ public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncExclusiveReductionsSequence: AsyncSequence {
|
||||
/// The iterator for an `AsyncExclusiveReductionsSequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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) {
|
||||
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 }
|
||||
guard var 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 {
|
||||
guard let value = value else {
|
||||
current = nil
|
||||
return nil
|
||||
}
|
||||
await transform(&result, value)
|
||||
current = result
|
||||
return result
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
extension AsyncExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncExclusiveReductionsSequence.Iterator: Sendable {}
|
||||
@@ -1,3 +1,15 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given closure.
|
||||
@@ -17,6 +29,7 @@ extension AsyncSequence {
|
||||
/// result and the next element in the receiving sequence, and returns
|
||||
/// the result.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async -> Element
|
||||
@@ -27,14 +40,15 @@ extension AsyncSequence {
|
||||
|
||||
/// An asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using a given closure.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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
|
||||
@@ -42,10 +56,12 @@ public struct AsyncInclusiveReductionsSequence<Base: AsyncSequence> {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncInclusiveReductionsSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
|
||||
/// The iterator for an `AsyncInclusiveReductionsSequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
@@ -58,7 +74,7 @@ extension AsyncInclusiveReductionsSequence: AsyncSequence {
|
||||
internal let transform: @Sendable (Base.Element, Base.Element) async -> Base.Element
|
||||
|
||||
@inlinable
|
||||
internal init(
|
||||
init(
|
||||
_ iterator: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Element, Base.Element) async -> Base.Element
|
||||
) {
|
||||
@@ -78,11 +94,15 @@ extension AsyncInclusiveReductionsSequence: AsyncSequence {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInclusiveReductionsSequence: Sendable where Base: Sendable { }
|
||||
extension AsyncInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncInclusiveReductionsSequence: Sendable where Base: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncInclusiveReductionsSequence.Iterator: Sendable {}
|
||||
@@ -1,104 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 elements of this asynchronous sequence with
|
||||
/// the given separator inserted in between each element.
|
||||
///
|
||||
/// Any value of the asynchronous sequence's element type can be used as the separator.
|
||||
///
|
||||
/// - Parameter 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(with separator: Element) -> AsyncInterspersedSequence<Self> {
|
||||
AsyncInterspersedSequence(self, 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 let base: Base
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Base.Element
|
||||
|
||||
@inlinable
|
||||
internal init(_ base: Base, separator: Base.Element) {
|
||||
self.base = base
|
||||
self.separator = separator
|
||||
}
|
||||
}
|
||||
|
||||
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
|
||||
case element(Result<Base.Element, Error>)
|
||||
case separator
|
||||
}
|
||||
|
||||
@usableFromInline
|
||||
internal var iterator: Base.AsyncIterator
|
||||
|
||||
@usableFromInline
|
||||
internal let separator: Base.Element
|
||||
|
||||
@usableFromInline
|
||||
internal var state = State.start
|
||||
|
||||
@inlinable
|
||||
internal init(_ iterator: Base.AsyncIterator, separator: Base.Element) {
|
||||
self.iterator = iterator
|
||||
self.separator = separator
|
||||
}
|
||||
|
||||
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 .start:
|
||||
state = .separator
|
||||
return try await iterator.next()
|
||||
case .separator:
|
||||
do {
|
||||
guard let next = try await iterator.next() else { return nil }
|
||||
state = .element(.success(next))
|
||||
} catch {
|
||||
state = .element(.failure(error))
|
||||
}
|
||||
return separator
|
||||
case .element(let result):
|
||||
state = .separator
|
||||
return try result._rethrowGet()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> AsyncInterspersedSequence<Base>.Iterator {
|
||||
Iterator(base.makeAsyncIterator(), separator: separator)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncInterspersedSequence: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
extension AsyncInterspersedSequence.Iterator: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
extension AsyncInterspersedSequence.Iterator.State: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
|
||||
@@ -9,16 +9,22 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements with a separator.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
|
||||
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 {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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
|
||||
|
||||
@@ -36,31 +42,31 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
|
||||
@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")
|
||||
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 .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")
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -74,7 +80,7 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
|
||||
@usableFromInline
|
||||
var state: State
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(_ iterator: Base.AsyncIterator, separator: Separator) {
|
||||
state = .initial(iterator, separator)
|
||||
}
|
||||
@@ -83,37 +89,37 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
|
||||
public mutating func next() async rethrows -> Base.Element.Element? {
|
||||
do {
|
||||
switch state {
|
||||
case .terminal:
|
||||
case .terminal:
|
||||
return nil
|
||||
case .initial(var outerIterator, let separator):
|
||||
guard let innerSequence = try await outerIterator.next() else {
|
||||
state = .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)
|
||||
}
|
||||
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
|
||||
@@ -128,7 +134,7 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
|
||||
@usableFromInline
|
||||
let separator: Separator
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(_ base: Base, separator: Separator) {
|
||||
self.base = base
|
||||
self.separator = separator
|
||||
@@ -140,11 +146,9 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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 { }
|
||||
extension AsyncJoinedBySeparatorSequence.Iterator.State: 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.State.SeparatorState: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, Base.AsyncIterator: Sendable, Separator: Sendable, Separator.AsyncIterator: Sendable, Base.Element.AsyncIterator: Sendable { }
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, Separator: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncJoinedBySeparatorSequence.Iterator: Sendable {}
|
||||
@@ -9,8 +9,10 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence where Element: AsyncSequence {
|
||||
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements
|
||||
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func joined() -> AsyncJoinedSequence<Self> {
|
||||
return AsyncJoinedSequence(self)
|
||||
@@ -18,6 +20,7 @@ extension AsyncSequence where Element: AsyncSequence {
|
||||
}
|
||||
|
||||
/// An `AsyncSequence` that concatenates`AsyncSequence` elements
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
|
||||
public typealias Element = Base.Element.Element
|
||||
@@ -32,42 +35,42 @@ public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base
|
||||
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:
|
||||
case .terminal:
|
||||
return nil
|
||||
case .initial(var outerIterator):
|
||||
guard let innerSequence = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
case .initial(var outerIterator):
|
||||
guard let innerSequence = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
let innerIterator = innerSequence.makeAsyncIterator()
|
||||
}
|
||||
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 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
|
||||
}
|
||||
return item
|
||||
}
|
||||
|
||||
state = .sequence(outerIterator, nextInner.makeAsyncIterator())
|
||||
return try await next()
|
||||
guard let nextInner = try await outerIterator.next() else {
|
||||
state = .terminal
|
||||
return nil
|
||||
}
|
||||
|
||||
state = .sequence(outerIterator, nextInner.makeAsyncIterator())
|
||||
return try await next()
|
||||
}
|
||||
} catch {
|
||||
state = .terminal
|
||||
@@ -75,24 +78,24 @@ public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
@inlinable
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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 { }
|
||||
extension AsyncJoinedSequence.Iterator.State: Sendable
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, Base.AsyncIterator: Sendable, Base.Element.AsyncIterator: Sendable { }
|
||||
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncJoinedSequence.Iterator: Sendable {}
|
||||
@@ -0,0 +1,106 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2025 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if compiler(>=6.0)
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncSequence {
|
||||
|
||||
/// Converts any failure into a new error.
|
||||
///
|
||||
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
|
||||
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
|
||||
///
|
||||
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
public func mapError<MappedError: Error>(
|
||||
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
|
||||
) -> some AsyncSequence<Self.Element, MappedError> {
|
||||
AsyncMapErrorSequence(base: self, transform: transform)
|
||||
}
|
||||
|
||||
/// Converts any failure into a new error.
|
||||
///
|
||||
/// - Parameter transform: A closure that takes the failure as a parameter and returns a new error.
|
||||
/// - Returns: An asynchronous sequence that maps the error thrown into the one produced by the transform closure.
|
||||
///
|
||||
/// Use the ``mapError(_:)`` operator when you need to replace one error type with another.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
public func mapError<MappedError: Error>(
|
||||
_ transform: @Sendable @escaping (Self.Failure) -> MappedError
|
||||
) -> (some AsyncSequence<Self.Element, MappedError> & Sendable) where Self: Sendable, Self.Element: Sendable {
|
||||
AsyncMapErrorSequence(base: self, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence that converts any failure into a new error.
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
struct AsyncMapErrorSequence<Base: AsyncSequence, MappedError: Error> {
|
||||
typealias Element = Base.Element
|
||||
typealias Failure = MappedError
|
||||
|
||||
private let base: Base
|
||||
private let transform: @Sendable (Base.Failure) async -> MappedError
|
||||
|
||||
init(
|
||||
base: Base,
|
||||
transform: @Sendable @escaping (Base.Failure) async -> MappedError
|
||||
) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncMapErrorSequence: AsyncSequence {
|
||||
|
||||
/// The iterator that produces elements of the map sequence.
|
||||
struct Iterator: AsyncIteratorProtocol {
|
||||
typealias Element = Base.Element
|
||||
|
||||
private var base: Base.AsyncIterator
|
||||
|
||||
private let transform: @Sendable (Base.Failure) async -> MappedError
|
||||
|
||||
init(
|
||||
base: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Failure) async -> MappedError
|
||||
) {
|
||||
self.base = base
|
||||
self.transform = transform
|
||||
}
|
||||
|
||||
mutating func next() async throws(MappedError) -> Element? {
|
||||
try await self.next(isolation: nil)
|
||||
}
|
||||
|
||||
mutating func next(isolation actor: isolated (any Actor)?) async throws(MappedError) -> Element? {
|
||||
do {
|
||||
return try await base.next(isolation: actor)
|
||||
} catch {
|
||||
throw await transform(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func makeAsyncIterator() -> Iterator {
|
||||
Iterator(
|
||||
base: base.makeAsyncIterator(),
|
||||
transform: transform
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.2, *)
|
||||
extension AsyncMapErrorSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncMapErrorSequence.Iterator: Sendable {}
|
||||
#endif
|
||||
@@ -1,209 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 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,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
return AsyncMerge2Sequence(base1, base2)
|
||||
}
|
||||
|
||||
struct Merge2StateMachine<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base1.Element: Sendable, Base2.Element: Sendable {
|
||||
typealias Element1 = Base1.Element
|
||||
typealias Element2 = Base2.Element
|
||||
|
||||
let iter1TerminatesOnNil : Bool
|
||||
let iter2terminatesOnNil : Bool
|
||||
|
||||
enum Partial: @unchecked Sendable {
|
||||
case first(Result<Element1?, Error>, Base1.AsyncIterator)
|
||||
case second(Result<Element2?, Error>, Base2.AsyncIterator)
|
||||
}
|
||||
|
||||
enum Either {
|
||||
case first(Base1.Element)
|
||||
case second(Base2.Element)
|
||||
}
|
||||
|
||||
var state: (PartialIteration<Base1.AsyncIterator, Partial>, PartialIteration<Base2.AsyncIterator, Partial>)
|
||||
|
||||
init(_ iterator1: Base1.AsyncIterator, terminatesOnNil iter1TerminatesOnNil: Bool = false, _ iterator2: Base2.AsyncIterator, terminatesOnNil iter2terminatesOnNil: Bool = false) {
|
||||
self.iter1TerminatesOnNil = iter1TerminatesOnNil
|
||||
self.iter2terminatesOnNil = iter2terminatesOnNil
|
||||
state = (.idle(iterator1), .idle(iterator2))
|
||||
}
|
||||
|
||||
mutating func apply(_ task1: Task<Merge2StateMachine<Base1, Base2>.Partial, Never>?, _ task2: Task<Merge2StateMachine<Base1, Base2>.Partial, Never>?) async rethrows -> Either? {
|
||||
switch await Task.select([task1, task2].compactMap ({ $0 })).value {
|
||||
case .first(let result, let iterator):
|
||||
do {
|
||||
guard let value = try state.0.resolve(result, iterator) else {
|
||||
if iter1TerminatesOnNil {
|
||||
state.1.cancel()
|
||||
return nil
|
||||
}
|
||||
return try await next()
|
||||
}
|
||||
return .first(value)
|
||||
} catch {
|
||||
state.1.cancel()
|
||||
throw error
|
||||
}
|
||||
case .second(let result, let iterator):
|
||||
do {
|
||||
guard let value = try state.1.resolve(result, iterator) else {
|
||||
if iter2terminatesOnNil {
|
||||
state.0.cancel()
|
||||
return nil
|
||||
}
|
||||
return try await next()
|
||||
}
|
||||
return .second(value)
|
||||
} catch {
|
||||
state.0.cancel()
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func first(_ iterator1: Base1.AsyncIterator) -> Task<Partial, Never> {
|
||||
Task {
|
||||
var iter = iterator1
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .first(.success(value), iter)
|
||||
} catch {
|
||||
return .first(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func second(_ iterator2: Base2.AsyncIterator) -> Task<Partial, Never> {
|
||||
Task {
|
||||
var iter = iterator2
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .second(.success(value), iter)
|
||||
} catch {
|
||||
return .second(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Advances to the next element and returns it or `nil` if no next element exists.
|
||||
mutating func next() async rethrows -> Either? {
|
||||
if Task.isCancelled {
|
||||
state.0.cancel()
|
||||
state.1.cancel()
|
||||
return nil
|
||||
}
|
||||
switch state {
|
||||
case (.idle(let iterator1), .idle(let iterator2)):
|
||||
let task1 = first(iterator1)
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2))
|
||||
return try await apply(task1, task2)
|
||||
case (.idle(let iterator1), .pending(let task2)):
|
||||
let task1 = first(iterator1)
|
||||
state = (.pending(task1), .pending(task2))
|
||||
return try await apply(task1, task2)
|
||||
case (.pending(let task1), .idle(let iterator2)):
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2))
|
||||
return try await apply(task1, task2)
|
||||
case (.idle(var iterator1), .terminal):
|
||||
do {
|
||||
if let value = try await iterator1.next() {
|
||||
state = (.idle(iterator1), .terminal)
|
||||
return .first(value)
|
||||
} else {
|
||||
state = (.terminal, .terminal)
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = (.terminal, .terminal)
|
||||
throw error
|
||||
}
|
||||
case (.terminal, .idle(var iterator2)):
|
||||
do {
|
||||
if let value = try await iterator2.next() {
|
||||
state = (.terminal, .idle(iterator2))
|
||||
return .second(value)
|
||||
} else {
|
||||
state = (.terminal, .terminal)
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = (.terminal, .terminal)
|
||||
throw error
|
||||
}
|
||||
case (.terminal, .pending(let task2)):
|
||||
return try await apply(nil, task2)
|
||||
case (.pending(let task1), .pending(let task2)):
|
||||
return try await apply(task1, task2)
|
||||
case (.pending(let task1), .terminal):
|
||||
return try await apply(task1, nil)
|
||||
case (.terminal, .terminal):
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
extension Merge2StateMachine.Either where Base1.Element == Base2.Element {
|
||||
var value : Base1.Element {
|
||||
switch self {
|
||||
case .first(let val):
|
||||
return val
|
||||
case .second(let val):
|
||||
return val
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// An asynchronous sequence of elements from two underlying asynchronous sequences
|
||||
///
|
||||
/// In a `AsyncMerge2Sequence` instance, the *i*th element is the *i*th element
|
||||
/// resolved in sequential order out of the two underyling asynchronous sequences.
|
||||
/// Use the `merge(_:_:)` function to create an `AsyncMerge2Sequence`.
|
||||
public struct AsyncMerge2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: AsyncSequence, Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base1: Sendable, Base2: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
/// An iterator for `AsyncMerge2Sequence`
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
var state: Merge2StateMachine<Base1, Base2>
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator) {
|
||||
state = Merge2StateMachine(base1, base2)
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
return try await state.next()?.value
|
||||
}
|
||||
}
|
||||
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -1,284 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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 of elements from three 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,
|
||||
Base2.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
|
||||
return AsyncMerge3Sequence(base1, base2, base3)
|
||||
}
|
||||
|
||||
/// An asynchronous sequence of elements from three underlying asynchronous sequences
|
||||
///
|
||||
/// In a `AsyncMerge3Sequence` instance, the *i*th element is the *i*th element
|
||||
/// resolved in sequential order out of the two underyling asynchronous sequences.
|
||||
/// Use the `merge(_:_:_:)` function to create an `AsyncMerge3Sequence`.
|
||||
public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: AsyncSequence, Sendable
|
||||
where
|
||||
Base1.Element == Base2.Element,
|
||||
Base2.Element == Base3.Element,
|
||||
Base1: Sendable, Base2: Sendable, Base3: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
|
||||
public typealias Element = Base1.Element
|
||||
/// An iterator for `AsyncMerge3Sequence`
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
enum Partial: @unchecked Sendable {
|
||||
case first(Result<Element?, Error>, Base1.AsyncIterator)
|
||||
case second(Result<Element?, Error>, Base2.AsyncIterator)
|
||||
case third(Result<Element?, Error>, Base3.AsyncIterator)
|
||||
}
|
||||
|
||||
var state: (PartialIteration<Base1.AsyncIterator, Partial>, PartialIteration<Base2.AsyncIterator, Partial>, PartialIteration<Base3.AsyncIterator, Partial>)
|
||||
|
||||
init(_ iterator1: Base1.AsyncIterator, _ iterator2: Base2.AsyncIterator, _ iterator3: Base3.AsyncIterator) {
|
||||
state = (.idle(iterator1), .idle(iterator2), .idle(iterator3))
|
||||
}
|
||||
|
||||
mutating func apply(_ task1: Task<Partial, Never>?, _ task2: Task<Partial, Never>?, _ task3: Task<Partial, Never>?) async rethrows -> Element? {
|
||||
switch await Task.select([task1, task2, task3].compactMap { $0 }).value {
|
||||
case .first(let result, let iterator):
|
||||
do {
|
||||
guard let value = try state.0.resolve(result, iterator) else {
|
||||
return try await next()
|
||||
}
|
||||
return value
|
||||
} catch {
|
||||
state.1.cancel()
|
||||
state.2.cancel()
|
||||
throw error
|
||||
}
|
||||
case .second(let result, let iterator):
|
||||
do {
|
||||
guard let value = try state.1.resolve(result, iterator) else {
|
||||
return try await next()
|
||||
}
|
||||
return value
|
||||
} catch {
|
||||
state.0.cancel()
|
||||
state.2.cancel()
|
||||
throw error
|
||||
}
|
||||
case .third(let result, let iterator):
|
||||
do {
|
||||
guard let value = try state.2.resolve(result, iterator) else {
|
||||
return try await next()
|
||||
}
|
||||
return value
|
||||
} catch {
|
||||
state.0.cancel()
|
||||
state.1.cancel()
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func first(_ iterator1: Base1.AsyncIterator) -> Task<Partial, Never> {
|
||||
Task {
|
||||
var iter = iterator1
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .first(.success(value), iter)
|
||||
} catch {
|
||||
return .first(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func second(_ iterator2: Base2.AsyncIterator) -> Task<Partial, Never> {
|
||||
Task {
|
||||
var iter = iterator2
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .second(.success(value), iter)
|
||||
} catch {
|
||||
return .second(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func third(_ iterator3: Base3.AsyncIterator) -> Task<Partial, Never> {
|
||||
Task {
|
||||
var iter = iterator3
|
||||
do {
|
||||
let value = try await iter.next()
|
||||
return .third(.success(value), iter)
|
||||
} catch {
|
||||
return .third(.failure(error), iter)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> Element? {
|
||||
// state must have either all terminal or at least 1 idle iterator
|
||||
// state may not have a saturation of pending tasks
|
||||
switch state {
|
||||
// three idle
|
||||
case (.idle(let iterator1), .idle(let iterator2), .idle(let iterator3)):
|
||||
let task1 = first(iterator1)
|
||||
let task2 = second(iterator2)
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
// two idle
|
||||
case (.idle(let iterator1), .idle(let iterator2), .pending(let task3)):
|
||||
let task1 = first(iterator1)
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
case (.idle(let iterator1), .pending(let task2), .idle(let iterator3)):
|
||||
let task1 = first(iterator1)
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
case (.pending(let task1), .idle(let iterator2), .idle(let iterator3)):
|
||||
let task2 = second(iterator2)
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
|
||||
// 1 idle
|
||||
case (.idle(let iterator1), .pending(let task2), .pending(let task3)):
|
||||
let task1 = first(iterator1)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
case (.pending(let task1), .idle(let iterator2), .pending(let task3)):
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
case (.pending(let task1), .pending(let task2), .idle(let iterator3)):
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .pending(task2), .pending(task3))
|
||||
return try await apply(task1, task2, task3)
|
||||
|
||||
// terminal degradations
|
||||
// 1 terminal
|
||||
case (.terminal, .idle(let iterator2), .idle(let iterator3)):
|
||||
let task2 = second(iterator2)
|
||||
let task3 = third(iterator3)
|
||||
state = (.terminal, .pending(task2), .pending(task3))
|
||||
return try await apply(nil, task2, task3)
|
||||
case (.terminal, .idle(let iterator2), .pending(let task3)):
|
||||
let task2 = second(iterator2)
|
||||
state = (.terminal, .pending(task2), .pending(task3))
|
||||
return try await apply(nil, task2, task3)
|
||||
case (.terminal, .pending(let task2), .idle(let iterator3)):
|
||||
let task3 = third(iterator3)
|
||||
state = (.terminal, .pending(task2), .pending(task3))
|
||||
return try await apply(nil, task2, task3)
|
||||
case (.idle(let iterator1), .terminal, .idle(let iterator3)):
|
||||
let task1 = first(iterator1)
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .terminal, .pending(task3))
|
||||
return try await apply(task1, nil, task3)
|
||||
case (.idle(let iterator1), .terminal, .pending(let task3)):
|
||||
let task1 = first(iterator1)
|
||||
state = (.pending(task1), .terminal, .pending(task3))
|
||||
return try await apply(task1, nil, task3)
|
||||
case (.pending(let task1), .terminal, .idle(let iterator3)):
|
||||
let task3 = third(iterator3)
|
||||
state = (.pending(task1), .terminal, .pending(task3))
|
||||
return try await apply(task1, nil, task3)
|
||||
case (.idle(let iterator1), .idle(let iterator2), .terminal):
|
||||
let task1 = first(iterator1)
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2), .terminal)
|
||||
return try await apply(task1, task2, nil)
|
||||
case (.idle(let iterator1), .pending(let task2), .terminal):
|
||||
let task1 = first(iterator1)
|
||||
state = (.pending(task1), .pending(task2), .terminal)
|
||||
return try await apply(task1, task2, nil)
|
||||
case (.pending(let task1), .idle(let iterator2), .terminal):
|
||||
let task2 = second(iterator2)
|
||||
state = (.pending(task1), .pending(task2), .terminal)
|
||||
return try await apply(task1, task2, nil)
|
||||
|
||||
// 2 terminal
|
||||
// these can be permuted in place since they dont need to run two or more tasks at once
|
||||
case (.terminal, .terminal, .idle(var iterator3)):
|
||||
do {
|
||||
if let value = try await iterator3.next() {
|
||||
state = (.terminal, .terminal, .idle(iterator3))
|
||||
return value
|
||||
} else {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
throw error
|
||||
}
|
||||
case (.terminal, .idle(var iterator2), .terminal):
|
||||
do {
|
||||
if let value = try await iterator2.next() {
|
||||
state = (.terminal, .idle(iterator2), .terminal)
|
||||
return value
|
||||
} else {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
throw error
|
||||
}
|
||||
case (.idle(var iterator1), .terminal, .terminal):
|
||||
do {
|
||||
if let value = try await iterator1.next() {
|
||||
state = (.idle(iterator1), .terminal, .terminal)
|
||||
return value
|
||||
} else {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
state = (.terminal, .terminal, .terminal)
|
||||
throw error
|
||||
}
|
||||
// 3 terminal
|
||||
case (.terminal, .terminal, .terminal):
|
||||
return nil
|
||||
// partials
|
||||
case (.pending(let task1), .pending(let task2), .pending(let task3)):
|
||||
return try await apply(task1, task2, task3)
|
||||
case (.pending(let task1), .pending(let task2), .terminal):
|
||||
return try await apply(task1, task2, nil)
|
||||
case (.pending(let task1), .terminal, .pending(let task3)):
|
||||
return try await apply(task1, nil, task3)
|
||||
case (.terminal, .pending(let task2), .pending(let task3)):
|
||||
return try await apply(nil, task2, task3)
|
||||
case (.pending(let task1), .terminal, .terminal):
|
||||
return try await apply(task1, nil, nil)
|
||||
case (.terminal, .pending(let task2), .terminal):
|
||||
return try await apply(nil, task2, nil)
|
||||
case (.terminal, .terminal, .pending(let task3)):
|
||||
return try await apply(nil, nil, task3)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
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() -> Iterator {
|
||||
return Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -9,8 +9,10 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence where Element: Equatable {
|
||||
/// Creates an asynchronous sequence that omits repeated elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self> {
|
||||
AsyncRemoveDuplicatesSequence(self) { lhs, rhs in
|
||||
lhs == rhs
|
||||
@@ -18,19 +20,27 @@ extension AsyncSequence where Element: Equatable {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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> {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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> {
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
@@ -46,7 +56,7 @@ public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence
|
||||
@usableFromInline
|
||||
var last: Element?
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
|
||||
self.iterator = iterator
|
||||
self.predicate = predicate
|
||||
@@ -73,7 +83,7 @@ public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence
|
||||
|
||||
@usableFromInline
|
||||
let predicate: @Sendable (Element, Element) async -> Bool
|
||||
|
||||
|
||||
init(_ base: Base, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
|
||||
self.base = base
|
||||
self.predicate = predicate
|
||||
@@ -85,14 +95,11 @@ public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence
|
||||
}
|
||||
}
|
||||
|
||||
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 { }
|
||||
|
||||
|
||||
/// An asynchronous sequence that omits repeated elements by testing them with an error-throwing predicate.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
|
||||
/// The iterator for an `AsyncThrowingRemoveDuplicatesSequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
|
||||
@@ -105,7 +112,7 @@ public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncS
|
||||
@usableFromInline
|
||||
var last: Element?
|
||||
|
||||
@inlinable
|
||||
@usableFromInline
|
||||
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async throws -> Bool) {
|
||||
self.iterator = iterator
|
||||
self.predicate = predicate
|
||||
@@ -132,7 +139,7 @@ public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncS
|
||||
|
||||
@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
|
||||
@@ -144,5 +151,13 @@ public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncS
|
||||
}
|
||||
}
|
||||
|
||||
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 { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncThrowingRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncRemoveDuplicatesSequence.Iterator: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingRemoveDuplicatesSequence.Iterator: Sendable {}
|
||||
@@ -0,0 +1,726 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the Swift Async Algorithms open source project
|
||||
//
|
||||
// Copyright (c) 2022 Apple Inc. and the Swift project authors
|
||||
// Licensed under Apache License v2.0 with Runtime Library Exception
|
||||
//
|
||||
// See https://swift.org/LICENSE.txt for license information
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
#if compiler(>=6.2)
|
||||
|
||||
import Synchronization
|
||||
import DequeModule
|
||||
|
||||
@available(AsyncAlgorithms 1.1, *)
|
||||
extension AsyncSequence
|
||||
where Element: Sendable, Self: SendableMetatype, AsyncIterator: SendableMetatype {
|
||||
/// Creates a shared async sequence that allows multiple concurrent iterations over a single source.
|
||||
///
|
||||
/// The `share` method transforms an async sequence into a shareable sequence that can be safely
|
||||
/// iterated by multiple concurrent tasks. This is useful when you want to broadcast elements from
|
||||
/// a single source to multiple consumers without duplicating work or creating separate iterations.
|
||||
///
|
||||
/// Each element from the source sequence is delivered to all active iterators.
|
||||
/// Elements are buffered according to the specified buffering policy to handle timing differences
|
||||
/// between consumers.
|
||||
///
|
||||
/// The base sequence is iterated in it's own task to ensure that cancellation is not polluted from
|
||||
/// one side of iteration to another.
|
||||
///
|
||||
/// ## Example Usage
|
||||
///
|
||||
/// ```swift
|
||||
/// let numbers = [1, 2, 3, 4, 5].async.map {
|
||||
/// try? await Task.sleep(for: .seconds(1))
|
||||
/// return $0
|
||||
/// }
|
||||
///
|
||||
/// let shared = numbers.share()
|
||||
///
|
||||
/// // Multiple tasks can iterate concurrently
|
||||
/// let consumer1 = Task {
|
||||
/// for await value in shared {
|
||||
/// print("Consumer 1: \(value)")
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// let consumer2 = Task {
|
||||
/// for await value in shared {
|
||||
/// print("Consumer 2: \(value)")
|
||||
/// }
|
||||
/// }
|
||||
///
|
||||
/// await consumer1.value
|
||||
/// await consumer2.value
|
||||
/// ```
|
||||
///
|
||||
/// - Parameter bufferingPolicy: The policy controlling how elements are enqueued to the shared buffer. Defaults to `.bounded(1)`.
|
||||
/// - `.bounded(n)`: Limits the buffer to `n` elements, applying backpressure to the source when that limit is reached
|
||||
/// - `.bufferingOldest(n)`: Keeps the oldest `n` elements, discarding newer ones when full
|
||||
/// - `.bufferingNewest(n)`: Keeps the newest `n` elements, discarding older ones when full
|
||||
/// - `.unbounded`: Allows unlimited buffering (use with caution)
|
||||
///
|
||||
/// - Returns: A sendable async sequence that can be safely shared across multiple concurrent tasks.
|
||||
///
|
||||
public func share(
|
||||
bufferingPolicy: AsyncBufferSequencePolicy = .bounded(1)
|
||||
) -> some AsyncSequence<Element, Failure> & Sendable {
|
||||
// The iterator is transferred to the isolation of the iterating task
|
||||
// this has to be done "unsafely" since we cannot annotate the transfer
|
||||
// however since iterating an AsyncSequence types twice has been defined
|
||||
// as invalid and one creation of the iterator is virtually a consuming
|
||||
// operation so this is safe at runtime.
|
||||
// The general principal of `.share()` is to provide a mecahnism for non-
|
||||
// shared AsyncSequence types to be shared. The parlance for those is
|
||||
// that the base AsyncSequence type is not Sendable. If the iterator
|
||||
// is not marked as `nonisolated(unsafe)` the compiler will claim that
|
||||
// the value is "Capture of 'iterator' with non-Sendable type 'Self.AsyncIterator' in a '@Sendable' closure;"
|
||||
// Since the closure returns a disconnected non-sendable value there is no
|
||||
// distinct problem here and the compiler just needs to be informed
|
||||
// that the diagnostic is overly pessimistic.
|
||||
nonisolated(unsafe) let iterator = makeAsyncIterator()
|
||||
return AsyncShareSequence<Self>(
|
||||
{
|
||||
iterator
|
||||
},
|
||||
bufferingPolicy: bufferingPolicy
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// An async sequence that enables safe concurrent sharing of a single source sequence.
|
||||
//
|
||||
// `AsyncShareSequence` wraps a base async sequence and allows multiple concurrent iterators
|
||||
// to consume elements from the same source. It handles all the complexity of coordinating
|
||||
// between multiple consumers, buffering elements, and managing the lifecycle of the underlying
|
||||
// iteration.
|
||||
//
|
||||
// ## Key Features
|
||||
//
|
||||
// **Single Source Iteration**: The base sequence's iterator is created and consumed only once
|
||||
// **Concurrent Safe**: Multiple tasks can safely iterate simultaneously
|
||||
// **Configurable Buffering**: Supports various buffering strategies for different use cases
|
||||
// **Automatic Cleanup**: Properly manages resources and cancellation across all consumers
|
||||
//
|
||||
// ## Internal Architecture
|
||||
//
|
||||
// The implementation uses several key components:
|
||||
// `Side`: Represents a single consumer's iteration state
|
||||
// `Iteration`: Coordinates all consumers and manages the shared buffer
|
||||
// `Extent`: Manages the overall lifecycle and cleanup
|
||||
//
|
||||
// This type is typically not used directly; instead, use the `share()` method on any
|
||||
// async sequence that meets the sendability requirements.
|
||||
@available(AsyncAlgorithms 1.1, *)
|
||||
struct AsyncShareSequence<Base: AsyncSequence>: Sendable
|
||||
where Base.Element: Sendable, Base: SendableMetatype, Base.AsyncIterator: SendableMetatype {
|
||||
// Represents a single consumer's connection to the shared sequence.
|
||||
//
|
||||
// Each iterator of the shared sequence creates its own `Side` instance, which tracks
|
||||
// that consumer's position in the shared buffer and manages its continuation for
|
||||
// async iteration. The `Side` automatically registers itself with the central
|
||||
// `Iteration` coordinator and cleans up when deallocated.
|
||||
//
|
||||
// ## Lifecycle
|
||||
//
|
||||
// **Creation**: Automatically registers with the iteration coordinator
|
||||
// **Usage**: Tracks buffer position and manages async continuations
|
||||
// **Cleanup**: Automatically unregisters and cancels pending operations on deinit
|
||||
final class Side {
|
||||
// Tracks the state of a single consumer's iteration.
|
||||
//
|
||||
// - `continuation`: The continuation waiting for the next element (nil if not waiting)
|
||||
// - `position`: The consumer's current position in the shared buffer
|
||||
struct State {
|
||||
var continuation: UnsafeContinuation<Result<Element?, Failure>, Never>?
|
||||
var position = 0
|
||||
|
||||
// Creates a new state with the position adjusted by the given offset.
|
||||
//
|
||||
// This is used when the shared buffer is trimmed to maintain correct
|
||||
// relative positioning for this consumer.
|
||||
//
|
||||
// - Parameter adjustment: The number of positions to subtract from the current position
|
||||
// - Returns: A new `State` with the adjusted position
|
||||
func offset(_ adjustment: Int) -> State {
|
||||
State(continuation: continuation, position: position - adjustment)
|
||||
}
|
||||
}
|
||||
|
||||
let iteration: Iteration
|
||||
let id: Int
|
||||
|
||||
init(_ iteration: Iteration) {
|
||||
self.iteration = iteration
|
||||
id = iteration.registerSide()
|
||||
}
|
||||
|
||||
deinit {
|
||||
iteration.unregisterSide(id)
|
||||
}
|
||||
|
||||
func next(isolation actor: isolated (any Actor)?) async throws(Failure) -> Element? {
|
||||
try await iteration.next(isolation: actor, id: id)
|
||||
}
|
||||
}
|
||||
|
||||
// The central coordinator that manages the shared iteration state.
|
||||
//
|
||||
// `Iteration` is responsible for:
|
||||
// Managing the single background task that consumes the source sequence
|
||||
// Coordinating between multiple consumer sides
|
||||
// Buffering elements according to the specified policy
|
||||
// Handling backpressure and flow control
|
||||
// Managing cancellation and cleanup
|
||||
//
|
||||
// ## Thread Safety
|
||||
//
|
||||
// All operations are synchronized using a `Mutex` to ensure thread-safe access
|
||||
// to the shared state across multiple concurrent consumers.
|
||||
final class Iteration: Sendable {
|
||||
// Represents the state of the background task that consumes the source sequence.
|
||||
//
|
||||
// The iteration task goes through several states during its lifecycle:
|
||||
// `pending`: Initial state, holds the factory to create the iterator
|
||||
// `starting`: Transitional state while the task is being created
|
||||
// `running`: Active state with a running background task
|
||||
// `cancelled`: Terminal state when the iteration has been cancelled
|
||||
enum IteratingTask {
|
||||
case pending(@Sendable () -> sending Base.AsyncIterator)
|
||||
case starting
|
||||
case running(Task<Void, Never>)
|
||||
case cancelled
|
||||
|
||||
var isStarting: Bool {
|
||||
switch self {
|
||||
case .starting: true
|
||||
default: false
|
||||
}
|
||||
}
|
||||
|
||||
func cancel() {
|
||||
switch self {
|
||||
case .running(let task):
|
||||
task.cancel()
|
||||
default:
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
// The complete shared state for coordinating all aspects of the shared iteration.
|
||||
//
|
||||
// This state is protected by a mutex and contains all the information needed
|
||||
// to coordinate between multiple consumers, manage buffering, and control
|
||||
// the background iteration task.
|
||||
struct State: Sendable {
|
||||
// Defines how elements are stored and potentially discarded in the shared buffer.
|
||||
//
|
||||
// `unbounded`: Store all elements without limit (may cause memory growth)
|
||||
// `bufferingOldest(Int)`: Keep only the oldest N elements, ignore newer ones when full
|
||||
// `bufferingNewest(Int)`: Keep only the newest N elements, discard older ones when full
|
||||
enum StoragePolicy: Sendable {
|
||||
case unbounded
|
||||
case bufferingOldest(Int)
|
||||
case bufferingNewest(Int)
|
||||
}
|
||||
|
||||
var generation = 0
|
||||
var sides = [Int: Side.State]()
|
||||
var iteratingTask: IteratingTask
|
||||
private(set) var buffer = Deque<Element>()
|
||||
private(set) var finished = false
|
||||
private(set) var failure: Failure?
|
||||
var cancelled = false
|
||||
var limit: UnsafeContinuation<Bool, Never>?
|
||||
var demand: UnsafeContinuation<Void, Never>?
|
||||
|
||||
let storagePolicy: StoragePolicy
|
||||
|
||||
init(
|
||||
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
|
||||
bufferingPolicy: AsyncBufferSequencePolicy
|
||||
) {
|
||||
self.iteratingTask = .pending(iteratorFactory)
|
||||
switch bufferingPolicy.policy {
|
||||
case .bounded: self.storagePolicy = .unbounded
|
||||
case .bufferingOldest(let bound): self.storagePolicy = .bufferingOldest(bound)
|
||||
case .bufferingNewest(let bound): self.storagePolicy = .bufferingNewest(bound)
|
||||
case .unbounded: self.storagePolicy = .unbounded
|
||||
}
|
||||
}
|
||||
|
||||
// Removes elements from the front of the buffer that all consumers have already processed.
|
||||
//
|
||||
// This method finds the minimum position across all active consumers and removes
|
||||
// that many elements from the front of the buffer. It then adjusts all consumer
|
||||
// positions to account for the removed elements, maintaining their relative positions.
|
||||
//
|
||||
// This optimization prevents the buffer from growing indefinitely when all consumers
|
||||
// are keeping pace with each other.
|
||||
mutating func trimBuffer() {
|
||||
if let minimumIndex = sides.values.map({ $0.position }).min(), minimumIndex > 0 {
|
||||
buffer.removeFirst(minimumIndex)
|
||||
sides = sides.mapValues {
|
||||
$0.offset(minimumIndex)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Private state machine transitions for the emission of a given value.
|
||||
//
|
||||
// This method ensures the continuations are properly consumed when emitting values
|
||||
// and returns those continuations for resumption.
|
||||
private mutating func _emit<T>(
|
||||
_ value: T,
|
||||
limit: Int
|
||||
) -> (T, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) {
|
||||
let belowLimit = buffer.count < limit || limit == 0
|
||||
defer {
|
||||
if belowLimit {
|
||||
self.limit = nil
|
||||
}
|
||||
demand = nil
|
||||
}
|
||||
guard case .cancelled = iteratingTask else {
|
||||
return (value, belowLimit ? self.limit : nil, demand, false)
|
||||
}
|
||||
return (value, belowLimit ? self.limit : nil, demand, true)
|
||||
}
|
||||
|
||||
// Internal state machine transitions for the emission of a given value.
|
||||
//
|
||||
// This method ensures the continuations are properly consumed when emitting values
|
||||
// and returns those continuations for resumption.
|
||||
//
|
||||
// If no limit is specified it interprets that as an unbounded limit.
|
||||
mutating func emit<T>(
|
||||
_ value: T,
|
||||
limit: Int?
|
||||
) -> (T, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) {
|
||||
return _emit(value, limit: limit ?? .max)
|
||||
}
|
||||
|
||||
// Adds an element to the buffer according to the configured storage policy.
|
||||
//
|
||||
// The behavior depends on the storage policy:
|
||||
// **Unbounded**: Always appends the element
|
||||
// **Buffering Oldest**: Appends only if under the limit, otherwise ignores the element
|
||||
// **Buffering Newest**: Appends if under the limit, otherwise removes the oldest and appends
|
||||
//
|
||||
// - Parameter element: The element to add to the buffer
|
||||
mutating func enqueue(_ element: Element) {
|
||||
let count = buffer.count
|
||||
|
||||
switch storagePolicy {
|
||||
case .unbounded:
|
||||
buffer.append(element)
|
||||
case .bufferingOldest(let limit):
|
||||
if count < limit {
|
||||
buffer.append(element)
|
||||
}
|
||||
case .bufferingNewest(let limit):
|
||||
if count < limit {
|
||||
buffer.append(element)
|
||||
} else if count > 0 {
|
||||
buffer.removeFirst()
|
||||
buffer.append(element)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
mutating func finish() {
|
||||
finished = true
|
||||
}
|
||||
|
||||
mutating func fail(_ error: Failure) {
|
||||
finished = true
|
||||
failure = error
|
||||
}
|
||||
}
|
||||
|
||||
let state: Mutex<State>
|
||||
let limit: Int?
|
||||
|
||||
init(
|
||||
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
|
||||
bufferingPolicy: AsyncBufferSequencePolicy
|
||||
) {
|
||||
state = Mutex(State(iteratorFactory, bufferingPolicy: bufferingPolicy))
|
||||
switch bufferingPolicy.policy {
|
||||
case .bounded(let limit):
|
||||
self.limit = limit
|
||||
default:
|
||||
self.limit = nil
|
||||
}
|
||||
}
|
||||
|
||||
func cancel() {
|
||||
let (task, limitContinuation, demand, cancelled) = state.withLock {
|
||||
state -> (IteratingTask?, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) in
|
||||
guard state.sides.count == 0 else {
|
||||
state.cancelled = true
|
||||
return state.emit(nil, limit: limit)
|
||||
}
|
||||
defer {
|
||||
state.iteratingTask = .cancelled
|
||||
state.cancelled = true
|
||||
}
|
||||
return state.emit(state.iteratingTask, limit: limit)
|
||||
}
|
||||
task?.cancel()
|
||||
limitContinuation?.resume(returning: cancelled)
|
||||
demand?.resume()
|
||||
}
|
||||
|
||||
func registerSide() -> Int {
|
||||
state.withLock { state in
|
||||
defer { state.generation += 1 }
|
||||
state.sides[state.generation] = Side.State()
|
||||
return state.generation
|
||||
}
|
||||
}
|
||||
|
||||
func unregisterSide(_ id: Int) {
|
||||
let (side, continuation, cancelled, iteratingTaskToCancel) = state.withLock {
|
||||
state -> (Side.State?, UnsafeContinuation<Bool, Never>?, Bool, IteratingTask?) in
|
||||
let side = state.sides.removeValue(forKey: id)
|
||||
state.trimBuffer()
|
||||
let cancelRequested = state.sides.count == 0 && state.cancelled
|
||||
guard let limit, state.buffer.count < limit else {
|
||||
guard case .cancelled = state.iteratingTask else {
|
||||
defer {
|
||||
if cancelRequested {
|
||||
state.iteratingTask = .cancelled
|
||||
}
|
||||
}
|
||||
return (side, nil, false, cancelRequested ? state.iteratingTask : nil)
|
||||
}
|
||||
return (side, nil, true, nil)
|
||||
}
|
||||
defer { state.limit = nil }
|
||||
guard case .cancelled = state.iteratingTask else {
|
||||
defer {
|
||||
if cancelRequested {
|
||||
state.iteratingTask = .cancelled
|
||||
}
|
||||
}
|
||||
return (side, state.limit, false, cancelRequested ? state.iteratingTask : nil)
|
||||
}
|
||||
return (side, state.limit, true, nil)
|
||||
}
|
||||
if let continuation {
|
||||
continuation.resume(returning: cancelled)
|
||||
}
|
||||
if let side {
|
||||
side.continuation?.resume(returning: .success(nil))
|
||||
}
|
||||
if let iteratingTaskToCancel {
|
||||
iteratingTaskToCancel.cancel()
|
||||
}
|
||||
}
|
||||
|
||||
func iterate() async -> Bool {
|
||||
if let limit, limit > 0 {
|
||||
let cancelled = await withUnsafeContinuation { (continuation: UnsafeContinuation<Bool, Never>) in
|
||||
let (resume, cancelled) = state.withLock { state -> (UnsafeContinuation<Bool, Never>?, Bool) in
|
||||
guard state.buffer.count >= limit else {
|
||||
assert(state.limit == nil)
|
||||
guard case .cancelled = state.iteratingTask else {
|
||||
return (continuation, false)
|
||||
}
|
||||
return (continuation, true)
|
||||
}
|
||||
state.limit = continuation
|
||||
guard case .cancelled = state.iteratingTask else {
|
||||
return (nil, false)
|
||||
}
|
||||
return (nil, true)
|
||||
}
|
||||
if let resume {
|
||||
resume.resume(returning: cancelled)
|
||||
}
|
||||
}
|
||||
if cancelled {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
// await a demand
|
||||
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
|
||||
let hasPendingDemand = state.withLock { state in
|
||||
for (_, side) in state.sides {
|
||||
if side.continuation != nil {
|
||||
return true
|
||||
}
|
||||
}
|
||||
state.demand = continuation
|
||||
return false
|
||||
}
|
||||
if hasPendingDemand {
|
||||
continuation.resume()
|
||||
}
|
||||
}
|
||||
return state.withLock { state in
|
||||
switch state.iteratingTask {
|
||||
case .cancelled:
|
||||
return false
|
||||
default:
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func cancel(id: Int) {
|
||||
unregisterSide(id) // doubly unregistering is idempotent but has a side effect of emitting nil if present
|
||||
}
|
||||
|
||||
struct Resumption {
|
||||
let continuation: UnsafeContinuation<Result<Element?, Failure>, Never>
|
||||
let result: Result<Element?, Failure>
|
||||
|
||||
func resume() {
|
||||
continuation.resume(returning: result)
|
||||
}
|
||||
}
|
||||
|
||||
func emit(_ result: Result<Element?, Failure>) {
|
||||
let (resumptions, limitContinuation, demandContinuation, cancelled) = state.withLock {
|
||||
state -> ([Resumption], UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool) in
|
||||
var resumptions = [Resumption]()
|
||||
switch result {
|
||||
case .success(let element):
|
||||
if let element {
|
||||
state.enqueue(element)
|
||||
} else {
|
||||
state.finish()
|
||||
}
|
||||
case .failure(let failure):
|
||||
state.fail(failure)
|
||||
}
|
||||
for (id, side) in state.sides {
|
||||
if let continuation = side.continuation {
|
||||
if side.position < state.buffer.count {
|
||||
resumptions.append(Resumption(continuation: continuation, result: .success(state.buffer[side.position])))
|
||||
state.sides[id]?.position += 1
|
||||
state.sides[id]?.continuation = nil
|
||||
} else if state.finished {
|
||||
state.sides[id]?.continuation = nil
|
||||
if let failure = state.failure {
|
||||
resumptions.append(Resumption(continuation: continuation, result: .failure(failure)))
|
||||
} else {
|
||||
resumptions.append(Resumption(continuation: continuation, result: .success(nil)))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
state.trimBuffer()
|
||||
return state.emit(resumptions, limit: limit)
|
||||
}
|
||||
|
||||
if let limitContinuation {
|
||||
limitContinuation.resume(returning: cancelled)
|
||||
}
|
||||
if let demandContinuation {
|
||||
demandContinuation.resume()
|
||||
}
|
||||
for resumption in resumptions {
|
||||
resumption.resume()
|
||||
}
|
||||
}
|
||||
|
||||
private func nextIteration(
|
||||
_ id: Int
|
||||
) async -> Result<AsyncShareSequence<Base>.Element?, AsyncShareSequence<Base>.Failure> {
|
||||
return await withTaskCancellationHandler {
|
||||
await withUnsafeContinuation { continuation in
|
||||
let (res, limitContinuation, demandContinuation, cancelled) = state.withLock {
|
||||
state -> (
|
||||
Result<Element?, Failure>?, UnsafeContinuation<Bool, Never>?, UnsafeContinuation<Void, Never>?, Bool
|
||||
) in
|
||||
guard let side = state.sides[id] else {
|
||||
return state.emit(.success(nil), limit: limit)
|
||||
}
|
||||
if side.position < state.buffer.count {
|
||||
// There's an element available at this position
|
||||
let element = state.buffer[side.position]
|
||||
state.sides[id]?.position += 1
|
||||
state.trimBuffer()
|
||||
return state.emit(.success(element), limit: limit)
|
||||
} else {
|
||||
// Position is beyond the buffer
|
||||
if let failure = state.failure {
|
||||
return state.emit(.failure(failure), limit: limit)
|
||||
} else if state.finished {
|
||||
return state.emit(.success(nil), limit: limit)
|
||||
} else {
|
||||
state.sides[id]?.continuation = continuation
|
||||
return state.emit(nil, limit: limit)
|
||||
}
|
||||
}
|
||||
}
|
||||
if let limitContinuation {
|
||||
limitContinuation.resume(returning: cancelled)
|
||||
}
|
||||
if let demandContinuation {
|
||||
demandContinuation.resume()
|
||||
}
|
||||
if let res {
|
||||
continuation.resume(returning: res)
|
||||
}
|
||||
}
|
||||
} onCancel: {
|
||||
cancel(id: id)
|
||||
}
|
||||
}
|
||||
|
||||
private func iterationLoop(factory: @Sendable () -> sending Base.AsyncIterator) async {
|
||||
var iterator = factory()
|
||||
do {
|
||||
while await iterate() {
|
||||
if let element = try await iterator.next() {
|
||||
emit(.success(element))
|
||||
} else {
|
||||
emit(.success(nil))
|
||||
}
|
||||
}
|
||||
} catch {
|
||||
emit(.failure(error as! Failure))
|
||||
}
|
||||
}
|
||||
|
||||
func next(isolation actor: isolated (any Actor)?, id: Int) async throws(Failure) -> Element? {
|
||||
let (factory, cancelled) = state.withLock { state -> ((@Sendable () -> sending Base.AsyncIterator)?, Bool) in
|
||||
switch state.iteratingTask {
|
||||
case .pending(let factory):
|
||||
state.iteratingTask = .starting
|
||||
return (factory, false)
|
||||
case .cancelled:
|
||||
return (nil, true)
|
||||
default:
|
||||
return (nil, false)
|
||||
}
|
||||
}
|
||||
if cancelled { return nil }
|
||||
if let factory {
|
||||
let task: Task<Void, Never>
|
||||
// for the fancy dance of availability and canImport see the comment on the next check for details
|
||||
#if swift(>=6.2)
|
||||
if #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) {
|
||||
task = Task(name: "Share Iteration") { [factory, self] in
|
||||
await iterationLoop(factory: factory)
|
||||
}
|
||||
} else {
|
||||
task = Task.detached(name: "Share Iteration") { [factory, self] in
|
||||
await iterationLoop(factory: factory)
|
||||
}
|
||||
}
|
||||
#else
|
||||
task = Task.detached { [factory, self] in
|
||||
await iterationLoop(factory: factory)
|
||||
}
|
||||
#endif
|
||||
// Known Issue: there is a very small race where the task may not get a priority escalation during startup
|
||||
// this unfortuantely cannot be avoided since the task should ideally not be formed within the critical
|
||||
// region of the state. Since that could lead to potential deadlocks in low-core-count systems.
|
||||
// That window is relatively small and can be revisited if a suitable proof of safe behavior can be
|
||||
// determined.
|
||||
state.withLock { state in
|
||||
precondition(state.iteratingTask.isStarting)
|
||||
state.iteratingTask = .running(task)
|
||||
}
|
||||
}
|
||||
|
||||
// withTaskPriorityEscalationHandler is only available for the '26 releases and the 6.2 version of
|
||||
// the _Concurrency library. This menas for Darwin based OSes we have to have a fallback at runtime,
|
||||
// and for non-darwin OSes we need to verify against the ability to import that version.
|
||||
// Using this priority escalation means that the base task can avoid being detached.
|
||||
//
|
||||
// This is disabled for now until the 9999 availability is removed from `withTaskPriorityEscalationHandler`
|
||||
#if false // TODO: remove when this is resolved
|
||||
guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else {
|
||||
return try await nextIteration(id).get()
|
||||
}
|
||||
return try await withTaskPriorityEscalationHandler {
|
||||
return await nextIteration(id)
|
||||
} onPriorityEscalated: { old, new in
|
||||
let task = state.withLock { state -> Task<Void, Never>? in
|
||||
switch state.iteratingTask {
|
||||
case .running(let task):
|
||||
return task
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
task?.escalatePriority(to: new)
|
||||
}.get()
|
||||
#else
|
||||
return try await nextIteration(id).get()
|
||||
#endif
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
// Manages the lifecycle of the shared iteration.
|
||||
//
|
||||
// `Extent` serves as the ownership boundary for the shared sequence. When the
|
||||
// `AsyncShareSequence` itself is deallocated, the `Extent` ensures that the
|
||||
// background iteration task is properly cancelled and all resources are cleaned up.
|
||||
//
|
||||
// This design allows multiple iterators to safely reference the same underlying
|
||||
// iteration coordinator while ensuring proper cleanup when the shared sequence
|
||||
// is no longer needed.
|
||||
final class Extent: Sendable {
|
||||
let iteration: Iteration
|
||||
|
||||
init(
|
||||
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
|
||||
bufferingPolicy: AsyncBufferSequencePolicy
|
||||
) {
|
||||
iteration = Iteration(iteratorFactory, bufferingPolicy: bufferingPolicy)
|
||||
}
|
||||
|
||||
deinit {
|
||||
iteration.cancel()
|
||||
}
|
||||
}
|
||||
|
||||
let extent: Extent
|
||||
|
||||
init(
|
||||
_ iteratorFactory: @escaping @Sendable () -> sending Base.AsyncIterator,
|
||||
bufferingPolicy: AsyncBufferSequencePolicy
|
||||
) {
|
||||
extent = Extent(iteratorFactory, bufferingPolicy: bufferingPolicy)
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.1, *)
|
||||
extension AsyncShareSequence: AsyncSequence {
|
||||
typealias Element = Base.Element
|
||||
typealias Failure = Base.Failure
|
||||
|
||||
struct Iterator: AsyncIteratorProtocol {
|
||||
let side: Side
|
||||
|
||||
init(_ iteration: Iteration) {
|
||||
side = Side(iteration)
|
||||
}
|
||||
|
||||
mutating func next() async rethrows -> Element? {
|
||||
try await side.next(isolation: nil)
|
||||
}
|
||||
|
||||
mutating func next(isolation actor: isolated (any Actor)?) async throws(Failure) -> Element? {
|
||||
try await side.next(isolation: actor)
|
||||
}
|
||||
}
|
||||
|
||||
func makeAsyncIterator() -> Iterator {
|
||||
Iterator(extent.iteration)
|
||||
}
|
||||
}
|
||||
|
||||
#endif
|
||||
+21
-16
@@ -9,62 +9,67 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension Sequence {
|
||||
/// An asynchronous sequence containing the same elements as this sequence,
|
||||
/// but on which operations, such as `map` and `filter`, are
|
||||
/// implemented asynchronously.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public var async: AsyncLazySequence<Self> {
|
||||
AsyncLazySequence(self)
|
||||
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 algoritms based on
|
||||
/// data to interoperate with other asynchronous sequences and algorithms based on
|
||||
/// asynchronous sequences.
|
||||
///
|
||||
/// This functions similarly to `LazySequence` by accessing elemetns sequentially
|
||||
/// This functions similarly to `LazySequence` by accessing elements sequentially
|
||||
/// in the iterator's `next()` method.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
|
||||
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 {
|
||||
guard !Task.isCancelled, let value = iterator?.next() else {
|
||||
iterator = nil
|
||||
return nil
|
||||
}
|
||||
return value
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@usableFromInline
|
||||
let base: Base
|
||||
|
||||
|
||||
@usableFromInline
|
||||
init(_ base: Base) {
|
||||
self.base = base
|
||||
}
|
||||
|
||||
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeIterator())
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncLazySequence: Sendable where Base: Sendable { }
|
||||
extension AsyncLazySequence.Iterator: Sendable where Base.Iterator: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSyncSequence: Sendable where Base: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncSyncSequence.Iterator: Sendable {}
|
||||
@@ -9,47 +9,66 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
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)
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
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)
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
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 {
|
||||
@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
|
||||
guard latest else {
|
||||
return previous ?? element
|
||||
}
|
||||
return element
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public func throttle(for interval: Duration, latest: Bool = true) -> AsyncThrottleSequence<Self, ContinuousClock, Element> {
|
||||
throttle(for: interval, clock: .continuous, latest: latest)
|
||||
@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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
|
||||
@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) {
|
||||
|
||||
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
|
||||
@@ -57,33 +76,50 @@ public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncThrottleSequence: AsyncSequence {
|
||||
@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) {
|
||||
|
||||
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 = clock.now
|
||||
let start = last ?? clock.now
|
||||
repeat {
|
||||
guard let element = try await base.next() else {
|
||||
return nil
|
||||
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)
|
||||
if start.duration(to: clock.now) >= interval {
|
||||
let now = clock.now
|
||||
if start.duration(to: now) >= interval || last == nil {
|
||||
last = now
|
||||
return reduction
|
||||
} else {
|
||||
reduced = reduction
|
||||
@@ -91,14 +127,14 @@ extension AsyncThrottleSequence: AsyncSequence {
|
||||
} while true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), interval: interval, clock: clock, reducing: reducing)
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncThrottleSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension _AsyncThrottleSequence: Sendable where Base: Sendable, Element: Sendable {}
|
||||
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncThrottleSequence.Iterator: Sendable where Base.AsyncIterator: Sendable { }
|
||||
@available(*, unavailable)
|
||||
extension _AsyncThrottleSequence.Iterator: Sendable {}
|
||||
@@ -1,213 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(_:)`, `fail(_:)` and `finish()` via suspension/resume ensures that the production of values does not exceed the consumption of values from iteration. Each of these methods suspends after enqueuing the event and is resumed when the next call to `next()` on the `Iterator` is made.
|
||||
public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
|
||||
/// The iterator for an `AsyncThrowingChannel` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
let channel: AsyncThrowingChannel<Element, Failure>
|
||||
var active: Bool = true
|
||||
|
||||
init(_ channel: AsyncThrowingChannel<Element, Failure>) {
|
||||
self.channel = channel
|
||||
}
|
||||
|
||||
public mutating func next() async throws -> Element? {
|
||||
guard active else {
|
||||
return nil
|
||||
}
|
||||
let generation = channel.establish()
|
||||
do {
|
||||
let value: Element? = try await withTaskCancellationHandler { [channel] in
|
||||
channel.cancel(generation)
|
||||
} operation: {
|
||||
try await channel.next(generation)
|
||||
}
|
||||
|
||||
if let value = value {
|
||||
return value
|
||||
} else {
|
||||
active = false
|
||||
return nil
|
||||
}
|
||||
} catch {
|
||||
active = false
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct Awaiting: Hashable {
|
||||
var generation: Int
|
||||
var continuation: UnsafeContinuation<Element?, Error>?
|
||||
let cancelled: Bool
|
||||
|
||||
init(generation: Int, continuation: UnsafeContinuation<Element?, Error>) {
|
||||
self.generation = generation
|
||||
self.continuation = continuation
|
||||
cancelled = false
|
||||
}
|
||||
|
||||
init(placeholder generation: Int) {
|
||||
self.generation = generation
|
||||
self.continuation = nil
|
||||
cancelled = false
|
||||
}
|
||||
|
||||
init(cancelled generation: Int) {
|
||||
self.generation = generation
|
||||
self.continuation = nil
|
||||
cancelled = true
|
||||
}
|
||||
|
||||
func hash(into hasher: inout Hasher) {
|
||||
hasher.combine(generation)
|
||||
}
|
||||
|
||||
static func == (_ lhs: Awaiting, _ rhs: Awaiting) -> Bool {
|
||||
return lhs.generation == rhs.generation
|
||||
}
|
||||
}
|
||||
|
||||
enum Emission {
|
||||
case idle
|
||||
case pending([UnsafeContinuation<UnsafeContinuation<Element?, Error>?, Never>])
|
||||
case awaiting(Set<Awaiting>)
|
||||
|
||||
mutating func cancel(_ generation: Int) -> UnsafeContinuation<Element?, Error>? {
|
||||
switch self {
|
||||
case .awaiting(var awaiting):
|
||||
let continuation = awaiting.remove(Awaiting(placeholder: generation))?.continuation
|
||||
self = .awaiting(awaiting)
|
||||
return continuation
|
||||
case .idle:
|
||||
self = .awaiting([Awaiting(cancelled: generation)])
|
||||
return nil
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
struct State {
|
||||
var emission: Emission = .idle
|
||||
var generation = 0
|
||||
var terminal = false
|
||||
}
|
||||
|
||||
let state = ManagedCriticalState(State())
|
||||
|
||||
public init(_ elementType: Element.Type = Element.self) { }
|
||||
|
||||
func establish() -> Int {
|
||||
state.withCriticalRegion { state in
|
||||
defer { state.generation &+= 1 }
|
||||
return state.generation
|
||||
}
|
||||
}
|
||||
|
||||
func cancel(_ generation: Int) {
|
||||
state.withCriticalRegion { state in
|
||||
state.emission.cancel(generation)
|
||||
}?.resume(returning: nil)
|
||||
}
|
||||
|
||||
func next(_ generation: Int) async throws -> Element? {
|
||||
return try await withUnsafeThrowingContinuation { continuation in
|
||||
var cancelled = false
|
||||
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Error>?, Never>? in
|
||||
switch state.emission {
|
||||
case .idle:
|
||||
state.emission = .awaiting([Awaiting(generation: generation, continuation: continuation)])
|
||||
return nil
|
||||
case .pending(var sends):
|
||||
let send = sends.removeFirst()
|
||||
if sends.count == 0 {
|
||||
state.emission = .idle
|
||||
} else {
|
||||
state.emission = .pending(sends)
|
||||
}
|
||||
return UnsafeResumption(continuation: send, success: continuation)
|
||||
case .awaiting(var nexts):
|
||||
if nexts.update(with: Awaiting(generation: generation, continuation: continuation)) != nil {
|
||||
nexts.remove(Awaiting(placeholder: generation))
|
||||
cancelled = true
|
||||
}
|
||||
state.emission = .awaiting(nexts)
|
||||
return nil
|
||||
}
|
||||
}?.resume()
|
||||
if cancelled {
|
||||
continuation.resume(returning: nil)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func _send(_ result: Result<Element?, Error>) async {
|
||||
let continuation: UnsafeContinuation<Element?, Error>? = await withUnsafeContinuation { continuation in
|
||||
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Error>?, Never>? in
|
||||
if state.terminal {
|
||||
return UnsafeResumption(continuation: continuation, success: nil)
|
||||
}
|
||||
switch result {
|
||||
case .success(let value):
|
||||
if value == nil {
|
||||
state.terminal = true
|
||||
}
|
||||
case .failure:
|
||||
state.terminal = true
|
||||
}
|
||||
switch state.emission {
|
||||
case .idle:
|
||||
state.emission = .pending([continuation])
|
||||
return nil
|
||||
case .pending(var sends):
|
||||
sends.append(continuation)
|
||||
state.emission = .pending(sends)
|
||||
return nil
|
||||
case .awaiting(var nexts):
|
||||
let next = nexts.removeFirst().continuation
|
||||
if nexts.count == 0 {
|
||||
state.emission = .idle
|
||||
} else {
|
||||
state.emission = .awaiting(nexts)
|
||||
}
|
||||
return UnsafeResumption(continuation: continuation, success: next)
|
||||
}
|
||||
}?.resume()
|
||||
}
|
||||
continuation?.resume(with: result)
|
||||
}
|
||||
|
||||
/// Send an element to an awaiting iteration. This function will resume when the next call to `next()` is made.
|
||||
/// If the channel is already finished then this returns immediately
|
||||
public func send(_ element: Element) async {
|
||||
await _send(.success(element))
|
||||
}
|
||||
|
||||
/// Send an error to an awaiting iteration. This function will resume when the next call to `next()` is made.
|
||||
/// If the channel is already finished then this returns immediately
|
||||
public func fail(_ error: Error) async where Failure == Error {
|
||||
await _send(.failure(error))
|
||||
}
|
||||
|
||||
/// Send a finish to an awaiting iteration. This function will resume when the next call to `next()` is made.
|
||||
/// If the channel is already finished then this returns immediately
|
||||
public func finish() async {
|
||||
await _send(.success(nil))
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
return Iterator(self)
|
||||
}
|
||||
}
|
||||
@@ -9,32 +9,44 @@
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given error-throwing closure.
|
||||
///
|
||||
/// This can be seen as applying the reduce function to each element and
|
||||
/// providing the initial value followed by these results as an asynchronous sequence.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
/// - transform: A closure that combines the previously reduced result and
|
||||
/// the next element in the receiving asynchronous sequence and returns
|
||||
/// the result. If the closure throws an error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async throws -> Result) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
|
||||
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.
|
||||
/// Starting from the initial value, this combines each element of the base
|
||||
/// asynchronous sequence with the running result and emits each intermediate
|
||||
/// result. The initial value itself is not emitted, so the first element of
|
||||
/// the returned sequence is the result of combining the initial value with
|
||||
/// the first element of the base sequence. If the base sequence is empty, the
|
||||
/// returned sequence is also empty.
|
||||
///
|
||||
/// - Parameters:
|
||||
/// - initial: The value to use as the initial value.
|
||||
@@ -42,81 +54,97 @@ extension AsyncSequence {
|
||||
/// the next element in the receiving asynchronous sequence, mutating the
|
||||
/// previous result instead of returning a value. If the closure throws an
|
||||
/// error, the sequence throws.
|
||||
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
|
||||
/// elements.
|
||||
/// - Returns: An asynchronous sequence of the reduced elements.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async throws -> Void) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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) {
|
||||
init(
|
||||
_ base: Base,
|
||||
initial: Element,
|
||||
transform: @Sendable @escaping (inout Element, Base.Element) async throws -> Void
|
||||
) {
|
||||
self.base = base
|
||||
self.initial = initial
|
||||
self.transform = transform
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
|
||||
/// The iterator for an `AsyncThrowingExclusiveReductionsSequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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) {
|
||||
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 }
|
||||
guard var 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 {
|
||||
guard let value = value else {
|
||||
current = nil
|
||||
return nil
|
||||
}
|
||||
do {
|
||||
try await transform(&result, value)
|
||||
current = result
|
||||
return result
|
||||
} catch {
|
||||
current = nil
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
|
||||
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncThrowingExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable {}
|
||||
@@ -1,3 +1,15 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncSequence {
|
||||
/// Returns an asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using the given error-throwing closure.
|
||||
@@ -16,6 +28,7 @@ extension AsyncSequence {
|
||||
/// 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func reductions(
|
||||
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
|
||||
@@ -26,14 +39,15 @@ extension AsyncSequence {
|
||||
|
||||
/// An asynchronous sequence containing the accumulated results of combining the
|
||||
/// elements of the asynchronous sequence using a given error-throwing closure.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@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
|
||||
@@ -41,10 +55,12 @@ public struct AsyncThrowingInclusiveReductionsSequence<Base: AsyncSequence> {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
|
||||
public typealias Element = Base.Element
|
||||
|
||||
|
||||
/// The iterator for an `AsyncThrowingInclusiveReductionsSequence` instance.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@frozen
|
||||
public struct Iterator: AsyncIteratorProtocol {
|
||||
@usableFromInline
|
||||
@@ -57,7 +73,7 @@ extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
|
||||
internal let transform: @Sendable (Base.Element, Base.Element) async throws -> Base.Element
|
||||
|
||||
@inlinable
|
||||
internal init(
|
||||
init(
|
||||
_ iterator: Base.AsyncIterator,
|
||||
transform: @Sendable @escaping (Base.Element, Base.Element) async throws -> Base.Element
|
||||
) {
|
||||
@@ -82,11 +98,15 @@ extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
@inlinable
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base.makeAsyncIterator(), transform: transform)
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncThrowingInclusiveReductionsSequence: Sendable where Base: Sendable { }
|
||||
extension AsyncThrowingInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncThrowingInclusiveReductionsSequence: Sendable where Base: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncThrowingInclusiveReductionsSequence.Iterator: Sendable {}
|
||||
@@ -10,85 +10,82 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
/// An `AsyncSequence` that produces elements at regular intervals.
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
@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
|
||||
}
|
||||
|
||||
func nextDeadline(_ clock: C) -> C.Instant {
|
||||
let now = clock.now
|
||||
let last = self.last ?? now
|
||||
let next = last.advanced(by: interval)
|
||||
if next < now {
|
||||
return last.advanced(by: interval * Int(((next.duration(to: now)) / interval).rounded(.up)))
|
||||
} else {
|
||||
return next
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
public mutating func next() async -> C.Instant? {
|
||||
guard let clock = clock else {
|
||||
guard let clock = self.clock else {
|
||||
return nil
|
||||
}
|
||||
let next = nextDeadline(clock)
|
||||
|
||||
let next = (self.last ?? clock.now).advanced(by: self.interval)
|
||||
do {
|
||||
try await clock.sleep(until: next, tolerance: tolerance)
|
||||
try await clock.sleep(until: next, tolerance: self.tolerance)
|
||||
} catch {
|
||||
self.clock = nil
|
||||
return nil
|
||||
}
|
||||
let now = clock.now
|
||||
last = next
|
||||
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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
@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> {
|
||||
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 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
@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> {
|
||||
public static func repeating(
|
||||
every interval: Duration,
|
||||
tolerance: Duration? = nil
|
||||
) -> AsyncTimerSequence<SuspendingClock> {
|
||||
return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: SuspendingClock())
|
||||
}
|
||||
}
|
||||
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncTimerSequence: Sendable { }
|
||||
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
|
||||
extension AsyncTimerSequence: Sendable {}
|
||||
|
||||
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
|
||||
extension AsyncTimerSequence.Iterator: Sendable { }
|
||||
@available(*, unavailable)
|
||||
extension AsyncTimerSequence.Iterator: Sendable {}
|
||||
@@ -1,165 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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>
|
||||
where Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base1.AsyncIterator: Sendable,
|
||||
Base2.AsyncIterator: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable {
|
||||
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>: Sendable
|
||||
where Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base1.AsyncIterator: Sendable,
|
||||
Base2.AsyncIterator: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable {
|
||||
let base1: Base1
|
||||
let base2: Base2
|
||||
|
||||
init(_ base1: Base1, _ base2: Base2) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncZip2Sequence: AsyncSequence {
|
||||
public typealias Element = (Base1.Element, Base2.Element)
|
||||
|
||||
/// The iterator for an `AsyncZip2Sequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
var base1: Base1.AsyncIterator?
|
||||
var base2: Base2.AsyncIterator?
|
||||
|
||||
enum Partial: Sendable {
|
||||
case first(Result<Base1.Element?, Error>, Base1.AsyncIterator)
|
||||
case second(Result<Base2.Element?, Error>, Base2.AsyncIterator)
|
||||
}
|
||||
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> (Base1.Element, Base2.Element)? {
|
||||
func iteration(
|
||||
_ group: inout TaskGroup<Partial>,
|
||||
_ value1: inout Base1.Element?,
|
||||
_ value2: inout Base2.Element?,
|
||||
_ iterator1: inout Base1.AsyncIterator?,
|
||||
_ iterator2: inout Base2.AsyncIterator?
|
||||
) async -> Result<(Base1.Element, Base2.Element)?, Error>? {
|
||||
guard let partial = await group.next() else {
|
||||
return .success(nil)
|
||||
}
|
||||
switch partial {
|
||||
case .first(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value1 = value
|
||||
iterator1 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
case .second(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value2 = value
|
||||
iterator2 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
guard let base1 = base1, let base2 = base2 else {
|
||||
return nil
|
||||
}
|
||||
|
||||
let (result, iter1, iter2) = await withTaskGroup(of: Partial.self) { group -> (Result<(Base1.Element, Base2.Element)?, Error>, Base1.AsyncIterator?, Base2.AsyncIterator?) in
|
||||
group.addTask {
|
||||
var iterator = base1
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .first(.success(value), iterator)
|
||||
} catch {
|
||||
return .first(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
group.addTask {
|
||||
var iterator = base2
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .second(.success(value), iterator)
|
||||
} catch {
|
||||
return .second(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
var res1: Base1.Element?
|
||||
var res2: Base2.Element?
|
||||
var iter1: Base1.AsyncIterator?
|
||||
var iter2: Base2.AsyncIterator?
|
||||
|
||||
if let result = await iteration(&group, &res1, &res2, &iter1, &iter2) {
|
||||
return (result, nil, nil)
|
||||
}
|
||||
if let result = await iteration(&group, &res1, &res2, &iter1, &iter2) {
|
||||
return (result, nil, nil)
|
||||
}
|
||||
guard let res1 = res1, let res2 = res2 else {
|
||||
return (.success(nil), nil, nil)
|
||||
}
|
||||
|
||||
return (.success((res1, res2)), iter1, iter2)
|
||||
}
|
||||
do {
|
||||
guard let value = try result._rethrowGet() else {
|
||||
self.base1 = nil
|
||||
self.base2 = nil
|
||||
return nil
|
||||
}
|
||||
self.base1 = iter1
|
||||
self.base2 = iter2
|
||||
return value
|
||||
} catch {
|
||||
self.base1 = nil
|
||||
self.base2 = nil
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -1,210 +0,0 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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>
|
||||
where Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base3: Sendable,
|
||||
Base1.AsyncIterator: Sendable,
|
||||
Base2.AsyncIterator: Sendable,
|
||||
Base3.AsyncIterator: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
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>: Sendable
|
||||
where Base1: Sendable,
|
||||
Base2: Sendable,
|
||||
Base3: Sendable,
|
||||
Base1.AsyncIterator: Sendable,
|
||||
Base2.AsyncIterator: Sendable,
|
||||
Base3.AsyncIterator: Sendable,
|
||||
Base1.Element: Sendable,
|
||||
Base2.Element: Sendable,
|
||||
Base3.Element: Sendable {
|
||||
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
|
||||
}
|
||||
}
|
||||
|
||||
extension AsyncZip3Sequence: AsyncSequence {
|
||||
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
|
||||
|
||||
/// The iterator for an `AsyncZip3Sequence` instance.
|
||||
public struct Iterator: AsyncIteratorProtocol, Sendable {
|
||||
var base1: Base1.AsyncIterator?
|
||||
var base2: Base2.AsyncIterator?
|
||||
var base3: Base3.AsyncIterator?
|
||||
|
||||
enum Partial: Sendable {
|
||||
case first(Result<Base1.Element?, Error>, Base1.AsyncIterator)
|
||||
case second(Result<Base2.Element?, Error>, Base2.AsyncIterator)
|
||||
case third(Result<Base3.Element?, Error>, Base3.AsyncIterator)
|
||||
}
|
||||
|
||||
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator, _ base3: Base3.AsyncIterator) {
|
||||
self.base1 = base1
|
||||
self.base2 = base2
|
||||
self.base3 = base3
|
||||
}
|
||||
|
||||
public mutating func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element)? {
|
||||
func iteration(
|
||||
_ group: inout TaskGroup<Partial>,
|
||||
_ value1: inout Base1.Element?,
|
||||
_ value2: inout Base2.Element?,
|
||||
_ value3: inout Base3.Element?,
|
||||
_ iterator1: inout Base1.AsyncIterator?,
|
||||
_ iterator2: inout Base2.AsyncIterator?,
|
||||
_ iterator3: inout Base3.AsyncIterator?
|
||||
) async -> Result<(Base1.Element, Base2.Element, Base3.Element)?, Error>? {
|
||||
guard let partial = await group.next() else {
|
||||
return .success(nil)
|
||||
}
|
||||
switch partial {
|
||||
case .first(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value1 = value
|
||||
iterator1 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
case .second(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value2 = value
|
||||
iterator2 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
case .third(let res, let iter):
|
||||
switch res {
|
||||
case .success(let value):
|
||||
if let value = value {
|
||||
value3 = value
|
||||
iterator3 = iter
|
||||
return nil
|
||||
} else {
|
||||
group.cancelAll()
|
||||
return .success(nil)
|
||||
}
|
||||
case .failure(let error):
|
||||
group.cancelAll()
|
||||
return .failure(error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
guard let base1 = base1, let base2 = base2, let base3 = base3 else {
|
||||
return nil
|
||||
}
|
||||
|
||||
let (result, iter1, iter2, iter3) = await withTaskGroup(of: Partial.self) { group -> (Result<(Base1.Element, Base2.Element, Base3.Element)?, Error>, Base1.AsyncIterator?, Base2.AsyncIterator?, Base3.AsyncIterator?) in
|
||||
group.addTask {
|
||||
var iterator = base1
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .first(.success(value), iterator)
|
||||
} catch {
|
||||
return .first(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
group.addTask {
|
||||
var iterator = base2
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .second(.success(value), iterator)
|
||||
} catch {
|
||||
return .second(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
group.addTask {
|
||||
var iterator = base3
|
||||
do {
|
||||
let value = try await iterator.next()
|
||||
return .third(.success(value), iterator)
|
||||
} catch {
|
||||
return .third(.failure(error), iterator)
|
||||
}
|
||||
}
|
||||
var res1: Base1.Element?
|
||||
var res2: Base2.Element?
|
||||
var res3: Base3.Element?
|
||||
var iter1: Base1.AsyncIterator?
|
||||
var iter2: Base2.AsyncIterator?
|
||||
var iter3: Base3.AsyncIterator?
|
||||
|
||||
if let result = await iteration(&group, &res1, &res2, &res3, &iter1, &iter2, &iter3) {
|
||||
return (result, nil, nil, nil)
|
||||
}
|
||||
if let result = await iteration(&group, &res1, &res2, &res3, &iter1, &iter2, &iter3) {
|
||||
return (result, nil, nil, nil)
|
||||
}
|
||||
if let result = await iteration(&group, &res1, &res2, &res3, &iter1, &iter2, &iter3) {
|
||||
return (result, nil, nil, nil)
|
||||
}
|
||||
guard let res1 = res1, let res2 = res2, let res3 = res3 else {
|
||||
return (.success(nil), nil, nil, nil)
|
||||
}
|
||||
|
||||
return (.success((res1, res2, res3)), iter1, iter2, iter3)
|
||||
}
|
||||
do {
|
||||
guard let value = try result._rethrowGet() else {
|
||||
self.base1 = nil
|
||||
self.base2 = nil
|
||||
self.base3 = nil
|
||||
return nil
|
||||
}
|
||||
self.base1 = iter1
|
||||
self.base2 = iter2
|
||||
self.base3 = iter3
|
||||
return value
|
||||
} catch {
|
||||
self.base1 = nil
|
||||
self.base2 = nil
|
||||
self.base3 = nil
|
||||
throw error
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public func makeAsyncIterator() -> Iterator {
|
||||
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public func buffer(
|
||||
policy: AsyncBufferSequencePolicy
|
||||
) -> AsyncBufferSequence<Self> {
|
||||
AsyncBufferSequence<Self>(base: self, policy: policy)
|
||||
}
|
||||
}
|
||||
|
||||
/// A policy dictating the buffering behaviour of an ``AsyncBufferSequence``
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence {
|
||||
// Internal implementation note:
|
||||
// This type origianlly had no requirement that the element is actually Sendable. However,
|
||||
// that is technically an implementation detail hole in the safety of the system, it needs
|
||||
// to specify that the element is actually Sendable since the draining mechanism passes
|
||||
// through the isolation that is in nature sending but cannot be marked as such for the
|
||||
// isolated next method.
|
||||
// In practice the users of this type are safe from isolation crossing since the Element
|
||||
// is as sendable as it is required by the base sequences the buffer is constructed from.
|
||||
enum StorageType {
|
||||
case transparent(Base.AsyncIterator)
|
||||
case bounded(storage: BoundedBufferStorage<Base>)
|
||||
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().wrapped?._rethrowGet()
|
||||
case .unbounded(let storage):
|
||||
return try await storage.next().wrapped?._rethrowGet()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension AsyncBufferSequence: Sendable where Base: Sendable {}
|
||||
|
||||
@available(*, unavailable)
|
||||
extension AsyncBufferSequence.Iterator: Sendable {}
|
||||
@@ -0,0 +1,329 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
struct BoundedBufferStateMachine<Base: AsyncSequence> {
|
||||
typealias Element = Base.Element
|
||||
typealias SuspendedProducer = UnsafeContinuation<Void, Never>
|
||||
typealias SuspendedConsumer = UnsafeContinuation<UnsafeTransfer<Result<Base.Element, Error>?>, Never>
|
||||
|
||||
// We are using UnsafeTransfer here since we have to get the elements from the task
|
||||
// into the consumer task. This is a transfer but we cannot prove this to the compiler at this point
|
||||
// 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
|
||||
guard buffer.count < limit else {
|
||||
self.state = .buffering(
|
||||
task: task,
|
||||
buffer: buffer,
|
||||
suspendedProducer: continuation,
|
||||
suspendedConsumer: nil
|
||||
)
|
||||
return .none
|
||||
}
|
||||
return .resumeProducer
|
||||
|
||||
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: UnsafeTransfer<Result<Base.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: UnsafeTransfer(.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<UnsafeTransfer<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<UnsafeTransfer<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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension BoundedBufferStateMachine: Sendable where Base: Sendable {}
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension BoundedBufferStateMachine.State: Sendable where Base: Sendable {}
|
||||
@@ -0,0 +1,158 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
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 -> UnsafeTransfer<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 UnsafeTransfer(result)
|
||||
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
return await withUnsafeContinuation {
|
||||
(continuation: UnsafeContinuation<UnsafeTransfer<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: UnsafeTransfer(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: UnsafeTransfer(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: UnsafeTransfer(Result<Base.Element, Error>.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: UnsafeTransfer(nil))
|
||||
}
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,259 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
struct UnboundedBufferStateMachine<Base: AsyncSequence> {
|
||||
typealias Element = Base.Element
|
||||
typealias SuspendedConsumer = UnsafeContinuation<UnsafeTransfer<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: UnsafeTransfer<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: UnsafeTransfer(.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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension UnboundedBufferStateMachine: Sendable where Base: Sendable {}
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
extension UnboundedBufferStateMachine.State: Sendable where Base: Sendable {}
|
||||
@@ -0,0 +1,126 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
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 -> UnsafeTransfer<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 UnsafeTransfer(result)
|
||||
case .none:
|
||||
break
|
||||
}
|
||||
|
||||
return await withUnsafeContinuation {
|
||||
(continuation: UnsafeContinuation<UnsafeTransfer<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: UnsafeTransfer(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: UnsafeTransfer(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: UnsafeTransfer(Result<Base.Element, Error>.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: UnsafeTransfer(nil))
|
||||
}
|
||||
}
|
||||
|
||||
deinit {
|
||||
self.interrupted()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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,67 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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,348 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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
|
||||
}
|
||||
|
||||
guard suspendedConsumers.isEmpty 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)
|
||||
}
|
||||
// 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
|
||||
|
||||
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)
|
||||
}
|
||||
|
||||
guard suspendedProducers.isEmpty 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
|
||||
)
|
||||
}
|
||||
// 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
|
||||
|
||||
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,143 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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(AsyncAlgorithms 1.0, *)
|
||||
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,98 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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,109 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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.
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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,773 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// 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
|
||||
@available(AsyncAlgorithms 1.0, *)
|
||||
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
|
||||
|
||||
guard let element = buffer.popFirst() 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
|
||||
)
|
||||
}
|
||||
self.state = .waitingForDemand(
|
||||
task: task,
|
||||
upstreams: upstreams,
|
||||
buffer: buffer
|
||||
)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: continuation,
|
||||
result: .success(element)
|
||||
)
|
||||
|
||||
case .upstreamsFinished(var buffer):
|
||||
self.state = .modifying
|
||||
|
||||
guard let element = buffer.popFirst() else {
|
||||
self.state = .finished
|
||||
|
||||
return .resumeDownstreamContinuationWithNil(continuation)
|
||||
}
|
||||
self.state = .upstreamsFinished(buffer: buffer)
|
||||
|
||||
return .resumeContinuation(
|
||||
downstreamContinuation: continuation,
|
||||
result: .success(element)
|
||||
)
|
||||
|
||||
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")
|
||||
}
|
||||
}
|
||||
}
|
||||
Loaded 100 of 229 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user