Add MultiProducerSingleConsumerChannel (#305)

* Add `AsyncBackpressuredStream` proposal and implementation

# Motivation

The pitch to add external backpressure support to the standard libraries `AsyncStream` got returned for revision since there are larger open questions around `AsyncSequence`. However, having external backpressure in a source asynchronous sequence is becoming more and more important.

# Modification

This PR adds a modified proposal and implementation that brings the Swift Evolution proposal over to Swift Async Algorithms.

* Update proposal and implementation

* Update proposal

* Add example project

* Formatting

* Fix Swift 6.0 build

* Future direction for ~Copyable elements

* Apply formatting

* Fix CI

* Move to 6.1 and update proposal

* Guard tests

* Minor edits to the proposal

* Fix revision order

* FIxup setOnTerminationCallback

* Address review feedback

* Rename to `MultiProducerSingleConsumerAsyncChannel`

* Allow one termination callback per source.

* Fix all sendable warnings

* Remove unbounded strategy, rename copy -> makeAdditionalSource, rename asyncSequence() -> elements(), and move enqueue and cancel to the `CallbackHandle` previously called `CallbackToken`

* Remove Example and fix docs and fix format

* fixes grammar and some word order issues

* Remove unnecessary consume

---------

Co-authored-by: Joe Heck <j_heck@apple.com>
This commit is contained in:
Franz BuschandJoe Heck authored and GitHub committed 2025-11-18 15:56:41 -08:00
1 parent 24bd5acc81
commit 4686d2edd3
8 files changed
+4718

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
+1
View File
@@ -22,3 +22,4 @@ jobs:
uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
with:
license_header_check_project_name: "Swift Async Algorithms"
format_check_container_image: "swiftlang/swift:nightly-6.1-noble" # Needed since 6.0.x doesn't support sending keyword
@@ -0,0 +1,838 @@
# MultiProducerSingleConsumerAsyncChannel
* Proposal: [SAA-0016](0016-multi-producer-single-consumer-channel.md)
* Authors: [Franz Busch](https://github.com/FranzBusch)
* Status: **Implemented**
## Revision
- 2023/12/18: Migrate proposal from Swift Evolution to Swift Async Algorithms.
- 2023/12/19: Add element size dependent strategy
- 2024/05/19: Rename to multi producer single consumer channel
- 2024/05/28: Add unbounded strategy
- 2025/03/24: Adopt `~Copyable` for correct semantics and better performance.
## Introduction
[SE-0314](https://github.com/apple/swift-evolution/blob/main/proposals/0314-async-stream.md)
introduced new `Async[Throwing]Stream` types which act as root asynchronous
sequences. These two types allow bridging from synchronous callbacks such as
delegates to an asynchronous sequence. This proposal adds a new root primitive
with the goal of modeling asynchronous multi-producer-single-consumer systems.
## Motivation
After using the `AsyncSequence` protocol, the `Async[Throwing]Stream` types, and
the `Async[Throwing]Channel` types extensively over the past years, we learned
that there is a gap in the ecosystem for a type that provides strict
multi-producer-single-consumer guarantees with external backpressure support.
Additionally, any stream/channel like type needs to have a clear definition
about the following behaviors:
1. Backpressure
2. Multi/single consumer support
3. Downstream consumer termination
4. Upstream producer termination
The below sections are providing a detailed explanation of each of those.
### Backpressure
In general, backpressure is the mechanism that prevents a fast producer from
overwhelming a slow consumer. It helps the stability of the overall system by
regulating the flow of data between different components. Additionally, it
allows us to put an upper bound on the resource consumption of a system. In reality,
backpressure is used in almost all networked applications.
In Swift, asynchronous sequences also have the concept of internal backpressure.
This is modeled by the pull-based implementation where a consumer has to call
`next` on the `AsyncIterator`. In this model, there is no way for a consumer to
overwhelm a producer since the producer controls the rate of pulling elements.
However, the internal backpressure of an asynchronous sequence isn't the only
backpressure in play. There is also the source backpressure that is producing
the actual elements. For a backpressured system, it is important that every
component of such a system is aware of the backpressure of its consumer and its
producer.
Let's take a quick look at how our current root asynchronous sequences are handling
this.
`Async[Throwing]Stream` aims to support backpressure by providing a configurable
buffer and returning `Async[Throwing]Stream.Continuation.YieldResult` which
contains the current buffer depth from the `yield()` method. However, only
providing the current buffer depth on `yield()` is not enough to bridge a
backpressured system into an asynchronous sequence since this can only be used
as a "stop" signal, but we are missing a signal to indicate resuming the
production. The only viable backpressure strategy that can be implemented with
the current API is a timed backoff where we stop producing for some period of
time and then speculatively produce again. This is a very inefficient pattern
that produces high latencies and inefficient use of resources.
`Async[Throwing]Channel` is a multi-producer-multi-consumer channel that only
supports asynchronous producers. Additionally, the backpressure strategy is
fixed by a buffer size of 1 element per producer.
We are currently lacking a type that supports a configurable backpressure
strategy and both asynchronous and synchronous producers.
### Multi/single consumer support
The `AsyncSequence` protocol itself makes no assumptions about whether the
implementation supports multiple consumers or not. This allows the creation of
unicast and multicast asynchronous sequences. The difference between a unicast
and multicast asynchronous sequence is if they allow multiple iterators to be
created. `AsyncStream` does support the creation of multiple iterators and it
does handle multiple consumers correctly. On the other hand,
`AsyncThrowingStream` also supports multiple iterators but does `fatalError`
when more than one iterator has to suspend. The original proposal states:
> As with any sequence, iterating over an AsyncStream multiple times, or
creating multiple iterators and iterating over them separately, may produce an
unexpected series of values.
While that statement leaves room for any behavior, we learned that a clear distinction
of behavior for root asynchronous sequences is beneficial; especially when it comes to
how transformation algorithms are applied on top.
### Downstream consumer termination
Downstream consumer termination allows the producer to notify the consumer that
no more values are going to be produced. `Async[Throwing]Stream` does support
this by calling the `finish()` or `finish(throwing:)` methods of the
`Async[Throwing]Stream.Continuation`. However, `Async[Throwing]Stream` does not
handle the case that the `Continuation` may be `deinit`ed before one of the
finish methods is called. This currently leads to async streams that never
terminate.
### Upstream producer termination
Upstream producer termination is the inverse of downstream consumer termination,
where the producer is notified once the consumption has terminated. Currently,
`Async[Throwing]Stream` does expose the `onTermination` property on the
`Continuation`. The `onTermination` closure is invoked once the consumer has
terminated. The consumer can terminate in four separate cases:
1. The asynchronous sequence was `deinit`ed and no iterator was created.
2. The iterator was `deinit`ed and the asynchronous sequence is unicast.
3. The consuming task is canceled.
4. The asynchronous sequence returned `nil` or threw.
`Async[Throwing]Stream` currently invokes `onTermination` in all cases; however,
since `Async[Throwing]Stream` supports multiple consumers (as discussed in the
`Multi/single consumer support` section), a single consumer task being canceled
leads to the termination of all consumers. This is not expected from multicast
asynchronous sequences in general.
## Proposed solution
The above motivation lays out the expected behaviors for any consumer/producer
system and compares them to the behaviors of `Async[Throwing]Stream` and
`Async[Throwing]Channel`.
This section proposes a new type called `MultiProducerSingleConsumerAsyncChannel`
that implements all of the above-mentioned behaviors. Importantly, this proposed
solution is taking advantage of `~Copyable` types to model the
multi-producer-single-consumer behavior. While the current `AsyncSequence`
protocols are not supporting `~Copyable` types, we provide a way to convert the
proposed channel to an asynchronous sequence. This leaves us room to support any
potential future asynchronous streaming protocol that supports `~Copyable`.
### Creating a MultiProducerSingleConsumerAsyncChannel
You can create an `MultiProducerSingleConsumerAsyncChannel` instance using the
`makeChannel(of:backpressureStrategy:)` method. This method returns you the
channel and the source. The source can be used to send new values to the
asynchronous channel. The new API specifically provides a
multi-producer/single-consumer pattern.
```swift
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
// The channel and source can be extracted from the returned type
let channel = consume channelAndSource.channel
let source = consume channelAndSource.source
```
The new proposed APIs offer two different backpressure strategies:
- Watermark: Using a low and high watermark.
- Unbounded: Unbounded buffering of the channel. **Only** use this if the
production is limited through some other means.
The source is used to send values to the channel. It provides different APIs for
synchronous and asynchronous producers. All of the APIs are relaying the
backpressure of the channel. The synchronous multi-step APIs are the foundation
for all other APIs. Below is an example of how it can be used:
```swift
do {
let sendResult = try source.send(contentsOf: sequence)
switch sendResult {
case .produceMore:
// Trigger more production in the underlying system
case .enqueueCallback(let callbackHandle):
// There are enough values in the channel already. We need to enqueue
// a callback to get notified when we should produce more.
callbackHandle.enqueueCallback(onProduceMore: { result in
switch result {
case .success:
// Trigger more production in the underlying system
case .failure(let error):
// Terminate the underlying producer
}
})
}
} catch {
// `send(contentsOf:)` throws if the channel already terminated
}
```
The above API offers the most control and highest performance when bridging a
synchronous producer to a `MultiProducerSingleConsumerAsyncChannel`. First, you have
to send values using the `send(contentsOf:)` which returns a `SendResult`. The
result either indicates that more values should be produced or that a callback
should be enqueued by calling the `enqueueCallback(onProduceMore:)` method.
This callback is invoked once the backpressure strategy
decides that more values should be produced. This API aims to offer the most
flexibility with the greatest performance. The callback only has to be allocated
in the case where the producer needs to pause production.
Additionally, the above API is the building block for some higher-level and
easier-to-use APIs to send values to the channel. Below is an
example of the two higher-level APIs.
```swift
// Writing new values and providing a callback when to produce more
try source.send(contentsOf: sequence, onProduceMore: { result in
switch result {
case .success:
// Trigger more production
case .failure(let error):
// Terminate the underlying producer
}
})
// This method suspends until more values should be produced
try await source.send(contentsOf: sequence)
```
With the above APIs, we should be able to effectively bridge any system into a
`MultiProducerSingleConsumerAsyncChannel` regardless of whether the system is callback-based,
blocking, or asynchronous.
### Multi producer
To support multiple producers, the source offers a `copy` method to produce a new
source. The source is returned `sending`, so it is in a disconnected isolation
region from the original source, allowing it to be passed into a different isolation
region to concurrently produce elements.
```swift
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 5)
)
var channel = consume channelAndSource.channel
var source1 = consume channelAndSource.source
var source2 = source1.makeAdditionalSource()
group.addTask {
try await source1.send(1)
}
group.addTask() {
try await source2.send(2)
}
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
print(await channel.next()) // Prints either 1 or 2 depending on which child task runs first
```
### Downstream consumer termination
> When reading the next two examples of termination behavior, keep in mind
that the newly proposed APIs are providing a strict single consumer channel.
Calling `finish()` terminates the downstream consumer. Below is an example of
this:
```swift
// Termination through calling finish
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
source.finish()
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints nil
```
If the channel has a failure type it can also be finished with an error.
```swift
// Termination through calling finish
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
throwing: SomeError.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
source.finish(throwing: SomeError)
print(try await channel.next()) // Prints Optional(1)
print(try await channel.next()) // Throws SomeError
```
The other way to terminate the consumer is by deiniting the source. This has the
same effect as calling `finish()`. Since the source is a `~Copyable` type, this
will happen automatically when the source is last used or explicitly consumed.
```swift
// Termination through deiniting the source
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
try await source.send(1)
_ = consume source // Explicitly consume the source
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints nil
```
### Upstream producer termination
The producer will get notified about termination through the `onTerminate`
callback. Termination of the producer happens in the following scenarios:
```swift
// Termination through task cancellation
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
let task = Task {
await channel.next()
}
task.cancel() // Prints Terminated
```
```swift
// Termination through deiniting the channel
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
_ = consume channel // Prints Terminated
```
```swift
// Termination through finishing the source and consuming the last element
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source = consume channelAndSource.source
source.setOnTerminationCallback { print("Terminated") }
_ = try await source.send(1)
source.finish()
print(await channel.next()) // Prints Optional(1)
await channel.next() // Prints Terminated
```
```swift
// Termination through deiniting the last source and consuming the last element
let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
)
var channel = consume channelAndSource.channel
var source1 = consume channelAndSource.source
var source2 = source1.makeAdditionalSource()
source1.setOnTerminationCallback { print("Terminated") }
_ = try await source1.send(1)
_ = consume source1
_ = try await source2.send(2)
print(await channel.next()) // Prints Optional(1)
print(await channel.next()) // Prints Optional(2)
_ = consume source2
await channel.next() // Prints Terminated
```
Similar to the downstream consumer termination, trying to send more elements after the
producer has been terminated will result in an error thrown from the send methods.
## Detailed design
```swift
#if compiler(>=6.1)
/// An error that is thrown from the various `send` methods of the
/// ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// This error is thrown when the channel is already finished when
/// trying to send new elements to the source.
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error { }
/// A multi-producer single-consumer channel.
///
/// The ``MultiProducerSingleConsumerAsyncChannel`` provides a ``MultiProducerSingleConsumerAsyncChannel/Source`` to
/// send values to the channel. The channel supports different back pressure strategies to control the
/// buffering and demand. The channel will buffer values until its backpressure strategy decides that the
/// producer have to wait.
///
/// This channel is also suitable for the single-producer single-consumer use-case
///
/// ## Using a MultiProducerSingleConsumerAsyncChannel
///
/// To use a ``MultiProducerSingleConsumerAsyncChannel`` you have to create a new channel with its source first by calling
/// the ``MultiProducerSingleConsumerAsyncChannel/makeChannel(of:throwing:BackpressureStrategy:)`` method.
/// Afterwards, you can pass the source to the producer and the channel to the consumer.
///
/// ```
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 2, high: 4)
/// )
///
/// // The channel and source can be extracted from the returned type
/// let channel = consume channelAndSource.channel
/// let source = consume channelAndSource.source
/// ```
///
/// ### Asynchronous producing
///
/// Values can be send to the source from asynchronous contexts using ``MultiProducerSingleConsumerAsyncChannel/Source/send(_:)-8eo96``
/// and ``MultiProducerSingleConsumerAsyncChannel/Source/send(contentsOf:)``. Backpressure results in calls
/// to the `send` methods to be suspended. Once more elements should be produced the `send` methods will be resumed.
///
/// ```
/// try await withThrowingTaskGroup(of: Void.self) { group in
/// group.addTask {
/// try await source.send(1)
/// try await source.send(2)
/// try await source.send(3)
/// }
///
/// for await element in channel {
/// print(element)
/// }
/// }
/// ```
///
/// ### Synchronous produceing
///
/// Values can also be send to the source from synchronous context. Backpressure is also exposed on the synchronous contexts; however,
/// it is up to the caller to decide how to properly translate the backpressure to underlying producer e.g. by blocking the thread.
///
/// ```swift
/// do {
/// let sendResult = try source.send(contentsOf: sequence)
///
/// switch sendResult {
/// case .produceMore:
/// // Trigger more production in the underlying system
///
/// case .enqueueCallback(let callbackHandle):
/// // There are enough values in the channel already. We need to enqueue
/// // a callback to get notified when we should produce more.
/// callbackHandle.enqueueCallback(onProduceMore: { result in
/// switch result {
/// case .success:
/// // Trigger more production in the underlying system
/// case .failure(let error):
/// // Terminate the underlying producer
/// }
/// })
/// }
/// } catch {
/// // `send(contentsOf:)` throws if the channel already terminated
/// }
/// ```
///
/// ### Multiple producers
///
/// To support multiple producers the source offers a ``Source/makeAdditionalSource()`` method to produce a new source.
///
/// ### Terminating the production of values
///
/// The consumer can be terminated through multiple ways:
/// - Calling ``Source/finish(throwing:)``.
/// - Deiniting all sources.
///
/// In both cases, if there are still elements buffered by the channel, then the consumer will receive
/// all buffered elements. Afterwards it will be terminated.
///
/// ### Observing termination of the consumer
///
/// When the consumer stops consumption by either deiniting the channel or the task calling ``next(isolation:)``
/// getting cancelled, the source will get notified about the termination if a termination callback has been set
/// before by calling ``Source/setOnTerminationCallback(_:)``.
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>: ~Copyable {
/// A struct containing the initialized channel and source.
///
/// This struct can be deconstructed by consuming the individual
/// components from it.
///
/// ```swift
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 5, high: 10)
/// )
/// var channel = consume channelAndSource.channel
/// var source = consume channelAndSource.source
/// ```
@frozen
public struct ChannelAndStream : ~Copyable {
/// The channel.
public var channel: MultiProducerSingleConsumerAsyncChannel
/// The source.
public var source: Source
}
/// Initializes a new ``MultiProducerSingleConsumerAsyncChannel`` and an ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// - Parameters:
/// - elementType: The element type of the channel.
/// - failureType: The failure type of the channel.
/// - backpressureStrategy: The backpressure strategy that the channel should use.
/// - Returns: A tuple containing the channel and its source. The source should be passed to the
/// producer while the channel should be passed to the consumer.
public static func makeChannel(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy
) -> ChannelAndStream
/// Returns the next element.
///
/// If this method returns `nil` it indicates that no further values can ever
/// be returned. The channel automatically closes when all sources have been deinited.
///
/// If there are no elements and the channel has not been finished yet, this method will
/// suspend until an element is send to the channel.
///
/// If the task calling this method is cancelled this method will return `nil`.
///
/// - Parameter isolation: The callers isolation.
/// - Returns: The next buffered element.
public func next(isolation: isolated (any Actor)? = #isolation) async throws(Failure) -> Element?
}
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// A struct to send values to the channel.
///
/// Use this source to provide elements to the channel by calling one of the `send` methods.
public struct Source: ~Copyable, Sendable {
/// A struct representing the backpressure of the channel.
public struct BackpressureStrategy: Sendable {
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
public static func watermark(low: Int, high: Int) -> BackpressureStrategy
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
/// - waterLevelForElement: A closure used to compute the contribution of each buffered element to the current water level.
///
/// - Note, `waterLevelForElement` will be called on each element when it is written into the source and when
/// it is consumed from the channel, so it is recommended to provide a function that runs in constant time.
public static func watermark(low: Int, high: Int, waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int) -> BackpressureStrategy
/// An unbounded backpressure strategy.
///
/// - Important: Only use this strategy if the production of elements is limited through some other mean. Otherwise
/// an unbounded backpressure strategy can result in infinite memory usage and cause
/// your process to run out of memory.
public static func unbounded() -> BackpressureStrategy
}
/// A type that indicates the result of sending elements to the source.
public enum SendResult: ~Copyable, Sendable {
/// A handle that is returned when the channel's backpressure strategy indicated that production should
/// be suspended. Use this handle to enqueue a callback by calling the ``CallbackHandle/enqueueCallback(onProduceMore:)`` method.
///
/// - Important: ``CallbackHandle/enqueueCallback(onProduceMore:)`` and ``CallbackHandle/cancelCallback()`` must
/// only be called once.
public struct CallbackHandle: Sendable, Hashable {
/// Enqueues a callback that will be invoked once more elements should be produced.
///
/// - Important: Calling enqueue more than once is **not allowed**.
///
/// - Parameters:
/// - onProduceMore: The callback which gets invoked once more elements should be produced.
@inlinable
public mutating func enqueueCallback(
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
)
/// Cancel an enqueued callback.
///
/// - Note: This methods supports being called before ``enqueueCallback(onProduceMore:)`` is called.
///
/// - Important: Calling enqueue more than once is **not allowed**.
@inlinable
public mutating func cancelCallback()
}
/// Indicates that more elements should be produced and send to the source.
case produceMore
/// Indicates that a callback should be enqueued.
case enqueueCallback(CallbackHandle)
}
/// A callback to invoke when the channel finished.
///
/// This is called after the last element has been consumed by the channel.
public func setOnTerminationCallback(_ callback: @escaping @Sendable () -> Void)
/// Creates a new source which can be used to send elements to the channel concurrently.
///
/// The channel will only automatically be finished if all existing sources have been deinited.
///
/// - Returns: A new source for sending elements to the channel.
public mutating func makeAdditionalSource() -> Source
/// Sends new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// - Parameter sequence: The elements to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) throws -> SendResult where Element == S.Element, S: Sequence
/// Send the element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// - Parameter element: The element to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
public mutating func send(_ element: sending consuming Element) throws -> SendResult
/// Send new elements to the channel and provide a callback which will be invoked once more elements should be produced.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(contentsOf:onProduceMore:)``.
public mutating func send<S>(
contentsOf sequence: consuming sending S,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) where Element == S.Element, S: Sequence
/// Sends the element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - element: The element to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(_:onProduceMore:)``.
public mutating func send(
_ element: consuming sending Element,
onProduceMore: @escaping @Sendable (Result<Void, Error>
) -> Void)
/// Send new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element == S.Element, S: Sequence
/// Send new element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - element: The element to send to the channel.
public mutating func send(_ element: consuming sending Element) async throws
/// Send the elements of the asynchronous sequence to the channel.
///
/// This method returns once the provided asynchronous sequence or the channel finished.
///
/// - Important: This method does not finish the source if consuming the upstream sequence terminated.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
public mutating func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element: Sendable, Element == S.Element, S: Sendable, S: AsyncSequence
/// Indicates that the production terminated.
///
/// After all buffered elements are consumed the subsequent call to ``MultiProducerSingleConsumerAsyncChannel/next(isolation:)`` will return
/// `nil` or throw an error.
///
/// Calling this function more than once has no effect. After calling finish, the channel enters a terminal state and doesn't accept
/// new elements.
///
/// - Parameters:
/// - error: The error to throw, or `nil`, to finish normally.
public consuming func finish(throwing error: Failure? = nil)
}
}
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// Converts the channel to an asynchronous sequence for consumption.
///
/// - Important: The returned asynchronous sequence only supports a single iterator to be created and
/// will fatal error at runtime on subsequent calls to `makeAsyncIterator`.
public consuming func asyncSequence() -> some (AsyncSequence<Element, Failure> & Sendable)
}
```
## Comparison to other root asynchronous primitives
### swift-async-algorithm: AsyncChannel
The `AsyncChannel` is a multi-consumer/multi-producer root asynchronous sequence
which can be used to communicate between two tasks. It only offers asynchronous
production APIs and has an effective buffer of one per producer. This means that
any producer will be suspended until its value has been consumed. `AsyncChannel`
can handle multiple consumers and resumes them in FIFO order.
### swift-nio: NIOAsyncSequenceProducer
The NIO team has created their own root asynchronous sequence with the goal to
provide a high-performance sequence that can be used to bridge a NIO `Channel`
inbound stream into Concurrency. The `NIOAsyncSequenceProducer` is a highly
generic and fully inlinable type and quite unwieldy to use. This proposal is
heavily inspired by the learnings from this type but tries to create a more
flexible and easier-to-use API that fits into the standard library.
## Future directions
### Adaptive backpressure strategy
The high/low watermark strategy is common in networking code; however, there are
other strategies such as an adaptive strategy that we could offer in the future.
An adaptive strategy regulates the backpressure based on the rate of
consumption and production. With the proposed new APIs, we can easily add further
strategies.
### Support `~Copyable` elements
In the future, we can extend the channel to support `~Copyable` elements. We
only need an underlying buffer primitive that can hold `~Copyable` types, and the
continuations need to support `~Copyable` elements as well. By making the
channel not directly conform to `AsyncSequence`, we can support this down the
road.
## Alternatives considered
### Provide an `onTermination` callback to the factory method
During development of the new APIs, I first tried to provide the `onTermination`
callback in the `makeChannel` method. However, that showed significant usability
problems in scenarios where one wants to store the source in a type and
reference `self` in the `onTermination` closure at the same time; hence, I kept
the current pattern of setting the `onTermination` closure on the source.
### Provide a `onConsumerCancellation` callback
During the pitch phase, it was raised that we should provide a
`onConsumerCancellation` callback which gets invoked once the asynchronous
channel notices that the consuming task got cancelled. This callback could be
used to customize how cancellation is handled by the channel, e.g. one could
imagine writing a few more elements to the channel before finishing it. Right now,
the channel immediately returns `nil` or throws a `CancellationError` when it
notices cancellation. This proposal decided not to provide this customization
because it opens up the possibility that asynchronous channels are not terminating
when implemented incorrectly. Additionally, asynchronous sequences are not the
only place where task cancellation leads to an immediate error being thrown i.e.
`Task.sleep()` does the same. Hence, the value of the asynchronous not
terminating immediately brings little value when the next call in the iterating
task might throw. However, the implementation is flexible enough to add this in
the future, and we can just default it to the current behaviour.
### Create a custom type for the `Result` of the `onProduceMore` callback
The `onProducerMore` callback takes a `Result<Void, Error>` which is used to
indicate if the producer should produce more or if the asynchronous channel
finished. We could introduce a new type for this, but the proposal decided
against it since it effectively is a result type.
### Use an initializer instead of factory methods
Instead of providing a `makeChannel` factory method, we could use an initializer
approach that takes a closure which gets the `Source` passed into. A similar API
has been offered with the `Continuation` based approach and
[SE-0388](https://github.com/apple/swift-evolution/blob/main/proposals/0388-async-stream-factory.md)
introduced new factory methods to solve some of the usability ergonomics with
the initializer based APIs.
### Provide the type on older compilers
To achieve maximum performance, the implementation is using `~Copyable` extensively.
On Swift versions before 6.1, there is a https://github.com/swiftlang/swift/issues/78048 when using; hence, this type
is only usable with Swift 6.1 and later compilers.
## Acknowledgements
- [Johannes Weiss](https://github.com/weissi) - For making me aware how
important this problem is and providing great ideas on how to shape the API.
- [Philippe Hausler](https://github.com/phausler) - For helping me designing the
APIs and continuously providing feedback
- [George Barnett](https://github.com/glbrntt) - For providing extensive code
reviews and testing the implementation.
- [Si Beaumont](https://github.com/simonjbeaumont) - For implementing the element size dependent strategy
@@ -0,0 +1,329 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2023 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 source file is part of the SwiftCertificates open source project
//
// Copyright (c) 2023 Apple Inc. and the SwiftCertificates project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
/// ``_TinyArray`` is a ``RandomAccessCollection`` optimised to store zero or one ``Element``.
/// It supports arbitrary many elements but if only up to one ``Element`` is stored it does **not** allocate separate storage on the heap
/// and instead stores the ``Element`` inline.
@usableFromInline
struct _TinyArray<Element> {
@usableFromInline
enum Storage {
case one(Element)
case arbitrary([Element])
}
@usableFromInline
var storage: Storage
}
// MARK: - TinyArray "public" interface
extension _TinyArray: Equatable where Element: Equatable {}
extension _TinyArray: Hashable where Element: Hashable {}
extension _TinyArray: Sendable where Element: Sendable {}
extension _TinyArray: RandomAccessCollection {
@usableFromInline
typealias Element = Element
@usableFromInline
typealias Index = Int
@inlinable
subscript(position: Int) -> Element {
get {
self.storage[position]
}
set {
self.storage[position] = newValue
}
}
@inlinable
var startIndex: Int {
self.storage.startIndex
}
@inlinable
var endIndex: Int {
self.storage.endIndex
}
}
extension _TinyArray {
@inlinable
init(_ elements: some Sequence<Element>) {
self.storage = .init(elements)
}
@inlinable
init() {
self.storage = .init()
}
@inlinable
mutating func append(_ newElement: Element) {
self.storage.append(newElement)
}
@inlinable
mutating func append(contentsOf newElements: some Sequence<Element>) {
self.storage.append(contentsOf: newElements)
}
@discardableResult
@inlinable
mutating func remove(at index: Int) -> Element {
self.storage.remove(at: index)
}
@inlinable
mutating func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows {
try self.storage.removeAll(where: shouldBeRemoved)
}
@inlinable
mutating func sort(by areInIncreasingOrder: (Element, Element) throws -> Bool) rethrows {
try self.storage.sort(by: areInIncreasingOrder)
}
}
// MARK: - TinyArray.Storage "private" implementation
extension _TinyArray.Storage: Equatable where Element: Equatable {
@inlinable
static func == (lhs: Self, rhs: Self) -> Bool {
switch (lhs, rhs) {
case (.one(let lhs), .one(let rhs)):
return lhs == rhs
case (.arbitrary(let lhs), .arbitrary(let rhs)):
// we don't use lhs.elementsEqual(rhs) so we can hit the fast path from Array
// if both arrays share the same underlying storage: https://github.com/apple/swift/blob/b42019005988b2d13398025883e285a81d323efa/stdlib/public/core/Array.swift#L1775
return lhs == rhs
case (.one(let element), .arbitrary(let array)),
(.arbitrary(let array), .one(let element)):
guard array.count == 1 else {
return false
}
return element == array[0]
}
}
}
extension _TinyArray.Storage: Hashable where Element: Hashable {
@inlinable
func hash(into hasher: inout Hasher) {
// same strategy as Array: https://github.com/apple/swift/blob/b42019005988b2d13398025883e285a81d323efa/stdlib/public/core/Array.swift#L1801
hasher.combine(count)
for element in self {
hasher.combine(element)
}
}
}
extension _TinyArray.Storage: Sendable where Element: Sendable {}
extension _TinyArray.Storage: RandomAccessCollection {
@inlinable
subscript(position: Int) -> Element {
get {
switch self {
case .one(let element):
guard position == 0 else {
fatalError("index \(position) out of bounds")
}
return element
case .arbitrary(let elements):
return elements[position]
}
}
set {
switch self {
case .one:
guard position == 0 else {
fatalError("index \(position) out of bounds")
}
self = .one(newValue)
case .arbitrary(var elements):
elements[position] = newValue
self = .arbitrary(elements)
}
}
}
@inlinable
var startIndex: Int {
0
}
@inlinable
var endIndex: Int {
switch self {
case .one: return 1
case .arbitrary(let elements): return elements.endIndex
}
}
}
extension _TinyArray.Storage {
@inlinable
init(_ elements: some Sequence<Element>) {
var iterator = elements.makeIterator()
guard let firstElement = iterator.next() else {
self = .arbitrary([])
return
}
guard let secondElement = iterator.next() else {
// newElements just contains a single element
// and we hit the fast path
self = .one(firstElement)
return
}
var elements: [Element] = []
elements.reserveCapacity(elements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
while let nextElement = iterator.next() {
elements.append(nextElement)
}
self = .arbitrary(elements)
}
@inlinable
init() {
self = .arbitrary([])
}
@inlinable
mutating func append(_ newElement: Element) {
self.append(contentsOf: CollectionOfOne(newElement))
}
@inlinable
mutating func append(contentsOf newElements: some Sequence<Element>) {
switch self {
case .one(let firstElement):
var iterator = newElements.makeIterator()
guard let secondElement = iterator.next() else {
// newElements is empty, nothing to do
return
}
var elements: [Element] = []
elements.reserveCapacity(1 + newElements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
elements.appendRemainingElements(from: &iterator)
self = .arbitrary(elements)
case .arbitrary(var elements):
if elements.isEmpty {
// if `self` is currently empty and `newElements` just contains a single
// element, we skip allocating an array and set `self` to `.one(firstElement)`
var iterator = newElements.makeIterator()
guard let firstElement = iterator.next() else {
// newElements is empty, nothing to do
return
}
guard let secondElement = iterator.next() else {
// newElements just contains a single element
// and we hit the fast path
self = .one(firstElement)
return
}
elements.reserveCapacity(elements.count + newElements.underestimatedCount)
elements.append(firstElement)
elements.append(secondElement)
elements.appendRemainingElements(from: &iterator)
self = .arbitrary(elements)
} else {
elements.append(contentsOf: newElements)
self = .arbitrary(elements)
}
}
}
@discardableResult
@inlinable
mutating func remove(at index: Int) -> Element {
switch self {
case .one(let oldElement):
guard index == 0 else {
fatalError("index \(index) out of bounds")
}
self = .arbitrary([])
return oldElement
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
return elements.remove(at: index)
}
}
@inlinable
mutating func removeAll(where shouldBeRemoved: (Element) throws -> Bool) rethrows {
switch self {
case .one(let oldElement):
if try shouldBeRemoved(oldElement) {
self = .arbitrary([])
}
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
return try elements.removeAll(where: shouldBeRemoved)
}
}
@inlinable
mutating func sort(by areInIncreasingOrder: (Element, Element) throws -> Bool) rethrows {
switch self {
case .one:
// a collection of just one element is always sorted, nothing to do
break
case .arbitrary(var elements):
defer {
self = .arbitrary(elements)
}
try elements.sort(by: areInIncreasingOrder)
}
}
}
extension Array {
@inlinable
mutating func appendRemainingElements(from iterator: inout some IteratorProtocol<Element>) {
while let nextElement = iterator.next() {
append(nextElement)
}
}
}
@@ -0,0 +1,637 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2023 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if compiler(>=6.1)
/// An error that is thrown from the various `send` methods of the
/// ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// This error is thrown when the channel is already finished when
/// trying to send new elements to the source.
@available(AsyncAlgorithms 1.1, *)
public struct MultiProducerSingleConsumerAsyncChannelAlreadyFinishedError: Error {
@usableFromInline
init() {}
}
/// A multi-producer single-consumer channel.
///
/// The ``MultiProducerSingleConsumerAsyncChannel`` provides a ``MultiProducerSingleConsumerAsyncChannel/Source`` to
/// send values to the channel. The channel supports different back pressure strategies to control the
/// buffering and demand. The channel will buffer values until its backpressure strategy decides that the
/// producer have to wait.
///
/// This channel is also suitable for the single-producer single-consumer use-case
///
/// ## Using a MultiProducerSingleConsumerAsyncChannel
///
/// To use a ``MultiProducerSingleConsumerAsyncChannel`` you have to create a new channel with its source first by calling
/// the ``MultiProducerSingleConsumerAsyncChannel/makeChannel(of:throwing:backpressureStrategy:)`` method.
/// Afterwards, you can pass the source to the producer and the channel to the consumer.
///
/// ```
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 2, high: 4)
/// )
///
/// // The channel and source can be extracted from the returned type
/// let channel = consume channelAndSource.channel
/// let source = consume channelAndSource.source
/// ```
///
/// ### Asynchronous producing
///
/// Values can be send to the source from asynchronous contexts using ``MultiProducerSingleConsumerAsyncChannel/Source/send(contentsOf:)-1h7t9``
/// and ``MultiProducerSingleConsumerAsyncChannel/Source/send(_:)->()``. Backpressure results in calls
/// to the `send` methods to be suspended. Once more elements should be produced the `send` methods will be resumed.
///
/// ```
/// try await withThrowingTaskGroup(of: Void.self) { group in
/// group.addTask {
/// try await source.send(1)
/// try await source.send(2)
/// try await source.send(3)
/// }
///
/// for await element in channel {
/// print(element)
/// }
/// }
/// ```
///
/// ### Synchronous produceing
///
/// Values can also be send to the source from synchronous context. Backpressure is also exposed on the synchronous contexts; however,
/// it is up to the caller to decide how to properly translate the backpressure to underlying producer e.g. by blocking the thread.
///
/// ```swift
/// do {
/// let sendResult = try source.send(contentsOf: sequence)
///
/// switch sendResult {
/// case .produceMore:
/// // Trigger more production in the underlying system
///
/// case .enqueueCallback(let callbackHandle):
/// // There are enough values in the channel already. We need to enqueue
/// // a callback to get notified when we should produce more.
/// callbackHandle.enqueueCallback(onProduceMore: { result in
/// switch result {
/// case .success:
/// // Trigger more production in the underlying system
/// case .failure(let error):
/// // Terminate the underlying producer
/// }
/// })
/// }
/// } catch {
/// // `send(contentsOf:)` throws if the channel already terminated
/// }
/// ```
///
/// ### Multiple producers
///
/// To support multiple producers the source offers a ``Source/makeAdditionalSource()`` method to produce a new source.
///
/// ### Terminating the production of values
///
/// The consumer can be terminated through multiple ways:
/// - Calling ``Source/finish(throwing:)``.
/// - Deiniting all sources.
///
/// In both cases, if there are still elements buffered by the channel, then the consumer will receive
/// all buffered elements. Afterwards it will be terminated.
///
/// ### Observing termination of the consumer
///
/// When the consumer stops consumption by either deiniting the channel or the task calling ``next(isolation:)``
/// getting cancelled, the source will get notified about the termination if a termination callback has been set
/// before by calling ``Source/setOnTerminationCallback(_:)``.
@available(AsyncAlgorithms 1.1, *)
public struct MultiProducerSingleConsumerAsyncChannel<Element, Failure: Error>: ~Copyable {
/// The backing storage.
@usableFromInline
let storage: _Storage
/// A struct containing the initialized channel and source.
///
/// This struct can be deconstructed by consuming the individual
/// components from it.
///
/// ```swift
/// let channelAndSource = MultiProducerSingleConsumerAsyncChannel.makeChannel(
/// of: Int.self,
/// backpressureStrategy: .watermark(low: 5, high: 10)
/// )
/// var channel = consume channelAndSource.channel
/// var source = consume channelAndSource.source
/// ```
@frozen
public struct ChannelAndStream: ~Copyable {
/// The channel.
@usableFromInline
var channel: MultiProducerSingleConsumerAsyncChannel?
/// Takes and returns the channel.
///
/// - Important: If this is called more than once it will result in a runtime crash.
@inlinable
public mutating func takeChannel() -> sending MultiProducerSingleConsumerAsyncChannel {
return self.channel.takeSending()!
}
/// The source.
public var source: Source
init(
channel: consuming MultiProducerSingleConsumerAsyncChannel,
source: consuming Source
) {
self.channel = .some(channel)
self.source = source
}
}
/// Initializes a new ``MultiProducerSingleConsumerAsyncChannel`` and an ``MultiProducerSingleConsumerAsyncChannel/Source``.
///
/// - Parameters:
/// - elementType: The element type of the channel.
/// - failureType: The failure type of the channel.
/// - backpressureStrategy: The backpressure strategy that the channel should use.
/// - Returns: A struct containing the channel and its source. The source should be passed to the
/// producer while the channel should be passed to the consumer.
public static func makeChannel(
of elementType: Element.Type = Element.self,
throwing failureType: Failure.Type = Never.self,
backpressureStrategy: Source.BackpressureStrategy
) -> sending ChannelAndStream {
let storage = _Storage(
backpressureStrategy: backpressureStrategy.internalBackpressureStrategy
)
let source = Source(storage: storage)
return .init(channel: .init(storage: storage), source: source)
}
init(storage: _Storage) {
self.storage = storage
}
deinit {
self.storage.channelDeinitialized()
}
/// Returns the next element.
///
/// If this method returns `nil` it indicates that no further values can ever
/// be returned. The channel automatically closes when all sources have been deinited.
///
/// If there are no elements and the channel has not been finished yet, this method will
/// suspend until an element is send to the channel.
///
/// If the task calling this method is cancelled this method will return `nil`.
///
/// - Parameter isolation: The callers isolation.
/// - Returns: The next buffered element.
@inlinable
public mutating func next(
isolation: isolated (any Actor)? = #isolation
) async throws(Failure) -> Element? {
do {
return try await self.storage.next()
} catch {
// This force-cast is safe since we only allow closing the source with this failure
// We only need this force cast since continuations don't support typed throws yet.
throw error as! Failure
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel {
/// A struct to send values to the channel.
///
/// Use this source to provide elements to the channel by calling one of the `send` methods.
public struct Source: ~Copyable {
/// A struct representing the backpressure of the channel.
public struct BackpressureStrategy: Sendable {
var internalBackpressureStrategy: _InternalBackpressureStrategy
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
public static func watermark(low: Int, high: Int) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: nil)
)
)
}
/// A backpressure strategy using a high and low watermark to suspend and resume production respectively.
///
/// - Parameters:
/// - low: When the number of buffered elements drops below the low watermark, producers will be resumed.
/// - high: When the number of buffered elements rises above the high watermark, producers will be suspended.
/// - waterLevelForElement: A closure used to compute the contribution of each buffered element to the current water level.
///
/// - Important: `waterLevelForElement` will be called during a lock on each element when it is written into the source and when
/// it is consumed from the channel, so it must be side-effect free and at best constant in time.
public static func watermark(
low: Int,
high: Int,
waterLevelForElement: @escaping @Sendable (borrowing Element) -> Int
) -> BackpressureStrategy {
.init(
internalBackpressureStrategy: .watermark(
.init(low: low, high: high, waterLevelForElement: waterLevelForElement)
)
)
}
}
/// A type that indicates the result of sending elements to the source.
public enum SendResult: ~Copyable, Sendable {
/// A handle that is returned when the channel's backpressure strategy indicated that production should
/// be suspended. Use this handle to enqueue a callback by calling the ``CallbackHandle/enqueueCallback(onProduceMore:)`` method.
///
/// - Important: ``CallbackHandle/enqueueCallback(onProduceMore:)`` and ``CallbackHandle/cancelCallback()`` must
/// only be called once.
public struct CallbackHandle: Sendable, Hashable {
@usableFromInline
let _id: UInt64
@usableFromInline
let _storage: _Storage
@usableFromInline
init(id: UInt64, storage: _Storage) {
self._id = id
self._storage = storage
}
/// Enqueues a callback that will be invoked once more elements should be produced.
///
/// - Important: Calling enqueue more than once is **not allowed**.
///
/// - Parameters:
/// - onProduceMore: The callback which gets invoked once more elements should be produced.
@inlinable
public mutating func enqueueCallback(
onProduceMore: sending @escaping (Result<Void, Error>) -> Void
) {
self._storage.enqueueProducer(callbackToken: self._id, onProduceMore: onProduceMore)
}
/// Cancel an enqueued callback.
///
/// - Note: This methods supports being called before ``enqueueCallback(onProduceMore:)`` is called.
///
/// - Important: Calling enqueue more than once is **not allowed**.
@inlinable
public mutating func cancelCallback() {
self._storage.cancelProducer(callbackToken: self._id)
}
@inlinable
public static func == (lhs: Self, rhs: Self) -> Bool {
lhs._id == rhs._id
}
@inlinable
public func hash(into hasher: inout Hasher) {
hasher.combine(self._id)
}
}
/// Indicates that more elements should be produced and send to the source.
case produceMore
/// Indicates that a callback should be enqueued.
case enqueueCallback(CallbackHandle)
}
@usableFromInline
let _storage: _Storage
@usableFromInline
let _id: UInt64
internal init(
storage: _Storage
) {
self._storage = storage
self._id = self._storage.sourceInitialized()
}
deinit {
self._storage.sourceDeinitialized()
}
/// Sets a callback to invoke when the channel terminated.
///
/// This is called after the last element has been consumed by the channel.
/// If the channel has already terminated this callback is called immediately.
///
/// - Important: Only one termination callback can be set per source. Setting a callback if
/// a previous one has been set will override the previous one.
public func setOnTerminationCallback(_ callback: (@Sendable () -> Void)?) {
self._storage.setOnTerminationCallback(sourceID: self._id, callback: callback)
}
/// Creates a new source which can be used to send elements to the channel concurrently.
///
/// The channel will only automatically be finished if all existing sources have been deinited.
///
/// - Returns: A new source for sending elements to the channel.
public mutating func makeAdditionalSource() -> sending Self {
.init(storage: self._storage)
}
/// Sends new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// - Parameter sequence: The elements to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
@inlinable
public mutating func send<S>(
contentsOf sequence: consuming sending S
) throws -> SendResult where Element == S.Element, S: Sequence, Element: Copyable {
try self._storage.send(contentsOf: sequence)
}
/// Send the element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// - Parameter element: The element to send to the channel.
/// - Returns: The result that indicates if more elements should be produced at this time.
@inlinable
public mutating func send(_ element: consuming sending Element) throws -> SendResult {
try self._storage.send(contentsOf: CollectionOfOne(element))
}
/// Send new elements to the channel and provide a callback which will be invoked once more elements should be produced.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(contentsOf:onProduceMore:)``.
@inlinable
public mutating func send<S>(
contentsOf sequence: consuming sending S,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) where Element == S.Element, S: Sequence, Element: Copyable {
do {
let sendResult = try self.send(contentsOf: sequence)
switch consume sendResult {
case .produceMore:
onProduceMore(Result<Void, Error>.success(()))
case .enqueueCallback(var callbackHandle):
callbackHandle.enqueueCallback(onProduceMore: onProduceMore)
}
} catch {
onProduceMore(.failure(error))
}
}
/// Sends the element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then `onProduceMore` will be invoked with
/// a `Result.failure`.
///
/// - Parameters:
/// - element: The element to send to the channel.
/// - onProduceMore: The callback which gets invoked once more elements should be produced. This callback might be
/// invoked during the call to ``send(_:onProduceMore:)``.
@inlinable
public mutating func send(
_ element: consuming sending Element,
onProduceMore: @escaping @Sendable (Result<Void, Error>) -> Void
) {
do {
let sendResult = try self.send(element)
switch consume sendResult {
case .produceMore:
onProduceMore(Result<Void, Error>.success(()))
case .enqueueCallback(var callbackHandle):
callbackHandle.enqueueCallback(onProduceMore: onProduceMore)
}
} catch {
onProduceMore(.failure(error))
}
}
/// Send new elements to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// first element of the provided sequence. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
@inlinable
public mutating func send<S>(
contentsOf sequence: consuming sending S
) async throws where Element == S.Element, S: Sequence, Element: Copyable {
let syncSend: (sending S, inout Self) throws -> SendResult = { try $1.send(contentsOf: $0) }
let sendResult = try syncSend(sequence, &self)
switch consume sendResult {
case .produceMore:
return ()
case .enqueueCallback(let callbackToken):
let id = callbackToken._id
let storage = self._storage
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { continuation in
self._storage.enqueueProducer(
callbackToken: id,
continuation: continuation
)
}
} onCancel: {
storage.cancelProducer(callbackToken: id)
}
}
}
/// Send new element to the channel.
///
/// If there is a task consuming the channel and awaiting the next element then the task will get resumed with the
/// provided element. If the channel already terminated then this method will throw an error
/// indicating the failure.
///
/// This method returns once more elements should be produced.
///
/// - Parameters:
/// - element: The element to send to the channel.
@inlinable
public mutating func send(_ element: consuming sending Element) async throws {
let syncSend: (consuming sending Element, inout Self) throws -> SendResult = { try $1.send($0) }
let sendResult = try syncSend(element, &self)
switch consume sendResult {
case .produceMore:
return ()
case .enqueueCallback(let callbackHandle):
let id = callbackHandle._id
let storage = self._storage
try await withTaskCancellationHandler {
try await withUnsafeThrowingContinuation { continuation in
self._storage.enqueueProducer(
callbackToken: id,
continuation: continuation
)
}
} onCancel: {
storage.cancelProducer(callbackToken: id)
}
}
}
/// Send the elements of the asynchronous sequence to the channel.
///
/// This method returns once the provided asynchronous sequence or the channel finished.
///
/// - Important: This method does not finish the source if consuming the upstream sequence terminated.
///
/// - Parameters:
/// - sequence: The elements to send to the channel.
@inlinable
public mutating func send<S>(contentsOf sequence: consuming sending S) async throws
where Element == S.Element, S: AsyncSequence, Element: Copyable, S: Sendable, Element: Sendable {
for try await element in sequence {
try await self.send(contentsOf: CollectionOfOne(element))
}
}
/// Indicates that the production terminated.
///
/// After all buffered elements are consumed the subsequent call to ``MultiProducerSingleConsumerAsyncChannel/next(isolation:)`` will return
/// `nil` or throw an error.
///
/// Calling this function more than once has no effect. After calling finish, the channel enters a terminal state and doesn't accept
/// new elements.
///
/// - Parameters:
/// - error: The error to throw, or `nil`, to finish normally.
@inlinable
public consuming func finish(throwing error: Failure? = nil) {
self._storage.finish(error)
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel where Element: Copyable {
struct ChannelAsyncSequence: AsyncSequence {
@usableFromInline
final class _Backing: Sendable {
@usableFromInline
let storage: MultiProducerSingleConsumerAsyncChannel._Storage
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self.storage = storage
self.storage.sequenceInitialized()
}
deinit {
self.storage.sequenceDeinitialized()
}
}
@usableFromInline
let _backing: _Backing
public func makeAsyncIterator() -> Self.Iterator {
.init(storage: self._backing.storage)
}
}
/// Converts the channel to an asynchronous sequence for consumption.
///
/// - Important: The returned asynchronous sequence only supports a single iterator to be created and
/// will fatal error at runtime on subsequent calls to `makeAsyncIterator`.
public consuming func elements() -> some (AsyncSequence<Element, Failure> & Sendable) {
ChannelAsyncSequence(_backing: .init(storage: self.storage))
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel.ChannelAsyncSequence where Element: Copyable {
struct Iterator: AsyncIteratorProtocol {
@usableFromInline
final class _Backing {
@usableFromInline
let storage: MultiProducerSingleConsumerAsyncChannel._Storage
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self.storage = storage
self.storage.iteratorInitialized()
}
deinit {
self.storage.iteratorDeinitialized()
}
}
@usableFromInline
let _backing: _Backing
init(storage: MultiProducerSingleConsumerAsyncChannel._Storage) {
self._backing = .init(storage: storage)
}
@inlinable
mutating func next() async throws -> Element? {
do {
return try await self._backing.storage.next(isolation: nil)
} catch {
throw error as! Failure
}
}
@inlinable
mutating func next(
isolation actor: isolated (any Actor)? = #isolation
) async throws(Failure) -> Element? {
do {
return try await self._backing.storage.next(isolation: actor)
} catch {
throw error as! Failure
}
}
}
}
@available(AsyncAlgorithms 1.1, *)
extension MultiProducerSingleConsumerAsyncChannel.ChannelAsyncSequence: Sendable {}
#endif
@@ -0,0 +1,30 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
#if compiler(>=6.0)
import DequeModule
import Synchronization
@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
final class ManualTaskExecutor: TaskExecutor {
private let jobs = Mutex<Deque<UnownedJob>>(.init())
func enqueue(_ job: UnownedJob) {
self.jobs.withLock { $0.append(job) }
}
func run() {
while let job = self.jobs.withLock({ $0.popFirst() }) {
job.runSynchronously(on: self.asUnownedTaskExecutor())
}
}
}
#endif