[AsyncStreaming] Propagate cancellation to late readers (#449)

* [AsyncStreaming] Propagate cancellation to late readers

Distinguish cancellation from normal source completion when a reader continuation is installed after the channel has already finished.

* [AsyncStreaming] Distinguish terminal read states

Track cancellation separately from an already-consumed terminal result so normal source completion does not throw CancellationError. Precondition on repeated reads after cancellation, a final element, or a source failure, with coverage for each terminal path.

* [AsyncStreaming] Handle pending reader cancellation

Deliver cancellation exactly once when it races with a resumed reader, preserve fused final-element completion, and align terminal-read tests and documentation with the reader contract.

* [AsyncStreaming] Test cancellation through public API

Remove the internal-only state-machine test so the regression suite exercises the supported AsyncStreaming interface without @testable import.
This commit is contained in:
Tianhao Liu authored and GitHub committed 2026-09-03 10:53:07 +02:00
1 parent a5195afbd5
commit 11645b8feb
4 files changed
+174 -54

No files matched your search

@@ -446,8 +446,9 @@ extension DuplexAsyncChannel {
/// in `read`) — and whose outer `.second` arm carries the failure
/// thrown by `body`.
///
/// - Important: After the reader observes a non-`nil` `finalElement`,
/// calling `read(body:)` again is a programmer error.
/// - Important: After the reader observes a non-`nil` `finalElement` or
/// `read(body:)` throws a read-side error, calling `read(body:)` again is
/// a programmer error.
@inlinable
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
@@ -513,13 +514,8 @@ extension DuplexAsyncChannel {
throw .second(error)
}
case .returnNil:
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .throwCancellation:
throw .first(.second(CancellationError()))
case .suspend:
do {
@@ -272,6 +272,8 @@ extension MultiProducerSingleConsumerAsyncChannel {
switch consume action {
case .resumeReader(let c):
c.resume()
case .resumeReaderWithCancellationError(let c):
c.resume(throwing: .second(CancellationError()))
case .none:
break
}
@@ -410,12 +412,12 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
case .channeling(let s):
let producers = Array(s.suspendedProducers.lazy.map { $0.1 })
let onTerminations = s.onTerminations
self = .init(state: .finished(.init(sourceFinished: false)))
self = .init(state: .finished(.consumed))
return .failProducersAndCallOnTerminations(producers, onTerminations)
case .sourceFinished(let s):
let onTerminations = s.onTerminations
self = .init(state: .finished(.init(sourceFinished: true)))
self = .init(state: .finished(.consumed))
return .callOnTerminations(onTerminations)
case .finished(let s):
@@ -679,7 +681,8 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
/// The channel was finished with a failure and the buffer is now drained;
/// throw the failure to the reader.
case throwFailure(Failure?, [(UInt64, @Sendable () -> Void)])
case returnNil
/// Cancellation finished the channel before it could be delivered to the reader.
case throwCancellation
}
@inlinable
@@ -731,7 +734,7 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
let fe = s.finalElement.swap(newValue: nil)
let onTerminations = s.onTerminations
let failure = s.failure
self = .init(state: .finished(.init(sourceFinished: true)))
self = .init(state: .finished(.consumed))
if let failure {
return .throwFailure(failure, onTerminations)
@@ -745,8 +748,14 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
)
case .finished(let s):
self = .init(state: .finished(s))
return .returnNil
switch s {
case .cancelled:
self = .init(state: .finished(.consumed))
return .throwCancellation
case .consumed:
self = .init(state: .finished(.consumed))
preconditionFailure("MultiProducerSingleConsumerAsyncChannel.read called after termination")
}
}
}
@@ -800,6 +809,9 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
@usableFromInline
enum SuspendReadAction: ~Copyable, Sendable {
case resumeReader(UnsafeContinuation<Void, EitherError<Failure, CancellationError>>)
case resumeReaderWithCancellationError(
UnsafeContinuation<Void, EitherError<Failure, CancellationError>>
)
}
@inlinable
@@ -825,8 +837,16 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
return .resumeReader(continuation)
case .finished(let s):
self = .init(state: .finished(s))
return .resumeReader(continuation)
switch s {
case .cancelled:
// Cancellation may finish the channel before this continuation is installed.
// Consume that pending cancellation exactly once.
self = .init(state: .finished(.consumed))
return .resumeReaderWithCancellationError(continuation)
case .consumed:
self = .init(state: .finished(.consumed))
preconditionFailure("MultiProducerSingleConsumerAsyncChannel.read called after termination")
}
}
}
@@ -850,10 +870,11 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage {
let reader = s.readerContinuation.take()
let producers = Array(s.suspendedProducers.lazy.map { $0.1 })
let onTerminations = s.onTerminations
self = .init(state: .finished(.init(sourceFinished: false)))
if let reader {
self = .init(state: .finished(.consumed))
return .resumeReaderWithCancellationError(reader, producers, onTerminations)
}
self = .init(state: .finished(.cancelled))
return .failProducersAndCallOnTerminations(producers, onTerminations)
case .sourceFinished(let s):
@@ -980,12 +1001,9 @@ extension MultiProducerSingleConsumerAsyncChannel._Storage._StateMachine {
}
@usableFromInline
struct Finished: ~Copyable, Sendable {
@usableFromInline
var sourceFinished: Bool
@inlinable
init(sourceFinished: Bool) { self.sourceFinished = sourceFinished }
enum Finished: Sendable {
case cancelled
case consumed
}
case channeling(Channeling)
@@ -320,8 +320,9 @@ extension MultiProducerSingleConsumerAsyncChannel {
/// the task is canceled while suspended in `read`) — and whose outer
/// `.second` arm carries the failure thrown by `body`.
///
/// - Important: After the reader observes a non-`nil` `finalElement`,
/// calling `read(body:)` again is a programmer error.
/// - Important: After the reader observes a non-`nil` `finalElement` or
/// `read(body:)` throws a read-side error, calling `read(body:)` again is
/// a programmer error.
@inlinable
public mutating func read<Return: ~Copyable, BodyFailure: Error>(
body: (inout UniqueDeque<Element>, consuming FinalElement?) async throws(BodyFailure) -> Return
@@ -391,13 +392,8 @@ extension MultiProducerSingleConsumerAsyncChannel {
throw .second(error)
}
case .returnNil:
var empty = UniqueDeque<Element>()
do throws(BodyFailure) {
return try await body(&empty, nil)
} catch {
throw .second(error)
}
case .throwCancellation:
throw .first(.second(CancellationError()))
case .suspend:
do {
@@ -17,6 +17,8 @@ import ContainersPreview
import DequeModule
import Testing
private struct MultiProducerSingleConsumerAsyncChannelTestError: Error {}
@Suite(.serialized)
struct MultiProducerSingleConsumerAsyncChannelTests {
// MARK: - AsyncReader.read
@@ -75,7 +77,120 @@ struct MultiProducerSingleConsumerAsyncChannelTests {
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readReturnsEmptyBufferOnEOSAfterFinish() async throws {
func readThrowsCancellationWhenTaskStartsCancelled() async {
await withTaskGroup(of: Void.self) { group in
group.cancelAll()
// A child added to an already-cancelled group starts cancelled, so the
// cancellation handler runs before the reader continuation is installed.
group.addTask {
await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
_ = consume source
do {
_ = try await channel.read { _, _ in
Issue.record("read body must not run after cancellation")
}
Issue.record("expected CancellationError")
} catch let EitherError<EitherError<Never, CancellationError>, Never>.first(.second(error)) {
_ = error
} catch {
Issue.record("unexpected error: \(error)")
}
}
}
await group.waitForAll()
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readDoesNotThrowCancellationWhenSourceFinishes() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
let source = source
source.finish()
var sawFinalElement = false
try await channel.read { buffer, finalElement in
#expect(buffer.count == 0)
sawFinalElement = finalElement != nil
}
#expect(sawFinalElement)
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readAfterCancellationPreconditions() async {
await #expect(processExitsWith: .failure) {
await withTaskGroup(of: Void.self) { group in
group.cancelAll()
group.addTask {
await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
_ = consume source
try? await channel.read { _, _ in }
try? await channel.read { _, _ in }
}
}
await group.waitForAll()
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readAfterFinalElementPreconditions() async {
await #expect(processExitsWith: .failure) {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
let source = source
source.finish()
try await channel.read { _, finalElement in
#expect(finalElement != nil)
}
try await channel.read { _, _ in }
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readAfterFailurePreconditions() async {
await #expect(processExitsWith: .failure) {
await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
throwing: MultiProducerSingleConsumerAsyncChannelTestError.self,
backpressureStrategy: .watermark(low: 1, high: 2)
) { channel, source in
var channel = channel
let source = source
source.finish(throwing: MultiProducerSingleConsumerAsyncChannelTestError())
try? await channel.read { _, _ in }
try? await channel.read { _, _ in }
}
}
}
@available(macOS 15.0, iOS 18.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@Test
func readReturnsEmptyBufferAndFinalElementOnEOSAfterFinish() async throws {
try await MultiProducerSingleConsumerAsyncChannel.withChannel(
of: Int.self,
backpressureStrategy: .watermark(low: 2, high: 4)
@@ -86,17 +201,18 @@ struct MultiProducerSingleConsumerAsyncChannelTests {
var writeBuffer = UniqueArray<Int>(minimumCapacity: 1)
writeBuffer.append(1)
try await source.write(buffer: &writeBuffer)
source.finish()
try await channel.read { buffer, _ in
try await channel.read { buffer, finalElement in
#expect(buffer.count == 1)
#expect(finalElement == nil)
buffer.removeAll()
}
var sawEmpty = false
try await channel.read { buffer, _ in
sawEmpty = buffer.count == 0
source.finish()
try await channel.read { buffer, finalElement in
#expect(buffer.count == 0)
#expect(finalElement != nil)
}
#expect(sawEmpty)
}
}
@@ -426,15 +542,12 @@ struct MultiProducerSingleConsumerAsyncChannelTests {
var source = source
group.addTask {
// Reader drains until EOS.
// Reader drains until it observes the final element.
while true {
var done = false
try await channel.read { buffer, _ in
if buffer.count == 0 {
done = true
} else {
buffer.removeAll()
}
try await channel.read { buffer, finalElement in
buffer.removeAll()
done = finalElement != nil
}
if done { break }
}
@@ -465,13 +578,10 @@ struct MultiProducerSingleConsumerAsyncChannelTests {
nonisolated(unsafe) var collected: [Int] = []
var done = false
while !done {
try await channel.read { buffer, _ in
if buffer.count == 0 {
done = true
} else {
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
}
try await channel.read { buffer, finalElement in
var c = buffer.consumeAll()
while let v = c.next() { collected.append(v) }
done = finalElement != nil
}
}
#expect(collected == Array(0..<total))