diff --git a/NOTICE.txt b/NOTICE.txt index d79250ea5..f4389cb2a 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -71,7 +71,7 @@ This product contains a derivation of Fabian Fett's 'Base64.swift'. --- -This product contains a derivation of "XCTest+AsyncAwait.swift" from AsyncHTTPClient. +This product contains a derivation of "XCTest+AsyncAwait.swift" & "StructuredConcurrencyHelpers" from AsyncHTTPClient. * LICENSE (Apache License 2.0): * https://www.apache.org/licenses/LICENSE-2.0 diff --git a/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift b/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift index 43d6aa213..7a7787efc 100644 --- a/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift +++ b/Sources/NIOPosix/MultiThreadedEventLoopGroup.swift @@ -622,3 +622,43 @@ extension NIODeadline { return self - target } } + +extension MultiThreadedEventLoopGroup { + #if compiler(>=6.0) + /// Start & automatically shut down a new ``MultiThreadedEventLoopGroup``. + /// + /// This method allows to start & automatically dispose of a ``MultiThreadedEventLoopGroup`` following the principle of Structured Concurrency. + /// The ``MultiThreadedEventLoopGroup`` is guaranteed to be shut down upon return, whether `body` throws or not. + /// + /// - Note: Outside of top-level code (typically in your main function) or tests, you should generally not use this function to create a new + /// ``MultiThreadedEventLoopGroup`` because creating & destroying threads is expensive. Instead, share an existing one. + @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *) + public static func withEventLoopGroup( + numberOfThreads: Int, + metricsDelegate: (any NIOEventLoopMetricsDelegate)? = nil, + isolation actor: isolated (any Actor)? = #isolation, + _ body: (MultiThreadedEventLoopGroup) async throws -> Result + ) async throws -> Result { + let group = MultiThreadedEventLoopGroup( + numberOfThreads: numberOfThreads, + canBeShutDown: .notByUser, // We want to prevent direct user shutdowns. + metricsDelegate: metricsDelegate, + selectorFactory: NIOPosix.Selector.init + ) + return try await asyncDo { + try await body(group) + } finally: { _ in + let q = DispatchQueue(label: "MTELG.shutdown") + let _: () = try await withCheckedThrowingContinuation { (cont) -> Void in + group._shutdownGracefully(queue: q, allowShuttingDownOverride: true) { error in + if let error { + cont.resume(throwing: error) + } else { + cont.resume() + } + } + } + } + } + #endif +} diff --git a/Sources/NIOPosix/StructuredConcurrencyHelpers.swift b/Sources/NIOPosix/StructuredConcurrencyHelpers.swift new file mode 100644 index 000000000..07afda6f6 --- /dev/null +++ b/Sources/NIOPosix/StructuredConcurrencyHelpers.swift @@ -0,0 +1,97 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2025 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 +// +//===----------------------------------------------------------------------===// + +//===----------------------------------------------------------------------===// +// +// This source file is part of the AsyncHTTPClient open source project +// +// Copyright (c) 2025 Apple Inc. and the AsyncHTTPClient project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of AsyncHTTPClient project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// +// swift-format-ignore +// Note: Whitespace changes are used to workaround compiler bug +// https://github.com/swiftlang/swift/issues/79285 + +#if compiler(>=6.0) +@inlinable +@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) +internal func asyncDo( + isolation: isolated (any Actor)? = #isolation, + // DO NOT FIX THE WHITESPACE IN THE NEXT LINE UNTIL 5.10 IS UNSUPPORTED + // https://github.com/swiftlang/swift/issues/79285 + _ body: () async throws -> sending R, finally: sending @escaping ((any Error)?) async throws -> Void) async throws -> sending R { + let result: R + do { + result = try await body() + } catch { + // `body` failed, we need to invoke `finally` with the `error`. + + // This _looks_ unstructured but isn't really because we unconditionally always await the return. + // We need to have an uncancelled task here to assure this is actually running in case we hit a + // cancellation error. + try await Task { + try await finally(error) + }.value + throw error + } + + // `body` succeeded, we need to invoke `finally` with `nil` (no error). + + // This _looks_ unstructured but isn't really because we unconditionally always await the return. + // We need to have an uncancelled task here to assure this is actually running in case we hit a + // cancellation error. + try await Task { + try await finally(nil) + }.value + return result +} +#else +@inlinable +@available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) +internal func asyncDo( + _ body: () async throws -> R, + finally: @escaping @Sendable ((any Error)?) async throws -> Void +) async throws -> R { + let result: R + do { + result = try await body() + } catch { + // `body` failed, we need to invoke `finally` with the `error`. + + // This _looks_ unstructured but isn't really because we unconditionally always await the return. + // We need to have an uncancelled task here to assure this is actually running in case we hit a + // cancellation error. + try await Task { + try await finally(error) + }.value + throw error + } + + // `body` succeeded, we need to invoke `finally` with `nil` (no error). + + // This _looks_ unstructured but isn't really because we unconditionally always await the return. + // We need to have an uncancelled task here to assure this is actually running in case we hit a + // cancellation error. + try await Task { + try await finally(nil) + }.value + return result +} +#endif diff --git a/Tests/NIOPosixTests/EventLoopTest.swift b/Tests/NIOPosixTests/EventLoopTest.swift index 737ff1568..456c37569 100644 --- a/Tests/NIOPosixTests/EventLoopTest.swift +++ b/Tests/NIOPosixTests/EventLoopTest.swift @@ -2014,6 +2014,62 @@ final class EventLoopTest: XCTestCase { } } } + + #if compiler(>=6.0) + func testStructuredConcurrencyMTELGStartStop() async throws { + let loops = try await MultiThreadedEventLoopGroup.withEventLoopGroup( + numberOfThreads: 3 + ) { group in + let loops = Array(group.makeIterator()).map { $0 as! SelectableEventLoop } + for loop in loops { + XCTAssert( + loop.debugDescription.contains("state = open"), + loop.debugDescription + ) + XCTAssert( + !loop.debugDescription.contains("selector = Selector { descriptor = -1 }"), + loop.debugDescription + ) + } + return loops + } + XCTAssertEqual(3, loops.count) + for loop in loops { + XCTAssert( + loop.debugDescription.contains("state = resourcesReclaimed"), + loop.debugDescription + ) + XCTAssert( + loop.debugDescription.contains("selector = Selector { descriptor = -1 }") + ) + } + } + + func testStructuredConcurrencyMTELGStartStopUserCannotStopMidWay() async throws { + let threadCount = try await MultiThreadedEventLoopGroup.withEventLoopGroup( + numberOfThreads: 3 + ) { group in + do { + try await group.shutdownGracefully() + XCTFail("shutdown worked, it shouldn't have") + } catch EventLoopError.unsupportedOperation { + // okay + return Array(group.makeIterator()).count + } + return -1 + } + XCTAssertEqual(3, threadCount) + } + + func testStructuredConcurrencyMTELGStartStopCanDoBasicAsyncStuff() async throws { + let actual = try await MultiThreadedEventLoopGroup.withEventLoopGroup( + numberOfThreads: 3 + ) { group in + try await group.any().scheduleTask(in: .milliseconds(10), { "cool" }).futureResult.get() + } + XCTAssertEqual("cool", actual) + } + #endif } private final class EventLoopWithPreSucceededFuture: EventLoop {