[][src]Crate signal_hook_registry

Backend of the signal-hook crate.

The signal-hook crate tries to provide an API to the unix signals, which are a global resource. Therefore, it is desirable an application contains just one version of the crate which manages this global resource. But that makes it impossible to make breaking changes in the API.

Therefore, this crate provides very minimal and low level API to the signals that is unlikely to have to change, while there may be multiple versions of the signal-hook that all use this low-level API to provide different versions of the high level APIs.

It is also possible some other crates might want to build a completely different API. This split allows these crates to still reuse the same low-level routines in this crate instead of going to the (much more dangerous) unix calls.

What this crate provides

The only thing this crate does is multiplexing the signals. An application or library can add or remove callbacks and have multiple callbacks for the same signal.

It handles dispatching the callbacks and managing them in a way that uses only the async-signal-safe functions inside the signal handler. Note that the callbacks are still run inside the signal handler, so it is up to the caller to ensure they are also async-signal-safe.

What this is for

This is a building block for other libraries creating reasonable abstractions on top of signals. The signal-hook is the generally preferred way if you need to handle signals in your application and provides several safe patterns of doing so.

Rust version compatibility

Currently builds on 1.26.0 an newer and this is very unlikely to change. However, tests require dependencies that don't build there, so tests need newer Rust version (they are run on stable).

Portability

This crate includes a limited support for Windows, based on signal/raise in the CRT. There are differences in both API and behavior:

Structs

SigId

An ID of registered action.

Constants

FORBIDDEN

List of forbidden signals.

Functions

register

Registers an arbitrary action for the given signal.

register_sigaction

Register a signal action.

register_signal_unchecked

Register a signal action without checking for forbidden signals.

register_unchecked

Register a signal action without checking for forbidden signals.

unregister

Removes a previously installed action.

unregister_signal

Removes all previously installed actions for a given signal.