use NIOSingletons EventLoops/NIOThreadPool instead of spawning new

Author: Johannes Weiss

Package.swift

@@ -21,7 +21,7 @@ let package = Package(
         .library(name: "AsyncHTTPClient", targets: ["AsyncHTTPClient"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-nio.git", from: "2.50.0"),
+        .package(url: "https://github.com/apple/swift-nio.git", from: "2.57.0"),
         .package(url: "https://github.com/apple/swift-nio-ssl.git", from: "2.22.0"),
         .package(url: "https://github.com/apple/swift-nio-http2.git", from: "1.19.0"),
         .package(url: "https://github.com/apple/swift-nio-extras.git", from: "1.13.0"),
@@ -38,6 +38,8 @@ let package = Package(
                 .target(name: "CAsyncHTTPClient"),
                 .product(name: "NIO", package: "swift-nio"),
                 .product(name: "NIOCore", package: "swift-nio"),
+                .product(name: "NIOSingletonsPosix", package: "swift-nio"),
+                .product(name: "NIOSingletonsTransportServices", package: "swift-nio-transport-services"),
                 .product(name: "NIOPosix", package: "swift-nio"),
                 .product(name: "NIOHTTP1", package: "swift-nio"),
                 .product(name: "NIOConcurrencyHelpers", package: "swift-nio"),

README.md

@@ -27,14 +27,10 @@ and  `AsyncHTTPClient` dependency to your target:
 
 The code snippet below illustrates how to make a simple GET request to a remote server.
 
-Please note that the example will spawn a new `EventLoopGroup` which will _create fresh threads_ which is a very costly operation. In a real-world application that uses [SwiftNIO](https://github.com/apple/swift-nio) for other parts of your application (for example a web server), please prefer `eventLoopGroupProvider: .shared(myExistingEventLoopGroup)` to share the `EventLoopGroup` used by AsyncHTTPClient with other parts of your application.
-
-If your application does not use SwiftNIO yet, it is acceptable to use `eventLoopGroupProvider: .createNew` but please make sure to share the returned `HTTPClient` instance throughout your whole application. Do not create a large number of `HTTPClient` instances with `eventLoopGroupProvider: .createNew`, this is very wasteful and might exhaust the resources of your program.
-
 ```swift
 import AsyncHTTPClient
 
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 
 /// MARK: - Using Swift Concurrency
 let request = HTTPClientRequest(url: "https://apple.com/")
@@ -78,7 +74,7 @@ The default HTTP Method is `GET`. In case you need to have more control over the
 ```swift
 import AsyncHTTPClient
 
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 do {
     var request = HTTPClientRequest(url: "https://apple.com/")
     request.method = .POST
@@ -103,7 +99,7 @@ try await httpClient.shutdown()
 ```swift
 import AsyncHTTPClient
 
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 defer {
     try? httpClient.syncShutdown()
 }
@@ -129,15 +125,15 @@ httpClient.execute(request: request).whenComplete { result in
 ### Redirects following
 Enable follow-redirects behavior using the client configuration:
 ```swift
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew,
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton,
                             configuration: HTTPClient.Configuration(followRedirects: true))
 ```
 
 ### Timeouts
 Timeouts (connect and read) can also be set using the client configuration:
 ```swift
 let timeout = HTTPClient.Configuration.Timeout(connect: .seconds(1), read: .seconds(1))
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew,
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton,
                             configuration: HTTPClient.Configuration(timeout: timeout))
 ```
 or on a per-request basis:
@@ -151,7 +147,7 @@ The following example demonstrates how to count the number of bytes in a streami
 
 #### Using Swift Concurrency
 ```swift
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 do {
     let request = HTTPClientRequest(url: "https://apple.com/")
     let response = try await httpClient.execute(request, timeout: .seconds(30))
@@ -251,7 +247,7 @@ asynchronously, while reporting the download progress at the same time, like in
 example:
 
 ```swift
-let client = HTTPClient(eventLoopGroupProvider: .createNew)
+let client = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 let request = try HTTPClient.Request(
     url: "https://swift.org/builds/development/ubuntu1804/latest-build.yml"
 )
@@ -275,7 +271,7 @@ client.execute(request: request, delegate: delegate).futureResult
 ### Unix Domain Socket Paths
 Connecting to servers bound to socket paths is easy:
 ```swift
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 httpClient.execute(
     .GET,
     socketPath: "/tmp/myServer.socket",
@@ -285,7 +281,7 @@ httpClient.execute(
 
 Connecting over TLS to a unix domain socket path is possible as well:
 ```swift
-let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 httpClient.execute(
     .POST,
     secureSocketPath: "/tmp/myServer.socket",
@@ -312,7 +308,7 @@ The exclusive use of HTTP/1 is possible by setting `httpVersion` to `.http1Only`
 var configuration = HTTPClient.Configuration()
 configuration.httpVersion = .http1Only
 let client = HTTPClient(
-    eventLoopGroupProvider: .createNew,
+    eventLoopGroupProvider: .globalSingleton,
     configuration: configuration
 )
 ```

Sources/AsyncHTTPClient/Docs.docc/index.md

@@ -31,10 +31,6 @@ and  `AsyncHTTPClient` dependency to your target:
 
 The code snippet below illustrates how to make a simple GET request to a remote server.
 
-Please note that the example will spawn a new `EventLoopGroup` which will _create fresh threads_ which is a very costly operation. In a real-world application that uses [SwiftNIO](https://github.com/apple/swift-nio) for other parts of your application (for example a web server), please prefer `eventLoopGroupProvider: .shared(myExistingEventLoopGroup)` to share the `EventLoopGroup` used by AsyncHTTPClient with other parts of your application.
-
-If your application does not use SwiftNIO yet, it is acceptable to use `eventLoopGroupProvider: .createNew` but please make sure to share the returned `HTTPClient` instance throughout your whole application. Do not create a large number of `HTTPClient` instances with `eventLoopGroupProvider: .createNew`, this is very wasteful and might exhaust the resources of your program.
-
 ```swift
 import AsyncHTTPClient
 

Sources/AsyncHTTPClient/HTTPClient.swift

@@ -23,6 +23,8 @@ import NIOPosix
 import NIOSSL
 import NIOTLS
 import NIOTransportServices
+import NIOSingletonsPosix
+import NIOSingletonsTransportServices
 
 extension Logger {
     private func requestInfo(_ request: HTTPClient.Request) -> Logger.Metadata.Value {
@@ -44,7 +46,7 @@ let globalRequestID = ManagedAtomic(0)
 /// Example:
 ///
 /// ```swift
-///     let client = HTTPClient(eventLoopGroupProvider: .createNew)
+///     let client = HTTPClient(eventLoopGroupProvider: .globalSingleton)
 ///     client.get(url: "https://swift.org", deadline: .now() + .seconds(1)).whenComplete { result in
 ///         switch result {
 ///         case .failure(let error):
@@ -106,15 +108,15 @@ public class HTTPClient {
         switch self.eventLoopGroupProvider {
         case .shared(let group):
             self.eventLoopGroup = group
-        case .createNew:
+        case .globalSingleton:
             #if canImport(Network)
             if #available(OSX 10.14, iOS 12.0, tvOS 12.0, watchOS 6.0, *) {
-                self.eventLoopGroup = NIOTSEventLoopGroup()
+                self.eventLoopGroup = NIOSingletons.multiThreadedTransportServicesEventLoopGroup
             } else {
-                self.eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+                self.eventLoopGroup = NIOSingletons.multiThreadedPosixEventLoopGroup
             }
             #else
-            self.eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+            self.eventLoopGroup = NIOSingletons.multiThreadedPosixEventLoopGroup
             #endif
         }
         self.configuration = configuration
@@ -214,55 +216,16 @@ public class HTTPClient {
     }
 
     /// Shuts down the ``HTTPClient`` and releases its resources.
-    ///
-    /// - note: You cannot use this method if you sharted the ``HTTPClient`` with
-    ///         `init(eventLoopGroupProvider: .createNew)` because that will shut down the `EventLoopGroup` the
-    ///         returned future would run in.
     public func shutdown() -> EventLoopFuture<Void> {
-        switch self.eventLoopGroupProvider {
-        case .shared(let group):
-            let promise = group.any().makePromise(of: Void.self)
-            self.shutdown(queue: .global()) { error in
-                if let error = error {
-                    promise.fail(error)
-                } else {
-                    promise.succeed(())
-                }
-            }
-            return promise.futureResult
-        case .createNew:
-            preconditionFailure("Cannot use the shutdown() method which returns a future when owning the EventLoopGroup. Please use the one of the other shutdown methods.")
-        }
-    }
-
-    private func shutdownEventLoop(queue: DispatchQueue, _ callback: @escaping ShutdownCallback) {
-        self.stateLock.withLock {
-            switch self.eventLoopGroupProvider {
-            case .shared:
-                self.state = .shutDown
-                queue.async {
-                    callback(nil)
-                }
-            case .createNew:
-                switch self.state {
-                case .shuttingDown:
-                    self.state = .shutDown
-                    self.eventLoopGroup.shutdownGracefully(queue: queue, callback)
-                case .shutDown, .upAndRunning:
-                    assertionFailure("The only valid state at this point is \(String(describing: State.shuttingDown))")
-                }
-            }
-        }
-    }
-
-    private func shutdownFileIOThreadPool(queue: DispatchQueue, _ callback: @escaping ShutdownCallback) {
-        self.fileIOThreadPoolLock.withLock {
-            guard let fileIOThreadPool = fileIOThreadPool else {
-                callback(nil)
-                return
+        let promise = self.eventLoopGroup.any().makePromise(of: Void.self)
+        self.shutdown(queue: .global()) { error in
+            if let error = error {
+                promise.fail(error)
+            } else {
+                promise.succeed(())
             }
-            fileIOThreadPool.shutdownGracefully(queue: queue, callback)
         }
+        return promise.futureResult
     }
 
     private func shutdown(requiresCleanClose: Bool, queue: DispatchQueue, _ callback: @escaping ShutdownCallback) {
@@ -293,23 +256,20 @@ public class HTTPClient {
                     let error: Error? = (requiresClean && unclean) ? HTTPClientError.uncleanShutdown : nil
                     return (callback, error)
                 }
-                self.shutdownFileIOThreadPool(queue: queue) { ioThreadPoolError in
-                    self.shutdownEventLoop(queue: queue) { error in
-                        let reportedError = error ?? ioThreadPoolError ?? uncleanError
-                        callback(reportedError)
-                    }
+                self.stateLock.withLock {
+                    self.state = .shutDown
+                }
+                queue.async {
+                    callback(uncleanError)
                 }
             }
         }
     }
 
     private func makeOrGetFileIOThreadPool() -> NIOThreadPool {
         self.fileIOThreadPoolLock.withLock {
-            guard let fileIOThreadPool = fileIOThreadPool else {
-                let fileIOThreadPool = NIOThreadPool(numberOfThreads: System.coreCount)
-                fileIOThreadPool.start()
-                self.fileIOThreadPool = fileIOThreadPool
-                return fileIOThreadPool
+            guard let fileIOThreadPool = self.fileIOThreadPool else {
+                return NIOSingletons.posixBlockingPool
             }
             return fileIOThreadPool
         }
@@ -853,8 +813,8 @@ public class HTTPClient {
     public enum EventLoopGroupProvider {
         /// `EventLoopGroup` will be provided by the user. Owner of this group is responsible for its lifecycle.
         case shared(EventLoopGroup)
-        /// `EventLoopGroup` will be created by the client. When ``HTTPClient/syncShutdown()`` is called, the created `EventLoopGroup` will be shut down as well.
-        case createNew
+        /// An `EventLoopGroup` from `NIOSingletons`.
+        case globalSingleton
     }
 
     /// Specifies how the library will treat the event loop passed by the user.
@@ -914,6 +874,13 @@ public class HTTPClient {
     }
 }
 
+extension HTTPClient.EventLoopGroupProvider {
+    @available(*, deprecated, renamed: "globalSingleton")
+    public static var createNew: Self {
+        return .globalSingleton
+    }
+}
+
 #if swift(>=5.7)
 extension HTTPClient.Configuration: Sendable {}
 #endif

Tests/AsyncHTTPClientTests/AsyncAwaitEndToEndTests.swift

@@ -20,7 +20,7 @@ import NIOSSL
 import XCTest
 
 private func makeDefaultHTTPClient(
-    eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .createNew
+    eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .globalSingleton
 ) -> HTTPClient {
     var config = HTTPClient.Configuration()
     config.tlsConfiguration = .clientDefault
@@ -500,7 +500,7 @@ final class AsyncAwaitEndToEndTests: XCTestCase {
             let config = HTTPClient.Configuration()
                 .enableFastFailureModeForTesting()
 
-            let localClient = HTTPClient(eventLoopGroupProvider: .createNew, configuration: config)
+            let localClient = HTTPClient(eventLoopGroupProvider: .globalSingleton, configuration: config)
             defer { XCTAssertNoThrow(try localClient.syncShutdown()) }
             let request = HTTPClientRequest(url: "https://localhost:\(port)")
             await XCTAssertThrowsError(try await localClient.execute(request, deadline: .now() + .seconds(2))) { error in
@@ -566,7 +566,7 @@ final class AsyncAwaitEndToEndTests: XCTestCase {
             // this is the actual configuration under test
             config.dnsOverride = ["example.com": "localhost"]
 
-            let localClient = HTTPClient(eventLoopGroupProvider: .createNew, configuration: config)
+            let localClient = HTTPClient(eventLoopGroupProvider: .globalSingleton, configuration: config)
             defer { XCTAssertNoThrow(try localClient.syncShutdown()) }
             let request = HTTPClientRequest(url: "https://example.com:\(bin.port)/echohostheader")
             let response = await XCTAssertNoThrowWithResult(try await localClient.execute(request, deadline: .now() + .seconds(2)))

Tests/AsyncHTTPClientTests/HTTP2ClientTests.swift

@@ -25,7 +25,7 @@ import XCTest
 
 class HTTP2ClientTests: XCTestCase {
     func makeDefaultHTTPClient(
-        eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .createNew
+        eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .globalSingleton
     ) -> HTTPClient {
         var config = HTTPClient.Configuration()
         config.tlsConfiguration = .clientDefault
@@ -40,7 +40,7 @@ class HTTP2ClientTests: XCTestCase {
 
     func makeClientWithActiveHTTP2Connection<RequestHandler>(
         to bin: HTTPBin<RequestHandler>,
-        eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .createNew
+        eventLoopGroupProvider: HTTPClient.EventLoopGroupProvider = .globalSingleton
     ) -> HTTPClient {
         let client = self.makeDefaultHTTPClient(eventLoopGroupProvider: eventLoopGroupProvider)
         var response: HTTPClient.Response?
@@ -301,7 +301,7 @@ class HTTP2ClientTests: XCTestCase {
         config.httpVersion = .automatic
         config.timeout.read = .milliseconds(100)
         let client = HTTPClient(
-            eventLoopGroupProvider: .createNew,
+            eventLoopGroupProvider: .globalSingleton,
             configuration: config,
             backgroundActivityLogger: Logger(label: "HTTPClient", factory: StreamLogHandler.standardOutput(label:))
         )
@@ -322,7 +322,8 @@ class HTTP2ClientTests: XCTestCase {
         config.tlsConfiguration = tlsConfig
         config.httpVersion = .automatic
         let client = HTTPClient(
-            eventLoopGroupProvider: .createNew,
+            // TODO: Test fails if the provided ELG is a multi-threaded NIOTSEventLoopGroup (probably racy)
+            eventLoopGroupProvider: .shared(bin.group),
             configuration: config,
             backgroundActivityLogger: Logger(label: "HTTPClient", factory: StreamLogHandler.standardOutput(label:))
         )

Tests/AsyncHTTPClientTests/HTTPClientInformationalResponsesTests.swift

@@ -37,7 +37,7 @@ final class HTTPClientReproTests: XCTestCase {
             }
         }
 
-        let client = HTTPClient(eventLoopGroupProvider: .createNew)
+        let client = HTTPClient(eventLoopGroupProvider: .globalSingleton)
         defer { XCTAssertNoThrow(try client.syncShutdown()) }
 
         let httpBin = HTTPBin(.http1_1(ssl: false, compress: false)) { _ in
@@ -91,7 +91,7 @@ final class HTTPClientReproTests: XCTestCase {
             }
         }
 
-        let client = HTTPClient(eventLoopGroupProvider: .createNew)
+        let client = HTTPClient(eventLoopGroupProvider: .globalSingleton)
         defer { XCTAssertNoThrow(try client.syncShutdown()) }
 
         let httpBin = HTTPBin(.http1_1(ssl: false, compress: false)) { _ in

Tests/AsyncHTTPClientTests/HTTPClientNIOTSTests.swift

@@ -38,7 +38,7 @@ class HTTPClientNIOTSTests: XCTestCase {
     }
 
     func testCorrectEventLoopGroup() {
-        let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+        let httpClient = HTTPClient(eventLoopGroupProvider: .globalSingleton)
         defer {
             XCTAssertNoThrow(try httpClient.syncShutdown())
         }