mirror of
https://github.com/apple/swift-nio
synced 2026-11-22 04:30:41 +00:00
ELF.getAbandoningOnCancel() (#3722)
### Motivation: `EventLoopFuture.get()` violates Structured Concurrency in two ways: 1. It doesn't automatically propagate cancellation 2. It doesn't return control back on cancellation (1) is unfixable without user help but (2) we can address. ### Modifications: - Add `EventLoopFuture.getAbandoningOnCancel()` ### Result: - Users now have a way to at least get back control.
This commit is contained in:
1 parent
c1ccdbcc95
commit
21de5f08c1
3 files changed
+159
-1
No files matched your search
@@ -83,6 +83,9 @@ extension EventLoopFuture {
|
||||
///
|
||||
/// This function can be used to bridge an `EventLoopFuture` into the `async` world. Ie. if you're in an `async`
|
||||
/// function and want to get the result of this future.
|
||||
///
|
||||
/// - seealso: ``getAbandoningOnCancel()`` which returns a `CancellationError` on cancellation (by abandoning this
|
||||
/// future) instead of ignoring cancellation altogether.
|
||||
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
|
||||
@preconcurrency
|
||||
@inlinable
|
||||
@@ -98,6 +101,33 @@ extension EventLoopFuture {
|
||||
}
|
||||
}.wrappedValue
|
||||
}
|
||||
|
||||
/// Get the value/error from an `EventLoopFuture` in an `async` context, abandoning the future on cancellation.
|
||||
///
|
||||
/// - warning: This method still violates Structured Concurrency: Cancelling the surrounding task does _not_
|
||||
/// cancel the operation that this future represents, it merely _abandons_ the future. In other words, the
|
||||
/// operation is likely still ongoing (holding on to its resources) and its result will be dropped. Unlike
|
||||
/// ``get()`` however, this method _will_ return promptly on cancellation, throwing `CancellationError`.
|
||||
///
|
||||
/// This function can be used to bridge an `EventLoopFuture` into the `async` world. Ie. if you're in an `async`
|
||||
/// function and want to get the result of this future.
|
||||
///
|
||||
/// If cancellation and the completion of this future race, either the future's result or a `CancellationError`
|
||||
/// may be returned.
|
||||
///
|
||||
/// - seealso: ``get()`` which ignores cancellation entirely and therefore only returns once this future completes.
|
||||
@available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
|
||||
@inlinable
|
||||
public func getAbandoningOnCancel() async throws -> Value where Value: Sendable {
|
||||
let promise = self.eventLoop.makePromise(of: Value.self)
|
||||
self.cascade(to: promise)
|
||||
return try await withTaskCancellationHandler {
|
||||
try await promise.futureResult.get()
|
||||
} onCancel: {
|
||||
// If the future completes first, this is a no-op (first completion wins).
|
||||
promise.fail(CancellationError())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#if canImport(Dispatch)
|
||||
|
||||
@@ -16,7 +16,10 @@ methods are ``EventLoopFuture/get()`` and
|
||||
``EventLoopPromise/completeWithTask(_:)``.
|
||||
|
||||
> Warning: The future ``EventLoopFuture/get()`` method does not support task
|
||||
> cancellation.
|
||||
> cancellation. If you need to return on cancellation, use
|
||||
> ``EventLoopFuture/getAbandoningOnCancel()``: it throws `CancellationError`
|
||||
> when the `Task` is cancelled but it merely _abandons_ the future, i.e. the
|
||||
> operation backing the future is likely still ongoing.
|
||||
|
||||
Here is a small example of how these work:
|
||||
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
//===----------------------------------------------------------------------===//
|
||||
//
|
||||
// This source file is part of the SwiftNIO open source project
|
||||
//
|
||||
// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
|
||||
// Licensed under Apache License v2.0
|
||||
//
|
||||
// See LICENSE.txt for license information
|
||||
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
|
||||
//
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
//
|
||||
//===----------------------------------------------------------------------===//
|
||||
|
||||
import NIOCore
|
||||
import NIOPosix
|
||||
import Testing
|
||||
|
||||
private struct DummyError: Error {}
|
||||
|
||||
@Suite("EventLoopFuture.getAbandoningOnCancel()")
|
||||
struct EventLoopFutureGetAbandoningOnCancelTests {
|
||||
private let loop = MultiThreadedEventLoopGroup.singleton.next()
|
||||
|
||||
@Test
|
||||
func returnsValueOfAlreadySucceededFuture() async throws {
|
||||
let value = try await self.loop.makeSucceededFuture(42).getAbandoningOnCancel()
|
||||
#expect(value == 42)
|
||||
}
|
||||
|
||||
@Test
|
||||
func returnsValueOfFutureThatSucceedsLater() async throws {
|
||||
let promise = self.loop.makePromise(of: Int.self)
|
||||
|
||||
try await withThrowingTaskGroup(of: Void.self) { group in
|
||||
group.addTask {
|
||||
let value = try await promise.futureResult.getAbandoningOnCancel()
|
||||
#expect(value == 42)
|
||||
}
|
||||
promise.succeed(42)
|
||||
try await group.waitForAll()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func throwsErrorOfFailedFuture() async throws {
|
||||
let future: EventLoopFuture<Int> = self.loop.makeFailedFuture(DummyError())
|
||||
await #expect(throws: DummyError.self) {
|
||||
try await future.getAbandoningOnCancel()
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
func throwsCancellationErrorAndAbandonsTheFutureOnCancellation() async throws {
|
||||
let promise = self.loop.makePromise(of: Int.self)
|
||||
let awaitingPromise = self.loop.makePromise(of: Void.self)
|
||||
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.addTask {
|
||||
awaitingPromise.succeed(())
|
||||
await #expect(throws: CancellationError.self) {
|
||||
try await promise.futureResult.getAbandoningOnCancel()
|
||||
}
|
||||
}
|
||||
|
||||
// Give the child task a chance to actually suspend on the future before we cancel it. Both orderings
|
||||
// (cancellation before and after the suspension) must throw `CancellationError` though.
|
||||
try? await awaitingPromise.futureResult.get()
|
||||
try? await self.loop.submit {}.get()
|
||||
|
||||
group.cancelAll()
|
||||
}
|
||||
|
||||
// Cancellation only abandoned the future, it didn't complete it: The underlying operation is still ongoing and
|
||||
// completing it later works just as before.
|
||||
promise.succeed(42)
|
||||
let value = try await promise.futureResult.get()
|
||||
#expect(value == 42)
|
||||
}
|
||||
|
||||
@Test
|
||||
func throwsCancellationErrorIfTheTaskIsAlreadyCancelled() async throws {
|
||||
let promise = self.loop.makePromise(of: Int.self)
|
||||
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.addTask {
|
||||
while !Task.isCancelled {
|
||||
await Task.yield()
|
||||
}
|
||||
await #expect(throws: CancellationError.self) {
|
||||
try await promise.futureResult.getAbandoningOnCancel()
|
||||
}
|
||||
}
|
||||
group.cancelAll()
|
||||
}
|
||||
|
||||
// The future itself is untouched, so we still need to complete it (or we'd leak an unfulfilled promise).
|
||||
promise.succeed(42)
|
||||
let value = try await promise.futureResult.get()
|
||||
#expect(value == 42)
|
||||
}
|
||||
|
||||
@Test
|
||||
func survivesCancellationRacingTheFuturesCompletion() async throws {
|
||||
for _ in 0..<100 {
|
||||
let promise = self.loop.makePromise(of: Int.self)
|
||||
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.addTask {
|
||||
do {
|
||||
let value = try await promise.futureResult.getAbandoningOnCancel()
|
||||
#expect(value == 42)
|
||||
} catch is CancellationError {
|
||||
// Also acceptable: cancellation won the race.
|
||||
} catch {
|
||||
Issue.record("unexpected error: \(error)")
|
||||
}
|
||||
}
|
||||
|
||||
promise.succeed(42)
|
||||
group.cancelAll()
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user