diff --git a/Sources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md b/Sources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md new file mode 100644 index 0000000..df35908 --- /dev/null +++ b/Sources/ServiceLifecycle/Docs.docc/LoggingConfiguration.md @@ -0,0 +1,12 @@ +# ``ServiceLifecycle/ServiceGroupConfiguration/LoggingConfiguration`` + +## Topics + +### Creating a logging configuration + +- ``init()`` + +### Inspecting a service group configuration + +- ``keys`` +- ``Keys-swift.struct`` diff --git a/Sources/ServiceLifecycle/Docs.docc/ServiceConfiguration.md b/Sources/ServiceLifecycle/Docs.docc/ServiceConfiguration.md new file mode 100644 index 0000000..97bf40c --- /dev/null +++ b/Sources/ServiceLifecycle/Docs.docc/ServiceConfiguration.md @@ -0,0 +1,14 @@ +# ``ServiceLifecycle/ServiceGroupConfiguration/ServiceConfiguration`` + +## Topics + +### Creating a service configuration + +- ``init(service:successTerminationBehavior:failureTerminationBehavior:)`` + +### Inspecting a service configuration + +- ``service`` +- ``failureTerminationBehavior`` +- ``successTerminationBehavior`` +- ``TerminationBehavior`` diff --git a/Sources/ServiceLifecycle/Docs.docc/ServiceGroup.md b/Sources/ServiceLifecycle/Docs.docc/ServiceGroup.md new file mode 100644 index 0000000..bb2d113 --- /dev/null +++ b/Sources/ServiceLifecycle/Docs.docc/ServiceGroup.md @@ -0,0 +1,20 @@ +# ``ServiceLifecycle/ServiceGroup`` + +## Topics + +### Creating a service group + +- ``init(configuration:)`` +- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)`` +- ``init(services:configuration:logger:)`` + +### Adding to a service group + +- ``addServiceUnlessShutdown(_:)-r47h`` +- ``addServiceUnlessShutdown(_:)-9jpoj`` + +### Running a service group + +- ``run(file:line:)`` +- ``run()`` +- ``triggerGracefulShutdown()`` diff --git a/Sources/ServiceLifecycle/Docs.docc/ServiceGroupConfiguration.md b/Sources/ServiceLifecycle/Docs.docc/ServiceGroupConfiguration.md new file mode 100644 index 0000000..034dc04 --- /dev/null +++ b/Sources/ServiceLifecycle/Docs.docc/ServiceGroupConfiguration.md @@ -0,0 +1,32 @@ +# ``ServiceLifecycle/ServiceGroupConfiguration`` + +## Topics + +### Creating a service group configuration + +- ``init(services:logger:)-309oa`` +- ``init(services:logger:)-2mhze`` +- ``init(gracefulShutdownSignals:)`` + +### Creating a new service group configuration with signal handlers + +- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-9uhzu`` +- ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)-1noxs`` + +### Inspecting the service group services + +- ``services`` +- ``ServiceConfiguration`` + +### Inspecting the service group logging + +- ``logging`` +- ``LoggingConfiguration`` +- ``logger`` + +### Inspecting the service group signal handling + +- ``cancellationSignals`` +- ``maximumCancellationDuration`` +- ``gracefulShutdownSignals`` +- ``maximumGracefulShutdownDuration`` diff --git a/Sources/ServiceLifecycle/Docs.docc/index.md b/Sources/ServiceLifecycle/Docs.docc/index.md index cbd2cf8..ecd7f46 100644 --- a/Sources/ServiceLifecycle/Docs.docc/index.md +++ b/Sources/ServiceLifecycle/Docs.docc/index.md @@ -76,12 +76,17 @@ let package = Package( - ``ServiceGroup`` - ``ServiceGroupConfiguration`` +- ``ServiceGroupError`` ### Graceful Shutdown -- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)`` -- ``cancelOnGracefulShutdown(_:)`` - -### Errors +- ``gracefulShutdown()`` +- ``cancelWhenGracefulShutdown(_:)`` +- ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)`` +- ``withGracefulShutdownHandler(isolation:operation:onGracefulShutdown:)`` +- ``AsyncCancelOnGracefulShutdownSequence`` -- ``ServiceGroupError`` +- ``cancelOnGracefulShutdown(_:)`` +- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)`` +- ``withGracefulShutdownHandler(operation:onGracefulShutdown:)-1x21p`` +- ``withTaskCancellationOrGracefulShutdownHandler(operation:onCancelOrGracefulShutdown:)-81m01`` diff --git a/Sources/ServiceLifecycle/GracefulShutdown.swift b/Sources/ServiceLifecycle/GracefulShutdown.swift index 7d210ce..91c5dfb 100644 --- a/Sources/ServiceLifecycle/GracefulShutdown.swift +++ b/Sources/ServiceLifecycle/GracefulShutdown.swift @@ -58,6 +58,9 @@ public func withGracefulShutdownHandler( return try await operation() } +/// Execute an operation with a graceful shutdown handler that’s immediately invoked if the current task is shutting down gracefully. +/// +/// Use ``withGracefulShutdownHandler(isolation:operation:onGracefulShutdown:)`` instead. @available(*, deprecated, message: "Use the method with the isolation parameter instead.") @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) @_disfavoredOverload @@ -142,6 +145,11 @@ public func withTaskCancellationOrGracefulShutdownHandler( handler() } } + +/// Execute an operation with a graceful shutdown or task cancellation handler that’s immediately invoked if the current task is +/// shutting down gracefully or has been cancelled. +/// +/// Use ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)`` instead. @available(*, deprecated, message: "Use the method with the isolation parameter instead.") @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) @_disfavoredOverload @@ -156,6 +164,10 @@ public func withTaskCancellationOrGracefulShutdownHandler( } } #else +/// Execute an operation with a graceful shutdown or task cancellation handler that’s immediately invoked if the current task is +/// shutting down gracefully or has been cancelled. +/// +/// Use ``withTaskCancellationOrGracefulShutdownHandler(isolation:operation:onCancelOrGracefulShutdown:)`` instead. @available(*, deprecated, message: "Use the method with the isolation parameter instead.") @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) @_disfavoredOverload @@ -244,6 +256,7 @@ public func cancelWhenGracefulShutdown( /// Cancels the closure when a graceful shutdown was triggered. /// +/// Use ``cancelWhenGracefulShutdown(_:)`` instead. /// - Parameter operation: The actual operation. #if compiler(>=6.0) @available(*, deprecated, renamed: "cancelWhenGracefulShutdown") diff --git a/Sources/ServiceLifecycle/ServiceGroup.swift b/Sources/ServiceLifecycle/ServiceGroup.swift index 48e882d..2fa3e8b 100644 --- a/Sources/ServiceLifecycle/ServiceGroup.swift +++ b/Sources/ServiceLifecycle/ServiceGroup.swift @@ -16,7 +16,7 @@ import Logging import UnixSignals import AsyncAlgorithms -/// A ``ServiceGroup`` is responsible for running a number of services, setting up signal handling and signalling graceful shutdown to the services. +/// A service group is responsible for running a number of services, setting up signal handling and signalling graceful shutdown to the services. @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) public actor ServiceGroup: Sendable, Service { /// The internal state of the ``ServiceGroup``. @@ -47,7 +47,7 @@ public actor ServiceGroup: Sendable, Service { /// The current state of the group. private var state: State - /// Initializes a new ``ServiceGroup``. + /// Creates a service group. /// /// - Parameters: /// - configuration: The group's configuration @@ -68,7 +68,7 @@ public actor ServiceGroup: Sendable, Service { self.maximumCancellationDuration = configuration._maximumCancellationDuration } - /// Initializes a new ``ServiceGroup``. + /// Creates a service group. /// /// - Parameters: /// - services: The groups's service configurations. @@ -91,6 +91,9 @@ public actor ServiceGroup: Sendable, Service { self.init(configuration: configuration) } + /// Creates a service group. + /// + /// Use ``init(services:gracefulShutdownSignals:cancellationSignals:logger:)`` instead. @available(*, deprecated, renamed: "init(services:gracefulShutdownSignals:cancellationSignals:logger:)") public init( services: [any Service], @@ -109,7 +112,7 @@ public actor ServiceGroup: Sendable, Service { self.maximumCancellationDuration = configuration._maximumCancellationDuration } - /// Adds a new service to the group. + /// Adds a service to the group. /// /// If the group is currently running, the added service will be started immediately. /// If the group is gracefully shutting down, cancelling, or already finished, the added service will not be started. @@ -131,7 +134,7 @@ public actor ServiceGroup: Sendable, Service { } } - /// Adds a new service to the group. + /// Adds a service to the group. /// /// If the group is currently running, the added service will be started immediately. /// If the group is gracefully shutting down, cancelling, or already finished, the added service will not be started. @@ -152,8 +155,8 @@ public actor ServiceGroup: Sendable, Service { } /// Runs all the services by spinning up a child task per service. - /// Furthermore, this method sets up the correct signal handlers - /// for graceful shutdown. + /// + /// Furthermore, this method sets up the correct signal handlers for graceful shutdown. public func run(file: String = #file, line: Int = #line) async throws { switch self.state { case .initial(var services): diff --git a/Sources/ServiceLifecycle/ServiceGroupConfiguration.swift b/Sources/ServiceLifecycle/ServiceGroupConfiguration.swift index c1beef8..20fbf3c 100644 --- a/Sources/ServiceLifecycle/ServiceGroupConfiguration.swift +++ b/Sources/ServiceLifecycle/ServiceGroupConfiguration.swift @@ -17,11 +17,12 @@ import UnixSignals let deprecatedLoggerLabel = "service-lifecycle-deprecated-method-logger" -/// The configuration for the ``ServiceGroup``. +/// The configuration for the service group. @available(macOS 10.15, iOS 13.0, watchOS 6.0, tvOS 13.0, *) public struct ServiceGroupConfiguration: Sendable { /// The group's logging configuration. public struct LoggingConfiguration: Sendable { + /// The keys to use for logging public struct Keys: Sendable { /// The logging key used for logging the unix signal. public var signalKey = "sl-signal" @@ -36,19 +37,23 @@ public struct ServiceGroupConfiguration: Sendable { /// The logging key used for logging an error. public var errorKey = "sl-error" - /// Initializes a new ``ServiceGroupConfiguration/LoggingConfiguration/Keys``. + /// Creates a new set of keys. public init() {} } /// The keys used for logging. public var keys = Keys() - /// Initializes a new ``ServiceGroupConfiguration/LoggingConfiguration``. + /// Creates a new logging configuration. public init() {} } + /// A service configuration. public struct ServiceConfiguration: Sendable { - /// The behavior to follow when the service finishes its ``Service/run()`` method via returning or throwing. + + /// The behavior to follow when the service finishes running. + /// + /// This describes what the service lifecycle code does when a service's run method returns or throws. public struct TerminationBehavior: Sendable, CustomStringConvertible { internal enum _TerminationBehavior { case cancelGroup @@ -58,10 +63,14 @@ public struct ServiceGroupConfiguration: Sendable { internal let behavior: _TerminationBehavior + /// Cancel the service group. public static let cancelGroup = Self(behavior: .cancelGroup) + /// Gracefully shut down the service group. public static let gracefullyShutdownGroup = Self(behavior: .gracefullyShutdownGroup) + /// Ignore the completion of the service. public static let ignore = Self(behavior: .ignore) + /// A string representation of the behavior when a service finishes running. public var description: String { switch self.behavior { case .cancelGroup: @@ -76,17 +85,17 @@ public struct ServiceGroupConfiguration: Sendable { /// The service to which the initialized configuration applies. public var service: any Service - /// The behavior when the service returns from its ``Service/run()`` method. + /// The behavior when the service returns from its run method. public var successTerminationBehavior: TerminationBehavior - /// The behavior when the service throws from its ``Service/run()`` method. + /// The behavior when the service throws from its run method. public var failureTerminationBehavior: TerminationBehavior - /// Initializes a new ``ServiceGroupConfiguration/ServiceConfiguration``. + /// Initializes a new service configuration. /// /// - Parameters: /// - service: The service to which the initialized configuration applies. - /// - successTerminationBehavior: The behavior when the service returns from its ``Service/run()`` method. - /// - failureTerminationBehavior: The behavior when the service throws from its ``Service/run()`` method. + /// - successTerminationBehavior: The behavior when the service returns from its run method. + /// - failureTerminationBehavior: The behavior when the service throws from its run method. public init( service: any Service, successTerminationBehavior: TerminationBehavior = .cancelGroup, @@ -166,7 +175,7 @@ public struct ServiceGroupConfiguration: Sendable { internal var _maximumCancellationDuration: (secondsComponent: Int64, attosecondsComponent: Int64)? - /// Initializes a new ``ServiceGroupConfiguration``. + /// Creates a new service group configuration from the service configurations you provide. /// /// - Parameters: /// - services: The groups's service configurations. @@ -179,7 +188,7 @@ public struct ServiceGroupConfiguration: Sendable { self.logger = logger } - /// Initializes a new ``ServiceGroupConfiguration``. + /// Creates a new service group configuration from service configurations you provide with cancellation and shutdown signals. /// /// - Parameters: /// - services: The groups's service configurations. @@ -198,7 +207,7 @@ public struct ServiceGroupConfiguration: Sendable { self.cancellationSignals = cancellationSignals } - /// Initializes a new ``ServiceGroupConfiguration``. + /// Creates a new service group configuration from services you provide. /// /// - Parameters: /// - services: The groups's services. @@ -211,7 +220,7 @@ public struct ServiceGroupConfiguration: Sendable { self.logger = logger } - /// Initializes a new ``ServiceGroupConfiguration``. + /// Creates a new service group configuration from services you provide with cancellation and shutdown signals.. /// /// - Parameters: /// - services: The groups's services. @@ -230,6 +239,7 @@ public struct ServiceGroupConfiguration: Sendable { self.cancellationSignals = cancellationSignals } + /// Initializes a new service group configuration. @available(*, deprecated) public init(gracefulShutdownSignals: [UnixSignal]) { self.services = []