nested lifecycles

motivation: add ability to create a hirearchy of lifecycles to help manage more complex systems

changes:
* define top-level lifcycle where signal handling and backtraces are handled
* conform Lifecycle to LifecycleItem so that lifecycles can be nested
* change shutdown to return an error to better conform with LifecycleItem api

Author: tomerd

Sources/ServiceLauncher/Lifecycle.swift

@@ -21,61 +21,178 @@ import Backtrace
 import Dispatch
 import Logging
 
+public struct TopLevelLifecycle {
+    private let lifecycle = Lifecycle(label: "\(TopLevelLifecycle.self)")
+
+    /// Starts the provided `LifecycleItem` array and waits (blocking) until a shutdown `Signal` is captured or `Lifecycle.shutdown` is called on another thread.
+    /// Startup is performed in the order of items provided.
+    ///
+    /// - parameters:
+    ///    - configuration: Defines lifecycle `Configuration`
+    public func startAndWait(configuration: Configuration = .init()) throws {
+        let waitSemaphore = DispatchSemaphore(value: 0)
+        var startError: Error?
+
+        self.start(configuration: configuration) { error in
+            startError = error
+            waitSemaphore.signal()
+        }
+        waitSemaphore.wait()
+        try startError.map { throw $0 }
+        self.wait()
+    }
+
+    /// Starts the provided `LifecycleItem` array.
+    /// Startup is performed in the order of items provided.
+    ///
+    /// - parameters:
+    ///    - configuration: Defines lifecycle `Configuration`
+    ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
+    public func start(configuration: Configuration = .init(), callback: @escaping (Error?) -> Void) {
+        if configuration.installBacktrace {
+            self.lifecycle.logger.info("installing backtrace")
+            Backtrace.install()
+        }
+        configuration.shutdownSignal?.forEach { signal in
+            self.lifecycle.logger.info("setting up shutdown hook on \(signal)")
+            let signalSource = TopLevelLifecycle.trap(signal: signal, handler: { signal in
+                self.lifecycle.logger.info("intercepted signal: \(signal)")
+                self.shutdown()
+           })
+            self.lifecycle.shutdownGroup.notify(queue: DispatchQueue.global()) {
+                signalSource.cancel()
+            }
+        }
+        self.lifecycle.start(on: configuration.callbackQueue) { error in
+            callback(error)
+        }
+    }
+
+    /// Shuts down the `LifecycleItem` array provided in `start` or `startAndWait`.
+    /// Shutdown is performed in reverse order of items provided./
+    ///
+    /// - parameters:
+    ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
+    public func shutdown(callback: @escaping (Error?) -> Void = { _ in }) {
+        self.lifecycle.shutdown(callback: callback)
+    }
+
+    /// Waits (blocking) until shutdown signal is captured or `Lifecycle.shutdown` is invoked on another thread.
+    public func wait() {
+        self.lifecycle.wait()
+    }
+
+    /// Adds a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - items: one or more `LifecycleItem`.
+    func register(_ items: [LifecycleItem]) {
+        self.lifecycle.register(items)
+    }
+
+    /// Adds a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - items: one or more `LifecycleItem`.
+    internal func register(_ items: LifecycleItem...) {
+        self.lifecycle.register(items)
+    }
+
+    /// Add a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - label: label of the item, useful for debugging.
+    ///    - start: closure to perform the startup.
+    ///    - shutdown: closure to perform the shutdown.
+    func register(label: String, start: Lifecycle.Handler, shutdown: Lifecycle.Handler) {
+        self.lifecycle.register(label: label, start: start, shutdown: shutdown)
+    }
+
+    /// Adds a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - label: label of the item, useful for debugging.
+    ///    - shutdown: closure to perform the shutdown.
+    func registerShutdown(label: String, _ handler: Lifecycle.Handler) {
+        self.lifecycle.registerShutdown(label: label, handler)
+    }
+
+    /// Adds a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - label: label of the item, useful for debugging.
+    ///    - start: closure to perform the shutdown.
+    ///    - shutdown: closure to perform the shutdown.
+    func register(label: String, start: @escaping () throws -> Void, shutdown: @escaping () throws -> Void) {
+        self.lifecycle.register(label: label, start: start, shutdown: shutdown)
+    }
+
+    /// Adds a `LifecycleItem` to a `LifecycleItems` collection.
+    ///
+    /// - parameters:
+    ///    - label: label of the item, useful for debugging.
+    ///    - shutdown: closure to perform the shutdown.
+    func registerShutdown(label: String, _ handler: @escaping () throws -> Void) {
+        self.lifecycle.registerShutdown(label: label, handler)
+    }
+}
+
 /// `Lifecycle` provides a basic mechanism to cleanly startup and shutdown the application, freeing resources in order before exiting.
-public class Lifecycle {
-    private let logger = Logger(label: "\(Lifecycle.self)")
-    private let shutdownGroup = DispatchGroup()
+public class Lifecycle: LifecycleItem {
+    public let label: String
+    internal let logger: Logger
 
     private var state = State.idle
     private let stateLock = Lock()
 
     private var items = [LifecycleItem]()
     private let itemsLock = Lock()
 
+    internal let shutdownGroup = DispatchGroup()
+
     /// Creates a `Lifecycle` instance.
-    public init() {
+    public init(label: String) {
+        self.label = label
+        self.logger = Logger(label: "\(Lifecycle.self) \(label)")
         self.shutdownGroup.enter()
     }
 
-    /// Starts the provided `LifecycleItem` array and waits (blocking) until a shutdown `Signal` is captured or `Lifecycle.shutdown` is called on another thread.
+    /// Starts the provided `LifecycleItem` array.
     /// Startup is performed in the order of items provided.
     ///
     /// - parameters:
-    ///    - configuration: Defines lifecycle `Configuration`
-    public func startAndWait(configuration: Configuration = .init()) throws {
-        let waitLock = Lock()
-        let group = DispatchGroup()
-        var startError: Error?
-        let items = self.itemsLock.withLock { self.items }
-        group.enter()
-        self._start(configuration: configuration, items: items) { error in
-            waitLock.withLock {
-                startError = error
-            }
-            group.leave()
-        }
-        self.shutdownGroup.wait()
-        try waitLock.withLock {
-            startError
-        }.map { error in
-            throw error
-        }
+    ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
+    public func start(callback: @escaping (Error?) -> Void) {
+        self.start(on: DispatchQueue.global(), callback: callback)
     }
 
     /// Starts the provided `LifecycleItem` array.
     /// Startup is performed in the order of items provided.
     ///
     /// - parameters:
-    ///    - configuration: Defines lifecycle `Configuration`
+    ///    - on: `DispatchQueue` to run the handler on
     ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
-    public func start(configuration: Configuration = .init(), callback: @escaping (Error?) -> Void) {
+    public func start(on queue: DispatchQueue, callback: @escaping (Error?) -> Void) {
         let items = self.itemsLock.withLock { self.items }
-        self._start(configuration: configuration, items: items, callback: callback)
+        self._start(on: queue, items: items, callback: callback)
     }
 
     /// Shuts down the `LifecycleItem` array provided in `start` or `startAndWait`.
     /// Shutdown is performed in reverse order of items provided.
-    public func shutdown(on queue: DispatchQueue = DispatchQueue.global(), callback: @escaping ([String: Error]) -> Void = { _ in }) {
+    ///
+    /// - parameters:
+    ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
+    public func shutdown(callback: @escaping (Error?) -> Void = { _ in }) {
+        self.shutdown(on: DispatchQueue.global(), callback: callback)
+    }
+
+    /// Shuts down the `LifecycleItem` array provided in `start` or `startAndWait`.
+    /// Shutdown is performed in reverse order of items provided.
+    ///
+    /// - parameters:
+    ///    - on: `DispatchQueue` to run the handler on
+    ///    - callback: The handler which is called after the start operation completes. The parameter will be `nil` on success and contain the `Error` otherwise.
+    public func shutdown(on queue: DispatchQueue, callback: @escaping (Error?) -> Void = { _ in }) {
         self.stateLock.lock()
         switch self.state {
         case .idle:
@@ -92,32 +209,28 @@ public class Lifecycle {
             self.stateLock.unlock()
             self._shutdown(on: queue, items: items) { errors in
                 defer { self.shutdownGroup.leave() }
-                callback(errors)
+                callback(errors.count > 0 ? ShutdownError(errors: errors) : nil)
             }
         }
     }
 
-    /// Waits (blocking) until shutdown signal is captured or `Lifecycle.shutdown` is invoked on another thread.
     public func wait() {
         self.shutdownGroup.wait()
     }
 
     // MARK: - private
 
-    private func _start(configuration: Configuration, items: [LifecycleItem], callback: @escaping (Error?) -> Void) {
+    private func _start(on queue: DispatchQueue = DispatchQueue.global(), items: [LifecycleItem], callback: @escaping (Error?) -> Void) {
         self.stateLock.withLock {
             guard case .idle = self.state else {
                 preconditionFailure("invalid state, \(self.state)")
             }
             precondition(items.count > 0, "invalid number of items, must be > 0")
             self.logger.info("starting lifecycle")
-            if configuration.installBacktrace {
-                self.logger.info("installing backtrace")
-                Backtrace.install()
-            }
+
             self.state = .starting
         }
-        self._start(on: configuration.callbackQueue, items: items, index: 0) { _, error in
+        self._start(on: queue, items: items, index: 0) { _, error in
             self.stateLock.lock()
             if error != nil {
                 self.state = .shuttingDown
@@ -126,23 +239,13 @@ public class Lifecycle {
             case .shuttingDown:
                 self.stateLock.unlock()
                 // shutdown was called while starting, or start failed, shutdown what we can
-                self._shutdown(on: configuration.callbackQueue, items: items) { _ in
+                self._shutdown(on: queue, items: items) { _ in
                     callback(error)
                     self.shutdownGroup.leave()
                 }
             case .starting:
                 self.state = .started(items)
                 self.stateLock.unlock()
-                configuration.shutdownSignal?.forEach { signal in
-                    self.logger.info("setting up shutdown hook on \(signal)")
-                    let signalSource = Lifecycle.trap(signal: signal, handler: { signal in
-                        self.logger.info("intercepted signal: \(signal)")
-                        self.shutdown(on: configuration.callbackQueue)
-                    })
-                    self.shutdownGroup.notify(queue: DispatchQueue.global()) {
-                        signalSource.cancel()
-                    }
-                }
                 return callback(nil)
             default:
                 preconditionFailure("invalid state, \(self.state)")
@@ -161,7 +264,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
@@ -215,6 +318,10 @@ public class Lifecycle {
         case shuttingDown
         case shutdown
     }
+
+    public struct ShutdownError: Error {
+        let errors: [String: Error]
+    }
 }
 
 extension Lifecycle {
@@ -224,31 +331,11 @@ extension Lifecycle {
         let shutdown: Handler
 
         func start(callback: @escaping (Error?) -> Void) {
-            self.start.run(callback)
+            self.start.run(callback: callback)
         }
 
         func shutdown(callback: @escaping (Error?) -> Void) {
-            self.shutdown.run(callback)
-        }
-    }
-}
-
-extension Lifecycle {
-    /// `Lifecycle` configuration options.
-    public struct Configuration {
-        /// Defines the `DispatchQueue` on which startup and shutdown handlers are executed.
-        public let callbackQueue: DispatchQueue
-        /// Defines if to install a crash signal trap that prints backtraces.
-        public let shutdownSignal: [Signal]?
-        /// Defines what, if any, signals to trap for invoking shutdown.
-        public let installBacktrace: Bool
-
-        public init(callbackQueue: DispatchQueue = DispatchQueue.global(),
-                    shutdownSignal: [Signal]? = [.TERM, .INT],
-                    installBacktrace: Bool = true) {
-            self.callbackQueue = callbackQueue
-            self.shutdownSignal = shutdownSignal
-            self.installBacktrace = installBacktrace
+            self.shutdown.run(callback: callback)
         }
     }
 }
@@ -326,7 +413,7 @@ public extension Lifecycle {
         ///
         /// - parameters:
         ///    - callback: the underlying completion handler
-        public init(_ callback: @escaping (@escaping (Error?) -> Void) -> Void) {
+        public init(callback: @escaping (@escaping (Error?) -> Void) -> Void) {
             self.body = callback
         }
 
@@ -335,20 +422,20 @@ public extension Lifecycle {
         /// - parameters:
         ///    - callback: the underlying completion handler
         public static func async(_ callback: @escaping (@escaping (Error?) -> Void) -> Void) -> Handler {
-            return Handler(callback)
+            return Handler(callback: callback)
         }
 
         /// Asynchronous `Lifecycle.Handler` based on a blocking, throwing function.
         ///
         /// - parameters:
         ///    - body: the underlying function
         public static func sync(_ body: @escaping () throws -> Void) -> Handler {
-            return Handler { completionHandler in
+            return Handler { callback in
                 do {
                     try body()
-                    completionHandler(nil)
+                    callback(nil)
                 } catch {
-                    completionHandler(error)
+                    callback(error)
                 }
             }
         }
@@ -360,7 +447,7 @@ public extension Lifecycle {
             }
         }
 
-        internal func run(_ callback: @escaping (Error?) -> Void) {
+        internal func run(callback: @escaping (Error?) -> Void) {
             self.body(callback)
         }
     }
@@ -373,7 +460,27 @@ public protocol LifecycleItem {
     func shutdown(callback: @escaping (Error?) -> Void)
 }
 
-extension Lifecycle {
+extension TopLevelLifecycle {
+    /// `Lifecycle` configuration options.
+    public struct Configuration {
+        /// Defines the `DispatchQueue` on which startup and shutdown handlers are executed.
+        public let callbackQueue: DispatchQueue
+        /// Defines if to install a crash signal trap that prints backtraces.
+        public let shutdownSignal: [Signal]?
+        /// Defines what, if any, signals to trap for invoking shutdown.
+        public let installBacktrace: Bool
+
+        public init(callbackQueue: DispatchQueue = DispatchQueue.global(),
+                    shutdownSignal: [Signal]? = [.TERM, .INT],
+                    installBacktrace: Bool = true) {
+            self.callbackQueue = callbackQueue
+            self.shutdownSignal = shutdownSignal
+            self.installBacktrace = installBacktrace
+        }
+    }
+}
+
+extension TopLevelLifecycle {
     /// Setup a signal trap.
     ///
     /// - parameters: