expose the underlying lifecycle for composition reasons (#70)

motivation: application frameworks thae use ServiceLifecycle may need to expose their underlying  lifecycle so they can be also composed into larger systems

changes:
* expose ServiceLifecycle::underlying
* make sure backtrace installer is only called once per process
* add swift-atomics dependency (>=5.2 and above)
* add atomic helper (<5.2)

Author: tomerd

Package.swift

@@ -14,9 +14,24 @@ let package = Package(
         .package(url: "https://github.com/swift-server/swift-backtrace.git", from: "1.1.1"),
         .package(url: "https://github.com/apple/swift-nio.git", from: "2.0.0"), // used in tests
     ],
-    targets: [
-        .target(name: "Lifecycle", dependencies: ["Logging", "Metrics", "Backtrace"]),
-        .target(name: "LifecycleNIOCompat", dependencies: ["Lifecycle", "NIO"]),
-        .testTarget(name: "LifecycleTests", dependencies: ["Lifecycle", "LifecycleNIOCompat"]),
-    ]
+    targets: []
 )
+
+#if compiler(>=5.2)
+package.dependencies += [
+    .package(url: "https://github.com/apple/swift-atomics.git", .exact("0.0.3")), // exact since < 1.0
+]
+package.targets += [
+    .target(name: "Lifecycle", dependencies: ["Logging", "Metrics", "Backtrace", "Atomics"]),
+]
+#else
+package.targets += [
+    .target(name: "CLifecycleHelpers", dependencies: []),
+    .target(name: "Lifecycle", dependencies: ["CLifecycleHelpers", "Logging", "Metrics", "Backtrace"]),
+]
+#endif
+
+package.targets += [
+    .target(name: "LifecycleNIOCompat", dependencies: ["Lifecycle", "NIO"]),
+    .testTarget(name: "LifecycleTests", dependencies: ["Lifecycle", "LifecycleNIOCompat"]),
+]

Sources/CLifecycleHelpers/CLifecycleAtomics.c

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftServiceLifecycle open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftServiceLifecycle project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftServiceLifecycle project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#include <CLifecycleAtomics.h>
+
+#include <stdlib.h>
+#include <stdatomic.h>
+
+struct c_lifecycle_atomic_bool *c_lifecycle_atomic_bool_create(bool value) {
+    struct c_lifecycle_atomic_bool *wrapper = malloc(sizeof(*wrapper));
+    atomic_init(&wrapper->value, value);
+    return wrapper;
+}
+
+bool c_lifecycle_atomic_bool_compare_and_exchange(struct c_lifecycle_atomic_bool *wrapper, bool expected, bool desired) {
+    bool expected_copy = expected;
+    return atomic_compare_exchange_strong(&wrapper->value, &expected_copy, desired);
+}

Sources/CLifecycleHelpers/include/CLifecycleAtomics.h

@@ -0,0 +1,23 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftServiceLifecycle open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftServiceLifecycle project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftServiceLifecycle project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#include <stdbool.h>
+#include <stdint.h>
+
+struct c_lifecycle_atomic_bool {
+    _Atomic bool value;
+};
+struct c_lifecycle_atomic_bool * _Nonnull c_lifecycle_atomic_bool_create(bool value);
+
+bool c_lifecycle_atomic_bool_compare_and_exchange(struct c_lifecycle_atomic_bool * _Nonnull atomic, bool expected, bool desired);

Sources/Lifecycle/Atomics.swift

@@ -0,0 +1,49 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftServiceLifecycle open source project
+//
+// Copyright (c) 2021 Apple Inc. and the SwiftServiceLifecycle project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftServiceLifecycle project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(Atomics)
+import Atomics
+#else
+import CLifecycleHelpers
+#endif
+
+internal class AtomicBoolean {
+    #if canImport(Atomics)
+    private let managed: ManagedAtomic<Bool>
+    #else
+    private let unmanaged: UnsafeMutablePointer<c_lifecycle_atomic_bool>
+    #endif
+
+    init(_ value: Bool) {
+        #if canImport(Atomics)
+        self.managed = .init(value)
+        #else
+        self.unmanaged = c_lifecycle_atomic_bool_create(value)
+        #endif
+    }
+
+    deinit {
+        #if !canImport(Atomics)
+        self.unmanaged.deinitialize(count: 1)
+        #endif
+    }
+
+    func compareAndSwap(expected: Bool, desired: Bool) -> Bool {
+        #if canImport(Atomics)
+        return self.managed.compareExchange(expected: expected, desired: desired, ordering: .acquiring).exchanged
+        #else
+        return c_lifecycle_atomic_bool_compare_and_exchange(self.unmanaged, expected, desired)
+        #endif
+    }
+}

Sources/Lifecycle/Lifecycle.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the SwiftServiceLifecycle open source project
 //
-// Copyright (c) 2019-2020 Apple Inc. and the SwiftServiceLifecycle project authors
+// Copyright (c) 2019-2021 Apple Inc. and the SwiftServiceLifecycle project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -20,6 +20,7 @@ import Glibc
 import Backtrace
 import Dispatch
 import Logging
+import Metrics
 
 // MARK: - LifecycleTask
 
@@ -99,13 +100,15 @@ public struct LifecycleHandler {
 /// `ServiceLifecycle` provides a basic mechanism to cleanly startup and shutdown the application, freeing resources in order before exiting.
 ///  By default, also install shutdown hooks based on `Signal` and backtraces.
 public struct ServiceLifecycle {
+    private static let backtracesInstalled = AtomicBoolean(false)
+
     private let configuration: Configuration
 
     /// The underlying `ComponentLifecycle` instance
     ///
     /// Designed for composition purposes, mainly for frameworks that need to offer both top-level start/stop functionality and composition into larger systems.
     /// In other words, should not be used outside the context of building an Application framework.
-    private let underlying: ComponentLifecycle
+    public let underlying: ComponentLifecycle
 
     /// Creates a `ServiceLifecycle` instance.
     ///
@@ -114,11 +117,8 @@ public struct ServiceLifecycle {
     public init(configuration: Configuration = .init()) {
         self.configuration = configuration
         self.underlying = ComponentLifecycle(label: self.configuration.label, logger: self.configuration.logger)
-        // setup backtrace trap as soon as possible
-        if configuration.installBacktrace {
-            self.log("installing backtrace")
-            Backtrace.install()
-        }
+        // setup backtraces as soon as possible, so if we crash during setup we get a backtrace
+        self.installBacktrace()
     }
 
     /// Starts the provided `LifecycleTask` array.
@@ -127,13 +127,19 @@ public struct ServiceLifecycle {
     /// - 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) {
+        guard self.underlying.idle else {
+            preconditionFailure("already started")
+        }
         self.setupShutdownHook()
         self.underlying.start(on: self.configuration.callbackQueue, callback)
     }
 
     /// Starts the provided `LifecycleTask` array and waits (blocking) until a shutdown `Signal` is captured or `shutdown` is called on another thread.
     /// Startup is performed in the order of items provided.
     public func startAndWait() throws {
+        guard self.underlying.idle else {
+            preconditionFailure("already started")
+        }
         self.setupShutdownHook()
         try self.underlying.startAndWait(on: self.configuration.callbackQueue)
     }
@@ -152,6 +158,13 @@ public struct ServiceLifecycle {
         self.underlying.wait()
     }
 
+    private func installBacktrace() {
+        if self.configuration.installBacktrace, ServiceLifecycle.backtracesInstalled.compareAndSwap(expected: false, desired: true) {
+            self.log("installing backtrace")
+            Backtrace.install()
+        }
+    }
+
     private func setupShutdownHook() {
         self.configuration.shutdownSignal?.forEach { signal in
             self.log("setting up shutdown hook on \(signal)")
@@ -364,6 +377,16 @@ public class ComponentLifecycle: LifecycleTask {
         self.shutdownGroup.wait()
     }
 
+    // MARK: - internal
+
+    internal var idle: Bool {
+        if case .idle = self.state {
+            return true
+        } else {
+            return false
+        }
+    }
+
     // MARK: - private
 
     private func _start(on queue: DispatchQueue, tasks: [LifecycleTask], callback: @escaping (Error?) -> Void) {

Tests/LifecycleTests/ServiceLifecycleTests+XCTest.swift

@@ -33,6 +33,7 @@ extension ServiceLifecycleTests {
             ("testNesting", testNesting),
             ("testNesting2", testNesting2),
             ("testSignalDescription", testSignalDescription),
+            ("testBacktracesInstalledOnce", testBacktracesInstalledOnce),
         ]
     }
 }

Tests/LifecycleTests/ServiceLifecycleTests.swift

@@ -14,6 +14,7 @@
 
 @testable import Lifecycle
 import LifecycleNIOCompat
+import Logging
 import XCTest
 
 final class ServiceLifecycleTests: XCTestCase {
@@ -226,4 +227,10 @@ final class ServiceLifecycleTests: XCTestCase {
         XCTAssertEqual("\(ServiceLifecycle.Signal.INT)", "Signal(INT, rawValue: \(ServiceLifecycle.Signal.INT.rawValue))")
         XCTAssertEqual("\(ServiceLifecycle.Signal.ALRM)", "Signal(ALRM, rawValue: \(ServiceLifecycle.Signal.ALRM.rawValue))")
     }
+
+    func testBacktracesInstalledOnce() {
+        let config = ServiceLifecycle.Configuration(installBacktrace: true)
+        _ = ServiceLifecycle(configuration: config)
+        _ = ServiceLifecycle(configuration: config)
+    }
 }

docker/docker-compose.1804.50.yaml

@@ -13,6 +13,6 @@ services:
     image: swift-service-lifecycle:18.04-5.0
     environment:
       - SKIP_SIGNAL_TEST=true
-  
+
   shell:
     image: swift-service-lifecycle:18.04-5.0

scripts/soundness.sh

@@ -19,7 +19,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed -e 's/2017-2018/YEARS/' -e 's/2019-2020/YEARS/' -e 's/2019/YEARS/' -e 's/2020/YEARS/'
+    sed -e 's/2017-2018/YEARS/' -e 's/2019-2020/YEARS/' -e 's/2019-2021/YEARS/' -e 's/2019/YEARS/' -e 's/2020/YEARS/' -e 's/2021/YEARS/'
 }
 
 printf "=> Checking for unacceptable language... "