Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Kitura/BlueSignals

Generic Cross Platform Signal Handler
https://github.com/Kitura/BlueSignals

linux macos signals-default-handler swift trap-handler trap-multiple-signals

Last synced: about 1 month ago
JSON representation

Generic Cross Platform Signal Handler

Awesome Lists containing this project

README 

        


    

    APIDoc

    

    

    Build Status - Master

    

    macOS

    iOS

    Linux

    Apache 2

    

    Slack Status

    




# 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).