tokio_signal/
lib.rs

1#![doc(html_root_url = "https://docs.rs/tokio-signal/0.2.9")]
2#![deny(missing_docs)]
3
4//! Asynchronous signal handling for Tokio
5//!
6//! > **Note:** This crate is **deprecated in tokio 0.2.x** and has been moved
7//! > into [`tokio::signal`] behind the `signal` [feature flag].
8//!
9//! [`tokio::signal`]: https://docs.rs/tokio/latest/tokio/signal/index.html
10//! [feature flag]: https://docs.rs/tokio/latest/tokio/index.html#feature-flags
11//!
12//! This crate implements asynchronous signal handling for Tokio, an
13//! asynchronous I/O framework in Rust. The primary type exported from this
14//! crate, `unix::Signal`, allows listening for arbitrary signals on Unix
15//! platforms, receiving them in an asynchronous fashion.
16//!
17//! Note that signal handling is in general a very tricky topic and should be
18//! used with great care. This crate attempts to implement 'best practice' for
19//! signal handling, but it should be evaluated for your own applications' needs
20//! to see if it's suitable.
21//!
22//! The are some fundamental limitations of this crate documented on the
23//! `Signal` structure as well.
24//!
25//! # Examples
26//!
27//! Print out all ctrl-C notifications received
28//!
29//! ```rust,no_run
30//! extern crate futures;
31//! extern crate tokio;
32//! extern crate tokio_signal;
33//!
34//! use futures::{Future, Stream};
35//!
36//! fn main() {
37//!     // Create an infinite stream of "Ctrl+C" notifications. Each item received
38//!     // on this stream may represent multiple ctrl-c signals.
39//!     let ctrl_c = tokio_signal::ctrl_c().flatten_stream();
40//!
41//!     // Process each ctrl-c as it comes in
42//!     let prog = ctrl_c.for_each(|()| {
43//!         println!("ctrl-c received!");
44//!         Ok(())
45//!     });
46//!
47//!     tokio::runtime::current_thread::block_on_all(prog).unwrap();
48//! }
49//! ```
50//!
51//! Wait for SIGHUP on Unix
52//!
53//! ```rust,no_run
54//! # extern crate futures;
55//! # extern crate tokio;
56//! # extern crate tokio_signal;
57//! # #[cfg(unix)]
58//! # mod foo {
59//! #
60//! extern crate futures;
61//! extern crate tokio;
62//! extern crate tokio_signal;
63//!
64//! use futures::{Future, Stream};
65//! use tokio_signal::unix::{Signal, SIGHUP};
66//!
67//! fn main() {
68//!     // Like the previous example, this is an infinite stream of signals
69//!     // being received, and signals may be coalesced while pending.
70//!     let stream = Signal::new(SIGHUP).flatten_stream();
71//!
72//!     // Convert out stream into a future and block the program
73//!     tokio::runtime::current_thread::block_on_all(stream.into_future()).ok().unwrap();
74//! }
75//! # }
76//! # fn main() {}
77//! ```
78
79extern crate futures;
80extern crate mio;
81extern crate tokio_executor;
82extern crate tokio_io;
83extern crate tokio_reactor;
84
85use std::io;
86
87use futures::stream::Stream;
88use futures::{future, Future};
89use tokio_reactor::Handle;
90
91pub mod unix;
92pub mod windows;
93
94/// A future whose error is `io::Error`
95pub type IoFuture<T> = Box<dyn Future<Item = T, Error = io::Error> + Send>;
96/// A stream whose error is `io::Error`
97pub type IoStream<T> = Box<dyn Stream<Item = T, Error = io::Error> + Send>;
98
99/// Creates a stream which receives "ctrl-c" notifications sent to a process.
100///
101/// In general signals are handled very differently across Unix and Windows, but
102/// this is somewhat cross platform in terms of how it can be handled. A ctrl-c
103/// event to a console process can be represented as a stream for both Windows
104/// and Unix.
105///
106/// This function binds to the default event loop. Note that
107/// there are a number of caveats listening for signals, and you may wish to
108/// read up on the documentation in the `unix` or `windows` module to take a
109/// peek.
110pub fn ctrl_c() -> IoFuture<IoStream<()>> {
111    ctrl_c_handle(&Handle::default())
112}
113
114/// Creates a stream which receives "ctrl-c" notifications sent to a process.
115///
116/// In general signals are handled very differently across Unix and Windows, but
117/// this is somewhat cross platform in terms of how it can be handled. A ctrl-c
118/// event to a console process can be represented as a stream for both Windows
119/// and Unix.
120///
121/// This function receives a `Handle` to an event loop and returns a future
122/// which when resolves yields a stream receiving all signal events. Note that
123/// there are a number of caveats listening for signals, and you may wish to
124/// read up on the documentation in the `unix` or `windows` module to take a
125/// peek.
126pub fn ctrl_c_handle(handle: &Handle) -> IoFuture<IoStream<()>> {
127    return ctrl_c_imp(handle);
128
129    #[cfg(unix)]
130    fn ctrl_c_imp(handle: &Handle) -> IoFuture<IoStream<()>> {
131        let handle = handle.clone();
132        Box::new(future::lazy(move || {
133            unix::Signal::with_handle(unix::libc::SIGINT, &handle)
134                .map(|x| Box::new(x.map(|_| ())) as Box<dyn Stream<Item = _, Error = _> + Send>)
135        }))
136    }
137
138    #[cfg(windows)]
139    fn ctrl_c_imp(handle: &Handle) -> IoFuture<IoStream<()>> {
140        let handle = handle.clone();
141        // Use lazy to ensure that `ctrl_c` gets called while on an event loop
142        Box::new(future::lazy(move || {
143            windows::Event::ctrl_c_handle(&handle)
144                .map(|x| Box::new(x) as Box<Stream<Item = _, Error = _> + Send>)
145        }))
146    }
147}
tokio_signal/lib.rs

tokio_signal/
lib.rs
