# Signals Generic Cross Platform Signal Handler. ## Prerequisites ### Swift * Swift Open Source `swift-5.1-RELEASE` toolchain (**Minimum REQUIRED for latest release**) * Swift Open Source `swift-5.4-RELEASE` toolchain (**Recommended**) * Swift toolchain included in *Xcode Version 11.0 or higher*. BlueSignals version 2.0 and above supports Swift 5.1+. See older versions of BlueSSLService for older versions of Swift. ### macOS * macOS 10.14.6 (*Mojave*) or higher. * Xcode Version 11.0 or higher using one of the above toolchains. * Xcode Version 12.5 or higher using the included toolchain (*Recommended*). ### iOS * iOS 10.0 or higher * Xcode Version 11.0 or higher using one of the above toolchains. * Xcode Version 12.5 or higher using the included toolchain (*Recommended*). ### Linux * Ubuntu 16.04 (or 16.10 but only tested on 16.04) and 18.04. * One of the Swift Open Source toolchain listed above. ## Build To build Signals from the command line: ``` % cd % swift build ``` ## Using Signals ### Including in your project #### Swift Package Manager To include BlueSignals into a Swift Package Manager package, add it to the `dependencies` attribute defined in your `Package.swift` file. You can select the version using the `majorVersion` and `minor` parameters. For example: ``` dependencies: [ .Package(url: "https://github.com/Kitura/BlueSignals.git", majorVersion: , minor: ) ] ``` #### Carthage To include BlueSignals in a project using Carthage, add a line to your `Cartfile` with the GitHub organization and project names and version. For example: ``` github "Kitura/BlueSignals" ~> . ``` #### CocoaPods To include BlueSignals in a project using CocoaPods, you just add `BlueSignals` to your `Podfile`, for example: ``` platform :ios, '10.0' target 'MyApp' do use_frameworks! pod 'BlueSignals' end ``` ### Before starting The first thing you need to do is import the Signals framework. This is done by the following: ``` import Signals ``` ### Provided APIs Signals provides four (4) class level APIs. Three (3) are used for trapping and handling operating system signals. The other function allows for the raising of a signal. #### Watching a signal ``SignalWatch`` provides an interface that allows a trapped signal to notify multiple "signal watchers". In this way, signal traps can be shared across libraries in the same application. In most cases this can be used as a direct replacement for `trap()`. When a signal is added via ``SignalWatch``, it will install it's own handler on that signal via `trap()`. As such, it is important to not use `trap()` directly when using ``SignalWatch``. If all watchers of a signal are removed, ``SignalWatch`` will intelligently restore the handler that was installed before ``SignalWatch``. ```swift import Signals ... let server: SomeServer = ... SignalWatch.shared.on(signal: .int) { _ in server.shutdownServer() } server.run() ``` #### Trapping a signal - `trap(signal signal: Signal, action: SigActionHandler)` - This basic API allows you to set and specific handler for a specific signal. The example below shows how to add a trap handler to a server in order to perform and orderly shutdown in the event that user press `^C` which sends the process a `SIGINT`. ```swift import Signals ... let server: SomeServer = ... Signals.trap(signal: .int) { signal in server.shutdownServer() } server.run() ``` Additionally, convenience API's that build on the basic API specified above are provided that will allow for trapping multiple signals, each to a separate handler or to a single handler. - `trap(signals signals: [(signal: Signal, action: SigActionHandler)])` - This lets you trap multiple signals to separate handlers in a single function call. - `trap(signals signals: [Signal], action: SigActionHandler)` - This API lets you trap multiple signals to a common handler. #### Raising a signal - `raise(signal signal: Signal)` - This API is used to send an operating system signal to your application. This example illustrates how to use Signals to raise a signal with the OS, in this case `SIGABRT`. ```swift import Signals ... Signals.raise(signal: .abrt) ``` #### Ignoring a signal - `func ignore(signal: Signal)` - This API is used to ignore an operating system signal. This example illustrates how to use Signals to ignore a signal with the OS, in this case `SIGPIPE`. ```swift import Signals ... Signals.ignore(signal: .pipe) ``` #### Restoring a signals default handler - `func restore(signal: Signal)` - This API is used to restore an operating system signals default handler. This example illustrates how to use Signals to restore a signals default handler, in this case `SIGPIPE`. ```swift import Signals ... Signals.restore(signal: .pipe) ``` #### Adding a USER-DEFINED signal This example shows how to add a user defined signal, add a trap handler for it and then raise the signal. ```swift import Signals let mySignal = Signals.Signal.user(20) Signals.trap(signal: mySignal) { signal in print("Received signal \(signal)") } Signals.raise(signal: mySignal) ``` The output of the above snippet is: ``` Received signal 20 ``` ## Community We love to talk server-side Swift and Kitura. Join our [Slack](http://swift-at-ibm-slack.mybluemix.net/) to meet the team! ## License This library is licensed under Apache 2.0. Full license text is available in [LICENSE](https://github.com/Kitura/BlueSignals/blob/master/LICENSE).