Philippe HauslerandJamie 70c36ce9a1 Share algorithm (#357)
This is an implementation of share; an algorithm for allowing AsyncSequence types to be iterated by multiple consumers. In addition this cleans up the project to be a starting point for the 1.1 release - it fixes the continuous integration support and configurations but has the cost of only supporting 3 active releases (6.0, 6.1, and 6.2). Previous releases are only going to have legacy support via older released versions.

* Fix the remaining todo on hard cancellation vs soft cancellation

* Update Sources/AsyncAlgorithms/AsyncShareSequence.swift

Co-authored-by: Jamie <2119834+jamieQ@users.noreply.github.com>

* Update the implementation of share to handle sendability requirements, address some edge cases and update to the latest version of the discussion around buffering behaviors as well as adding some documentation and commentary

* Add some first drafts at unit tests for verifying share behaviors

* Cleanup some of the documentation and address feedback for implementation details

* Fix merge damage by restoring the changes from @jamieQ

* Fix up some availability issues w.r.t. sendable metatypes

* Add a preamble to SendableMetatypes.swift

* Add a fallback for next (for pre 6.2 swift's)

* Slight adjustments for older compiler builds and expose the sendable metatypes since those are part of documentation

* Update formatting and gate availability for older compilers

* Speculative fix for pre 6.1 compiler crashes by removing the sending keyword

* Revert "Speculative fix for pre 6.1 compiler crashes by removing the sending keyword"

This reverts commit 875fa81bc6.

* Speculative fix for pre 6.1 compiler crashes by removing the sending keyword, and correct sendable metatype shim availability

* Remove block comment for formatting check

* Take a more conservative approach and roll back to only supporting share on 6.2

* Only test share on 6.2 or newer

* roll back to older sendable metatype constraints

* yet another stab at 5.10 visionOS guards

* Formatting pass

* Disable 5.10 builds and leave those to older releases

* Ignore swift-version files to avoid local swiftly toolchain selection from being required by others

* Renumber the proposals and copy share into a guide

* Add a link from the primary doc interface to share

---------

Co-authored-by: Jamie <2119834+jamieQ@users.noreply.github.com>
2025-09-10 10:00:31 -07:00
2025-09-10 10:00:31 -07:00
2025-09-10 10:00:31 -07:00
2025-09-10 10:00:31 -07:00
2025-09-10 10:00:31 -07:00
2025-03-28 21:59:41 +01:00
2025-03-28 21:59:41 +01:00
2023-09-23 18:16:32 +02:00
2025-03-28 21:59:41 +01:00
2025-09-10 10:00:31 -07:00
2025-03-28 21:59:41 +01:00
2024-01-24 11:28:26 +00:00

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. 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 and the Swift Forums.

Contents

Combining asynchronous sequences

  • chain(_:...): Concatenates two or more asynchronous sequences with the same element type.
  • combineLatest(_:...): 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(_:...): Merges two or more asynchronous sequence into a single asynchronous sequence producing the elements of all of the underlying asynchronous sequences.
  • zip(_:...): Creates an asynchronous sequence of pairs built out of underlying asynchronous sequences.
  • joined(separator:): Concatenated elements of an asynchronous sequence of asynchronous sequences, inserting the given separator between each element.

Creating asynchronous sequences

  • async: Create an asynchronous sequence composed from a synchronous sequence.
  • AsyncChannel: An asynchronous sequence with back pressure sending semantics.
  • AsyncThrowingChannel: An asynchronous sequence with back pressure sending semantics that can emit failures.

Performance optimized asynchronous iterators

  • AsyncBufferedByteIterator: A highly efficient iterator useful for iterating byte sequences derived from asynchronous read functions.

Other useful asynchronous sequences

Asynchronous Sequences that transact in time

Obtaining all values from an asynchronous sequence

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.

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:

.package(url: "https://github.com/apple/swift-async-algorithms", from: "1.0.0"),

Include "AsyncAlgorithms" as a dependency for your executable target:

.target(name: "<target>", dependencies: [
    .product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
]),

Finally, add import AsyncAlgorithms to your source code.

Getting Started

⚠️ Please note that this package requires Xcode 14 on macOS hosts. Previous versions of Xcode do not contain the required Swift version.

Building/Testing Using Xcode on macOS

  1. In the swift-async-algorithms directory run swift build or swift test accordingly

Building/Testing on Linux

  1. Download the most recent development toolchain for your Linux distribution
  2. Decompress the archive to a path in which the swift executable is in the binary search path environment variable ($PATH)
  3. In the swift-async-algorithms directory run swift build or swift test accordingly

Source Stability

The Swift Async Algorithms package has a goal of being source stable as soon as possible; version numbers will follow Semantic Versioning. 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.

S
Description
Mirror of github.com/apple/swift-async-algorithms
Readme Apache-2.0
2.6 MiB
0 Stars 1 Watchers 0 Forks
Languages
Swift 99.2%
C++ 0.8%