Swiftpack.co - Package - IBM-Swift/BlueSignals

APIDoc Build Status - Master macOS iOS Linux Apache 2 Slack Status

Signals

Generic Cross Platform Signal Handler.

Prerequisites

Swift

  • Swift Open Source swift-4.0.0-RELEASE toolchain (Minimum REQUIRED for latest release)
  • Swift Open Source swift-4.1.2-RELEASE toolchain (Recommended)
  • Swift toolchain included in Xcode Version 9.4 or higher.

macOS

  • macOS 10.11.6 (El Capitan) or higher.
  • Xcode Version 9.0 or higher using one of the above toolchains.
  • Xcode Version 9.4 or higher using the included toolchain (Recommended).

iOS

  • iOS 10.0 or higher
  • Xcode Version 9.0 or higher using one of the above toolchains.
  • Xcode Version 9.4 or higher using the included toolchain (Recommended).

Linux

  • Ubuntu 16.04 (or 16.10 but only tested on 16.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

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.

Github

link
Stars: 36
Help us keep the lights on

Dependencies

Releases

1.0.6 - Feb 27, 2018

Version 1.0

Generic Cross Platform Signal Handler.

Prerequisites

Swift

  • Swift Open Source swift-4.0.0-RELEASE toolchain (Minimum REQUIRED for latest release)
  • Swift Open Source swift-4.1-RELEASE toolchain (Recommended)
  • Swift toolchain included in Xcode Version 9.3 (9E145) or higher.

macOS

  • macOS 10.11.6 (El Capitan) or higher.
  • Xcode Version 9.0 (9A325) or higher using one of the above toolchains.
  • Xcode Version 9.2 (9C40b) or higher using the included toolchain (Recommended).
  • CommonCrypto is provided by macOS.

iOS

  • iOS 10.0 or higher
  • Xcode Version 9.0 (9A325) or higher using one of the above toolchains.
  • Xcode Version 9.3 (9E145) or higher using the included toolchain (Recommended).

Linux

  • Ubuntu 16.04 (or 16.10 but only tested on 16.04).
  • One of the Swift Open Source toolchain listed above.

Changes since 1.0.0

  • Updated for Swift 4.1.
  • Updated for Swift 4.2, added support for Travis CI.
  • Minor license update.

0.9.52 - Aug 19, 2016

This release minimally requires use of the swift-3.1.1-RELEASE toolchain or the swift-4.0.0-RELEASE toolchain which is recommended.

  • Compatible with Xcode 9.0 (9A235) General Release or higher using one of the above toolchains.
  • Allow use on iOS, tvOS and watchOS as well as macOS.
  • Added new APIs to allow for ignoring a signal and restoring a signals default behavior.
  • Swift 4 fixes. See issue #2 and related PR #3.
  • Swift 4 Support.

0.8.0 - Aug 16, 2016

This release requires use of the swift-DEVELOPMENT-SNAPSHOT-2016-08-15-a toolchain.

  • Compatible with Xcode 8 Beta 6 using the above toolchain.

0.7.1 - Aug 6, 2016

This release requires use of the swift-DEVELOPMENT-SNAPSHOT-2016-08-04-a toolchain or the new swift-DEVELOPMENT-SNAPSHOT-2016-08-07-a toolchain.

  • Compatible with Xcode 8 Beta 4 using the above toolchain.

0.5.0 - Jul 26, 2016

This release requires use of the new swift-DEVELOPMENT-SNAPSHOT-2016-07-25-a toolchain.

Note: Due to inconsistencies in the implementation of Data on macOS and Linux, this release continues to use the NSData and NSMutableData types. Once these inconsistencies are rectified, the Data type will be adopted.