provide programatic access to shutdown errors (#17)

motivation: in some cases users may want access to the shutdown errors

changes: add optoinal callback to shutdown providing access to shutdown errors

Author: tomerd

Sources/ServiceLauncher/Lifecycle.swift

@@ -75,24 +75,39 @@ public class Lifecycle {
 
     /// Shuts down the `LifecycleItem` array provided in `start` or `startAndWait`.
     /// Shutdown is performed in reverse order of items provided.
-    public func shutdown() {
+    public func shutdown(callback: @escaping ([String: Error]?) -> Void = { _ in }) {
+        let setupShutdownListener = { (queue: DispatchQueue) in
+            self.shutdownGroup.notify(queue: queue) {
+                guard case .shutdown(let errors) = self.state else {
+                    preconditionFailure("invalid state, \(self.state)")
+                }
+                callback(errors)
+            }
+        }
+
         self.stateLock.lock()
         switch self.state {
         case .idle:
+            self.state = .shutdown(nil)
+            self.stateLock.unlock()
+            defer { self.shutdownGroup.leave() }
+            callback(nil)
+        case .shutdown:
             self.stateLock.unlock()
-            self.shutdownGroup.leave()
-        case .starting:
-            self.state = .shuttingDown
+            self.logger.warning("already shutdown")
+            callback(nil)
+        case .starting(let queue):
+            self.state = .shuttingDown(queue)
             self.stateLock.unlock()
-        case .shuttingDown, .shutdown:
+            setupShutdownListener(queue)
+        case .shuttingDown(let queue):
             self.stateLock.unlock()
-            return
+            setupShutdownListener(queue)
         case .started(let queue, let items):
-            self.state = .shuttingDown
+            self.state = .shuttingDown(queue)
             self.stateLock.unlock()
-            self._shutdown(on: queue, items: items) {
-                self.shutdownGroup.leave()
-            }
+            setupShutdownListener(queue)
+            self._shutdown(on: queue, items: items, callback: self.shutdownGroup.leave)
         }
     }
 
@@ -114,12 +129,12 @@ public class Lifecycle {
                 self.logger.info("installing backtrace")
                 Backtrace.install()
             }
-            self.state = .starting
+            self.state = .starting(configuration.callbackQueue)
         }
         self._start(on: configuration.callbackQueue, items: items, index: 0) { started, error in
             self.stateLock.lock()
             if error != nil {
-                self.state = .shuttingDown
+                self.state = .shuttingDown(configuration.callbackQueue)
             }
             switch self.state {
             case .shuttingDown:
@@ -161,7 +176,7 @@ public class Lifecycle {
         self.logger.info("starting item [\(items[index].label)]")
         start { error in
             if let error = error {
-                self.logger.info("failed to start [\(items[index].label)]: \(error)")
+                self.logger.error("failed to start [\(items[index].label)]: \(error)")
                 return callback(index, error)
             }
             // shutdown called while starting
@@ -175,43 +190,48 @@ public class Lifecycle {
     private func _shutdown(on queue: DispatchQueue, items: [LifecycleItem], callback: @escaping () -> Void) {
         self.stateLock.withLock {
             self.logger.info("shutting down lifecycle")
-            self.state = .shuttingDown
+            self.state = .shuttingDown(queue)
         }
-        self._shutdown(on: queue, items: items.reversed(), index: 0) {
+        self._shutdown(on: queue, items: items.reversed(), index: 0, errors: nil) { errors in
             self.stateLock.withLock {
                 guard case .shuttingDown = self.state else {
                     preconditionFailure("invalid state, \(self.state)")
                 }
-                self.state = .shutdown
+                self.state = .shutdown(errors)
             }
             self.logger.info("bye")
             callback()
         }
     }
 
-    private func _shutdown(on queue: DispatchQueue, items: [LifecycleItem], index: Int, callback: @escaping () -> Void) {
+    private func _shutdown(on queue: DispatchQueue, items: [LifecycleItem], index: Int, errors: [String: Error]?, callback: @escaping ([String: Error]?) -> Void) {
         // async barrier
         let shutdown = { (callback) -> Void in queue.async { items[index].shutdown(callback: callback) } }
-        let callback = { () -> Void in queue.async { callback() } }
+        let callback = { (errors) -> Void in queue.async { callback(errors) } }
 
         if index >= items.count {
-            return callback()
+            return callback(errors)
         }
         self.logger.info("stopping item [\(items[index].label)]")
         shutdown { error in
+            var errors = errors
             if let error = error {
-                self.logger.info("failed to stop [\(items[index].label)]: \(error)")
+                if errors == nil {
+                    errors = [:]
+                }
+                errors![items[index].label] = error
+                self.logger.error("failed to stop [\(items[index].label)]: \(error)")
             }
-            self._shutdown(on: queue, items: items, index: index + 1, callback: callback)
+            self._shutdown(on: queue, items: items, index: index + 1, errors: errors, callback: callback)
         }
     }
 
     private enum State {
         case idle
-        case starting
+        case starting(DispatchQueue)
         case started(DispatchQueue, [LifecycleItem])
-        case shuttingDown
-        case shutdown
+        case shuttingDown(DispatchQueue)
+        case shutdown([String: Error]?)
     }
 }
 

Tests/ServiceLauncherTests/LifecycleTests+XCTest.swift

@@ -28,9 +28,11 @@ extension Tests {
             ("testStartThenShutdown", testStartThenShutdown),
             ("testDispatchQueues", testDispatchQueues),
             ("testShutdownWhileStarting", testShutdownWhileStarting),
+            ("testShutdownWhenIdle", testShutdownWhenIdle),
+            ("testShutdownWhenShutdown", testShutdownWhenShutdown),
             ("testShutdownDuringHangingStart", testShutdownDuringHangingStart),
-            ("testBadStartup", testBadStartup),
-            ("testBadShutdown", testBadShutdown),
+            ("testShutdownErrors", testShutdownErrors),
+            ("testStartupErrors", testStartupErrors),
             ("testStartAndWait", testStartAndWait),
             ("testBadStartAndWait", testBadStartAndWait),
             ("testShutdownInOrder", testShutdownInOrder),

Tests/ServiceLauncherTests/LifecycleTests.swift

@@ -22,9 +22,11 @@ final class Tests: XCTestCase {
         let items = (0 ... Int.random(in: 10 ... 20)).map { _ in GoodItem() }
         let lifecycle = Lifecycle()
         lifecycle.register(items)
-        lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in
-            XCTAssertNil(error, "not expecting error")
-            lifecycle.shutdown()
+        lifecycle.start(configuration: .init(shutdownSignal: nil)) { startError in
+            XCTAssertNil(startError, "not expecting error")
+            lifecycle.shutdown { shutdownErrors in
+                XCTAssertNil(shutdownErrors, "not expecting error")
+            }
         }
         lifecycle.wait()
         items.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
@@ -118,104 +120,146 @@ final class Tests: XCTestCase {
         items.suffix(started + 1).forEach { XCTAssertEqual($0.state, .idle, "expected item to be idle, but \($0.state)") }
     }
 
+    func testShutdownWhenIdle() {
+        let lifecycle = Lifecycle()
+        lifecycle.register(GoodItem())
+
+        let sempahpore1 = DispatchSemaphore(value: 0)
+        lifecycle.shutdown { errors in
+            XCTAssertNil(errors)
+            sempahpore1.signal()
+        }
+        lifecycle.wait()
+        XCTAssertEqual(.success, sempahpore1.wait(timeout: .now() + 1))
+
+        let sempahpore2 = DispatchSemaphore(value: 0)
+        lifecycle.shutdown { errors in
+            XCTAssertNil(errors)
+            sempahpore2.signal()
+        }
+        lifecycle.wait()
+        XCTAssertEqual(.success, sempahpore2.wait(timeout: .now() + 1))
+    }
+
+    func testShutdownWhenShutdown() {
+        let lifecycle = Lifecycle()
+        lifecycle.register(GoodItem())
+        let sempahpore1 = DispatchSemaphore(value: 0)
+        lifecycle.start { _ in
+            lifecycle.shutdown { errors in
+                XCTAssertNil(errors)
+                sempahpore1.signal()
+            }
+        }
+        lifecycle.wait()
+        XCTAssertEqual(.success, sempahpore1.wait(timeout: .now() + 1))
+
+        let sempahpore2 = DispatchSemaphore(value: 0)
+        lifecycle.shutdown { errors in
+            XCTAssertNil(errors)
+            sempahpore2.signal()
+        }
+        lifecycle.wait()
+        XCTAssertEqual(.success, sempahpore2.wait(timeout: .now() + 1))
+    }
+
     func testShutdownDuringHangingStart() {
         let lifecycle = Lifecycle()
-        let testQueue = DispatchQueue(label: UUID().uuidString)
-        let blockStartGroup = DispatchGroup()
-        let waitForShutdownGroup = DispatchGroup()
-        let shutdownCompleteGroup = DispatchGroup()
-        blockStartGroup.enter()
-        waitForShutdownGroup.enter()
-        shutdownCompleteGroup.enter()
+        let blockStartSemaphore = DispatchSemaphore(value: 0)
         var startCalls = [String]()
         var stopCalls = [String]()
 
         do {
             let id = UUID().uuidString
             lifecycle.register(label: id,
                                start: {
-                                   dispatchPrecondition(condition: DispatchPredicate.onQueue(testQueue))
                                    startCalls.append(id)
-                                   blockStartGroup.wait()
+                                   blockStartSemaphore.wait()
                                },
                                shutdown: {
-                                   dispatchPrecondition(condition: DispatchPredicate.onQueue(testQueue))
                                    XCTAssertTrue(startCalls.contains(id))
                                    stopCalls.append(id)
-                                   waitForShutdownGroup.leave()
-                        })
+                                })
         }
         do {
             let id = UUID().uuidString
             lifecycle.register(label: id,
                                start: {
-                                   dispatchPrecondition(condition: DispatchPredicate.onQueue(testQueue))
                                    startCalls.append(id)
                                },
                                shutdown: {
-                                   dispatchPrecondition(condition: DispatchPredicate.onQueue(testQueue))
                                    XCTAssertTrue(startCalls.contains(id))
                                    stopCalls.append(id)
-                        })
+                                })
         }
-        lifecycle.start(configuration: .init(callbackQueue: testQueue, shutdownSignal: nil)) { error in
+        lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in
             XCTAssertNil(error)
         }
         lifecycle.shutdown()
-        blockStartGroup.leave()
-        waitForShutdownGroup.wait()
+        blockStartSemaphore.signal()
         lifecycle.wait()
-        XCTAssertEqual(startCalls.count, stopCalls.count)
         XCTAssertEqual(startCalls.count, 1)
+        XCTAssertEqual(stopCalls.count, 1)
     }
 
-    func testBadStartup() {
+    func testShutdownErrors() {
         class BadItem: LifecycleItem {
-            let label: String = UUID().uuidString
+            let label = UUID().uuidString
 
             func start(callback: (Error?) -> Void) {
-                callback(TestError())
+                callback(nil)
             }
 
             func shutdown(callback: (Error?) -> Void) {
-                callback(nil)
+                callback(TestError())
             }
         }
 
-        let items: [LifecycleItem] = [GoodItem(), GoodItem(), BadItem(), GoodItem()]
+        var shutdownErrors: [String: Error]?
+        let shutdownSemaphore = DispatchSemaphore(value: 0)
+        let items: [LifecycleItem] = [GoodItem(), BadItem(), BadItem(), GoodItem(), BadItem()]
         let lifecycle = Lifecycle()
         lifecycle.register(items)
         lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in
-            XCTAssert(error is TestError, "expected error to match")
+            XCTAssertNil(error, "not expecting error")
+            lifecycle.shutdown { errors in
+                shutdownErrors = errors
+                shutdownSemaphore.signal()
+            }
         }
         lifecycle.wait()
-        let badItemIndex = items.firstIndex { $0 as? BadItem != nil }!
-        items.prefix(badItemIndex).compactMap { $0 as? GoodItem }.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
-        items.suffix(from: badItemIndex + 1).compactMap { $0 as? GoodItem }.forEach { XCTAssertEqual($0.state, .idle, "expected item to be idle, but \($0.state)") }
+        XCTAssertEqual(.success, shutdownSemaphore.wait(timeout: .now() + 1))
+
+        let goodItems = items.compactMap { $0 as? GoodItem }
+        goodItems.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
+        let badItems = items.compactMap { $0 as? BadItem }
+        XCTAssertEqual(shutdownErrors?.count, badItems.count, "expected shutdown errors")
+        badItems.forEach { XCTAssert(shutdownErrors?[$0.label] is TestError, "expected error to match") }
     }
 
-    func testBadShutdown() {
+    func testStartupErrors() {
         class BadItem: LifecycleItem {
             let label: String = UUID().uuidString
 
             func start(callback: (Error?) -> Void) {
-                callback(nil)
+                callback(TestError())
             }
 
             func shutdown(callback: (Error?) -> Void) {
-                callback(TestError())
+                callback(nil)
             }
         }
 
-        let items: [LifecycleItem] = [GoodItem(), BadItem(), GoodItem()]
+        let items: [LifecycleItem] = [GoodItem(), GoodItem(), BadItem(), GoodItem()]
         let lifecycle = Lifecycle()
         lifecycle.register(items)
         lifecycle.start(configuration: .init(shutdownSignal: nil)) { error in
-            XCTAssertNil(error, "not expecting error")
-            lifecycle.shutdown()
+            XCTAssert(error is TestError, "expected error to match")
         }
         lifecycle.wait()
-        items.compactMap { $0 as? GoodItem }.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
+        let badItemIndex = items.firstIndex { $0 as? BadItem != nil }!
+        items.prefix(badItemIndex).compactMap { $0 as? GoodItem }.forEach { XCTAssertEqual($0.state, .shutdown, "expected item to be shutdown, but \($0.state)") }
+        items.suffix(from: badItemIndex + 1).compactMap { $0 as? GoodItem }.forEach { XCTAssertEqual($0.state, .idle, "expected item to be idle, but \($0.state)") }
     }
 
     func testStartAndWait() {