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 <path-to-clone>
% 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: <majorVersion>, minor: <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" ~> <majorVersion>.<minor>

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.

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.

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.

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.

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.

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.

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 to meet the team!

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.