Compare commits

...
88 Commits
Author SHA1 Message Date
Thibault Wittemberg 9cfed92b02 buffer: implement with custom storages (#239) 2023-02-10 11:27:06 -08:00
Franz Busch ca2ac60495 Tolerate cancelling before we create our task (#250)
# Motivation
We switched the point in time when we create tasks to the first call to `next()`. This had the side effect that we can now be cancelled before we even created our task. Which by itself is fine but we didn't handle it in the state machines.

# Modification
Adapt the state machines of `debounce`, `zip`, `merge` and `combineLatest` to handle cancellation before `next()`.

# Result
We shouldn't run into these preconditions anymore.
2023-02-06 17:05:07 +00:00
ga eun kim bf0ec24bde fix iterator variable name on zip (#251) 2023-02-01 15:20:40 +00:00
Thibault Wittemberg 0ebc8058fc channel: re-implement with a state machine (#235) 2023-01-12 09:40:37 -08:00
Philippe Hausler a07a3f41b5 Rename AsyncLazySequence to AsyncSyncSequence per review feedback (#246)
* Rename AsyncLazySequence to AsyncSyncSequence per review feedback

* Rename and number the async proposal
2023-01-10 15:36:42 -08:00
Philippe Hausler e7b9b6039d Extract the result to test the preconditions seperate from the function calls for locking (#244) 2023-01-03 15:24:40 -08:00
Dan AppelandDan Appel 3f12423c47 Add precondition guards to pthread_mutex calls (#243)
While in the current configuration lock/unlock shouldn't ever fail,
it seems polite to guard against basic misuse in debug builds.

Co-authored-by: Dan Appel <dan_appel@apple.com>
2023-01-03 15:15:34 -08:00
Philippe Hausler aed5422380 AsyncLazySequence proposal (#189) 2023-01-03 09:31:58 -08:00
Philippe Hausler b6dff00602 Transform the reductions and remove duplicates guides into a proposal (#233) 2023-01-03 09:31:36 -08:00
Philippe Hausler 4ba079747d Transform the chunk and timer guides into a proposal (#231) 2023-01-03 09:31:15 -08:00
Philippe Hausler 7586d2060f Convert the guides for debounce and throttle into a proposal (#194)
* Convert the guides for debounce and throttle into a proposal

* Adjust Sendability of the iterator requirements
2023-01-03 09:30:31 -08:00
Hayashi Tatsuya fb15375758 Fix Source links in documentations (#234) 2022-12-16 10:09:34 -08:00
Max Desiatov 5656338b5d Remove print from implementation of some algorithms (#240) 2022-11-28 08:03:04 -05:00
Philippe Hausler 9abd029409 Ensure all imports of other modules are implementation only (#232) 2022-11-16 10:54:45 -08:00
Thibault Wittemberg dd97b564ae tests: harmonize debounce availability (#223) 2022-11-16 10:19:45 -08:00
Philippe Hausler 0174f58455 Cleanup Sendable conformances and @preconcurrency imports to build as strict concurrency clean (#230) 2022-11-16 10:15:26 -08:00
Franz Busch ae26222e86 Rework combineLatest to remove the Sendable constraint on the base iterator (#228)
# Motivation
This follows the recent rework of the `merge` and `zip` algorithms where we dropped the `Sendable` constraint on the `BaseX.AsyncIterator`. This PR now removes the same constraint on `combineLatest`.

# Modification
This PR overhauls the implementation of `combineLatest` with the goal of changing these things:
- Drop the `Sendable` constraint of the base `AsyncIterator`s
- Only create a single `Task`

# Result
`combineLatest` now doesn't require the base `AsyncIterator` to be `Sendable`
2022-11-16 08:49:50 -08:00
Franz Busch ed0b086089 Remove Sendable from AsyncBufferedByteIterator (#220)
# Motivation
I raise on the pitch of `AsyncBufferedByteIterator` on the forums that I think the iterator must not be `Sendable`. The reasoning for this is twofold. First, an iterator is the connection of a consumer to the `AsyncSequence`; therefore, iterators should not be shared since it breaks that assumption. Secondly, the implementation of the `AsyncBufferedByteIterator` can be more straight forward since we don't have to check for unique ownership of the storage.

# Modification
Remove the `Sendable` conformances from  `AsyncBufferedByteIterator`.
2022-10-20 11:49:54 -07:00
Franz Busch 8f5e8cee42 Merge the zip2 and zip3 implementations (#221)
# Motivation
We recently merged https://github.com/apple/swift-async-algorithms/pull/201 which removed the `Sendable` constraint of the `AsyncIterator` from `zip`. There were some left over comments that we wanted to fix in a follow up. Furthermore, we also can merge the implementations of `zip2` and `zip3` relatively easily. The merging also aids us in understanding what we need from the variadic generics proposals and allows us to give feedback since `zip` is non-trivial to implement with variadic generics.
Lastly, the merged state machine will be a good base for the overhaul of `combineLatest`.

# Modification
This PR merges the state machines from `zip2` and `zip3` into a single one. Furthermore, it addresses some of the open feedback from the last PR.

# Result
We now have a single state machine which is a good foundation for our changes to `combineLatest`.
2022-10-20 11:49:13 -07:00
Franz Busch 6c6ed33514 Remove Sendability from all Iterators (#219)
# Motivation
We have been discussing this a lot in the other PRs, but in general said that an `AsyncIterator` is the connection between the consuming task and the `AsyncSequence`. If an `AsyncIterator` would be `Sendable` then we don't have that relationship anymore. Therefore, no iterator of an `AsyncIterator` should be `Sendable`.

# Modification
Remove all `Sendable` conformances of the iterators even the conditional ones. We can always add them back later.
2022-10-20 09:34:24 -07:00
Philippe Hausler 2cfb16691a Task.select is no longer used and can potentially impact performance negatively (#217) 2022-10-20 09:34:05 -07:00
Philippe Hausler cc0621eb1b Renumber bytes's proposal 2022-10-18 13:14:44 -07:00
Philippe Hausler f32328ac6f Convert the bytes iterator guide to a proposal (#187) 2022-10-18 13:13:45 -07:00
Philippe Hausler 3890885e80 Renumber chain's proposal 2022-10-18 13:06:34 -07:00
Philippe Hausler cf70e78632 Convert the chain guide to a proposal (#188) 2022-10-14 13:30:17 -07:00
Franz Busch be681c12e3 Remove Sendable constraint for AsyncChain2Sequence (#213)
# Motivation
We want to remove any `Sendable` constraints on iterators since they ought to not be passed between `Task`s.

# Modification
Explicitly mark the `AsyncChain2Sequence` to be not `Sendable`.

# Result
Nobody can make this `Sendable`.
2022-10-14 08:41:25 -07:00
Franz Busch c21ee2d706 Remove Sendable constraint for AsyncAdjacentPairsSequence (#212)
# Motivation
We want to remove any `Sendable` constraints on iterators since they ought to not be passed between `Task`s.

# Modification
Explicitly mark the `AsyncAdjacentPairsSequence` to be not `Sendable`.

# Result
Nobody can make this `Sendable`.
2022-10-14 08:39:53 -07:00
Philippe Hausler aedcb785a4 Simplify chunks algorithm by re-using merge and composition (#209) 2022-10-12 09:35:07 -07:00
Philippe Hausler 9d427ce159 Relax Sendable conditional conformance for AsyncJoinedBySeparatorSequence (#210) 2022-10-12 09:25:11 -07:00
Doug Russell 081ca79161 Deprecation Housekeeping (#206) (#207)
`withTaskCancellationHandler<T>(_:, operation:)` -> `withTaskCancellationHandler<T>(operation:onCancel:)`
2022-10-11 19:54:17 +01:00
Thibault Wittemberg 76b27aebef zip: remove Sendable constraint + limit task creation (#201) 2022-10-10 08:58:22 -07:00
Doug Russell 1bd073999c Deprecation Housekeeping (#206)
`withTaskCancellationHandler<T>(_:, operation:)` -> `withTaskCancellationHandler<T>(operation:onCancel:)`
2022-10-10 08:35:35 -07:00
Franz Busch 314b10c634 Remove AsyncIterator: Sendable requirement from merge (#185)
* Remove `AsyncIterator: Sendable` requirement from merge

# Motivation
Currently a lot of the operator implementations in here that consume other `AsyncSequence`s require the `AsyncIterator` to be `Sendable`. This is mostly due to the fact that we are calling `makeAsyncIterator` on the upstream `AsyncSequence` and then pass that iterator around to various newly spawned `Task`s. This has two downsides:
1. It only allows users to use operators like `merge` if their `AsyncSequence.AsyncIterator` is `Sendable`
2. In merge we are creating new `Task`s for every new demand. Creating `Task`s is not cheap.

My main goal of this PR was to remove the `Sendable` constraint from `merge`.

# Modification
This PR overhauls the complete inner workings of the `AsyncMerge2Sequence`. It does a couple of things:
1. The main change is that instead of creating new `Task`s for every demand, we are creating one `Task` when the `AsyncIterator` is created. This task has as child task for every upstream sequence.
2. When calling `next` we are signalling the child tasks to demand from the upstream
3. A new state machine that is synchronizing the various concurrent operations that can happen
4. Handling cancellation since we are creating a bunch of continuations.

# Result
In the end, this PR swaps the implementation of `AsyncMerge2Sequence` and drops the `Sendable` constraint and passes all tests. Furthermore, on my local performance testing I saw up 50% speed increase in throughput.

# Open points
1. I need to make this sequence re-throwing but before going down that rabbit whole I wanna get buy-in on the implementation.
2. We should discuss and document if `merge` and other operators are hot or cold, i.e. if they only request if they got downstream demand
3. I need to switch `AsyncMerge3Sequence` over to the same iplementation

* Split logic into multiple files, adapt merge3 and incorporate PR feedback

* Add more tests and fix upstream throw behaviour

* Remove internal class from the sequence

* Setup task after first next

* Remove unnecessary tests
2022-10-10 08:34:50 -07:00
Jeff Lewis 4feeb83d13 make initializers '@usableFromInline' instead of '@inlinable' to support building for library evolution (#205) 2022-10-05 09:39:14 -07:00
Philippe Hausler af9ce91db4 Simplify resumptions to avoid needing a resumption type and mark continuations as resumed directly in critical regions (#203) 2022-10-04 14:28:14 -07:00
Franz Busch f05e450f0b Remove AsyncIterator: Sendable requirement from debounce (#198)
* Remove `AsyncIterator: Sendable` requirement from debounce

# Motivation
The current implementation of `AsyncDebounceSequence` requires the base `AsyncIterator` to be `Sendable`. This is causing two problems:

1. It only allows users to use `debounce` if their `AsyncSequence.AsyncIterator` is `Sendable`
2. In `debounce` we are creating a lot of new `Task`s and reating `Task`s is not cheap.

My main goal of this PR was to remove the `Sendable` constraint from `debounce`.

# Modification
This PR overhauls the implementation of `debounce` and aligns it with the implementation of the open `merge` PR https://github.com/apple/swift-async-algorithms/pull/185 . The most important changes are this:
- I removed the `Sendable` requirement from the base sequences `AsyncIterator`.
- Instead of creating new Tasks for the sleep and for the upstream consumption. I am now creating one Task and manipulate it by signalling continuations
- I am not cancelling the sleep. Instead I am recalculating the time left to sleep when a sleep finishes.

# Result
In the end, this PR swaps the implementation of `AsyncDebounceSequence` and drops the `Sendable` constraint and passes all tests. Furthermore, on my local performance testing I saw up 150% speed increase in throughput.

* Fix https://github.com/apple/swift-async-algorithms/issues/174

* Code review

* Remove lock methods

* Cleanup some unused code

* Setup task after first call to next
2022-09-30 10:12:11 -07:00
Thibault Wittemberg 2b5fbf3c91 [Channel] improve send cancellation (#184)
* asyncChannel: introduce ChannelToken to model Pending and Awaiting

* asyncChannel: harmonize send and next cancellation

* asyncChannel: add .finished as an emission state

* asyncThrowingChannel: harmonize send and next cancellation

* channel: update documentation for cancellation
2022-09-14 15:24:29 -07:00
Thibault Wittemberg 68c8dc285b asyncChainSequence: harmonize unit tests nomenclature (#191) 2022-08-30 10:48:20 -07:00
Thibault Wittemberg cba18c3f88 asyncLazySequence: harmonize unit tests nomenclature (#190) 2022-08-30 10:47:50 -07:00
Philippe Hausler c0fdfdb8aa Add an introduction and formatting for the combineLatest algorithm into a proposal. (#177)
* Add an introduction and formatting for the `combineLatest` algorithm into a proposal

* Update the proposal # to 0006
2022-08-04 09:44:07 -07:00
Philippe Hausler e3a18a0353 Modify the adjacent pairs guide into a proposal ready for review (#178)
* Modify the adjacent pairs guide into a proposal ready for review

* Update the proposal # to 0005
2022-08-04 09:43:14 -07:00
Franz BuschandPhilippe Hausler b92ba058d8 Proposal for joined and joined(separator:) (#180)
* Proposal for `joined` and `joined(separator:)`

* Small fixes

* Update proposal # to 0004

Co-authored-by: Philippe Hausler <phausler@apple.com>
2022-08-04 09:42:14 -07:00
Thibault Wittemberg f44d02eb26 Improve adjacent pairs unit tests (#179)
* adjacentPairs: improve unit tests

* adjacentPairs: conform indentation to project standards
2022-07-18 09:28:55 -07:00
Philippe Hausler 57072e617a Correct proposal link for compacted 2022-07-13 10:19:35 -07:00
Philippe Hausler 45aa5b950c Rename compacted proposal to 0003 2022-07-13 10:15:10 -07:00
Philippe Hausler 6ff1f1b411 Compacted proposal (#162) 2022-07-13 09:02:40 -07:00
shiz 2a211e18be Fix typo in Validation.md (#172)
* Add escaping characters before |

* Add more escaping characters before |
2022-06-27 14:23:48 -07:00
Thibault Wittemberg 9baff2ad3d [AsyncThrowingChannel] make the fail terminal event non async (#164)
* asyncThrowingChannel: make fail set a terminal state

* asyncChannel: align naming on asyncThrowingChannel

* asyncChannel: remove a test base on Task.sleep

* guides: update Channel with non async fail(_:)
2022-06-27 09:04:37 -07:00
Thibault Wittemberg 6df7fcdd10 merge: improve unit tests (#161) 2022-06-27 09:04:15 -07:00
Ole Begemann 8a355f015f Fix a few typos (#173) 2022-06-27 09:03:09 -07:00
shiz 816cf644af Add missing back quote (#171) 2022-06-27 09:00:33 -07:00
Philippe Hausler cca423ff03 Remove the disable of availability and mark methods as available to clock/instant/duration (#165)
* Remove the disable of availability and mark methods as available to clock/instant/duration

* Rework availability to be more permissive for tests

* Use hand coded values instead of defines (only available via Darwin versions of Dispatch)

* Adjust additional test availability

* Correct debounce test availability guard

* Update build instructions to indicate Xcode requirements

* Ensure the clock property of the validation diagram is only available for targets that can support it
2022-06-16 13:06:20 -07:00
Thibault Wittemberg 9a3e94d440 compacted: rename unit tests (#166) 2022-06-15 23:28:45 -07:00
Philippe Hausler 07b8d74cc7 [SAA-0002] Merge (#156) 2022-06-13 11:04:03 -07:00
Philippe Hausler 434591a571 Update availability to be in sync with Clock/Instant/Duration (#159) 2022-06-13 10:18:45 -07:00
Max Desiatov 6e9a5757bc Fix typo in BufferedBytes.md (#158)
`BufferedAsyncByteIterator` -> `AsyncBufferedByteIterator`
2022-05-30 19:29:53 -07:00
Thibault Wittemberg a973b06d06 Fix async channel finishes all (#152)
* asyncChannel: enforce termination for all when finished

* asyncThrowingChannel: enforce termination for all when finished

* asyncChannel: improve unit tests readability

* asyncChannel: adapt the Guide to the new finish behaviour

* asyncChannel: adapt the Guide to the new finish behaviour
2022-05-04 13:07:33 -07:00
Kevin Tan 6b59cfb8d0 Minor documentation improvements (#153) 2022-05-03 21:17:53 -07:00
Philippe Hausler d185b2068b [SAA-0001] Zip (#149) 2022-04-27 16:08:26 -07:00
Thibault Wittemberg bbbe08d331 zip: improve unit tests readability (#151) 2022-04-25 17:50:09 -07:00
Thibault Wittemberg 6d5d6319f4 asyncThrowingChannel: fixes potential crashes when no more awaiting (#150)
This commit fixes crashes where the state is "awaiting" with no more awaiting clients.
The state is now set to .idle to reflect the reality.
2022-04-21 11:10:14 -07:00
Thibault Wittemberg 047ab6abef asyncChannel: fixes potential crashes when no more awaiting (#143)
This commit fixes crashes where the state is "awaiting" with no more awaiting clients.
The state is now set to .idle to reflect the reality.
2022-04-15 10:05:40 -07:00
Tiago Lopes d2164b9ef6 Fix redundant where clauses in AsyncBufferSequence extension (#141) 2022-04-12 07:23:05 -07:00
Tiago Lopes b3d4ffb94c Fix broken links to guides in README.md (#146) 2022-04-11 16:53:54 -07:00
Tiago Lopes 5b78eaf423 Fix some typos in Chain.md (#144) 2022-04-11 15:06:39 -07:00
Kyle a3576e669b Add docc support and publish documentation to GitHub pages (#137)
* Move Guides into docc base location

* Add Github gh-page support

* Conditionally add docc-plugin dependency

* Temp skip AsyncSequenceValidation target
2022-04-11 14:25:33 -07:00
Kristoffer Johansson 94a7ecec28 Moves XCTestCase.validate into its own module (#135)
* Move XCTestCase.validate into it’s own module

* Remove unnecessary import statement
2022-04-08 14:15:55 -07:00
Philippe Hausler 6a8aec2a1f #131 Cancel sends as if they were terminal events on task cancellation (#132) 2022-04-08 10:44:30 -07:00
Philippe Hausler 9d03d90a13 #120 Ensure concurrent access to AsyncBufferedByteIterator does not crash from dangling pointers (#121) 2022-04-08 10:44:06 -07:00
k-kohey c174e4603e fix merge example (#140) 2022-04-08 08:47:25 -07:00
Yuka Ezura b6755e6313 Fix typo (#138) 2022-04-07 12:18:56 -07:00
Philippe Hausler 18749897a8 #113 Define the first element of throttled sequences by not exceeding the rate (and fix a expectation misalignment of events) (#133)
* #113 Define the first element of throttled sequences by not exceeding the rate (and fix a expectation misalignment of events)

* Update guide for throttle referencing the first element and duration measurement
2022-04-01 11:40:44 -07:00
Guillaume Lessard 6971c8fc67 Update README.md (#134)
Insert a forgotten word.
2022-04-01 09:24:42 -07:00
Tiago Lopes f1581d0973 Fix a grammatical sentence in Collections.md (#127) 2022-03-30 10:20:47 -07:00
Tiago Lopes 442d20e8c8 Fix TestRangeReplaceableCollection.swift file name (#128) 2022-03-30 10:20:19 -07:00
Laszlo Teveli b8a8d5d2ae Rename AdjacentPairsSequence.swift (#126) 2022-03-29 12:15:04 -07:00
Laszlo Teveli b136d48e7f Adjacent Pairs (#111) 2022-03-29 10:01:55 -07:00
Reza Shirazian 4b5a3ef050 measureSequenceThroughput-duration-clean-up (#125)
duration and start property in measureSequenceThroughput is vestigial from early development. This PR cleans that up.
2022-03-29 09:10:51 -07:00
Tiago Lopes 9ce65b089c Fix the README link to the Swift Forums (#123) 2022-03-28 17:54:26 -07:00
Reza Shirazian fac138c517 #45 - Two sided performance test for merge (#114)
This PR extends `measureSequenceThroughput` to take two outputs so functions like merge/ zip etc can be tested by both sides.
2022-03-28 17:09:22 -07:00
Jordan Kay a8bba84598 Fix spelling and typos (#122)
* Fix spelling

* Fix typos
2022-03-28 17:02:51 -07:00
Vikram Kriplaney 739815f65d Fix zip example (#119) 2022-03-28 11:08:46 -07:00
Reza Shirazian 0dfb244b1b Fixing a few typos (#115)
This PR fixes a few typos across various comments in the code.
2022-03-27 08:19:52 -07:00
Philippe Hausler f9369af30c Add instructions for building with swift 5.6 toolchains (#106) 2022-03-25 14:49:20 -07:00
jamieQ 1656fd8839 Fix typo in AsyncChannel documentation (#108)
fix typo
2022-03-25 14:49:10 -07:00
Philippe Hausler db847ef410 Remove shims for use with the swift development toolchains (#105) 2022-03-24 16:03:21 -07:00
Philippe Hausler 21f20e9030 Only emit diagnostics for unexpected diagram mismatches (#103) 2022-03-24 15:14:40 -07:00
Philippe Hausler df97fdaced Update the code of conduct to avoid it going out of sync (#102) 2022-03-24 12:28:19 -07:00
147 changed files with 9925 additions and 5757 deletions

No files matched your search

+48
View File
@@ -0,0 +1,48 @@
# AsyncSyncSequence
* Proposal: [NNNN](NNNN-lazy.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.
+2 -52
View File
@@ -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. -->
+110
View File
@@ -0,0 +1,110 @@
# 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: **Implemented**
* Implementation: [[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)]
* 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,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `zip(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncZipSequence` which is an asynchronous sequence.
Each iteration of an `AsyncZipSequence` will await for all base iterators to produce a value. This iteration will be done concurrently to produce a singular tuple result. If any of the base iterations terminates by returning `nil` from its iteration, the `AsyncZipSequence` iteration is immediately considered unsatisfiable and returns `nil` and all iterations of other bases will be cancelled. If any iteration of the bases throws an error, then the other iterations concurrently running are cancelled and the produced error is rethrown, terminating the iteration.
`AsyncZipSequence` requires that the iterations are done concurrently. This means that the base sequences, their elements, and iterators must all be `Sendable`. That makes `AsyncZipSequence` inherently `Sendable`.
The source of throwing of `AsyncZipSequence` is determined by its bases. That means that if any base can throw an error then the iteration of the `AsyncZipSequence` can throw. If no bases can throw, then the `AsyncZipSequence` does not throw.
### Naming
The `zip(_:...)` function takes its name from the Swift standard library function of the same name. The `AsyncZipSequence` family of types take their name from the same family from the standard library for the type returned by `zip(_:_:)`. The one difference is that this asynchronous version allows for the affordance of recognizing the eventual variadic generic need of expanding a zip of more than just two sources.
It is common in some libraries to have a `ZipMap` or some other combination of `zip` and `map`. This is a common usage pattern, but leaving a singular type for composition feels considerably more approachable.
### Comparison with other libraries
**Swift** The swift standard library has an [API definition of zip](https://developer.apple.com/documentation/swift/1541125-zip) as a top level function for combining two sequences.
**ReactiveX** ReactiveX has an [API definition of Zip](https://reactivex.io/documentation/operators/zip.html) as a top level function for combining Observables.
**Combine** Combine has an [API definition of zip](https://developer.apple.com/documentation/combine/publisher/zip(_:)/) as an operator style method for combining Publishers.
## 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.
+103
View File
@@ -0,0 +1,103 @@
# 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: **Implemented**
* Implementation: [[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)]
* 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,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1.Element == Base2.Element, Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `merge(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncMergeSequence` which is an asynchronous sequence.
Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`.
When iterating a `AsyncMergeSequence`, the sequence terminates when all of the base asynchronous sequences terminate, since this means there is no potential for any further elements to be produced.
The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
### Naming
Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence, the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
### Comparison with other libraries
**ReactiveX** ReactiveX has an [API definition of Merge](https://reactivex.io/documentation/operators/merge.html) as a top level function for merging Observables.
**Combine** Combine has an [API definition of merge(with:)](https://developer.apple.com/documentation/combine/publisher/merge(with:)-7qt71/) as an operator style method for merging Publishers.
## 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.
+61
View File
@@ -0,0 +1,61 @@
# Compacted
* Proposal: [0003](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/0003-compacted.md)
* Authors: [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* 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)
+67
View File
@@ -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: **Implemented**
* 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.
+55
View File
@@ -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: **Implemented**
* Implementation: [[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAdjacentPairsSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestAdjacentPairs.swift)]
* Decision Notes:
* Bugs:
## Introduction
The `adjacentPairs()` API serve the purpose of collecting adjacent values. This operation is available for any `AsyncSequence` by calling the `adjacentPairs()` method.
```swift
extension AsyncSequence {
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self>
}
```
## Detailed Design
The `adjacentPairs()` algorithm produces elements of tuple (size of 2), containing a pair of the original `Element` type.
The interface for this algorithm is available on all `AsyncSequence` types. The returned `AsyncAdjacentPairsSequence` conditionally conforms to `Sendable`.
Its iterator keeps track of the previous element returned in the `next()` function and updates it in every turn.
```swift
for await (first, second) in (1...5).async.adjacentPairs() {
print("First: \(first), Second: \(second)")
}
// First: 1, Second: 2
// First: 2, Second: 3
// First: 3, Second: 4
// First: 4, Second: 5
```
It composes well with the [Dictionary.init(_:uniquingKeysWith:)](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Collections.md) API that deals with `AsyncSequence` of tuples.
```swift
Dictionary(uniqueKeysWithValues: url.lines.adjacentPairs())
```
## Alternatives Considered
This functionality is often written as a `zip` of a sequence together with itself, dropping its first element (`zip(source, source.dropFirst())`).
It's such a dominant use-case, the [swift-algorithms](https://github.com/apple/swift-algorithms) package also [introduced](https://github.com/apple/swift-algorithms/pull/119) it to its collection of algorithms.
## Credits/Inspiration
The synchronous counterpart in [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md).
+95
View File
@@ -0,0 +1,95 @@
# 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: **Implemented**
* Implementation: [[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)]
* 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 precicely 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,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncCombineLatestSequence` which is an asynchronous sequence.
Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must all be `Sendable`.
If any of the bases terminate before the first element is produced, then the `AsyncCombineLatestSequence` iteration can never be satisfied. So, if a base's iterator returns `nil` at the first iteration, then the `AsyncCombineLatestSequence` iterator immediately returns `nil` to signify a terminal state. In this particular case, any outstanding iteration of other bases will be cancelled. After the first element is produced ,this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the bases, the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point (within the first iteration or afterwards), an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
### Naming
Since the inherent behavior of `combineLatest(_:...)` combines the latest values from multiple streams into a tuple the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
### Comparison with other libraries
Combine latest often appears in libraries developed for processing events over time since the event ordering of a concept of "latest" only occurs when asynchrony is involved.
**ReactiveX** ReactiveX has an [API definition of CombineLatest](https://reactivex.io/documentation/operators/combinelatest.html) as a top level function for combining Observables.
**Combine** Combine has an [API definition of combineLatest](https://developer.apple.com/documentation/combine/publisher/combinelatest(_:)/) has an operator style method for combining Publishers.
+80
View File
@@ -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: **Implemented**
* 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).
+59
View File
@@ -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: **Implemented**
* 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, Sendable {
public typealias Element = UInt8
public init(
capacity: Int,
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
)
public mutating func next() async throws -> UInt8?
}
```
For each invocation of `next`, the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes, a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled, the read function is invoked to acquire the next filled buffer, at which point it takes a byte out of that buffer.
If the read function returns `0`, indicating it didn't read any more bytes, the iterator is decided to be finished and no additional invocations to the read function are made.
If the read function throws, the error will be thrown by the iteration. Subsequent invocations to the iterator will then return `nil` without invoking the read function.
If the task is cancelled during the iteration, the iteration will check the cancellation only in passes where the read function is invoked, and will throw a `CancellationError`.
### Naming
This type was named precisely for what it does: it is an asynchronous iterator that buffers bytes.
+356
View File
@@ -0,0 +1,356 @@
# Chunked & Timer
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-chunk.md)
* Author(s): [Kevin Perry](https://github.com/kperryua), [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Implementation: [
[By group](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedByGroupSequence.swift),
[On projection](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
[Count and signal](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountAndSignalSequence.swift)
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChunk.swift)
]
[
[Timer](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncTimerSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestTimer.swift)
]
* Decision Notes:
* Bugs:
## Introduction
Grouping of values from an asynchronous sequence is often useful for tasks that involve writing those values efficiently or useful to handle specific structured data inputs.
The groupings may be controlled by different ways but one most notable is to control them by regular intervals. Producing elements at regular intervals can be useful for composing with other algorithms. These can range from invoking code at specific times to using those regular intervals as a delimiter of events. There are other cases this exists in APIs however those do not currently interact with Swift concurrency. These existing APIs are ones like `Timer` or `DispatchTimer` but are bound to internal clocks that are not extensible.
## Proposed Solution
Chunking operations can be broken down into a few distinct categories: grouping according to a binary predicate used to determine whether consecutive elements belong to the same group, projecting an element's property to determine the element's chunk membership, by discrete count, by another signal asynchronous sequence which indicates when the chunk should be delimited, or by a combination of count and signal.
To satisfy the specific grouping by inteervals we propose to add a new type; `AsyncTimerSequence` which utilizes the new `Clock`, `Instant` and `Duration` types. This allows the interaction of the timer to custom implementations of types adopting `Clock`.
This asynchronous sequence will produce elements of the clock's `Instant` type after the interval has elapsed. That instant will be the `now` at the time that the sleep has resumed. For each invocation to `next()` the `AsyncTimerSequence.Iterator` will calculate the next deadline to resume and pass that and the tolerance to the clock. If at any point in time the task executing that iteration is cancelled the iteration will return `nil` from the call to `next()`.
## Detailed Design
### Grouping
Group chunks are determined by passing two consecutive elements to a closure which tests whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator receives the first element from the base sequence, it will immediately be added to a group. When it receives the second item, it tests whether the previous item and the current item belong to the same group. If they are not in the same group, then the iterator emits the first item's group and a new group is created containing the second item. Items declared to be in the same group accumulate until a new group is declared, or the iterator finds the end of the base sequence. When the base sequence terminates, the final group is emitted. If the base sequence throws an error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard any current group.
```swift
extension AsyncSequence {
public func chunked<Collected: RangeReplaceableCollection>(
into: Collected.Type,
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
) -> AsyncChunkedByGroupSequence<Self, Collected>
where Collected.Element == Element
public func chunked(
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
) -> AsyncChunkedByGroupSequence<Self, [Element]>
}
```
Consider an example where an asynchronous sequence emits the following values: `10, 20, 30, 10, 40, 40, 10, 20`. Given the chunked operation to be defined as follows:
```swift
let chunks = numbers.chunked { $0 <= $1 }
for await numberChunk in chunks {
print(numberChunk)
}
```
That snippet will produce the following values:
```swift
[10, 20, 30]
[10, 40, 40]
[10, 20]
```
While `Array` is the default type for chunks, thanks to the overload that takes a `RangeReplaceableCollection` type, the same sample can be chunked into instances of `ContiguousArray`, or any other `RangeReplaceableCollection` instead.
```swift
let chunks = numbers.chunked(into: ContiguousArray.self) { $0 <= $1 }
for await numberChunk in chunks {
print(numberChunk)
}
```
That variant is the funnel method for the main implementation, which passes `[Element].self` in as the parameter.
### Projection
In some scenarios, chunks are determined not by comparing different elements, but by the element itself. This may be the case when the element has some sort of discriminator that can determine the chunk it belongs to. When two consecutive elements have different projections, the current chunk is emitted and a new chunk is created for the new element.
When the `AsyncChunkedOnProjectionSequence`'s iterator receives `nil` from the base sequence, it emits the final chunk. When the base sequence throws an error, the iterator discards the current chunk and rethrows that error.
Similarly to the `chunked(by:)` method this algorithm has an optional specification for the `RangeReplaceableCollection` which is used as the type of each chunk.
```swift
extension AsyncSequence {
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(
into: Collected.Type,
on projection: @escaping @Sendable (Element) -> Subject
) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected>
public func chunked<Subject : Equatable>(
on projection: @escaping @Sendable (Element) -> Subject
) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]>
}
```
The following example shows how a sequence of names can be chunked together by their first characters.
```swift
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
let groupedNames = names.chunked(on: \.first!)
for try await (firstLetter, names) in groupedNames {
print(firstLetter)
for name in names {
print(" ", name)
}
}
```
A special property of this kind of projection chunking is that when an asynchronous sequence's elements are known to be ordered, the output of the chunking asynchronous sequence is suitable for initializing dictionaries using the `AsyncSequence` initializer for `Dictionary`. This is because the projection can be easily designed to match the sorting characteristics and thereby guarantee that the output matches the pattern of an array of pairs of unique "keys" with the chunks as the "values".
In the example above, if the names are known to be ordered then you can take advantage of the uniqueness of each "first character" projection to initialize a `Dictionary` like so:
```swift
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
let nameDirectory = try await Dictionary(uniqueKeysWithValues: names.chunked(on: \.first!))
```
### Count or Signal
Sometimes chunks are determined not by the elements themselves, but by external factors. This final category enables limiting chunks to a specific size and/or delimiting them by another asynchronous sequence which is referred to as a "signal". This particular chunking family is useful for scenarios where the elements are more efficiently processed as chunks than individual elements, regardless of their values.
This family is broken down into two sub-families of methods: ones that employ a signal plus an optional count (which return an `AsyncChunksOfCountOrSignalSequence`), and the ones that only deal with counts (which return an `AsyncChunksOfCountSequence`). Both sub-families have `Collected` as their element type, or `Array` if unspecified. These sub-families have rethrowing behaviors; if the base `AsyncSequence` can throw then the chunks sequence can also throw. Likewise if the base `AsyncSequence` cannot throw then the chunks sequence also cannot throw.
##### Count only
```swift
extension AsyncSequence {
public func chunks<Collected: RangeReplaceableCollection>(
ofCount count: Int,
into: Collected.Type
) -> AsyncChunksOfCountSequence<Self, Collected>
where Collected.Element == Element
public func chunks(
ofCount count: Int
) -> AsyncChunksOfCountSequence<Self, [Element]>
}
```
If a chunk size limit is specified via an `ofCount` parameter, the sequence will produce chunks of type `Collected` with at most the specified number of elements. When a chunk reaches the given size, the asynchronous sequence will emit it immediately.
For example, an asynchronous sequence of `UInt8` bytes can be chunked into at most 1024-byte `Data` instances like so:
```swift
let packets = bytes.chunks(ofCount: 1024, into: Data.self)
for try await packet in packets {
write(packet)
}
```
##### Signal only
```swift
extension AsyncSequence {
public func chunked<Signal, Collected: RangeReplaceableCollection>(
by signal: Signal,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
where Collected.Element == Element
public func chunked<Signal>(
by signal: Signal
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
by timer: AsyncTimerSequence<C>,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
where Collected.Element == Element
public func chunked<C: Clock>(
by timer: AsyncTimerSequence<C>
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
}
```
If a signal asynchronous sequence is specified, the chunking asynchronous sequence emits chunks whenever the signal emits. The signals element values are ignored. If the chunking asynchronous sequence hasn't accumulated any elements since its previous emission, then no value is emitted in response to the signal.
Since time is a frequent method of signaling desired delineations of chunks, there is a pre-specialized set of overloads that take `AsyncTimerSequence`. These allow shorthand initialization by using `AsyncTimerSequence`'s static member initializers.
As an example, an asynchronous sequence of log messages can be chunked into arrays of logs in four second segments like so:
```swift
let fourSecondsOfLogs = logs.chunked(by: .repeating(every: .seconds(4)))
for await chunk in fourSecondsOfLogs {
send(chunk)
}
```
##### Count or Signal
```swift
extension AsyncSequence {
public func chunks<Signal, Collected: RangeReplaceableCollection>(
ofCount count: Int,
or signal: Signal,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
where Collected.Element == Element
public func chunks<Signal>(
ofCount count: Int,
or signal: Signal
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
by timer: AsyncTimerSequence<C>,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
where Collected.Element == Element
public func chunked<C: Clock>(
by timer: AsyncTimerSequence<C>
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
}
```
If both count and signal are specified, the chunking asynchronous sequence emits chunks whenever *either* the chunk reaches the specified size *or* the signal asynchronous sequence emits. When a signal causes a chunk to be emitted, the accumulated element count is reset back to zero. When an `AsyncTimerSequence` is used as a signal, the timer is started from the moment `next()` is called for the first time on `AsyncChunksOfCountOrSignalSequence`'s iterator, and it emits on a regular cadence from that moment. Note that the scheduling of the timer's emission is unaffected by any chunks emitted based on count.
Like the example above, this code emits up to 1024-byte `Data` instances, but a chunk will also be emitted every second.
```swift
let packets = bytes.chunks(ofCount: 1024 or: .repeating(every: .seconds(1)), into: Data.self)
for try await packet in packets {
write(packet)
}
```
In any configuration of any of the chunking families, when the base asynchronous sequence terminates, one of two things will happen: 1) a partial chunk will be emitted, or 2) no chunk will be emitted (i.e. the iterator received no elements since the emission of the previous chunk). No elements from the base asynchronous sequence are ever discarded, except in the case of a thrown error.
## Interfaces
### Grouping
```swift
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
where Collected.Element == Base.Element {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunkedByGroupSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
extension AsyncChunkedByGroupSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
```
### Projection
```swift
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
public typealias Element = (Subject, Collected)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> (Subject, Collected)?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunkedOnProjectionSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Subject: Sendable { }
```
### Count
```swift
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
where Collected.Element == Base.Element {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
```
### Count or Signal
```swift
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable
where
Collected.Element == Base.Element,
Base: Sendable, Signal: Sendable,
Base.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable,
Base.Element: Sendable, Signal.Element: Sendable {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol, Sendable {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
```
### Timer
```swift
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
public typealias Element = C.Instant
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async -> C.Instant?
}
public init(
interval: C.Instant.Duration,
tolerance: C.Instant.Duration? = nil,
clock: C
)
public func makeAsyncIterator() -> Iterator
}
extension AsyncTimerSequence where C == SuspendingClock {
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock>
}
extension AsyncTimerSequence: Sendable { }
```
## Alternatives Considered
It was considered to make the chunked element to be an `AsyncSequence` instead of allowing collection into a `RangeReplaceableCollection` however it was determined that the throwing behavior of that would be complex to understand. If that hurdle could be overcome then that might be a future direction/consideration that would be worth exploring.
Variants of `chunked(by:)` (grouping) and `chunked(on:)` (projection) methods could be added that take delimiting `Signal` and `AsyncTimerSequence` inputs similar to `chunked(byCount:or:)`. However, it was decided that such functionality was likely to be underutilized and not worth the complication to the already broad surface area of `chunked` methods.
The naming of this family was considered to be `collect` which is used in APIs like `Combine`. This family of functions has distinct similarity to those APIs.
## Credits/Inspiration
This transformation function is a heavily inspired analog of the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md)
https://developer.apple.com/documentation/foundation/timer
https://developer.apple.com/documentation/foundation/timer/timerpublisher
+157
View File
@@ -0,0 +1,157 @@
# Rate Limiting
* Proposal: [SAA-NNNN]()
* Authors: [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Implementation:
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncDebounceSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestDebounce.swift)
]
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrottleSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestThrottle.swift)
]
* Decision Notes:
* Bugs:
## Introduction
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to only emit values after a given period of time of inactivity, or "quiescence", has elapsed. This algorithm is commonly referred to as debouncing. A very close reelativee is an apporach 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/
+196
View File
@@ -0,0 +1,196 @@
# Reductions
* Proposal: [SAA-NNNN](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/NNNN-reductions.md)
* Author(s): [Philippe Hausler](https://github.com/phausler)
* Status: **Implemented**
* Implementation: [
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncExclusiveReductionsSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestReductions.swift)
]
* Decision Notes:
* Bugs:
## Introduction
The family of algorithms for reduce are useful for converting a sequence or asynchronous sequence into a single value, but that can elide important intermediate information. The _reductions_ algorithm is often called "scan", but this name does not convey its heritage to the family of reducing.
There are two strategies that are usable for creating continuous reductions: exclusive reductions and inclusive reductions:
* Exclusive reductions take a value and incorporate values into that initial value. A common example is reductions by appending to an array.
* Inclusive reductions transact only on the values provided. A common example is adding numbers.
There are also common specializations of this algorithm that are worth offering as a shorthand. Particularly removing duplications that is a common task of reducing a sequence. When processing values over time it is definitely possible that the same value may occur in a row. When the distinctness of the presence value is not needed it is useful to consider the values over time that are differing from the last. Particularly this can be expressed as removing duplicate values either in the case as they are directly `Equatable` or by a predicate.
## Proposed Solution
Exclusive reductions come in two variants: transforming by application, or transformation via mutation. This replicates the same interface as `reduce(_:_:)` and `reduce(into:_:)`. Unlike the `reduce` algorithms, the `reductions` algorithm also comes in two flavors: throwing or non throwing transformations.
```swift
extension AsyncSequence {
public func reductions<Result>(
_ initial: Result,
_ transform: @Sendable @escaping (Result, Element) async -> Result
) -> AsyncExclusiveReductionsSequence<Self, Result>
public func reductions<Result>(
into initial: Result,
_ transform: @Sendable @escaping (inout Result, Element) async -> Void
) -> AsyncExclusiveReductionsSequence<Self, Result>
}
extension AsyncSequence {
public func reductions<Result>(
_ initial: Result,
_ transform: @Sendable @escaping (Result, Element) async throws -> Result
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
public func reductions<Result>(
into initial: Result,
_ transform: @Sendable @escaping (inout Result, Element) async throws -> Void
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
}
```
These APIs can be used to reduce an initial value progressively or reduce into an initial value via mutation. In practice, a common use case for reductions is to mutate a collection by appending values.
```swift
characters.reductions(into: "") { $0.append($1) }
```
If the characters being produced asynchronously are `"a", "b", "c"`, then the iteration of the reductions is `"a", "ab", "abc"`.
Inclusive reductions do not have an initial value and therefore do not need an additional variations beyond the throwing and non throwing flavors.
```swift
extension AsyncSequence {
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async -> Element
) -> AsyncInclusiveReductionsSequence<Self>
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
) -> AsyncThrowingInclusiveReductionsSequence<Self>
}
```
This is often used for scenarios like a running tally or other similar cases.
```swift
numbers.reductions { $0 + $1 }
```
In the above example, if the numbers are a sequence of `1, 2, 3, 4`, the produced values would be `1, 3, 6, 10`.
The `removeDuplicates()` and `removeDuplicates(by:)` APIs serve this purpose of removing duplicate values that occur. These are special case optimizations in the family of the reductions APIs. These algorithms test against the previous value and if the latest iteration of the base `AsyncSequence` is the same as the last it invokes `next()` again. The resulting `AsyncRemoveDuplicatesSequence` will ensure that no duplicate values occur next to each other. This should not be confused with only emitting unique new values; where each value is tested against a collected set of values.
```swift
extension AsyncSequence where Element: Equatable {
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self>
}
extension AsyncSequence {
public func removeDuplicates(
by predicate: @escaping @Sendable (Element, Element) async -> Bool
) -> AsyncRemoveDuplicatesSequence<Self>
public func removeDuplicates(
by predicate: @escaping @Sendable (Element, Element) async throws -> Bool
) -> AsyncThrowingRemoveDuplicatesSequence<Self>
}
```
The `removeDuplicates` family comes in three variants. One variant is conditional upon the `Element` type being `Equatable`. This variation is a shorthand for writing `.removeDuplicates { $0 == $1 }`. The next variation is the closure version that allows for custom predicates to be applied. This algorithm allows for the cases where the elements themselves may not be equatable but portions of the element may be compared. Lastly is the variation that allows for comparison when the comparison method may throw.
## Detailed Design
#### Reductions
The exclusive reduction variants come in two distinct cases: non-throwing and throwing. These both have corresponding types to encompass that throwing behavior.
For non-throwing exclusive reductions, the element type of the sequence is the result of the reduction transform. `AsyncExclusiveReductionsSequence` will throw if the base asynchronous sequence throws, and will not throw if the base does not throws.
```swift
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
}
extension AsyncExclusiveReductionsSequence: AsyncSequence {
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncExclusiveReductionsSequence: Sendable
where Base: Sendable, Element: Sendable { }
```
The sendability behavior of `AsyncExclusiveReductionsSequence` is such that when the base, base iterator, and element are `Sendable` then `AsyncExclusiveReductionsSequence` is `Sendable`.
```swift
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
}
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async throws -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncThrowingExclusiveReductionsSequence: Sendable
where Base: Sendable, Element: Sendable { }
```
#### Remove Duplicates
In the cases where the `Element` type is `Equatable` or the non-trowing predicate variant these utilize the type `AsyncRemoveDuplicatesSequence`. The throwing predicate variant uses `AsyncThrowingRemoveDuplicatesSequence`. Both of these types are conditionally `Sendable` when the base, base element, and base iterator are `Sendable`
The `AsyncRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and will not throw if the base asynchronous sequence does not throw.
```swift
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator {
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
}
}
extension AsyncRemoveDuplicatesSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
```
The `AsyncThrowingRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and still may throw if the base asynchronous sequence does not throw due to the predicate having the potential of throwing.
```swift
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async throws -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncThrowingRemoveDuplicatesSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
```
## Alternatives Considered
One alternate name for `reductions` was to name it `scan`; however the naming from the Swift Algorithms package offers considerably more inference to the heritage of what family of functions this algorithm belongs to.
## Credits/Inspiration
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md)
-54
View File
@@ -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
+26 -11
View File
@@ -12,25 +12,40 @@ let package = Package(
],
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: "_CAsyncSequenceValidationSupport", type: .static, targets: ["AsyncSequenceValidation"]),
.library(name: "AsyncAlgorithms_XCTest", targets: ["AsyncAlgorithms_XCTest"]),
],
dependencies: [],
dependencies: [.package(url: "https://github.com/apple/swift-collections.git", .upToNextMajor(from: "1.0.3"))],
targets: [
.target(name: "AsyncAlgorithms", dependencies: ["ClockShims"]),
.target(name: "ClockShims"),
.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"],
swiftSettings: [
.unsafeFlags([
"-Xfrontend", "-disable-availability-checking"
])
]),
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"]),
]
)
#if canImport(Darwin)
import Darwin
let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil
#elseif canImport(Glibc)
import Glibc
let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil
#else
let buildingDocs = false
#endif
// Only require the docc plugin when building documentation
package.dependencies += buildingDocs ? [
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
] : []
+29 -38
View File
@@ -14,58 +14,54 @@ 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:
@@ -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,89 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// An `AsyncSequence` that iterates over the adjacent pairs of the original
/// `AsyncSequence`.
@frozen
public struct AsyncAdjacentPairsSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = (Base.Element, Base.Element)
@usableFromInline
let base: Base
@inlinable
init(_ base: Base) {
self.base = base
}
/// The iterator for an `AsyncAdjacentPairsSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
public typealias Element = (Base.Element, Base.Element)
@usableFromInline
var base: Base.AsyncIterator
@usableFromInline
internal var previousElement: Base.Element?
@inlinable
init(_ base: Base.AsyncIterator) {
self.base = base
}
@inlinable
public mutating func next() async rethrows -> (Base.Element, Base.Element)? {
if previousElement == nil {
previousElement = try await base.next()
}
guard let previous = previousElement, let next = try await base.next() else {
return nil
}
previousElement = next
return (previous, next)
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator())
}
}
extension AsyncSequence {
/// An `AsyncSequence` that iterates over the adjacent pairs of the original
/// original `AsyncSequence`.
///
/// ```
/// for await (first, second) in (1...5).async.adjacentPairs() {
/// print("First: \(first), Second: \(second)")
/// }
///
/// // First: 1, Second: 2
/// // First: 2, Second: 3
/// // First: 3, Second: 4
/// // First: 4, Second: 5
/// ```
///
/// - Returns: An `AsyncSequence` where the element is a tuple of two adjacent elements
/// or the original `AsyncSequence`.
@inlinable
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self> {
AsyncAdjacentPairsSequence(self)
}
}
extension AsyncAdjacentPairsSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
@available(*, unavailable)
extension AsyncAdjacentPairsSequence.Iterator: Sendable { }
@@ -0,0 +1,35 @@
# ``AsyncAlgorithms``
**Swift Async Algorithms** is an open-source package of asynchronous sequence and advanced algorithms that involve concurrency, along with their related types.
## Overview
This package has three main goals:
- First-class integration with `async/await`
- Provide a home for time-based algorithms
- Be cross-platform and open source
## Topics
### Getting Started
- <doc:AdjacentPairs>
- <doc:BufferedBytes>
- <doc:Chain>
- <doc:Channel>
- <doc:Chunked>
- <doc:Collections>
- <doc:CombineLatest>
- <doc:Compacted>
- <doc:Debounce>
- <doc:Effects>
- <doc:Intersperse>
- <doc:Joined>
- <doc:Lazy>
- <doc:Merge>
- <doc:Reductions>
- <doc:RemoveDuplicates>
- <doc:Throttle>
- <doc:Timer>
- <doc:Zip>
@@ -0,0 +1,49 @@
# AdjacentPairs
* Author(s): [László Teveli](https://github.com/tevelee)
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAdjacentPairsSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestAdjacentPairs.swift)]
The `adjacentPairs()` API serve the purpose of collecting adjacent values. This operation is available for any `AsyncSequence` by calling the `adjacentPairs()` method.
```swift
extension AsyncSequence {
public func adjacentPairs() -> AsyncAdjacentPairsSequence<Self>
}
```
## Detailed Design
The `adjacentPairs()` algorithm produces elements of tuple (size of 2), containing a pair of the original `Element` type.
The interface for this algorithm is available on all `AsyncSequence` types. The returned `AsyncAdjacentPairsSequence` conditionally conforms to `Sendable`.
Its iterator keeps track of the previous element returned in the `next()` function and updates it in every turn.
```swift
for await (first, second) in (1...5).async.adjacentPairs() {
print("First: \(first), Second: \(second)")
}
// First: 1, Second: 2
// First: 2, Second: 3
// First: 3, Second: 4
// First: 4, Second: 5
```
It composes well with the [Dictionary.init(_:uniquingKeysWith:)](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Collections.md) API that deals with `AsyncSequence` of tuples.
```swift
Dictionary(uniqueKeysWithValues: url.lines.adjacentPairs())
```
## Alternatives Considered
This functionality is often written as a `zip` of a sequence together with itself, dropping its first element (`zip(source, source.dropFirst())`).
It's such a dominant use-case, the [swift-algorithms](https://github.com/apple/swift-algorithms) package also [introduced](https://github.com/apple/swift-algorithms/pull/119) it to its collection of algorithms.
## Credits/Inspiration
The synchronous counterpart in [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Guides/AdjacentPairs.md).
@@ -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)
}
@@ -9,8 +9,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 +60,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.
@@ -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 {
@@ -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 {
@@ -1,6 +1,6 @@
# 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) |
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/CombineLatest/AsyncCombineLatest3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCombineLatest.swift)]
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
@@ -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.
@@ -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
@@ -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)
]
@@ -1,58 +1,59 @@
| Type | Throws | Sendablity |
| 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|
@@ -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,6 +1,6 @@
# AsyncLazySequence
# AsyncSyncSequence
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncLazySequence.swift) |
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncSyncSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)]
Converts a non-asynchronous sequence into an asynchronous one.
@@ -17,19 +17,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) |
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Merge/AsyncMerge3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestMerge.swift)]
Merges two or more asynchronous sequences sharing the same element type into one singular asynchronous sequence.
```swift
let appleFeed = URL("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 }
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 = merge(appleFeed, nasdaqFeed) {
for try await ticker in merge(appleFeed, nasdaqFeed) {
print(ticker)
}
```
@@ -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` and it's `Iterator` 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) |
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Zip/AsyncZip3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestZip.swift)]
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
```swift
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
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) = zip(appleFeed, nasdaqFeed) {
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,7 +39,7 @@
/// }
///
///
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol {
public typealias Element = UInt8
@usableFromInline var buffer: _AsyncBytesBuffer
@@ -64,10 +64,13 @@ public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
}
}
@available(*, unavailable)
extension AsyncBufferedByteIterator: Sendable { }
@frozen @usableFromInline
internal struct _AsyncBytesBuffer: @unchecked Sendable {
internal struct _AsyncBytesBuffer {
@usableFromInline
final class Storage: Sendable {
final class Storage {
fileprivate let buffer: UnsafeMutableRawBufferPointer
init(
@@ -85,7 +88,7 @@ internal struct _AsyncBytesBuffer: @unchecked Sendable {
}
}
@usableFromInline internal var storage: Storage
@usableFromInline internal let storage: Storage
@usableFromInline internal var nextPointer: UnsafeRawPointer
@usableFromInline internal var endPointer: UnsafeRawPointer
@@ -15,7 +15,7 @@
/// - 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`.
@inlinable
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element {
@@ -80,4 +80,6 @@ extension AsyncChain2Sequence: AsyncSequence {
}
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
@available(*, unavailable)
extension AsyncChain2Sequence.Iterator: Sendable { }
@@ -16,7 +16,7 @@
/// - 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`
@inlinable
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3> {
@@ -95,4 +95,3 @@ extension AsyncChain3Sequence: AsyncSequence {
}
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
-210
View File
@@ -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)
}
}
@@ -37,6 +37,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)
@@ -103,7 +104,7 @@ public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeR
@usableFromInline
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
@@ -84,7 +84,7 @@ public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equ
@usableFromInline
let projection : @Sendable (Base.Element) -> Subject
@inlinable
@usableFromInline
init(_ base: Base, projection: @escaping @Sendable (Base.Element) -> Subject) {
self.base = base
self.projection = projection
@@ -98,4 +98,3 @@ 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 { }
@@ -31,60 +31,79 @@ extension AsyncSequence {
}
/// 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, *)
@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, *)
@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, *)
@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, *)
@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 {
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 +124,7 @@ 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)
}
}
@@ -68,7 +68,7 @@ public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeRe
@usableFromInline
let count : Int
@inlinable
@usableFromInline
init(_ base: Base, count: Int) {
precondition(count > 0)
self.base = base
@@ -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())
}
}
@@ -68,5 +68,4 @@ extension AsyncSequence {
}
}
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 { }
extension AsyncCompactedSequence: Sendable where Base: Sendable, Base.Element: 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)
}
}
@@ -112,4 +112,3 @@ extension AsyncExclusiveReductionsSequence: AsyncSequence {
}
extension AsyncExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
extension AsyncExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
@@ -85,4 +85,3 @@ extension AsyncInclusiveReductionsSequence: AsyncSequence {
}
extension AsyncInclusiveReductionsSequence: Sendable where Base: Sendable { }
extension AsyncInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
@@ -33,7 +33,7 @@ public struct AsyncInterspersedSequence<Base: AsyncSequence> {
@usableFromInline
internal let separator: Base.Element
@inlinable
@usableFromInline
internal init(_ base: Base, separator: Base.Element) {
self.base = base
self.separator = separator
@@ -61,7 +61,7 @@ extension AsyncInterspersedSequence: AsyncSequence {
@usableFromInline
internal var state = State.start
@inlinable
@usableFromInline
internal init(_ iterator: Base.AsyncIterator, separator: Base.Element) {
self.iterator = iterator
self.separator = separator
@@ -99,6 +99,4 @@ extension AsyncInterspersedSequence: AsyncSequence {
}
}
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 { }
extension AsyncInterspersedSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
@@ -74,7 +74,7 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
@usableFromInline
var state: State
@inlinable
@usableFromInline
init(_ iterator: Base.AsyncIterator, separator: Separator) {
state = .initial(iterator, separator)
}
@@ -128,7 +128,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
@@ -141,10 +141,4 @@ public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: Asy
}
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 { }
@@ -79,7 +79,7 @@ public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base
@usableFromInline
let base: Base
@inlinable
@usableFromInline
init(_ base: Base) {
self.base = base
}
@@ -91,8 +91,4 @@ public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base
}
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 { }
@@ -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())
}
}
@@ -46,7 +46,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
@@ -85,10 +85,6 @@ 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.
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
@@ -105,7 +101,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
@@ -144,5 +140,6 @@ 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 { }
extension AsyncRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
extension AsyncThrowingRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable { }
@@ -14,21 +14,21 @@ extension Sequence {
/// but on which operations, such as `map` and `filter`, are
/// implemented asynchronously.
@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.
@frozen
public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
public struct AsyncSyncSequence<Base: Sequence>: AsyncSequence {
public typealias Element = Base.Element
@frozen
@@ -66,5 +66,4 @@ public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
}
}
extension AsyncLazySequence: Sendable where Base: Sendable { }
extension AsyncLazySequence.Iterator: Sendable where Base.Iterator: Sendable { }
extension AsyncSyncSequence: Sendable where Base: Sendable { }
@@ -11,19 +11,19 @@
extension AsyncSequence {
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@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, *)
@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, *)
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func throttle<C: Clock>(for interval: C.Instant.Duration, clock: C, latest: Bool = true) -> AsyncThrottleSequence<Self, C, Element> {
throttle(for: interval, clock: clock) { previous, element in
if latest {
@@ -35,14 +35,14 @@ extension AsyncSequence {
}
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@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, *)
@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
@@ -57,13 +57,14 @@ public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
}
}
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@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
@@ -77,13 +78,15 @@ extension AsyncThrottleSequence: AsyncSequence {
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
}
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
@@ -97,8 +100,5 @@ extension AsyncThrottleSequence: AsyncSequence {
}
}
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@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 { }
@@ -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)
}
}
@@ -119,4 +119,3 @@ extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
}
extension AsyncThrowingExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
@@ -89,4 +89,3 @@ extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
}
extension AsyncThrowingInclusiveReductionsSequence: Sendable where Base: Sendable { }
extension AsyncThrowingInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
@@ -10,7 +10,7 @@
//===----------------------------------------------------------------------===//
/// 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
@@ -71,7 +71,7 @@ public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
}
}
@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> {
@@ -79,7 +79,7 @@ extension AsyncTimerSequence {
}
}
@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> {
@@ -87,8 +87,5 @@ extension AsyncTimerSequence where C == SuspendingClock {
}
}
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@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 { }
@@ -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,131 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence where Self: Sendable {
/// Creates an asynchronous sequence that buffers elements.
///
/// The buffering behaviour is dictated by the policy:
/// - bounded: will buffer elements until the limit is reached. Then it will suspend the upstream async sequence.
/// - unbounded: will buffer elements without limit.
/// - bufferingNewest: will buffer elements until the limit is reached. Then it will discard the oldest elements.
/// - bufferingOldest: will buffer elements until the limit is reached. Then it will discard the newest elements.
///
/// - Parameter policy: A policy that drives the behaviour of the ``AsyncBufferSequence``
/// - Returns: An asynchronous sequence that buffers elements up to a given limit.
public func buffer(
policy: AsyncBufferSequencePolicy
) -> AsyncBufferSequence<Self> {
AsyncBufferSequence<Self>(base: self, policy: policy)
}
}
/// A policy dictating the buffering behaviour of an ``AsyncBufferSequence``
public struct AsyncBufferSequencePolicy: Sendable {
enum _Policy {
case bounded(Int)
case unbounded
case bufferingNewest(Int)
case bufferingOldest(Int)
}
let policy: _Policy
/// A policy for buffering elements until the limit is reached.
/// Then consumption of the upstream `AsyncSequence` will be paused until elements are consumed from the buffer.
/// If the limit is zero then no buffering policy is applied.
public static func bounded(_ limit: Int) -> Self {
precondition(limit >= 0, "The limit should be positive or equal to 0.")
return Self(policy: .bounded(limit))
}
/// A policy for buffering elements without limit.
public static var unbounded: Self {
return Self(policy: .unbounded)
}
/// A policy for buffering elements until the limit is reached.
/// After the limit is reached and a new element is produced by the upstream, the oldest buffered element will be discarded.
/// If the limit is zero then no buffering policy is applied.
public static func bufferingLatest(_ limit: Int) -> Self {
precondition(limit >= 0, "The limit should be positive or equal to 0.")
return Self(policy: .bufferingNewest(limit))
}
/// A policy for buffering elements until the limit is reached.
/// After the limit is reached and a new element is produced by the upstream, the latest buffered element will be discarded.
/// If the limit is zero then no buffering policy is applied.
public static func bufferingOldest(_ limit: Int) -> Self {
precondition(limit >= 0, "The limit should be positive or equal to 0.")
return Self(policy: .bufferingOldest(limit))
}
}
/// An `AsyncSequence` that buffers elements in regard to a policy.
public struct AsyncBufferSequence<Base: AsyncSequence & Sendable>: AsyncSequence {
enum StorageType<Base: AsyncSequence> {
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
public init(
base: Base,
policy: AsyncBufferSequencePolicy
) {
self.base = base
self.policy = policy
}
public func makeAsyncIterator() -> Iterator {
let storageType: StorageType<Base>
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<Base>
public mutating func next() async rethrows -> Element? {
switch self.storageType {
case .transparent(var iterator):
let element = try await iterator.next()
self.storageType = .transparent(iterator)
return element
case .bounded(let storage):
return try await storage.next()?._rethrowGet()
case .unbounded(let storage):
return try await storage.next()?._rethrowGet()
}
}
}
}
extension AsyncBufferSequence: Sendable where Base: Sendable { }
@available(*, unavailable)
extension AsyncBufferSequence.Iterator: Sendable { }
@@ -0,0 +1,310 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
struct BoundedBufferStateMachine<Base: AsyncSequence> {
typealias Element = Base.Element
typealias SuspendedProducer = UnsafeContinuation<Void, Never>
typealias SuspendedConsumer = UnsafeContinuation<Result<Base.Element, Error>?, Never>
private enum State {
case initial(base: Base)
case buffering(
task: Task<Void, Never>,
buffer: Deque<Result<Element, Error>>,
suspendedProducer: SuspendedProducer?,
suspendedConsumer: SuspendedConsumer?
)
case modifying
case finished(buffer: Deque<Result<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 by 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 by started.")
case .buffering(let task, let buffer, .none, .none):
// we are either idle or the buffer is already in use (no awaiting consumer)
// if the buffer is available we resume the producer so it can we can request the next element
// otherwise we confirm the suspension
if buffer.count < limit {
return .resumeProducer
} else {
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: continuation, suspendedConsumer: nil)
return .none
}
case .buffering(_, let buffer, .none, .some):
// we have an awaiting consumer, we can resume the producer so the next element can be requested
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty as we have an awaiting consumer already.")
return .resumeProducer
case .buffering(_, _, .some, _):
preconditionFailure("Invalid state. There is already a suspended producer.")
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
return .resumeProducer
}
}
enum ElementProducedAction {
case none
case resumeConsumer(continuation: SuspendedConsumer, result: Result<Element, Error>)
}
mutating func elementProduced(element: Element) -> ElementProducedAction {
switch self.state {
case .initial:
preconditionFailure("Invalid state. The task should already by 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(element))
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
return .none
case .buffering(let task, let buffer, .none, .some(let suspendedConsumer)):
// we have an awaiting consumer, we can resume it with the element and exit
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
self.state = .buffering(task: task, buffer: buffer, suspendedProducer: nil, suspendedConsumer: nil)
return .resumeConsumer(continuation: suspendedConsumer, result: .success(element))
case .buffering(_, _, .some, _):
preconditionFailure("Invalid state. There should not be a suspended producer.")
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
return .none
}
}
enum FinishAction {
case none
case resumeConsumer(
continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
)
}
mutating func finish(error: Error?) -> FinishAction {
switch self.state {
case .initial:
preconditionFailure("Invalid state. The task should already by 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)
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)
}
}
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 by 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)
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)
}
}
enum InterruptedAction {
case none
case resumeProducerAndConsumer(
task: Task<Void, Never>,
producerContinuation: UnsafeContinuation<Void, Never>?,
consumerContinuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>?
)
}
mutating func interrupted() -> InterruptedAction {
switch self.state {
case .initial:
self.state = .finished(buffer: [])
return .none
case .buffering(let task, _, let suspendedProducer, let suspendedConsumer):
self.state = .finished(buffer: [])
return .resumeProducerAndConsumer(
task: task,
producerContinuation: suspendedProducer,
consumerContinuation: suspendedConsumer
)
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
self.state = .finished(buffer: [])
return .none
}
}
}
@@ -0,0 +1,142 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
final class BoundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Sendable {
private let stateMachine: ManagedCriticalState<BoundedBufferStateMachine<Base>>
init(base: Base, limit: Int) {
self.stateMachine = ManagedCriticalState(BoundedBufferStateMachine(base: base, limit: limit))
}
func next() async -> Result<Base.Element, Error>? {
return await withTaskCancellationHandler {
let (shouldSuspend, result) = self.stateMachine.withCriticalRegion { stateMachine -> (Bool, Result<Base.Element, Error>?) in
let action = stateMachine.next()
switch action {
case .startTask(let base):
self.startTask(stateMachine: &stateMachine, base: base)
return (true, nil)
case .suspend:
return (true, nil)
case .returnResult(let producerContinuation, let result):
producerContinuation?.resume()
return (false, result)
}
}
if !shouldSuspend {
return result
}
return await withUnsafeContinuation { (continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.nextSuspended(continuation: continuation)
switch action {
case .none:
break
case .returnResult(let producerContinuation, let result):
producerContinuation?.resume()
continuation.resume(returning: result)
}
}
}
} onCancel: {
self.interrupted()
}
}
private func startTask(
stateMachine: inout BoundedBufferStateMachine<Base>,
base: Base
) {
let task = Task {
do {
var iterator = base.makeAsyncIterator()
loop: while true {
let shouldSuspend = self.stateMachine.withCriticalRegion { stateMachine -> Bool in
return stateMachine.shouldSuspendProducer()
}
if shouldSuspend {
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
self.stateMachine.withCriticalRegion { stateMachine in
let action = 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
}
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced(element: element)
switch action {
case .none:
break
case .resumeConsumer(let continuation, let result):
continuation.resume(returning: result)
}
}
}
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.finish(error: nil)
switch action {
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: nil)
}
}
} catch {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.finish(error: error)
switch action {
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: .failure(error))
}
}
}
}
stateMachine.taskStarted(task: task)
}
func interrupted() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.interrupted()
switch action {
case .none:
break
case .resumeProducerAndConsumer(let task, let producerContinuation, let consumerContinuation):
task.cancel()
producerContinuation?.resume()
consumerContinuation?.resume(returning: nil)
}
}
}
deinit {
self.interrupted()
}
}
@@ -0,0 +1,250 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
struct UnboundedBufferStateMachine<Base: AsyncSequence> {
typealias Element = Base.Element
typealias SuspendedConsumer = UnsafeContinuation<Result<Element, Error>?, Never>
enum Policy {
case unlimited
case bufferingNewest(Int)
case bufferingOldest(Int)
}
private enum State {
case initial(base: Base)
case buffering(
task: Task<Void, Never>,
buffer: Deque<Result<Element, Error>>,
suspendedConsumer: SuspendedConsumer?
)
case modifying
case finished(buffer: Deque<Result<Element, Error>>)
}
private var state: State
private let policy: Policy
init(base: Base, policy: Policy) {
self.state = .initial(base: base)
self.policy = policy
}
var task: Task<Void, Never>? {
switch self.state {
case .buffering(let task, _, _):
return task
default:
return nil
}
}
mutating func taskStarted(task: Task<Void, Never>) {
switch self.state {
case .initial:
self.state = .buffering(task: task, buffer: [], suspendedConsumer: nil)
case .buffering:
preconditionFailure("Invalid state.")
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
preconditionFailure("Invalid state.")
}
}
enum ElementProducedAction {
case none
case resumeConsumer(
continuation: SuspendedConsumer,
result: Result<Element, Error>
)
}
mutating func elementProduced(element: Element) -> ElementProducedAction {
switch self.state {
case .initial:
preconditionFailure("Invalid state. The task should already by started.")
case .buffering(let task, var buffer, .none):
// we are either idle or the buffer is already in use (no awaiting consumer)
// we have to apply the policy when stacking the new element
self.state = .modifying
switch self.policy {
case .unlimited:
buffer.append(.success(element))
case .bufferingNewest(let limit):
if buffer.count >= limit {
_ = buffer.popFirst()
}
buffer.append(.success(element))
case .bufferingOldest(let limit):
if buffer.count < limit {
buffer.append(.success(element))
}
}
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
return .none
case .buffering(let task, let buffer, .some(let suspendedConsumer)):
// we have an awaiting consumer, we can resume it with the element
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
return .resumeConsumer(
continuation: suspendedConsumer,
result: .success(element)
)
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
return .none
}
}
enum FinishAction {
case none
case resumeConsumer(continuation: SuspendedConsumer?)
}
mutating func finish(error: Error?) -> FinishAction {
switch self.state {
case .initial:
preconditionFailure("Invalid state. The task should already by started.")
case .buffering(_, var buffer, .none):
// we are either idle or the buffer is already in use (no awaiting consumer)
// if we have an error we stack it in the buffer so it can be consumed later
if let error {
buffer.append(.failure(error))
}
self.state = .finished(buffer: buffer)
return .none
case .buffering(_, let buffer, let suspendedConsumer):
// we have an awaiting consumer, we can resume it with nil or the error
precondition(buffer.isEmpty, "Invalid state. The buffer should be empty.")
self.state = .finished(buffer: [])
return .resumeConsumer(continuation: suspendedConsumer)
case .modifying:
preconditionFailure("Invalid state.")
case .finished:
return .none
}
}
enum NextAction {
case startTask(base: Base)
case suspend
case returnResult(Result<Element, Error>?)
}
mutating func next() -> NextAction {
switch self.state {
case .initial(let base):
return .startTask(base: base)
case .buffering(_, let buffer, let suspendedConsumer) where buffer.isEmpty:
// we are idle, we have to suspend the consumer
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
return .suspend
case .buffering(let task, var buffer, let suspendedConsumer):
// the buffer is already in use, we can unstack a value and directly resume the consumer
precondition(suspendedConsumer == nil, "Invalid states. There is already a suspended consumer.")
self.state = .modifying
let result = buffer.popFirst()!
self.state = .buffering(task: task, buffer: buffer, suspendedConsumer: nil)
return .returnResult(result)
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)
}
}
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)
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)
}
}
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
}
}
}
@@ -0,0 +1,114 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
final class UnboundedBufferStorage<Base: AsyncSequence>: Sendable where Base: Sendable {
private let stateMachine: ManagedCriticalState<UnboundedBufferStateMachine<Base>>
init(base: Base, policy: UnboundedBufferStateMachine<Base>.Policy) {
self.stateMachine = ManagedCriticalState(UnboundedBufferStateMachine<Base>(base: base, policy: policy))
}
func next() async -> Result<Base.Element, Error>? {
return await withTaskCancellationHandler {
let (shouldSuspend, result) = self.stateMachine.withCriticalRegion { stateMachine -> (Bool, Result<Base.Element, Error>?) in
let action = stateMachine.next()
switch action {
case .startTask(let base):
self.startTask(stateMachine: &stateMachine, base: base)
return (true, nil)
case .suspend:
return (true, nil)
case .returnResult(let result):
return (false, result)
}
}
if !shouldSuspend {
return result
}
return await withUnsafeContinuation { (continuation: UnsafeContinuation<Result<Base.Element, Error>?, Never>) in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.nextSuspended(continuation: continuation)
switch action {
case .none:
break
case .resumeConsumer(let result):
continuation.resume(returning: result)
}
}
}
} onCancel: {
self.interrupted()
}
}
private func startTask(
stateMachine: inout UnboundedBufferStateMachine<Base>,
base: Base
) {
let task = Task {
do {
for try await element in base {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced(element: element)
switch action {
case .none:
break
case .resumeConsumer(let continuation, let result):
continuation.resume(returning: result)
}
}
}
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.finish(error: nil)
switch action {
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: nil)
}
}
} catch {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.finish(error: error)
switch action {
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: .failure(error))
}
}
}
}
stateMachine.taskStarted(task: task)
}
func interrupted() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.interrupted()
switch action {
case .none:
break
case .resumeConsumer(let task, let continuation):
task.cancel()
continuation?.resume(returning: nil)
}
}
}
deinit {
self.interrupted()
}
}
@@ -0,0 +1,60 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// A channel for sending elements from one task to another with back pressure.
///
/// The `AsyncChannel` class is intended to be used as a communication type between tasks,
/// particularly when one task produces values and another task consumes those values. The back
/// pressure applied by `send(_:)` via the suspension/resume ensures that
/// the production of values does not exceed the consumption of values from iteration. This method
/// suspends after enqueuing the event and is resumed when the next call to `next()`
/// on the `Iterator` is made, or when `finish()` is called from another Task.
/// As `finish()` induces a terminal state, there is no more need for a back pressure management.
/// This function does not suspend and will finish all the pending iterations.
public final class AsyncChannel<Element>: AsyncSequence, @unchecked 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()
}
}
}
@@ -0,0 +1,63 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// An error-throwing channel for sending elements from on task to another with back pressure.
///
/// The `AsyncThrowingChannel` class is intended to be used as a communication types between tasks,
/// particularly when one task produces values and another task consumes those values. The back
/// pressure applied by `send(_:)` via suspension/resume ensures that the production of values does
/// not exceed the consumption of values from iteration. This method suspends after enqueuing the event
/// and is resumed when the next call to `next()` on the `Iterator` is made, or when `finish()`/`fail(_:)` is called
/// from another Task. As `finish()` and `fail(_:)` induce a terminal state, there is no more need for a back pressure management.
/// Those functions do not suspend and will finish all the pending iterations.
public final class AsyncThrowingChannel<Element, Failure: Error>: AsyncSequence, @unchecked 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()
}
}
}
@@ -0,0 +1,344 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@_implementationOnly import OrderedCollections
struct ChannelStateMachine<Element, Failure: Error>: Sendable {
private struct SuspendedProducer: Hashable {
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 {
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 {
case channeling(
suspendedProducers: OrderedSet<SuspendedProducer>,
cancelledProducers: Set<SuspendedProducer>,
suspendedConsumers: OrderedSet<SuspendedConsumer>,
cancelledConsumers: Set<SuspendedConsumer>
)
case terminated(Termination)
}
private var state: State = .channeling(suspendedProducers: [], cancelledProducers: [], suspendedConsumers: [], cancelledConsumers: [])
enum SendAction {
case resumeConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
case suspend
}
mutating func send() -> SendAction {
switch self.state {
case .channeling(_, _, let suspendedConsumers, _) where suspendedConsumers.isEmpty:
// we are idle or waiting for consumers, we have to suspend the producer
return .suspend
case .channeling(let suspendedProducers, let cancelledProducers, var suspendedConsumers, let cancelledConsumers):
// we are waiting for producers, we can resume the first available consumer
let suspendedConsumer = suspendedConsumers.removeFirst()
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeConsumer(continuation: suspendedConsumer.continuation)
case .terminated:
return .resumeConsumer(continuation: nil)
}
}
enum SendSuspendedAction {
case resumeProducer
case resumeProducerAndConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
}
mutating func sendSuspended(
continuation: UnsafeContinuation<Void, Never>,
element: Element,
producerID: UInt64
) -> SendSuspendedAction? {
switch self.state {
case .channeling(var suspendedProducers, var cancelledProducers, var suspendedConsumers, let cancelledConsumers):
let suspendedProducer = SuspendedProducer(id: producerID, continuation: continuation, element: element)
if let _ = cancelledProducers.remove(suspendedProducer) {
// the producer was already cancelled, we resume it
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeProducer
}
if suspendedConsumers.isEmpty {
// we are idle or waiting for consumers
// we stack the incoming producer in a suspended state
suspendedProducers.append(suspendedProducer)
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .none
} else {
// we are waiting for producers
// we resume the first consumer
let suspendedConsumer = suspendedConsumers.removeFirst()
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeProducerAndConsumer(continuation: suspendedConsumer.continuation)
}
case .terminated:
return .resumeProducer
}
}
enum SendCancelledAction {
case none
case resumeProducer(continuation: UnsafeContinuation<Void, Never>?)
}
mutating func sendCancelled(producerID: UInt64) -> SendCancelledAction {
switch self.state {
case .channeling(var suspendedProducers, var cancelledProducers, let suspendedConsumers, let cancelledConsumers):
// the cancelled producer might be part of the waiting list
let placeHolder = SuspendedProducer.placeHolder(id: producerID)
if let removed = suspendedProducers.remove(placeHolder) {
// the producer was cancelled after being added to the suspended ones, we resume it
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeProducer(continuation: removed.continuation)
}
// the producer was cancelled before being added to the suspended ones
cancelledProducers.update(with: placeHolder)
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .none
case .terminated:
return .none
}
}
enum FinishAction {
case none
case resumeProducersAndConsumers(
producerSontinuations: [UnsafeContinuation<Void, Never>?],
consumerContinuations: [UnsafeContinuation<Element?, any Error>?]
)
}
mutating func finish(error: Failure?) -> FinishAction {
switch self.state {
case .channeling(let suspendedProducers, _, let suspendedConsumers, _):
// no matter if we are idle, waiting for producers or waiting for consumers, we resume every thing that is suspended
if let error {
if suspendedConsumers.isEmpty {
self.state = .terminated(.failed(error))
} else {
self.state = .terminated(.finished)
}
} else {
self.state = .terminated(.finished)
}
return .resumeProducersAndConsumers(
producerSontinuations: suspendedProducers.map { $0.continuation },
consumerContinuations: suspendedConsumers.map { $0.continuation }
)
case .terminated:
return .none
}
}
enum NextAction {
case resumeProducer(continuation: UnsafeContinuation<Void, Never>?, result: Result<Element?, Error>)
case suspend
}
mutating func next() -> NextAction {
switch self.state {
case .channeling(let suspendedProducers, _, _, _) where suspendedProducers.isEmpty:
// we are idle or waiting for producers, we must suspend
return .suspend
case .channeling(var suspendedProducers, let cancelledProducers, let suspendedConsumers, let cancelledConsumers):
// we are waiting for consumers, we can resume the first awaiting producer
let suspendedProducer = suspendedProducers.removeFirst()
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeProducer(
continuation: suspendedProducer.continuation,
result: .success(suspendedProducer.element)
)
case .terminated(.failed(let error)):
self.state = .terminated(.finished)
return .resumeProducer(continuation: nil, result: .failure(error))
case .terminated:
return .resumeProducer(continuation: nil, result: .success(nil))
}
}
enum NextSuspendedAction {
case resumeConsumer(element: Element?)
case resumeConsumerWithError(error: Error)
case resumeProducerAndConsumer(continuation: UnsafeContinuation<Void, Never>?, element: Element?)
}
mutating func nextSuspended(
continuation: UnsafeContinuation<Element?, any Error>,
consumerID: UInt64
) -> NextSuspendedAction? {
switch self.state {
case .channeling(var suspendedProducers, let cancelledProducers, var suspendedConsumers, var cancelledConsumers):
let suspendedConsumer = SuspendedConsumer(id: consumerID, continuation: continuation)
if let _ = cancelledConsumers.remove(suspendedConsumer) {
// the consumer was already cancelled, we resume it
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeConsumer(element: nil)
}
if suspendedProducers.isEmpty {
// we are idle or waiting for producers
// we stack the incoming consumer in a suspended state
suspendedConsumers.append(suspendedConsumer)
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .none
} else {
// we are waiting for consumers
// we resume the first producer
let suspendedProducer = suspendedProducers.removeFirst()
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeProducerAndConsumer(
continuation: suspendedProducer.continuation,
element: suspendedProducer.element
)
}
case .terminated(.finished):
return .resumeConsumer(element: nil)
case .terminated(.failed(let error)):
self.state = .terminated(.finished)
return .resumeConsumerWithError(error: error)
}
}
enum NextCancelledAction {
case none
case resumeConsumer(continuation: UnsafeContinuation<Element?, any Error>?)
}
mutating func nextCancelled(consumerID: UInt64) -> NextCancelledAction {
switch self.state {
case .channeling(let suspendedProducers, let cancelledProducers, var suspendedConsumers, var cancelledConsumers):
// the cancelled consumer might be part of the suspended ones
let placeHolder = SuspendedConsumer.placeHolder(id: consumerID)
if let removed = suspendedConsumers.remove(placeHolder) {
// the consumer was cancelled after being added to the suspended ones, we resume it
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .resumeConsumer(continuation: removed.continuation)
}
// the consumer was cancelled before being added to the suspended ones
cancelledConsumers.update(with: placeHolder)
self.state = .channeling(
suspendedProducers: suspendedProducers,
cancelledProducers: cancelledProducers,
suspendedConsumers: suspendedConsumers,
cancelledConsumers: cancelledConsumers
)
return .none
case .terminated:
return .none
}
}
}
@@ -0,0 +1,149 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
struct ChannelStorage<Element, 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 shouldExit = self.stateMachine.withCriticalRegion { stateMachine -> Bool in
let action = stateMachine.send()
switch action {
case .suspend:
// the element has not been delivered because no consumer available, we must suspend
return false
case .resumeConsumer(let continuation):
continuation?.resume(returning: element)
return true
}
}
if shouldExit {
return
}
let producerID = self.generateId()
await withTaskCancellationHandler {
// a suspension is needed
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
self.stateMachine.withCriticalRegion { stateMachine in
let action = 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: {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.sendCancelled(producerID: producerID)
switch action {
case .none:
break
case .resumeProducer(let continuation):
continuation?.resume()
}
}
}
}
func finish(error: Failure? = nil) {
self.stateMachine.withCriticalRegion { stateMachine in
let action = 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 (shouldExit, result) = self.stateMachine.withCriticalRegion { stateMachine -> (Bool, Result<Element?, Error>?) in
let action = stateMachine.next()
switch action {
case .suspend:
return (false, nil)
case .resumeProducer(let producerContinuation, let result):
producerContinuation?.resume()
return (true, result)
}
}
if shouldExit {
return try result?._rethrowGet()
}
let consumerID = self.generateId()
return try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { (continuation: UnsafeContinuation<Element?, any Error>) in
self.stateMachine.withCriticalRegion { stateMachine in
let action = 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: {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.nextCancelled(consumerID: consumerID)
switch action {
case .none:
break
case .resumeConsumer(let continuation):
continuation?.resume(returning: nil)
}
}
}
}
}
@@ -0,0 +1,89 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// Creates an asynchronous sequence that combines the latest values from two `AsyncSequence` types
/// by emitting a tuple of the values. ``combineLatest(_:_:)`` only emits a value whenever any of the base `AsyncSequence`s
/// emit a value (so long as each of the bases have emitted at least one value).
///
/// Finishes:
/// ``combineLatest(_:_:)`` finishes when one of the bases finishes before emitting any value or
/// when all bases finished.
///
/// Throws:
/// ``combineLatest(_:_:)`` throws when one of the bases throws. If one of the bases threw any buffered and not yet consumed
/// values will be dropped.
public func combineLatest<
Base1: AsyncSequence,
Base2: AsyncSequence
>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2> where
Base1: Sendable,
Base1.Element: Sendable,
Base2: Sendable,
Base2.Element: Sendable {
AsyncCombineLatest2Sequence(base1, base2)
}
/// An `AsyncSequence` that combines the latest values produced from two asynchronous sequences into an asynchronous sequence of tuples.
public struct AsyncCombineLatest2Sequence<
Base1: AsyncSequence,
Base2: AsyncSequence
>: AsyncSequence, Sendable where
Base1: Sendable,
Base1.Element: Sendable,
Base2: Sendable,
Base2.Element: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public typealias AsyncIterator = Iterator
let base1: Base1
let base2: Base2
public 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()
}
}
}
@@ -0,0 +1,99 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// Creates an asynchronous sequence that combines the latest values from three `AsyncSequence` types
/// by emitting a tuple of the values. ``combineLatest(_:_:_:)`` only emits a value whenever any of the base `AsyncSequence`s
/// emit a value (so long as each of the bases have emitted at least one value).
///
/// Finishes:
/// ``combineLatest(_:_:_:)`` finishes when one of the bases finishes before emitting any value or
/// when all bases finished.
///
/// Throws:
/// ``combineLatest(_:_:_:)`` throws when one of the bases throws. If one of the bases threw any buffered and not yet consumed
/// values will be dropped.
public func combineLatest<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3> where
Base1: Sendable,
Base1.Element: Sendable,
Base2: Sendable,
Base2.Element: Sendable,
Base3: Sendable,
Base3.Element: Sendable {
AsyncCombineLatest3Sequence(base1, base2, base3)
}
/// An `AsyncSequence` that combines the latest values produced from three asynchronous sequences into an asynchronous sequence of tuples.
public struct AsyncCombineLatest3Sequence<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: AsyncSequence, Sendable where
Base1: Sendable,
Base1.Element: Sendable,
Base2: Sendable,
Base2.Element: Sendable,
Base3: Sendable,
Base3.Element: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public typealias AsyncIterator = Iterator
let base1: Base1
let base2: Base2
let base3: Base3
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
self.base1 = base1
self.base2 = base2
self.base3 = base3
}
public func makeAsyncIterator() -> AsyncIterator {
Iterator(storage: .init(self.base1, self.base2, self.base3)
)
}
public struct Iterator: AsyncIteratorProtocol {
final class InternalClass {
private let storage: CombineLatestStorage<Base1, Base2, Base3>
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base3>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
guard let element = try await self.storage.next() else {
return nil
}
// This force unwrap is safe since there must be a third element.
return (element.0, element.1, element.2!)
}
}
let internalClass: InternalClass
fileprivate init(storage: CombineLatestStorage<Base1, Base2, Base3>) {
self.internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await self.internalClass.next()
}
}
}
@@ -0,0 +1,722 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
/// State machine for combine latest
struct CombineLatestStateMachine<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: Sendable where
Base1: Sendable,
Base2: Sendable,
Base3: Sendable,
Base1.Element: Sendable,
Base2.Element: Sendable,
Base3.Element: Sendable {
typealias DownstreamContinuation = UnsafeContinuation<Result<(
Base1.Element,
Base2.Element,
Base3.Element?
)?, Error>, Never>
private enum State: Sendable {
/// Small wrapper for the state of an upstream sequence.
struct Upstream<Element: Sendable>: Sendable {
/// The upstream continuation.
var continuation: UnsafeContinuation<Void, Error>?
/// The produced upstream element.
var element: Element?
/// Indicates wether the upstream finished/threw already
var isFinished: Bool
}
/// The initial state before a call to `next` happened.
case initial(base1: Base1, base2: Base2, base3: Base3?)
/// The state while we are waiting for downstream demand.
case waitingForDemand(
task: Task<Void, Never>,
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
)
/// The state while we are consuming the upstream and waiting until we get a result from all upstreams.
case combining(
task: Task<Void, Never>,
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
downstreamContinuation: DownstreamContinuation,
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
)
case upstreamsFinished(
buffer: Deque<(Base1.Element, Base2.Element, Base3.Element?)>
)
case upstreamThrew(
error: Error
)
/// The state once the downstream consumer stopped, i.e. by dropping all references
/// or by getting their `Task` cancelled.
case finished
/// Internal state to avoid CoW.
case modifying
}
private var state: State
private let numberOfUpstreamSequences: Int
/// Initializes a new `StateMachine`.
init(
base1: Base1,
base2: Base2,
base3: Base3?
) {
self.state = .initial(
base1: base1,
base2: base2,
base3: base3
)
if base3 == nil {
self.numberOfUpstreamSequences = 2
} else {
self.numberOfUpstreamSequences = 3
}
}
/// Actions returned by `iteratorDeinitialized()`.
enum IteratorDeinitializedAction {
/// Indicates that the `Task` needs to be cancelled and
/// the upstream continuations need to be resumed with a `CancellationError`.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
switch self.state {
case .initial:
// Nothing to do here. No demand was signalled until now
return .none
case .combining:
// An iterator was deinitialized while we have a suspended continuation.
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
case .waitingForDemand(let task, let upstreams, _):
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now and need to clean everything up.
self.state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .upstreamThrew, .upstreamsFinished:
// The iterator was dropped so we can transition to finished now.
self.state = .finished
return .none
case .finished:
// We are already finished so there is nothing left to clean up.
// This is just the references dropping afterwards.
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
mutating func taskIsStarted(
task: Task<Void, Never>,
downstreamContinuation: DownstreamContinuation
) {
switch self.state {
case .initial:
// The user called `next` and we are starting the `Task`
// to consume the upstream sequences
self.state = .combining(
task: task,
upstreams: (.init(isFinished: false), .init(isFinished: false), .init(isFinished: false)),
downstreamContinuation: downstreamContinuation,
buffer: .init()
)
case .combining, .waitingForDemand, .upstreamThrew, .upstreamsFinished, .finished:
// We only allow a single task to be created so this must never happen.
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `childTaskSuspended()`.
enum ChildTaskSuspendedAction {
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
case resumeContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>
)
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
case resumeContinuationWithError(
upstreamContinuation: UnsafeContinuation<Void, Error>,
error: Error
)
}
mutating func childTaskSuspended(baseIndex: Int, continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction? {
switch self.state {
case .initial:
// Child tasks are only created after we transitioned to `zipping`
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .upstreamsFinished:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .waitingForDemand(let task, var upstreams, let buffer):
self.state = .modifying
switch baseIndex {
case 0:
upstreams.0.continuation = continuation
case 1:
upstreams.1.continuation = continuation
case 2:
upstreams.2.continuation = continuation
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
}
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .none
case .combining:
// We are currently combining and need to resume any upstream until we transition to waitingForDemand
return .resumeContinuation(upstreamContinuation: continuation)
case .upstreamThrew, .finished:
// Since cancellation is cooperative it might be that child tasks are still getting
// suspended even though we already cancelled them. We must tolerate this and just resume
// the continuation with an error.
return .resumeContinuationWithError(
upstreamContinuation: continuation,
error: CancellationError()
)
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `elementProduced()`.
enum ElementProducedAction {
/// Indicates that the downstream continuation should be resumed with the element.
case resumeContinuation(
downstreamContinuation: DownstreamContinuation,
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
)
}
mutating func elementProduced(_ result: (Base1.Element?, Base2.Element?, Base3.Element?)) -> ElementProducedAction? {
switch self.state {
case .initial:
// Child tasks that are producing elements are only created after we transitioned to `zipping`
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case .upstreamsFinished:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .waitingForDemand(let task, var upstreams, var buffer):
// We got an element in late. This can happen since we race the upstreams.
// We have to store the new tuple in our buffer and remember the upstream states.
self.state = .modifying
switch result {
case (.some(let first), .none, .none):
buffer.append((first, upstreams.1.element!, upstreams.2.element))
upstreams.0.element = first
case (.none, .some(let second), .none):
buffer.append((upstreams.0.element!, second, upstreams.2.element))
upstreams.1.element = second
case (.none, .none, .some(let third)):
buffer.append((upstreams.0.element!, upstreams.1.element!, third))
upstreams.2.element = third
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
}
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .none
case .combining(let task, var upstreams, let downstreamContinuation, let buffer):
precondition(buffer.isEmpty, "Internal inconsistency current state \(self.state) and the buffer is not empty")
self.state = .modifying
switch result {
case (.some(let first), .none, .none):
upstreams.0.element = first
case (.none, .some(let second), .none):
upstreams.1.element = second
case (.none, .none, .some(let third)):
upstreams.2.element = third
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
}
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
if let first = upstreams.0.element,
let second = upstreams.1.element,
let third = upstreams.2.element {
// We got an element from each upstream so we can resume the downstream now
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .resumeContinuation(
downstreamContinuation: downstreamContinuation,
result: .success((first, second, third))
)
} else if let first = upstreams.0.element,
let second = upstreams.1.element,
self.numberOfUpstreamSequences == 2 {
// We got an element from each upstream so we can resume the downstream now
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .resumeContinuation(
downstreamContinuation: downstreamContinuation,
result: .success((first, second, nil))
)
} else {
// We are still waiting for one of the upstreams to produce an element
self.state = .combining(
task: task,
upstreams: (
.init(continuation: upstreams.0.continuation, element: upstreams.0.element, isFinished: upstreams.0.isFinished),
.init(continuation: upstreams.1.continuation, element: upstreams.1.element, isFinished: upstreams.1.isFinished),
.init(continuation: upstreams.2.continuation, element: upstreams.2.element, isFinished: upstreams.2.isFinished)
),
downstreamContinuation: downstreamContinuation,
buffer: buffer
)
return .none
}
case .upstreamThrew, .finished:
// Since cancellation is cooperative it might be that child tasks
// are still producing elements after we finished.
// We are just going to drop them since there is nothing we can do
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamFinished()`.
enum UpstreamFinishedAction {
/// Indicates the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with `nil` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func upstreamFinished(baseIndex: Int) -> UpstreamFinishedAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .upstreamsFinished:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .waitingForDemand(let task, var upstreams, let buffer):
// One of the upstreams finished.
self.state = .modifying
switch baseIndex {
case 0:
upstreams.0.isFinished = true
case 1:
upstreams.1.isFinished = true
case 2:
upstreams.2.isFinished = true
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished() with base index \(baseIndex)")
}
if upstreams.0.isFinished && upstreams.1.isFinished && upstreams.2.isFinished {
// All upstreams finished we can transition to either finished or upstreamsFinished now
if buffer.isEmpty {
self.state = .finished
} else {
self.state = .upstreamsFinished(buffer: buffer)
}
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
} else if upstreams.0.isFinished && upstreams.1.isFinished && self.numberOfUpstreamSequences == 2 {
// All upstreams finished we can transition to either finished or upstreamsFinished now
if buffer.isEmpty {
self.state = .finished
} else {
self.state = .upstreamsFinished(buffer: buffer)
}
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
} else {
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .none
}
case .combining(let task, var upstreams, let downstreamContinuation, let buffer):
// One of the upstreams finished.
self.state = .modifying
// We need to track if an empty upstream finished.
// If that happens we can transition to finish right away.
let emptyUpstreamFinished: Bool
switch baseIndex {
case 0:
upstreams.0.isFinished = true
emptyUpstreamFinished = upstreams.0.element == nil
case 1:
upstreams.1.isFinished = true
emptyUpstreamFinished = upstreams.1.element == nil
case 2:
upstreams.2.isFinished = true
emptyUpstreamFinished = upstreams.2.element == nil
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished() with base index \(baseIndex)")
}
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
if emptyUpstreamFinished {
// All upstreams finished
self.state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
} else if upstreams.0.isFinished && upstreams.1.isFinished && upstreams.2.isFinished {
// All upstreams finished
self.state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
} else if upstreams.0.isFinished && upstreams.1.isFinished && self.numberOfUpstreamSequences == 2 {
// All upstreams finished
self.state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
} else {
self.state = .combining(
task: task,
upstreams: upstreams,
downstreamContinuation: downstreamContinuation,
buffer: buffer
)
return .none
}
case .upstreamThrew, .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamThrew()`.
enum UpstreamThrewAction {
/// Indicates the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with the `error` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
error: Error,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .upstreamsFinished:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .waitingForDemand(let task, let upstreams, _):
// An upstream threw. We can cancel everything now and transition to finished.
// We just need to store the error for the next downstream demand
self.state = .upstreamThrew(
error: error
)
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .combining(let task, let upstreams, let downstreamContinuation, _):
// One of our upstreams threw. We need to transition to finished ourselves now
// and resume the downstream continuation with the error. Furthermore, we need to cancel all of
// the upstream work.
self.state = .finished
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
error: error,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .upstreamThrew, .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `cancelled()`.
enum CancelledAction {
/// Indicates that the downstream continuation needs to be resumed and
/// task and the upstream continuations should be cancelled.
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func cancelled() -> CancelledAction? {
switch self.state {
case .initial:
state = .finished
return .none
case .waitingForDemand(let task, let upstreams, _):
// The downstream task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
self.state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .combining(let task, let upstreams, let downstreamContinuation, _):
// The downstream Task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
self.state = .finished
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .upstreamsFinished:
// We can transition to finished now
self.state = .finished
return .none
case .upstreamThrew, .finished:
// We are already finished so nothing to do here:
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `next()`.
enum NextAction {
/// Indicates that a new `Task` should be created that consumes the sequence.
case startTask(Base1, Base2, Base3?)
/// Indicates that all upstream continuations should be resumed.
case resumeUpstreamContinuations(
upstreamContinuation: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with the result.
case resumeContinuation(
downstreamContinuation: DownstreamContinuation,
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
)
/// Indicates that the downstream continuation should be resumed with `nil`.
case resumeDownstreamContinuationWithNil(DownstreamContinuation)
}
mutating func next(for continuation: DownstreamContinuation) -> NextAction {
switch self.state {
case .initial(let base1, let base2, let base3):
// This is the first time we get demand singalled so we have to start the task
// The transition to the next state is done in the taskStarted method
return .startTask(base1, base2, base3)
case .combining:
// We already got demand signalled and have suspended the downstream task
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
case .waitingForDemand(let task, var upstreams, var buffer):
// We got demand signalled now we have to check if there is anything buffered.
// If not we have to transition to combining and need to resume all upstream continuations now
self.state = .modifying
if let element = buffer.popFirst() {
self.state = .waitingForDemand(
task: task,
upstreams: upstreams,
buffer: buffer
)
return .resumeContinuation(
downstreamContinuation: continuation,
result: .success(element)
)
} else {
let upstreamContinuations = [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
upstreams.0.continuation = nil
upstreams.1.continuation = nil
upstreams.2.continuation = nil
self.state = .combining(
task: task,
upstreams: upstreams,
downstreamContinuation: continuation,
buffer: buffer
)
return .resumeUpstreamContinuations(
upstreamContinuation: upstreamContinuations
)
}
case .upstreamsFinished(var buffer):
self.state = .modifying
if let element = buffer.popFirst() {
self.state = .upstreamsFinished(buffer: buffer)
return .resumeContinuation(
downstreamContinuation: continuation,
result: .success(element)
)
} else {
self.state = .finished
return .resumeDownstreamContinuationWithNil(continuation)
}
case .upstreamThrew(let error):
// One of the upstreams threw and we have to return this error now.
self.state = .finished
return .resumeContinuation(downstreamContinuation: continuation, result: .failure(error))
case .finished:
// We are already finished so we are just returning `nil`
return .resumeDownstreamContinuationWithNil(continuation)
case .modifying:
preconditionFailure("Invalid state")
}
}
}
@@ -0,0 +1,357 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
final class CombineLatestStorage<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: Sendable where
Base1: Sendable,
Base1.Element: Sendable,
Base2: Sendable,
Base2.Element: Sendable,
Base3: Sendable,
Base3.Element: Sendable {
typealias StateMachine = CombineLatestStateMachine<Base1, Base2, Base3>
private let stateMachine: ManagedCriticalState<StateMachine>
init(_ base1: Base1, _ base2: Base2, _ base3: Base3?) {
self.stateMachine = .init(.init(base1: base1, base2: base2, base3: base3))
}
func iteratorDeinitialized() {
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
switch action {
case .cancelTaskAndUpstreamContinuations(
let task,
let upstreamContinuation
):
upstreamContinuation.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element?)? {
try await withTaskCancellationHandler {
let result = await withUnsafeContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.next(for: continuation)
switch action {
case .startTask(let base1, let base2, let base3):
// first iteration, we start one child task per base to iterate over them
self.startTask(
stateMachine: &stateMachine,
base1: base1,
base2: base2,
base3: base3,
downStreamContinuation: continuation
)
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .resumeUpstreamContinuations(let upstreamContinuations):
// bases can be iterated over for 1 iteration so their next value can be retrieved
upstreamContinuations.forEach { $0.resume() }
case .resumeDownstreamContinuationWithNil(let continuation):
// the async sequence is already finished, immediately resuming
continuation.resume(returning: .success(nil))
}
}
}
return try result._rethrowGet()
} onCancel: {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.cancelled()
switch action {
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
}
}
private func startTask(
stateMachine: inout StateMachine,
base1: Base1,
base2: Base2,
base3: Base3?,
downStreamContinuation: StateMachine.DownstreamContinuation
) {
// This creates a new `Task` that is iterating the upstream
// sequences. We must store it to cancel it at the right times.
let task = Task {
await withThrowingTaskGroup(of: Void.self) { group in
// For each upstream sequence we are adding a child task that
// is consuming the upstream sequence
group.addTask {
var base1Iterator = base1.makeAsyncIterator()
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 0, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element1 = try await base1Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((element1, nil, nil))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
let action = self.stateMachine.withCriticalRegion { stateMachine in
stateMachine.upstreamFinished(baseIndex: 0)
}
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
break loop
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
group.addTask {
var base1Iterator = base2.makeAsyncIterator()
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 1, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element2 = try await base1Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((nil, element2, nil))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
let action = self.stateMachine.withCriticalRegion { stateMachine in
stateMachine.upstreamFinished(baseIndex: 1)
}
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
break loop
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
if let base3 = base3 {
group.addTask {
var base1Iterator = base3.makeAsyncIterator()
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 2, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element3 = try await base1Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((nil, nil, element3))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
let action = self.stateMachine.withCriticalRegion { stateMachine in
stateMachine.upstreamFinished(baseIndex: 2)
}
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
break loop
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
}
do {
try await group.waitForAll()
} catch {
// One of the upstream sequences threw an error
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.upstreamThrew(error)
switch action {
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let error,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .failure(error))
case .none:
break
}
}
group.cancelAll()
}
}
}
stateMachine.taskIsStarted(task: task, downstreamContinuation: downStreamContinuation)
}
}
@@ -0,0 +1,99 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Creates an asynchronous sequence that emits the latest element after a given quiescence period
/// has elapsed by using a specified Clock.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func debounce<C: Clock>(for interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncDebounceSequence<Self, C> where Self: Sendable {
AsyncDebounceSequence(self, interval: interval, tolerance: tolerance, clock: clock)
}
/// Creates an asynchronous sequence that emits the latest element after a given quiescence period
/// has elapsed.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func debounce(for interval: Duration, tolerance: Duration? = nil) -> AsyncDebounceSequence<Self, ContinuousClock> where Self: Sendable {
self.debounce(for: interval, tolerance: tolerance, clock: .continuous)
}
}
/// An `AsyncSequence` that emits the latest element after a given quiescence period
/// has elapsed.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public struct AsyncDebounceSequence<Base: AsyncSequence, C: Clock>: Sendable where Base: Sendable {
private let base: Base
private let clock: C
private let interval: C.Instant.Duration
private let tolerance: C.Instant.Duration?
/// Initializes a new ``AsyncDebounceSequence``.
///
/// - Parameters:
/// - base: The base sequence.
/// - interval: The interval to debounce.
/// - tolerance: The tolerance of the clock.
/// - clock: The clock.
public init(_ base: Base, interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
self.base = base
self.interval = interval
self.tolerance = tolerance
self.clock = clock
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncDebounceSequence: AsyncSequence {
public typealias Element = Base.Element
public func makeAsyncIterator() -> AsyncIterator {
let storage = DebounceStorage(
base: self.base,
interval: self.interval,
tolerance: self.tolerance,
clock: self.clock
)
return AsyncIterator(storage: storage)
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncDebounceSequence {
public struct AsyncIterator: AsyncIteratorProtocol {
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
///
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
final class InternalClass: Sendable {
private let storage: DebounceStorage<Base, C>
fileprivate init(storage: DebounceStorage<Base, C>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
try await self.storage.next()
}
}
let internalClass: InternalClass
fileprivate init(storage: DebounceStorage<Base, C>) {
self.internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await self.internalClass.next()
}
}
}
@@ -0,0 +1,706 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
struct DebounceStateMachine<Base: AsyncSequence, C: Clock> {
typealias Element = Base.Element
private enum State {
/// The initial state before a call to `next` happened.
case initial(base: Base)
/// The state while we are waiting for downstream demand.
case waitingForDemand(
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
bufferedElement: (element: Element, deadline: C.Instant)?
)
/// The state once the downstream signalled demand but before we received
/// the first element from the upstream.
case demandSignalled(
task: Task<Void, Never>,
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>
)
/// The state while we are consuming the upstream and waiting for the Clock.sleep to finish.
case debouncing(
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
currentElement: (element: Element, deadline: C.Instant)
)
/// The state once any of the upstream sequences threw an `Error`.
case upstreamFailure(
error: Error
)
/// The state once all upstream sequences finished or the downstream consumer stopped, i.e. by dropping all references
/// or by getting their `Task` cancelled.
case finished
}
/// The state machine's current state.
private var state: State
/// The interval to debounce.
private let interval: C.Instant.Duration
/// The clock.
private let clock: C
init(base: Base, clock: C, interval: C.Instant.Duration) {
self.state = .initial(base: base)
self.clock = clock
self.interval = interval
}
/// Actions returned by `iteratorDeinitialized()`.
enum IteratorDeinitializedAction {
/// Indicates that the `Task` needs to be cancelled and
/// the upstream and clock continuation need to be resumed with a `CancellationError`.
case cancelTaskAndUpstreamAndClockContinuations(
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
}
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
switch self.state {
case .initial:
// Nothing to do here. No demand was signalled until now
return .none
case .debouncing, .demandSignalled:
// An iterator was deinitialized while we have a suspended continuation.
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, _):
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now and need to clean everything up.
self.state = .finished
return .cancelTaskAndUpstreamAndClockContinuations(
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: clockContinuation
)
case .upstreamFailure:
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now. The cleanup already happened when we
// transitioned to `upstreamFailure`.
self.state = .finished
return .none
case .finished:
// We are already finished so there is nothing left to clean up.
// This is just the references dropping afterwards.
return .none
}
}
mutating func taskStarted(_ task: Task<Void, Never>, downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>) {
switch self.state {
case .initial:
// The user called `next` and we are starting the `Task`
// to consume the upstream sequence
self.state = .demandSignalled(
task: task,
clockContinuation: nil,
downstreamContinuation: downstreamContinuation
)
case .debouncing, .demandSignalled, .waitingForDemand, .upstreamFailure, .finished:
// We only a single iterator to be created so this must never happen.
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
}
}
/// Actions returned by `upstreamTaskSuspended()`.
enum UpstreamTaskSuspendedAction {
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
case resumeContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>
)
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
case resumeContinuationWithError(
upstreamContinuation: UnsafeContinuation<Void, Error>,
error: Error
)
}
mutating func upstreamTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> UpstreamTaskSuspendedAction? {
switch self.state {
case .initial:
// Child tasks are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(_, .some, _, _), .debouncing(_, .some, _, _):
// We already have an upstream continuation so we can never get a second one
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .upstreamFailure:
// The upstream already failed so it should never suspend again since the child task
// should have exited
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(let task, .none, let clockContinuation, let bufferedElement):
// The upstream task is ready to consume the next element
// we are just waiting to get demand
self.state = .waitingForDemand(
task: task,
upstreamContinuation: continuation,
clockContinuation: clockContinuation,
bufferedElement: bufferedElement
)
return .none
case .demandSignalled:
// It can happen that the demand got signalled before our upstream suspended for the first time
// We need to resume it right away to demand the first element from the upstream
return .resumeContinuation(upstreamContinuation: continuation)
case .debouncing(_, .none, _, _):
// We are currently debouncing and the upstream task suspended again
// We need to resume the continuation right away so that it continues to
// consume new elements from the upstream
return .resumeContinuation(upstreamContinuation: continuation)
case .finished:
// Since cancellation is cooperative it might be that child tasks are still getting
// suspended even though we already cancelled them. We must tolerate this and just resume
// the continuation with an error.
return .resumeContinuationWithError(
upstreamContinuation: continuation,
error: CancellationError()
)
}
}
/// Actions returned by `elementProduced()`.
enum ElementProducedAction {
/// Indicates that the clock continuation should be resumed to start the `Clock.sleep`.
case resumeClockContinuation(
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
deadline: C.Instant
)
}
mutating func elementProduced(_ element: Element, deadline: C.Instant) -> ElementProducedAction? {
switch self.state {
case .initial:
// Child tasks that are producing elements are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case .waitingForDemand(_, _, _, .some):
// We can only ever buffer one element because of the race of both child tasks
// After that element got buffered we are not resuming the upstream continuation
// and should never get another element until we get downstream demand signalled
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case .upstreamFailure:
// The upstream already failed so it should never have produced another element
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, .none):
// We got an element even though we don't have an outstanding demand
// this can happen because we race the upstream and Clock child tasks
// and the upstream might finish after the Clock. We just need
// to buffer the element for the next demand.
self.state = .waitingForDemand(
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: clockContinuation,
bufferedElement: (element, deadline)
)
return .none
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
// This is the first element that got produced after we got demand signalled
// We can now transition to debouncing and start the Clock.sleep
self.state = .debouncing(
task: task,
upstreamContinuation: nil,
downstreamContinuation: downstreamContinuation,
currentElement: (element, deadline)
)
let deadline = self.clock.now.advanced(by: self.interval)
return .resumeClockContinuation(
clockContinuation: clockContinuation,
deadline: deadline
)
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
// We just got another element and the Clock hasn't finished sleeping yet
// We just need to store the new element
self.state = .debouncing(
task: task,
upstreamContinuation: upstreamContinuation,
downstreamContinuation: downstreamContinuation,
currentElement: (element, deadline)
)
return .none
case .finished:
// Since cancellation is cooperative it might be that child tasks
// are still producing elements after we finished.
// We are just going to drop them since there is nothing we can do
return .none
}
}
/// Actions returned by `upstreamFinished()`.
enum UpstreamFinishedAction {
/// Indicates that the task and the clock continuation should be cancelled.
case cancelTaskAndClockContinuation(
task: Task<Void, Never>,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
/// Indicates that the downstream continuation should be resumed with `nil` and
/// the task and the upstream continuation should be cancelled.
case resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
/// Indicates that the downstream continuation should be resumed with `nil` and
/// the task and the upstream continuation should be cancelled.
case resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
element: Element,
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
}
mutating func upstreamFinished() -> UpstreamFinishedAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .waitingForDemand(_, .some, _, _):
// We will never receive an upstream finished and have an outstanding continuation
// since we only receive finish after resuming the upstream continuation
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .waitingForDemand(_, .none, _, .some):
// We will never receive an upstream finished while we have a buffered element
// To get there we would need to have received the buffered element and then
// received upstream finished all while waiting for demand; however, we should have
// never demanded the next element from upstream in the first place
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .upstreamFailure:
// The upstream already failed so it should never have finished again
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(let task, .none, let clockContinuation, .none):
// We don't have any buffered element so we can just go ahead
// and transition to finished and cancel everything
self.state = .finished
return .cancelTaskAndClockContinuation(
task: task,
clockContinuation: clockContinuation
)
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
// We demanded the next element from the upstream after we got signalled demand
// and the upstream finished. This means we need to resume the downstream with nil
self.state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuation: nil,
clockContinuation: clockContinuation
)
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, let currentElement):
// We are debouncing and the upstream finished. At this point
// we can just resume the downstream continuation with element and cancel everything else
self.state = .finished
return .resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: downstreamContinuation,
element: currentElement.element,
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: nil
)
case .finished:
// This is just everything finishing up, nothing to do here
return .none
}
}
/// Actions returned by `upstreamThrew()`.
enum UpstreamThrewAction {
/// Indicates that the task and the clock continuation should be cancelled.
case cancelTaskAndClockContinuation(
task: Task<Void, Never>,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
/// Indicates that the downstream continuation should be resumed with the `error` and
/// the task and the upstream continuation should be cancelled.
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
error: Error,
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
}
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .waitingForDemand(_, .some, _, _):
// We will never receive an upstream threw and have an outstanding continuation
// since we only receive threw after resuming the upstream continuation
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .waitingForDemand(_, .none, _, .some):
// We will never receive an upstream threw while we have a buffered element
// To get there we would need to have received the buffered element and then
// received upstream threw all while waiting for demand; however, we should have
// never demanded the next element from upstream in the first place
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .upstreamFailure:
// The upstream already failed so it should never have throw again.
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(let task, .none, let clockContinuation, .none):
// We don't have any buffered element so we can just go ahead
// and transition to finished and cancel everything
self.state = .finished
return .cancelTaskAndClockContinuation(
task: task,
clockContinuation: clockContinuation
)
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
// We demanded the next element from the upstream after we got signalled demand
// and the upstream threw. This means we need to resume the downstream with the error
self.state = .finished
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
downstreamContinuation: downstreamContinuation,
error: error,
task: task,
upstreamContinuation: nil,
clockContinuation: clockContinuation
)
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
// We are debouncing and the upstream threw. At this point
// we can just resume the downstream continuation with error and cancel everything else
self.state = .finished
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
downstreamContinuation: downstreamContinuation,
error: error,
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: nil
)
case .finished:
// This is just everything finishing up, nothing to do here
return .none
}
}
/// Actions returned by `clockTaskSuspended()`.
enum ClockTaskSuspendedAction {
/// Indicates that the continuation should be resumed which will lead to calling `sleep` on the Clock.
case resumeContinuation(
clockContinuation: UnsafeContinuation<C.Instant, Error>,
deadline: C.Instant
)
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
case resumeContinuationWithError(
clockContinuation: UnsafeContinuation<C.Instant, Error>,
error: Error
)
}
mutating func clockTaskSuspended(_ continuation: UnsafeContinuation<C.Instant, Error>) -> ClockTaskSuspendedAction? {
switch self.state {
case .initial:
// Child tasks are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
case .waitingForDemand(_, _, .some, _):
// We already have a clock continuation so we can never get a second one
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
case .demandSignalled(_, .some, _):
// We already have a clock continuation so we can never get a second one
preconditionFailure("Internal inconsistency current state \(self.state) and received clockTaskSuspended()")
case .waitingForDemand(let task, let upstreamContinuation, .none, let bufferedElement):
// The clock child task suspended and we just need to store the continuation until
// demand is signalled
self.state = .waitingForDemand(
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: continuation,
bufferedElement: bufferedElement
)
return .none
case .demandSignalled(let task, .none, let downstreamContinuation):
// The demand was signalled but we haven't gotten the first element from the upstream yet
// so we need to stay in this state and do nothing
self.state = .demandSignalled(
task: task,
clockContinuation: continuation,
downstreamContinuation: downstreamContinuation
)
return .none
case .debouncing(_, _, _, let currentElement):
// We are currently debouncing and the Clock task suspended
// We need to resume the continuation right away.
return .resumeContinuation(
clockContinuation: continuation,
deadline: currentElement.deadline
)
case .upstreamFailure:
// The upstream failed while we were waiting to suspend the clock task again
// The task should have already been cancelled and we just need to cancel the continuation
return .resumeContinuationWithError(
clockContinuation: continuation,
error: CancellationError()
)
case .finished:
// Since cancellation is cooperative it might be that child tasks are still getting
// suspended even though we already cancelled them. We must tolerate this and just resume
// the continuation with an error.
return .resumeContinuationWithError(
clockContinuation: continuation,
error: CancellationError()
)
}
}
/// Actions returned by `clockSleepFinished()`.
enum ClockSleepFinishedAction {
/// Indicates that the downstream continuation should be resumed with the given element.
case resumeDownStreamContinuation(
downStreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
element: Element
)
}
mutating func clockSleepFinished() -> ClockSleepFinishedAction? {
switch self.state {
case .initial:
// Child tasks are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
case .waitingForDemand:
// This can never happen since we kicked-off the Clock.sleep because we got signalled demand.
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
case .demandSignalled:
// This can never happen since we are still waiting for the first element until we resume the Clock sleep.
preconditionFailure("Internal inconsistency current state \(self.state) and received clockSleepFinished()")
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, let currentElement):
if currentElement.deadline <= self.clock.now {
// The deadline for the last produced element expired and we can forward it to the downstream
self.state = .waitingForDemand(
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: nil,
bufferedElement: nil
)
return .resumeDownStreamContinuation(
downStreamContinuation: downstreamContinuation,
element: currentElement.element
)
} else {
// The deadline is still in the future so we need to sleep again
return .none
}
case .upstreamFailure:
// The upstream failed before the Clock.sleep finished
// We already cleaned everything up so nothing left to do here.
return .none
case .finished:
// The upstream failed before the Clock.sleep finished
// We already cleaned everything up so nothing left to do here.
return .none
}
}
/// Actions returned by `cancelled()`.
enum CancelledAction {
/// Indicates that the downstream continuation needs to be resumed and
/// task and the upstream continuations should be cancelled.
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: UnsafeContinuation<Result<Element?, Error>, Never>,
task: Task<Void, Never>,
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?
)
}
mutating func cancelled() -> CancelledAction? {
switch self.state {
case .initial:
state = .finished
return .none
case .waitingForDemand:
// We got cancelled before we event got any demand. This can happen if a cancelled task
// calls next and the onCancel handler runs first. We can transition to finished right away.
self.state = .finished
return .none
case .demandSignalled(let task, let clockContinuation, let downstreamContinuation):
// We got cancelled while we were waiting for the first upstream element
// We can cancel everything at this point and return nil
self.state = .finished
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuation: nil,
clockContinuation: clockContinuation
)
case .debouncing(let task, let upstreamContinuation, let downstreamContinuation, _):
// We got cancelled while debouncing.
// We can cancel everything at this point and return nil
self.state = .finished
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuation: upstreamContinuation,
clockContinuation: nil
)
case .upstreamFailure:
// An upstream already threw and we cancelled everything already.
// We should stay in the upstream failure state until the error is consumed
return .none
case .finished:
// We are already finished so nothing to do here:
self.state = .finished
return .none
}
}
/// Actions returned by `next()`.
enum NextAction {
/// Indicates that a new `Task` should be created that consumes the sequence.
case startTask(Base)
case resumeUpstreamContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>?
)
case resumeUpstreamAndClockContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>?,
clockContinuation: UnsafeContinuation<C.Instant, Error>?,
deadline: C.Instant
)
/// Indicates that the downstream continuation should be resumed with `nil`.
case resumeDownstreamContinuationWithNil(UnsafeContinuation<Result<Element?, Error>, Never>)
/// Indicates that the downstream continuation should be resumed with the error.
case resumeDownstreamContinuationWithError(
UnsafeContinuation<Result<Element?, Error>, Never>,
Error
)
}
mutating func next(for continuation: UnsafeContinuation<Result<Element?, Error>, Never>) -> NextAction {
switch self.state {
case .initial(let base):
// This is the first time we get demand singalled so we have to start the task
// The transition to the next state is done in the taskStarted method
return .startTask(base)
case .demandSignalled, .debouncing:
// We already got demand signalled and have suspended the downstream task
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
case .waitingForDemand(let task, let upstreamContinuation, let clockContinuation, let bufferedElement):
if let bufferedElement = bufferedElement {
// We already got an element from the last buffered one
// We can kick of the clock and upstream consumption right away and transition to debouncing
self.state = .debouncing(
task: task,
upstreamContinuation: nil,
downstreamContinuation: continuation,
currentElement: bufferedElement
)
return .resumeUpstreamAndClockContinuation(
upstreamContinuation: upstreamContinuation,
clockContinuation: clockContinuation,
deadline: bufferedElement.deadline
)
} else {
// We don't have a buffered element so have to resume the upstream continuation
// to get the first one and transition to demandSignalled
self.state = .demandSignalled(
task: task,
clockContinuation: clockContinuation,
downstreamContinuation: continuation
)
return .resumeUpstreamContinuation(upstreamContinuation: upstreamContinuation)
}
case .upstreamFailure(let error):
// The upstream threw and haven't delivered the error yet
// Let's deliver it and transition to finished
self.state = .finished
return .resumeDownstreamContinuationWithError(continuation, error)
case .finished:
// We are already finished so we are just returning `nil`
return .resumeDownstreamContinuationWithNil(continuation)
}
}
}
@@ -0,0 +1,296 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
final class DebounceStorage<Base: AsyncSequence, C: Clock>: @unchecked Sendable where Base: Sendable {
typealias Element = Base.Element
/// The state machine protected with a lock.
private let stateMachine: ManagedCriticalState<DebounceStateMachine<Base, C>>
/// The interval to debounce.
private let interval: C.Instant.Duration
/// The tolerance for the clock.
private let tolerance: C.Instant.Duration?
/// The clock.
private let clock: C
init(base: Base, interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
self.stateMachine = .init(.init(base: base, clock: clock, interval: interval))
self.interval = interval
self.tolerance = tolerance
self.clock = clock
}
func iteratorDeinitialized() {
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
switch action {
case .cancelTaskAndUpstreamAndClockContinuations(
let task,
let upstreamContinuation,
let clockContinuation
):
upstreamContinuation?.resume(throwing: CancellationError())
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
case .none:
break
}
}
func next() async rethrows -> Element? {
// We need to handle cancellation here because we are creating a continuation
// and because we need to cancel the `Task` we created to consume the upstream
return try await withTaskCancellationHandler {
// We always suspend since we can never return an element right away
let result: Result<Element?, Error> = await withUnsafeContinuation { continuation in
self.stateMachine.withCriticalRegion {
let action = $0.next(for: continuation)
switch action {
case .startTask(let base):
self.startTask(
stateMachine: &$0,
base: base,
downstreamContinuation: continuation
)
case .resumeUpstreamContinuation(let upstreamContinuation):
// This is signalling the upstream task that is consuming the upstream
// sequence to signal demand.
upstreamContinuation?.resume(returning: ())
case .resumeUpstreamAndClockContinuation(let upstreamContinuation, let clockContinuation, let deadline):
// This is signalling the upstream task that is consuming the upstream
// sequence to signal demand and start the clock task.
upstreamContinuation?.resume(returning: ())
clockContinuation?.resume(returning: deadline)
case .resumeDownstreamContinuationWithNil(let continuation):
continuation.resume(returning: .success(nil))
case .resumeDownstreamContinuationWithError(let continuation, let error):
continuation.resume(returning: .failure(error))
}
}
}
return try result._rethrowGet()
} onCancel: {
let action = self.stateMachine.withCriticalRegion { $0.cancelled() }
switch action {
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
let downstreamContinuation,
let task,
let upstreamContinuation,
let clockContinuation
):
upstreamContinuation?.resume(throwing: CancellationError())
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .none:
break
}
}
}
private func startTask(
stateMachine: inout DebounceStateMachine<Base, C>,
base: Base,
downstreamContinuation: UnsafeContinuation<Result<Base.Element?, Error>, Never>
) {
let task = Task {
await withThrowingTaskGroup(of: Void.self) { group in
// The task that consumes the upstream sequence
group.addTask {
var iterator = base.makeAsyncIterator()
// This is our upstream consumption loop
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand
// and until the Clock sleep finished.
try await withUnsafeThrowingContinuation { continuation in
let action = self.stateMachine.withCriticalRegion { $0.upstreamTaskSuspended(continuation) }
switch action {
case .resumeContinuation(let continuation):
// This happens if there is outstanding demand
// and we need to demand from upstream right away
continuation.resume(returning: ())
case .resumeContinuationWithError(let continuation, let error):
// This happens if the task got cancelled.
continuation.resume(throwing: error)
case .none:
break
}
}
// We got signalled from the downstream that we have demand so let's
// request a new element from the upstream
if let element = try await iterator.next() {
let action = self.stateMachine.withCriticalRegion {
let deadline = self.clock.now.advanced(by: self.interval)
return $0.elementProduced(element, deadline: deadline)
}
switch action {
case .resumeClockContinuation(let clockContinuation, let deadline):
clockContinuation?.resume(returning: deadline)
case .none:
break
}
} else {
// The upstream returned `nil` which indicates that it finished
let action = self.stateMachine.withCriticalRegion { $0.upstreamFinished() }
// All of this is mostly cleanup around the Task and the outstanding
// continuations used for signalling.
switch action {
case .cancelTaskAndClockContinuation(let task, let clockContinuation):
task.cancel()
clockContinuation?.resume(throwing: CancellationError())
break loop
case .resumeContinuationWithNilAndCancelTaskAndUpstreamAndClockContinuation(
let downstreamContinuation,
let task,
let upstreamContinuation,
let clockContinuation
):
upstreamContinuation?.resume(throwing: CancellationError())
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
break loop
case .resumeContinuationWithElementAndCancelTaskAndUpstreamAndClockContinuation(
let downstreamContinuation,
let element,
let task,
let upstreamContinuation,
let clockContinuation
):
upstreamContinuation?.resume(throwing: CancellationError())
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
downstreamContinuation.resume(returning: .success(element))
break loop
case .none:
break loop
}
}
}
}
group.addTask {
// This is our clock scheduling loop
loop: while true {
do {
// We are creating a continuation sleeping on the Clock.
// This continuation is only resumed if the downstream consumer called `next`.
let deadline: C.Instant = try await withUnsafeThrowingContinuation { continuation in
let action = self.stateMachine.withCriticalRegion { $0.clockTaskSuspended(continuation) }
switch action {
case .resumeContinuation(let continuation, let deadline):
// This happens if there is outstanding demand
// and we need to demand from upstream right away
continuation.resume(returning: deadline)
case .resumeContinuationWithError(let continuation, let error):
// This happens if the task got cancelled.
continuation.resume(throwing: error)
case .none:
break
}
}
try await self.clock.sleep(until: deadline, tolerance: self.tolerance)
let action = self.stateMachine.withCriticalRegion { $0.clockSleepFinished() }
switch action {
case .resumeDownStreamContinuation(let downStreamContinuation, let element):
downStreamContinuation.resume(returning: .success(element))
case .none:
break
}
} catch {
// The only error that we expect is the `CancellationError`
// thrown from the Clock.sleep or from the withUnsafeContinuation.
// This happens if we are cleaning everything up. We can just drop that error and break our loop
precondition(error is CancellationError, "Received unexpected error \(error) in the Clock loop")
break loop
}
}
}
do {
try await group.waitForAll()
} catch {
// The upstream sequence threw an error
let action = self.stateMachine.withCriticalRegion { $0.upstreamThrew(error) }
switch action {
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuation(
let downstreamContinuation,
let error,
let task,
let upstreamContinuation,
let clockContinuation
):
upstreamContinuation?.resume(throwing: CancellationError())
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
downstreamContinuation.resume(returning: .failure(error))
case .cancelTaskAndClockContinuation(
let task,
let clockContinuation
):
clockContinuation?.resume(throwing: CancellationError())
task.cancel()
case .none:
break
}
group.cancelAll()
}
}
}
stateMachine.taskStarted(task, downstreamContinuation: downstreamContinuation)
}
}
+27 -3
View File
@@ -37,7 +37,8 @@ internal struct Lock {
#if canImport(Darwin)
platformLock.initialize(to: os_unfair_lock())
#elseif canImport(Glibc)
pthread_mutex_init(platformLock, nil)
let result = pthread_mutex_init(platformLock, nil)
precondition(result == 0, "pthread_mutex_init failed")
#elseif canImport(WinSDK)
InitializeSRWLock(platformLock)
#endif
@@ -45,7 +46,8 @@ internal struct Lock {
fileprivate static func deinitialize(_ platformLock: PlatformLock) {
#if canImport(Glibc)
pthread_mutex_destroy(platformLock)
let result = pthread_mutex_destroy(platformLock)
precondition(result == 0, "pthread_mutex_destroy failed")
#endif
platformLock.deinitialize(count: 1)
}
@@ -64,7 +66,8 @@ internal struct Lock {
#if canImport(Darwin)
os_unfair_lock_unlock(platformLock)
#elseif canImport(Glibc)
pthread_mutex_unlock(platformLock)
let result = pthread_mutex_unlock(platformLock)
precondition(result == 0, "pthread_mutex_unlock failed")
#elseif canImport(WinSDK)
ReleaseSRWLockExclusive(platformLock)
#endif
@@ -87,6 +90,27 @@ internal struct Lock {
func unlock() {
Lock.unlock(platformLock)
}
/// Acquire the lock for the duration of the given block.
///
/// This convenience method should be preferred to `lock` and `unlock` in
/// most situations, as it ensures that the lock will be released regardless
/// of how `body` exits.
///
/// - Parameter body: The block to execute while holding the lock.
/// - Returns: The value returned by the block.
func withLock<T>(_ body: () throws -> T) rethrows -> T {
self.lock()
defer {
self.unlock()
}
return try body()
}
// specialise Void return (for performance)
func withLockVoid(_ body: () throws -> Void) rethrows -> Void {
try self.withLock(body)
}
}
struct ManagedCriticalState<State> {
@@ -0,0 +1,94 @@
//===----------------------------------------------------------------------===//
//
// 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
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
/// Creates an asynchronous sequence of elements from two underlying asynchronous sequences
public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
where
Base1.Element == Base2.Element,
Base1: Sendable, Base2: Sendable,
Base1.Element: Sendable
{
return AsyncMerge2Sequence(base1, base2)
}
/// An ``Swift/AsyncSequence`` that takes two upstream ``Swift/AsyncSequence``s and combines their elements.
public struct AsyncMerge2Sequence<
Base1: AsyncSequence,
Base2: AsyncSequence
>: Sendable where
Base1.Element == Base2.Element,
Base1: Sendable, Base2: Sendable,
Base1.Element: Sendable
{
public typealias Element = Base1.Element
private let base1: Base1
private let base2: Base2
/// Initializes a new ``AsyncMerge2Sequence``.
///
/// - Parameters:
/// - base1: The first upstream ``Swift/AsyncSequence``.
/// - base2: The second upstream ``Swift/AsyncSequence``.
public init(
_ base1: Base1,
_ base2: Base2
) {
self.base1 = base1
self.base2 = base2
}
}
extension AsyncMerge2Sequence: AsyncSequence {
public func makeAsyncIterator() -> AsyncIterator {
let storage = MergeStorage<Base1, Base2, Base1>(
base1: base1,
base2: base2,
base3: nil
)
return AsyncIterator(storage: storage)
}
}
extension AsyncMerge2Sequence {
public struct AsyncIterator: AsyncIteratorProtocol {
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
///
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
final class InternalClass: Sendable {
private let storage: MergeStorage<Base1, Base2, Base1>
fileprivate init(storage: MergeStorage<Base1, Base2, Base1>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
try await storage.next()
}
}
let internalClass: InternalClass
fileprivate init(storage: MergeStorage<Base1, Base2, Base1>) {
internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await internalClass.next()
}
}
}
@@ -0,0 +1,105 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
/// Creates an asynchronous sequence of elements from two underlying asynchronous sequences
public func merge<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncMerge3Sequence<Base1, Base2, Base3>
where
Base1.Element == Base2.Element,
Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable,
Base1.Element: Sendable
{
return AsyncMerge3Sequence(base1, base2, base3)
}
/// An ``Swift/AsyncSequence`` that takes three upstream ``Swift/AsyncSequence``s and combines their elements.
public struct AsyncMerge3Sequence<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: Sendable where
Base1.Element == Base2.Element,
Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable,
Base1.Element: Sendable
{
public typealias Element = Base1.Element
private let base1: Base1
private let base2: Base2
private let base3: Base3
/// Initializes a new ``AsyncMerge2Sequence``.
///
/// - Parameters:
/// - base1: The first upstream ``Swift/AsyncSequence``.
/// - base2: The second upstream ``Swift/AsyncSequence``.
/// - base3: The third upstream ``Swift/AsyncSequence``.
public init(
_ base1: Base1,
_ base2: Base2,
_ base3: Base3
) {
self.base1 = base1
self.base2 = base2
self.base3 = base3
}
}
extension AsyncMerge3Sequence: AsyncSequence {
public func makeAsyncIterator() -> AsyncIterator {
let storage = MergeStorage(
base1: base1,
base2: base2,
base3: base3
)
return AsyncIterator(storage: storage)
}
}
public extension AsyncMerge3Sequence {
struct AsyncIterator: AsyncIteratorProtocol {
/// This class is needed to hook the deinit to observe once all references to the ``AsyncIterator`` are dropped.
///
/// If we get move-only types we should be able to drop this class and use the `deinit` of the ``AsyncIterator`` struct itself.
final class InternalClass: Sendable {
private let storage: MergeStorage<Base1, Base2, Base3>
fileprivate init(storage: MergeStorage<Base1, Base2, Base3>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
try await storage.next()
}
}
let internalClass: InternalClass
fileprivate init(storage: MergeStorage<Base1, Base2, Base3>) {
internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await internalClass.next()
}
}
}
@@ -0,0 +1,629 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@_implementationOnly import DequeModule
/// The state machine for any of the `merge` operator.
///
/// Right now this state machine supports 3 upstream `AsyncSequences`; however, this can easily be extended.
/// Once variadic generic land we should migrate this to use them instead.
struct MergeStateMachine<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
> where
Base1.Element == Base2.Element,
Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable,
Base1.Element: Sendable
{
typealias Element = Base1.Element
private enum State {
/// The initial state before a call to `makeAsyncIterator` happened.
case initial(
base1: Base1,
base2: Base2,
base3: Base3?
)
/// The state after `makeAsyncIterator` was called and we created our `Task` to consume the upstream.
case merging(
task: Task<Void, Never>,
buffer: Deque<Element>,
upstreamContinuations: [UnsafeContinuation<Void, Error>],
upstreamsFinished: Int,
downstreamContinuation: UnsafeContinuation<Element?, Error>?
)
/// The state once any of the upstream sequences threw an `Error`.
case upstreamFailure(
buffer: Deque<Element>,
error: Error
)
/// The state once all upstream sequences finished or the downstream consumer stopped, i.e. by dropping all references
/// or by getting their `Task` cancelled.
case finished
/// Internal state to avoid CoW.
case modifying
}
/// The state machine's current state.
private var state: State
private let numberOfUpstreamSequences: Int
/// Initializes a new `StateMachine`.
init(
base1: Base1,
base2: Base2,
base3: Base3?
) {
state = .initial(
base1: base1,
base2: base2,
base3: base3
)
if base3 == nil {
self.numberOfUpstreamSequences = 2
} else {
self.numberOfUpstreamSequences = 3
}
}
/// Actions returned by `iteratorDeinitialized()`.
enum IteratorDeinitializedAction {
/// Indicates that the `Task` needs to be cancelled and
/// all upstream continuations need to be resumed with a `CancellationError`.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that nothing should be done.
case none
}
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction {
switch state {
case .initial:
// Nothing to do here. No demand was signalled until now
return .none
case .merging(_, _, _, _, .some):
// An iterator was deinitialized while we have a suspended continuation.
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
case let .merging(task, _, upstreamContinuations, _, .none):
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now and need to clean everything up.
state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: upstreamContinuations
)
case .upstreamFailure:
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now. The cleanup already happened when we
// transitioned to `upstreamFailure`.
state = .finished
return .none
case .finished:
// We are already finished so there is nothing left to clean up.
// This is just the references dropping afterwards.
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
mutating func taskStarted(_ task: Task<Void, Never>) {
switch state {
case .initial:
// The user called `makeAsyncIterator` and we are starting the `Task`
// to consume the upstream sequences
state = .merging(
task: task,
buffer: .init(),
upstreamContinuations: [], // This should reserve capacity in the variadic generics case
upstreamsFinished: 0,
downstreamContinuation: nil
)
case .merging, .upstreamFailure, .finished:
// We only a single iterator to be created so this must never happen.
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `childTaskSuspended()`.
enum ChildTaskSuspendedAction {
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
case resumeContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>
)
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
case resumeContinuationWithError(
upstreamContinuation: UnsafeContinuation<Void, Error>,
error: Error
)
/// Indicates that nothing should be done.
case none
}
mutating func childTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction {
switch state {
case .initial:
// Child tasks are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .merging(_, _, _, _, .some):
// We have outstanding demand so request the next element
return .resumeContinuation(upstreamContinuation: continuation)
case .merging(let task, let buffer, var upstreamContinuations, let upstreamsFinished, .none):
// There is no outstanding demand from the downstream
// so we are storing the continuation and resume it once there is demand.
state = .modifying
upstreamContinuations.append(continuation)
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
return .none
case .upstreamFailure:
// Another upstream already threw so we just need to throw from this continuation
// which will end the consumption of the upstream.
return .resumeContinuationWithError(
upstreamContinuation: continuation,
error: CancellationError()
)
case .finished:
// Since cancellation is cooperative it might be that child tasks are still getting
// suspended even though we already cancelled them. We must tolerate this and just resume
// the continuation with an error.
return .resumeContinuationWithError(
upstreamContinuation: continuation,
error: CancellationError()
)
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `elementProduced()`.
enum ElementProducedAction {
/// Indicates that the downstream continuation should be resumed with the element.
case resumeContinuation(
downstreamContinuation: UnsafeContinuation<Element?, Error>,
element: Element
)
/// Indicates that nothing should be done.
case none
}
mutating func elementProduced(_ element: Element) -> ElementProducedAction {
switch state {
case .initial:
// Child tasks that are producing elements are only created after we transitioned to `merging`
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case let .merging(task, buffer, upstreamContinuations, upstreamsFinished, .some(downstreamContinuation)):
// We produced an element and have an outstanding downstream continuation
// this means we can go right ahead and resume the continuation with that element
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
return .resumeContinuation(
downstreamContinuation: downstreamContinuation,
element: element
)
case .merging(let task, var buffer, let upstreamContinuations, let upstreamsFinished, .none):
// There is not outstanding downstream continuation so we must buffer the element
// This happens if we race our upstream sequences to produce elements
// and the _losers_ are signalling their produced element
state = .modifying
buffer.append(element)
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
return .none
case .upstreamFailure:
// Another upstream already produced an error so we just drop the new element
return .none
case .finished:
// Since cancellation is cooperative it might be that child tasks
// are still producing elements after we finished.
// We are just going to drop them since there is nothing we can do
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamFinished()`.
enum UpstreamFinishedAction {
/// Indicates that the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with `nil` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: UnsafeContinuation<Element?, Error>,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that nothing should be done.
case none
}
mutating func upstreamFinished() -> UpstreamFinishedAction {
switch state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .merging(let task, let buffer, let upstreamContinuations, var upstreamsFinished, let .some(downstreamContinuation)):
// One of the upstreams finished
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
// First we increment our counter of finished upstreams
upstreamsFinished += 1
if upstreamsFinished == self.numberOfUpstreamSequences {
// All of our upstreams have finished and we can transition to finished now
// We also need to cancel the tasks and any outstanding continuations
state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: upstreamContinuations
)
} else {
// There are still upstreams that haven't finished so we are just storing our new
// counter of finished upstreams
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: downstreamContinuation
)
return .none
}
case .merging(let task, let buffer, let upstreamContinuations, var upstreamsFinished, .none):
// First we increment our counter of finished upstreams
upstreamsFinished += 1
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
if upstreamsFinished == self.numberOfUpstreamSequences {
// All of our upstreams have finished; however, we are only transitioning to
// finished once our downstream calls `next` again.
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: upstreamContinuations
)
} else {
// There are still upstreams that haven't finished.
return .none
}
case .upstreamFailure:
// Another upstream threw already so we can just ignore this finish
return .none
case .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamThrew()`.
enum UpstreamThrewAction {
/// Indicates that the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with the `error` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: UnsafeContinuation<Element?, Error>,
error: Error,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that nothing should be done.
case none
}
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction {
switch state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case let .merging(task, buffer, upstreamContinuations, _, .some(downstreamContinuation)):
// An upstream threw an error and we have a downstream continuation.
// We just need to resume the downstream continuation with the error and cancel everything
precondition(buffer.isEmpty, "We are holding a continuation so the buffer must be empty")
// We can transition to finished right away because we are returning the error
state = .finished
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
error: error,
task: task,
upstreamContinuations: upstreamContinuations
)
case let .merging(task, buffer, upstreamContinuations, _, .none):
// An upstream threw an error and we don't have a downstream continuation.
// We need to store the error and wait for the downstream to consume the
// rest of the buffer and the error. However, we can already cancel the task
// and the other upstream continuations since we won't need any more elements.
state = .upstreamFailure(
buffer: buffer,
error: error
)
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: upstreamContinuations
)
case .upstreamFailure:
// Another upstream threw already so we can just ignore this error
return .none
case .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `cancelled()`.
enum CancelledAction {
/// Indicates that the downstream continuation needs to be resumed and
/// task and the upstream continuations should be cancelled.
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: UnsafeContinuation<Element?, Error>,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that nothing should be done.
case none
}
mutating func cancelled() -> CancelledAction {
switch state {
case .initial:
// Since we are only transitioning to merging when the task is started we
// can be cancelled already.
state = .finished
return .none
case let .merging(task, _, upstreamContinuations, _, .some(downstreamContinuation)):
// The downstream Task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
state = .finished
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: upstreamContinuations
)
case let .merging(task, _, upstreamContinuations, _, .none):
// The downstream Task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: upstreamContinuations
)
case .upstreamFailure:
// An upstream already threw and we cancelled everything already.
// We can just transition to finished now
state = .finished
return .none
case .finished:
// We are already finished so nothing to do here:
state = .finished
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `next()`.
enum NextAction {
/// Indicates that a new `Task` should be created that consumes the sequence and the downstream must be supsended
case startTaskAndSuspendDownstreamTask(Base1, Base2, Base3?)
/// Indicates that the `element` should be returned.
case returnElement(Result<Element, Error>)
/// Indicates that `nil` should be returned.
case returnNil
/// Indicates that the `error` should be thrown.
case throwError(Error)
/// Indicates that the downstream task should be suspended.
case suspendDownstreamTask
}
mutating func next() -> NextAction {
switch state {
case .initial(let base1, let base2, let base3):
// This is the first time we got demand signalled. We need to start the task now
// We are transitioning to merging in the taskStarted method.
return .startTaskAndSuspendDownstreamTask(base1, base2, base3)
case .merging(_, _, _, _, .some):
// We have multiple AsyncIterators iterating the sequence
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
case .merging(let task, var buffer, let upstreamContinuations, let upstreamsFinished, .none):
state = .modifying
if let element = buffer.popFirst() {
// We have an element buffered already so we can just return that.
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
return .returnElement(.success(element))
} else {
// There was nothing in the buffer so we have to suspend the downstream task
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: upstreamContinuations,
upstreamsFinished: upstreamsFinished,
downstreamContinuation: nil
)
return .suspendDownstreamTask
}
case .upstreamFailure(var buffer, let error):
state = .modifying
if let element = buffer.popFirst() {
// There was still a left over element that we need to return
state = .upstreamFailure(
buffer: buffer,
error: error
)
return .returnElement(.success(element))
} else {
// The buffer is empty and we can now throw the error
// that an upstream produced
state = .finished
return .throwError(error)
}
case .finished:
// We are already finished so we are just returning `nil`
return .returnNil
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `next(for)`.
enum NextForAction {
/// Indicates that the upstream continuations should be resumed to demand new elements.
case resumeUpstreamContinuations(
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func next(for continuation: UnsafeContinuation<Element?, Error>) -> NextForAction {
switch state {
case .initial,
.merging(_, _, _, _, .some),
.upstreamFailure,
.finished:
// All other states are handled by `next` already so we should never get in here with
// any of those
preconditionFailure("Internal inconsistency current state \(self.state) and received next(for:)")
case let .merging(task, buffer, upstreamContinuations, upstreamsFinished, .none):
// We suspended the task and need signal the upstreams
state = .merging(
task: task,
buffer: buffer,
upstreamContinuations: [], // TODO: don't alloc new array here
upstreamsFinished: upstreamsFinished,
downstreamContinuation: continuation
)
return .resumeUpstreamContinuations(
upstreamContinuations: upstreamContinuations
)
case .modifying:
preconditionFailure("Invalid state")
}
}
}
@@ -0,0 +1,449 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
final class MergeStorage<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: @unchecked Sendable where
Base1.Element == Base2.Element,
Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable,
Base1.Element: Sendable
{
typealias Element = Base1.Element
/// The lock that protects our state.
private let lock = Lock.allocate()
/// The state machine.
private var stateMachine: MergeStateMachine<Base1, Base2, Base3>
init(
base1: Base1,
base2: Base2,
base3: Base3?
) {
stateMachine = .init(base1: base1, base2: base2, base3: base3)
}
deinit {
self.lock.deinitialize()
}
func iteratorDeinitialized() {
let action = lock.withLock { self.stateMachine.iteratorDeinitialized() }
switch action {
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
func next() async rethrows -> Element? {
// We need to handle cancellation here because we are creating a continuation
// and because we need to cancel the `Task` we created to consume the upstream
try await withTaskCancellationHandler {
self.lock.lock()
let action = self.stateMachine.next()
switch action {
case .startTaskAndSuspendDownstreamTask(let base1, let base2, let base3):
self.startTask(
stateMachine: &self.stateMachine,
base1: base1,
base2: base2,
base3: base3
)
// It is safe to hold the lock across this method
// since the closure is guaranteed to be run straight away
return try await withUnsafeThrowingContinuation { continuation in
let action = self.stateMachine.next(for: continuation)
self.lock.unlock()
switch action {
case let .resumeUpstreamContinuations(upstreamContinuations):
// This is signalling the child tasks that are consuming the upstream
// sequences to signal demand.
upstreamContinuations.forEach { $0.resume(returning: ()) }
}
}
case let .returnElement(element):
self.lock.unlock()
return try element._rethrowGet()
case .returnNil:
self.lock.unlock()
return nil
case let .throwError(error):
self.lock.unlock()
throw error
case .suspendDownstreamTask:
// It is safe to hold the lock across this method
// since the closure is guaranteed to be run straight away
return try await withUnsafeThrowingContinuation { continuation in
let action = self.stateMachine.next(for: continuation)
self.lock.unlock()
switch action {
case let .resumeUpstreamContinuations(upstreamContinuations):
// This is signalling the child tasks that are consuming the upstream
// sequences to signal demand.
upstreamContinuations.forEach { $0.resume(returning: ()) }
}
}
}
} onCancel: {
let action = self.lock.withLock { self.stateMachine.cancelled() }
switch action {
case let .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation,
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: nil)
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
}
private func startTask(stateMachine: inout MergeStateMachine<Base1, Base2, Base3>, base1: Base1, base2: Base2, base3: Base3?) {
// This creates a new `Task` that is iterating the upstream
// sequences. We must store it to cancel it at the right times.
let task = Task {
await withThrowingTaskGroup(of: Void.self) { group in
// For each upstream sequence we are adding a child task that
// is consuming the upstream sequence
group.addTask {
var iterator1 = base1.makeAsyncIterator()
// This is our upstream consumption loop
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
let action = self.lock.withLock {
self.stateMachine.childTaskSuspended(continuation)
}
switch action {
case let .resumeContinuation(continuation):
// This happens if there is outstanding demand
// and we need to demand from upstream right away
continuation.resume(returning: ())
case let .resumeContinuationWithError(continuation, error):
// This happens if another upstream already failed or if
// the task got cancelled.
continuation.resume(throwing: error)
case .none:
break
}
}
// We got signalled from the downstream that we have demand so let's
// request a new element from the upstream
if let element1 = try await iterator1.next() {
let action = self.lock.withLock {
self.stateMachine.elementProduced(element1)
}
switch action {
case let .resumeContinuation(continuation, element):
// We had an outstanding demand and where the first
// upstream to produce an element so we can forward it to
// the downstream
continuation.resume(returning: element)
case .none:
break
}
} else {
// The upstream returned `nil` which indicates that it finished
let action = self.lock.withLock {
self.stateMachine.upstreamFinished()
}
// All of this is mostly cleanup around the Task and the outstanding
// continuations used for signalling.
switch action {
case let .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation,
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: nil)
break loop
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
// Copy from the above just using the base2 sequence
group.addTask {
var iterator2 = base2.makeAsyncIterator()
// This is our upstream consumption loop
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
let action = self.lock.withLock {
self.stateMachine.childTaskSuspended(continuation)
}
switch action {
case let .resumeContinuation(continuation):
// This happens if there is outstanding demand
// and we need to demand from upstream right away
continuation.resume(returning: ())
case let .resumeContinuationWithError(continuation, error):
// This happens if another upstream already failed or if
// the task got cancelled.
continuation.resume(throwing: error)
case .none:
break
}
}
// We got signalled from the downstream that we have demand so let's
// request a new element from the upstream
if let element2 = try await iterator2.next() {
let action = self.lock.withLock {
self.stateMachine.elementProduced(element2)
}
switch action {
case let .resumeContinuation(continuation, element):
// We had an outstanding demand and where the first
// upstream to produce an element so we can forward it to
// the downstream
continuation.resume(returning: element)
case .none:
break
}
} else {
// The upstream returned `nil` which indicates that it finished
let action = self.lock.withLock {
self.stateMachine.upstreamFinished()
}
// All of this is mostly cleanup around the Task and the outstanding
// continuations used for signalling.
switch action {
case let .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation,
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: nil)
break loop
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
// Copy from the above just using the base3 sequence
if let base3 = base3 {
group.addTask {
var iterator3 = base3.makeAsyncIterator()
// This is our upstream consumption loop
loop: while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
let action = self.lock.withLock {
self.stateMachine.childTaskSuspended(continuation)
}
switch action {
case let .resumeContinuation(continuation):
// This happens if there is outstanding demand
// and we need to demand from upstream right away
continuation.resume(returning: ())
case let .resumeContinuationWithError(continuation, error):
// This happens if another upstream already failed or if
// the task got cancelled.
continuation.resume(throwing: error)
case .none:
break
}
}
// We got signalled from the downstream that we have demand so let's
// request a new element from the upstream
if let element3 = try await iterator3.next() {
let action = self.lock.withLock {
self.stateMachine.elementProduced(element3)
}
switch action {
case let .resumeContinuation(continuation, element):
// We had an outstanding demand and where the first
// upstream to produce an element so we can forward it to
// the downstream
continuation.resume(returning: element)
case .none:
break
}
} else {
// The upstream returned `nil` which indicates that it finished
let action = self.lock.withLock {
self.stateMachine.upstreamFinished()
}
// All of this is mostly cleanup around the Task and the outstanding
// continuations used for signalling.
switch action {
case let .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation,
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: nil)
break loop
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
break loop
case .none:
break loop
}
}
}
}
}
do {
try await group.waitForAll()
} catch {
// One of the upstream sequences threw an error
let action = self.lock.withLock {
self.stateMachine.upstreamThrew(error)
}
switch action {
case let .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation,
error,
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(throwing: error)
case let .cancelTaskAndUpstreamContinuations(
task,
upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
group.cancelAll()
}
}
}
// We need to inform our state machine that we started the Task
stateMachine.taskStarted(task)
}
}
-12
View File
@@ -1,12 +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
//
//===----------------------------------------------------------------------===//
@_exported import ClockShims
+1 -1
View File
@@ -9,7 +9,7 @@
//
//===----------------------------------------------------------------------===//
// This is a hack around the fact that we dont have generic effects
// This is a hack around the fact that we don't have generic effects
// alternatively in the use cases we would want `rethrows(unsafe)`
// or something like that to avoid this nifty hack...
-78
View File
@@ -1,78 +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
//
//===----------------------------------------------------------------------===//
struct TaskSelectState<Success: Sendable, Failure: Error>: Sendable {
var complete = false
var tasks: [Task<Success, Failure>]? = []
mutating func add(_ task: Task<Success, Failure>) -> Task<Success, Failure>? {
if var tasks = tasks {
tasks.append(task)
self.tasks = tasks
return nil
} else {
return task
}
}
}
extension Task {
/// Determine the first task to complete of a sequence of tasks.
///
/// - Parameters:
/// - tasks: The running tasks to obtain a result from
/// - Returns: The first task to complete from the running tasks
public static func select<Tasks: Sequence & Sendable>(
_ tasks: Tasks
) async -> Task<Success, Failure>
where Tasks.Element == Task<Success, Failure> {
let state = ManagedCriticalState(TaskSelectState<Success, Failure>())
return await withTaskCancellationHandler {
let tasks = state.withCriticalRegion { state -> [Task<Success, Failure>] in
defer { state.tasks = nil }
return state.tasks ?? []
}
for task in tasks {
task.cancel()
}
} operation: {
await withUnsafeContinuation { continuation in
for task in tasks {
Task<Void, Never> {
_ = await task.result
let winner = state.withCriticalRegion { state -> Bool in
defer { state.complete = true }
return !state.complete
}
if winner {
continuation.resume(returning: task)
}
}
state.withCriticalRegion { state in
state.add(task)
}?.cancel()
}
}
}
}
/// Determine the first task to complete of a list of tasks.
///
/// - Parameters:
/// - tasks: The running tasks to obtain a result from
/// - Returns: The first task to complete from the running tasks
public static func select(
_ tasks: Task<Success, Failure>...
) async -> Task<Success, Failure> {
await select(tasks)
}
}
@@ -1,37 +0,0 @@
struct UnsafeResumption<Success, Failure: Error> {
let continuation: UnsafeContinuation<Success, Failure>
let result: Result<Success, Failure>
init(continuation: UnsafeContinuation<Success, Failure>, result: Result<Success, Failure>) {
self.continuation = continuation
self.result = result
}
init(continuation: UnsafeContinuation<Success, Failure>, success: Success) {
self.init(continuation: continuation, result: .success(success))
}
init(continuation: UnsafeContinuation<Success, Failure>, failure: Failure) {
self.init(continuation: continuation, result: .failure(failure))
}
func resume() {
continuation.resume(with: result)
}
}
extension UnsafeResumption where Failure == Error {
init(continuation: UnsafeContinuation<Success, Failure>, catching body: () throws -> Success) {
self.init(continuation: continuation, result: Result(catching: body))
}
}
extension UnsafeResumption where Success == Void {
init(continuation: UnsafeContinuation<Success, Failure>) {
self.init(continuation: continuation, result: .success(()))
}
}
extension UnsafeResumption: Sendable where Success: Sendable { }
@@ -0,0 +1,71 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// Creates an asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
/// and emits a tuple of the values.
public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(
_ base1: Base1,
_ base2: Base2
) -> AsyncZip2Sequence<Base1, Base2> {
AsyncZip2Sequence(base1, base2)
}
/// An asynchronous sequence that concurrently awaits values from two `AsyncSequence` types
/// and emits a tuple of the values.
public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: AsyncSequence, Sendable
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public typealias AsyncIterator = Iterator
let base1: Base1
let base2: Base2
init(_ base1: Base1, _ base2: Base2) {
self.base1 = base1
self.base2 = base2
}
public func makeAsyncIterator() -> AsyncIterator {
Iterator(storage: .init(self.base1, self.base2, nil))
}
public struct Iterator: AsyncIteratorProtocol {
final class InternalClass {
private let storage: ZipStorage<Base1, Base2, Base2>
fileprivate init(storage: ZipStorage<Base1, Base2, Base2>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
guard let element = try await self.storage.next() else {
return nil
}
return (element.0, element.1)
}
}
let internalClass: InternalClass
fileprivate init(storage: ZipStorage<Base1, Base2, Base2>) {
self.internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await self.internalClass.next()
}
}
}
@@ -0,0 +1,76 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// Creates an asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
/// and emits a tuple of the values.
public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(
_ base1: Base1,
_ base2: Base2,
_ base3: Base3
) -> AsyncZip3Sequence<Base1, Base2, Base3> {
AsyncZip3Sequence(base1, base2, base3)
}
/// An asynchronous sequence that concurrently awaits values from three `AsyncSequence` types
/// and emits a tuple of the values.
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: AsyncSequence, Sendable
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable, Base3: Sendable, Base3.Element: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public typealias AsyncIterator = Iterator
let base1: Base1
let base2: Base2
let base3: Base3
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
self.base1 = base1
self.base2 = base2
self.base3 = base3
}
public func makeAsyncIterator() -> AsyncIterator {
Iterator(storage: .init(self.base1, self.base2, self.base3)
)
}
public struct Iterator: AsyncIteratorProtocol {
final class InternalClass {
private let storage: ZipStorage<Base1, Base2, Base3>
fileprivate init(storage: ZipStorage<Base1, Base2, Base3>) {
self.storage = storage
}
deinit {
self.storage.iteratorDeinitialized()
}
func next() async rethrows -> Element? {
guard let element = try await self.storage.next() else {
return nil
}
// This force unwrap is safe since there must be a third element.
return (element.0, element.1, element.2!)
}
}
let internalClass: InternalClass
fileprivate init(storage: ZipStorage<Base1, Base2, Base3>) {
self.internalClass = InternalClass(storage: storage)
}
public mutating func next() async rethrows -> Element? {
try await self.internalClass.next()
}
}
}
@@ -0,0 +1,550 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
/// State machine for zip
struct ZipStateMachine<
Base1: AsyncSequence,
Base2: AsyncSequence,
Base3: AsyncSequence
>: Sendable where
Base1: Sendable,
Base2: Sendable,
Base3: Sendable,
Base1.Element: Sendable,
Base2.Element: Sendable,
Base3.Element: Sendable {
typealias DownstreamContinuation = UnsafeContinuation<Result<(
Base1.Element,
Base2.Element,
Base3.Element?
)?, Error>, Never>
private enum State: Sendable {
/// Small wrapper for the state of an upstream sequence.
struct Upstream<Element: Sendable>: Sendable {
/// The upstream continuation.
var continuation: UnsafeContinuation<Void, Error>?
/// The produced upstream element.
var element: Element?
}
/// The initial state before a call to `next` happened.
case initial(base1: Base1, base2: Base2, base3: Base3?)
/// The state while we are waiting for downstream demand.
case waitingForDemand(
task: Task<Void, Never>,
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>)
)
/// The state while we are consuming the upstream and waiting until we get a result from all upstreams.
case zipping(
task: Task<Void, Never>,
upstreams: (Upstream<Base1.Element>, Upstream<Base2.Element>, Upstream<Base3.Element>),
downstreamContinuation: DownstreamContinuation
)
/// The state once one upstream sequences finished/threw or the downstream consumer stopped, i.e. by dropping all references
/// or by getting their `Task` cancelled.
case finished
/// Internal state to avoid CoW.
case modifying
}
private var state: State
private let numberOfUpstreamSequences: Int
/// Initializes a new `StateMachine`.
init(
base1: Base1,
base2: Base2,
base3: Base3?
) {
self.state = .initial(
base1: base1,
base2: base2,
base3: base3
)
if base3 == nil {
self.numberOfUpstreamSequences = 2
} else {
self.numberOfUpstreamSequences = 3
}
}
/// Actions returned by `iteratorDeinitialized()`.
enum IteratorDeinitializedAction {
/// Indicates that the `Task` needs to be cancelled and
/// the upstream continuations need to be resumed with a `CancellationError`.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func iteratorDeinitialized() -> IteratorDeinitializedAction? {
switch self.state {
case .initial:
// Nothing to do here. No demand was signalled until now
return .none
case .zipping:
// An iterator was deinitialized while we have a suspended continuation.
preconditionFailure("Internal inconsistency current state \(self.state) and received iteratorDeinitialized()")
case .waitingForDemand(let task, let upstreams):
// The iterator was dropped which signals that the consumer is finished.
// We can transition to finished now and need to clean everything up.
self.state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .finished:
// We are already finished so there is nothing left to clean up.
// This is just the references dropping afterwards.
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
mutating func taskIsStarted(
task: Task<Void, Never>,
downstreamContinuation: DownstreamContinuation
) {
switch self.state {
case .initial:
// The user called `next` and we are starting the `Task`
// to consume the upstream sequences
self.state = .zipping(
task: task,
upstreams: (.init(), .init(), .init()),
downstreamContinuation: downstreamContinuation
)
case .zipping, .waitingForDemand, .finished:
// We only allow a single task to be created so this must never happen.
preconditionFailure("Internal inconsistency current state \(self.state) and received taskStarted()")
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `childTaskSuspended()`.
enum ChildTaskSuspendedAction {
/// Indicates that the continuation should be resumed which will lead to calling `next` on the upstream.
case resumeContinuation(
upstreamContinuation: UnsafeContinuation<Void, Error>
)
/// Indicates that the continuation should be resumed with an Error because another upstream sequence threw.
case resumeContinuationWithError(
upstreamContinuation: UnsafeContinuation<Void, Error>,
error: Error
)
}
mutating func childTaskSuspended(baseIndex: Int, continuation: UnsafeContinuation<Void, Error>) -> ChildTaskSuspendedAction? {
switch self.state {
case .initial:
// Child tasks are only created after we transitioned to `zipping`
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended()")
case .waitingForDemand(let task, var upstreams):
self.state = .modifying
switch baseIndex {
case 0:
upstreams.0.continuation = continuation
case 1:
upstreams.1.continuation = continuation
case 2:
upstreams.2.continuation = continuation
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
}
self.state = .waitingForDemand(
task: task,
upstreams: upstreams
)
return .none
case .zipping(let task, var upstreams, let downstreamContinuation):
// We are currently zipping. If we have a buffered element from the base
// already then we store the continuation otherwise we just go ahead and resume it
switch baseIndex {
case 0:
if upstreams.0.element == nil {
return .resumeContinuation(upstreamContinuation: continuation)
} else {
self.state = .modifying
upstreams.0.continuation = continuation
self.state = .zipping(
task: task,
upstreams: upstreams,
downstreamContinuation: downstreamContinuation
)
return .none
}
case 1:
if upstreams.1.element == nil {
return .resumeContinuation(upstreamContinuation: continuation)
} else {
self.state = .modifying
upstreams.1.continuation = continuation
self.state = .zipping(
task: task,
upstreams: upstreams,
downstreamContinuation: downstreamContinuation
)
return .none
}
case 2:
if upstreams.2.element == nil {
return .resumeContinuation(upstreamContinuation: continuation)
} else {
self.state = .modifying
upstreams.2.continuation = continuation
self.state = .zipping(
task: task,
upstreams: upstreams,
downstreamContinuation: downstreamContinuation
)
return .none
}
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received childTaskSuspended() with base index \(baseIndex)")
}
case .finished:
// Since cancellation is cooperative it might be that child tasks are still getting
// suspended even though we already cancelled them. We must tolerate this and just resume
// the continuation with an error.
return .resumeContinuationWithError(
upstreamContinuation: continuation,
error: CancellationError()
)
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `elementProduced()`.
enum ElementProducedAction {
/// Indicates that the downstream continuation should be resumed with the element.
case resumeContinuation(
downstreamContinuation: DownstreamContinuation,
result: Result<(Base1.Element, Base2.Element, Base3.Element?)?, Error>
)
}
mutating func elementProduced(_ result: (Base1.Element?, Base2.Element?, Base3.Element?)) -> ElementProducedAction? {
switch self.state {
case .initial:
// Child tasks that are producing elements are only created after we transitioned to `zipping`
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case .waitingForDemand:
// We are only issuing demand when we get signalled by the downstream.
// We should never receive an element when we are waiting for demand.
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
case .zipping(let task, var upstreams, let downstreamContinuation):
self.state = .modifying
switch result {
case (.some(let first), .none, .none):
precondition(upstreams.0.element == nil)
upstreams.0.element = first
case (.none, .some(let second), .none):
precondition(upstreams.1.element == nil)
upstreams.1.element = second
case (.none, .none, .some(let third)):
precondition(upstreams.2.element == nil)
upstreams.2.element = third
default:
preconditionFailure("Internal inconsistency current state \(self.state) and received elementProduced()")
}
// Implementing this for the two arities without variadic generics is a bit awkward sadly.
if let first = upstreams.0.element,
let second = upstreams.1.element,
let third = upstreams.2.element {
// We got an element from each upstream so we can resume the downstream now
self.state = .waitingForDemand(
task: task,
upstreams: (
.init(continuation: upstreams.0.continuation),
.init(continuation: upstreams.1.continuation),
.init(continuation: upstreams.2.continuation)
)
)
return .resumeContinuation(
downstreamContinuation: downstreamContinuation,
result: .success((first, second, third))
)
} else if let first = upstreams.0.element,
let second = upstreams.1.element,
self.numberOfUpstreamSequences == 2 {
// We got an element from each upstream so we can resume the downstream now
self.state = .waitingForDemand(
task: task,
upstreams: (
.init(continuation: upstreams.0.continuation),
.init(continuation: upstreams.1.continuation),
.init(continuation: upstreams.2.continuation)
)
)
return .resumeContinuation(
downstreamContinuation: downstreamContinuation,
result: .success((first, second, nil))
)
} else {
// We are still waiting for one of the upstreams to produce an element
self.state = .zipping(
task: task,
upstreams: (
.init(continuation: upstreams.0.continuation, element: upstreams.0.element),
.init(continuation: upstreams.1.continuation, element: upstreams.1.element),
.init(continuation: upstreams.2.continuation, element: upstreams.2.element)
),
downstreamContinuation: downstreamContinuation
)
return .none
}
case .finished:
// Since cancellation is cooperative it might be that child tasks
// are still producing elements after we finished.
// We are just going to drop them since there is nothing we can do
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamFinished()`.
enum UpstreamFinishedAction {
/// Indicates that the downstream continuation should be resumed with `nil` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func upstreamFinished() -> UpstreamFinishedAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .waitingForDemand:
// This can't happen. We are only issuing demand for a single element each time.
// There must never be outstanding demand to an upstream while we have no demand ourselves.
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamFinished()")
case .zipping(let task, let upstreams, let downstreamContinuation):
// One of our upstreams finished. We need to transition to finished ourselves now
// and resume the downstream continuation with nil. Furthermore, we need to cancel all of
// the upstream work.
self.state = .finished
return .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `upstreamThrew()`.
enum UpstreamThrewAction {
/// Indicates that the downstream continuation should be resumed with the `error` and
/// the task and the upstream continuations should be cancelled.
case resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
error: Error,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func upstreamThrew(_ error: Error) -> UpstreamThrewAction? {
switch self.state {
case .initial:
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .waitingForDemand:
// This can't happen. We are only issuing demand for a single element each time.
// There must never be outstanding demand to an upstream while we have no demand ourselves.
preconditionFailure("Internal inconsistency current state \(self.state) and received upstreamThrew()")
case .zipping(let task, let upstreams, let downstreamContinuation):
// One of our upstreams threw. We need to transition to finished ourselves now
// and resume the downstream continuation with the error. Furthermore, we need to cancel all of
// the upstream work.
self.state = .finished
return .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
error: error,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .finished:
// This is just everything finishing up, nothing to do here
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `cancelled()`.
enum CancelledAction {
/// Indicates that the downstream continuation needs to be resumed and
/// task and the upstream continuations should be cancelled.
case resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: DownstreamContinuation,
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the task and the upstream continuations should be cancelled.
case cancelTaskAndUpstreamContinuations(
task: Task<Void, Never>,
upstreamContinuations: [UnsafeContinuation<Void, Error>]
)
}
mutating func cancelled() -> CancelledAction? {
switch self.state {
case .initial:
state = .finished
return .none
case .waitingForDemand(let task, let upstreams):
// The downstream task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
self.state = .finished
return .cancelTaskAndUpstreamContinuations(
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .zipping(let task, let upstreams, let downstreamContinuation):
// The downstream Task got cancelled so we need to cancel our upstream Task
// and resume all continuations. We can also transition to finished.
self.state = .finished
return .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
downstreamContinuation: downstreamContinuation,
task: task,
upstreamContinuations: [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
)
case .finished:
// We are already finished so nothing to do here:
self.state = .finished
return .none
case .modifying:
preconditionFailure("Invalid state")
}
}
/// Actions returned by `next()`.
enum NextAction {
/// Indicates that a new `Task` should be created that consumes the sequence.
case startTask(Base1, Base2, Base3?)
case resumeUpstreamContinuations(
upstreamContinuation: [UnsafeContinuation<Void, Error>]
)
/// Indicates that the downstream continuation should be resumed with `nil`.
case resumeDownstreamContinuationWithNil(DownstreamContinuation)
}
mutating func next(for continuation: DownstreamContinuation) -> NextAction {
switch self.state {
case .initial(let base1, let base2, let base3):
// This is the first time we get demand singalled so we have to start the task
// The transition to the next state is done in the taskStarted method
return .startTask(base1, base2, base3)
case .zipping:
// We already got demand signalled and have suspended the downstream task
// Getting a second next calls means the iterator was transferred across Tasks which is not allowed
preconditionFailure("Internal inconsistency current state \(self.state) and received next()")
case .waitingForDemand(let task, var upstreams):
// We got demand signalled now and can transition to zipping.
// We also need to resume all upstream continuations now
self.state = .modifying
let upstreamContinuations = [upstreams.0.continuation, upstreams.1.continuation, upstreams.2.continuation].compactMap { $0 }
upstreams.0.continuation = nil
upstreams.1.continuation = nil
upstreams.2.continuation = nil
self.state = .zipping(
task: task,
upstreams: upstreams,
downstreamContinuation: continuation
)
return .resumeUpstreamContinuations(
upstreamContinuation: upstreamContinuations
)
case .finished:
// We are already finished so we are just returning `nil`
return .resumeDownstreamContinuationWithNil(continuation)
case .modifying:
preconditionFailure("Invalid state")
}
}
}
@@ -0,0 +1,320 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
final class ZipStorage<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where Base1: Sendable, Base1.Element: Sendable, Base2: Sendable, Base2.Element: Sendable, Base3: Sendable, Base3.Element: Sendable {
typealias StateMachine = ZipStateMachine<Base1, Base2, Base3>
private let stateMachine: ManagedCriticalState<StateMachine>
init(_ base1: Base1, _ base2: Base2, _ base3: Base3?) {
self.stateMachine = .init(.init(base1: base1, base2: base2, base3: base3))
}
func iteratorDeinitialized() {
let action = self.stateMachine.withCriticalRegion { $0.iteratorDeinitialized() }
switch action {
case .cancelTaskAndUpstreamContinuations(
let task,
let upstreamContinuation
):
upstreamContinuation.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
func next() async rethrows -> (Base1.Element, Base2.Element, Base3.Element?)? {
try await withTaskCancellationHandler {
let result = await withUnsafeContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.next(for: continuation)
switch action {
case .startTask(let base1, let base2, let base3):
// first iteration, we start one child task per base to iterate over them
self.startTask(
stateMachine: &stateMachine,
base1: base1,
base2: base2,
base3: base3,
downStreamContinuation: continuation
)
case .resumeUpstreamContinuations(let upstreamContinuations):
// bases can be iterated over for 1 iteration so their next value can be retrieved
upstreamContinuations.forEach { $0.resume() }
case .resumeDownstreamContinuationWithNil(let continuation):
// the async sequence is already finished, immediately resuming
continuation.resume(returning: .success(nil))
}
}
}
return try result._rethrowGet()
} onCancel: {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.cancelled()
switch action {
case .resumeDownstreamContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .cancelTaskAndUpstreamContinuations(let task, let upstreamContinuations):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
case .none:
break
}
}
}
}
private func startTask(
stateMachine: inout StateMachine,
base1: Base1,
base2: Base2,
base3: Base3?,
downStreamContinuation: StateMachine.DownstreamContinuation
) {
// This creates a new `Task` that is iterating the upstream
// sequences. We must store it to cancel it at the right times.
let task = Task {
await withThrowingTaskGroup(of: Void.self) { group in
// For each upstream sequence we are adding a child task that
// is consuming the upstream sequence
group.addTask {
var base1Iterator = base1.makeAsyncIterator()
while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 0, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element1 = try await base1Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((element1, nil, nil))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.upstreamFinished()
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .none:
break
}
}
}
}
}
group.addTask {
var base2Iterator = base2.makeAsyncIterator()
while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 1, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element2 = try await base2Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((nil, element2, nil))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.upstreamFinished()
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .none:
break
}
}
}
}
}
if let base3 = base3 {
group.addTask {
var base3Iterator = base3.makeAsyncIterator()
while true {
// We are creating a continuation before requesting the next
// element from upstream. This continuation is only resumed
// if the downstream consumer called `next` to signal his demand.
try await withUnsafeThrowingContinuation { continuation in
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.childTaskSuspended(baseIndex: 2, continuation: continuation)
switch action {
case .resumeContinuation(let upstreamContinuation):
upstreamContinuation.resume()
case .resumeContinuationWithError(let upstreamContinuation, let error):
upstreamContinuation.resume(throwing: error)
case .none:
break
}
}
}
if let element3 = try await base3Iterator.next() {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.elementProduced((nil, nil, element3))
switch action {
case .resumeContinuation(let downstreamContinuation, let result):
downstreamContinuation.resume(returning: result)
case .none:
break
}
}
} else {
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.upstreamFinished()
switch action {
case .resumeContinuationWithNilAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .success(nil))
case .none:
break
}
}
}
}
}
}
do {
try await group.waitForAll()
} catch {
// One of the upstream sequences threw an error
self.stateMachine.withCriticalRegion { stateMachine in
let action = stateMachine.upstreamThrew(error)
switch action {
case .resumeContinuationWithErrorAndCancelTaskAndUpstreamContinuations(
let downstreamContinuation,
let error,
let task,
let upstreamContinuations
):
upstreamContinuations.forEach { $0.resume(throwing: CancellationError()) }
task.cancel()
downstreamContinuation.resume(returning: .failure(error))
case .none:
break
}
}
group.cancelAll()
}
}
}
stateMachine.taskIsStarted(task: task, downstreamContinuation: downStreamContinuation)
}
}
@@ -14,10 +14,10 @@ import AsyncAlgorithms
import AsyncSequenceValidation
extension XCTestCase {
func recordFailure(_ description: String, detail: String? = nil, system: Bool = false, at location: AsyncSequenceValidation.SourceLocation) {
func recordFailure(_ description: String, system: Bool = false, at location: AsyncSequenceValidation.SourceLocation) {
#if canImport(Darwin)
let context = XCTSourceCodeContext(location: XCTSourceCodeLocation(filePath: location.file.description, lineNumber: Int(location.line)))
let issue = XCTIssue(type: system ? .system : .assertionFailure, compactDescription: description, detailedDescription: detail, sourceCodeContext: context, associatedError: nil, attachments: [])
let issue = XCTIssue(type: system ? .system : .assertionFailure, compactDescription: description, detailedDescription: nil, sourceCodeContext: context, associatedError: nil, attachments: [])
record(issue)
#else
XCTFail(description, file: location.file, line: location.line)
@@ -26,25 +26,17 @@ extension XCTestCase {
func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, expectedFailures: Set<String>, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
var expectations = expectedFailures
var result: AsyncSequenceValidationDiagram.ExpectationResult?
var failures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
let baseLoc = AsyncSequenceValidation.SourceLocation(file: file, line: line)
var accountedFailures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
do {
let (result, failures) = try AsyncSequenceValidationDiagram.test(theme: theme, build)
var detail: String?
if failures.count > 0 {
detail = """
Expected
\(result.reconstituteExpected(theme: theme))
Actual
\(result.reconstituteActual(theme: theme))
"""
print("Expected")
print(result.reconstituteExpected(theme: theme))
print("Actual")
print(result.reconstituteActual(theme: theme))
}
(result, failures) = try AsyncSequenceValidationDiagram.test(theme: theme, build)
for failure in failures {
if expectations.remove(failure.description) == nil {
recordFailure(failure.description, detail: detail, at: failure.specification?.location ?? baseLoc)
recordFailure(failure.description, at: failure.specification?.location ?? baseLoc)
} else {
accountedFailures.append(failure)
}
}
} catch {
@@ -52,6 +44,18 @@ extension XCTestCase {
recordFailure("\(error)", system: true, at: (error as? SourceFailure)?.location ?? baseLoc)
}
}
// If no failures were expected and the result reconstitues to something different
// than what was expected, dump that out as a failure for easier diagnostics, this
// likely should be done via attachments but that does not display inline code
// nicely. Ideally we would want to have this display as a runtime warning but those
// do not have source line attribution; for now XCTFail is good enough.
if let result = result, expectedFailures.count == 0 {
let expected = result.reconstituteExpected(theme: theme)
let actual = result.reconstituteActual(theme: theme)
if expected != actual {
XCTFail("Validation failure:\nExpected:\n\(expected)\nActual:\n\(actual)", file: file, line: line)
}
}
// any remaining expectations are failures that were expected but did not happen
for expectation in expectations {
XCTFail("Expected failure: \(expectation) did not occur.", file: file, line: line)
@@ -0,0 +1,14 @@
# ``AsyncSequenceValidation``
## Overview
Testing is a critical area of focus for any package to make it robust, catch bugs, and explain the expected behaviors in a documented manner. Testing things that are asynchronous can be difficult, testing things that are asynchronous multiple times can be even more difficult.
Types that implement `AsyncSequence` can often be described in deterministic actions given particular inputs. For the inputs, the events can be described as a discrete set: values, errors being thrown, the terminal state of returning a `nil` value from the iterator, or advancing in time and not doing anything. Likewise, the expected output has a discrete set of events: values, errors being caught, the terminal state of receiving a `nil` value from the iterator, or advancing in time and not doing anything.
## Topics
### Getting Started
- <doc:Validation>
@@ -41,7 +41,7 @@ The syntax is trivially parsable (and consequently customizable). By default, th
| Symbol | Description | Example |
| ------- | ----------------- | ---------- |
| `-` | Advance time | `"a--b--"` |
| `|` | Termination | `"ab-|"` |
| `\|` | Termination | `"ab-\|"` |
| `^` | Thrown error | `"ab-^"` |
| `;` | Cancellation | `"ab;-"` |
| `[` | Begin group | `"[ab]-"` |
@@ -218,15 +218,15 @@ Access to the validation diagram input list is done through calls such as `$0.in
| Symbol | Token | Description | Example |
| ------- | ------------------------- | ----------------- | ---------- |
| `-` | `.step` | Advance time | `"a--b--"` |
| `|` | `.finish` | Termination | `"ab-|"` |
| `\|` | `.finish` | Termination | `"ab-\|"` |
| `^` | `.error` | Thrown error | `"ab-^"` |
| `;` | `.cancel` | Cancellation | `"ab;-"` |
| `[` | `.beginGroup` | Begin group | `"[ab]-"` |
| `]` | `.endGroup` | End group | `"[ab]-"` |
| `'` | `.beginValue` `.endValue` | Begin/End Value | `"'foo'-"` |
| `,` | `.delayNext` | Delay next | `",[a,]b"` |
| ` ` | `.skip` | Skip/Ignore | `"a b- |"` |
| | `.value` | Values. | `"ab-|"` |
| ` ` | `.skip` | Skip/Ignore | `"a b- \|"` |
| | `.value` | Values. | `"ab-\|"` |
There are some diagram input specifications that are not valid. The three cases are:
@@ -11,7 +11,6 @@
import _CAsyncSequenceValidationSupport
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
@resultBuilder
public struct AsyncSequenceValidationDiagram : Sendable {
public struct Component<T> {
@@ -97,15 +96,20 @@ public struct AsyncSequenceValidationDiagram : Sendable {
}
let queue: WorkQueue
let _clock: Clock
public var inputs: InputList
public let clock: Clock
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public var clock: Clock {
_clock
}
internal init() {
let queue = WorkQueue()
self.queue = queue
self.inputs = InputList(queue: queue)
self.clock = Clock(queue: queue)
self._clock = Clock(queue: queue)
}
}
+27 -6
View File
@@ -11,7 +11,6 @@
import AsyncAlgorithms
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
extension AsyncSequenceValidationDiagram {
public struct Clock {
let queue: WorkQueue
@@ -22,8 +21,20 @@ extension AsyncSequenceValidationDiagram {
}
}
@available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *)
extension AsyncSequenceValidationDiagram.Clock: Clock {
public protocol TestClock: Sendable {
associatedtype Instant: TestInstant
var now: Instant { get }
func sleep(until deadline: Self.Instant, tolerance: Self.Instant.Duration?) async throws
}
public protocol TestInstant: Equatable {
associatedtype Duration
}
extension AsyncSequenceValidationDiagram.Clock {
public struct Step: DurationProtocol, Hashable, CustomStringConvertible {
internal var rawValue: Int
@@ -66,7 +77,7 @@ extension AsyncSequenceValidationDiagram.Clock: Clock {
}
}
public struct Instant: InstantProtocol, CustomStringConvertible {
public struct Instant: CustomStringConvertible {
public typealias Duration = Step
let when: Step
@@ -103,11 +114,21 @@ extension AsyncSequenceValidationDiagram.Clock: Clock {
) async throws {
let token = queue.prepare()
try await withTaskCancellationHandler {
queue.cancel(token)
} operation: {
try await withUnsafeThrowingContinuation { continuation in
queue.enqueue(AsyncSequenceValidationDiagram.Context.currentJob, deadline: deadline, continuation: continuation, token: token)
}
} onCancel: {
queue.cancel(token)
}
}
}
extension AsyncSequenceValidationDiagram.Clock.Instant: TestInstant { }
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram.Clock.Instant: InstantProtocol { }
extension AsyncSequenceValidationDiagram.Clock: TestClock { }
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram.Clock: Clock { }
Loaded 100 of 147 files, more files were not shown because too many files have changed in this diff. Show more