Add optional promise parameter to RedisConnectionPool.close

Motivation:

The actual process for closing a connection pool involves closing each individual connection, which is all asynchronous.

There is currently no way to work off of the event when all of the connections have completed their close process.

Modifications:

- Add: `poolHasActiveConnections` error value to `RedisConnectionPoolError`
- Add: `promise` parameter to the `RedisConnectionPool.close` method
- Add: Documentation comments for the close method

Result:

Developers should now have a way of chaining callbacks when all connections in a pool have been closed.

Author: tanner0101

Sources/RediStack/Connection Pool/ConnectionPool.swift

@@ -145,12 +145,12 @@ internal final class ConnectionPool {
 
     /// Deactivates this connection pool. Once this is called, no further connections can be obtained
     /// from the pool. Leased connections are not deactivated and can continue to be used.
-    func close() {
+    func close(promise: EventLoopPromise<Void>? = nil) {
         if self.loop.inEventLoop {
-            self.closePool()
+            self.closePool(promise: promise)
         } else {
             self.loop.execute {
-                self.closePool()
+                self.closePool(promise: promise)
             }
         }
     }
@@ -308,12 +308,13 @@ extension ConnectionPool {
         waiter.succeed(connection)
     }
 
-    private func closePool() {
+    private func closePool(promise: EventLoopPromise<Void>?) {
         self.loop.preconditionInEventLoop()
 
         // Pool closure must be monotonic.
         guard case .active = self.state else {
             self.logger.warning("Duplicate attempt to close connection pool")
+            promise?.succeed(())
             return
         }
 
@@ -322,7 +323,7 @@ extension ConnectionPool {
         // To close the pool we need to drop all active connections.
         let connections = self.availableConnections
         self.availableConnections = []
-        connections.forEach { _ = $0.close() }
+        let closeFutures = connections.map { $0.close() }
 
         // We also cancel all pending leases.
         while let pendingLease = self.connectionWaiters.popFirst() {
@@ -331,12 +332,15 @@ extension ConnectionPool {
 
         guard self.activeConnectionCount == 0 else {
             self.logger.trace("Waiting for connections to be returned to the pool, not closing.", metadata: ["active-connections": "\(self.activeConnectionCount)"])
+            promise?.fail(RedisConnectionPoolError.poolHasActiveConnections)
             return
         }
 
         // That was all the connections, so this is now closed.
         self.logger.trace("Pool closed")
         self.state = .closed
+        EventLoopFuture<Void>.andAllSucceed(closeFutures, on: self.loop)
+            .cascade(to: promise)
     }
 
     /// This is the on-thread implementation for leasing connections out to users. Here we work out how to get a new

Sources/RediStack/Connection Pool/ConnectionPoolErrors.swift

@@ -26,6 +26,7 @@ public struct RedisConnectionPoolError: LocalizedError, Equatable {
         case poolClosed
         case timedOutWaitingForConnection
         case noAvailableConnectionTargets
+        case poolHasActiveConnections
     }
 
     /// The connection pool has already been closed, but the user has attempted to perform another operation on it.
@@ -36,4 +37,7 @@ public struct RedisConnectionPoolError: LocalizedError, Equatable {
 
     /// The pool has been configured without available connection targets, so there is nowhere to connect to.
     public static let noAvailableConnectionTargets = RedisConnectionPoolError(baseError: .noAvailableConnectionTargets)
+
+    /// Waiting for connections to be returned to the pool, not closing.
+    public static let poolHasActiveConnections = RedisConnectionPoolError(baseError: .poolHasActiveConnections)
 }

Sources/RediStack/RedisConnectionPool.swift

@@ -120,9 +120,14 @@ extension RedisConnectionPool {
         }
     }
 
-    public func close() {
+    /// Closes all connections in the pool and deactivates the pool from creating new connections.
+    ///
+    /// This method is safe to call multiple times.
+    /// - Important: If the pool has connections in active use, the close process will not complete.
+    /// - Parameter promise: A notification promise to resolve once the close process has completed.
+    public func close(promise: EventLoopPromise<Void>? = nil) {
         self.loop.execute {
-            self.pool?.close()
+            self.pool?.close(promise: promise)
 
             // This breaks the cycle between us and the pool.
             self.pool = nil