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,21 +21,8 @@ import Backtrace
 import Dispatch
 import Logging
 
-/// `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()
-
-    private var state = State.idle
-    private let stateSemaphore = DispatchSemaphore(value: 1)
-
-    private var items = [LifecycleItem]()
-    private let itemsSemaphore = DispatchSemaphore(value: 1)
-
-    /// Creates a `Lifecycle` instance.
-    public init() {
-        self.shutdownGroup.enter()
-    }
+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.
@@ -45,14 +32,13 @@ public class Lifecycle {
     public func startAndWait(configuration: Configuration = .init()) throws {
         let waitSemaphore = DispatchSemaphore(value: 0)
         var startError: Error?
-        let items = self.itemsSemaphore.lock { self.items }
-        self._start(configuration: configuration, items: items) { error in
+        self.start(configuration: configuration) { error in
             startError = error
             waitSemaphore.signal()
         }
         waitSemaphore.wait()
         try startError.map { throw $0 }
-        self.shutdownGroup.wait()
+        self.wait()
     }
 
     /// Starts the provided `LifecycleItem` array.
@@ -62,13 +48,151 @@ public class Lifecycle {
     ///    - 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(on: configuration.callbackQueue)
+           })
+            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:
+    ///    - 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 = DispatchQueue.global(), callback: @escaping (Error?) -> Void = { _ in }) {
+        self.lifecycle.shutdown(on: queue, 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: LifecycleItem {
+    public let label: String
+    internal let logger: Logger
+
+    private var state = State.idle
+    private let stateSemaphore = DispatchSemaphore(value: 1)
+
+    private var items = [LifecycleItem]()
+    private let itemsSemaphore = DispatchSemaphore(value: 1)
+
+    internal let shutdownGroup = DispatchGroup()
+
+    /// Creates a `Lifecycle` instance.
+    public init(label: String) {
+        self.label = label
+        self.logger = Logger(label: "\(Lifecycle.self) \(label)")
+        self.shutdownGroup.enter()
+    }
+
+    /// Starts the provided `LifecycleItem` array.
+    /// Startup is performed in the 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 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:
+    ///    - 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(on queue: DispatchQueue, callback: @escaping (Error?) -> Void) {
         let items = self.itemsSemaphore.lock { 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.
+    ///
+    /// - 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.
-    public func shutdown(on queue: DispatchQueue = DispatchQueue.global(), callback: @escaping ([String: Error]) -> Void = { _ in }) {
+    ///
+    /// - 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.stateSemaphore.wait()
         switch self.state {
         case .idle:
@@ -85,32 +209,28 @@ public class Lifecycle {
             self.stateSemaphore.signal()
             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.stateSemaphore.lock {
             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.stateSemaphore.wait()
             if error != nil {
                 self.state = .shuttingDown
@@ -119,23 +239,13 @@ public class Lifecycle {
             case .shuttingDown:
                 self.stateSemaphore.signal()
                 // 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.stateSemaphore.signal()
-                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)")
@@ -154,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
@@ -211,6 +321,10 @@ public class Lifecycle {
         case shuttingDown
         case shutdown
     }
+
+    public struct ShutdownError: Error {
+        let errors: [String: Error]
+    }
 }
 
 extension Lifecycle {
@@ -220,31 +334,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)
         }
     }
 }
@@ -322,7 +416,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
         }
 
@@ -331,20 +425,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)
                 }
             }
         }
@@ -356,7 +450,7 @@ public extension Lifecycle {
             }
         }
 
-        internal func run(_ callback: @escaping (Error?) -> Void) {
+        internal func run(callback: @escaping (Error?) -> Void) {
             self.body(callback)
         }
     }
@@ -369,7 +463,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:

Tests/LinuxMain.swift

@@ -26,6 +26,7 @@ import XCTest
 @testable import ServiceLauncherTests
 
 XCTMain([
-    testCase(Tests.allTests),
+    testCase(LifeycleTests.allTests),
+    testCase(TopLevelTests.allTests),
 ])
 #endif