From 9c688dbad2eadb013ed04422bbe90b7eba05d551 Mon Sep 17 00:00:00 2001 From: Eric McBride Date: Wed, 15 Feb 2023 19:52:33 -0600 Subject: [PATCH 1/3] Updated Documentation for Signals --- tokio/src/signal/unix.rs | 15 ++++++++------- tokio/src/signal/windows.rs | 33 ++++++++++++++++++++------------- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index e5345fdfccc..2aafc6c2199 100644 --- a/tokio/src/signal/unix.rs +++ b/tokio/src/signal/unix.rs @@ -292,8 +292,12 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { } } -/// A stream of events for receiving a particular type of OS signal. +/// An event for receiving a particular type of OS signal. /// +/// The signal can be turned into a `Stream` using [`SignalStream`]. +/// +/// [`SignalStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.SignalStream.html +/// /// In general signal handling on Unix is a pretty tricky topic, and this /// structure is no exception! There are some important limitations to keep in /// mind when using `Signal` streams: @@ -307,9 +311,6 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// Once `poll` has been called, however, a further signal is guaranteed to /// be yielded as an item. /// -/// Put another way, any element pulled off the returned stream corresponds to -/// *at least one* signal, but possibly more. -/// /// * Signal handling in general is relatively inefficient. Although some /// improvements are possible in this crate, it's recommended to not plan on /// having millions of signal channels open. @@ -345,11 +346,11 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// #[tokio::main] /// async fn main() -> Result<(), Box> { /// // An infinite stream of hangup signals. -/// let mut stream = signal(SignalKind::hangup())?; +/// let mut sig = signal(SignalKind::hangup())?; /// /// // Print whenever a HUP signal is received /// loop { -/// stream.recv().await; +/// sig.recv().await; /// println!("got signal HUP"); /// } /// } @@ -360,7 +361,7 @@ pub struct Signal { inner: RxFuture, } -/// Creates a new stream which will receive notifications when the current +/// Creates a new signal which will receive notifications when the current /// process receives the specified signal `kind`. /// /// This function will create a new stream which binds to the default reactor. diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index 730f95d0591..3e0c0e27082 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -22,7 +22,7 @@ pub(crate) use self::imp::{OsExtraData, OsStorage}; #[path = "windows/stub.rs"] mod imp; -/// Creates a new stream which receives "ctrl-c" notifications sent to the +/// Creates a new event which receives "ctrl-c" notifications sent to the /// process. /// /// # Examples @@ -50,14 +50,18 @@ pub fn ctrl_c() -> io::Result { }) } -/// Represents a stream which receives "ctrl-c" notifications sent to the process +/// Represents an event which receives "ctrl-c" notifications sent to the process /// via `SetConsoleCtrlHandler`. +/// +/// This event can be turned into a `Stream` using [`CtrlCStream`]. /// -/// A notification to this process notifies *all* streams listening for +/// [`CtrlCStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlCStream.html +/// +/// A notification to this process notifies *all* receivers for /// 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"] +/// then the receiver may only receive one item about the two notifications. +#[must_use = "events do nothing unless polled"] #[derive(Debug)] pub struct CtrlC { inner: RxFuture, @@ -66,7 +70,7 @@ pub struct CtrlC { impl CtrlC { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by the `RxFuture`. /// /// # Examples /// @@ -75,12 +79,11 @@ impl CtrlC { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { - /// // An infinite stream of CTRL-C events. - /// let mut stream = ctrl_c()?; + /// let mut signal = ctrl_c()?; /// /// // Print whenever a CTRL-C event is received. /// for countdown in (0..3).rev() { - /// stream.recv().await; + /// signal.recv().await; /// println!("got CTRL-C. {} more to exit", countdown); /// } /// @@ -94,7 +97,7 @@ impl CtrlC { /// Polls to receive the next signal notification event, outside of an /// `async` context. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received. /// /// # Examples /// @@ -127,11 +130,15 @@ impl CtrlC { /// Represents a stream which receives "ctrl-break" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// -/// A notification to this process notifies *all* streams listening for +/// This event can be turned into a `Stream` using [`CtrlBreakStream`]. +/// +/// [`CtrlBreakStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlBreakStream.html +/// +/// A notification to this process notifies *all* receivers for /// 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"] +/// then the receiver may only receive one item about the two notifications. +#[must_use = "events do nothing unless polled"] #[derive(Debug)] pub struct CtrlBreak { inner: RxFuture, From 480fbc255c2d48d01e211f48ba0e81fc67f950ec Mon Sep 17 00:00:00 2001 From: Eric McBride Date: Wed, 15 Feb 2023 19:57:21 -0600 Subject: [PATCH 2/3] Fix Rust Fmt --- tokio/src/signal/unix.rs | 2 +- tokio/src/signal/windows.rs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index 2aafc6c2199..3fb26cadb3b 100644 --- a/tokio/src/signal/unix.rs +++ b/tokio/src/signal/unix.rs @@ -297,7 +297,7 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// The signal can be turned into a `Stream` using [`SignalStream`]. /// /// [`SignalStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.SignalStream.html -/// +/// /// In general signal handling on Unix is a pretty tricky topic, and this /// structure is no exception! There are some important limitations to keep in /// mind when using `Signal` streams: diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index 3e0c0e27082..0d3e86cd5a5 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -52,11 +52,11 @@ pub fn ctrl_c() -> io::Result { /// Represents an event which receives "ctrl-c" notifications sent to the process /// via `SetConsoleCtrlHandler`. -/// +/// /// This event can be turned into a `Stream` using [`CtrlCStream`]. /// /// [`CtrlCStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlCStream.html -/// +/// /// A notification to this process notifies *all* receivers for /// 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, From a79022709616ab2141cecc508bf6067f235cef2e Mon Sep 17 00:00:00 2001 From: Eric McBride Date: Sun, 26 Feb 2023 13:15:58 -0600 Subject: [PATCH 3/3] update docstrings --- tokio/src/signal/unix.rs | 9 ++- tokio/src/signal/windows.rs | 120 ++++++++++++++++++------------------ 2 files changed, 66 insertions(+), 63 deletions(-) diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index 3fb26cadb3b..ae5c13085e9 100644 --- a/tokio/src/signal/unix.rs +++ b/tokio/src/signal/unix.rs @@ -292,9 +292,9 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { } } -/// An event for receiving a particular type of OS signal. +/// An listener for receiving a particular type of OS signal. /// -/// The signal can be turned into a `Stream` using [`SignalStream`]. +/// The listener can be turned into a `Stream` using [`SignalStream`]. /// /// [`SignalStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.SignalStream.html /// @@ -311,6 +311,9 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> { /// Once `poll` has been called, however, a further signal is guaranteed to /// be yielded as an item. /// +/// Put another way, any element pulled off the returned listener corresponds to +/// *at least one* signal, but possibly more. +/// /// * Signal handling in general is relatively inefficient. Although some /// improvements are possible in this crate, it's recommended to not plan on /// having millions of signal channels open. @@ -361,7 +364,7 @@ pub struct Signal { inner: RxFuture, } -/// Creates a new signal which will receive notifications when the current +/// Creates a new listener which will receive notifications when the current /// process receives the specified signal `kind`. /// /// This function will create a new stream which binds to the default reactor. diff --git a/tokio/src/signal/windows.rs b/tokio/src/signal/windows.rs index 0d3e86cd5a5..2f70f98b15a 100644 --- a/tokio/src/signal/windows.rs +++ b/tokio/src/signal/windows.rs @@ -22,7 +22,7 @@ pub(crate) use self::imp::{OsExtraData, OsStorage}; #[path = "windows/stub.rs"] mod imp; -/// Creates a new event which receives "ctrl-c" notifications sent to the +/// Creates a new listener which receives "ctrl-c" notifications sent to the /// process. /// /// # Examples @@ -32,12 +32,12 @@ mod imp; /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { -/// // An infinite stream of CTRL-C events. -/// let mut stream = ctrl_c()?; +/// // A listener of CTRL-C events. +/// let mut signal = ctrl_c()?; /// /// // Print whenever a CTRL-C event is received. /// for countdown in (0..3).rev() { -/// stream.recv().await; +/// signal.recv().await; /// println!("got CTRL-C. {} more to exit", countdown); /// } /// @@ -50,7 +50,7 @@ pub fn ctrl_c() -> io::Result { }) } -/// Represents an event which receives "ctrl-c" notifications sent to the process +/// Represents a listener which receives "ctrl-c" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// /// This event can be turned into a `Stream` using [`CtrlCStream`]. @@ -60,8 +60,8 @@ pub fn ctrl_c() -> io::Result { /// A notification to this process notifies *all* receivers for /// 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 receiver may only receive one item about the two notifications. -#[must_use = "events do nothing unless polled"] +/// then the listener may only receive one item about the two notifications. +#[must_use = "listeners do nothing unless polled"] #[derive(Debug)] pub struct CtrlC { inner: RxFuture, @@ -70,7 +70,7 @@ pub struct CtrlC { impl CtrlC { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by the `RxFuture`. + /// `None` is returned if no more events can be received by the listener. /// /// # Examples /// @@ -127,18 +127,18 @@ impl CtrlC { } } -/// Represents a stream which receives "ctrl-break" notifications sent to the process +/// Represents a listener which receives "ctrl-break" notifications sent to the process /// via `SetConsoleCtrlHandler`. /// -/// This event can be turned into a `Stream` using [`CtrlBreakStream`]. +/// This listener can be turned into a `Stream` using [`CtrlBreakStream`]. /// /// [`CtrlBreakStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlBreakStream.html /// /// A notification to this process notifies *all* receivers for /// 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 receiver may only receive one item about the two notifications. -#[must_use = "events do nothing unless polled"] +/// then the listener may only receive one item about the two notifications. +#[must_use = "listeners do nothing unless polled"] #[derive(Debug)] pub struct CtrlBreak { inner: RxFuture, @@ -147,7 +147,7 @@ pub struct CtrlBreak { impl CtrlBreak { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -156,12 +156,12 @@ impl CtrlBreak { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { - /// // An infinite stream of CTRL-BREAK events. - /// let mut stream = ctrl_break()?; + /// // A listener of CTRL-BREAK events. + /// let mut signal = ctrl_break()?; /// /// // Print whenever a CTRL-BREAK event is received. /// loop { - /// stream.recv().await; + /// signal.recv().await; /// println!("got signal CTRL-BREAK"); /// } /// } @@ -173,7 +173,7 @@ impl CtrlBreak { /// Polls to receive the next signal notification event, outside of an /// `async` context. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -203,7 +203,7 @@ impl CtrlBreak { } } -/// Creates a new stream which receives "ctrl-break" notifications sent to the +/// Creates a new listener which receives "ctrl-break" notifications sent to the /// process. /// /// # Examples @@ -213,12 +213,12 @@ impl CtrlBreak { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { -/// // An infinite stream of CTRL-BREAK events. -/// let mut stream = ctrl_break()?; +/// // A listener of CTRL-BREAK events. +/// let mut signal = ctrl_break()?; /// /// // Print whenever a CTRL-BREAK event is received. /// loop { -/// stream.recv().await; +/// signal.recv().await; /// println!("got signal CTRL-BREAK"); /// } /// } @@ -229,7 +229,7 @@ pub fn ctrl_break() -> io::Result { }) } -/// Creates a new stream which receives "ctrl-close" notifications sent to the +/// Creates a new listener which receives "ctrl-close" notifications sent to the /// process. /// /// # Examples @@ -239,12 +239,12 @@ pub fn ctrl_break() -> io::Result { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { -/// // An infinite stream of CTRL-CLOSE events. -/// let mut stream = ctrl_close()?; +/// // A listener of CTRL-CLOSE events. +/// let mut signal = ctrl_close()?; /// /// // Print whenever a CTRL-CLOSE event is received. /// for countdown in (0..3).rev() { -/// stream.recv().await; +/// signal.recv().await; /// println!("got CTRL-CLOSE. {} more to exit", countdown); /// } /// @@ -257,14 +257,14 @@ pub fn ctrl_close() -> io::Result { }) } -/// Represents a stream which receives "ctrl-close" notitifications sent to the process +/// Represents a listener which receives "ctrl-close" notitifications sent to the process /// via 'SetConsoleCtrlHandler'. /// -/// A notification to this process notifies *all* streams listening for +/// A notification to this process notifies *all* listeners listening for /// 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"] +/// then the listener may only receive one item about the two notifications. +#[must_use = "listeners do nothing unless polled"] #[derive(Debug)] pub struct CtrlClose { inner: RxFuture, @@ -273,7 +273,7 @@ pub struct CtrlClose { impl CtrlClose { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -282,11 +282,11 @@ impl CtrlClose { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { - /// // An infinite stream of CTRL-CLOSE events. - /// let mut stream = ctrl_close()?; + /// // A listener of CTRL-CLOSE events. + /// let mut signal = ctrl_close()?; /// /// // Print whenever a CTRL-CLOSE event is received. - /// stream.recv().await; + /// signal.recv().await; /// println!("got CTRL-CLOSE. Cleaning up before exiting"); /// /// Ok(()) @@ -299,7 +299,7 @@ impl CtrlClose { /// Polls to receive the next signal notification event, outside of an /// `async` context. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -329,7 +329,7 @@ impl CtrlClose { } } -/// Creates a new stream which receives "ctrl-shutdown" notifications sent to the +/// Creates a new listener which receives "ctrl-shutdown" notifications sent to the /// process. /// /// # Examples @@ -339,10 +339,10 @@ impl CtrlClose { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { -/// // An infinite stream of CTRL-SHUTDOWN events. -/// let mut stream = ctrl_shutdown()?; +/// // A listener of CTRL-SHUTDOWN events. +/// let mut signal = ctrl_shutdown()?; /// -/// stream.recv().await; +/// signal.recv().await; /// println!("got CTRL-SHUTDOWN. Cleaning up before exiting"); /// /// Ok(()) @@ -354,14 +354,14 @@ pub fn ctrl_shutdown() -> io::Result { }) } -/// Represents a stream which receives "ctrl-shutdown" notitifications sent to the process +/// Represents a listener which receives "ctrl-shutdown" notitifications sent to the process /// via 'SetConsoleCtrlHandler'. /// -/// A notification to this process notifies *all* streams listening for +/// A notification to this process notifies *all* listeners listening for /// 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"] +/// then the listener may only receive one item about the two notifications. +#[must_use = "listeners do nothing unless polled"] #[derive(Debug)] pub struct CtrlShutdown { inner: RxFuture, @@ -370,7 +370,7 @@ pub struct CtrlShutdown { impl CtrlShutdown { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -379,11 +379,11 @@ impl CtrlShutdown { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { - /// // An infinite stream of CTRL-SHUTDOWN events. - /// let mut stream = ctrl_shutdown()?; + /// // A listener of CTRL-SHUTDOWN events. + /// let mut signal = ctrl_shutdown()?; /// /// // Print whenever a CTRL-SHUTDOWN event is received. - /// stream.recv().await; + /// signal.recv().await; /// println!("got CTRL-SHUTDOWN. Cleaning up before exiting"); /// /// Ok(()) @@ -396,7 +396,7 @@ impl CtrlShutdown { /// Polls to receive the next signal notification event, outside of an /// `async` context. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -426,7 +426,7 @@ impl CtrlShutdown { } } -/// Creates a new stream which receives "ctrl-logoff" notifications sent to the +/// Creates a new listener which receives "ctrl-logoff" notifications sent to the /// process. /// /// # Examples @@ -436,10 +436,10 @@ impl CtrlShutdown { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { -/// // An infinite stream of CTRL-LOGOFF events. -/// let mut stream = ctrl_logoff()?; +/// // A listener of CTRL-LOGOFF events. +/// let mut signal = ctrl_logoff()?; /// -/// stream.recv().await; +/// signal.recv().await; /// println!("got CTRL-LOGOFF. Cleaning up before exiting"); /// /// Ok(()) @@ -451,14 +451,14 @@ pub fn ctrl_logoff() -> io::Result { }) } -/// Represents a stream which receives "ctrl-logoff" notitifications sent to the process +/// Represents a listener which receives "ctrl-logoff" notitifications sent to the process /// via 'SetConsoleCtrlHandler'. /// -/// A notification to this process notifies *all* streams listening for +/// A notification to this process notifies *all* listeners listening for /// 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"] +/// then the listener may only receive one item about the two notifications. +#[must_use = "listeners do nothing unless polled"] #[derive(Debug)] pub struct CtrlLogoff { inner: RxFuture, @@ -467,7 +467,7 @@ pub struct CtrlLogoff { impl CtrlLogoff { /// Receives the next signal notification event. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples /// @@ -476,11 +476,11 @@ impl CtrlLogoff { /// /// #[tokio::main] /// async fn main() -> Result<(), Box> { - /// // An infinite stream of CTRL-LOGOFF events. - /// let mut stream = ctrl_logoff()?; + /// // An listener of CTRL-LOGOFF events. + /// let mut signal = ctrl_logoff()?; /// /// // Print whenever a CTRL-LOGOFF event is received. - /// stream.recv().await; + /// signal.recv().await; /// println!("got CTRL-LOGOFF. Cleaning up before exiting"); /// /// Ok(()) @@ -493,7 +493,7 @@ impl CtrlLogoff { /// Polls to receive the next signal notification event, outside of an /// `async` context. /// - /// `None` is returned if no more events can be received by this stream. + /// `None` is returned if no more events can be received by this listener. /// /// # Examples ///