Compare commits

..
1 Commits
Author SHA1 Message Date
Philippe Hausler 68f59669ea Initializing gh-pages branch 2022-04-11 12:51:25 -07:00
122 changed files with 0 additions and 15025 deletions

No files matched your search

-11
View File
@@ -1,11 +0,0 @@
.DS_Store
/.build
/Packages
/*.xcodeproj
xcuserdata/
DerivedData/
.swiftpm/config/registries.json
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
.netrc
.swiftpm
Package.resolved
-5
View File
@@ -1,5 +0,0 @@
# Code of Conduct
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
-10
View File
@@ -1,10 +0,0 @@
By submitting a pull request, you represent that you have the right to license
your contribution to Apple and the community, and agree by submitting the patch
that your contributions are licensed under the [Swift
license](https://swift.org/LICENSE.txt).
---
Before submitting the pull request, please make sure you have tested your
changes and that they follow the Swift project [guidelines for contributing
code](https://swift.org/contributing/#contributing-code).
@@ -1,67 +0,0 @@
# Feature name
* Proposal: [NNNN](NNNN-filename.md)
* Authors: [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
* Review Manager: TBD
* Status: **Awaiting implementation**
*During the review process, add the following fields as needed:*
* Implementation: [apple/swift-async-algorithms#NNNNN](https://github.com/apple/swift-async-algorithms/pull/NNNNN)
* Decision Notes: [Rationale](https://forums.swift.org/), [Additional Commentary](https://forums.swift.org/)
* Bugs: [NNNN](https://github.com/apple/swift-async-algorithms/issues)
## Introduction
A short description of what the feature is. Try to keep it to a
single-paragraph "elevator pitch" so the reader understands what
problem this proposal is addressing.
Swift forums thread: [Discussion thread topic for that proposal](https://forums.swift.org/)
## Motivation
Describe the problems that this proposal seeks to address. If the
problem is that some common pattern is currently hard to express, show
how one can currently get a similar effect and describe its
drawbacks. If it's completely new functionality that cannot be
emulated, motivate why this new functionality would help Swift
developers create better Swift code.
## Proposed solution
Describe your solution to the problem. Provide examples and describe
how they work. Show how your solution is better than current
workarounds: is it cleaner, safer, or more efficient?
## Detailed design
Describe the design of the solution in detail. If it involves new
syntax in the language, show the additions and changes to the Swift
grammar. If it's a new API, show the full API and its documentation
comments detailing what it does. The detail in this section should be
sufficient for someone who is *not* one of the authors to be able to
reasonably implement the feature.
## Effect on API resilience
API resilience describes the changes one can make to a public API
without breaking its ABI. Does this proposal introduce features that
would become part of a public API? If so, what kinds of changes can be
made without breaking ABI? Can this feature be added/removed without
breaking ABI? For more information about the resilience model, see the
[library evolution
document](https://github.com/apple/swift/blob/master/docs/LibraryEvolution.rst)
in the Swift repository.
## Alternatives considered
Describe alternative approaches to addressing the same problem, and
why you chose this approach instead.
## Acknowledgments
If significant changes or improvements suggested by members of the
community were incorporated into the proposal as it developed, take a
moment here to thank them for their contributions. Swift evolution is a
collaborative process, and everyone's input should receive recognition!
-110
View File
@@ -1,110 +0,0 @@
# 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.
-211
View File
@@ -1,211 +0,0 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
## Runtime Library Exception to the Apache 2.0 License: ##
As an exception, if you use this Software to compile your source code and
portions of this Software are embedded into the binary product as a result,
you may redistribute such product without providing attribution as would
otherwise be required by Sections 4(a), 4(b) and 4(d) of the License.
-58
View File
@@ -1,58 +0,0 @@
// swift-tools-version: 5.6
import PackageDescription
let package = Package(
name: "AsyncAlgorithms",
platforms: [
.macOS("10.15"),
.iOS("13.0"),
.tvOS("13.0"),
.watchOS("6.0")
],
products: [
.library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]),
.library(name: "AsyncSequenceValidation", targets: ["AsyncSequenceValidation"]),
.library(name: "_CAsyncSequenceValidationSupport", type: .static, targets: ["AsyncSequenceValidation"]),
.library(name: "AsyncAlgorithms_XCTest", targets: ["AsyncAlgorithms_XCTest"]),
],
dependencies: [],
targets: [
.target(name: "AsyncAlgorithms"),
.target(
name: "AsyncSequenceValidation",
dependencies: ["_CAsyncSequenceValidationSupport", "AsyncAlgorithms"]),
.systemLibrary(name: "_CAsyncSequenceValidationSupport"),
.target(
name: "AsyncAlgorithms_XCTest",
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation"],
swiftSettings: [
.unsafeFlags([
"-Xfrontend", "-disable-availability-checking"
])
]),
.testTarget(
name: "AsyncAlgorithmsTests",
dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"],
swiftSettings: [
.unsafeFlags([
"-Xfrontend", "-disable-availability-checking"
])
]),
]
)
#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"),
] : []
-121
View File
@@ -1,121 +0,0 @@
# swift-async-algorithms
**Swift Async Algorithms** is an open-source package of asynchronous sequence and advanced algorithms that involve concurrency, along with their related types.
This package has three main goals:
- First-class integration with `async/await`
- Provide a home for time-based algorithms
- Be cross-platform and open source
## Motivation
AsyncAlgorithms is a package for algorithms that work with *values over time*. That includes those primarily about *time*, like `debounce` and `throttle`, but also algorithms about *order* like `combineLatest` and `merge`. Operations that work with multiple inputs (like `zip` does on `Sequence`) can be surprisingly complex to implement, with subtle behaviors and many edge cases to consider. A shared package can get these details correct, with extensive testing and documentation, for the benefit of all Swift apps.
The foundation for AsyncAlgorithms was included in Swift 5.5 from [AsyncSequence](https://github.com/apple/swift-evolution/blob/main/proposals/0298-asyncsequence.md). Swift 5.5 also brings the ability to use a natural `for/in` loop with `await` to process the values in an `AsyncSequence` and `Sequence`-equivalent API like `map` and `filter`. Structured concurrency allows us to write code where intermediate state is simply a local variable, `try` can be used directly on functions that `throw`, and generally treat the logic for asynchronous code similar to that of synchronous code.
This package is the home for these APIs. Development and API design take place on [GitHub](https://github.com/apple/swift-async-algorithms) and the [Swift Forums](https://forums.swift.org/c/related-projects/swift-async-algorithms).
## Contents
#### Combining asynchronous sequences
- [`chain(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Chain.md): Concatenates two or more asynchronous sequences with the same element type.
- [`combineLatest(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/CombineLatest.md): Combines two or more asynchronous sequences into an asynchronous sequence producing a tuple of elements from those base asynchronous sequences that updates when any of the base sequences produce a value.
- [`merge(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Merge.md): Merges two or more asynchronous sequence into a single asynchronous sequence producing the elements of all of the underlying asynchronous sequences.
- [`zip(_:...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Zip.md): Creates an asynchronous sequence of pairs built out of underlying asynchronous sequences.
- [`joined(separator:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Joined.md): Concatenated elements of an asynchronous sequence of asynchronous sequences, inserting the given separator between each element.
#### Creating asynchronous sequences
- [`async`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Lazy.md): Create an asynchronous sequence composed from a synchronous sequence.
- [`AsyncChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics.
- [`AsyncThrowingChannel`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Channel.md): An asynchronous sequence with back pressure sending semantics that can emit failures.
#### Performance optimized asynchronous iterators
- [`AsyncBufferedByteIterator`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/BufferedBytes.md): A highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
#### Other useful asynchronous sequences
- [`adjacentPairs()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/AdjacentPairs.md): Collects tuples of adjacent elements.
- [`chunks(...)` and `chunked(...)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Chunked.md): Collect values into chunks.
- [`compacted()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Compacted.md): Remove nil values from an asynchronous sequence.
- [`removeDuplicates()`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/RemoveDuplicates.md): Remove sequentially adjacent duplicate values.
- [`interspersed(with:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Intersperse.md): Place a value between every two elements of an asynchronous sequence.
#### Asynchronous Sequences that transact in time
- [`debounce(for:tolerance:clock:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Debounce.md): Emit values after a quiescence period has been reached.
- [`throttle(for:clock:reducing:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Throttle.md): Ensure a minimum interval has elapsed between events.
- [`AsyncTimerSequence`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Timer.md): Emit the value of now at a given interval repeatedly.
#### Obtaining all values from an asynchronous sequence
- [`RangeReplaceableCollection.init(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new instance of a collection containing the elements of an asynchronous sequence.
- [`Dictionary.init(uniqueKeysWithValues:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary from the key-value pairs in the given asynchronous sequence.
- [`Dictionary.init(_:uniquingKeysWith:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary from the key-value pairs in the given asynchronous sequence, using a combining closure to determine the value for any duplicate keys.
- [`Dictionary.init(grouping:by:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new dictionary whose keys are the groupings returned by the given closure and whose values are arrays of the elements that returned each key.
- [`SetAlgebra.init(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Collections.md): Creates a new set from an asynchronous sequence of items.
#### Task management
- [`Task.select(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Select.md): Determine the first task to complete of a sequence of tasks.
#### Effects
Each algorithm has specific behavioral effects. For throwing effects these can either be if the sequence throws, does not throw, or rethrows errors. Sendability effects in some asynchronous sequences are conditional whereas others require the composed parts to all be sendable to satisfy a requirement of `Sendable`. The effects are [listed here](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Effects.md).
## Adding Swift Async Algorithms as a Dependency
To use the `AsyncAlgorithms` library in a SwiftPM project,
add the following line to the dependencies in your `Package.swift` file:
```swift
.package(url: "https://github.com/apple/swift-async-algorithms"),
```
Include `"AsyncAlgorithms"` as a dependency for your executable target:
```swift
.target(name: "<target>", dependencies: [
.product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
]),
```
Finally, add `import AsyncAlgorithms` to your source code.
## Getting Started
⚠️ Please note that this package currently requires a recent [Swift Trunk Development toolchain](https://www.swift.org/download/#trunk-development-main). More information on how to use custom toolchains with Xcode can be viewed [here](https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/AlternativeToolchains.html).
### Building/Testing Using Xcode on macOS
1. Download the most recent development Xcode toolchain.
2. Install the package
4. Select the development toolchain in Xcode
4. Open the `swift-async-algorithms` package directory in Xcode
5. Build or Test in Xcode as normal
⚠️ Note: `swift test` does not currently work properly with custom toolchains for this package.
### Building/Testing on Linux
1. Download the most recent development toolchain for your Linux distribution
2. Decompress the archive to a path in which the `swift` executable is in the binary search path environment variable (`$PATH`)
3. In the `swift-async-algorithms` directory run `swift build` or `swift test` accordingly
### Building with Swift 5.6
1. `git checkout swift-5.6`
2. run `swift build` or `swift test` accordingly
## Source Stability
The Swift Async Algorithms package has a goal of being source stable as soon as possible; version numbers will follow [Semantic Versioning](https://semver.org/). Source breaking changes to public API can only land in a new major version.
The public API of version 1.0 of the `swift-async-algorithms` package will consist of non-underscored declarations that are marked `public` in the `AsyncAlgorithms` module. Interfaces that aren't part of the public API may continue to change in any release, including patch releases.
Future minor versions of the package may introduce changes to these rules as needed.
We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump.
@@ -1,87 +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 `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, Base.AsyncIterator: Sendable { }
extension AsyncAdjacentPairsSequence.Iterator: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
@@ -1,36 +0,0 @@
# ``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:Select>
- <doc:Throttle>
- <doc:Timer>
- <doc:Zip>
@@ -1,49 +0,0 @@
# 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).
@@ -1,54 +0,0 @@
# AsyncBufferedByteIterator
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncBufferedByteIterator.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestBufferedByteIterator.swift)]
Provides a highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.
This type provides infrastructure for creating `AsyncSequence` types with an `Element` of `UInt8` backed by file descriptors or similar read sources.
```swift
struct AsyncBytes: AsyncSequence {
public typealias Element = UInt8
var handle: ReadableThing
internal init(_ readable: ReadableThing) {
handle = readable
}
public func makeAsyncIterator() -> AsyncBufferedByteIterator {
return AsyncBufferedByteIterator(capacity: 16384) { buffer in
// This runs once every 16384 invocations of next()
return try await handle.read(into: buffer)
}
}
}
```
## Detailed Design
```swift
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
public typealias Element = UInt8
public init(
capacity: Int,
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
)
public mutating func next() async throws -> UInt8?
}
```
For each invocation of `next`, the iterator will check if a buffer has been filled. If the buffer is filled with some amount of bytes, a fast path is taken to directly return a byte out of that buffer. If the buffer is not filled, the read function is invoked to acquire the next filled buffer, at which point it takes a byte out of that buffer.
If the read function returns `0`, indicating it didn't read any more bytes, the iterator is decided to be finished and no additional invocations to the read function are made.
If the read function throws, the error will be thrown by the iteration. Subsequent invocations to the iterator will then return `nil` without invoking the read function.
If the task is cancelled during the iteration, the iteration will check the cancellation only in passes where the read function is invoked, and will throw a `CancellationError`.
### Naming
This type was named precisely for what it does: it is an asynchronous iterator that buffers bytes.
@@ -1,73 +0,0 @@
# Chain
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChain3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChain.swift)]
Chains two or more asynchronous sequences together sequentially where the elements from the resulting asynchronous sequence are comprised in order from the elements of the first asynchronous sequence and then the second (and so on) or until an error occurs.
This operation is available for all `AsyncSequence` types who share the same `Element` type.
```swift
let preamble = [
"// Some header to add as a preamble",
"//",
""
].async
let lines = chain(preamble, URL(fileURLWithPath: "/tmp/Sample.swift").lines)
for try await line in lines {
print(line)
}
```
The above example shows how two `AsyncSequence` types can be chained together. In this case it prepends a preamble to the `lines` content of the file.
## Detailed Design
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
```swift
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3>
public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> where Base1.Element == Base2.Element {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
```
The `chain(_:...)` function takes two or more sequences as arguments.
The resulting `AsyncChainSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments also conform to it.
When any of the asynchronous sequences being chained together come to their end of iteration, the `AsyncChainSequence` iteration proceeds to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration, the `AsyncChainSequence` then ends its iteration.
At any point in time, if one of the comprising asynchronous sequences throws an error during iteration, the resulting `AsyncChainSequence` iteration will throw that error and end iteration. The throwing behavior of `AsyncChainSequence` is that it will throw when any of its comprising bases throw, and will not throw when all of its comprising bases do not throw.
### Naming
This function's and type's name match the term of art used in other languages and libraries.
This combinator function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chain.md).
@@ -1,82 +0,0 @@
# Channel
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChannel.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrowingChannel.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChannel.swift)
]
## Introduction
`AsyncStream` introduced a mechanism to send buffered elements from a context that doesn't use Swift concurrency into one that does. That design only addressed a portion of the potential use cases; the missing portion was the back pressure excerpted across two concurrency domains.
## Proposed Solution
To achieve a system that supports back pressure and allows for the communication of more than one value from one task to another we are introducing a new type, the _channel_. The channel will be a reference-type asynchronous sequence with an asynchronous sending capability that awaits the consumption of iteration. Each value sent by the channel will await the consumption of that value by iteration. That awaiting behavior will allow for the affordance of back pressure applied from the consumption site to be transmitted to the production site. This means that the rate of production cannot exceed the rate of consumption, and that the rate of consumption cannot exceed the rate of production. Sending a terminal event to the channel will instantly resume all pending operations for every producers and consumers.
## Detailed Design
Similar to the `AsyncStream` and `AsyncThrowingStream` types, the type for sending elements via back pressure will come in two versions. These two versions will account for the throwing nature or non-throwing nature of the elements being produced.
Each type will have functions to send elements and to send terminal events.
```swift
public final class AsyncChannel<Element: Sendable>: AsyncSequence, Sendable {
public struct Iterator: AsyncIteratorProtocol, Sendable {
public mutating func next() async -> Element?
}
public init(element elementType: Element.Type = Element.self)
public func send(_ element: Element) async
public func finish()
public func makeAsyncIterator() -> Iterator
}
public final class AsyncThrowingChannel<Element: Sendable, Failure: Error>: AsyncSequence, Sendable {
public struct Iterator: AsyncIteratorProtocol, Sendable {
public mutating func next() async throws -> Element?
}
public init(element elementType: Element.Type = Element.self, failure failureType: Failure.Type = Failure.self)
public func send(_ element: Element) async
public func fail(_ error: Error) async where Failure == Error
public func finish()
public func makeAsyncIterator() -> Iterator
}
```
Channels are intended to be used as communication types between tasks. Particularly when one task produces values and another task consumes said values. On the one hand, the back pressure applied by `send(_:)` and `fail(_:)` 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. On the other hand, the call to `finish()` 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, indicating the termination of the iterations. Further calls to `send(_:)` will immediately resume.
```swift
let channel = AsyncChannel<String>()
Task {
while let resultOfLongCalculation = doLongCalculations() {
await channel.send(resultOfLongCalculation)
}
channel.finish()
}
for await calculationResult in channel {
print(calculationResult)
}
```
The example above uses a task to perform intense calculations; each of which are sent to the other task via the `send(_:)` method. That call to `send(_:)` returns when the next iteration of the channel is invoked.
## Alternatives Considered
The use of the name "subject" was considered, due to its heritage as a name for a sync-to-async adapter type.
It was considered to make `AsyncChannel` and `AsyncThrowingChannel` actors, however due to the cancellation internals it would imply that these types would need to create new tasks to handle cancel events. The advantages of an actor in this particular case did not outweigh the impact of adjusting the implementations to be actors.
## Credits/Inspiration
`AsyncChannel` and `AsyncThrowingChannel` was heavily inspired from `Subject` but with the key difference that it uses Swift concurrency to apply back pressure.
https://developer.apple.com/documentation/combine/subject/
@@ -1,314 +0,0 @@
# Chunked
* Author(s): [Kevin Perry](https://github.com/kperryua)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedByGroupSequence.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunkedOnProjectionSequence.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountAndSignalSequence.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncChunksOfCountSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestChunk.swift)
]
## Introduction
Grouping of values from an asynchronous sequence is often useful for tasks that involve writing those values efficiently or useful to handle specific structured data inputs.
## Proposed Solution
Chunking operations can be broken down into a few distinct categories: grouping according to a binary predicate used to determine whether consecutive elements belong to the same group, projecting an element's property to determine the element's chunk membership, by discrete count, by another signal asynchronous sequence which indicates when the chunk should be delimited, or by a combination of count and signal.
### Grouping
Group chunks are determined by passing two consecutive elements to a closure which tests whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator receives the first element from the base sequence, it will immediately be added to a group. When it receives the second item, it tests whether the previous item and the current item belong to the same group. If they are not in the same group, then the iterator emits the first item's group and a new group is created containing the second item. Items declared to be in the same group accumulate until a new group is declared, or the iterator finds the end of the base sequence. When the base sequence terminates, the final group is emitted. If the base sequence throws an error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard any current group.
```swift
extension AsyncSequence {
public func chunked<Collected: RangeReplaceableCollection>(
into: Collected.Type,
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
) -> AsyncChunkedByGroupSequence<Self, Collected>
where Collected.Element == Element
public func chunked(
by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool
) -> AsyncChunkedByGroupSequence<Self, [Element]>
}
```
Consider an example where an asynchronous sequence emits the following values: `10, 20, 30, 10, 40, 40, 10, 20`. Given the chunked operation to be defined as follows:
```swift
let chunks = numbers.chunked { $0 <= $1 }
for await numberChunk in chunks {
print(numberChunk)
}
```
That snippet will produce the following values:
```swift
[10, 20, 30]
[10, 40, 40]
[10, 20]
```
While `Array` is the default type for chunks, thanks to the overload that takes a `RangeReplaceableCollection` type, the same sample can be chunked into instances of `ContiguousArray`, or any other `RangeReplaceableCollection` instead.
```swift
let chunks = numbers.chunked(into: ContiguousArray.self) { $0 <= $1 }
for await numberChunk in chunks {
print(numberChunk)
}
```
That variant is the funnel method for the main implementation, which passes `[Element].self` in as the parameter.
### Projection
In some scenarios, chunks are determined not by comparing different elements, but by the element itself. This may be the case when the element has some sort of discriminator that can determine the chunk it belongs to. When two consecutive elements have different projections, the current chunk is emitted and a new chunk is created for the new element.
When the `AsyncChunkedOnProjectionSequence`'s iterator receives `nil` from the base sequence, it emits the final chunk. When the base sequence throws an error, the iterator discards the current chunk and rethrows that error.
Similarly to the `chunked(by:)` method this algorithm has an optional specification for the `RangeReplaceableCollection` which is used as the type of each chunk.
```swift
extension AsyncSequence {
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(
into: Collected.Type,
on projection: @escaping @Sendable (Element) -> Subject
) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected>
public func chunked<Subject : Equatable>(
on projection: @escaping @Sendable (Element) -> Subject
) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]>
}
```
The following example shows how a sequence of names can be chunked together by their first characters.
```swift
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
let groupedNames = names.chunked(on: \.first!)
for try await (firstLetter, names) in groupedNames {
print(firstLetter)
for name in names {
print(" ", name)
}
}
```
A special property of this kind of projection chunking is that when an asynchronous sequence's elements are known to be ordered, the output of the chunking asynchronous sequence is suitable for initializing dictionaries using the `AsyncSequence` initializer for `Dictionary`. This is because the projection can be easily designed to match the sorting characteristics and thereby guarantee that the output matches the pattern of an array of pairs of unique "keys" with the chunks as the "values".
In the example above, if the names are known to be ordered then you can take advantage of the uniqueness of each "first character" projection to initialize a `Dictionary` like so:
```swift
let names = URL(fileURLWithPath: "/tmp/names.txt").lines
let nameDirectory = try await Dictionary(uniqueKeysWithValues: names.chunked(on: \.first!))
```
### Count or Signal
Sometimes chunks are determined not by the elements themselves, but by external factors. This final category enables limiting chunks to a specific size and/or delimiting them by another asynchronous sequence which is referred to as a "signal". This particular chunking family is useful for scenarios where the elements are more efficiently processed as chunks than individual elements, regardless of their values.
This family is broken down into two sub-families of methods: ones that employ a signal plus an optional count (which return an `AsyncChunksOfCountOrSignalSequence`), and the ones that only deal with counts (which return an `AsyncChunksOfCountSequence`). Both sub-families have `Collected` as their element type, or `Array` if unspecified. These sub-families have rethrowing behaviors; if the base `AsyncSequence` can throw then the chunks sequence can also throw. Likewise if the base `AsyncSequence` cannot throw then the chunks sequence also cannot throw.
##### Count only
```swift
extension AsyncSequence {
public func chunks<Collected: RangeReplaceableCollection>(
ofCount count: Int,
into: Collected.Type
) -> AsyncChunksOfCountSequence<Self, Collected>
where Collected.Element == Element
public func chunks(
ofCount count: Int
) -> AsyncChunksOfCountSequence<Self, [Element]>
}
```
If a chunk size limit is specified via an `ofCount` parameter, the sequence will produce chunks of type `Collected` with at most the specified number of elements. When a chunk reaches the given size, the asynchronous sequence will emit it immediately.
For example, an asynchronous sequence of `UInt8` bytes can be chunked into at most 1024-byte `Data` instances like so:
```swift
let packets = bytes.chunks(ofCount: 1024, into: Data.self)
for try await packet in packets {
write(packet)
}
```
##### Signal only
```swift
extension AsyncSequence {
public func chunked<Signal, Collected: RangeReplaceableCollection>(
by signal: Signal,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
where Collected.Element == Element
public func chunked<Signal>(
by signal: Signal
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
by timer: AsyncTimerSequence<C>,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
where Collected.Element == Element
public func chunked<C: Clock>(
by timer: AsyncTimerSequence<C>
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
}
```
If a signal asynchronous sequence is specified, the chunking asynchronous sequence emits chunks whenever the signal emits. The signals element values are ignored. If the chunking asynchronous sequence hasn't accumulated any elements since its previous emission, then no value is emitted in response to the signal.
Since time is a frequent method of signaling desired delineations of chunks, there is a pre-specialized set of overloads that take `AsyncTimerSequence`. These allow shorthand initialization by using `AsyncTimerSequence`'s static member initializers.
As an example, an asynchronous sequence of log messages can be chunked into arrays of logs in four second segments like so:
```swift
let fourSecondsOfLogs = logs.chunked(by: .repeating(every: .seconds(4)))
for await chunk in fourSecondsOfLogs {
send(chunk)
}
```
##### Count or Signal
```swift
extension AsyncSequence {
public func chunks<Signal, Collected: RangeReplaceableCollection>(
ofCount count: Int,
or signal: Signal,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal>
where Collected.Element == Element
public func chunks<Signal>(
ofCount count: Int,
or signal: Signal
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal>
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(
by timer: AsyncTimerSequence<C>,
into: Collected.Type
) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>>
where Collected.Element == Element
public func chunked<C: Clock>(
by timer: AsyncTimerSequence<C>
) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>>
}
```
If both count and signal are specified, the chunking asynchronous sequence emits chunks whenever *either* the chunk reaches the specified size *or* the signal asynchronous sequence emits. When a signal causes a chunk to be emitted, the accumulated element count is reset back to zero. When an `AsyncTimerSequence` is used as a signal, the timer is started from the moment `next()` is called for the first time on `AsyncChunksOfCountOrSignalSequence`'s iterator, and it emits on a regular cadence from that moment. Note that the scheduling of the timer's emission is unaffected by any chunks emitted based on count.
Like the example above, this code emits up to 1024-byte `Data` instances, but a chunk will also be emitted every second.
```swift
let packets = bytes.chunks(ofCount: 1024 or: .repeating(every: .seconds(1)), into: Data.self)
for try await packet in packets {
write(packet)
}
```
In any configuration of any of the chunking families, when the base asynchronous sequence terminates, one of two things will happen: 1) a partial chunk will be emitted, or 2) no chunk will be emitted (i.e. the iterator received no elements since the emission of the previous chunk). No elements from the base asynchronous sequence are ever discarded, except in the case of a thrown error.
## Detailed Design
### Grouping
```swift
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
where Collected.Element == Base.Element {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunkedByGroupSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
extension AsyncChunkedByGroupSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
```
### Projection
```swift
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
public typealias Element = (Subject, Collected)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> (Subject, Collected)?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunkedOnProjectionSequence: Sendable
where Base: Sendable, Base.Element: Sendable { }
extension AsyncChunkedOnProjectionSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Subject: Sendable { }
```
### Count
```swift
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence
where Collected.Element == Base.Element {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
```
### Count or Signal
```swift
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable
where
Collected.Element == Base.Element,
Base: Sendable, Signal: Sendable,
Base.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable,
Base.Element: Sendable, Signal.Element: Sendable {
public typealias Element = Collected
public struct Iterator: AsyncIteratorProtocol, Sendable {
public mutating func next() async rethrows -> Collected?
}
public func makeAsyncIterator() -> Iterator
}
```
## Alternatives Considered
It was considered to make the chunked element to be an `AsyncSequence` instead of allowing collection into a `RangeReplaceableCollection` however it was determined that the throwing behavior of that would be complex to understand. If that hurdle could be overcome then that might be a future direction/consideration that would be worth exploring.
Variants of `chunked(by:)` (grouping) and `chunked(on:)` (projection) methods could be added that take delimiting `Signal` and `AsyncTimerSequence` inputs similar to `chunked(byCount:or:)`. However, it was decided that such functionality was likely to be underutilized and not worth the complication to the already broad surface area of `chunked` methods.
The naming of this family was considered to be `collect` which is used in APIs like `Combine`. This family of functions has distinct similarity to those APIs.
## Credits/Inspiration
This transformation function is a heavily inspired analog of the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Chunked.md)
@@ -1,104 +0,0 @@
# Collection Initializers
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Dictionary.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/RangeReplaceableCollection.swift),
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/SetAlgebra.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestDictionary.swift),
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestRangeReplaceableCollection.swift),
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestSetAlgebra.swift),
]
## Introduction
`Array`, `Dictionary` and `Set` are some of the most commonly-used data structures for storing collections of elements. Having a way to transition from an `AsyncSequence` to a collection is not only a useful shorthand but a powerful way of expressing direct intent for how to consume an `AsyncSequence`.
This type of functionality can be useful for examples and testing, and also for interfacing with existing APIs that expect a fully-formed collection before processing it.
## Proposed Solution
Three categories of initializers will be added to provide initializers for those three primary types: `Array`, `Dictionary` and `Set`. However these initializers can be written in a generic fashion such that they can apply to all similar collections.
`RangeReplaceableCollection` will gain a new initializer that constructs a collection given an `AsyncSequence`. This will allow for creating arrays from asynchronous sequences but also allow for creating types like `Data` or `ContiguousArray`. Because of the nature of asynchronous sequences, this initializer must be asynchronous and declare that it rethrows errors from the base asynchronous sequence.
```swift
extension RangeReplaceableCollection {
public init<Source: AsyncSequence>(
_ source: Source
) async rethrows
where Source.Element == Element
}
```
`Dictionary` will gain a family of new asynchronous, rethrowing initializers to parallel the existing `Sequence`-based initializers. The initializers will be asynchronous to facilitate uniquing keys and other tasks that may be asynchronous, in addition to the asynchronous initialization of the dictionaries.
```swift
extension Dictionary {
public init<S: AsyncSequence>(
uniqueKeysWithValues keysAndValues: S
) async rethrows
where S.Element == (Key, Value)
public init<S: AsyncSequence>(
_ keysAndValues: S,
uniquingKeysWith combine: (Value, Value) async throws -> Value
) async rethrows
where S.Element == (Key, Value)
public init<S: AsyncSequence>(
grouping values: S,
by keyForValue: (S.Element) async throws -> Key
) async rethrows
where Value == [S.Element]
}
```
`SetAlgebra` will gain a new asynchronous, rethrowing initializer that constructs a `SetAlgebra` type given an `AsyncSequence`. This will allow for creating sets from asynchronous sequences and allow for creating types like `OptionSet` types or `IndexSet`.
```swift
extension SetAlgebra {
public init<Source: AsyncSequence>(
_ source: Source
) async rethrows
where Source.Element == Element
}
```
## Detailed Design
Each of the initializers is intended for uses where the `AsyncSequence` being used for initialization is known to be finite. Common uses include:
* Reading from files via the `AsyncBytes` style sequences or `lines` accessors.
* Gathering elements produced by a `TaskGroup`.
* Accessing a prefix of an indefinite `AsyncSequence`.
Each of the initializers will use the `for`-`await`-`in`/`for`-`try`-`await`-`in` syntax to iterate the sequence directly in the initializer. In addition each initializer relies on the `AsyncSequence` being passed in to properly respect cancellation. In the cases where cancellation is a potential, developers should be ready to either check immediately or be ready for initialization based on a partial sequence, depending on the behavior of the `AsyncSequence` being used.
### RangeReplaceableCollection
```swift
let contents = try await Data(URL(fileURLWithPath: "/tmp/example.bin").resourceBytes)
```
### Dictionary
```swift
let table = await Dictionary(uniqueKeysWithValues: zip(keys, values))
```
### SetAlgebra
```swift
let allItems = await Set(items.prefix(10))
```
## Alternatives Considered
The spelling of these initializers could be expressed as a trailing conversion. However, that can lead to hard-to-read chains of operations. Functionally these all belong to the `reduce` family of functions, but due to source readability concerns they are more ergonomic for understanding what the code does by using the initializer patterns.
## Credits/Inspiration
The direct inspiration for each initialization is from their standard library counterparts.
@@ -1,83 +0,0 @@
# Combine Latest
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCombineLatest2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCombineLatest3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCombineLatest.swift)]
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
```swift
let appleFeed = URL("http://www.example.com/ticker?symbol=AAPL").lines
let nasdaqFeed = URL("http://www.example.com/ticker?symbol=^IXIC").lines
for try await (apple, nasdaq) in combineLatest(appleFeed, nasdaqFeed) {
print("AAPL: \(apple) NASDAQ: \(nasdaq)")
}
```
Given some sample inputs the following combined events can be expected.
| Timestamp | appleFeed | nasdaqFeed | combined output |
| ----------- | --------- | ---------- | ----------------------------- |
| 11:40 AM | 173.91 | | |
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
| 12:40 AM | | 14218.34 | AAPL: 173.91 NASDAQ: 14218.34 |
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
## Detailed Design
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
```swift
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncCombineLatest2Sequence<Base1, Base2>
public func combineLatest<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncCombineLatest3Sequence<Base1, Base2, Base3>
public struct AsyncCombineLatest2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable,
Base1.Element: Sendable, Base2.Element: Sendable,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncCombineLatest3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `combineLatest(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncCombineLatestSequence` which is an asynchronous sequence.
Since the bases comprising the `AsyncCombineLatestSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must all be `Sendable`.
If any of the bases terminate before the first element is produced, then the `AsyncCombineLatestSequence` iteration can never be satisfied. So, if a base's iterator returns `nil` at the first iteration, then the `AsyncCombineLatestSequence` iterator immediately returns `nil` to signify a terminal state. In this particular case, any outstanding iteration of other bases will be cancelled. After the first element is produced ,this behavior is different since the latest values can still be satisfied by at least one base. This means that beyond the construction of the first tuple comprised of the returned elements of the bases, the terminal state of the `AsyncCombineLatestSequence` iteration will only be reached when all of the base iterations reach a terminal state.
The throwing behavior of `AsyncCombineLatestSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point (within the first iteration or afterwards), an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
### Naming
Since the inherent behavior of `combineLatest(_:...)` combines the latest values from multiple streams into a tuple the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
### Comparison with other libraries
Combine latest often appears in libraries developed for processing events over time since the event ordering of a concept of "latest" only occurs when asynchrony is involved.
**ReactiveX** ReactiveX has an [API definition of CombineLatest](https://reactivex.io/documentation/operators/combinelatest.html) as a top level function for combining Observables.
**Combine** Combine has an [API definition of combineLatest](https://developer.apple.com/documentation/combine/publisher/combinelatest(_:)/) has an operator style method for combining Publishers.
@@ -1,57 +0,0 @@
# Compacted
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncCompactedSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestCompacted.swift)
]
## Introduction
Just as it is common for `Sequence` types that contain optional values to need to `.compactMap { $0 }`, `AsyncSequence` types have the same use cases. This common task means that the type must employ a closure to test the optional value. This can be done more efficiently for both execution performance as well as API efficiency of typing.
## Proposed Solution
Similar to the Swift Algorithms package we propose that a new method be added to `AsyncSequence` to fit this need.
```swift
extension AsyncSequence {
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
where Element == Unwrapped?
}
```
This is equivalent to writing `.compactMap { $0 }` from a behavioral standpoint but is easier to reason about and is more efficient since it does not need to execute or store a closure.
## Detailed Design
The `AsyncCompactedSequence` type from an effects standpoint works just like `AsyncCompactMapSequence`. When the base asynchronous sequence throws, the iteration of `AsyncCompactedSequence` can throw. Likewise if the base does not throw then the iteration of `AsyncCompactedSequence` does not throw. This type is conditionally `Sendable` when the base, base element, and base iterator are `Sendable.
```swift
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
where Base.Element == Element? {
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator())
}
}
extension AsyncCompactedSequence: Sendable
where
Base: Sendable, Base.Element: Sendable,
Base.AsyncIterator: Sendable { }
extension AsyncCompactedSequence.Iterator: Sendable
where
Base: Sendable, Base.Element: Sendable,
Base.AsyncIterator: Sendable { }
```
## Credits/Inspiration
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Compacted.md)
@@ -1,75 +0,0 @@
# Debounce
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[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)
]
## Introduction
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to only emit values after a given period of time of inactivity, or "quiescence", has elapsed. This algorithm is commonly referred to as debouncing.
## Proposed Solution
The debounce algorithm produces elements after a particular duration has passed between events. It transacts within a given tolerance applied to a clock. If values are produced by the base `AsyncSequence` during this quiet period, the debounce does not resume its next iterator until the period has elapsed with no values are produced or unless a terminal event is encountered.
The interface for this algorithm is available on all `AsyncSequence` types where the base type, iterator, and element are `Sendable`, since this algorithm will inherently create tasks to manage their timing of events. A shorthand implementation will be offered where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values.
```swift
extension AsyncSequence {
public func debounce<C: Clock>(
for interval: C.Instant.Duration,
tolerance: C.Instant.Duration? = nil,
clock: C
) -> AsyncDebounceSequence<Self, C>
public func debounce(
for interval: Duration,
tolerance: Duration? = nil
) -> AsyncDebounceSequence<Self, ContinuousClock>
}
```
This all boils down to a terse description of how to transform the asynchronous sequence over time.
```swift
fastEvents.debounce(for: .seconds(1))
```
In this case it transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second with no events to elapse before emitting a value.
## Detailed Design
The type that implements the algorithm for debounce emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
```swift
public struct AsyncDebounceSequence<Base: AsyncSequence, C: Clock>: Sendable
where Base.AsyncIterator: Sendable, Base.Element: Sendable, Base: Sendable {
}
extension AsyncDebounceSequence: AsyncSequence {
public typealias Element = Base.Element
public struct Iterator: AsyncIteratorProtocol, Sendable {
public mutating func next() async rethrows -> Base.Element?
}
public func makeAsyncIterator() -> Iterator
}
```
Since the stored types comprising `AsyncDebounceSequence` must be `Sendable`; `AsyncDebounceSequence` is unconditionally always `Sendable`.
## Alternatives Considered
An alternative form of `debounce` could exist similar to the reductions of `throttle`, where a closure would be invoked for each value being set as the latest, and reducing a new value to produce for the debounce.
## Credits/Inspiration
The naming for debounce comes as a term of art; originally this term was inspired by electronic circuitry. When a physical switch closes a circuit it can easily have a "bouncing" behavior (also called chatter) that is caused by electrical contact resistance and the physical bounce of springs associated with switches. That phenomenon is often addressed with additional circuits to de-bounce (removing the bouncing) by ensuring a certain quiescence occurs.
http://reactivex.io/documentation/operators/debounce.html
https://developer.apple.com/documentation/combine/publishers/debounce/
@@ -1,59 +0,0 @@
| Type | Throws | Sendability |
|-----------------------------------------------------|--------------|-------------|
| `AsyncAdjacentPairsSequence` | rethrows | Conditional |
| `AsyncBufferedByteIterator` | throws | Sendable |
| `AsyncBufferSequence` | rethrows | Conditional |
| `AsyncBufferSequence.Iterator` | rethrows | Conditional |
| `AsyncChain2Sequence` | rethrows | Conditional |
| `AsyncChain2Sequence.Iterator` | rethrows | Conditional |
| `AsyncChain3Sequence` | rethrows | Conditional |
| `AsyncChain3Sequence.Iterator` | rethrows | Conditional |
| `AsyncChannel` | non-throwing | Sendable |
| `AsyncChannel.Iterator` | non-throwing | Sendable |
| `AsyncChunkedByGroupSequence` | rethrows | Conditional |
| `AsyncChunkedByGroupSequence.Iterator` | rethrows | Conditional |
| `AsyncChunkedOnProjectionSequence` | rethrows | Conditional |
| `AsyncChunkedOnProjectionSequence.Iterator` | rethrows | Conditional |
| `AsyncChunksOfCountOrSignalSequence` | rethrows | Sendable |
| `AsyncChunksOfCountOrSignalSequence.Iterator` | rethrows | Sendable |
| `AsyncChunksOfCountSequence` | rethrows | Conditional |
| `AsyncChunksOfCountSequence.Iterator` | rethrows | Conditional |
| `AsyncCombineLatest2Sequence` | rethrows | Sendable |
| `AsyncCombineLatest2Sequence.Iterator` | rethrows | Sendable |
| `AsyncCombineLatest3Sequence` | rethrows | Sendable |
| `AsyncCombineLatest3Sequence.Iterator` | rethrows | Sendable |
| `AsyncCompactedSequence` | rethrows | Conditional |
| `AsyncCompactedSequence.Iterator` | rethrows | Conditional |
| `AsyncDebounceSequence` | rethrows | Sendable |
| `AsyncDebounceSequence.Iterator` | rethrows | Sendable |
| `AsyncExclusiveReductionsSequence` | rethrows | Conditional |
| `AsyncExclusiveReductionsSequence.Iterator` | rethrows | Conditional |
| `AsyncInclusiveReductionsSequence` | rethrows | Conditional |
| `AsyncInclusiveReductionsSequence.Iterator` | rethrows | Conditional |
| `AsyncInterspersedSequence` | rethrows | Conditional |
| `AsyncInterspersedSequence.Iterator` | rethrows | Conditional |
| `AsyncJoinedSequence` | rethrows | Conditional |
| `AsyncJoinedSequence.Iterator` | rethrows | Conditional |
| `AsyncLazySequence` | non-throwing | Conditional |
| `AsyncLazySequence.Iterator` | non-throwing | Conditional |
| `AsyncLimitBuffer` | non-throwing | Sendable |
| `AsyncMerge2Sequence` | rethrows | Sendable |
| `AsyncMerge2Sequence.Iterator` | rethrows | Sendable |
| `AsyncMerge3Sequence` | rethrows | Sendable |
| `AsyncMerge3Sequence.Iterator` | rethrows | Sendable |
| `AsyncRemoveDuplicatesSequence` | rethrows | Conditional |
| `AsyncRemoveDuplicatesSequence.Iterator` | rethrows | Conditional |
| `AsyncThrottleSequence` | rethrows | Conditional |
| `AsyncThrottleSequence.Iterator` | rethrows | Conditional |
| `AsyncThrowingChannel` | throws | Sendable |
| `AsyncThrowingChannel.Iterator` | throws | Sendable |
| `AsyncThrowingExclusiveReductionsSequence` | throws | Conditional |
| `AsyncThrowingExclusiveReductionsSequence.Iterator` | throws | Conditional |
| `AsyncThrowingInclusiveReductionsSequence` | throws | Conditional |
| `AsyncThrowingInclusiveReductionsSequence.Iterator` | throws | Conditional |
| `AsyncTimerSequence` | non-throwing | Sendable |
| `AsyncTimerSequence.Iterator` | non-throwing | Sendable |
| `AsyncZip2Sequence` | rethrows | Sendable |
| `AsyncZip2Sequence.Iterator` | rethrows | Sendable |
| `AsyncZip3Sequence` | rethrows | Sendable |
| `AsyncZip3Sequence.Iterator` | rethrows | Sendable |
@@ -1,60 +0,0 @@
# Intersperse
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncInterspersedSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestInterspersed.swift)]
Places a given value in between each element of the asynchronous sequence.
```swift
let numbers = [1, 2, 3].async.interspersed(with: 0)
for await number in numbers {
print(number)
}
// prints 1 0 2 0 3
let empty = [].async.interspersed(with: 0)
// await Array(empty) == []
```
`interspersed(with:)` takes a separator value and inserts it in between every
element in the asynchronous sequence.
## Detailed Design
A new method is added to `AsyncSequence`:
```swift
extension AsyncSequence {
func interspersed(with separator: Element) -> AsyncInterspersedSequence<Self>
}
```
The new `AsyncInterspersedSequence` type represents the asynchronous sequence
when the separator is inserted between each element.
When the base asynchronous sequence can throw on iteration, `AsyncInterspersedSequence`
will throw on iteration. When the base does not throw, the iteration of
`AsyncInterspersedSequence` does not throw either.
`AsyncInterspersedSequence` is conditionally `Sendable` when the base asynchronous
sequence is `Sendable` and the element is also `Sendable`.
### Naming
This method’s and type’s name match the term of art used in other languages
and libraries.
This method is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Intersperse.md).
### Comparison with other languages
**[Haskell][Haskell]:** Has an `intersperse` function which takes an element
and a list and 'intersperses' that element between the elements of the list.
**[Rust][Rust]:** Has a function called `intersperse` to insert a particular
value between each element.
<!-- Link references for other languages -->
[Haskell]: https://hackage.haskell.org/package/base-4.14.0.0/docs/Data-List.html#v:intersperse
[Rust]: https://docs.rs/itertools/0.9.0/itertools/trait.Itertools.html#method.intersperse
@@ -1,127 +0,0 @@
# Joined
* Author(s): [Kevin Perry](https://github.com/kperryua)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncJoinedSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestJoin.swift)
]
## Introduction
Concatenates an asynchronous sequence of asynchronous sequences that share an `Element` type together sequentially where the elements from the resulting asynchronous sequence are comprised in order from the elements of the first asynchronous sequence and then the second (and so on) or until an error occurs. Similar to `chain()`, except the number of asynchronous sequences to concatenate is not known up front.
Optionally allows inserting the elements of a separator asynchronous sequence in between each of the other sequences.
```swift
let sequenceOfURLs: AsyncSequence<URL> = ...
let sequenceOfLines = sequenceOfURLs.map { $0.lines }
let joinedWithSeparator = sequenceOfLines.joined(separator: ["===================="].async)
for try await lineOrSeparator in joinedWithSeparator {
print(lineOrSeparator)
}
```
This example shows how an `AsyncSequence` of `URL`s can be turned into an `AsyncSequence` of the lines of each of those files in sequence, with a separator line in between each file.
## Proposed Solution
```swift
extension AsyncSequence where Element: AsyncSequence {
public func joined() -> AsyncJoinedSequence<Self> {
return AsyncJoinedSequence(self)
}
}
```
```swift
extension AsyncSequence where Element: AsyncSequence {
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
return AsyncJoinedBySeparatorSequence(self, separator: separator)
}
}
```
## Detailed Design
```swift
public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
public typealias Element = Base.Element.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Base.Element.Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncJoinedSequence: Sendable
where
Base: Sendable,
Base.Element: Sendable,
Base.Element.Element: Sendable,
Base.AsyncIterator: Sendable,
Base.Element.AsyncIterator: Sendable { }
extension AsyncJoinedSequence.Iterator: Sendable
where
Base: Sendable,
Base.Element: Sendable,
Base.Element.Element: Sendable,
Base.AsyncIterator: Sendable,
Base.Element.AsyncIterator: Sendable { }
```
```swift
public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: AsyncSequence>: AsyncSequence
where Base.Element: AsyncSequence, Separator.Element == Base.Element.Element {
public typealias Element = Base.Element.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Base.Element.Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncJoinedBySeparatorSequence: Sendable
where
Base: Sendable,
Base.Element: Sendable,
Base.Element.Element: Sendable,
Base.AsyncIterator: Sendable,
Separator: Sendable,
Separator.AsyncIterator: Sendable,
Base.Element.AsyncIterator: Sendable { }
extension AsyncJoinedBySeparatorSequence.Iterator: Sendable
where
Base: Sendable,
Base.Element: Sendable,
Base.Element.Element: Sendable,
Base.AsyncIterator: Sendable,
Separator: Sendable,
Separator.AsyncIterator: Sendable,
Base.Element.AsyncIterator: Sendable { }
```
The resulting `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` type is an asynchronous sequence, with conditional conformance to `Sendable` when the arguments conform.
When any of the asynchronous sequences being joined together come to their end of iteration, the `Joined` sequence iteration proceeds to the separator asynchronous sequence, if any. When the separator asynchronous sequence terminates, or if no separator was specified, it proceeds on to the next asynchronous sequence. When the last asynchronous sequence reaches the end of iteration the `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` then ends its iteration. At any point in time if one of the comprising asynchronous sequences ever throws an error during iteration the `AsyncJoinedSequence` or `AsyncJoinedBySeparatorSequence` iteration will throw that error and end iteration.
## Future Directions
The Swift Algorithms package has [additional synchronous variants of `joined()`](https://github.com/apple/swift-algorithms/blob/main/Guides/Joined.md). It is conceivable to bring asynchronous variants of those over to `AsyncSequence`.
The variant that takes a single element as a separator is straightforward, but can be trivially replicated with `[element].async`. However, it may be beneficial for performance to reimplement this directly.
There is another variant that takes a closure that allows one to customize the separator based on the return value of a closure. That closure is passed each of the two consecutive asynchronous sequences (not the two neighboring elements in consecutive sequences). This variant arguably has the greatest utility when the sequence type conforms to `Collection`, allowing either the `count` or any arbitrary element to be obtained directly. With `AsyncSequence`, it is less likely that this function with provide a similar level of utility, so it has been omitted.
## Alternatives Considered
Because `joined()` is essentially identical to `flatMap { $0 }`, it was considered that this should be called `flatten()` instead. However, it is preferable to follow the lead of the Swift standard library's `joined()` method.
## Credits/Inspiration
The Swift standard library has functions on synchronous sequences ([`joined()`](https://developer.apple.com/documentation/swift/sequence/1641166-joined), [`joined(separator:)`](https://developer.apple.com/documentation/swift/sequence/2431985-joined)) that perform similar (but synchronous) tasks.
@@ -1,39 +0,0 @@
# AsyncLazySequence
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncLazySequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestLazy.swift)]
Converts a non-asynchronous sequence into an asynchronous one.
This operation is available for all `Sequence` types.
```swift
let numbers = [1, 2, 3, 4].async
let characters = "abcde".async
```
This transformation can be useful to test operations specifically available on `AsyncSequence` but also is useful
to combine with other `AsyncSequence` types to provide well known sources of data.
## Detailed Design
The `.async` property returns an `AsyncLazySequence` that is generic upon the base `Sequence` it was constructed from.
```swift
extension Sequence {
public var async: AsyncLazySequence<Self> { get }
}
public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
...
}
extension AsyncLazySequence: Sendable where Base: Sendable { }
extension AsyncLazySequence.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`.
@@ -1,83 +0,0 @@
# Merge
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/Asyncmerge2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncMerge3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestMerge.swift)]
Merges two or more asynchronous sequences sharing the same element type into one singular asynchronous sequence.
```swift
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines.map { "AAPL: " + $0 }
let nasdaqFeed = URL(string:"http://www.example.com/ticker?symbol=^IXIC")!.lines.map { "^IXIC: " + $0 }
for try await ticker in merge(appleFeed, nasdaqFeed) {
print(ticker)
}
```
Given some sample inputs the following merged events can be expected.
| Timestamp | appleFeed | nasdaqFeed | merged output |
| ----------- | --------- | ---------- | --------------- |
| 11:40 AM | 173.91 | | AAPL: 173.91 |
| 12:25 AM | | 14236.78 | ^IXIC: 14236.78 |
| 12:40 AM | | 14218.34 | ^IXIC: 14218.34 |
| 1:15 PM | 173.00 | | AAPL: 173.00 |
## Detailed Design
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
```swift
public func merge<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncMerge2Sequence<Base1, Base2>
public func merge<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncMerge3Sequence<Base1, Base2, Base3>
public struct AsyncMerge2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
where
Base1.Element == Base2.Element,
Base1: Sendable, Base2: Sendable,
Base1.Element: Sendable, Base2.Element: Sendable,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncMerge3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1.Element == Base2.Element, Base1.Element == Base3.Element,
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = Base1.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `merge(_:...)` function takes two or more asynchronous sequences as arguments and produces an `AsyncMergeSequence` which is an asynchronous sequence.
Since the bases comprising the `AsyncMergeSequence` must be iterated concurrently to produce the latest value, those sequences must be able to be sent to child tasks. This means that a prerequisite of the bases must be that the base asynchronous sequences, their iterators, and the elements they produce must be `Sendable`.
When iterating a `AsyncMergeSequence`, the sequence terminates when all of the base asynchronous sequences terminate, since this means there is no potential for any further elements to be produced.
The throwing behavior of `AsyncMergeSequence` is that if any of the bases throw, then the composed asynchronous sequence throws on its iteration. If at any point an error is thrown by any base, the other iterations are cancelled and the thrown error is immediately thrown to the consuming iteration.
### Naming
Since the inherent behavior of `merge(_:...)` merges values from multiple streams into a singular asynchronous sequence, the naming is intended to be quite literal. There are precedent terms of art in other frameworks and libraries (listed in the comparison section). Other naming takes the form of "withLatestFrom". This was disregarded since the "with" prefix is often most associated with the passing of a closure and some sort of contextual concept; `withUnsafePointer` or `withUnsafeContinuation` are prime examples.
### Comparison with other libraries
**ReactiveX** ReactiveX has an [API definition of Merge](https://reactivex.io/documentation/operators/merge.html) as a top level function for merging Observables.
**Combine** Combine has an [API definition of merge(with:)](https://developer.apple.com/documentation/combine/publisher/merge(with:)-7qt71/) as an operator style method for merging Publishers.
@@ -1,131 +0,0 @@
# Reductions
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncExclusiveReductionsSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestReductions.swift)
]
## Introduction
The family of algorithms for reduce are useful for converting a sequence or asynchronous sequence into a single value, but that can elide important intermediate information. The _reductions_ algorithm is often called "scan", but this name does not convey its heritage to the family of reducing.
There are two strategies that are usable for creating continuous reductions: exclusive reductions and inclusive reductions:
* Exclusive reductions take a value and incorporate values into that initial value. A common example is reductions by appending to an array.
* Inclusive reductions transact only on the values provided. A common example is adding numbers.
## Proposed Solution
Exclusive reductions come in two variants: transforming by application, or transformation via mutation. This replicates the same interface as `reduce(_:_:)` and `reduce(into:_:)`. Unlike the `reduce` algorithms, the `reductions` algorithm also comes in two flavors: throwing or non throwing transformations.
```swift
extension AsyncSequence {
public func reductions<Result>(
_ initial: Result,
_ transform: @Sendable @escaping (Result, Element) async -> Result
) -> AsyncExclusiveReductionsSequence<Self, Result>
public func reductions<Result>(
into initial: Result,
_ transform: @Sendable @escaping (inout Result, Element) async -> Void
) -> AsyncExclusiveReductionsSequence<Self, Result>
}
extension AsyncSequence {
public func reductions<Result>(
_ initial: Result,
_ transform: @Sendable @escaping (Result, Element) async throws -> Result
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
public func reductions<Result>(
into initial: Result,
_ transform: @Sendable @escaping (inout Result, Element) async throws -> Void
) -> AsyncThrowingExclusiveReductionsSequence<Self, Result>
}
```
These APIs can be used to reduce an initial value progressively or reduce into an initial value via mutation. In practice, a common use case for reductions is to mutate a collection by appending values.
```swift
characters.reductions(into: "") { $0.append($1) }
```
If the characters being produced asynchronously are `"a", "b", "c"`, then the iteration of the reductions is `"a", "ab", "abc"`.
Inclusive reductions do not have an initial value and therefore do not need an additional variations beyond the throwing and non throwing flavors.
```swift
extension AsyncSequence {
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async -> Element
) -> AsyncInclusiveReductionsSequence<Self>
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
) -> AsyncThrowingInclusiveReductionsSequence<Self>
}
```
This is often used for scenarios like a running tally or other similar cases.
```swift
numbers.reductions { $0 + $1 }
```
In the above example, if the numbers are a sequence of `1, 2, 3, 4`, the produced values would be `1, 3, 6, 10`.
## Detailed Design
The exclusive reduction variants come in two distinct cases: non-throwing and throwing. These both have corresponding types to encompass that throwing behavior.
For non-throwing exclusive reductions, the element type of the sequence is the result of the reduction transform. `AsyncExclusiveReductionsSequence` will throw if the base asynchronous sequence throws, and will not throw if the base does not throws.
```swift
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
}
extension AsyncExclusiveReductionsSequence: AsyncSequence {
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncExclusiveReductionsSequence: Sendable
where Base: Sendable, Element: Sendable { }
extension AsyncExclusiveReductionsSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Element: Sendable { }
```
The sendability behavior of `AsyncExclusiveReductionsSequence` is such that when the base, base iterator, and element are `Sendable` then `AsyncExclusiveReductionsSequence` is `Sendable`.
```swift
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
}
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async throws -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncThrowingExclusiveReductionsSequence: Sendable
where Base: Sendable, Element: Sendable { }
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable, Element: Sendable { }
```
## Alternatives Considered
One alternate name for `reductions` was to name it `scan`; however the naming from the Swift Algorithms package offers considerably more inference to the heritage of what family of functions this algorithm belongs to.
## Credits/Inspiration
This transformation function is a direct analog to the synchronous version [defined in the Swift Algorithms package](https://github.com/apple/swift-algorithms/blob/main/Guides/Reductions.md)
@@ -1,93 +0,0 @@
# RemoveDuplicates
* Author(s): [Kevin Perry](https://github.com/kperryua)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncRemoveDuplicatesSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestRemoveDuplicates.swift)
]
## Introduction
When processing values over time it is definitely possible that the same value may occur in a row. When the distinctness of the presence value is not needed it is useful to consider the values over time that are differing from the last. Particularly this can be expressed as removing duplicate values either in the case as they are directly `Equatable` or by a predicate.
## Proposed Solution
The `removeDuplicates()` and `removeDuplicates(by:)` APIs serve this purpose of removing duplicate values that occur. These algorithms test against the previous value and if the latest iteration of the base `AsyncSequence` is the same as the last it invokes `next()` again. The resulting `AsyncRemoveDuplicatesSequence` will ensure that no duplicate values occur next to each other. This should not be confused with only emitting unique new values; where each value is tested against a collected set of values.
```swift
extension AsyncSequence where Element: Equatable {
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self>
}
extension AsyncSequence {
public func removeDuplicates(
by predicate: @escaping @Sendable (Element, Element) async -> Bool
) -> AsyncRemoveDuplicatesSequence<Self>
public func removeDuplicates(
by predicate: @escaping @Sendable (Element, Element) async throws -> Bool
) -> AsyncThrowingRemoveDuplicatesSequence<Self>
}
```
The `removeDuplicates` family comes in three variants. One variant is conditional upon the `Element` type being `Equatable`. This variation is a shorthand for writing `.removeDuplicates { $0 == $1 }`. The next variation is the closure version that allows for custom predicates to be applied. This algorithm allows for the cases where the elements themselves may not be equatable but portions of the element may be compared. Lastly is the variation that allows for comparison when the comparison method may throw.
## Detailed Design
In the cases where the `Element` type is `Equatable` or the non-trowing predicate variant these utilize the type `AsyncRemoveDuplicatesSequence`. The throwing predicate variant uses `AsyncThrowingRemoveDuplicatesSequence`. Both of these types are conditionally `Sendable` when the base, base element, and base iterator are `Sendable`
The `AsyncRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and will not throw if the base asynchronous sequence does not throw.
```swift
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator {
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
}
}
extension AsyncRemoveDuplicatesSequence: Sendable
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
extension AsyncRemoveDuplicatesSequence.Iterator: Sendable
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
```
The `AsyncThrowingRemoveDuplicatesSequence` will rethrow if the base asynchronous sequence throws and still may throw if the base asynchronous sequence does not throw due to the predicate having the potential of throwing.
```swift
public struct AsyncThrowingRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async throws -> Element?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncThrowingRemoveDuplicatesSequence: Sendable
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
extension AsyncThrowingRemoveDuplicatesSequence.Iterator: Sendable
where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
```
## Alternatives Considered
An alternative algorithm for uniqueness was considered but was discounted since it does not directly belong to this particular family of methods.
The name of this method could be considered to belong to the `filter` family and could refer directly to the repetitions. There is distinct merit to considering the name to be `filterRepetitions` or `removeRepetitions`. Likewise the terminology of `drop` also has merit.
## Credits/Inspiration
The Combine framework has a [function for publishers](https://developer.apple.com/documentation/combine/publisher/removeduplicates()/) that performs a similar task.
@@ -1,53 +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
@@ -1,90 +0,0 @@
# Throttle
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncThrottleSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestThrottle.swift)
]
## Introduction
When events can potentially happen faster than the desired consumption rate, there are multiple ways to handle the situation. One approach is to emit values after a given period has elapsed. These emitted values can be reduced from the values encountered during the waiting period. This algorithm is commonly referred to as throttling.
## Proposed Solution
The throttle algorithm produces elements such that at least a specific interval has elapsed between them. It transacts by measuring against a specific clock. If values are produced by the base `AsyncSequence` the throttle does not resume its next iterator until the period has elapsed or unless a terminal event is encountered.
The interface for this algorithm is available on all `AsyncSequence` types. Unlike other algorithms like `debounce`, the throttle algorithm does not need to create additional tasks or require any sort of tolerance because the interval is just measured. A shorthand implementation will be offered in conjunction where the clock is the `ContinuousClock`, which allows for easy construction with `Duration` values. An additional shorthand is offered to reduce the values such that it provides a "latest" or "earliest" value, representing the leading or trailing edge of a throttled region of production of events.
```swift
extension AsyncSequence {
public func throttle<C: Clock, Reduced>(
for interval: C.Instant.Duration,
clock: C,
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
) -> AsyncThrottleSequence<Self, C, Reduced>
public func throttle<Reduced>(
for interval: Duration,
reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced
) -> AsyncThrottleSequence<Self, ContinuousClock, Reduced>
public func throttle<C: Clock>(
for interval: C.Instant.Duration,
clock: C,
latest: Bool = true
) -> AsyncThrottleSequence<Self, C, Element>
public func throttle(
for interval: Duration,
latest: Bool = true
) -> AsyncThrottleSequence<Self, ContinuousClock, Element>
}
```
This all boils down to a terse description of how to transform the asynchronous sequence over time.
```swift
fastEvents.throttle(for: .seconds(1))
```
In this case, the throttle transforms a potentially fast asynchronous sequence of events into one that waits for a window of 1 second to elapse before emitting a value.
## Detailed Design
The type that implements the algorithm for throttle emits the same element type as the base that it applies to. It also throws when the base type throws (and likewise does not throw when the base type does not throw).
```swift
public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
}
extension AsyncThrottleSequence: AsyncSequence {
public typealias Element = Reduced
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Reduced?
}
public func makeAsyncIterator() -> Iterator
}
extension AsyncThrottleSequence: Sendable
where Base: Sendable, Element: Sendable { }
extension AsyncThrottleSequence.Iterator: Sendable
where Base.AsyncIterator: Sendable { }
```
The `AsyncThrottleSequence` and its `Iterator` are conditionally `Sendable` if the base types comprising it are `Sendable`.
The time in which events are measured are from the previous emission if present. If a duration has elapsed between the last emission and the point in time the throttle is measured then that duration is counted as elapsed. The first element is considered not throttled because no interval can be constructed from the start to the first element.
## Alternatives Considered
It was considered to only provide the "latest" style APIs, however the reduction version grants more flexibility and can act as a funnel to the implementations of `latest`.
## Credits/Inspiration
http://reactivex.io/documentation/operators/sample.html
https://developer.apple.com/documentation/combine/publishers/throttle/
@@ -1,51 +0,0 @@
# Timer
* Author(s): [Philippe Hausler](https://github.com/phausler)
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncTimerSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestTimer.swift)
]
## Introduction
Producing elements at regular intervals can be useful for composing with other algorithms. These can range from invoking code at specific times to using those regular intervals as a delimiter of events. There are other cases this exists in APIs however those do not currently interact with Swift concurrency. These existing APIs are ones like `Timer` or `DispatchTimer` but are bound to internal clocks that are not extensible.
## Proposed Solution
We propose to add a new type; `AsyncTimerSequence` which utilizes the new `Clock`, `Instant` and `Duration` types. This allows the interaction of the timer to custom implementations of types adopting `Clock`.
This asynchronous sequence will produce elements of the clock's `Instant` type after the interval has elapsed. That instant will be the `now` at the time that the sleep has resumed. For each invocation to `next()` the `AsyncTimerSequence.Iterator` will calculate the next deadline to resume and pass that and the tolerance to the clock. If at any point in time the task executing that iteration is cancelled the iteration will return `nil` from the call to `next()`.
```swift
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
public typealias Element = C.Instant
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async -> C.Instant?
}
public init(
interval: C.Instant.Duration,
tolerance: C.Instant.Duration? = nil,
clock: C
)
public func makeAsyncIterator() -> Iterator
}
extension AsyncTimerSequence where C == SuspendingClock {
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock>
}
extension AsyncTimerSequence: Sendable { }
extension AsyncTimerSequence.Iterator: Sendable { }
```
Since all the types comprising `AsyncTimerSequence` and it's `Iterator` are `Sendable` these types are also `Sendable.
## Credits/Inspiration
https://developer.apple.com/documentation/foundation/timer
https://developer.apple.com/documentation/foundation/timer/timerpublisher
@@ -1,85 +0,0 @@
# Zip
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncZip2Sequence.swift), [Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncZip3Sequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestZip.swift)]
Combines the latest values produced from two or more asynchronous sequences into an asynchronous sequence of tuples.
```swift
let appleFeed = URL(string: "http://www.example.com/ticker?symbol=AAPL")!.lines
let nasdaqFeed = URL(string: "http://www.example.com/ticker?symbol=^IXIC")!.lines
for try await (apple, nasdaq) in zip(appleFeed, nasdaqFeed) {
print("APPL: \(apple) NASDAQ: \(nasdaq)")
}
```
Given some sample inputs the following zipped events can be expected.
| Timestamp | appleFeed | nasdaqFeed | combined output |
| ----------- | --------- | ---------- | ----------------------------- |
| 11:40 AM | 173.91 | | |
| 12:25 AM | | 14236.78 | AAPL: 173.91 NASDAQ: 14236.78 |
| 12:40 AM | | 14218.34 | |
| 1:15 PM | 173.00 | | AAPL: 173.00 NASDAQ: 14218.34 |
## Detailed Design
This function family and the associated family of return types are prime candidates for variadic generics. Until that proposal is accepted, these will be implemented in terms of two- and three-base sequence cases.
```swift
public func zip<Base1: AsyncSequence, Base2: AsyncSequence>(_ base1: Base1, _ base2: Base2) -> AsyncZip2Sequence<Base1, Base2>
public func zip<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ base1: Base1, _ base2: Base2, _ base3: Base3) -> AsyncZip3Sequence<Base1, Base2, Base3>
public struct AsyncZip2Sequence<Base1: AsyncSequence, Base2: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable,
Base1.Element: Sendable, Base2.Element: Sendable,
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
public struct AsyncZip3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>: Sendable
where
Base1: Sendable, Base2: Sendable, Base3: Sendable
Base1.Element: Sendable, Base2.Element: Sendable, Base3.Element: Sendable
Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable {
public typealias Element = (Base1.Element, Base2.Element, Base3.Element)
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async rethrows -> Element?
}
public func makeAsyncIterator() -> Iterator
}
```
The `zip(_:...)` function takes two or more asynchronous sequences as arguments with the resulting `AsyncZipSequence` which is an asynchronous sequence.
Each iteration of an `AsyncZipSequence` will await for all base iterators to produce a value. This iteration will be done concurrently to produce a singular tuple result. If any of the base iterations terminates by returning `nil` from its iteration, the `AsyncZipSequence` iteration is immediately considered unsatisfiable and returns `nil` and all iterations of other bases will be cancelled. If any iteration of the bases throws an error, then the other iterations concurrently running are cancelled and the produced error is rethrown, terminating the iteration.
`AsyncZipSequence` requires that the iterations are done concurrently. This means that the base sequences, their elements, and iterators must all be `Sendable`. That makes `AsyncZipSequence` inherently `Sendable`.
The source of throwing of `AsyncZipSequence` is determined by its bases. That means that if any base can throw an error then the iteration of the `AsyncZipSequence` can throw. If no bases can throw, then the `AsyncZipSequence` does not throw.
### Naming
The `zip(_:...)` function takes its name from the Swift standard library function of the same name. The `AsyncZipSequence` family of types take their name from the same family from the standard library for the type returned by `zip(_:_:)`. The one difference is that this asynchronous version allows for the affordance of recognizing the eventual variadic generic need of expanding a zip of more than just two sources.
It is common in some libraries to have a `ZipMap` or some other combination of `zip` and `map`. This is a common usage pattern, but leaving a singular type for composition feels considerably more approachable.
### Comparison with other libraries
**Swift** The swift standard library has an [API definition of zip](https://developer.apple.com/documentation/swift/1541125-zip) as a top level function for combining two sequences.
**ReactiveX** ReactiveX has an [API definition of Zip](https://reactivex.io/documentation/operators/zip.html) as a top level function for combining Observables.
**Combine** Combine has an [API definition of zip](https://developer.apple.com/documentation/combine/publisher/zip(_:)/) as an operator style method for combining Publishers.
@@ -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 characteristics 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 { }
extension AsyncBufferSequence.Iterator: Sendable where Base: 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)
}
}
@@ -1,156 +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 `AsyncIterator` that provides a convenient and high-performance implementation
/// of a common architecture for `AsyncSequence` of `UInt8`, otherwise known as byte streams.
///
/// Bytes are read into an internal buffer of `capacity` bytes via the
/// `readFunction`. Invoking `next()` returns bytes from the internal buffer until it's
/// empty, and then suspends and awaits another invocation of `readFunction` to
/// refill. If `readFunction` returns 0 (indicating nothing was read), `next()` will
/// return `nil` from then on. Cancellation is checked before each invocation of
/// `readFunction`, which means that many calls to `next()` will not check for
/// cancellation.
///
/// A typical use of `AsyncBufferedByteIterator` looks something like this:
///
/// struct AsyncBytes: AsyncSequence {
/// public typealias Element = UInt8
/// var handle: ReadableThing
///
/// internal init(_ readable: ReadableThing) {
/// handle = readable
/// }
///
/// public func makeAsyncIterator() -> AsyncBufferedByteIterator {
/// return BufferedAsyncByteIterator(capacity: 16384) { buffer in
/// // This runs once every 16384 invocations of next()
/// return try await handle.read(into: buffer)
/// }
/// }
/// }
///
///
public struct AsyncBufferedByteIterator: AsyncIteratorProtocol, Sendable {
public typealias Element = UInt8
@usableFromInline var buffer: _AsyncBytesBuffer
/// Creates an asynchronous buffered byte iterator with a specified capacity and read function.
///
/// - Parameters:
/// - capacity: The maximum number of bytes that a single invocation of `readFunction` may produce.
/// This is the allocated capacity of the backing buffer for iteration; the value must be greater than 0.
/// - readFunction: The function for refilling the buffer.
public init(
capacity: Int,
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
) {
buffer = _AsyncBytesBuffer(capacity: capacity, readFunction: readFunction)
}
/// Reads a byte out of the buffer if available. When no bytes are available, this will trigger
/// the read function to reload the buffer and then return the next byte from that buffer.
@inlinable @inline(__always)
public mutating func next() async throws -> UInt8? {
return try await buffer.next()
}
}
@frozen @usableFromInline
internal struct _AsyncBytesBuffer: @unchecked Sendable {
@usableFromInline
final class Storage: Sendable {
fileprivate let buffer: UnsafeMutableRawBufferPointer
init(
capacity: Int
) {
precondition(capacity > 0)
buffer = UnsafeMutableRawBufferPointer.allocate(
byteCount: capacity,
alignment: MemoryLayout<AnyObject>.alignment
)
}
deinit {
buffer.deallocate()
}
}
@usableFromInline internal var storage: Storage
@usableFromInline internal var nextPointer: UnsafeRawPointer
@usableFromInline internal var endPointer: UnsafeRawPointer
internal let readFunction: @Sendable (UnsafeMutableRawBufferPointer) async throws -> Int
internal var finished = false
@usableFromInline init(
capacity: Int,
readFunction: @Sendable @escaping (UnsafeMutableRawBufferPointer) async throws -> Int
) {
let s = Storage(capacity: capacity)
self.readFunction = readFunction
storage = s
nextPointer = UnsafeRawPointer(s.buffer.baseAddress!)
endPointer = nextPointer
}
@inline(never) @usableFromInline
internal mutating func reloadBufferAndNext() async throws -> UInt8? {
if finished {
return nil
}
try Task.checkCancellation()
do {
// If two tasks have access to this iterator then the references on
// the storage will be non uniquely owned. This means that any reload
// must happen into it's own fresh buffer. The consumption of those
// bytes between two tasks are inherently defined as potential
// duplication by the nature of sending that buffer across the two
// tasks - this means that the brief period in which they may be
// sharing non reloaded bytes is to be expected; basically in that
// edge case of making the iterator and sending that across to two
// places to iterate is asking for something bizzare and the answer
// should not be crash, but it definitely cannot be consistent.
//
// The unique ref check is here to prevent the potentials of a crashing
// secnario.
if !isKnownUniquelyReferenced(&storage) {
// The count is not mutated across invocations so the access is safe.
let capacity = storage.buffer.count
storage = Storage(capacity: capacity)
}
let readSize: Int = try await readFunction(storage.buffer)
if readSize == 0 {
finished = true
nextPointer = endPointer
return nil
}
nextPointer = UnsafeRawPointer(storage.buffer.baseAddress!)
endPointer = nextPointer + readSize
} catch {
finished = true
nextPointer = endPointer
throw error
}
return try await next()
}
@inlinable @inline(__always)
internal mutating func next() async throws -> UInt8? {
if _fastPath(nextPointer != endPointer) {
let byte = nextPointer.load(fromByteOffset: 0, as: UInt8.self)
nextPointer = nextPointer + 1
return byte
}
return try await reloadBufferAndNext()
}
}
@@ -1,83 +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
//
//===----------------------------------------------------------------------===//
/// Returns a new asynchronous sequence that iterates over the two given asynchronous sequences, one
/// followed by the other.
///
/// - Parameters:
/// - s1: The first asynchronous sequence.
/// - s2: The second asynchronous sequence.
/// - Returns: An asynchronous sequence that iterates first over the elements of `s1`, and
/// then over the elements of `s2`.
@inlinable
public func chain<Base1: AsyncSequence, Base2: AsyncSequence>(_ s1: Base1, _ s2: Base2) -> AsyncChain2Sequence<Base1, Base2> where Base1.Element == Base2.Element {
AsyncChain2Sequence(s1, s2)
}
/// A concatenation of two asynchronous sequences with the same element type.
@frozen
public struct AsyncChain2Sequence<Base1: AsyncSequence, Base2: AsyncSequence> where Base1.Element == Base2.Element {
@usableFromInline
let base1: Base1
@usableFromInline
let base2: Base2
@usableFromInline
init(_ base1: Base1, _ base2: Base2) {
self.base1 = base1
self.base2 = base2
}
}
extension AsyncChain2Sequence: AsyncSequence {
public typealias Element = Base1.Element
/// The iterator for a `AsyncChain2Sequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base1: Base1.AsyncIterator?
@usableFromInline
var base2: Base2.AsyncIterator?
@usableFromInline
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator) {
self.base1 = base1
self.base2 = base2
}
@inlinable
public mutating func next() async rethrows -> Element? {
do {
if let value = try await base1?.next() {
return value
} else {
base1 = nil
}
return try await base2?.next()
} catch {
base1 = nil
base2 = nil
throw error
}
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator())
}
}
extension AsyncChain2Sequence: Sendable where Base1: Sendable, Base2: Sendable { }
extension AsyncChain2Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable { }
@@ -1,98 +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
//
//===----------------------------------------------------------------------===//
/// Returns a new asynchronous sequence that iterates over the three given asynchronous sequences, one
/// followed by the other.
///
/// - Parameters:
/// - s1: The first asynchronous sequence.
/// - s2: The second asynchronous sequence.
/// - s3: The third asynchronous sequence.
/// - Returns: An asynchronous sequence that iterates first over the elements of `s1`, and
/// then over the elements of `s2`, and then over the elements of `s3`
@inlinable
public func chain<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence>(_ s1: Base1, _ s2: Base2, _ s3: Base3) -> AsyncChain3Sequence<Base1, Base2, Base3> {
AsyncChain3Sequence(s1, s2, s3)
}
/// A concatenation of three asynchronous sequences with the same element type.
@frozen
public struct AsyncChain3Sequence<Base1: AsyncSequence, Base2: AsyncSequence, Base3: AsyncSequence> where Base1.Element == Base2.Element, Base1.Element == Base3.Element {
@usableFromInline
let base1: Base1
@usableFromInline
let base2: Base2
@usableFromInline
let base3: Base3
@usableFromInline
init(_ base1: Base1, _ base2: Base2, _ base3: Base3) {
self.base1 = base1
self.base2 = base2
self.base3 = base3
}
}
extension AsyncChain3Sequence: AsyncSequence {
public typealias Element = Base1.Element
/// The iterator for a `AsyncChain3Sequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base1: Base1.AsyncIterator?
@usableFromInline
var base2: Base2.AsyncIterator?
@usableFromInline
var base3: Base3.AsyncIterator?
@usableFromInline
init(_ base1: Base1.AsyncIterator, _ base2: Base2.AsyncIterator, _ base3: Base3.AsyncIterator) {
self.base1 = base1
self.base2 = base2
self.base3 = base3
}
@inlinable
public mutating func next() async rethrows -> Element? {
do {
if let value = try await base1?.next() {
return value
} else {
base1 = nil
}
if let value = try await base2?.next() {
return value
} else {
base2 = nil
}
return try await base3?.next()
} catch {
base1 = nil
base2 = nil
base3 = nil
throw error
}
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base1.makeAsyncIterator(), base2.makeAsyncIterator(), base3.makeAsyncIterator())
}
}
extension AsyncChain3Sequence: Sendable where Base1: Sendable, Base2: Sendable, Base3: Sendable { }
extension AsyncChain3Sequence.Iterator: Sendable where Base1.AsyncIterator: Sendable, Base2.AsyncIterator: Sendable, Base3.AsyncIterator: Sendable { }
-243
View File
@@ -1,243 +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 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(_:)` and `finish()` via the 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 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
if awaiting.isEmpty {
self = .idle
} else {
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
var terminal = false
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Never>?, Never>? in
if state.terminal {
terminal = true
return nil
}
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
}
if nexts.isEmpty {
state.emission = .idle
} else {
state.emission = .awaiting(nexts)
}
return nil
}
}?.resume()
if cancelled || terminal {
continuation.resume(returning: nil)
}
}
}
func finishAll() {
let (sends, nexts) = state.withCriticalRegion { state -> ([UnsafeContinuation<UnsafeContinuation<Element?, Never>?, Never>], Set<Awaiting>) in
if state.terminal {
return ([], [])
}
state.terminal = true
switch state.emission {
case .idle:
return ([], [])
case .pending(let nexts):
state.emission = .idle
return (nexts, [])
case .awaiting(let nexts):
state.emission = .idle
return ([], nexts)
}
}
for send in sends {
send.resume(returning: nil)
}
for next in nexts {
next.continuation?.resume(returning: nil)
}
}
func _send(_ element: Element) async {
await withTaskCancellationHandler {
finishAll()
} operation: {
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 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(returning: element)
}
}
/// 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(element)
}
/// Send a finish to all awaiting iterations.
public func finish() {
finishAll()
}
/// Create an `Iterator` for iteration of an `AsyncChannel`
public func makeAsyncIterator() -> Iterator {
return Iterator(self)
}
}
@@ -1,120 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection`
/// type by testing if elements belong in the same group.
@inlinable
public func chunked<Collected: RangeReplaceableCollection>(into: Collected.Type, by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool) -> AsyncChunkedByGroupSequence<Self, Collected> where Collected.Element == Element {
AsyncChunkedByGroupSequence(self, grouping: belongInSameGroup)
}
/// Creates an asynchronous sequence that creates chunks by testing if elements belong in the same group.
@inlinable
public func chunked(by belongInSameGroup: @escaping @Sendable (Element, Element) -> Bool) -> AsyncChunkedByGroupSequence<Self, [Element]> {
chunked(into: [Element].self, by: belongInSameGroup)
}
}
/// An `AsyncSequence` that chunks by testing if two elements belong to the same group.
///
/// Group chunks are determined by passing two consecutive elements to a closure which tests
/// whether they are in the same group. When the `AsyncChunkedByGroupSequence` iterator
/// receives the first element from the base sequence, it will immediately be added to a group. When
/// it receives the second item, it tests whether the previous item and the current item belong to the
/// same group. If they are not in the same group, then the iterator emits the first item's group and a
/// new group is created containing the second item. Items declared to be in the same group
/// accumulate until a new group is declared, or the iterator finds the end of the base sequence.
/// When the base sequence terminates, the final group is emitted. If the base sequence throws an
/// error, `AsyncChunkedByGroupSequence` will rethrow that error immediately and discard
/// any current group.
///
/// let numbers = [10, 20, 30, 10, 40, 40, 10, 20].async
/// let chunks = numbers.chunked { $0 <= $1 }
/// for await numberChunk in chunks {
/// print(numberChunk)
/// }
/// // prints
/// // [10, 20, 30]
/// // [10, 40, 40]
/// // [10, 20]
public struct AsyncChunkedByGroupSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
public typealias Element = Collected
/// The iterator for a `AsyncChunkedByGroupSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base: Base.AsyncIterator
@usableFromInline
let grouping: @Sendable (Base.Element, Base.Element) -> Bool
@usableFromInline
init(base: Base.AsyncIterator, grouping: @escaping @Sendable (Base.Element, Base.Element) -> Bool) {
self.base = base
self.grouping = grouping
}
@usableFromInline
var hangingNext: Base.Element?
@inlinable
public mutating func next() async rethrows -> Collected? {
var firstOpt = hangingNext
if firstOpt == nil {
firstOpt = try await base.next()
} else {
hangingNext = nil
}
guard let first = firstOpt else {
return nil
}
var result: Collected = .init()
result.append(first)
var prev = first
while let next = try await base.next() {
if grouping(prev, next) {
result.append(next)
prev = next
} else {
hangingNext = next
break
}
}
return result
}
}
@usableFromInline
let base : Base
@usableFromInline
let grouping : @Sendable (Base.Element, Base.Element) -> Bool
@inlinable
init(_ base: Base, grouping: @escaping @Sendable (Base.Element, Base.Element) -> Bool) {
self.base = base
self.grouping = grouping
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base: base.makeAsyncIterator(), grouping: grouping)
}
}
extension AsyncChunkedByGroupSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
extension AsyncChunkedByGroupSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
@@ -1,101 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type on the uniqueness of a given subject.
@inlinable
public func chunked<Subject : Equatable, Collected: RangeReplaceableCollection>(into: Collected.Type, on projection: @escaping @Sendable (Element) -> Subject) -> AsyncChunkedOnProjectionSequence<Self, Subject, Collected> {
AsyncChunkedOnProjectionSequence(self, projection: projection)
}
/// Creates an asynchronous sequence that creates chunks on the uniqueness of a given subject.
@inlinable
public func chunked<Subject : Equatable>(on projection: @escaping @Sendable (Element) -> Subject) -> AsyncChunkedOnProjectionSequence<Self, Subject, [Element]> {
chunked(into: [Element].self, on: projection)
}
}
/// An `AsyncSequence` that chunks on a subject when it differs from the last element.
public struct AsyncChunkedOnProjectionSequence<Base: AsyncSequence, Subject: Equatable, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
public typealias Element = (Subject, Collected)
/// The iterator for a `AsyncChunkedOnProjectionSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base: Base.AsyncIterator
@usableFromInline
let projection: @Sendable (Base.Element) -> Subject
@usableFromInline
init(base: Base.AsyncIterator, projection: @escaping @Sendable (Base.Element) -> Subject) {
self.base = base
self.projection = projection
}
@usableFromInline
var hangingNext: (Subject, Base.Element)?
@inlinable
public mutating func next() async rethrows -> (Subject, Collected)? {
var firstOpt = hangingNext
if firstOpt == nil {
let nextOpt = try await base.next()
if let next = nextOpt {
firstOpt = (projection(next), next)
}
} else {
hangingNext = nil
}
guard let first = firstOpt else {
return nil
}
var result: Collected = .init()
result.append(first.1)
while let next = try await base.next() {
let subj = projection(next)
if subj == first.0 {
result.append(next)
} else {
hangingNext = (subj, next)
break
}
}
return (first.0, result)
}
}
@usableFromInline
let base : Base
@usableFromInline
let projection : @Sendable (Base.Element) -> Subject
@inlinable
init(_ base: Base, projection: @escaping @Sendable (Base.Element) -> Subject) {
self.base = base
self.projection = projection
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base: base.makeAsyncIterator(), projection: projection)
}
}
extension AsyncChunkedOnProjectionSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
extension AsyncChunkedOnProjectionSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable, Subject : Sendable { }
@@ -1,110 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type of a given count or when a signal `AsyncSequence` produces an element.
public func chunks<Signal, Collected: RangeReplaceableCollection>(ofCount count: Int, or signal: Signal, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal> where Collected.Element == Element {
AsyncChunksOfCountOrSignalSequence(self, count: count, signal: signal)
}
/// Creates an asynchronous sequence that creates chunks of a given count or when a signal `AsyncSequence` produces an element.
public func chunks<Signal>(ofCount count: Int, or signal: Signal) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal> {
chunks(ofCount: count, or: signal, into: [Element].self)
}
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type when a signal `AsyncSequence` produces an element.
public func chunked<Signal, Collected: RangeReplaceableCollection>(by signal: Signal, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, Signal> where Collected.Element == Element {
AsyncChunksOfCountOrSignalSequence(self, count: nil, signal: signal)
}
/// Creates an asynchronous sequence that creates chunks when a signal `AsyncSequence` produces an element.
public func chunked<Signal>(by signal: Signal) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], Signal> {
chunked(by: signal, into: [Element].self)
}
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type of a given count or when an `AsyncTimerSequence` fires.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func chunks<C: Clock, Collected: RangeReplaceableCollection>(ofCount count: Int, or timer: AsyncTimerSequence<C>, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>> where Collected.Element == Element {
AsyncChunksOfCountOrSignalSequence(self, count: count, signal: timer)
}
/// Creates an asynchronous sequence that creates chunks of a given count or when an `AsyncTimerSequence` fires.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func chunks<C: Clock>(ofCount count: Int, or timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
chunks(ofCount: count, or: timer, into: [Element].self)
}
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` type when an `AsyncTimerSequence` fires.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func chunked<C: Clock, Collected: RangeReplaceableCollection>(by timer: AsyncTimerSequence<C>, into: Collected.Type) -> AsyncChunksOfCountOrSignalSequence<Self, Collected, AsyncTimerSequence<C>> where Collected.Element == Element {
AsyncChunksOfCountOrSignalSequence(self, count: nil, signal: timer)
}
/// Creates an asynchronous sequence that creates chunks when an `AsyncTimerSequence` fires.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func chunked<C: Clock>(by timer: AsyncTimerSequence<C>) -> AsyncChunksOfCountOrSignalSequence<Self, [Element], AsyncTimerSequence<C>> {
chunked(by: timer, into: [Element].self)
}
}
/// An `AsyncSequence` that chunks elements into collected `RangeReplaceableCollection` instances by either count or a signal from another `AsyncSequence`.
public struct AsyncChunksOfCountOrSignalSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection, Signal: AsyncSequence>: AsyncSequence, Sendable where Collected.Element == Base.Element, Base: Sendable, Signal: Sendable, Base.AsyncIterator: Sendable, Signal.AsyncIterator: Sendable, Base.Element: Sendable, Signal.Element: Sendable {
public typealias Element = Collected
/// The iterator for a `AsyncChunksOfCountOrSignalSequence` instance.
public struct Iterator: AsyncIteratorProtocol, Sendable {
let count: Int?
var state: Merge2StateMachine<Base, Signal>
init(base: Base.AsyncIterator, count: Int?, signal: Signal.AsyncIterator) {
self.count = count
self.state = Merge2StateMachine(base, terminatesOnNil: true, signal)
}
public mutating func next() async rethrows -> Collected? {
var result : Collected?
while let next = try await state.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
}
}
}
return result
}
}
let base: Base
let signal: Signal
let count: Int?
init(_ base: Base, count: Int?, signal: Signal) {
if let count = count {
precondition(count > 0)
}
self.base = base
self.count = count
self.signal = signal
}
public func makeAsyncIterator() -> Iterator {
return Iterator(base: base.makeAsyncIterator(), count: count, signal: signal.makeAsyncIterator())
}
}
@@ -1,85 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Creates an asynchronous sequence that creates chunks of a given `RangeReplaceableCollection` of a given count.
@inlinable
public func chunks<Collected: RangeReplaceableCollection>(ofCount count: Int, into: Collected.Type) -> AsyncChunksOfCountSequence<Self, Collected> where Collected.Element == Element {
AsyncChunksOfCountSequence(self, count: count)
}
/// Creates an asynchronous sequence that creates chunks of a given count.
@inlinable
public func chunks(ofCount count: Int) -> AsyncChunksOfCountSequence<Self, [Element]> {
chunks(ofCount: count, into: [Element].self)
}
}
/// An `AsyncSequence` that chunks elements into `RangeReplaceableCollection` instances of at least a given count.
public struct AsyncChunksOfCountSequence<Base: AsyncSequence, Collected: RangeReplaceableCollection>: AsyncSequence where Collected.Element == Base.Element {
public typealias Element = Collected
/// The iterator for a `AsyncChunksOfCountSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base: Base.AsyncIterator
@usableFromInline
let count: Int
@usableFromInline
init(base: Base.AsyncIterator, count: Int) {
self.base = base
self.count = count
}
@inlinable
public mutating func next() async rethrows -> Collected? {
guard let first = try await base.next() else {
return nil
}
var result: Collected = .init()
result.append(first)
while let next = try await base.next() {
result.append(next)
if result.count == count {
break
}
}
return result
}
}
@usableFromInline
let base : Base
@usableFromInline
let count : Int
@inlinable
init(_ base: Base, count: Int) {
precondition(count > 0)
self.base = base
self.count = count
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base: base.makeAsyncIterator(), count: count)
}
}
extension AsyncChunksOfCountSequence : Sendable where Base : Sendable, Base.Element : Sendable { }
extension AsyncChunksOfCountSequence.Iterator : Sendable where Base.AsyncIterator : Sendable, Base.Element : Sendable { }
@@ -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())
}
}
@@ -1,72 +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 `AsyncSequence` that iterates over every non-nil element from the original
/// `AsyncSequence`.
@frozen
public struct AsyncCompactedSequence<Base: AsyncSequence, Element>: AsyncSequence
where Base.Element == Element? {
@usableFromInline
let base: Base
@inlinable
init(_ base: Base) {
self.base = base
}
/// The iterator for an `AsyncCompactedSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var base: Base.AsyncIterator
@inlinable
init(_ base: Base.AsyncIterator) {
self.base = base
}
@inlinable
public mutating func next() async rethrows -> Element? {
while let wrapped = try await base.next() {
guard let some = wrapped else { continue }
return some
}
return nil
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator())
}
}
extension AsyncSequence {
/// Returns a new `AsyncSequence` that iterates over every non-nil element from the
/// original `AsyncSequence`.
///
/// Produces the same result as `c.compactMap { $0 }`.
///
/// - Returns: An `AsyncSequence` where the element is the unwrapped original
/// element and iterates over every non-nil element from the original
/// `AsyncSequence`.
///
/// Complexity: O(1)
@inlinable
public func compacted<Unwrapped>() -> AsyncCompactedSequence<Self, Unwrapped>
where Element == Unwrapped? {
AsyncCompactedSequence(self)
}
}
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 { }
@@ -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 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> {
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> {
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.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 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
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)
}
}
@@ -1,115 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously-reduced result and
/// the next element in the receiving asynchronous sequence, which it returns.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
@inlinable
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async -> Result) -> AsyncExclusiveReductionsSequence<Self, Result> {
reductions(into: initial) { result, element in
result = await transform(result, element)
}
}
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously-reduced result and
/// the next element in the receiving asynchronous sequence, mutating the
/// previous result instead of returning a value.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
@inlinable
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async -> Void) -> AsyncExclusiveReductionsSequence<Self, Result> {
AsyncExclusiveReductionsSequence(self, initial: initial, transform: transform)
}
}
/// An asynchronous sequence of applying a transform to the element of an asynchronous sequence and the
/// previously transformed result.
@frozen
public struct AsyncExclusiveReductionsSequence<Base: AsyncSequence, Element> {
@usableFromInline
let base: Base
@usableFromInline
let initial: Element
@usableFromInline
let transform: @Sendable (inout Element, Base.Element) async -> Void
@inlinable
init(_ base: Base, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async -> Void) {
self.base = base
self.initial = initial
self.transform = transform
}
}
extension AsyncExclusiveReductionsSequence: AsyncSequence {
/// The iterator for an `AsyncExclusiveReductionsSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var iterator: Base.AsyncIterator
@usableFromInline
var current: Element?
@usableFromInline
let transform: @Sendable (inout Element, Base.Element) async -> Void
@inlinable
init(_ iterator: Base.AsyncIterator, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async -> Void) {
self.iterator = iterator
self.current = initial
self.transform = transform
}
@inlinable
public mutating func next() async rethrows -> Element? {
guard let result = current else { return nil }
let value = try await iterator.next()
if let value = value {
var result = result
await transform(&result, value)
current = result
return result
} else {
current = nil
return nil
}
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
}
}
extension AsyncExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
extension AsyncExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
@@ -1,88 +0,0 @@
extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given closure.
///
/// This can be seen as applying the reduce function to each element and
/// producing an asynchronous sequence consisting of the initial value followed
/// by these results.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].async.reductions(+)
/// print(await Array(runningTotal))
///
/// // prints [1, 3, 6, 10]
/// ```
///
/// - Parameter transform: A closure that combines the previously reduced
/// result and the next element in the receiving sequence, and returns
/// the result.
/// - Returns: An asynchronous sequence of the reduced elements.
@inlinable
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async -> Element
) -> AsyncInclusiveReductionsSequence<Self> {
AsyncInclusiveReductionsSequence(self, transform: transform)
}
}
/// An asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using a given closure.
@frozen
public struct AsyncInclusiveReductionsSequence<Base: AsyncSequence> {
@usableFromInline
let base: Base
@usableFromInline
let transform: @Sendable (Base.Element, Base.Element) async -> Base.Element
@inlinable
init(_ base: Base, transform: @Sendable @escaping (Base.Element, Base.Element) async -> Base.Element) {
self.base = base
self.transform = transform
}
}
extension AsyncInclusiveReductionsSequence: AsyncSequence {
public typealias Element = Base.Element
/// The iterator for an `AsyncInclusiveReductionsSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
internal var iterator: Base.AsyncIterator
@usableFromInline
internal var element: Base.Element?
@usableFromInline
internal let transform: @Sendable (Base.Element, Base.Element) async -> Base.Element
@inlinable
internal init(
_ iterator: Base.AsyncIterator,
transform: @Sendable @escaping (Base.Element, Base.Element) async -> Base.Element
) {
self.iterator = iterator
self.transform = transform
}
@inlinable
public mutating func next() async rethrows -> Base.Element? {
guard let previous = element else {
element = try await iterator.next()
return element
}
guard let next = try await iterator.next() else { return nil }
element = await transform(previous, next)
return element
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator(), transform: transform)
}
}
extension AsyncInclusiveReductionsSequence: Sendable where Base: Sendable { }
extension AsyncInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
@@ -1,104 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Returns an asynchronous sequence containing elements of this asynchronous sequence with
/// the given separator inserted in between each element.
///
/// Any value of the asynchronous sequence's element type can be used as the separator.
///
/// - Parameter separator: The value to insert in between each of this async
/// sequence’s elements.
/// - Returns: The interspersed asynchronous sequence of elements.
@inlinable
public func interspersed(with separator: Element) -> AsyncInterspersedSequence<Self> {
AsyncInterspersedSequence(self, separator: separator)
}
}
/// An asynchronous sequence that presents the elements of a base asynchronous sequence of
/// elements with a separator between each of those elements.
public struct AsyncInterspersedSequence<Base: AsyncSequence> {
@usableFromInline
internal let base: Base
@usableFromInline
internal let separator: Base.Element
@inlinable
internal init(_ base: Base, separator: Base.Element) {
self.base = base
self.separator = separator
}
}
extension AsyncInterspersedSequence: AsyncSequence {
public typealias Element = Base.Element
/// The iterator for an `AsyncInterspersedSequence` asynchronous sequence.
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
internal enum State {
case start
case element(Result<Base.Element, Error>)
case separator
}
@usableFromInline
internal var iterator: Base.AsyncIterator
@usableFromInline
internal let separator: Base.Element
@usableFromInline
internal var state = State.start
@inlinable
internal init(_ iterator: Base.AsyncIterator, separator: Base.Element) {
self.iterator = iterator
self.separator = separator
}
public mutating func next() async rethrows -> Base.Element? {
// After the start, the state flips between element and separator. Before
// returning a separator, a check is made for the next element as a
// separator is only returned between two elements. The next element is
// stored to allow it to be returned in the next iteration. However, if
// the checking the next element throws, the separator is emitted before
// rethrowing that error.
switch state {
case .start:
state = .separator
return try await iterator.next()
case .separator:
do {
guard let next = try await iterator.next() else { return nil }
state = .element(.success(next))
} catch {
state = .element(.failure(error))
}
return separator
case .element(let result):
state = .separator
return try result._rethrowGet()
}
}
}
@inlinable
public func makeAsyncIterator() -> AsyncInterspersedSequence<Base>.Iterator {
Iterator(base.makeAsyncIterator(), separator: separator)
}
}
extension AsyncInterspersedSequence: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
extension AsyncInterspersedSequence.Iterator: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
extension AsyncInterspersedSequence.Iterator.State: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
@@ -1,150 +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 where Element: AsyncSequence {
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements with a separator.
@inlinable
public func joined<Separator: AsyncSequence>(separator: Separator) -> AsyncJoinedBySeparatorSequence<Self, Separator> {
return AsyncJoinedBySeparatorSequence(self, separator: separator)
}
}
/// An `AsyncSequence` that concatenates `AsyncSequence` elements with a separator.
public struct AsyncJoinedBySeparatorSequence<Base: AsyncSequence, Separator: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence, Separator.Element == Base.Element.Element {
public typealias Element = Base.Element.Element
public typealias AsyncIterator = Iterator
/// The iterator for an `AsyncJoinedBySeparatorSequence` instance.
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
enum State {
@usableFromInline
enum SeparatorState {
case initial(Separator)
case partialAsync(Separator.AsyncIterator, ContiguousArray<Element>)
case cached(ContiguousArray<Element>)
case partialCached(ContiguousArray<Element>.Iterator, ContiguousArray<Element>)
@usableFromInline
func startSeparator() -> SeparatorState {
switch self {
case .initial(let separatorSequence):
return .partialAsync(separatorSequence.makeAsyncIterator(), [])
case .cached(let array):
return .partialCached(array.makeIterator(), array)
default:
fatalError("Invalid separator sequence state")
}
}
@usableFromInline
func next() async rethrows -> (Element?, SeparatorState) {
switch self {
case .partialAsync(var separatorIterator, var cache):
guard let next = try await separatorIterator.next() else {
return (nil, .cached(cache))
}
cache.append(next)
return (next, .partialAsync(separatorIterator, cache))
case .partialCached(var cacheIterator, let cache):
guard let next = cacheIterator.next() else {
return (nil, .cached(cache))
}
return (next, .partialCached(cacheIterator, cache))
default:
fatalError("Invalid separator sequence state")
}
}
}
case initial(Base.AsyncIterator, Separator)
case sequence(Base.AsyncIterator, Base.Element.AsyncIterator, SeparatorState)
case separator(Base.AsyncIterator, SeparatorState, Base.Element)
case terminal
}
@usableFromInline
var state: State
@inlinable
init(_ iterator: Base.AsyncIterator, separator: Separator) {
state = .initial(iterator, separator)
}
@inlinable
public mutating func next() async rethrows -> Base.Element.Element? {
do {
switch state {
case .terminal:
return nil
case .initial(var outerIterator, let separator):
guard let innerSequence = try await outerIterator.next() else {
state = .terminal
return nil
}
let innerIterator = innerSequence.makeAsyncIterator()
state = .sequence(outerIterator, innerIterator, .initial(separator))
return try await next()
case .sequence(var outerIterator, var innerIterator, let separatorState):
if let item = try await innerIterator.next() {
state = .sequence(outerIterator, innerIterator, separatorState)
return item
}
guard let nextInner = try await outerIterator.next() else {
state = .terminal
return nil
}
state = .separator(outerIterator, separatorState.startSeparator(), nextInner)
return try await next()
case .separator(let iterator, let separatorState, let nextBase):
let (itemOpt, newSepState) = try await separatorState.next()
guard let item = itemOpt else {
state = .sequence(iterator, nextBase.makeAsyncIterator(), newSepState)
return try await next()
}
state = .separator(iterator, newSepState, nextBase)
return item
}
} catch {
state = .terminal
throw error
}
}
}
@usableFromInline
let base: Base
@usableFromInline
let separator: Separator
@inlinable
init(_ base: Base, separator: Separator) {
self.base = base
self.separator = separator
}
@inlinable
public func makeAsyncIterator() -> Iterator {
return Iterator(base.makeAsyncIterator(), separator: separator)
}
}
extension AsyncJoinedBySeparatorSequence: Sendable
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, 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 { }
@@ -1,98 +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 where Element: AsyncSequence {
/// Concatenate an `AsyncSequence` of `AsyncSequence` elements
@inlinable
public func joined() -> AsyncJoinedSequence<Self> {
return AsyncJoinedSequence(self)
}
}
/// An `AsyncSequence` that concatenates`AsyncSequence` elements
@frozen
public struct AsyncJoinedSequence<Base: AsyncSequence>: AsyncSequence where Base.Element: AsyncSequence {
public typealias Element = Base.Element.Element
public typealias AsyncIterator = Iterator
/// The iterator for an `AsyncJoinedSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
enum State {
case initial(Base.AsyncIterator)
case sequence(Base.AsyncIterator, Base.Element.AsyncIterator)
case terminal
}
@usableFromInline
var state: State
@inlinable
init(_ iterator: Base.AsyncIterator) {
state = .initial(iterator)
}
@inlinable
public mutating func next() async rethrows -> Base.Element.Element? {
do {
switch state {
case .terminal:
return nil
case .initial(var outerIterator):
guard let innerSequence = try await outerIterator.next() else {
state = .terminal
return nil
}
let innerIterator = innerSequence.makeAsyncIterator()
state = .sequence(outerIterator, innerIterator)
return try await next()
case .sequence(var outerIterator, var innerIterator):
if let item = try await innerIterator.next() {
state = .sequence(outerIterator, innerIterator)
return item
}
guard let nextInner = try await outerIterator.next() else {
state = .terminal
return nil
}
state = .sequence(outerIterator, nextInner.makeAsyncIterator())
return try await next()
}
} catch {
state = .terminal
throw error
}
}
}
@usableFromInline
let base: Base
@inlinable
init(_ base: Base) {
self.base = base
}
@inlinable
public func makeAsyncIterator() -> Iterator {
return Iterator(base.makeAsyncIterator())
}
}
extension AsyncJoinedSequence: Sendable
where Base: Sendable, Base.Element: Sendable, Base.Element.Element: Sendable, 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 { }
@@ -1,70 +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 Sequence {
/// An asynchronous sequence containing the same elements as this sequence,
/// but on which operations, such as `map` and `filter`, are
/// implemented asynchronously.
@inlinable
public var async: AsyncLazySequence<Self> {
AsyncLazySequence(self)
}
}
/// An asynchronous sequence composed from a synchronous sequence.
///
/// Asynchronous lazy sequences can be used to interface existing or pre-calculated
/// data to interoperate with other asynchronous sequences and algorithms based on
/// asynchronous sequences.
///
/// This functions similarly to `LazySequence` by accessing elements sequentially
/// in the iterator's `next()` method.
@frozen
public struct AsyncLazySequence<Base: Sequence>: AsyncSequence {
public typealias Element = Base.Element
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var iterator: Base.Iterator?
@usableFromInline
init(_ iterator: Base.Iterator) {
self.iterator = iterator
}
@inlinable
public mutating func next() async -> Base.Element? {
if !Task.isCancelled, let value = iterator?.next() {
return value
} else {
iterator = nil
return nil
}
}
}
@usableFromInline
let base: Base
@usableFromInline
init(_ base: Base) {
self.base = base
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeIterator())
}
}
extension AsyncLazySequence: Sendable where Base: Sendable { }
extension AsyncLazySequence.Iterator: Sendable where Base.Iterator: 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 underlying 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 underlying 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 don't 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())
}
}
@@ -1,148 +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 where Element: Equatable {
/// Creates an asynchronous sequence that omits repeated elements.
public func removeDuplicates() -> AsyncRemoveDuplicatesSequence<Self> {
AsyncRemoveDuplicatesSequence(self) { lhs, rhs in
lhs == rhs
}
}
}
extension AsyncSequence {
/// Creates an asynchronous sequence that omits repeated elements by testing them with a predicate.
public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async -> Bool) -> AsyncRemoveDuplicatesSequence<Self> {
return AsyncRemoveDuplicatesSequence(self, predicate: predicate)
}
/// Creates an asynchronous sequence that omits repeated elements by testing them with an error-throwing predicate.
public func removeDuplicates(by predicate: @escaping @Sendable (Element, Element) async throws -> Bool) -> AsyncThrowingRemoveDuplicatesSequence<Self> {
return AsyncThrowingRemoveDuplicatesSequence(self, predicate: predicate)
}
}
/// An asynchronous sequence that omits repeated elements by testing them with a predicate.
public struct AsyncRemoveDuplicatesSequence<Base: AsyncSequence>: AsyncSequence {
public typealias Element = Base.Element
/// The iterator for an `AsyncRemoveDuplicatesSequence` instance.
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var iterator: Base.AsyncIterator
@usableFromInline
let predicate: @Sendable (Element, Element) async -> Bool
@usableFromInline
var last: Element?
@inlinable
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
self.iterator = iterator
self.predicate = predicate
}
@inlinable
public mutating func next() async rethrows -> Element? {
guard let last = last else {
last = try await iterator.next()
return last
}
while let element = try await iterator.next() {
if await !predicate(last, element) {
self.last = element
return element
}
}
return nil
}
}
@usableFromInline
let base: Base
@usableFromInline
let predicate: @Sendable (Element, Element) async -> Bool
init(_ base: Base, predicate: @escaping @Sendable (Element, Element) async -> Bool) {
self.base = base
self.predicate = predicate
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
}
}
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
/// The iterator for an `AsyncThrowingRemoveDuplicatesSequence` instance.
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var iterator: Base.AsyncIterator
@usableFromInline
let predicate: @Sendable (Element, Element) async throws -> Bool
@usableFromInline
var last: Element?
@inlinable
init(iterator: Base.AsyncIterator, predicate: @escaping @Sendable (Element, Element) async throws -> Bool) {
self.iterator = iterator
self.predicate = predicate
}
@inlinable
public mutating func next() async throws -> Element? {
guard let last = last else {
last = try await iterator.next()
return last
}
while let element = try await iterator.next() {
if try await !predicate(last, element) {
self.last = element
return element
}
}
return nil
}
}
@usableFromInline
let base: Base
@usableFromInline
let predicate: @Sendable (Element, Element) async throws -> Bool
init(_ base: Base, predicate: @escaping @Sendable (Element, Element) async throws -> Bool) {
self.base = base
self.predicate = predicate
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(iterator: base.makeAsyncIterator(), predicate: predicate)
}
}
extension AsyncThrowingRemoveDuplicatesSequence: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
extension AsyncThrowingRemoveDuplicatesSequence.Iterator: Sendable where Base: Sendable, Base.Element: Sendable, Base.AsyncIterator: Sendable { }
@@ -1,107 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2021 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func throttle<C: Clock, Reduced>(for interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> AsyncThrottleSequence<Self, C, Reduced> {
AsyncThrottleSequence(self, interval: interval, clock: clock, reducing: reducing)
}
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func throttle<Reduced>(for interval: Duration, reducing: @Sendable @escaping (Reduced?, Element) async -> Reduced) -> AsyncThrottleSequence<Self, ContinuousClock, Reduced> {
throttle(for: interval, clock: .continuous, reducing: reducing)
}
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func throttle<C: Clock>(for interval: C.Instant.Duration, clock: C, latest: Bool = true) -> AsyncThrottleSequence<Self, C, Element> {
throttle(for: interval, clock: clock) { previous, element in
if latest {
return element
} else {
return previous ?? element
}
}
}
/// Create a rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public func throttle(for interval: Duration, latest: Bool = true) -> AsyncThrottleSequence<Self, ContinuousClock, Element> {
throttle(for: interval, clock: .continuous, latest: latest)
}
}
/// A rate-limited `AsyncSequence` by emitting values at most every specified interval.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public struct AsyncThrottleSequence<Base: AsyncSequence, C: Clock, Reduced> {
let base: Base
let interval: C.Instant.Duration
let clock: C
let reducing: @Sendable (Reduced?, Base.Element) async -> Reduced
init(_ base: Base, interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Base.Element) async -> Reduced) {
self.base = base
self.interval = interval
self.clock = clock
self.reducing = reducing
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncThrottleSequence: AsyncSequence {
public typealias Element = Reduced
/// The iterator for an `AsyncThrottleSequence` instance.
public struct Iterator: AsyncIteratorProtocol {
var base: Base.AsyncIterator
var last: C.Instant?
let interval: C.Instant.Duration
let clock: C
let reducing: @Sendable (Reduced?, Base.Element) async -> Reduced
init(_ base: Base.AsyncIterator, interval: C.Instant.Duration, clock: C, reducing: @Sendable @escaping (Reduced?, Base.Element) async -> Reduced) {
self.base = base
self.interval = interval
self.clock = clock
self.reducing = reducing
}
public mutating func next() async rethrows -> Reduced? {
var reduced: Reduced?
let start = last ?? clock.now
repeat {
guard let element = try await base.next() else {
return nil
}
let reduction = await reducing(reduced, element)
let now = clock.now
if start.duration(to: now) >= interval || last == nil {
last = now
return reduction
} else {
reduced = reduction
}
} while true
}
}
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator(), interval: interval, clock: clock, reducing: reducing)
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncThrottleSequence: Sendable where Base: Sendable, Element: Sendable { }
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncThrottleSequence.Iterator: Sendable where Base.AsyncIterator: Sendable { }
@@ -1,251 +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
if awaiting.isEmpty {
self = .idle
} else {
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
var terminal = false
state.withCriticalRegion { state -> UnsafeResumption<UnsafeContinuation<Element?, Error>?, Never>? in
if state.terminal {
terminal = true
return nil
}
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
}
if nexts.isEmpty {
state.emission = .idle
} else {
state.emission = .awaiting(nexts)
}
return nil
}
}?.resume()
if cancelled || terminal {
continuation.resume(returning: nil)
}
}
}
func finishAll() {
let (sends, nexts) = state.withCriticalRegion { state -> ([UnsafeContinuation<UnsafeContinuation<Element?, Error>?, Never>], Set<Awaiting>) in
if state.terminal {
return ([], [])
}
state.terminal = true
switch state.emission {
case .idle:
return ([], [])
case .pending(let nexts):
state.emission = .idle
return (nexts, [])
case .awaiting(let nexts):
state.emission = .idle
return ([], nexts)
}
}
for send in sends {
send.resume(returning: nil)
}
for next in nexts {
next.continuation?.resume(returning: nil)
}
}
func _send(_ result: Result<Element, Error>) async {
await withTaskCancellationHandler {
finishAll()
} operation: {
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)
}
if case .failure = result {
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.map { $0 as Element? })
}
}
/// 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 all awaiting iterations.
public func finish() {
finishAll()
}
public func makeAsyncIterator() -> Iterator {
return Iterator(self)
}
}
@@ -1,122 +0,0 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given error-throwing closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving asynchronous sequence and returns
/// the result. If the closure throws an error, the sequence throws.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
@inlinable
public func reductions<Result>(_ initial: Result, _ transform: @Sendable @escaping (Result, Element) async throws -> Result) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
reductions(into: initial) { result, element in
result = try await transform(result, element)
}
}
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given error-throwing closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
///
/// - Parameters:
/// - initial: The value to use as the initial value.
/// - transform: A closure that combines the previously reduced result and
/// the next element in the receiving asynchronous sequence, mutating the
/// previous result instead of returning a value. If the closure throws an
/// error, the sequence throws.
/// - Returns: An asynchronous sequence of the initial value followed by the reduced
/// elements.
@inlinable
public func reductions<Result>(into initial: Result, _ transform: @Sendable @escaping (inout Result, Element) async throws -> Void) -> AsyncThrowingExclusiveReductionsSequence<Self, Result> {
AsyncThrowingExclusiveReductionsSequence(self, initial: initial, transform: transform)
}
}
/// An asynchronous sequence of applying an error-throwing transform to the element of
/// an asynchronous sequence and the previously transformed result.
@frozen
public struct AsyncThrowingExclusiveReductionsSequence<Base: AsyncSequence, Element> {
@usableFromInline
let base: Base
@usableFromInline
let initial: Element
@usableFromInline
let transform: @Sendable (inout Element, Base.Element) async throws -> Void
@inlinable
init(_ base: Base, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async throws -> Void) {
self.base = base
self.initial = initial
self.transform = transform
}
}
extension AsyncThrowingExclusiveReductionsSequence: AsyncSequence {
/// The iterator for an `AsyncThrowingExclusiveReductionsSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
var iterator: Base.AsyncIterator
@usableFromInline
var current: Element?
@usableFromInline
let transform: @Sendable (inout Element, Base.Element) async throws -> Void
@inlinable
init(_ iterator: Base.AsyncIterator, initial: Element, transform: @Sendable @escaping (inout Element, Base.Element) async throws -> Void) {
self.iterator = iterator
self.current = initial
self.transform = transform
}
@inlinable
public mutating func next() async throws -> Element? {
guard let result = current else { return nil }
let value = try await iterator.next()
if let value = value {
var result = result
do {
try await transform(&result, value)
current = result
return result
} catch {
current = nil
throw error
}
} else {
current = nil
return nil
}
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator(), initial: initial, transform: transform)
}
}
extension AsyncThrowingExclusiveReductionsSequence: Sendable where Base: Sendable, Element: Sendable { }
extension AsyncThrowingExclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Element: Sendable { }
@@ -1,92 +0,0 @@
extension AsyncSequence {
/// Returns an asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using the given error-throwing closure.
///
/// This can be seen as applying the reduce function to each element and
/// providing the initial value followed by these results as an asynchronous sequence.
///
/// ```
/// let runningTotal = [1, 2, 3, 4].async.reductions(+)
/// print(await Array(runningTotal))
///
/// // prints [1, 3, 6, 10]
/// ```
///
/// - Parameter transform: A closure that combines the previously reduced
/// result and the next element in the receiving sequence. If the closure
/// throws an error, the sequence throws.
/// - Returns: An asynchronous sequence of the reduced elements.
@inlinable
public func reductions(
_ transform: @Sendable @escaping (Element, Element) async throws -> Element
) -> AsyncThrowingInclusiveReductionsSequence<Self> {
AsyncThrowingInclusiveReductionsSequence(self, transform: transform)
}
}
/// An asynchronous sequence containing the accumulated results of combining the
/// elements of the asynchronous sequence using a given error-throwing closure.
@frozen
public struct AsyncThrowingInclusiveReductionsSequence<Base: AsyncSequence> {
@usableFromInline
let base: Base
@usableFromInline
let transform: @Sendable (Base.Element, Base.Element) async throws -> Base.Element
@inlinable
init(_ base: Base, transform: @Sendable @escaping (Base.Element, Base.Element) async throws -> Base.Element) {
self.base = base
self.transform = transform
}
}
extension AsyncThrowingInclusiveReductionsSequence: AsyncSequence {
public typealias Element = Base.Element
/// The iterator for an `AsyncThrowingInclusiveReductionsSequence` instance.
@frozen
public struct Iterator: AsyncIteratorProtocol {
@usableFromInline
internal var iterator: Base.AsyncIterator?
@usableFromInline
internal var element: Base.Element?
@usableFromInline
internal let transform: @Sendable (Base.Element, Base.Element) async throws -> Base.Element
@inlinable
internal init(
_ iterator: Base.AsyncIterator,
transform: @Sendable @escaping (Base.Element, Base.Element) async throws -> Base.Element
) {
self.iterator = iterator
self.transform = transform
}
@inlinable
public mutating func next() async throws -> Base.Element? {
guard let previous = element else {
element = try await iterator?.next()
return element
}
guard let next = try await iterator?.next() else { return nil }
do {
element = try await transform(previous, next)
} catch {
iterator = nil
throw error
}
return element
}
}
@inlinable
public func makeAsyncIterator() -> Iterator {
Iterator(base.makeAsyncIterator(), transform: transform)
}
}
extension AsyncThrowingInclusiveReductionsSequence: Sendable where Base: Sendable { }
extension AsyncThrowingInclusiveReductionsSequence.Iterator: Sendable where Base.AsyncIterator: Sendable, Base.Element: Sendable { }
@@ -1,94 +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 `AsyncSequence` that produces elements at regular intervals.
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public struct AsyncTimerSequence<C: Clock>: AsyncSequence {
public typealias Element = C.Instant
/// The iterator for an `AsyncTimerSequence` instance.
public struct Iterator: AsyncIteratorProtocol {
var clock: C?
let interval: C.Instant.Duration
let tolerance: C.Instant.Duration?
var last: C.Instant?
init(interval: C.Instant.Duration, tolerance: C.Instant.Duration?, clock: C) {
self.clock = clock
self.interval = interval
self.tolerance = tolerance
}
func nextDeadline(_ clock: C) -> C.Instant {
let now = clock.now
let last = self.last ?? now
let next = last.advanced(by: interval)
if next < now {
return last.advanced(by: interval * Int(((next.duration(to: now)) / interval).rounded(.up)))
} else {
return next
}
}
public mutating func next() async -> C.Instant? {
guard let clock = clock else {
return nil
}
let next = nextDeadline(clock)
do {
try await clock.sleep(until: next, tolerance: tolerance)
} catch {
self.clock = nil
return nil
}
let now = clock.now
last = next
return now
}
}
let clock: C
let interval: C.Instant.Duration
let tolerance: C.Instant.Duration?
/// Create an `AsyncTimerSequence` with a given repeating interval.
public init(interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) {
self.clock = clock
self.interval = interval
self.tolerance = tolerance
}
public func makeAsyncIterator() -> Iterator {
Iterator(interval: interval, tolerance: tolerance, clock: clock)
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncTimerSequence {
/// Create an `AsyncTimerSequence` with a given repeating interval.
public static func repeating(every interval: C.Instant.Duration, tolerance: C.Instant.Duration? = nil, clock: C) -> AsyncTimerSequence<C> {
return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: clock)
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncTimerSequence where C == SuspendingClock {
/// Create an `AsyncTimerSequence` with a given repeating interval.
public static func repeating(every interval: Duration, tolerance: Duration? = nil) -> AsyncTimerSequence<SuspendingClock> {
return AsyncTimerSequence(interval: interval, tolerance: tolerance, clock: SuspendingClock())
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncTimerSequence: Sendable { }
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
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())
}
}
-81
View File
@@ -1,81 +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 Dictionary {
/// Creates a new dictionary from the key-value pairs in the given asynchronous sequence.
///
/// You use this initializer to create a dictionary when you have an asynchronous sequence
/// of key-value tuples with unique keys. Passing an asynchronous sequence with duplicate
/// keys to this initializer results in a runtime error. If your
/// asynchronous sequence might have duplicate keys, use the
/// `Dictionary(_:uniquingKeysWith:)` initializer instead.
///
/// - Parameter keysAndValues: An asynchronous sequence of key-value pairs to use for
/// the new dictionary. Every key in `keysAndValues` must be unique.
/// - Returns: A new dictionary initialized with the elements of
/// `keysAndValues`.
/// - Precondition: The sequence must not have duplicate keys.
@inlinable
public init<S: AsyncSequence>(uniqueKeysWithValues keysAndValues: S) async rethrows where S.Element == (Key, Value) {
self.init(uniqueKeysWithValues: try await Array(keysAndValues))
}
/// Creates a new dictionary from the key-value pairs in the given asynchronous sequence,
/// using a combining closure to determine the value for any duplicate keys.
///
/// You use this initializer to create a dictionary when you have a sequence
/// of key-value tuples that might have duplicate keys. As the dictionary is
/// built, the initializer calls the `combine` closure with the current and
/// new values for any duplicate keys. Pass a closure as `combine` that
/// returns the value to use in the resulting dictionary: The closure can
/// choose between the two values, combine them to produce a new value, or
/// even throw an error.
///
/// - Parameters:
/// - keysAndValues: An asynchronous sequence of key-value pairs to use for the new
/// dictionary.
/// - combine: A closure that is called with the values for any duplicate
/// keys that are encountered. The closure returns the desired value for
/// the final dictionary, or throws an error if building the dictionary
/// can't proceed.
@inlinable
public init<S: AsyncSequence>(_ keysAndValues: S, uniquingKeysWith combine: (Value, Value) async throws -> Value) async rethrows where S.Element == (Key, Value) {
self.init()
for try await (key, value) in keysAndValues {
if let existing = self[key] {
self[key] = try await combine(existing, value)
} else {
self[key] = value
}
}
}
/// Creates a new dictionary whose keys are the groupings returned by the
/// given closure and whose values are arrays of the elements that returned
/// each key.
///
/// The arrays in the "values" position of the new dictionary each contain at
/// least one element, with the elements in the same order as the source
/// asynchronous sequence.
///
/// - Parameters:
/// - values: An asynchronous sequence of values to group into a dictionary.
/// - keyForValue: A closure that returns a key for each element in
/// `values`.
@inlinable
public init<S: AsyncSequence>(grouping values: S, by keyForValue: (S.Element) async throws -> Key) async rethrows where Value == [S.Element] {
self.init()
for try await value in values {
let key = try await keyForValue(value)
self[key, default: []].append(value)
}
}
}
-117
View File
@@ -1,117 +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
//
//===----------------------------------------------------------------------===//
#if canImport(Darwin)
@_implementationOnly import Darwin
#elseif canImport(Glibc)
@_implementationOnly import Glibc
#elseif canImport(WinSDK)
@_implementationOnly import WinSDK
#endif
internal struct Lock {
#if canImport(Darwin)
typealias Primitive = os_unfair_lock
#elseif canImport(Glibc)
typealias Primitive = pthread_mutex_t
#elseif canImport(WinSDK)
typealias Primitive = SRWLOCK
#endif
typealias PlatformLock = UnsafeMutablePointer<Primitive>
let platformLock: PlatformLock
private init(_ platformLock: PlatformLock) {
self.platformLock = platformLock
}
fileprivate static func initialize(_ platformLock: PlatformLock) {
#if canImport(Darwin)
platformLock.initialize(to: os_unfair_lock())
#elseif canImport(Glibc)
pthread_mutex_init(platformLock, nil)
#elseif canImport(WinSDK)
InitializeSRWLock(platformLock)
#endif
}
fileprivate static func deinitialize(_ platformLock: PlatformLock) {
#if canImport(Glibc)
pthread_mutex_destroy(platformLock)
#endif
platformLock.deinitialize(count: 1)
}
fileprivate static func lock(_ platformLock: PlatformLock) {
#if canImport(Darwin)
os_unfair_lock_lock(platformLock)
#elseif canImport(Glibc)
pthread_mutex_lock(platformLock)
#elseif canImport(WinSDK)
AcquireSRWLockExclusive(platformLock)
#endif
}
fileprivate static func unlock(_ platformLock: PlatformLock) {
#if canImport(Darwin)
os_unfair_lock_unlock(platformLock)
#elseif canImport(Glibc)
pthread_mutex_unlock(platformLock)
#elseif canImport(WinSDK)
ReleaseSRWLockExclusive(platformLock)
#endif
}
static func allocate() -> Lock {
let platformLock = PlatformLock.allocate(capacity: 1)
initialize(platformLock)
return Lock(platformLock)
}
func deinitialize() {
Lock.deinitialize(platformLock)
}
func lock() {
Lock.lock(platformLock)
}
func unlock() {
Lock.unlock(platformLock)
}
}
struct ManagedCriticalState<State> {
private final class LockedBuffer: ManagedBuffer<State, Lock.Primitive> {
deinit {
withUnsafeMutablePointerToElements { Lock.deinitialize($0) }
}
}
private let buffer: ManagedBuffer<State, Lock.Primitive>
init(_ initial: State) {
buffer = LockedBuffer.create(minimumCapacity: 1) { buffer in
buffer.withUnsafeMutablePointerToElements { Lock.initialize($0) }
return initial
}
}
func withCriticalRegion<R>(_ critical: (inout State) throws -> R) rethrows -> R {
try buffer.withUnsafeMutablePointers { header, lock in
Lock.lock(lock)
defer { Lock.unlock(lock) }
return try critical(&header.pointee)
}
}
}
extension ManagedCriticalState: @unchecked Sendable where State: Sendable { }
@@ -1,47 +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
//
//===----------------------------------------------------------------------===//
enum PartialIteration<Iterator: AsyncIteratorProtocol, Partial: Sendable>: CustomStringConvertible {
case idle(Iterator)
case pending(Task<Partial, Never>)
case terminal
var description: String {
switch self {
case .idle: return "idle"
case .pending: return "pending"
case .terminal: return "terminal"
}
}
mutating func resolve(_ result: Result<Iterator.Element?, Error>, _ iterator: Iterator) rethrows -> Iterator.Element? {
do {
guard let value = try result._rethrowGet() else {
self = .terminal
return nil
}
self = .idle(iterator)
return value
} catch {
self = .terminal
throw error
}
}
mutating func cancel() {
if case .pending(let task) = self {
task.cancel()
}
self = .terminal
}
}
extension PartialIteration: Sendable where Iterator: Sendable, Iterator.Element: Sendable { }
@@ -1,23 +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 RangeReplaceableCollection {
/// Creates a new instance of a collection containing the elements of an asynchronous sequence.
///
/// - Parameter source: The asynchronous sequence of elements for the new collection.
@inlinable
public init<Source: AsyncSequence>(_ source: Source) async rethrows where Source.Element == Element {
self.init()
for try await item in source {
append(item)
}
}
}
-35
View File
@@ -1,35 +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
//
//===----------------------------------------------------------------------===//
// This is a hack around the fact that we don't have generic effects
// alternatively in the use cases we would want `rethrows(unsafe)`
// or something like that to avoid this nifty hack...
@rethrows
internal protocol _ErrorMechanism {
associatedtype Output
func get() throws -> Output
}
extension _ErrorMechanism {
// rethrow an error only in the cases where it is known to be reachable
internal func _rethrowError() rethrows -> Never {
_ = try _rethrowGet()
fatalError("materialized error without being in a throwing context")
}
internal func _rethrowGet() rethrows -> Output {
return try get()
}
}
extension Result: _ErrorMechanism { }
-25
View File
@@ -1,25 +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 SetAlgebra {
/// Creates a new set from an asynchronous sequence of items.
///
/// Use this initializer to create a new set from an asynchronous sequence
///
/// - Parameter source: The elements to use as members of the new set.
@inlinable
public init<Source: AsyncSequence>(_ source: Source) async rethrows where Source.Element == Element {
self.init()
for try await item in source {
insert(item)
}
}
}
-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 { }
@@ -1,76 +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
//
//===----------------------------------------------------------------------===//
import XCTest
import AsyncAlgorithms
import AsyncSequenceValidation
extension XCTestCase {
func recordFailure(_ description: String, system: Bool = false, at location: AsyncSequenceValidation.SourceLocation) {
#if canImport(Darwin)
let context = XCTSourceCodeContext(location: XCTSourceCodeLocation(filePath: location.file.description, lineNumber: Int(location.line)))
let issue = XCTIssue(type: system ? .system : .assertionFailure, compactDescription: description, detailedDescription: nil, sourceCodeContext: context, associatedError: nil, attachments: [])
record(issue)
#else
XCTFail(description, file: location.file, line: location.line)
#endif
}
func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, expectedFailures: Set<String>, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
var expectations = expectedFailures
var result: AsyncSequenceValidationDiagram.ExpectationResult?
var failures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
let baseLoc = AsyncSequenceValidation.SourceLocation(file: file, line: line)
var accountedFailures = [AsyncSequenceValidationDiagram.ExpectationFailure]()
do {
(result, failures) = try AsyncSequenceValidationDiagram.test(theme: theme, build)
for failure in failures {
if expectations.remove(failure.description) == nil {
recordFailure(failure.description, at: failure.specification?.location ?? baseLoc)
} else {
accountedFailures.append(failure)
}
}
} catch {
if expectations.remove("\(error)") == nil {
recordFailure("\(error)", system: true, at: (error as? SourceFailure)?.location ?? baseLoc)
}
}
// If no failures were expected and the result reconstitues to something different
// than what was expected, dump that out as a failure for easier diagnostics, this
// likely should be done via attachments but that does not display inline code
// nicely. Ideally we would want to have this display as a runtime warning but those
// do not have source line attribution; for now XCTFail is good enough.
if let result = result, expectedFailures.count == 0 {
let expected = result.reconstituteExpected(theme: theme)
let actual = result.reconstituteActual(theme: theme)
if expected != actual {
XCTFail("Validation failure:\nExpected:\n\(expected)\nActual:\n\(actual)", file: file, line: line)
}
}
// any remaining expectations are failures that were expected but did not happen
for expectation in expectations {
XCTFail("Expected failure: \(expectation) did not occur.", file: file, line: line)
}
}
func validate<Test: AsyncSequenceValidationTest>(expectedFailures: Set<String>, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
validate(theme: .ascii, expectedFailures: expectedFailures, build, file: file, line: line)
}
public func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, @AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
validate(theme: theme, expectedFailures: [], build, file: file, line: line)
}
public func validate<Test: AsyncSequenceValidationTest>(@AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line) {
validate(theme: .ascii, expectedFailures: [], build, file: file, line: line)
}
}
@@ -1,14 +0,0 @@
# ``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>
@@ -1,343 +0,0 @@
# AsyncSequence Validation
* Author(s): [Philippe Hausler](https://github.com/phausler)
* Implementation: [AsyncSequenceValidation](https://github.com/apple/swift-async-algorithms/tree/main/Sources/AsyncSequenceValidation)
## Introduction
Testing is a critical area of focus for any package to make it robust, catch bugs, and explain the expected behaviors in a documented manner. Testing things that are asynchronous can be difficult, testing things that are asynchronous multiple times can be even more difficult.
Types that implement `AsyncSequence` can often be described in deterministic actions given particular inputs. For the inputs, the events can be described as a discrete set: values, errors being thrown, the terminal state of returning a `nil` value from the iterator, or advancing in time and not doing anything. Likewise, the expected output has a discrete set of events: values, errors being caught, the terminal state of receiving a `nil` value from the iterator, or advancing in time and not doing anything.
## Proposed Solution
By restricting the domain space of values to `String` we can describe the events as a domain specific language, and with monospaced characters that domain space can be used to show values over time for both the input to an `AsyncSequence` but also the expected output.
```swift
validate {
"a--b--c---|"
$0.inputs[0].map { $0.capitalized }
"A--B--C---|"
}
```
This syntax can be accomplished with a confluence of utilizing some of the advanced features of XCTest, the concurrency runtime, and result builders. The diagram as listed flows as if each event that would propagate is an event flowing along a column but also it shows the expression progressed over time; describing each event.
By utilizing result builders, this same function can accommodate more than one input specification for testing things like `merge`.
```swift
validate {
"a-c--f-|"
"-b-de-g|"
merge($0.inputs[0], $0.inputs[1])
"abcdefg|"
}
```
Normally testing a function like `merge` would result in either limited expectations or be stochastic in nature. Those approaches are to account for the potential ordering not being deterministic. Taking the approach of having explicit ordering of time defined by the diagram allows for the test to be predictable. That determinism is sourced directly from the input sequences and the expected correlative output sequence. In short, the syntax of the test inputs and expectations make the execution reliable.
The syntax is trivially parsable (and consequently customizable). By default, the events require only a limited subset of characters for control; such as the advancing in time `-`, or the termination of a sequence by returning nil `|`. However some events may produce strings greater than just one character, other events may happen at the same time, and there is also the cancellation event. This all culminates into a test theme definition of:
| Symbol | Description | Example |
| ------- | ----------------- | ---------- |
| `-` | Advance time | `"a--b--"` |
| `|` | Termination | `"ab-|"` |
| `^` | Thrown error | `"ab-^"` |
| `;` | Cancellation | `"ab;-"` |
| `[` | Begin group | `"[ab]-"` |
| `]` | End group | `"[ab]-"` |
| `'` | Begin/End Value | `"'foo'-"` |
| `,` | Delay next | `",[a,]b"` |
Because some events may take up more than one character and the alignment is important to the visual progression of events, spaces are not counted as part of the parsed events. A space means that no time is advanced and not event is produced or expected. This means that the string `"a - -b- -"` is equivalent to `"a--b--"`.
Defining a custom theme can then be trivial, since the list of expected interactions are well known. For example an emoji based diagram can be easily constructed:
```swift
struct EmojiTokens: AsyncSequenceValidationTheme {
func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token {
switch character {
case "➖": return .step
case "❗️": return .error
case "❌": return .finish
case "➡️": return .beginValue
case "⬅️": return .endValue
case "⏳": return .delayNext
case " ": return .skip
default: return .value(String(character))
}
}
}
validate(theme: EmojiTokens()) {
"➖🔴➖🟠➖🟡➖🟢➖❌"
$0.inputs[0]
"➖🔴➖🟠➖🟡➖🟢➖❌"
}
```
## Detailed Design
The public interface for this system comes in two parts: the `AsyncSequenceValidationDiagram` subsystem and the `XCTest` extensions. The most commonly interacted-with and most approachable portion is the `XCTest` extension.
```swift
extension XCTestCase {
public func validate<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(theme: Theme, @AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line)
public func validate<Test: AsyncSequenceValidationTest>(@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test, file: StaticString = #file, line: UInt = #line)
}
```
These two methods break down to usage like some of the previously used examples. However, the reality of how it works is perhaps the more important portion. For example, the code listed below has some points of interest worth mentioning.
```swift
validate {
"a--b--c---|"
$0.inputs[0].map { item in await Task { item.capitalized }.value }
"A--B--C---|"
}
```
The progression of the input sequence can be derived from the `$0.inputs[0]`. This is an `AsyncSequence` with the `Element` type of `String` which at the given input emits an `"a"` at tick 0, a `"b"` at tick 3, a `"c"` at tick 6 and a finish event at tick 10. The output of the middle expression `$0.inputs[0].map { item in await Task { item.capitalized }.value }` is expected to emit an `"A"` at tick 0, a `"B"` at tick 3, a `"C"` at tick 6 and a finish event at tick 10.
Careful readers may immediately recognize that the `map` function is asynchronous and schedules work on a separate task. Normally, this would pose a distinct hazard to deterministic testing for timing of events. However, the `validate` utilizes a specialized hook into the Swift concurrency runtime to schedule the events stepwise and deterministically. This works in a two-fold manner: first, it uses a custom `Clock` to schedule events. Second, it ties that clock into a task driver that ensures enqueued jobs are executed in lockstep with that clock.
The underpinnings to make that work are the actual `AsyncSequenceValidationDiagram` subsystem. The `XCTest` interface does offer a considerably more simple surface area so the diagrams will be broken down into a few key sections for approachability. Those sections are the result builder, the diagram clock, the inputs, themes, and expectations/tests.
### Result Builder
The result builder syntax allows for simple and concise diagrams to be built. Those diagrams can come in a few forms, ranging from no inputs to three inputs. It is worth noting the implementation is not limited to just three inputs and can easily be expanded to more as we deem it needed. The builder itself uses the multiple parameter build block functions to ensure the proper ordering of inputs, tested sequences, and outputs.
```swift
@resultBuilder
public struct AsyncSequenceValidationDiagram : Sendable {
public static func buildBlock<Operation: AsyncSequence>(
_ sequence: Operation,
_ output: String
) -> some AsyncSequenceValidationTest where Operation.Element == String
public static func buildBlock<Operation: AsyncSequence>(
_ input: String,
_ sequence: Operation,
_ output: String
) -> some AsyncSequenceValidationTest where Operation.Element == String
public static func buildBlock<Operation: AsyncSequence>(
_ input1: String,
_ input2: String,
_ sequence: Operation,
_ output: String
) -> some AsyncSequenceValidationTest where Operation.Element == String
public static func buildBlock<Operation: AsyncSequence>(
_ input1: String,
_ input2: String,
_ input3: String,
_ sequence: Operation,
_ output: String
) -> some AsyncSequenceValidationTest where Operation.Element == String
public var inputs: InputList { get }
public var clock: Clock { get }
}
```
The `AsyncSequenceValidationTest`, `InputList`, and `Clock` will be covered in subsequent sections.
### Validation Diagram Clock
One of the key functionalities of the validation diagrams is being able to control time. For proper usage of this testing infrastructure, all clock sources must be tied to the `AsyncSequenceValidationDiagram.Clock` that is exposed on the diagram itself. This is the heartbeat of how each columnar input and expectation are produced and consumed. It measures time in an integral manner of `steps`. One step is advanced per event symbol; in the default ASCII diagrams that means:
* `-`, `;`, `|`, `^`, and any character value event.
* Quoted values like `"'foo'"`.
* Grouped events like `"[ab]"`.
```swift
extension AsyncSequenceValidationDiagram {
public struct Clock { }
}
extension AsyncSequenceValidationDiagram.Clock: Clock {
public struct Step: DurationProtocol, Hashable, CustomStringConvertible {
public static func + (lhs: Step, rhs: Step) -> Step
public static func - (lhs: Step, rhs: Step) -> Step
public static func / (lhs: Step, rhs: Int) -> Step
public static func * (lhs: Step, rhs: Int) -> Step
public static func / (lhs: Step, rhs: Step) -> Double
public static func < (lhs: Step, rhs: Step) -> Bool
public static var zero: Step
public static func steps(_ amount: Int) -> Step
}
public struct Instant: InstantProtocol, CustomStringConvertible {
public func advanced(by duration: Step) -> Instant
public func duration(to other: Instant) -> Step
}
public var now: Instant { get }
public var minimumResolution: Step { get }
public func sleep(
until deadline: Instant,
tolerance: Step? = nil
) async throws
}
```
Key notes: the `minimumResolution` of the `AsyncSequenceValidationDiagram.Clock` is fixed at `.steps(1)`, and the tolerance to the `sleep` function is ignored. These two behaviors were chosen because there is no sub-step granularity besides the order of execution and any coalescing due to tolerance would detract from the explicit expectations of deterministic execution order.
### Inputs
The inputs to the validation diagram are lazily constructed with the input parameters built by the result builder syntax. The inputs are `Sendable` and `AsyncSequence` conforming types that have their `Element` defined as `String`. The elements are produced as defined by the input specification in the result builder. This means that on each tick that an element is defined, the `next` function will resume to return that element (or return `nil` or throw an error, depending on the input specification). The `InputList` grants access to the defined inputs lazily.
```swift
extension AsyncSequenceValidationDiagram {
public struct Input: AsyncSequence, Sendable {
public typealias Element = String
public struct Iterator: AsyncIteratorProtocol {
public mutating func next() async throws -> String?
}
public func makeAsyncIterator() -> Iterator
}
public struct InputList: RandomAccessCollection, Sendable {
public typealias Element = Input
}
}
```
Access to the validation diagram input list is done through calls such as `$0.inputs[0]` seen in other examples. This access fetches lazily the first input specification and creates an `Input` `AsyncSequence` out of that domain specific language symbology.
### Themes
| Symbol | Token | Description | Example |
| ------- | ------------------------- | ----------------- | ---------- |
| `-` | `.step` | Advance time | `"a--b--"` |
| `|` | `.finish` | Termination | `"ab-|"` |
| `^` | `.error` | Thrown error | `"ab-^"` |
| `;` | `.cancel` | Cancellation | `"ab;-"` |
| `[` | `.beginGroup` | Begin group | `"[ab]-"` |
| `]` | `.endGroup` | End group | `"[ab]-"` |
| `'` | `.beginValue` `.endValue` | Begin/End Value | `"'foo'-"` |
| `,` | `.delayNext` | Delay next | `",[a,]b"` |
| ` ` | `.skip` | Skip/Ignore | `"a b- |"` |
| | `.value` | Values. | `"ab-|"` |
There are some diagram input specifications that are not valid. The three cases are:
* A step being specified in a group (`"[a-]b|"`).
* A nested group (`"[[ab]]|"`).
* An unbalanced nesting (`"[ab|"`).
```swift
public protocol AsyncSequenceValidationTheme {
func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token
}
extension AsyncSequenceValidationTheme where Self == AsyncSequenceValidationDiagram.ASCIITheme {
public static var ascii: AsyncSequenceValidationDiagram.ASCIITheme
}
extension AsyncSequenceValidationDiagram {
public enum Token {
case step
case error
case finish
case cancel
case delayNext
case beginValue
case endValue
case beginGroup
case endGroup
case skip
case value(String)
}
public struct ASCIITheme: AsyncSequenceValidationTheme {
public func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token
}
}
```
### Expectations and Tests
This set of interfaces are the primary mechanism in which the simplified XCTest extension rests upon.
Expectations defined by the domain specific language symbology can be roughly expressed as expected results and actual results. This notably avoids cancellation and steps, since those are better expressed through the failure reporting system. The expectation failures can express the combination of these expected and actual values. This can also show when the expectation failure occurred and the kind of expectation failure that happened, along with the payload of the actual and expected values.
```swift
extension AsyncSequenceValidationDiagram {
public struct ExpectationResult {
public var expected: [(Clock.Instant, Result<String?, Error>)]
public var actual: [(Clock.Instant, Result<String?, Error>)]
}
public struct ExpectationFailure: CustomStringConvertible {
public enum Kind {
case expectedFinishButGotValue(String)
case expectedMismatch(String, String)
case expectedValueButGotFinished(String)
case expectedFailureButGotValue(Error, String)
case expectedFailureButGotFinish(Error)
case expectedValueButGotFailure(String, Error)
case expectedFinishButGotFailure(Error)
case expectedValue(String)
case expectedFinish
case expectedFailure(Error)
case unexpectedValue(String)
case unexpectedFinish
case unexpectedFailure(Error)
}
public var when: Clock.Instant
public var kind: Kind
}
}
```
The testing itself reduces down to two methods, one being a default theme parameter of `.ascii`. The test methods execute the validation diagram using a custom scheduling hook from the concurrency runtime such that all events are sequentially processed on a single cooperatively-multitasking executed thread. That thread is responsible for ensuring the ordering of the events and the execution of each time delineation such that the order of emissions of any input events are sequential top to bottom: input 0 is emitted first, then input 1, etc. After the ordering of input events, the jobs enqueued onto that task driver thread are executed in order of receipt. This ensures the overall order of execution is stable and deterministic but, most importantly, predictable.
```swift
public protocol AsyncSequenceValidationTest: Sendable {
var inputs: [String] { get }
var output: String { get }
func test(_ event: (String) -> Void) async throws
}
extension AsyncSequenceValidationDiagram {
public static func test<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(
theme: Theme,
@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test
) throws -> (ExpectationResult, [ExpectationFailure])
public static func test<Test: AsyncSequenceValidationTest>(
@AsyncSequenceValidationDiagram _ build: (inout AsyncSequenceValidationDiagram) -> Test
) throws -> (ExpectationResult, [ExpectationFailure])
}
```
## Future Directions/Improvements
The emoji diagram theme could be made to be a built-in system. It makes for really flashy slides/demos and makes it really easy to see what is going on, but at the cost of being slightly harder to type.
The testing infrastructure could support (with minor alteration) testing iteration beyond the terminal cases, either errors being thrown from the iterator or past the first `nil` return value from `next`. This could help enforce some of the semantical expectations of `AsyncSequence`.
In addition to hooking into the runtime for execution of jobs, the deferred execution of jobs could also be hooked so that a time scale conversion could be made such that any sleep using any clock could map directly to the validation diagram internal clock ticks.
The testing infrastructure could also have support for testing for values that do not have specified order for a given tick. Some race conditions from external systems not under the control of the concurrency runtime may not be accountable. If that were to be a consideration, unordered group tokens could be added. For example the symbols `{` and `}` could be used to represent a group that is unordered. However, since there are not any cases where this really seems useful for the swift-async-algorithms package, this is not a priority at this time.
## Alternatives Considered
The validation diagram system could be retrofitted to accommodate other value types other than strings, however most use cases can easily be expressed in a readable form with minor adjustments to use strings.
The builder functions could pass in N-ary variants of the diagram to enforce the inputs to be specific instead of accessed via the lazy `InputList`. As we may potentially add additional numbers of inputs in the future this seems like a less maintainable implementation even though it may offer slightly more safety and only marginally better spelling, i.e., `$0.inputs[0]` versus `$0.input0` etc.
## Credits/Inspiration
Some of the major sources of inspiration for the validation diagram system were https://rxjs.dev/guide/testing/marble-testing and the graphical representations from https://rxmarbles.com. Both of these were immensely useful to help discuss the expected behaviors of how asynchronous sequences should behave.
@@ -1,111 +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
//
//===----------------------------------------------------------------------===//
import _CAsyncSequenceValidationSupport
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
@resultBuilder
public struct AsyncSequenceValidationDiagram : Sendable {
public struct Component<T> {
var component: T
var location: SourceLocation
}
public struct AccumulatedInputs {
var inputs: [Specification] = []
}
public struct AccumulatedInputsWithOperation<Operation: AsyncSequence> where Operation.Element == String {
var inputs: [Specification]
var operation: Operation
}
public static func buildExpression(_ expr: String, file: StaticString = #file, line: UInt = #line) -> Component<String> {
Component(component: expr, location: SourceLocation(file: file, line: line))
}
public static func buildExpression<S: AsyncSequence>(_ expr: S, file: StaticString = #file, line: UInt = #line) -> Component<S> {
Component(component: expr, location: SourceLocation(file: file, line: line))
}
public static func buildPartialBlock(first input: Component<String>) -> AccumulatedInputs {
return AccumulatedInputs(inputs: [Specification(specification: input.component, location: input.location)])
}
public static func buildPartialBlock<Operation: AsyncSequence>(first operation: Component<Operation>) -> AccumulatedInputsWithOperation<Operation> where Operation.Element == String {
return AccumulatedInputsWithOperation(inputs: [], operation: operation.component)
}
public static func buildPartialBlock(accumulated: AccumulatedInputs, next input: Component<String>) -> AccumulatedInputs {
return AccumulatedInputs(inputs: accumulated.inputs + [Specification(specification: input.component, location: input.location)])
}
public static func buildPartialBlock<Operation: AsyncSequence>(accumulated: AccumulatedInputs, next operation: Component<Operation>) -> AccumulatedInputsWithOperation<Operation> {
return AccumulatedInputsWithOperation(inputs: accumulated.inputs, operation: operation.component)
}
public static func buildPartialBlock<Operation: AsyncSequence>(accumulated: AccumulatedInputsWithOperation<Operation>, next output: Component<String>) -> some AsyncSequenceValidationTest {
return Test(inputs: accumulated.inputs, sequence: accumulated.operation, output: Specification(specification: output.component, location: output.location))
}
public static func buildBlock<Operation: AsyncSequence>(_ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
let part1 = buildPartialBlock(first: sequence)
let part2 = buildPartialBlock(accumulated: part1, next: output)
return part2
}
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
let part1 = buildPartialBlock(first: input1)
let part2 = buildPartialBlock(accumulated: part1, next: sequence)
let part3 = buildPartialBlock(accumulated: part2, next: output)
return part3
}
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
let part1 = buildPartialBlock(first: input1)
let part2 = buildPartialBlock(accumulated: part1, next: input2)
let part3 = buildPartialBlock(accumulated: part2, next: sequence)
let part4 = buildPartialBlock(accumulated: part3, next: output)
return part4
}
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ input3: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
let part1 = buildPartialBlock(first: input1)
let part2 = buildPartialBlock(accumulated: part1, next: input2)
let part3 = buildPartialBlock(accumulated: part2, next: input3)
let part4 = buildPartialBlock(accumulated: part3, next: sequence)
let part5 = buildPartialBlock(accumulated: part4, next: output)
return part5
}
public static func buildBlock<Operation: AsyncSequence>(_ input1: Component<String>, _ input2: Component<String>, _ input3: Component<String>, _ input4: Component<String>, _ sequence: Component<Operation>, _ output: Component<String>) -> some AsyncSequenceValidationTest where Operation.Element == String {
let part1 = buildPartialBlock(first: input1)
let part2 = buildPartialBlock(accumulated: part1, next: input2)
let part3 = buildPartialBlock(accumulated: part2, next: input3)
let part4 = buildPartialBlock(accumulated: part3, next: input3)
let part5 = buildPartialBlock(accumulated: part4, next: sequence)
let part6 = buildPartialBlock(accumulated: part5, next: output)
return part6
}
let queue: WorkQueue
public var inputs: InputList
public let clock: Clock
internal init() {
let queue = WorkQueue()
self.queue = queue
self.inputs = InputList(queue: queue)
self.clock = Clock(queue: queue)
}
}
-113
View File
@@ -1,113 +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
//
//===----------------------------------------------------------------------===//
import AsyncAlgorithms
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
public struct Clock {
let queue: WorkQueue
init(queue: WorkQueue) {
self.queue = queue
}
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram.Clock: Clock {
public struct Step: DurationProtocol, Hashable, CustomStringConvertible {
internal var rawValue: Int
internal init(_ rawValue: Int) {
self.rawValue = rawValue
}
public static func + (lhs: Step, rhs: Step) -> Step {
return .init(lhs.rawValue + rhs.rawValue)
}
public static func - (lhs: Step, rhs: Step) -> Step {
.init(lhs.rawValue - rhs.rawValue)
}
public static func / (lhs: Step, rhs: Int) -> Step {
.init(lhs.rawValue / rhs)
}
public static func * (lhs: Step, rhs: Int) -> Step {
.init(lhs.rawValue * rhs)
}
public static func / (lhs: Step, rhs: Step) -> Double {
Double(lhs.rawValue) / Double(rhs.rawValue)
}
public static func < (lhs: Step, rhs: Step) -> Bool {
lhs.rawValue < rhs.rawValue
}
public static var zero: Step { .init(0) }
public static func steps(_ amount: Int) -> Step {
return Step(amount)
}
public var description: String {
return "step \(rawValue)"
}
}
public struct Instant: InstantProtocol, CustomStringConvertible {
public typealias Duration = Step
let when: Step
public func advanced(by duration: Step) -> Instant {
Instant(when: when + duration)
}
public func duration(to other: Instant) -> Step {
other.when - when
}
public static func < (lhs: Instant, rhs: Instant) -> Bool {
lhs.when < rhs.when
}
public var description: String {
// the raw value is 1 indexed in execution but we should report it as 0 indexed
return "tick \(when.rawValue - 1)"
}
}
public var now: Instant {
queue.now
}
public var minimumResolution: Step {
.steps(1)
}
public func sleep(
until deadline: Instant,
tolerance: Step? = nil
) async throws {
let token = queue.prepare()
try await withTaskCancellationHandler {
queue.cancel(token)
} operation: {
try await withUnsafeThrowingContinuation { continuation in
queue.enqueue(AsyncSequenceValidationDiagram.Context.currentJob, deadline: deadline, continuation: continuation, token: token)
}
}
}
}
-165
View File
@@ -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
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
struct Failure: Error, Equatable { }
enum ParseFailure: Error, CustomStringConvertible, SourceFailure {
case stepInGroup(String, String.Index, SourceLocation)
case nestedGroup(String, String.Index, SourceLocation)
case unbalancedNesting(String, String.Index, SourceLocation)
var location: SourceLocation {
switch self {
case .stepInGroup(_, _, let location): return location
case .nestedGroup(_, _, let location): return location
case .unbalancedNesting(_, _, let location): return location
}
}
var description: String {
switch self {
case .stepInGroup:
return "validation diagram step symbol in group"
case .nestedGroup:
return "validation diagram nested grouping"
case .unbalancedNesting:
return "validation diagram unbalanced grouping"
}
}
}
enum Event {
case value(String, String.Index)
case failure(Error, String.Index)
case finish(String.Index)
case delayNext(String.Index)
case cancel(String.Index)
var results: [Result<String?, Error>] {
switch self {
case .value(let value, _): return [.success(value)]
case .failure(let failure, _): return [.failure(failure)]
case .finish: return [.success(nil)]
case .delayNext: return []
case .cancel: return []
}
}
var index: String.Index {
switch self {
case .value(_, let index): return index
case .failure(_, let index): return index
case .finish(let index): return index
case .delayNext(let index): return index
case .cancel(let index): return index
}
}
static func parse<Theme: AsyncSequenceValidationTheme>(_ dsl: String, theme: Theme, location: SourceLocation) throws -> [(Clock.Instant, Event)] {
var emissions = [(Clock.Instant, Event)]()
var when = Clock.Instant(when: .steps(0))
var string: String?
var grouping = 0
for index in dsl.indices {
let ch = dsl[index]
switch theme.token(dsl[index], inValue: string != nil) {
case .step:
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
} else {
throw ParseFailure.stepInGroup(dsl, index, location)
}
} else {
string?.append(ch)
}
case .error:
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .failure(Failure(), index)))
} else {
string?.append(ch)
}
case .finish:
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .finish(index)))
} else {
string?.append(ch)
}
case .cancel:
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .cancel(index)))
} else {
string?.append(ch)
}
case .delayNext:
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .delayNext(index)))
} else {
string?.append(ch)
}
case .beginValue:
string = ""
case .endValue:
if let value = string {
string = nil
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .value(value, index)))
}
case .beginGroup:
if grouping == 0 {
when = when.advanced(by: .steps(1))
} else {
throw ParseFailure.nestedGroup(dsl, index, location)
}
grouping += 1
case .endGroup:
grouping -= 1
if grouping < 0 {
throw ParseFailure.unbalancedNesting(dsl, index, location)
}
case .skip:
string?.append(ch)
continue
case .value(let str):
if string == nil {
if grouping == 0 {
when = when.advanced(by: .steps(1))
}
emissions.append((when, .value(String(ch), index)))
} else {
string?.append(str)
}
}
}
if grouping != 0 {
throw ParseFailure.unbalancedNesting(dsl, dsl.endIndex, location)
}
return emissions
}
}
}
@@ -1,168 +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
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
public struct ExpectationResult: Sendable {
public struct Event: Sendable {
public var when: Clock.Instant
public var result: Result<String?, Error>
public var offset: String.Index
}
public var expected: [Event]
public var actual: [(Clock.Instant, Result<String?, Error>)]
func reconstitute<Theme: AsyncSequenceValidationTheme>(_ result: Result<String?, Error>, theme: Theme) -> String {
var reconstituted = ""
switch result {
case .success(let value):
if let value = value {
if value.count > 1 {
reconstituted += theme.description(for: .beginValue)
reconstituted += theme.description(for: .value(value))
reconstituted += theme.description(for: .endValue)
} else {
reconstituted += theme.description(for: .value(value))
}
} else {
reconstituted += theme.description(for: .finish)
}
case .failure:
reconstituted += theme.description(for: .error)
}
return reconstituted
}
func reconstitute<Theme: AsyncSequenceValidationTheme>(_ events: [Clock.Instant : [Result<String?, Error>]], theme: Theme, end: Clock.Instant) -> String {
var now = Clock.Instant(when: .steps(1)) // adjust for the offset index
var reconstituted = ""
while now <= end {
if let results = events[now] {
if results.count == 1 {
reconstituted += reconstitute(results[0], theme: theme)
} else {
reconstituted += theme.description(for: .beginGroup)
for result in results {
reconstituted += reconstitute(result, theme: theme)
}
reconstituted += theme.description(for: .endGroup)
}
} else {
reconstituted += theme.description(for: .step)
}
now = now.advanced(by: .steps(1))
}
return reconstituted
}
public func reconstituteExpected<Theme: AsyncSequenceValidationTheme>(theme: Theme) -> String {
var events = [Clock.Instant : [Result<String?, Error>]]()
var end: Clock.Instant = Clock.Instant(when: .zero)
for expectation in expected {
let when = expectation.when
let result = expectation.result
events[when, default: []].append(result)
if when > end {
end = when
}
}
return reconstitute(events, theme: theme, end: end)
}
public func reconstituteActual<Theme: AsyncSequenceValidationTheme>(theme: Theme) -> String {
var events = [Clock.Instant : [Result<String?, Error>]]()
var end: Clock.Instant = Clock.Instant(when: .zero)
for (when, result) in actual {
events[when, default: []].append(result)
if when > end {
end = when
}
}
return reconstitute(events, theme: theme, end: end)
}
}
public struct ExpectationFailure: Sendable, CustomStringConvertible {
public enum Kind: Sendable {
case expectedFinishButGotValue(String)
case expectedMismatch(String, String)
case expectedValueButGotFinished(String)
case expectedFailureButGotValue(Error, String)
case expectedFailureButGotFinish(Error)
case expectedValueButGotFailure(String, Error)
case expectedFinishButGotFailure(Error)
case expectedValue(String)
case expectedFinish
case expectedFailure(Error)
case unexpectedValue(String)
case unexpectedFinish
case unexpectedFailure(Error)
case specificationViolationGotValueAfterIteration(String)
case specificationViolationGotFailureAfterIteration(Error)
}
public var when: Clock.Instant
public var kind: Kind
public var specification: Specification?
public var index: String.Index?
init(when: Clock.Instant, kind: Kind, specification: Specification? = nil, index: String.Index? = nil) {
self.when = when
self.kind = kind
self.specification = specification
self.index = index
}
var reason: String {
switch kind {
case .expectedFinishButGotValue(let actual):
return "expected finish but got \"\(actual)\""
case .expectedMismatch(let expected, let actual):
return "expected \"\(expected)\" but got \"\(actual)\""
case .expectedValueButGotFinished(let expected):
return "expected \"\(expected)\" but got finish"
case .expectedFailureButGotValue(_, let actual):
return "expected failure but got \"\(actual)\""
case .expectedFailureButGotFinish:
return "expected failure but got finish"
case .expectedValueButGotFailure(let expected, _):
return "expected \"\(expected)\" but got failure"
case .expectedFinishButGotFailure:
return "expected finish but got failure"
case .expectedValue(let expected):
return "expected \"\(expected)\""
case .expectedFinish:
return "expected finish"
case .expectedFailure:
return "expected failure"
case .unexpectedValue(let actual):
return "unexpected \"\(actual)\""
case .unexpectedFinish:
return "unexpected finish"
case .unexpectedFailure:
return "unexpected failure"
case .specificationViolationGotValueAfterIteration(let actual):
return "specification violation got \"\(actual)\" after iteration terminated"
case .specificationViolationGotFailureAfterIteration:
return "specification violation got failure after iteration terminated"
}
}
public var description: String {
return reason + " at tick \(when.when.rawValue - 1)"
}
}
}
-124
View File
@@ -1,124 +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
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
public struct Specification: Sendable {
public let specification: String
public let location: SourceLocation
init(specification: String, location: SourceLocation) {
self.specification = specification
self.location = location
}
}
public struct Input: AsyncSequence, Sendable {
public typealias Element = String
struct State {
var emissions = [(Clock.Instant, Event)]()
}
let state = ManagedCriticalState(State())
let queue: WorkQueue
let index: Int
public struct Iterator: AsyncIteratorProtocol, Sendable {
let state: ManagedCriticalState<State>
let queue: WorkQueue
let index: Int
var active: (Clock.Instant, [Result<String?, Error>])?
var eventIndex = 0
mutating func apply(when: Clock.Instant, results: [Result<String?, Error>]) async throws -> Element? {
let token = queue.prepare()
if eventIndex + 1 >= results.count {
active = nil
}
defer {
if active != nil {
eventIndex += 1
} else {
eventIndex = 0
}
}
return try await withTaskCancellationHandler { [queue] in
queue.cancel(token)
} operation: {
try await withUnsafeThrowingContinuation { continuation in
queue.enqueue(Context.currentJob, deadline: when, continuation: continuation, results[eventIndex], index: index, token: token)
}
}
}
public mutating func next() async throws -> Element? {
if let (when, results) = active {
return try await apply(when: when, results: results)
} else {
let next = state.withCriticalRegion { state -> (Clock.Instant, Event)? in
guard state.emissions.count > 0 else {
return nil
}
return state.emissions.removeFirst()
}
guard let next = next else {
return nil
}
let when = next.0
let results = next.1.results
active = (when, results)
return try await apply(when: when, results: results)
}
}
}
public func makeAsyncIterator() -> Iterator {
Iterator(state: state, queue: queue, index: index)
}
func parse<Theme: AsyncSequenceValidationTheme>(_ dsl: String, theme: Theme, location: SourceLocation) throws {
let emissions = try Event.parse(dsl, theme: theme, location: location)
state.withCriticalRegion { state in
state.emissions = emissions
}
}
var end: Clock.Instant? {
return state.withCriticalRegion { state in
state.emissions.map { $0.0 }.sorted().last
}
}
}
public struct InputList: RandomAccessCollection, Sendable {
let state = ManagedCriticalState([Input]())
let queue: WorkQueue
public var startIndex: Int { return 0 }
public var endIndex: Int {
state.withCriticalRegion { $0.count }
}
public subscript(position: Int) -> AsyncSequenceValidationDiagram.Input {
get {
return state.withCriticalRegion { state in
if position >= state.count {
for _ in state.count...position {
state.append(Input(queue: queue, index: position))
}
}
return state[position]
}
}
}
}
}
-25
View File
@@ -1,25 +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
//
//===----------------------------------------------------------------------===//
import _CAsyncSequenceValidationSupport
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
struct Job: Hashable, @unchecked Sendable {
let job: JobRef
init(_ job: JobRef) {
self.job = job
}
func execute() {
_swiftJobRun(unsafeBitCast(job, to: UnownedJob.self), AsyncSequenceValidationDiagram.Context.executor.asUnownedSerialExecutor())
}
}
@@ -1 +0,0 @@
../../Sources/AsyncAlgorithms/Locking.swift
@@ -1,28 +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
//
//===----------------------------------------------------------------------===//
public struct SourceLocation: Sendable, CustomStringConvertible {
public var file: StaticString
public var line: UInt
public init(file: StaticString, line: UInt) {
self.file = file
self.line = line
}
public var description: String {
return "\(file):\(line)"
}
}
public protocol SourceFailure: Error {
var location: SourceLocation { get }
}
@@ -1,86 +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
//
//===----------------------------------------------------------------------===//
import _CAsyncSequenceValidationSupport
#if canImport(Darwin)
@_implementationOnly import Darwin
#elseif canImport(Glibc)
@_implementationOnly import Glibc
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#endif
#if canImport(Darwin)
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
func start_thread(_ raw: UnsafeMutableRawPointer) -> UnsafeMutableRawPointer? {
Unmanaged<TaskDriver>.fromOpaque(raw).takeRetainedValue().run()
return nil
}
#elseif canImport(Glibc)
func start_thread(_ raw: UnsafeMutableRawPointer?) -> UnsafeMutableRawPointer? {
Unmanaged<TaskDriver>.fromOpaque(raw!).takeRetainedValue().run()
return nil
}
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#endif
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
final class TaskDriver {
let work: (TaskDriver) -> Void
let queue: WorkQueue
#if canImport(Darwin)
var thread: pthread_t?
#elseif canImport(Glibc)
var thread = pthread_t()
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#endif
init(queue: WorkQueue, _ work: @escaping (TaskDriver) -> Void) {
self.queue = queue
self.work = work
}
func start() {
pthread_create(&thread, nil, start_thread,
Unmanaged.passRetained(self).toOpaque())
}
func run() {
#if canImport(Darwin)
pthread_setname_np("Validation Diagram Clock Driver")
#endif
work(self)
}
func join() {
#if canImport(Darwin)
pthread_join(thread!, nil)
#elseif canImport(Glibc)
pthread_join(thread, nil)
#elseif canImport(WinSDK)
#error("TODO: Port TaskDriver threading to windows")
#endif
}
func enqueue(_ job: JobRef) {
let job = Job(job)
queue.enqueue(AsyncSequenceValidationDiagram.Context.currentJob) {
let previous = AsyncSequenceValidationDiagram.Context.currentJob
AsyncSequenceValidationDiagram.Context.currentJob = job
job.execute()
AsyncSequenceValidationDiagram.Context.currentJob = previous
}
}
}
-373
View File
@@ -1,373 +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
//
//===----------------------------------------------------------------------===//
import _CAsyncSequenceValidationSupport
import AsyncAlgorithms
@_silgen_name("swift_job_run")
@usableFromInline
internal func _swiftJobRun(
_ job: UnownedJob,
_ executor: UnownedSerialExecutor
) -> ()
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public protocol AsyncSequenceValidationTest: Sendable {
var inputs: [AsyncSequenceValidationDiagram.Specification] { get }
var output: AsyncSequenceValidationDiagram.Specification { get }
func test<C: Clock>(with clock: C, activeTicks: [C.Instant], output: AsyncSequenceValidationDiagram.Specification, _ event: (String) -> Void) async throws
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
struct Test<Operation: AsyncSequence>: AsyncSequenceValidationTest, @unchecked Sendable where Operation.Element == String {
let inputs: [Specification]
let sequence: Operation
let output: Specification
func test<C: _Concurrency.Clock>(with clock: C, activeTicks: [C.Instant], output: Specification, _ event: (String) -> Void) async throws {
var iterator = sequence.makeAsyncIterator()
do {
for tick in activeTicks {
if tick != clock.now {
try await clock.sleep(until: tick, tolerance: nil)
}
if let item = try await iterator.next() {
event(item)
} else {
break
}
}
do {
if let pastEnd = try await iterator.next(){
let failure = ExpectationFailure(
when: Context.clock!.now,
kind: .specificationViolationGotValueAfterIteration(pastEnd),
specification: output)
Context.specificationFailures.append(failure)
}
} catch {
let failure = ExpectationFailure(
when: Context.clock!.now,
kind: .specificationViolationGotFailureAfterIteration(error),
specification: output)
Context.specificationFailures.append(failure)
}
} catch {
throw error
}
}
}
struct Context {
final class ClockExecutor: SerialExecutor {
func enqueue(_ job: UnownedJob) {
job._runSynchronously(on: asUnownedSerialExecutor())
}
func asUnownedSerialExecutor() -> UnownedSerialExecutor {
UnownedSerialExecutor(ordinary: self)
}
}
static var clock: Clock?
static let executor = ClockExecutor()
static var driver: TaskDriver?
static var currentJob: Job?
static var specificationFailures = [ExpectationFailure]()
}
enum ActualResult {
case success(String?)
case failure(Error)
case none
init(_ result: Result<String?, Error>?) {
if let result = result {
switch result {
case .success(let value):
self = .success(value)
case .failure(let error):
self = .failure(error)
}
} else {
self = .none
}
}
}
static func validate<Theme: AsyncSequenceValidationTheme>(
inputs: [Specification],
output: Specification,
theme: Theme,
expected: [ExpectationResult.Event],
actual: [(Clock.Instant, Result<String?, Error>)]
) -> (ExpectationResult, [ExpectationFailure]) {
let result = ExpectationResult(expected: expected, actual: actual)
var failures = Context.specificationFailures
Context.specificationFailures.removeAll()
let actualTimes = actual.map { when, _ in when }
let expectedTimes = expected.map { $0.when }
var expectedMap = [Clock.Instant: [ExpectationResult.Event]]()
var actualMap = [Clock.Instant: [Result<String?, Error>]]()
for event in expected {
expectedMap[event.when, default: []].append(event)
}
for (when, result) in actual {
actualMap[when, default: []].append(result)
}
let allTimes = Set(actualTimes + expectedTimes).sorted()
for when in allTimes {
let expectedResults = expectedMap[when] ?? []
let actualResults = actualMap[when] ?? []
var expectedIterator = expectedResults.makeIterator()
var actualIterator = actualResults.makeIterator()
while let expectedEvent = expectedIterator.next() {
let actualResult = ActualResult(actualIterator.next())
switch (expectedEvent.result, actualResult) {
case (.success(let expected), .success(let actual)):
switch (expected, actual) {
case (.some(let expected), .some(let actual)):
if expected != actual {
let failure = ExpectationFailure(
when: when,
kind: .expectedMismatch(expected, actual),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
}
case (.none, .some(let actual)):
let failure = ExpectationFailure(
when: when,
kind: .expectedFinishButGotValue(actual),
specification: output)
failures.append(failure)
case (.some(let expected), .none):
let failure = ExpectationFailure(
when: when,
kind: .expectedValueButGotFinished(expected),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
case (.none, .none):
break
}
case (.success(let expected), .failure(let actual)):
if let expected = expected {
let failure = ExpectationFailure(
when: when,
kind: .expectedValueButGotFailure(expected, actual),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
} else {
let failure = ExpectationFailure(
when: when,
kind: .expectedFinishButGotFailure(actual),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
}
case (.success(let expected), .none):
switch expected {
case .some(let expected):
let failure = ExpectationFailure(
when: when,
kind: .expectedValue(expected),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
case .none:
let failure = ExpectationFailure(
when: when,
kind: .expectedFinish,
specification: output,
index: expectedEvent.offset)
failures.append(failure)
}
case (.failure(let expected), .success(let actual)):
if let actual = actual {
let failure = ExpectationFailure(
when: when,
kind: .expectedFailureButGotValue(expected, actual),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
} else {
let failure = ExpectationFailure(
when: when,
kind: .expectedFailureButGotFinish(expected),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
}
case (.failure, .failure):
break
case (.failure(let expected), .none):
let failure = ExpectationFailure(
when: when,
kind: .expectedFailure(expected),
specification: output,
index: expectedEvent.offset)
failures.append(failure)
}
}
while let unexpectedResult = actualIterator.next() {
switch unexpectedResult {
case .success(let actual):
switch actual {
case .some(let actual):
let failure = ExpectationFailure(
when: when,
kind: .unexpectedValue(actual),
specification: output)
failures.append(failure)
case .none:
let failure = ExpectationFailure(
when: when,
kind: .unexpectedFinish,
specification: output)
failures.append(failure)
}
case .failure(let actual):
let failure = ExpectationFailure(
when: when,
kind: .unexpectedFailure(actual),
specification: output)
failures.append(failure)
}
}
}
return (result, failures)
}
public static func test<Test: AsyncSequenceValidationTest, Theme: AsyncSequenceValidationTheme>(
theme: Theme,
@AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test
) throws -> (ExpectationResult, [ExpectationFailure]) {
let diagram = AsyncSequenceValidationDiagram()
let clock = diagram.clock
let test = build(diagram)
for index in 0..<test.inputs.count {
// fault in all inputs
_ = diagram.inputs[index]
}
for (index, input) in diagram.inputs.enumerated() {
let inputSpecification = test.inputs[index]
try input.parse(inputSpecification.specification, theme: theme, location: inputSpecification.location)
}
let parsedOutput = try Event.parse(test.output.specification, theme: theme, location: test.output.location)
let cancelEvents = Set(parsedOutput.filter { when, event in
switch event {
case .cancel: return true
default: return false
}
}.map { when, _ in return when })
let activeTicks = parsedOutput.reduce(into: [Clock.Instant.init(when: .zero)]) { events, thisEvent in
switch thisEvent {
case (let when, .delayNext(_)):
events.removeLast()
events.append(when.advanced(by: .steps(1)))
case (let when, _):
events.append(when)
}
}
var expected = [ExpectationResult.Event]()
for (when, event) in parsedOutput {
for result in event.results {
expected.append(ExpectationResult.Event(when: when, result: result, offset: event.index))
}
}
let times = parsedOutput.map { when, _ in when }
guard let end = (times + diagram.inputs.compactMap { $0.end }).max() else {
return (ExpectationResult(expected: [], actual: []), [])
}
let actual = ManagedCriticalState([(Clock.Instant, Result<String?, Error>)]())
Context.clock = clock
Context.specificationFailures.removeAll()
// This all needs to be isolated from potential Tasks (the caller function might be async!)
Context.driver = TaskDriver(queue: diagram.queue) { driver in
swift_task_enqueueGlobal_hook = { job, original in
Context.driver?.enqueue(job)
}
let runner = Task {
do {
try await test.test(with: clock, activeTicks: activeTicks, output: test.output) { event in
actual.withCriticalRegion { values in
values.append((clock.now, .success(event)))
}
}
actual.withCriticalRegion { values in
values.append((clock.now, .success(nil)))
}
} catch {
actual.withCriticalRegion { values in
values.append((clock.now, .failure(error)))
}
}
}
// Drain off any initial work. Work may spawn additional work to be done.
// If the driver ever becomes blocked on the clock, exit early out of that
// drain, because the drain cant make any forward progress if it is blocked
// by a needed clock advancement.
diagram.queue.drain()
// Next make sure to iterate a decent amount past the end of the maximum
// scheduled things (that way we ensure any reasonable errors are caught)
for _ in 0..<(end.when.rawValue * 2) {
if cancelEvents.contains(diagram.queue.now.advanced(by: .steps(1))) {
runner.cancel()
}
diagram.queue.advance()
}
runner.cancel()
Context.clock = nil
swift_task_enqueueGlobal_hook = nil
}
Context.driver?.start()
// This is only valid since we are doing tests here
// else wise this would cause QoS inversions
Context.driver?.join()
Context.driver = nil
return validate(
inputs: test.inputs,
output: test.output,
theme: theme,
expected: expected,
actual: actual.withCriticalRegion { $0 })
}
public static func test<Test: AsyncSequenceValidationTest>(
@AsyncSequenceValidationDiagram _ build: (AsyncSequenceValidationDiagram) -> Test
) throws -> (ExpectationResult, [ExpectationFailure]) {
try self.test(theme: .ascii, build)
}
}
@@ -1,74 +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
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
public protocol AsyncSequenceValidationTheme {
func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token
func description(for token: AsyncSequenceValidationDiagram.Token) -> String
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationTheme where Self == AsyncSequenceValidationDiagram.ASCIITheme {
public static var ascii: AsyncSequenceValidationDiagram.ASCIITheme {
return AsyncSequenceValidationDiagram.ASCIITheme()
}
}
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
extension AsyncSequenceValidationDiagram {
public enum Token: Sendable {
case step
case error
case finish
case cancel
case delayNext
case beginValue
case endValue
case beginGroup
case endGroup
case skip
case value(String)
}
public struct ASCIITheme: AsyncSequenceValidationTheme, Sendable {
public func token(_ character: Character, inValue: Bool) -> AsyncSequenceValidationDiagram.Token {
switch character {
case "-": return .step
case "^": return .error
case "|": return .finish
case ";": return .cancel
case ",": return .delayNext
case "'": return inValue ? .endValue : .beginValue
case "[": return .beginGroup
case "]": return .endGroup
case " ": return .skip
default: return .value(String(character))
}
}
public func description(for token: AsyncSequenceValidationDiagram.Token) -> String {
switch token {
case .step: return "-"
case .error: return "^"
case .finish: return "|"
case .cancel: return ";"
case .delayNext: return ","
case .beginValue: return "'"
case .endValue: return "'"
case .beginGroup: return "["
case .endGroup: return "]"
case .skip: return " "
case .value(let value): return value
}
}
}
}
@@ -1,300 +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
//
//===----------------------------------------------------------------------===//
@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
struct WorkQueue: Sendable {
enum Item: CustomStringConvertible, Comparable {
case blocked(Token, AsyncSequenceValidationDiagram.Clock.Instant, UnsafeContinuation<Void, Error>)
case emit(Token, AsyncSequenceValidationDiagram.Clock.Instant, UnsafeContinuation<String?, Error>, Result<String?, Error>, Int)
case work(Token, @Sendable () -> Void)
case cancelled(Token)
func run() {
switch self {
case .blocked(_, _, let continuation):
continuation.resume()
case .emit(_, _, let continuation, let result, _):
continuation.resume(with: result)
case .work(_, let work):
work()
case .cancelled:
break
}
}
var description: String {
switch self {
case .blocked(let token, let when, _):
return "wakeup #\(token) @\(when) "
case .emit(let token, let when, _, let result, let side):
return "emit #\(token) @\(when) result \(result) side \(side)"
case .work(let token, _):
return "work #\(token)"
case .cancelled(let token):
return "cancelled #\(token)"
}
}
var token: Token {
switch self {
case .blocked(let token, _, _): return token
case .emit(let token, _, _, _, _): return token
case .work(let token, _): return token
case .cancelled(let token): return token
}
}
var isCancelled: Bool {
switch self {
case .cancelled: return true
default: return false
}
}
func cancelling() -> Item {
switch self {
case .blocked(let token, _, let continuation):
return .work(token) {
continuation.resume(throwing: CancellationError())
}
case .emit(let token, _, let continuation, _, _):
return .work(token) {
continuation.resume(returning: nil)
}
default: return self
}
}
// the side order is repsected first since that is the logical flow of predictable events
// then the generation is taken into account
static func < (_ lhs: Item, _ rhs: Item) -> Bool {
switch (lhs, rhs) {
case (.emit(_, _, _, _, let lhs), .emit(_, _, _, _, let rhs)):
return lhs < rhs
default:
return lhs.token.generation < rhs.token.generation
}
}
// all tokens are distinct so we know the generation of when it was enqueued
// always means distinct equality (for ordering)
static func == (_ lhs: Item, _ rhs: Item) -> Bool {
return lhs.token == rhs.token
}
}
struct State {
// the nil Job in these two structures represent the root job in the TaskDriver
var queues = [Job? : [Item]]()
var jobs: [Job?] = [nil]
var items = [Token : Item]()
var now = AsyncSequenceValidationDiagram.Clock.Instant(when: .zero)
var generation = 0
mutating func drain() -> [Item] {
var items = [Item]()
// store off the jobs such that we can only visit the active queues
var jobs = self.jobs
while true {
let startingCount = items.count
var jobsToRemove = Set<Int>()
// iterate in order of the jobs from when they have been seen
// the dictionary is not ordered for its keys so make sure we iterate stably
for jobIndex in 0..<jobs.count {
let job = jobs[jobIndex]
// this needs to be reassigned out because it is mutated by removal
if var queue = queues[job] {
switch queue.first {
case .none:
break
case .cancelled(let token):
self.items.removeValue(forKey: token)
// clean out any cancelled items
queue.removeFirst()
case .blocked(let token, let when, _):
if when <= now {
self.items.removeValue(forKey: token)
items.append(queue.removeFirst())
} else {
// this job is blocked by a wait
jobsToRemove.insert(jobIndex)
}
break
case .emit(let token, let when, _, _, _):
if when <= now {
self.items.removeValue(forKey: token)
items.append(queue.removeFirst())
} else {
// this job is blocked by a wait
jobsToRemove.insert(jobIndex)
}
break
case .work(let token, _):
self.items.removeValue(forKey: token)
items.append(queue.removeFirst())
}
queues[job] = queue
// if there is nothing left in this queue then don't bother with it anymore
if queue.count == 0 {
jobsToRemove.insert(jobIndex)
}
}
}
// clear out the iteration for the next pass
for index in jobsToRemove.sorted().reversed() {
jobs.remove(at: index)
}
// if we have not actually added anything in this loop
// or if there are no more jobs to work with
// break out of this particular drain
if items.count == startingCount || jobs.count == 0 {
break
}
}
return items
}
}
let state = ManagedCriticalState(State())
var now: AsyncSequenceValidationDiagram.Clock.Instant {
state.withCriticalRegion { $0.now }
}
struct Token: Hashable, CustomStringConvertible {
var generation: Int
var description: String {
return generation.description
}
}
func prepare() -> Token {
state.withCriticalRegion { state in
defer { state.generation += 1 }
return Token(generation: state.generation)
}
}
func cancel(_ token: Token) {
state.withCriticalRegion { state in
if let existing = state.items[token] {
// find any existing items that are present and patch them up as cancelled
let item = existing.cancelling()
state.items[token] = item
for (job, var queue) in state.queues {
var finished = false
for index in 0..<queue.count {
if queue[index].token == existing.token {
queue[index] = item
finished = true
break
}
}
state.queues[job] = queue
if finished {
break
}
}
} else {
// emit a tombstone for the enqueue
state.items[token] = .cancelled(token)
}
}
}
func enqueue(_ job: Job?, deadline: AsyncSequenceValidationDiagram.Clock.Instant, continuation: UnsafeContinuation<Void, Error>, token: Token) {
state.withCriticalRegion { state in
if state.queues[job] == nil, let job = job {
state.jobs.append(job)
}
if state.items[token]?.isCancelled == true {
let item: Item = .work(token, {
continuation.resume(throwing: CancellationError())
})
state.queues[job, default: []].append(item)
state.items[token] = item
} else {
let item: Item = .blocked(token, deadline, continuation)
state.queues[job, default: []].append(item)
state.items[token] = item
}
}
}
func enqueue(_ job: Job?, deadline: AsyncSequenceValidationDiagram.Clock.Instant, continuation: UnsafeContinuation<String?, Error>, _ result: Result<String?, Error>, index: Int, token: Token) {
state.withCriticalRegion { state in
if state.queues[job] == nil, let job = job {
state.jobs.append(job)
}
if state.items[token]?.isCancelled == true {
let item: Item = .work(token, {
continuation.resume(returning: nil) // the input sequences should not throw cancellation errors
})
state.queues[job, default: []].append(item)
state.items[token] = item
} else {
let item: Item = .emit(token, deadline, continuation, result, index)
state.queues[job, default: []].append(item)
state.items[token] = item
}
}
}
func enqueue(_ job: Job?, work: @Sendable @escaping () -> Void) {
state.withCriticalRegion { state in
if state.queues[job] == nil, let job = job {
state.jobs.append(job)
}
let token = Token(generation: state.generation)
let item: Item = .work(token, work)
state.queues[job, default: []].append(item)
state.generation += 1
state.items[token] = item
}
}
func drain() {
// keep draining until there is no recursive work to do
while true {
var items: [Item] = state.withCriticalRegion { $0.drain() }
if items.count == 0 {
break
}
// ensure deterministic order of execution
// first by source order, then by enqueue order
items.sort()
for item in items {
item.run()
}
}
}
func advance() {
// drain off the advancement
var items: [Item] = state.withCriticalRegion { state in
state.now = state.now.advanced(by: .steps(1))
return state.drain()
}
// ensure deterministic order of execution
// first by source order, then by enqueue order
items.sort()
for item in items {
item.run()
}
// and cleanup any additional recursive items
drain()
}
}
@@ -1,248 +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
//
//===----------------------------------------------------------------------===//
#include <stdint.h>
#if !defined(__has_feature)
#define __has_feature(x) 0
#endif
#if !defined(__has_attribute)
#define __has_attribute(x) 0
#endif
#if !defined(__has_builtin)
#define __has_builtin(builtin) 0
#endif
#if !defined(__has_cpp_attribute)
#define __has_cpp_attribute(attribute) 0
#endif
// TODO: These macro definitions are duplicated in BridgedSwiftObject.h. Move
// them to a single file if we find a location that both Visibility.h and
// BridgedSwiftObject.h can import.
#if __has_feature(nullability)
// Provide macros to temporarily suppress warning about the use of
// _Nullable and _Nonnull.
# define SWIFT_BEGIN_NULLABILITY_ANNOTATIONS \
_Pragma("clang diagnostic push") \
_Pragma("clang diagnostic ignored \"-Wnullability-extension\"")
# define SWIFT_END_NULLABILITY_ANNOTATIONS \
_Pragma("clang diagnostic pop")
#else
// #define _Nullable and _Nonnull to nothing if we're not being built
// with a compiler that supports them.
# define _Nullable
# define _Nonnull
# define SWIFT_BEGIN_NULLABILITY_ANNOTATIONS
# define SWIFT_END_NULLABILITY_ANNOTATIONS
#endif
#define SWIFT_MACRO_CONCAT(A, B) A ## B
#define SWIFT_MACRO_IF_0(IF_TRUE, IF_FALSE) IF_FALSE
#define SWIFT_MACRO_IF_1(IF_TRUE, IF_FALSE) IF_TRUE
#define SWIFT_MACRO_IF(COND, IF_TRUE, IF_FALSE) \
SWIFT_MACRO_CONCAT(SWIFT_MACRO_IF_, COND)(IF_TRUE, IF_FALSE)
#if __has_attribute(pure)
#define SWIFT_READONLY __attribute__((__pure__))
#else
#define SWIFT_READONLY
#endif
#if __has_attribute(const)
#define SWIFT_READNONE __attribute__((__const__))
#else
#define SWIFT_READNONE
#endif
#if __has_attribute(always_inline)
#define SWIFT_ALWAYS_INLINE __attribute__((always_inline))
#else
#define SWIFT_ALWAYS_INLINE
#endif
#if __has_attribute(noinline)
#define SWIFT_NOINLINE __attribute__((__noinline__))
#else
#define SWIFT_NOINLINE
#endif
#if __has_attribute(noreturn)
#define SWIFT_NORETURN __attribute__((__noreturn__))
#else
#define SWIFT_NORETURN
#endif
#if __has_attribute(used)
#define SWIFT_USED __attribute__((__used__))
#else
#define SWIFT_USED
#endif
#if __has_attribute(unavailable)
#define SWIFT_ATTRIBUTE_UNAVAILABLE __attribute__((__unavailable__))
#else
#define SWIFT_ATTRIBUTE_UNAVAILABLE
#endif
#if (__has_attribute(weak_import))
#define SWIFT_WEAK_IMPORT __attribute__((weak_import))
#else
#define SWIFT_WEAK_IMPORT
#endif
// Define the appropriate attributes for sharing symbols across
// image (executable / shared-library) boundaries.
//
// SWIFT_ATTRIBUTE_FOR_EXPORTS will be placed on declarations that
// are known to be exported from the current image. Typically, they
// are placed on header declarations and then inherited by the actual
// definitions.
//
// SWIFT_ATTRIBUTE_FOR_IMPORTS will be placed on declarations that
// are known to be exported from a different image. This never
// includes a definition.
//
// Getting the right attribute on a declaratioon can be pretty awkward,
// but it's necessary under the C translation model. All of this
// ceremony is familiar to Windows programmers; C/C++ programmers
// everywhere else usually don't bother, but since we have to get it
// right for Windows, we have everything set up to get it right on
// other targets as well, and doing so lets the compiler use more
// efficient symbol access patterns.
#if defined(__MACH__) || defined(__wasi__)
// On Mach-O and WebAssembly, we use non-hidden visibility. We just use
// default visibility on both imports and exports, both because these
// targets don't support protected visibility but because they don't
// need it: symbols are not interposable outside the current image
// by default.
# define SWIFT_ATTRIBUTE_FOR_EXPORTS __attribute__((__visibility__("default")))
# define SWIFT_ATTRIBUTE_FOR_IMPORTS __attribute__((__visibility__("default")))
#elif defined(__ELF__)
// On ELF, we use non-hidden visibility. For exports, we must use
// protected visibility to tell the compiler and linker that the symbols
// can't be interposed outside the current image. For imports, we must
// use default visibility because protected visibility guarantees that
// the symbol is defined in the current library, which isn't true for
// an import.
//
// The compiler does assume that the runtime and standard library can
// refer to each other's symbols as DSO-local, so it's important that
// we get this right or we can get linker errors.
# define SWIFT_ATTRIBUTE_FOR_EXPORTS __attribute__((__visibility__("protected")))
# define SWIFT_ATTRIBUTE_FOR_IMPORTS __attribute__((__visibility__("default")))
#elif defined(__CYGWIN__)
// For now, we ignore all this on Cygwin.
# define SWIFT_ATTRIBUTE_FOR_EXPORTS
# define SWIFT_ATTRIBUTE_FOR_IMPORTS
// FIXME: this #else should be some sort of #elif Windows
#else // !__MACH__ && !__ELF__
// On PE/COFF, we use dllimport and dllexport.
# define SWIFT_ATTRIBUTE_FOR_EXPORTS __declspec(dllexport)
# define SWIFT_ATTRIBUTE_FOR_IMPORTS __declspec(dllimport)
#endif
// CMake conventionally passes -DlibraryName_EXPORTS when building
// code that goes into libraryName. This isn't the best macro name,
// but it's conventional. We do have to pass it explicitly in a few
// places in the build system for a variety of reasons.
//
// Unfortunately, defined(D) is a special function you can use in
// preprocessor conditions, not a macro you can use anywhere, so we
// need to manually check for all the libraries we know about so that
// we can use them in our condition below.s
#if defined(swiftCore_EXPORTS)
#define SWIFT_IMAGE_EXPORTS_swiftCore 1
#else
#define SWIFT_IMAGE_EXPORTS_swiftCore 0
#endif
#if defined(swift_Concurrency_EXPORTS)
#define SWIFT_IMAGE_EXPORTS_swift_Concurrency 1
#else
#define SWIFT_IMAGE_EXPORTS_swift_Concurrency 0
#endif
#if defined(swift_Distributed_EXPORTS)
#define SWIFT_IMAGE_EXPORTS_swift_Distributed 1
#else
#define SWIFT_IMAGE_EXPORTS_swift_Distributed 0
#endif
#if defined(swift_Differentiation_EXPORTS)
#define SWIFT_IMAGE_EXPORTS_swift_Differentiation 1
#else
#define SWIFT_IMAGE_EXPORTS_swift_Differentiation 0
#endif
#define SWIFT_EXPORT_FROM_ATTRIBUTE(LIBRARY) \
SWIFT_MACRO_IF(SWIFT_IMAGE_EXPORTS_##LIBRARY, \
SWIFT_ATTRIBUTE_FOR_EXPORTS, \
SWIFT_ATTRIBUTE_FOR_IMPORTS)
// SWIFT_EXPORT_FROM(LIBRARY) declares something to be a C-linkage
// entity exported by the given library.
//
// SWIFT_RUNTIME_EXPORT is just SWIFT_EXPORT_FROM(swiftCore).
//
// TODO: use this in shims headers in overlays.
#if defined(__cplusplus)
#define SWIFT_EXPORT_FROM(LIBRARY) extern "C" SWIFT_EXPORT_FROM_ATTRIBUTE(LIBRARY)
#define SWIFT_EXPORT extern "C"
#else
#define SWIFT_EXPORT extern
#define SWIFT_EXPORT_FROM(LIBRARY) SWIFT_EXPORT_FROM_ATTRIBUTE(LIBRARY)
#endif
#define SWIFT_RUNTIME_EXPORT SWIFT_EXPORT_FROM(swiftCore)
// Define mappings for calling conventions.
// Annotation for specifying a calling convention of
// a runtime function. It should be used with declarations
// of runtime functions like this:
// void runtime_function_name() SWIFT_CC(swift)
#define SWIFT_CC(CC) SWIFT_CC_##CC
// SWIFT_CC(c) is the C calling convention.
#define SWIFT_CC_c
// SWIFT_CC(swift) is the Swift calling convention.
// FIXME: the next comment is false.
// Functions outside the stdlib or runtime that include this file may be built
// with a compiler that doesn't support swiftcall; don't define these macros
// in that case so any incorrect usage is caught.
#if __has_attribute(swiftcall)
#define SWIFT_CC_swift __attribute__((swiftcall))
#define SWIFT_CONTEXT __attribute__((swift_context))
#define SWIFT_ERROR_RESULT __attribute__((swift_error_result))
#define SWIFT_INDIRECT_RESULT __attribute__((swift_indirect_result))
#else
#define SWIFT_CC_swift
#define SWIFT_CONTEXT
#define SWIFT_ERROR_RESULT
#define SWIFT_INDIRECT_RESULT
#endif
typedef struct _Job* JobRef;
typedef SWIFT_CC(swift) void (*swift_task_enqueueGlobal_original)(JobRef _Nonnull job);
SWIFT_EXPORT_FROM(swift_Concurrency)
SWIFT_CC(swift) void (* _Nullable swift_task_enqueueGlobal_hook)(
JobRef _Nonnull job, swift_task_enqueueGlobal_original _Nonnull original);
@@ -1,4 +0,0 @@
module _CAsyncSequenceValidationSupport [system] {
header "_CAsyncSequenceValidationSupport.h"
export *
}
@@ -1,68 +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
//
//===----------------------------------------------------------------------===//
import XCTest
import AsyncAlgorithms
#if canImport(Darwin)
final class TestThroughput: XCTestCase {
func test_chain2() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2) {
chain($0, $1)
}
}
func test_chain3() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2, thirdOutput: 3) {
chain($0, $1, $2)
}
}
func test_compacted() async {
await measureSequenceThroughput(output: .some(1)) {
$0.compacted()
}
}
func test_interspersed() async {
await measureSequenceThroughput(output: 1) {
$0.interspersed(with: 0)
}
}
func test_joined() async {
await measureSequenceThroughput(output: [1, 2, 3, 4, 5].async) {
$0.joined(separator: [0, 0, 0, 0, 0].async)
}
}
func test_merge2() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2) {
merge($0, $1)
}
}
func test_merge3() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2, thirdOutput: 3) {
merge($0, $1, $2)
}
}
func test_removeDuplicates() async {
await measureSequenceThroughput(source: (1...).async) {
$0.removeDuplicates()
}
}
func test_zip2() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2) {
zip($0, $1)
}
}
func test_zip3() async {
await measureSequenceThroughput(firstOutput: 1, secondOutput: 2, thirdOutput: 3) {
zip($0, $1, $2)
}
}
}
#endif
@@ -1,186 +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
//
//===----------------------------------------------------------------------===//
import AsyncAlgorithms
import Foundation
@preconcurrency import XCTest
#if canImport(Darwin)
public struct InfiniteAsyncSequence<Value: Sendable>: AsyncSequence, Sendable {
public typealias Element = Value
let value: Value
public struct AsyncIterator : AsyncIteratorProtocol, Sendable {
@usableFromInline
let value: Value
@inlinable
public mutating func next() async throws -> Element? {
guard !Task.isCancelled else {
return nil
}
return value
}
}
public func makeAsyncIterator() -> AsyncIterator {
return AsyncIterator(value: value)
}
}
final class _ThroughputMetric: NSObject, XCTMetric, @unchecked Sendable {
var eventCount = 0
override init() { }
func reportMeasurements(from startTime: XCTPerformanceMeasurementTimestamp, to endTime: XCTPerformanceMeasurementTimestamp) throws -> [XCTPerformanceMeasurement] {
return [XCTPerformanceMeasurement(identifier: "com.swift.AsyncAlgorithms.Throughput", displayName: "Throughput", doubleValue: Double(eventCount) / (endTime.date.timeIntervalSinceReferenceDate - startTime.date.timeIntervalSinceReferenceDate), unitSymbol: " Events/sec", polarity: .prefersLarger)]
}
func copy(with zone: NSZone? = nil) -> Any {
return self
}
func willBeginMeasuring() {
eventCount = 0
}
func didStopMeasuring() { }
}
extension XCTestCase {
public func measureSequenceThroughput<S: AsyncSequence, Output>( output: @autoclosure () -> Output, _ sequenceBuilder: (InfiniteAsyncSequence<Output>) -> S) async where S: Sendable {
let metric = _ThroughputMetric()
let sampleTime: Double = 0.1
measure(metrics: [metric]) {
let infSeq = InfiniteAsyncSequence(value: output())
let seq = sequenceBuilder(infSeq)
let exp = self.expectation(description: "Finished")
let iterTask = Task<Int, Error> {
var eventCount = 0
for try await _ in seq {
eventCount += 1
}
metric.eventCount = eventCount
exp.fulfill()
return eventCount
}
usleep(UInt32(sampleTime * Double(USEC_PER_SEC)))
iterTask.cancel()
self.wait(for: [exp], timeout: sampleTime * 2)
}
}
public func measureSequenceThroughput<S: AsyncSequence, Output>(firstOutput: @autoclosure () -> Output, secondOutput: @autoclosure () -> Output, _ sequenceBuilder: (InfiniteAsyncSequence<Output>, InfiniteAsyncSequence<Output>) -> S) async where S: Sendable {
let metric = _ThroughputMetric()
let sampleTime: Double = 0.1
measure(metrics: [metric]) {
let firstInfSeq = InfiniteAsyncSequence(value: firstOutput())
let secondInfSeq = InfiniteAsyncSequence(value: secondOutput())
let seq = sequenceBuilder(firstInfSeq, secondInfSeq)
let exp = self.expectation(description: "Finished")
let iterTask = Task<Int, Error> {
var eventCount = 0
for try await _ in seq {
eventCount += 1
}
metric.eventCount = eventCount
exp.fulfill()
return eventCount
}
usleep(UInt32(sampleTime * Double(USEC_PER_SEC)))
iterTask.cancel()
self.wait(for: [exp], timeout: sampleTime * 2)
}
}
public func measureSequenceThroughput<S: AsyncSequence, Output>(firstOutput: @autoclosure () -> Output, secondOutput: @autoclosure () -> Output, thirdOutput: @autoclosure () -> Output, _ sequenceBuilder: (InfiniteAsyncSequence<Output>, InfiniteAsyncSequence<Output>, InfiniteAsyncSequence<Output>) -> S) async where S: Sendable {
let metric = _ThroughputMetric()
let sampleTime: Double = 0.1
measure(metrics: [metric]) {
let firstInfSeq = InfiniteAsyncSequence(value: firstOutput())
let secondInfSeq = InfiniteAsyncSequence(value: secondOutput())
let thirdInfSeq = InfiniteAsyncSequence(value: thirdOutput())
let seq = sequenceBuilder(firstInfSeq, secondInfSeq, thirdInfSeq)
let exp = self.expectation(description: "Finished")
let iterTask = Task<Int, Error> {
var eventCount = 0
for try await _ in seq {
eventCount += 1
}
metric.eventCount = eventCount
exp.fulfill()
return eventCount
}
usleep(UInt32(sampleTime * Double(USEC_PER_SEC)))
iterTask.cancel()
self.wait(for: [exp], timeout: sampleTime * 2)
}
}
public func measureSequenceThroughput<S: AsyncSequence, Source: AsyncSequence>( source: Source, _ sequenceBuilder: (Source) -> S) async where S: Sendable, Source: Sendable {
let metric = _ThroughputMetric()
let sampleTime: Double = 0.1
measure(metrics: [metric]) {
let infSeq = source
let seq = sequenceBuilder(infSeq)
let exp = self.expectation(description: "Finished")
let iterTask = Task<Int, Error> {
var eventCount = 0
for try await _ in seq {
eventCount += 1
}
metric.eventCount = eventCount
exp.fulfill()
return eventCount
}
usleep(UInt32(sampleTime * Double(USEC_PER_SEC)))
iterTask.cancel()
self.wait(for: [exp], timeout: sampleTime * 2)
}
}
}
final class TestMeasurements: XCTestCase {
struct PassthroughSequence<S: AsyncSequence> : AsyncSequence, Sendable where S : Sendable, S.AsyncIterator : Sendable {
typealias Element = S.Element
struct AsyncIterator : AsyncIteratorProtocol, Sendable {
@usableFromInline
var base : S.AsyncIterator
@inlinable
mutating func next() async throws -> Element? {
return try await base.next()
}
}
let base : S
func makeAsyncIterator() -> AsyncIterator {
.init(base: base.makeAsyncIterator())
}
}
public func testThroughputTesting() async {
await self.measureSequenceThroughput(output: 1) {
PassthroughSequence(base: $0)
}
}
}
#endif
@@ -1,152 +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
//
//===----------------------------------------------------------------------===//
import XCTest
fileprivate enum _XCTAssertion {
case equal
case equalWithAccuracy
case identical
case notIdentical
case greaterThan
case greaterThanOrEqual
case lessThan
case lessThanOrEqual
case notEqual
case notEqualWithAccuracy
case `nil`
case notNil
case unwrap
case `true`
case `false`
case fail
case throwsError
case noThrow
var name: String? {
switch(self) {
case .equal: return "XCTAssertEqual"
case .equalWithAccuracy: return "XCTAssertEqual"
case .identical: return "XCTAssertIdentical"
case .notIdentical: return "XCTAssertNotIdentical"
case .greaterThan: return "XCTAssertGreaterThan"
case .greaterThanOrEqual: return "XCTAssertGreaterThanOrEqual"
case .lessThan: return "XCTAssertLessThan"
case .lessThanOrEqual: return "XCTAssertLessThanOrEqual"
case .notEqual: return "XCTAssertNotEqual"
case .notEqualWithAccuracy: return "XCTAssertNotEqual"
case .`nil`: return "XCTAssertNil"
case .notNil: return "XCTAssertNotNil"
case .unwrap: return "XCTUnwrap"
case .`true`: return "XCTAssertTrue"
case .`false`: return "XCTAssertFalse"
case .throwsError: return "XCTAssertThrowsError"
case .noThrow: return "XCTAssertNoThrow"
case .fail: return nil
}
}
}
fileprivate enum _XCTAssertionResult {
case success
case expectedFailure(String?)
case unexpectedFailure(Swift.Error)
var isExpected: Bool {
switch self {
case .unexpectedFailure(_): return false
default: return true
}
}
func failureDescription(_ assertion: _XCTAssertion) -> String {
let explanation: String
switch self {
case .success: explanation = "passed"
case .expectedFailure(let details?): explanation = "failed: \(details)"
case .expectedFailure(_): explanation = "failed"
case .unexpectedFailure(let error): explanation = "threw error \"\(error)\""
}
if let name = assertion.name {
return "\(name) \(explanation)"
} else {
return explanation
}
}
}
private func _XCTEvaluateAssertion(_ assertion: _XCTAssertion, message: () -> String, file: StaticString, line: UInt, expression: () throws -> _XCTAssertionResult) {
let result: _XCTAssertionResult
do {
result = try expression()
} catch {
result = .unexpectedFailure(error)
}
switch result {
case .success:
return
default:
XCTFail("\(result.failureDescription(assertion)) - \(message())", file: file, line: line)
}
}
fileprivate func _XCTAssertEqual<T>(_ expression1: () throws -> T, _ expression2: () throws -> T, _ equal: (T, T) -> Bool, _ message: () -> String, file: StaticString = #filePath, line: UInt = #line) {
_XCTEvaluateAssertion(.equal, message: message, file: file, line: line) {
let (value1, value2) = (try expression1(), try expression2())
if equal(value1, value2) {
return .success
} else {
return .expectedFailure("(\"\(value1)\") is not equal to (\"\(value2)\")")
}
}
}
public func XCTAssertEqual<A: Equatable, B: Equatable>(_ expression1: @autoclosure () throws -> (A, B), _ expression2: @autoclosure () throws -> (A, B), _ message: @autoclosure () -> String = "", file: StaticString = #filePath, line: UInt = #line) {
_XCTAssertEqual(expression1, expression2, { $0 == $1 }, message, file: file, line: line)
}
fileprivate func ==<A: Equatable, B: Equatable>(_ lhs: [(A, B)], _ rhs: [(A, B)]) -> Bool {
guard lhs.count == rhs.count else {
return false
}
for (lhsElement, rhsElement) in zip(lhs, rhs) {
if lhsElement != rhsElement {
return false
}
}
return true
}
public func XCTAssertEqual<A: Equatable, B: Equatable>(_ expression1: @autoclosure () throws -> [(A, B)], _ expression2: @autoclosure () throws -> [(A, B)], _ message: @autoclosure () -> String = "", file: StaticString = #filePath, line: UInt = #line) {
_XCTAssertEqual(expression1, expression2, { $0 == $1 }, message, file: file, line: line)
}
public func XCTAssertEqual<A: Equatable, B: Equatable, C: Equatable>(_ expression1: @autoclosure () throws -> (A, B, C), _ expression2: @autoclosure () throws -> (A, B, C), _ message: @autoclosure () -> String = "", file: StaticString = #filePath, line: UInt = #line) {
_XCTAssertEqual(expression1, expression2, { $0 == $1 }, message, file: file, line: line)
}
fileprivate func ==<A: Equatable, B: Equatable, C: Equatable>(_ lhs: [(A, B, C)], _ rhs: [(A, B, C)]) -> Bool {
guard lhs.count == rhs.count else {
return false
}
for (lhsElement, rhsElement) in zip(lhs, rhs) {
if lhsElement != rhsElement {
return false
}
}
return true
}
public func XCTAssertEqual<A: Equatable, B: Equatable, C: Equatable>(_ expression1: @autoclosure () throws -> [(A, B, C)], _ expression2: @autoclosure () throws -> [(A, B, C)], _ message: @autoclosure () -> String = "", file: StaticString = #filePath, line: UInt = #line) {
_XCTAssertEqual(expression1, expression2, { $0 == $1 }, message, file: file, line: line)
}
@@ -1,19 +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 Failure: Error, Equatable { }
func throwOn<T: Equatable>(_ toThrowOn: T, _ value: T) throws -> T {
if value == toThrowOn {
throw Failure()
}
return value
}
@@ -1,58 +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
//
//===----------------------------------------------------------------------===//
import AsyncAlgorithms
public struct Gate: Sendable {
enum State {
case closed
case open
case pending(UnsafeContinuation<Void, Never>)
}
let state = ManagedCriticalState(State.closed)
public func `open`() {
state.withCriticalRegion { state -> UnsafeContinuation<Void, Never>? in
switch state {
case .closed:
state = .open
return nil
case .open:
return nil
case .pending(let continuation):
state = .closed
return continuation
}
}?.resume()
}
public func enter() async {
var other: UnsafeContinuation<Void, Never>?
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
state.withCriticalRegion { state -> UnsafeContinuation<Void, Never>? in
switch state {
case .closed:
state = .pending(continuation)
return nil
case .open:
state = .closed
return continuation
case .pending(let existing):
other = existing
state = .pending(continuation)
return nil
}
}?.resume()
}
other?.resume()
}
}
@@ -1,55 +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
//
//===----------------------------------------------------------------------===//
public struct GatedSequence<Element> {
let elements: [Element]
let gates: [Gate]
var index = 0
public mutating func advance() {
defer { index += 1 }
guard index < gates.count else {
return
}
gates[index].open()
}
public init(_ elements: [Element]) {
self.elements = elements
self.gates = elements.map { _ in Gate() }
}
}
extension GatedSequence: AsyncSequence {
public struct Iterator: AsyncIteratorProtocol {
var gatedElements: [(Element, Gate)]
init(elements: [Element], gates: [Gate]) {
gatedElements = Array(zip(elements, gates))
}
public mutating func next() async -> Element? {
guard gatedElements.count > 0 else {
return nil
}
let (element, gate) = gatedElements.removeFirst()
await gate.enter()
return element
}
}
public func makeAsyncIterator() -> Iterator {
Iterator(elements: elements, gates: gates)
}
}
extension GatedSequence: Sendable where Element: Sendable { }
extension GatedSequence.Iterator: Sendable where Element: Sendable { }
@@ -1,22 +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 Indefinite<Element: Sendable>: Sequence, IteratorProtocol, Sendable {
let value: Element
func next() -> Element? {
return value
}
func makeIterator() -> Indefinite<Element> {
self
}
}
@@ -1 +0,0 @@
../../../Sources/AsyncAlgorithms/Locking.swift
@@ -1,255 +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
//
//===----------------------------------------------------------------------===//
import AsyncAlgorithms
public struct ManualClock: Clock {
public struct Step: DurationProtocol {
fileprivate var rawValue: Int
fileprivate init(_ rawValue: Int) {
self.rawValue = rawValue
}
public static func + (lhs: ManualClock.Step, rhs: ManualClock.Step) -> ManualClock.Step {
return .init(lhs.rawValue + rhs.rawValue)
}
public static func - (lhs: ManualClock.Step, rhs: ManualClock.Step) -> ManualClock.Step {
.init(lhs.rawValue - rhs.rawValue)
}
public static func / (lhs: ManualClock.Step, rhs: Int) -> ManualClock.Step {
.init(lhs.rawValue / rhs)
}
public static func * (lhs: ManualClock.Step, rhs: Int) -> ManualClock.Step {
.init(lhs.rawValue * rhs)
}
public static func / (lhs: ManualClock.Step, rhs: ManualClock.Step) -> Double {
Double(lhs.rawValue) / Double(rhs.rawValue)
}
public static func < (lhs: ManualClock.Step, rhs: ManualClock.Step) -> Bool {
lhs.rawValue < rhs.rawValue
}
public static var zero: ManualClock.Step { .init(0) }
public static func steps(_ amount: Int) -> Step {
return Step(amount)
}
}
public struct Instant: InstantProtocol, CustomStringConvertible {
public typealias Duration = Step
internal let rawValue: Int
internal init(_ rawValue: Int) {
self.rawValue = rawValue
}
public static func < (lhs: ManualClock.Instant, rhs: ManualClock.Instant) -> Bool {
return lhs.rawValue < rhs.rawValue
}
public func advanced(by duration: ManualClock.Step) -> ManualClock.Instant {
.init(rawValue + duration.rawValue)
}
public func duration(to other: ManualClock.Instant) -> ManualClock.Step {
.init(other.rawValue - rawValue)
}
public var description: String {
return "tick \(rawValue)"
}
}
fileprivate struct Wakeup {
let generation: Int
let continuation: UnsafeContinuation<Void, Error>
let deadline: Instant
}
fileprivate enum Scheduled: Hashable, Comparable, CustomStringConvertible {
case cancelled(Int)
case wakeup(Wakeup)
func hash(into hasher: inout Hasher) {
switch self {
case .cancelled(let generation):
hasher.combine(generation)
case .wakeup(let wakeup):
hasher.combine(wakeup.generation)
}
}
var description: String {
switch self {
case .cancelled: return "Cancelled wakeup"
case .wakeup(let wakeup): return "Wakeup at \(wakeup.deadline)"
}
}
static func == (_ lhs: Scheduled, _ rhs: Scheduled) -> Bool {
switch (lhs, rhs) {
case (.cancelled(let lhsGen), .cancelled(let rhsGen)):
return lhsGen == rhsGen
case (.cancelled(let lhsGen), .wakeup(let rhs)):
return lhsGen == rhs.generation
case (.wakeup(let lhs), .cancelled(let rhsGen)):
return lhs.generation == rhsGen
case (.wakeup(let lhs), .wakeup(let rhs)):
return lhs.generation == rhs.generation
}
}
static func < (lhs: ManualClock.Scheduled, rhs: ManualClock.Scheduled) -> Bool {
switch (lhs, rhs) {
case (.cancelled(let lhsGen), .cancelled(let rhsGen)):
return lhsGen < rhsGen
case (.cancelled(let lhsGen), .wakeup(let rhs)):
return lhsGen < rhs.generation
case (.wakeup(let lhs), .cancelled(let rhsGen)):
return lhs.generation < rhsGen
case (.wakeup(let lhs), .wakeup(let rhs)):
return lhs.generation < rhs.generation
}
}
var deadline: Instant? {
switch self {
case .cancelled: return nil
case .wakeup(let wakeup): return wakeup.deadline
}
}
func resume() {
switch self {
case .wakeup(let wakeup):
wakeup.continuation.resume()
default:
break
}
}
}
fileprivate struct State {
var generation = 0
var scheduled = Set<Scheduled>()
var now = Instant(0)
var hasSleepers = false
}
fileprivate let state = ManagedCriticalState(State())
public var now: Instant {
state.withCriticalRegion { $0.now }
}
public var minimumResolution: Step { return .zero }
public init() { }
fileprivate func cancel(_ generation: Int) {
state.withCriticalRegion { state -> UnsafeContinuation<Void, Error>? in
if let existing = state.scheduled.remove(.cancelled(generation)) {
switch existing {
case .wakeup(let wakeup):
return wakeup.continuation
default:
return nil
}
} else {
// insert the cancelled state for when it comes in to be scheduled as a wakeup
state.scheduled.insert(.cancelled(generation))
return nil
}
}?.resume(throwing: CancellationError())
}
var hasSleepers: Bool {
state.withCriticalRegion { $0.hasSleepers }
}
public func advance() {
let pending = state.withCriticalRegion { state -> Set<Scheduled> in
state.now = state.now.advanced(by: .steps(1))
let pending = state.scheduled.filter { item in
if let deadline = item.deadline {
return deadline <= state.now
} else {
return false
}
}
state.scheduled.subtract(pending)
if pending.count > 0 {
state.hasSleepers = false
}
return pending
}
for item in pending.sorted() {
item.resume()
}
}
public func advance(by steps: Step) {
for _ in 0..<steps.rawValue {
advance()
}
}
fileprivate func schedule(_ generation: Int, continuation: UnsafeContinuation<Void, Error>, deadline: Instant) {
let resumption = state.withCriticalRegion { state -> (UnsafeContinuation<Void, Error>, Result<Void, Error>)? in
let wakeup = Wakeup(generation: generation, continuation: continuation, deadline: deadline)
if let existing = state.scheduled.remove(.wakeup(wakeup)) {
switch existing {
case .wakeup:
fatalError()
case .cancelled:
// dont bother adding it back because it has been cancelled before we got here
return (continuation, .failure(CancellationError()))
}
} else {
// there is no cancelled placeholder so let it run free
if deadline > state.now {
// the deadline is in the future so run it then
state.hasSleepers = true
state.scheduled.insert(.wakeup(wakeup))
return nil
} else {
// the deadline is now or in the past so run it immediately
return (continuation, .success(()))
}
}
}
if let resumption = resumption {
resumption.0.resume(with: resumption.1)
}
}
public func sleep(until deadline: Instant, tolerance: Step? = nil) async throws {
let generation = state.withCriticalRegion { state -> Int in
defer { state.generation += 1 }
return state.generation
}
try await withTaskCancellationHandler {
cancel(generation)
} operation: {
try await withUnsafeThrowingContinuation { continuation in
schedule(generation, continuation: continuation, deadline: deadline)
}
}
}
}
@@ -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
//
//===----------------------------------------------------------------------===//
final class ReportingSequence<Element>: Sequence, IteratorProtocol {
enum Event: Equatable, CustomStringConvertible {
case next
case makeIterator
var description: String {
switch self {
case .next: return "next()"
case .makeIterator: return "makeIterator()"
}
}
}
var events = [Event]()
var elements: [Element]
init(_ elements: [Element]) {
self.elements = elements
}
func next() -> Element? {
events.append(.next)
guard elements.count > 0 else {
return nil
}
return elements.removeFirst()
}
func makeIterator() -> ReportingSequence {
events.append(.makeIterator)
return self
}
}
final class ReportingAsyncSequence<Element>: AsyncSequence, AsyncIteratorProtocol {
enum Event: Equatable, CustomStringConvertible {
case next
case makeAsyncIterator
var description: String {
switch self {
case .next: return "next()"
case .makeAsyncIterator: return "makeAsyncIterator()"
}
}
}
var events = [Event]()
var elements: [Element]
init(_ elements: [Element]) {
self.elements = elements
}
func next() async -> Element? {
events.append(.next)
guard elements.count > 0 else {
return nil
}
return elements.removeFirst()
}
func makeAsyncIterator() -> ReportingAsyncSequence {
events.append(.makeAsyncIterator)
return self
}
}
@@ -1,117 +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
//
//===----------------------------------------------------------------------===//
import AsyncAlgorithms
public struct Validator<Element: Sendable>: Sendable {
private enum Ready {
case idle
case ready
case pending(UnsafeContinuation<Void, Never>)
}
private struct State: Sendable {
var collected = [Element]()
var failure: Error?
var ready: Ready = .idle
}
private struct Envelope<Contents>: @unchecked Sendable {
var contents: Contents
}
private let state = ManagedCriticalState(State())
private func ready(_ apply: (inout State) -> Void) {
state.withCriticalRegion { state -> UnsafeContinuation<Void, Never>? in
apply(&state)
switch state.ready {
case .idle:
state.ready = .ready
return nil
case .pending(let continuation):
state.ready = .idle
return continuation
case .ready:
return nil
}
}?.resume()
}
internal func step() async {
await withUnsafeContinuation { (continuation: UnsafeContinuation<Void, Never>) in
state.withCriticalRegion { state -> UnsafeContinuation<Void, Never>? in
switch state.ready {
case .ready:
state.ready = .idle
return continuation
case .idle:
state.ready = .pending(continuation)
return nil
case .pending:
fatalError()
}
}?.resume()
}
}
let onEvent: (@Sendable (Result<Element?, Error>) async -> Void)?
init(onEvent: @Sendable @escaping (Result<Element?, Error>) async -> Void) {
self.onEvent = onEvent
}
public init() {
self.onEvent = nil
}
public func test<S: AsyncSequence>(_ sequence: S, onFinish: @Sendable @escaping (inout S.AsyncIterator) async -> Void) where S.Element == Element {
let envelope = Envelope(contents: sequence)
Task {
var iterator = envelope.contents.makeAsyncIterator()
ready { _ in }
do {
while let item = try await iterator.next() {
await onEvent?(.success(item))
ready { state in
state.collected.append(item)
}
}
await onEvent?(.success(nil))
} catch {
await onEvent?(.failure(error))
ready { state in
state.failure = error
}
}
ready { _ in }
await onFinish(&iterator)
}
}
public func validate() async -> [Element] {
await step()
return current
}
public var current: [Element] {
return state.withCriticalRegion { state in
return state.collected
}
}
public var failure: Error? {
return state.withCriticalRegion { state in
return state.failure
}
}
}
@@ -1,73 +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 {
func violatingSpecification(returningPastEndIteration element: Element) -> SpecificationViolatingSequence<Self> {
SpecificationViolatingSequence(self, kind: .producing(element))
}
func violatingSpecification(throwingPastEndIteration error: Error) -> SpecificationViolatingSequence<Self> {
SpecificationViolatingSequence(self, kind: .throwing(error))
}
}
struct SpecificationViolatingSequence<Base: AsyncSequence> {
enum Kind {
case producing(Base.Element)
case throwing(Error)
}
let base: Base
let kind: Kind
init(_ base: Base, kind: Kind) {
self.base = base
self.kind = kind
}
}
extension SpecificationViolatingSequence: AsyncSequence {
typealias Element = Base.Element
struct Iterator: AsyncIteratorProtocol {
var iterator: Base.AsyncIterator
let kind: Kind
var finished = false
var violated = false
mutating func next() async throws -> Element? {
if finished {
if violated {
return nil
}
violated = true
switch kind {
case .producing(let element): return element
case .throwing(let error): throw error
}
}
do {
if let value = try await iterator.next() {
return value
}
finished = true
return nil
} catch {
finished = true
throw error
}
}
}
func makeAsyncIterator() -> Iterator {
Iterator(iterator: base.makeAsyncIterator(), kind: kind)
}
}
@@ -1,60 +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
//
//===----------------------------------------------------------------------===//
@preconcurrency import XCTest
import AsyncAlgorithms
final class TestAdjacentPairs: XCTestCase {
func test_adjacentPairs() async {
let source = 1...5
let expected = [(1,2), (2,3), (3,4), (4,5)]
let sequence = source.async.adjacentPairs()
var actual: [(Int, Int)] = []
for await item in sequence {
actual.append(item)
}
XCTAssertEqual(expected, actual)
}
func test_empty() async {
let source = 0..<1
let expected: [(Int, Int)] = []
let sequence = source.async.adjacentPairs()
var actual: [(Int, Int)] = []
for await item in sequence {
actual.append(item)
}
XCTAssertEqual(expected, actual)
}
func test_cancellation() async {
let source = Indefinite(value: 0)
let sequence = source.async.adjacentPairs()
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
for await _ in sequence {
if !firstIteration {
firstIteration = true
iterated.fulfill()
}
}
finished.fulfill()
}
// ensure the other task actually starts
wait(for: [iterated], timeout: 1.0)
// cancellation should ensure the loop finishes
// without regards to the remaining underlying sequence
task.cancel()
wait(for: [finished], timeout: 1.0)
}
}
-481
View File
@@ -1,481 +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
//
//===----------------------------------------------------------------------===//
@preconcurrency import XCTest
import AsyncAlgorithms
final class TestBuffer: XCTestCase {
func test_buffering() async {
var gated = GatedSequence([1, 2, 3, 4, 5])
let sequence = gated.buffer(policy: .unbounded)
var iterator = sequence.makeAsyncIterator()
gated.advance()
var value = await iterator.next()
XCTAssertEqual(value, 1)
gated.advance()
gated.advance()
gated.advance()
value = await iterator.next()
XCTAssertEqual(value, 2)
value = await iterator.next()
XCTAssertEqual(value, 3)
value = await iterator.next()
XCTAssertEqual(value, 4)
gated.advance()
gated.advance()
value = await iterator.next()
XCTAssertEqual(value, 5)
value = await iterator.next()
XCTAssertEqual(value, nil)
value = await iterator.next()
XCTAssertEqual(value, nil)
}
func test_buffering_withError() async {
var gated = GatedSequence([1, 2, 3, 4, 5, 6, 7])
let gated_map = gated.map { try throwOn(3, $0) }
let sequence = gated_map.buffer(policy: .unbounded)
var iterator = sequence.makeAsyncIterator()
gated.advance()
var value = try! await iterator.next()
XCTAssertEqual(value, 1)
gated.advance()
gated.advance()
gated.advance()
value = try! await iterator.next()
XCTAssertEqual(value, 2)
gated.advance()
gated.advance()
gated.advance()
gated.advance()
do {
value = try await iterator.next()
XCTFail("next() should have thrown.")
} catch { }
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
}
func test_buffer_delegation() async {
actor BufferDelegate: AsyncBuffer {
var buffer = [Int]()
var pushed = [Int]()
func push(_ element: Int) async {
buffer.append(element)
pushed.append(element)
}
func pop() async -> Int? {
if buffer.count > 0 {
return buffer.removeFirst()
}
return nil
}
}
let delegate = BufferDelegate()
var gated = GatedSequence([1, 2, 3, 4, 5])
let sequence = gated.buffer {
delegate
}
var iterator = sequence.makeAsyncIterator()
gated.advance()
var value = await iterator.next()
var pushed = await delegate.pushed
XCTAssertEqual(pushed, [1])
XCTAssertEqual(value, 1)
gated.advance()
gated.advance()
gated.advance()
value = await iterator.next()
XCTAssertEqual(value, 2)
value = await iterator.next()
pushed = await delegate.pushed
XCTAssertEqual(value, 3)
value = await iterator.next()
pushed = await delegate.pushed
XCTAssertEqual(pushed, [1, 2, 3, 4])
XCTAssertEqual(value, 4)
gated.advance()
gated.advance()
value = await iterator.next()
pushed = await delegate.pushed
XCTAssertEqual(pushed, [1, 2, 3, 4, 5])
XCTAssertEqual(value, 5)
value = await iterator.next()
XCTAssertEqual(value, nil)
value = await iterator.next()
XCTAssertEqual(value, nil)
}
func test_delegatedBuffer_withError() async {
actor BufferDelegate: AsyncBuffer {
var buffer = [Int]()
var pushed = [Int]()
func push(_ element: Int) async {
buffer.append(element)
pushed.append(element)
}
func pop() async throws -> Int? {
if buffer.count > 0 {
let value = buffer.removeFirst()
if value == 3 {
throw Failure()
}
return value
}
return nil
}
}
let delegate = BufferDelegate()
var gated = GatedSequence([1, 2, 3, 4, 5, 6, 7])
let sequence = gated.buffer { delegate }
var iterator = sequence.makeAsyncIterator()
gated.advance()
var value = try! await iterator.next()
XCTAssertEqual(value, 1)
gated.advance()
gated.advance()
gated.advance()
value = try! await iterator.next()
XCTAssertEqual(value, 2)
gated.advance()
gated.advance()
gated.advance()
gated.advance()
do {
value = try await iterator.next()
XCTFail("next() should have thrown.")
} catch { }
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
value = try! await iterator.next()
XCTAssertNil(value)
}
func test_byteBuffer() async {
actor ByteBuffer: AsyncBuffer {
var buffer: [UInt8]?
func push(_ element: UInt8) async {
if buffer == nil {
buffer = [UInt8]()
}
buffer?.append(element)
}
func pop() async -> [UInt8]? {
defer { buffer = nil }
return buffer
}
}
var data = Data()
for _ in 0..<4096 {
data.append(UInt8.random(in: 0..<UInt8.max))
}
let buffered = data.async.buffer {
ByteBuffer()
}
var collected = Data()
for await segment in buffered {
collected.append(contentsOf: segment)
}
XCTAssertEqual(data, collected)
}
func test_multi_tasks() async {
var values = GatedSequence(Array(0 ... 10))
let bufferSeq = values.buffer(policy: .unbounded)
var iter_ = bufferSeq.makeAsyncIterator()
// Initiate the sequence's operation and creation of its Task and actor before sharing its iterator.
values.advance()
let _ = await iter_.next()
let iter = iter_
let task1 = Task<[Int], Never> {
var result = [Int]()
var iter1 = iter
while let val = await iter1.next() {
result.append(val)
}
return result
}
let task2 = Task<[Int], Never> {
var result = [Int]()
var iter2 = iter
while let val = await iter2.next() {
result.append(val)
}
return result
}
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
values.advance()
let task1Results = await task1.value
let task2Results = await task2.value
XCTAssertEqual(task1Results.sorted(), task1Results)
XCTAssertEqual(task2Results.sorted(), task2Results)
let combined = (task1Results + task2Results).sorted()
XCTAssertEqual(combined, Array(1 ... 10))
}
func test_multi_tasks_error() async {
var values = GatedSequence(Array(0 ... 10))
let mapSeq = values.map { try throwOn(7, $0) }
let bufferSeq = mapSeq.buffer(policy: .unbounded)
var iter_ = bufferSeq.makeAsyncIterator()
// Initiate the sequence's operation and creation of its Task and actor before sharing its iterator.
values.advance()
let _ = try! await iter_.next()
let iter = iter_
let task1 = Task<([Int], Error?), Never> {
var result = [Int]()
var err: Error?
var iter1 = iter
do {
while let val = try await iter1.next() {
result.append(val)
}
} catch {
err = error
}
return (result, err)
}
let task2 = Task<([Int], Error?), Never> {
var result = [Int]()
var err: Error?
var iter2 = iter
do {
while let val = try await iter2.next() {
result.append(val)
}
} catch {
err = error
}
return (result, err)
}
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
let task1Results = await task1.value
let task2Results = await task2.value
XCTAssertEqual(task1Results.0.sorted(), task1Results.0)
XCTAssertEqual(task2Results.0.sorted(), task2Results.0)
let combined = (task1Results.0 + task2Results.0).sorted()
XCTAssertEqual(combined, Array(1 ... 6))
XCTAssertEqual(1, [task1Results, task2Results].compactMap{ $0.1 }.count)
}
func test_multi_tasks_delegateBufferError() async {
actor BufferDelegate: AsyncBuffer {
var buffer = [Int]()
var pushed = [Int]()
func push(_ element: Int) async {
buffer.append(element)
pushed.append(element)
}
func pop() async throws -> Int? {
if buffer.count > 0 {
let value = buffer.removeFirst()
if value == 7 {
throw Failure()
}
return value
}
return nil
}
}
let delegate = BufferDelegate()
var values = GatedSequence(Array(0 ... 10))
let bufferSeq = values.buffer { delegate }
var iter_ = bufferSeq.makeAsyncIterator()
// Initiate the sequence's operation and creation of its Task and actor before sharing its iterator.
values.advance()
let _ = try! await iter_.next()
let iter = iter_
let task1 = Task<([Int], Error?), Never> {
var result = [Int]()
var err: Error?
var iter1 = iter
do {
while let val = try await iter1.next() {
result.append(val)
}
} catch {
err = error
}
return (result, err)
}
let task2 = Task<([Int], Error?), Never> {
var result = [Int]()
var err: Error?
var iter2 = iter
do {
while let val = try await iter2.next() {
result.append(val)
}
} catch {
err = error
}
return (result, err)
}
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
values.advance()
values.advance()
try? await Task.sleep(nanoseconds: 100_000_000)
values.advance()
let task1Results = await task1.value
let task2Results = await task2.value
XCTAssertEqual(task1Results.0.sorted(), task1Results.0)
XCTAssertEqual(task2Results.0.sorted(), task2Results.0)
let combined = (task1Results.0 + task2Results.0).sorted()
XCTAssertEqual(combined, Array(1 ... 6))
XCTAssertEqual(1, [task1Results, task2Results].compactMap{ $0.1 }.count)
}
func test_bufferingOldest() async {
validate {
"X-12- 34- 5 |"
$0.inputs[0].buffer(policy: .bufferingOldest(2))
"X,,,[1,],,[2,],[3,][5,]|"
}
}
func test_bufferingOldest_noDrops() async {
validate {
"X-12 3 4 5 |"
$0.inputs[0].buffer(policy: .bufferingOldest(2))
"X,,[1,][2,][3,][45]|"
}
}
func test_bufferingOldest_error() async {
validate {
"X-12345^"
$0.inputs[0].buffer(policy: .bufferingOldest(2))
"X,,,,,,[12^]"
}
}
func test_bufferingNewest() async {
validate {
"X-12- 34 -5|"
$0.inputs[0].buffer(policy: .bufferingNewest(2))
"X,,,[1,],,[3,],[4,][5,]|"
}
}
func test_bufferingNewest_noDrops() async {
validate {
"X-12 3 4 5 |"
$0.inputs[0].buffer(policy: .bufferingNewest(2))
"X,,[1,][2,][3,][45]|"
}
}
func test_bufferingNewest_error() async {
validate {
"X-12345^"
$0.inputs[0].buffer(policy: .bufferingNewest(2))
"X,,,,,,[45^]"
}
}
}
@@ -1,208 +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
//
//===----------------------------------------------------------------------===//
@preconcurrency import XCTest
import AsyncAlgorithms
final class TestBufferedByteIterator: XCTestCase {
actor Isolated<T: Sendable> {
var value: T
init(_ value: T) {
self.value = value
}
func update(_ value: T) async {
self.value = value
}
}
func test_immediately_empty() async throws {
let reloaded = Isolated(false)
var iterator = AsyncBufferedByteIterator(capacity: 3) { buffer in
XCTAssertEqual(buffer.count, 3)
await reloaded.update(true)
return 0
}
var wasReloaded = await reloaded.value
XCTAssertFalse(wasReloaded)
let byte = try await iterator.next()
XCTAssertNil(byte)
wasReloaded = await reloaded.value
XCTAssertTrue(wasReloaded)
}
func test_one_pass() async throws {
let reloaded = Isolated(0)
var iterator = AsyncBufferedByteIterator(capacity: 3) { buffer in
XCTAssertEqual(buffer.count, 3)
let count = await reloaded.value
await reloaded.update(count + 1)
if count >= 1 {
return 0
}
buffer.copyBytes(from: [1, 2, 3])
return 3
}
var reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 0)
var byte = try await iterator.next()
XCTAssertEqual(byte, 1)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 1)
byte = try await iterator.next()
XCTAssertEqual(byte, 2)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 1)
byte = try await iterator.next()
XCTAssertEqual(byte, 3)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 1)
byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 2)
byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 2)
}
func test_three_pass() async throws {
let reloaded = Isolated(0)
var iterator = AsyncBufferedByteIterator(capacity: 3) { buffer in
XCTAssertEqual(buffer.count, 3)
let count = await reloaded.value
await reloaded.update(count + 1)
if count >= 3 {
return 0
}
buffer.copyBytes(from: [1, 2, 3])
return 3
}
var reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 0)
for n in 1...3 {
var byte = try await iterator.next()
XCTAssertEqual(byte, 1)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
byte = try await iterator.next()
XCTAssertEqual(byte, 2)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
byte = try await iterator.next()
XCTAssertEqual(byte, 3)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
}
var byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 4)
byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 4)
}
func test_three_pass_throwing() async throws {
let reloaded = Isolated(0)
var iterator = AsyncBufferedByteIterator(capacity: 3) { buffer in
XCTAssertEqual(buffer.count, 3)
let count = await reloaded.value
await reloaded.update(count + 1)
if count >= 3 {
return 0
}
if count == 2 {
throw Failure()
}
buffer.copyBytes(from: [1, 2, 3])
return 3
}
var reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 0)
for n in 1...3 {
do {
var byte = try await iterator.next()
XCTAssertEqual(byte, 1)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
byte = try await iterator.next()
XCTAssertEqual(byte, 2)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
byte = try await iterator.next()
XCTAssertEqual(byte, 3)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, n)
} catch {
XCTAssertEqual(n, 3)
break
}
}
var byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 3)
byte = try await iterator.next()
XCTAssertNil(byte)
reloadCount = await reloaded.value
XCTAssertEqual(reloadCount, 3)
}
func test_cancellation() async {
struct RepeatingBytes: AsyncSequence {
typealias Element = UInt8
func makeAsyncIterator() -> AsyncBufferedByteIterator {
AsyncBufferedByteIterator(capacity: 3) { buffer in
buffer.copyBytes(from: [1, 2, 3])
return 3
}
}
}
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
do {
for try await _ in RepeatingBytes() {
if !firstIteration {
iterated.fulfill()
firstIteration = true
}
}
XCTFail("expected to throw a cancellation error")
} catch {
if error is CancellationError {
finished.fulfill()
}
}
}
wait(for: [iterated], timeout: 1.0)
// cancellation should ensure the loop finishes
// without regards to the remaining underlying sequence
task.cancel()
wait(for: [finished], timeout: 1.0)
}
}
-172
View File
@@ -1,172 +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
//
//===----------------------------------------------------------------------===//
@preconcurrency import XCTest
import AsyncAlgorithms
final class TestChain2: XCTestCase {
func test_chain() async {
let chained = chain([1, 2, 3].async, [4, 5, 6].async)
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
while let item = await iterator.next() {
actual.append(item)
}
XCTAssertEqual([1, 2, 3, 4, 5, 6], actual)
let pastEnd = await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_first() async throws {
let chained = chain([1, 2, 3].async.map { try throwOn(3, $0) }, [4, 5, 6].async)
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
do {
while let item = try await iterator.next() {
actual.append(item)
}
XCTFail()
} catch {
XCTAssertEqual(Failure(), error as? Failure)
}
XCTAssertEqual([1, 2], actual)
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_second() async throws {
let chained = chain([1, 2, 3].async, [4, 5, 6].async.map { try throwOn(5, $0) })
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
do {
while let item = try await iterator.next() {
actual.append(item)
}
XCTFail()
} catch {
XCTAssertEqual(Failure(), error as? Failure)
}
XCTAssertEqual([1, 2, 3, 4], actual)
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_cancellation() async {
let source = Indefinite(value: "test")
let sequence = chain(source.async, ["past indefinite"].async)
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
for await _ in sequence {
if !firstIteration {
firstIteration = true
iterated.fulfill()
}
}
finished.fulfill()
}
// ensure the other task actually starts
wait(for: [iterated], timeout: 1.0)
// cancellation should ensure the loop finishes
// without regards to the remaining underlying sequence
task.cancel()
wait(for: [finished], timeout: 1.0)
}
}
final class TestChain3: XCTestCase {
func test_chain() async {
let chained = chain([1, 2, 3].async, [4, 5, 6].async, [7, 8, 9].async)
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
while let item = await iterator.next() {
actual.append(item)
}
XCTAssertEqual([1, 2, 3, 4, 5, 6, 7, 8, 9], actual)
let pastEnd = await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_first() async throws {
let chained = chain([1, 2, 3].async.map { try throwOn(3, $0) }, [4, 5, 6].async, [7, 8, 9].async)
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
do {
while let item = try await iterator.next() {
actual.append(item)
}
XCTFail()
} catch {
XCTAssertEqual(Failure(), error as? Failure)
}
XCTAssertEqual([1, 2], actual)
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_second() async throws {
let chained = chain([1, 2, 3].async, [4, 5, 6].async.map { try throwOn(5, $0) }, [7, 8, 9].async)
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
do {
while let item = try await iterator.next() {
actual.append(item)
}
XCTFail()
} catch {
XCTAssertEqual(Failure(), error as? Failure)
}
XCTAssertEqual([1, 2, 3, 4], actual)
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_throwing_third() async throws {
let chained = chain([1, 2, 3].async, [4, 5, 6].async, [7, 8, 9].async.map { try throwOn(8, $0) })
var iterator = chained.makeAsyncIterator()
var actual = [Int]()
do {
while let item = try await iterator.next() {
actual.append(item)
}
XCTFail()
} catch {
XCTAssertEqual(Failure(), error as? Failure)
}
XCTAssertEqual([1, 2, 3, 4, 5, 6, 7], actual)
let pastEnd = try await iterator.next()
XCTAssertNil(pastEnd)
}
func test_cancellation() async {
let source = Indefinite(value: "test")
let sequence = chain(source.async, ["past indefinite"].async, ["and even further"].async)
let finished = expectation(description: "finished")
let iterated = expectation(description: "iterated")
let task = Task {
var firstIteration = false
for await _ in sequence {
if !firstIteration {
firstIteration = true
iterated.fulfill()
}
}
finished.fulfill()
}
// ensure the other task actually starts
wait(for: [iterated], timeout: 1.0)
// cancellation should ensure the loop finishes
// without regards to the remaining underlying sequence
task.cancel()
wait(for: [finished], timeout: 1.0)
}
}
Loaded 100 of 122 files, more files were not shown because too many files have changed in this diff. Show more