third_party/rust_crates/vendor/signal-hook/src/lib.rs - fuchsia - Git at Google

 #![doc(
     test(attr(deny(warnings))),
     test(attr(allow(bare_trait_objects, unknown_lints)))
 )]
 #![warn(missing_docs)]
 // Don't fail on links to things not enabled in features
 #![allow(
     unknown_lints,
     renamed_and_removed_lints,
     intra_doc_link_resolution_failure,
     broken_intra_doc_links
 )]
 // These little nifty labels saying that something needs a feature to be enabled
 #![cfg_attr(docsrs, feature(doc_cfg))]
 //! Library for easier and safe Unix signal handling
 //!
 //! Unix signals are inherently hard to handle correctly, for several reasons:
 //!
 //! * They are a global resource. If a library wants to set its own signal handlers, it risks
 //!   disrupting some other library. It is possible to chain the previous signal handler, but then
 //!   it is impossible to remove the old signal handlers from the chains in any practical manner.
 //! * They can be called from whatever thread, requiring synchronization. Also, as they can
 //!   interrupt a thread at any time, making most handling race-prone.
 //! * According to the POSIX standard, the set of functions one may call inside a signal handler is
 //!   limited to very few of them. To highlight, mutexes (or other locking mechanisms) and memory
 //!   allocation and deallocation is *not* allowed.
 //!
 //! # The goal of the library
 //!
 //! The aim is to subscriptions to signals a „structured“ resource, in a similar way memory
 //! allocation is ‒ parts of the program can independently subscribe and it's the same part of the
 //! program that can give them up, independently of what the other parts do. Therefore, it is
 //! possible to register multiple actions to the same signal.
 //!
 //! Another goal is to shield applications away from differences between platforms. Various Unix
 //! systems have little quirks and differences that need to be worked around and that's not
 //! something every application should be dealing with. We even try to provide some support for
 //! Windows, but we lack the expertise in that area, so that one is not complete and is a bit rough
 //! (if you know how it works there and are willing to either contribute the code or consult,
 //! please get in touch).
 //!
 //! Furthermore, it provides implementation of certain common signal-handling patterns, usable from
 //! safe Rust, without the application author needing to learn about *all* the traps.
 //!
 //! Note that despite everything, there are still some quirks around signal handling that are not
 //! possible to paper over and need to be considered. Also, there are some signal use cases that
 //! are inherently unsafe and they are not covered by this crate.
 //!
 //! # Anatomy of the crate
 //!
 //! The crate is split into several modules.
 //!
 //! The easiest way to handle signals is using the [`Signals`][crate::iterator::Signals] iterator
 //! thing. It can register for a set of signals and produce them one by one, in a blocking manner.
 //! You can reserve a thread for handling them as they come. If you want something asynchronous,
 //! there are adaptor crates for the most common asynchronous runtimes. The module also contains
 //! ways to build iterators that produce a bit more information that just the signal number.
 //!
 //! The [`flag`] module contains routines to set a flag based on incoming signals and to do
 //! certain actions inside the signal handlers based on the flags (the flags can also be
 //! manipulated by the rest of the application). This allows building things like checking if a
 //! signal happened on each loop iteration or making sure application shuts down on the second
 //! CTRL+C if it got stuck in graceful shutdown requested by the first.
 //!
 //! The [`consts`] module contains some constants, most importantly the signal numbers themselves
 //! (these are just re-exports from [`libc`] and if your OS has some extra ones, you can use them
 //! too, this is just for convenience).
 //!
 //! And last, there is the [`low_level`] module. It contains routines to directly register and
 //! unregister arbitrary actions. Some of the patters in the above modules return a [`SigId`],
 //! which can be used with the [`low_level::unregister`] to remove the action. There are also some
 //! other utilities that are more suited to build other abstractions with than to use directly.
 //!
 //! Certain parts of the library can be enabled or disabled with use flags:
 //!
 //! * `channel`: The [low_level::channel] module (on by default).
 //! * `iterator`: The [iterator] module (on by default).
 //! * `extended-sig-info`: Support for providing more information in the iterators or from the
 //!   async adaptor crates. This is off by default.
 //!
 //! # Limitations
 //!
 //! * OS limitations still apply. Certain signals are not possible to override or subscribe to ‒
 //!   `SIGKILL` or `SIGSTOP`.
 //! * Overriding some others is probably a very stupid idea (or very unusual needs) ‒ handling eg.
 //!   `SIGSEGV` is not something done lightly. For that reason, the crate will panic in case
 //!   registering of these is attempted (see [`FORBIDDEN`][crate::consts::FORBIDDEN]. If you still
 //!   need to do so, you can find such APIs in the `signal-hook-registry` backend crate, but
 //!   additional care must be taken.
 //! * Interaction with other signal-handling libraries is limited. If signal-hook finds an existing
 //!   handler present, it chain-calls it from the signal it installs and assumes other libraries
 //!   would do the same, but that's everything that can be done to make it work with libraries not
 //!   based on [`signal-hook-registry`](https://lib.rs/signal-hook-registry)
 //!   (the backend of this crate).
 //! * The above chaining contains a race condition in multi-threaded programs, where the previous
 //!   handler might not get called if it is received during the registration process. This is
 //!   handled (at least on non-windows platforms) on the same thread where the registration
 //!   happens, therefore it is advised to register at least one action for each signal of interest
 //!   early, before any additional threads are started. Registering any additional (or removing and
 //!   registering again) action on the same signal is without the race condition.
 //! * Once at least one action is registered for a signal, the default action is replaced (this is
 //!   how signals work in the OS). Even if all actions of that signal are removed, `signal-hook`
 //!   does not restore the default handler (such behaviour would be at times inconsistent with
 //!   making the actions independent and there's no reasonable way to do so in a race-free way in a
 //!   multi-threaded program while also dealing with signal handlers registered with other
 //!   libraries). It is, however, possible to *emulate* the default handler (see the
 //!   [`emulate_default_handler`][low_level::emulate_default_handler]) ‒ there are only 4
 //!   default handlers:
 //!   - Ignore. This is easy to emulate.
 //!   - Abort. Depending on if you call it from within a signal handler of from outside, the
 //!     [`low_level::abort`] or [`std::process::abort`] can be used.
 //!   - Terminate. This can be done with `exit` ([`low_level::exit`] or [`std::process::exit`]).
 //!   - Stop. It is possible to [`raise`][low_level::raise] the [`SIGSTOP`][consts::SIGSTOP] signal.
 //!     That one can't be replaced and always stops the application.
 //! * Many of the patterns here can collate multiple instances of the same signal into fewer
 //!   instances, if the application doesn't consume them fast enough. This is consistent with what
 //!   the kernel does if the application doesn't keep up with them, so it is something one needs to
 //!   deal with anyway.
 //!
 //! # Signal masks
 //!
 //! As the library uses `sigaction` under the hood, signal masking works as expected (eg. with
 //! `pthread_sigmask`). This means, signals will *not* be delivered if the signal is masked in all
 //! program's threads.
 //!
 //! By the way, if you do want to modify the signal mask (or do other Unix-specific magic), the
 //! [nix](https://lib.rs/crates/nix) crate offers safe interface to many low-level functions,
 //! including
 //! [`pthread_sigmask`](https://docs.rs/nix/0.11.0/nix/sys/signal/fn.pthread_sigmask.html).
 //!
 //! # Portability
 //!
 //! It should work on any POSIX.1-2001 system, which are all the major big OSes with the notable
 //! exception of Windows.
 //!
 //! Non-standard signals are also supported. Pass the signal value directly from `libc` or use
 //! the numeric value directly.
 //!
 //! ```rust
 //! use std::sync::Arc;
 //! use std::sync::atomic::{AtomicBool};
 //! let term = Arc::new(AtomicBool::new(false));
 //! let _ = signal_hook::flag::register(libc::SIGINT, Arc::clone(&term));
 //! ```
 //!
 //! This crate includes a limited support for Windows, based on `signal`/`raise` in the CRT.
 //! There are differences in both API and behavior:
 //!
 //! - Many parts of the library are not available there.
 //! - We have only a few signals: `SIGABRT`, `SIGABRT_COMPAT`, `SIGBREAK`,
 //!   `SIGFPE`, `SIGILL`, `SIGINT`, `SIGSEGV` and `SIGTERM`.
 //! - Due to lack of signal blocking, there's a race condition.
 //!   After the call to `signal`, there's a moment where we miss a signal.
 //!   That means when you register a handler, there may be a signal which invokes
 //!   neither the default handler or the handler you register.
 //! - Handlers registered by `signal` in Windows are cleared on first signal.
 //!   To match behavior in other platforms, we re-register the handler each time the handler is
 //!   called, but there's a moment where we miss a handler.
 //!   That means when you receive two signals in a row, there may be a signal which invokes
 //!   the default handler, nevertheless you certainly have registered the handler.
 //!
 //! Moreover, signals won't work as you expected. `SIGTERM` isn't actually used and
 //! not all `Ctrl-C`s are turned into `SIGINT`.
 //!
 //! Patches to improve Windows support in this library are welcome.
 //!
 //! # Features
 //!
 //! There are several feature flags that control how much is available as part of the crate, some
 //! enabled by default.
 //!
 //! * `channel`: (enabled by default) The [Channel][crate::low_level::channel] synchronization
 //!   primitive for exporting data out of signal handlers.
 //! * `iterator`: (enabled by default) An [Signals iterator][crate::iterator::Signals] that
 //!   provides a convenient interface for receiving signals in rust-friendly way.
 //! * `extended-siginfo` adds support for providing extra information as part of the iterator
 //!   interface.
 //!
 //! # Examples
 //!
 //! ## Using a flag to terminate a loop-based application
 //!
 //! ```rust
 //! use std::io::Error;
 //! use std::sync::Arc;
 //! use std::sync::atomic::{AtomicBool, Ordering};
 //!
 //! fn main() -> Result<(), Error> {
 //!     let term = Arc::new(AtomicBool::new(false));
 //!     signal_hook::flag::register(signal_hook::consts::SIGTERM, Arc::clone(&term))?;
 //!     while !term.load(Ordering::Relaxed) {
 //!         // Do some time-limited stuff here
 //!         // (if this could block forever, then there's no guarantee the signal will have any
 //!         // effect).
 //! #
 //! #       // Hack to terminate the example, not part of the real code.
 //! #       term.store(true, Ordering::Relaxed);
 //!     }
 //!     Ok(())
 //! }
 //! ```
 //!
 //! ## A complex signal handling with a background thread
 //!
 //! This also handles the double CTRL+C situation (eg. the second CTRL+C kills) and resetting the
 //! terminal on `SIGTSTP` (CTRL+Z, curses-based applications should do something like this).
 //!
 //! ```rust
 //! # #[cfg(feature = "extended-siginfo")] pub mod test {
 //! use std::io::Error;
 //! use std::sync::Arc;
 //! use std::sync::atomic::AtomicBool;
 //!
 //! use signal_hook::consts::signal::*;
 //! use signal_hook::consts::TERM_SIGNALS;
 //! use signal_hook::flag;
 //! // A friend of the Signals iterator, but can be customized by what we want yielded about each
 //! // signal.
 //! use signal_hook::iterator::SignalsInfo;
 //! use signal_hook::iterator::exfiltrator::WithOrigin;
 //! use signal_hook::low_level;
 //!
 //! # struct App;
 //! # impl App {
 //! # fn run_background() -> Self { Self }
 //! # fn wait_for_stop(self) {}
 //! # fn restore_term(&self) {}
 //! # fn claim_term(&self) {}
 //! # fn resize_term(&self) {}
 //! # fn reload_config(&self) {}
 //! # fn print_stats(&self) {}
 //! # }
 //!
 //! # pub
 //! fn main() -> Result<(), Error> {
 //!     // Make sure double CTRL+C and similar kills
 //!     let term_now = Arc::new(AtomicBool::new(false));
 //!     for sig in TERM_SIGNALS {
 //!         // When terminated by a second term signal, exit with exit code 1.
 //!         // This will do nothing the first time (because term_now is false).
 //!         flag::register_conditional_shutdown(*sig, 1, Arc::clone(&term_now))?;
 //!         // But this will "arm" the above for the second time, by setting it to true.
 //!         // The order of registering these is important, if you put this one first, it will
 //!         // first arm and then terminate ‒ all in the first round.
 //!         flag::register(*sig, Arc::clone(&term_now))?;
 //!     }
 //!
 //!     // Subscribe to all these signals with information about where they come from. We use the
 //!     // extra info only for logging in this example (it is not available on all the OSes or at
 //!     // all the occasions anyway, it may return `Unknown`).
 //!     let mut sigs = vec![
 //!         // Some terminal handling
 //!         SIGTSTP, SIGCONT, SIGWINCH,
 //!         // Reload of configuration for daemons ‒ um, is this example for a TUI app or a daemon
 //!         // O:-)? You choose...
 //!         SIGHUP,
 //!         // Application-specific action, to print some statistics.
 //!         SIGUSR1,
 //!     ];
 //!     sigs.extend(TERM_SIGNALS);
 //!     let mut signals = SignalsInfo::<WithOrigin>::new(&sigs)?;
 //! #   low_level::raise(SIGTERM)?; // Trick to terminate the example
 //!
 //!     // This is the actual application that'll start in its own thread. We'll control it from
 //!     // this thread based on the signals, but it keeps running.
 //!     // This is called after all the signals got registered, to avoid the short race condition
 //!     // in the first registration of each signal in multi-threaded programs.
 //!     let app = App::run_background();
 //!
 //!     // Consume all the incoming signals. This happens in "normal" Rust thread, not in the
 //!     // signal handlers. This means that we are allowed to do whatever we like in here, without
 //!     // restrictions, but it also means the kernel believes the signal already got delivered, we
 //!     // handle them in delayed manner. This is in contrast with eg the above
 //!     // `register_conditional_shutdown` where the shutdown happens *inside* the handler.
 //!     let mut has_terminal = true;
 //!     for info in &mut signals {
 //!         // Will print info about signal + where it comes from.
 //!         eprintln!("Received a signal {:?}", info);
 //!         match info.signal {
 //!             SIGTSTP => {
 //!                 // Restore the terminal to non-TUI mode
 //!                 if has_terminal {
 //!                     app.restore_term();
 //!                     has_terminal = false;
 //!                     // And actually stop ourselves.
 //!                     low_level::emulate_default_handler(SIGTSTP)?;
 //!                 }
 //!             }
 //!             SIGCONT => {
 //!                 if !has_terminal {
 //!                     app.claim_term();
 //!                     has_terminal = true;
 //!                 }
 //!             }
 //!             SIGWINCH => app.resize_term(),
 //!             SIGHUP => app.reload_config(),
 //!             SIGUSR1 => app.print_stats(),
 //!             term_sig => { // These are all the ones left
 //!                 eprintln!("Terminating");
 //!                 assert!(TERM_SIGNALS.contains(&term_sig));
 //!                 break;
 //!             }
 //!         }
 //!     }
 //!
 //!     // If during this another termination signal comes, the trick at the top would kick in and
 //!     // terminate early. But if it doesn't, the application shuts down gracefully.
 //!     app.wait_for_stop();
 //!
 //!     Ok(())
 //! }
 //! # }
 //! # fn main() {
 //! # #[cfg(feature = "extended-siginfo")] test::main().unwrap();
 //! # }
 //! ```
 //!
 //! # Asynchronous runtime support
 //!
 //! If you are looking for integration with an asynchronous runtime take a look at one of the
 //! following adapter crates:
 //!
 //! * [`signal-hook-async-std`](https://docs.rs/signal-hook-async-std) for async-std support
 //! * [`signal-hook-mio`](https://docs.rs/signal-hook-mio) for MIO support
 //! * [`signal-hook-tokio`](https://docs.rs/signal-hook-tokio) for Tokio support
 //!
 //! Feel free to open a pull requests if you want to add support for runtimes not mentioned above.
 //!
 //! # Porting from previous versions
 //!
 //! There were some noisy changes when going from 0.2 version to the 0.3 version. In particular:
 //!
 //! * A lot of things moved around to make the structure of the crate a bit more understandable.
 //!   Most of the time it should be possible to just search the documentation for the name that
 //!   can't be resolved to discover the new location.
 //!   - The signal constants (`SIGTERM`, for example) are in [`consts`] submodule (individual
 //!     imports) and in the [`consts::signal`] (for wildcard import of all of them).
 //!   - Some APIs that are considered more of a low-level building blocks than for casual day to
 //!     day use are now in the [`low_level`] submodule.
 //! * The previous version contained the `cleanup` module that allowed for removal of the actions
 //!   in rather destructive way (nuking actions of arbitrary other parts of the program). This is
 //!   completely gone in this version. The use case of shutting down the application on second
 //!   CTRL+C is now supported by a pattern described in the [`flag`] submodule. For other similar
 //!   needs, refer above for emulating default handlers.

 pub mod flag;
 #[cfg(all(not(windows), feature = "iterator"))]
 #[cfg_attr(docsrs, doc(cfg(all(not(windows), feature = "iterator"))))]
 pub mod iterator;
 pub mod low_level;

 /// The low-level constants.
 ///
 /// Like the signal numbers.
 pub mod consts {

     use libc::c_int;

     /// The signal constants.
     ///
     /// Can be mass-imported by `use signal_hook::consts::signal::*`, without polluting the
     /// namespace with other names. Also available in the [`consts`][crate::consts] directly (but
     /// with more constants around).
     pub mod signal {
         #[cfg(not(windows))]
         pub use libc::{
             SIGABRT, SIGALRM, SIGBUS, SIGCHLD, SIGCONT, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGIO,
             SIGKILL, SIGPIPE, SIGPROF, SIGQUIT, SIGSEGV, SIGSTOP, SIGSYS, SIGTERM, SIGTRAP,
             SIGTSTP, SIGTTIN, SIGTTOU, SIGURG, SIGUSR1, SIGUSR2, SIGVTALRM, SIGWINCH, SIGXCPU,
             SIGXFSZ,
         };

         #[cfg(windows)]
         pub use libc::{SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM};

         // NOTE: they perhaps deserve backport to libc.
         #[cfg(windows)]
         /// Same as `SIGABRT`, but the number is compatible to other platforms.
         pub const SIGABRT_COMPAT: libc::c_int = 6;
         #[cfg(windows)]
         /// Ctrl-Break is pressed for Windows Console processes.
         pub const SIGBREAK: libc::c_int = 21;
     }

     pub use self::signal::*;

     pub use signal_hook_registry::FORBIDDEN;

     /// Various signals commonly requesting shutdown of an application.
     #[cfg(not(windows))]
     pub const TERM_SIGNALS: &[c_int] = &[SIGTERM, SIGQUIT, SIGINT];

     /// Various signals commonly requesting shutdown of an application.
     #[cfg(windows)]
     pub const TERM_SIGNALS: &[c_int] = &[SIGTERM, SIGINT];
 }

 pub use signal_hook_registry::SigId;
	#![doc(
	test(attr(deny(warnings))),
	test(attr(allow(bare_trait_objects, unknown_lints)))
	)]
	#![warn(missing_docs)]
	// Don't fail on links to things not enabled in features
	#![allow(
	unknown_lints,
	renamed_and_removed_lints,
	intra_doc_link_resolution_failure,
	broken_intra_doc_links
	)]
	// These little nifty labels saying that something needs a feature to be enabled
	#![cfg_attr(docsrs, feature(doc_cfg))]
	//! Library for easier and safe Unix signal handling
	//!
	//! Unix signals are inherently hard to handle correctly, for several reasons:
	//!
	//! * They are a global resource. If a library wants to set its own signal handlers, it risks
	//! disrupting some other library. It is possible to chain the previous signal handler, but then
	//! it is impossible to remove the old signal handlers from the chains in any practical manner.
	//! * They can be called from whatever thread, requiring synchronization. Also, as they can
	//! interrupt a thread at any time, making most handling race-prone.
	//! * According to the POSIX standard, the set of functions one may call inside a signal handler is
	//! limited to very few of them. To highlight, mutexes (or other locking mechanisms) and memory
	//! allocation and deallocation is not allowed.
	//!
	//! # The goal of the library
	//!
	//! The aim is to subscriptions to signals a „structured“ resource, in a similar way memory
	//! allocation is ‒ parts of the program can independently subscribe and it's the same part of the
	//! program that can give them up, independently of what the other parts do. Therefore, it is
	//! possible to register multiple actions to the same signal.
	//!
	//! Another goal is to shield applications away from differences between platforms. Various Unix
	//! systems have little quirks and differences that need to be worked around and that's not
	//! something every application should be dealing with. We even try to provide some support for
	//! Windows, but we lack the expertise in that area, so that one is not complete and is a bit rough
	//! (if you know how it works there and are willing to either contribute the code or consult,
	//! please get in touch).
	//!
	//! Furthermore, it provides implementation of certain common signal-handling patterns, usable from
	//! safe Rust, without the application author needing to learn about all the traps.
	//!
	//! Note that despite everything, there are still some quirks around signal handling that are not
	//! possible to paper over and need to be considered. Also, there are some signal use cases that
	//! are inherently unsafe and they are not covered by this crate.
	//!
	//! # Anatomy of the crate
	//!
	//! The crate is split into several modules.
	//!
	//! The easiest way to handle signals is using the [`Signals`][crate::iterator::Signals] iterator
	//! thing. It can register for a set of signals and produce them one by one, in a blocking manner.
	//! You can reserve a thread for handling them as they come. If you want something asynchronous,
	//! there are adaptor crates for the most common asynchronous runtimes. The module also contains
	//! ways to build iterators that produce a bit more information that just the signal number.
	//!
	//! The [`flag`] module contains routines to set a flag based on incoming signals and to do
	//! certain actions inside the signal handlers based on the flags (the flags can also be
	//! manipulated by the rest of the application). This allows building things like checking if a
	//! signal happened on each loop iteration or making sure application shuts down on the second
	//! CTRL+C if it got stuck in graceful shutdown requested by the first.
	//!
	//! The [`consts`] module contains some constants, most importantly the signal numbers themselves
	//! (these are just re-exports from [`libc`] and if your OS has some extra ones, you can use them
	//! too, this is just for convenience).
	//!
	//! And last, there is the [`low_level`] module. It contains routines to directly register and
	//! unregister arbitrary actions. Some of the patters in the above modules return a [`SigId`],
	//! which can be used with the [`low_level::unregister`] to remove the action. There are also some
	//! other utilities that are more suited to build other abstractions with than to use directly.
	//!
	//! Certain parts of the library can be enabled or disabled with use flags:
	//!
	//! * `channel`: The [low_level::channel] module (on by default).
	//! * `iterator`: The [iterator] module (on by default).
	//! * `extended-sig-info`: Support for providing more information in the iterators or from the
	//! async adaptor crates. This is off by default.
	//!
	//! # Limitations
	//!
	//! * OS limitations still apply. Certain signals are not possible to override or subscribe to ‒
	//! `SIGKILL` or `SIGSTOP`.
	//! * Overriding some others is probably a very stupid idea (or very unusual needs) ‒ handling eg.
	//! `SIGSEGV` is not something done lightly. For that reason, the crate will panic in case
	//! registering of these is attempted (see [`FORBIDDEN`][crate::consts::FORBIDDEN]. If you still
	//! need to do so, you can find such APIs in the `signal-hook-registry` backend crate, but
	//! additional care must be taken.
	//! * Interaction with other signal-handling libraries is limited. If signal-hook finds an existing
	//! handler present, it chain-calls it from the signal it installs and assumes other libraries
	//! would do the same, but that's everything that can be done to make it work with libraries not
	//! based on [`signal-hook-registry`](https://lib.rs/signal-hook-registry)
	//! (the backend of this crate).
	//! * The above chaining contains a race condition in multi-threaded programs, where the previous
	//! handler might not get called if it is received during the registration process. This is
	//! handled (at least on non-windows platforms) on the same thread where the registration
	//! happens, therefore it is advised to register at least one action for each signal of interest
	//! early, before any additional threads are started. Registering any additional (or removing and
	//! registering again) action on the same signal is without the race condition.
	//! * Once at least one action is registered for a signal, the default action is replaced (this is
	//! how signals work in the OS). Even if all actions of that signal are removed, `signal-hook`
	//! does not restore the default handler (such behaviour would be at times inconsistent with
	//! making the actions independent and there's no reasonable way to do so in a race-free way in a
	//! multi-threaded program while also dealing with signal handlers registered with other
	//! libraries). It is, however, possible to emulate the default handler (see the
	//! [`emulate_default_handler`][low_level::emulate_default_handler]) ‒ there are only 4
	//! default handlers:
	//! - Ignore. This is easy to emulate.
	//! - Abort. Depending on if you call it from within a signal handler of from outside, the
	//! [`low_level::abort`] or [`std::process::abort`] can be used.
	//! - Terminate. This can be done with `exit` ([`low_level::exit`] or [`std::process::exit`]).
	//! - Stop. It is possible to [`raise`][low_level::raise] the [`SIGSTOP`][consts::SIGSTOP] signal.
	//! That one can't be replaced and always stops the application.
	//! * Many of the patterns here can collate multiple instances of the same signal into fewer
	//! instances, if the application doesn't consume them fast enough. This is consistent with what
	//! the kernel does if the application doesn't keep up with them, so it is something one needs to
	//! deal with anyway.
	//!
	//! # Signal masks
	//!
	//! As the library uses `sigaction` under the hood, signal masking works as expected (eg. with
	//! `pthread_sigmask`). This means, signals will not be delivered if the signal is masked in all
	//! program's threads.
	//!
	//! By the way, if you do want to modify the signal mask (or do other Unix-specific magic), the
	//! [nix](https://lib.rs/crates/nix) crate offers safe interface to many low-level functions,
	//! including
	//! [`pthread_sigmask`](https://docs.rs/nix/0.11.0/nix/sys/signal/fn.pthread_sigmask.html).
	//!
	//! # Portability
	//!
	//! It should work on any POSIX.1-2001 system, which are all the major big OSes with the notable
	//! exception of Windows.
	//!
	//! Non-standard signals are also supported. Pass the signal value directly from `libc` or use
	//! the numeric value directly.
	//!
	//! ```rust
	//! use std::sync::Arc;
	//! use std::sync::atomic::{AtomicBool};
	//! let term = Arc::new(AtomicBool::new(false));
	//! let _ = signal_hook::flag::register(libc::SIGINT, Arc::clone(&term));
	//! ```
	//!
	//! This crate includes a limited support for Windows, based on `signal`/`raise` in the CRT.
	//! There are differences in both API and behavior:
	//!
	//! - Many parts of the library are not available there.
	//! - We have only a few signals: `SIGABRT`, `SIGABRT_COMPAT`, `SIGBREAK`,
	//! `SIGFPE`, `SIGILL`, `SIGINT`, `SIGSEGV` and `SIGTERM`.
	//! - Due to lack of signal blocking, there's a race condition.
	//! After the call to `signal`, there's a moment where we miss a signal.
	//! That means when you register a handler, there may be a signal which invokes
	//! neither the default handler or the handler you register.
	//! - Handlers registered by `signal` in Windows are cleared on first signal.
	//! To match behavior in other platforms, we re-register the handler each time the handler is
	//! called, but there's a moment where we miss a handler.
	//! That means when you receive two signals in a row, there may be a signal which invokes
	//! the default handler, nevertheless you certainly have registered the handler.
	//!
	//! Moreover, signals won't work as you expected. `SIGTERM` isn't actually used and
	//! not all `Ctrl-C`s are turned into `SIGINT`.
	//!
	//! Patches to improve Windows support in this library are welcome.
	//!
	//! # Features
	//!
	//! There are several feature flags that control how much is available as part of the crate, some
	//! enabled by default.
	//!
	//! * `channel`: (enabled by default) The [Channel][crate::low_level::channel] synchronization
	//! primitive for exporting data out of signal handlers.
	//! * `iterator`: (enabled by default) An [Signals iterator][crate::iterator::Signals] that
	//! provides a convenient interface for receiving signals in rust-friendly way.
	//! * `extended-siginfo` adds support for providing extra information as part of the iterator
	//! interface.
	//!
	//! # Examples
	//!
	//! ## Using a flag to terminate a loop-based application
	//!
	//! ```rust
	//! use std::io::Error;
	//! use std::sync::Arc;
	//! use std::sync::atomic::{AtomicBool, Ordering};
	//!
	//! fn main() -> Result<(), Error> {
	//! let term = Arc::new(AtomicBool::new(false));
	//! signal_hook::flag::register(signal_hook::consts::SIGTERM, Arc::clone(&term))?;
	//! while !term.load(Ordering::Relaxed) {
	//! // Do some time-limited stuff here
	//! // (if this could block forever, then there's no guarantee the signal will have any
	//! // effect).
	//! #
	//! # // Hack to terminate the example, not part of the real code.
	//! # term.store(true, Ordering::Relaxed);
	//! }
	//! Ok(())
	//! }
	//! ```
	//!
	//! ## A complex signal handling with a background thread
	//!
	//! This also handles the double CTRL+C situation (eg. the second CTRL+C kills) and resetting the
	//! terminal on `SIGTSTP` (CTRL+Z, curses-based applications should do something like this).
	//!
	//! ```rust
	//! # #[cfg(feature = "extended-siginfo")] pub mod test {
	//! use std::io::Error;
	//! use std::sync::Arc;
	//! use std::sync::atomic::AtomicBool;
	//!
	//! use signal_hook::consts::signal::*;
	//! use signal_hook::consts::TERM_SIGNALS;
	//! use signal_hook::flag;
	//! // A friend of the Signals iterator, but can be customized by what we want yielded about each
	//! // signal.
	//! use signal_hook::iterator::SignalsInfo;
	//! use signal_hook::iterator::exfiltrator::WithOrigin;
	//! use signal_hook::low_level;
	//!
	//! # struct App;
	//! # impl App {
	//! # fn run_background() -> Self { Self }
	//! # fn wait_for_stop(self) {}
	//! # fn restore_term(&self) {}
	//! # fn claim_term(&self) {}
	//! # fn resize_term(&self) {}
	//! # fn reload_config(&self) {}
	//! # fn print_stats(&self) {}
	//! # }
	//!
	//! # pub
	//! fn main() -> Result<(), Error> {
	//! // Make sure double CTRL+C and similar kills
	//! let term_now = Arc::new(AtomicBool::new(false));
	//! for sig in TERM_SIGNALS {
	//! // When terminated by a second term signal, exit with exit code 1.
	//! // This will do nothing the first time (because term_now is false).
	//! flag::register_conditional_shutdown(*sig, 1, Arc::clone(&term_now))?;
	//! // But this will "arm" the above for the second time, by setting it to true.
	//! // The order of registering these is important, if you put this one first, it will
	//! // first arm and then terminate ‒ all in the first round.
	//! flag::register(*sig, Arc::clone(&term_now))?;
	//! }
	//!
	//! // Subscribe to all these signals with information about where they come from. We use the
	//! // extra info only for logging in this example (it is not available on all the OSes or at
	//! // all the occasions anyway, it may return `Unknown`).
	//! let mut sigs = vec![
	//! // Some terminal handling
	//! SIGTSTP, SIGCONT, SIGWINCH,
	//! // Reload of configuration for daemons ‒ um, is this example for a TUI app or a daemon
	//! // O:-)? You choose...
	//! SIGHUP,
	//! // Application-specific action, to print some statistics.
	//! SIGUSR1,
	//! ];
	//! sigs.extend(TERM_SIGNALS);
	//! let mut signals = SignalsInfo::<WithOrigin>::new(&sigs)?;
	//! # low_level::raise(SIGTERM)?; // Trick to terminate the example
	//!
	//! // This is the actual application that'll start in its own thread. We'll control it from
	//! // this thread based on the signals, but it keeps running.
	//! // This is called after all the signals got registered, to avoid the short race condition
	//! // in the first registration of each signal in multi-threaded programs.
	//! let app = App::run_background();
	//!
	//! // Consume all the incoming signals. This happens in "normal" Rust thread, not in the
	//! // signal handlers. This means that we are allowed to do whatever we like in here, without
	//! // restrictions, but it also means the kernel believes the signal already got delivered, we
	//! // handle them in delayed manner. This is in contrast with eg the above
	//! // `register_conditional_shutdown` where the shutdown happens inside the handler.
	//! let mut has_terminal = true;
	//! for info in &mut signals {
	//! // Will print info about signal + where it comes from.
	//! eprintln!("Received a signal {:?}", info);
	//! match info.signal {
	//! SIGTSTP => {
	//! // Restore the terminal to non-TUI mode
	//! if has_terminal {
	//! app.restore_term();
	//! has_terminal = false;
	//! // And actually stop ourselves.
	//! low_level::emulate_default_handler(SIGTSTP)?;
	//! }
	//! }
	//! SIGCONT => {
	//! if !has_terminal {
	//! app.claim_term();
	//! has_terminal = true;
	//! }
	//! }
	//! SIGWINCH => app.resize_term(),
	//! SIGHUP => app.reload_config(),
	//! SIGUSR1 => app.print_stats(),
	//! term_sig => { // These are all the ones left
	//! eprintln!("Terminating");
	//! assert!(TERM_SIGNALS.contains(&term_sig));
	//! break;
	//! }
	//! }
	//! }
	//!
	//! // If during this another termination signal comes, the trick at the top would kick in and
	//! // terminate early. But if it doesn't, the application shuts down gracefully.
	//! app.wait_for_stop();
	//!
	//! Ok(())
	//! }
	//! # }
	//! # fn main() {
	//! # #[cfg(feature = "extended-siginfo")] test::main().unwrap();
	//! # }
	//! ```
	//!
	//! # Asynchronous runtime support
	//!
	//! If you are looking for integration with an asynchronous runtime take a look at one of the
	//! following adapter crates:
	//!
	//! * [`signal-hook-async-std`](https://docs.rs/signal-hook-async-std) for async-std support
	//! * [`signal-hook-mio`](https://docs.rs/signal-hook-mio) for MIO support
	//! * [`signal-hook-tokio`](https://docs.rs/signal-hook-tokio) for Tokio support
	//!
	//! Feel free to open a pull requests if you want to add support for runtimes not mentioned above.
	//!
	//! # Porting from previous versions
	//!
	//! There were some noisy changes when going from 0.2 version to the 0.3 version. In particular:
	//!
	//! * A lot of things moved around to make the structure of the crate a bit more understandable.
	//! Most of the time it should be possible to just search the documentation for the name that
	//! can't be resolved to discover the new location.
	//! - The signal constants (`SIGTERM`, for example) are in [`consts`] submodule (individual
	//! imports) and in the [`consts::signal`] (for wildcard import of all of them).
	//! - Some APIs that are considered more of a low-level building blocks than for casual day to
	//! day use are now in the [`low_level`] submodule.
	//! * The previous version contained the `cleanup` module that allowed for removal of the actions
	//! in rather destructive way (nuking actions of arbitrary other parts of the program). This is
	//! completely gone in this version. The use case of shutting down the application on second
	//! CTRL+C is now supported by a pattern described in the [`flag`] submodule. For other similar
	//! needs, refer above for emulating default handlers.

	pub mod flag;
	#[cfg(all(not(windows), feature = "iterator"))]
	#[cfg_attr(docsrs, doc(cfg(all(not(windows), feature = "iterator"))))]
	pub mod iterator;
	pub mod low_level;

	/// The low-level constants.
	///
	/// Like the signal numbers.
	pub mod consts {

	use libc::c_int;

	/// The signal constants.
	///
	/// Can be mass-imported by `use signal_hook::consts::signal::*`, without polluting the
	/// namespace with other names. Also available in the [`consts`][crate::consts] directly (but
	/// with more constants around).
	pub mod signal {
	#[cfg(not(windows))]
	pub use libc::{
	SIGABRT, SIGALRM, SIGBUS, SIGCHLD, SIGCONT, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGIO,
	SIGKILL, SIGPIPE, SIGPROF, SIGQUIT, SIGSEGV, SIGSTOP, SIGSYS, SIGTERM, SIGTRAP,
	SIGTSTP, SIGTTIN, SIGTTOU, SIGURG, SIGUSR1, SIGUSR2, SIGVTALRM, SIGWINCH, SIGXCPU,
	SIGXFSZ,
	};

	#[cfg(windows)]
	pub use libc::{SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM};

	// NOTE: they perhaps deserve backport to libc.
	#[cfg(windows)]
	/// Same as `SIGABRT`, but the number is compatible to other platforms.
	pub const SIGABRT_COMPAT: libc::c_int = 6;
	#[cfg(windows)]
	/// Ctrl-Break is pressed for Windows Console processes.
	pub const SIGBREAK: libc::c_int = 21;
	}

	pub use self::signal::*;

	pub use signal_hook_registry::FORBIDDEN;

	/// Various signals commonly requesting shutdown of an application.
	#[cfg(not(windows))]
	pub const TERM_SIGNALS: &[c_int] = &[SIGTERM, SIGQUIT, SIGINT];

	/// Various signals commonly requesting shutdown of an application.
	#[cfg(windows)]
	pub const TERM_SIGNALS: &[c_int] = &[SIGTERM, SIGINT];
	}

	pub use signal_hook_registry::SigId;