signal: refactor: Prefer the implicit handle passing used by tokio

src/lib.rs

@@ -27,12 +27,10 @@
 //!
 //! fn main() {
 //!     let mut core = Core::new().unwrap();
-//!     let handle = core.handle();
-//!     let handle = handle.new_tokio_handle();
 //!
 //!     // Create an infinite stream of "Ctrl+C" notifications. Each item received
 //!     // on this stream may represent multiple ctrl-c signals.
-//!     let ctrl_c = tokio_signal::ctrl_c(&handle).flatten_stream();
+//!     let ctrl_c = tokio_signal::ctrl_c().flatten_stream();
 //!
 //!     // Process each ctrl-c as it comes in
 //!     let prog = ctrl_c.for_each(|()| {
@@ -63,12 +61,10 @@
 //!
 //! fn main() {
 //!     let mut core = Core::new().unwrap();
-//!     let handle = core.handle();
-//!     let handle = handle.new_tokio_handle();
 //!
 //!     // Like the previous example, this is an infinite stream of signals
 //!     // being received, and signals may be coalesced while pending.
-//!     let stream = Signal::new(SIGHUP, &handle).flatten_stream();
+//!     let stream = Signal::new(SIGHUP).flatten_stream();
 //!
 //!     // Convert out stream into a future and block the program
 //!     core.run(stream.into_future()).ok().unwrap();
@@ -100,6 +96,21 @@ pub type IoFuture<T> = Box<Future<Item = T, Error = io::Error> + Send>;
 /// A stream whose error is `io::Error`
 pub type IoStream<T> = Box<Stream<Item = T, Error = io::Error> + Send>;
 
+/// Creates a stream which receives "ctrl-c" notifications sent to a process.
+///
+/// In general signals are handled very differently across Unix and Windows, but
+/// this is somewhat cross platform in terms of how it can be handled. A ctrl-c
+/// event to a console process can be represented as a stream for both Windows
+/// and Unix.
+///
+/// This function binds to the default event loop. Note that
+/// there are a number of caveats listening for signals, and you may wish to
+/// read up on the documentation in the `unix` or `windows` module to take a
+/// peek.
+pub fn ctrl_c() -> IoFuture<IoStream<()>> {
+    ctrl_c_handle(&Handle::current())
+}
+
 /// Creates a stream which receives "ctrl-c" notifications sent to a process.
 ///
 /// In general signals are handled very differently across Unix and Windows, but
@@ -112,14 +123,14 @@ pub type IoStream<T> = Box<Stream<Item = T, Error = io::Error> + Send>;
 /// there are a number of caveats listening for signals, and you may wish to
 /// read up on the documentation in the `unix` or `windows` module to take a
 /// peek.
-pub fn ctrl_c(handle: &Handle) -> IoFuture<IoStream<()>> {
+pub fn ctrl_c_handle(handle: &Handle) -> IoFuture<IoStream<()>> {
     return ctrl_c_imp(handle);
 
     #[cfg(unix)]
     fn ctrl_c_imp(handle: &Handle) -> IoFuture<IoStream<()>> {
         let handle = handle.clone();
         Box::new(future::lazy(move || {
-            unix::Signal::new(unix::libc::SIGINT, &handle)
+            unix::Signal::with_handle(unix::libc::SIGINT, &handle)
                 .map(|x| Box::new(x.map(|_| ())) as Box<Stream<Item = _, Error = _> + Send>)
         }))
     }
@@ -129,7 +140,7 @@ pub fn ctrl_c(handle: &Handle) -> IoFuture<IoStream<()>> {
         let handle = handle.clone();
         // Use lazy to ensure that `ctrl_c` gets called while on an event loop
         Box::new(future::lazy(move || {
-            windows::Event::ctrl_c(&handle)
+            windows::Event::ctrl_c_handle(&handle)
                 .map(|x| Box::new(x) as Box<Stream<Item = _, Error = _> + Send>)
         }))
     }

src/unix.rs

@@ -344,6 +344,28 @@ pub struct Signal {
 unsafe impl Send for Signal {}
 
 impl Signal {
+    /// Creates a new stream which will receive notifications when the current
+    /// process receives the signal `signal`.
+    ///
+    /// This function will create a new stream which binds to the default event
+    /// loop. This function returns a future which will
+    /// then resolve to the signal stream, if successful.
+    ///
+    /// The `Signal` stream is an infinite stream which will receive
+    /// notifications whenever a signal is received. More documentation can be
+    /// found on `Signal` itself, but to reiterate:
+    ///
+    /// * Signals may be coalesced beyond what the kernel already does.
+    /// * Once a signal handler is registered with the process the underlying
+    ///   libc signal handler is never unregistered.
+    ///
+    /// A `Signal` stream can be created for a particular signal number
+    /// multiple times. When a signal is received then all the associated
+    /// channels will receive the signal notification.
+    pub fn new(signal: c_int) -> IoFuture<Signal> {
+        Signal::with_handle(signal, &Handle::current())
+    }
+
     /// Creates a new stream which will receive notifications when the current
     /// process receives the signal `signal`.
     ///
@@ -362,7 +384,7 @@ impl Signal {
     /// A `Signal` stream can be created for a particular signal number
     /// multiple times. When a signal is received then all the associated
     /// channels will receive the signal notification.
-    pub fn new(signal: c_int, handle: &Handle) -> IoFuture<Signal> {
+    pub fn with_handle(signal: c_int, handle: &Handle) -> IoFuture<Signal> {
         let handle = handle.clone();
         Box::new(future::lazy(move || {
             let result = (|| {

src/windows.rs

@@ -84,7 +84,15 @@ impl Event {
     ///
     /// This function will register a handler via `SetConsoleCtrlHandler` and
     /// deliver notifications to the returned stream.
-    pub fn ctrl_c(handle: &Handle) -> IoFuture<Event> {
+    pub fn ctrl_c() -> IoFuture<Event> {
+        Event::ctrl_c_handle(&Handle::current())
+    }
+
+    /// Creates a new stream listening for the `CTRL_C_EVENT` events.
+    ///
+    /// This function will register a handler via `SetConsoleCtrlHandler` and
+    /// deliver notifications to the returned stream.
+    pub fn ctrl_c_handle(handle: &Handle) -> IoFuture<Event> {
         Event::new(CTRL_C_EVENT, handle)
     }
 
@@ -92,7 +100,15 @@ impl Event {
     ///
     /// This function will register a handler via `SetConsoleCtrlHandler` and
     /// deliver notifications to the returned stream.
-    pub fn ctrl_break(handle: &Handle) -> IoFuture<Event> {
+    pub fn ctrl_break() -> IoFuture<Event> {
+        Event::ctrl_break_handle(&Handle::current())
+    }
+
+    /// Creates a new stream listening for the `CTRL_BREAK_EVENT` events.
+    ///
+    /// This function will register a handler via `SetConsoleCtrlHandler` and
+    /// deliver notifications to the returned stream.
+    pub fn ctrl_break_handle(handle: &Handle) -> IoFuture<Event> {
         Event::new(CTRL_BREAK_EVENT, handle)
     }