Files
swift-service-lifecycle/Sources/UnixSignals/UnixSignal.swift
T
Franz Busch fafab8f7ad Overhaul service lifecycle for Structured Concurrency (#130)
* Overhaul service lifecycle for Structured Concurrency

# Motivation
Since the release of Swift Concurrency the server ecosystem has adopted `async`/`await` in a lot of APIs making the user experience amazing. Another thing that Swift Concurrency introduced is Structured Concurrency which allows to create a task tree that with parent to child relations. Structured Concurrency has many benefits such as automatic cancellation and task local propagation.
The current state of this library predates the introduction of Swift Concurrency and is not inline anymore with how applications are structured that want to leverage Concurrency.

# Modification
This PR overhauls the implementation of service lifecycle completely. The reason for this is that the current implementation is very focused on how NIO based applications work before the introduction of Concurrency. Furthermore, Structured Concurrency is actually replacing part of the current functionality by providing new scoping mechanisms.
The overhauled implementation provides two primitive types. Anew `Service` protocol and a `ServiceRunner`. The former is providing a clear API which services have to conform to so that they can be run by the `ServiceRunner`.

An example usage of the types looks like this

```swift
actor FooService: Service {
    func run() async throws {}

    func shutdownGracefully() async throws {}
}
actor BarService: Service {
    func run() async throws {}

    func shutdownGracefully() async throws {}
}

let fooService = FooService()
let barService = BarService()

let runner = ServiceRunner(
    services: [fooService, barService],
   configuration: .init(),
   logger: logger
)

try await runner.run()
```

# Result
We now have a service lifecycle library that integrates nicely with Structured Concurrency. Its value add is that it solves to complex setup of the task group with the signal handling. Furthermore, it provides a currency type `Service` that can be passed to inject services.

* Remove `shutdownGracefully` method and switch to a handler based approach.

* Code review from George

* Add extensions to `TaskGroup` and `ThrowingTaskGroup`

* Remove long running property

* Documentation

* Fix tests

* Ensure ordering of shutdown

* Test

# Motivation

# Modification

# Result

* Introduce ServiceLifecycleTestKit

* Add AsyncCancelOngracefulShutdownSequence

* Tests and docs for graceful shutdown

# Motivation

# Modification

# Result

* Remove unsafe flags

* Add article for application authors

* Add correct licence and notice information for the things we copied from swift-nio

* Code review

* Remove @_unsafeInheritExectuor

* Code review

* Change log levels, rename to withGracefulShutdownHandler and support nested service runner graceful shutdown

* Add public `shutdownGracefully` method to the service runner

* Code review and expose new cancelOnGracefulShutdown method

* Extend graceful shutdown APIs and tolerate running outside of a `ServiceRunner`

* Rename to `ServiceGroup`

* Enable Swift 5.6 support

* Update soundess dockerfile

* Update Readme

* Make 5.6 build work
2023-04-27 11:56:08 +01:00

99 lines
2.6 KiB
Swift

//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftServiceLifecycle open source project
//
// Copyright (c) 2023 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(Darwin)
import Darwin
#elseif canImport(Glibc)
import Glibc
#endif
import Dispatch
/// A struct representing a Unix signal.
///
/// Signals are standardized messages sent to a running program to trigger specific behavior, such as quitting or error handling
public struct UnixSignal: Hashable, Sendable, CustomStringConvertible {
internal enum Wrapped {
case sighup
case sigint
case sigterm
case sigusr1
case sigusr2
case sigalrm
}
private let wrapped: Wrapped
private init(_ wrapped: Wrapped) {
self.wrapped = wrapped
}
public var rawValue: Int32 {
return self.wrapped.rawValue
}
public var description: String {
return String(describing: self.wrapped)
}
/// Hang up detected on controlling terminal or death of controlling process.
public static let sighup = Self(.sighup)
/// Issued if the user sends an interrupt signal.
public static let sigint = Self(.sigint)
/// Software termination signal.
public static let sigterm = Self(.sigterm)
public static let sigusr1 = Self(.sigusr1)
public static let sigusr2 = Self(.sigusr2)
public static let sigalrm = Self(.sigalrm)
}
extension UnixSignal.Wrapped: Hashable {}
extension UnixSignal.Wrapped: Sendable {}
extension UnixSignal.Wrapped: CustomStringConvertible {
var description: String {
switch self {
case .sighup:
return "SIGHUP"
case .sigint:
return "SIGINT"
case .sigterm:
return "SIGTERM"
case .sigusr1:
return "SIGUSR1"
case .sigusr2:
return "SIGUSR2"
case .sigalrm:
return "SIGALRM"
}
}
}
extension UnixSignal.Wrapped {
var rawValue: Int32 {
switch self {
case .sighup:
return SIGHUP
case .sigint:
return SIGINT
case .sigterm:
return SIGTERM
case .sigusr1:
return SIGUSR1
case .sigusr2:
return SIGUSR2
case .sigalrm:
return SIGALRM
}
}
}