diff options
author | Carl Lerche <me@carllerche.com> | 2019-11-15 22:11:13 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-11-15 22:11:13 -0800 |
commit | 8a7e57786a5dca139f5b4261685e22991ded0859 (patch) | |
tree | b69d1c48f8a760a58fc7ccfe0376d9812a88d303 /tokio/src/signal/ctrl_c.rs | |
parent | 930679587ae42e4df3113159ccf33fb5923dd73a (diff) |
Limit `futures` dependency to `Stream` via feature flag (#1774)
In an effort to reach API stability, the `tokio` crate is shedding its
_public_ dependencies on crates that are either a) do not provide a
stable (1.0+) release with longevity guarantees or b) match the `tokio`
release cadence. Of course, implementing `std` traits fits the
requirements.
The on exception, for now, is the `Stream` trait found in `futures_core`.
It is expected that this trait will not change much and be moved into `std.
Since Tokio is not yet going reaching 1.0, I feel that it is acceptable to maintain
a dependency on this trait given how foundational it is.
Since the `Stream` implementation is optional, types that are logically
streams provide `async fn next_*` functions to obtain the next value.
Avoiding the `next()` name prevents fn conflicts with `StreamExt::next()`.
Additionally, some misc cleanup is also done:
- `tokio::io::io` -> `tokio::io::util`.
- `delay` -> `delay_until`.
- `Timeout::new` -> `timeout(...)`.
- `signal::ctrl_c()` returns a future instead of a stream.
- `{tcp,unix}::Incoming` is removed (due to lack of `Stream` trait).
- `time::Throttle` is removed (due to lack of `Stream` trait).
- Fix: `mpsc::UnboundedSender::send(&self)` (no more conflict with `Sink` fns).
Diffstat (limited to 'tokio/src/signal/ctrl_c.rs')
-rw-r--r-- | tokio/src/signal/ctrl_c.rs | 61 |
1 files changed, 25 insertions, 36 deletions
diff --git a/tokio/src/signal/ctrl_c.rs b/tokio/src/signal/ctrl_c.rs index f9dd4679..35ef2393 100644 --- a/tokio/src/signal/ctrl_c.rs +++ b/tokio/src/signal/ctrl_c.rs @@ -1,46 +1,35 @@ #[cfg(unix)] -use super::unix::{self as os_impl, Signal as Inner}; +use super::unix::{self as os_impl}; #[cfg(windows)] -use super::windows::{self as os_impl, Event as Inner}; +use super::windows::{self as os_impl}; -use futures_core::stream::Stream; use std::io; -use std::pin::Pin; -use std::task::{Context, Poll}; -/// Represents a stream which receives "ctrl-c" notifications sent to the process. +/// Completes when a "ctrl-c" notification is sent to the 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. +/// While signals are handled very differently between Unix and Windows, both +/// platforms support receiving a signal on "ctrl-c". This function provides a +/// portable API for receiving this notification. /// -/// 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. +/// Once the returned future is polled, a listener a listener is registered. The +/// future will complete on the first received `ctrl-c` **after** the initial +/// call to either `Future::poll` or `.await`. /// -/// Notably, a notification to this process notifies *all* streams listening to -/// this event. Moreover, the notifications **are coalesced** if they aren't processed -/// quickly enough. This means that if two notifications are received back-to-back, -/// then the stream may only receive one item about the two notifications. -#[must_use = "streams do nothing unless polled"] -#[derive(Debug)] -pub struct CtrlC { - inner: Inner, -} - -/// Creates a new stream which receives "ctrl-c" notifications sent to the -/// process. +/// # Examples /// -/// This function binds to the default reactor. -pub fn ctrl_c() -> io::Result<CtrlC> { - os_impl::ctrl_c().map(|inner| CtrlC { inner }) -} - -impl Stream for CtrlC { - type Item = (); - - fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> { - Pin::new(&mut self.inner).poll_next(cx) - } +/// ```rust,no_run +/// use tokio::signal; +/// +/// #[tokio::main] +/// async fn main() { +/// println!("waiting for ctrl-c"); +/// +/// signal::ctrl_c().await.expect("failed to listen for event"); +/// +/// println!("received ctrl-c event"); +/// } +/// ``` +pub async fn ctrl_c() -> io::Result<()> { + os_impl::ctrl_c()?.recv().await; + Ok(()) } |