Updated Documentation for Signals #5459

ericmcbride · 2023-02-16T01:54:20Z

Motivation

Resolve Issue #5430 and to update the documentation to point to how to create Streams, using the Tokio-stream crate

Solution

Update documentation for Windows + Unix signals to not include "streams" since they do not implement the Stream Trait, and give a link to the acceptable Tokio-stream wrapper.

Darksonn · 2023-02-17T10:53:15Z

tokio/src/signal/windows.rs

-    /// `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`.


This should say "the CtrlC". The RxFuture type is an internal implementation detail.

or "this listener"

brody4hire

In general I would favor using "listener" rather than "event". The term "event" sounds to me like something that we would expect to receive or receive from only once.

I think we should update the documentation for some other Windows signal listener types as well:

CtrlBreak
CtrlClose
ctrl_shutdown
ctrl_logoff

brody4hire · 2023-02-17T17:32:29Z

tokio/src/signal/unix.rs

+/// An event for receiving a particular type of OS signal.
+///
+/// The signal can be turned into a `Stream` using [`SignalStream`].


Suggested change

/// An event for receiving a particular type of OS signal.

///

/// The signal can be turned into a `Stream` using [`SignalStream`].

/// A listener for receiving a particular type of OS signal.

///

/// The listener can be turned into a `Stream` using [`SignalStream`].

brody4hire · 2023-02-17T17:32:48Z

tokio/src/signal/unix.rs

@@ -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


Suggested change

/// Creates a new signal which will receive notifications when the current

/// Creates a new listener which will receive notifications when the current

brody4hire · 2023-02-17T17:45:43Z

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


Suggested change

/// Creates a new event which receives "ctrl-c" notifications sent to the

/// Creates a new listener which receives "ctrl-c" notifications sent to the

brody4hire · 2023-02-17T17:46:00Z

tokio/src/signal/windows.rs

@@ -50,14 +50,18 @@ pub fn ctrl_c() -> io::Result<CtrlC> {
    })
 }

-/// Represents a stream which receives "ctrl-c" notifications sent to the process
+/// Represents an event which receives "ctrl-c" notifications sent to the process


Suggested change

/// Represents an event which receives "ctrl-c" notifications sent to the process

/// Represents a listener which receives "ctrl-c" notifications sent to the process

brody4hire · 2023-02-17T17:48:42Z

tokio/src/signal/unix.rs

-///   Put another way, any element pulled off the returned stream corresponds to
-///   *at least one* signal, but possibly more.
-///


-/// Put another way, any element pulled off the returned stream corresponds to -/// *at least one* signal, but possibly more. +/// Put another way, any element pulled off the returned listener corresponds to +/// *at least one* signal, but possibly more.

brody4hire · 2023-02-17T17:49:07Z

tokio/src/signal/windows.rs

 /// via `SetConsoleCtrlHandler`.
 ///
-/// A notification to this process notifies *all* streams listening for
+/// This event can be turned into a `Stream` using [`CtrlCStream`].


Suggested change

/// This event can be turned into a `Stream` using [`CtrlCStream`].

/// This listener can be turned into a `Stream` using [`CtrlCStream`].

brody4hire · 2023-02-17T17:50:47Z

tokio/src/signal/windows.rs

-/// 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"]


I would favor using "listener" on these 2 lines as well.

brody4hire · 2023-02-17T17:51:28Z

tokio/src/signal/windows.rs

-    /// `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`.


or "this listener"

brody4hire · 2023-02-17T17:52:02Z

tokio/src/signal/windows.rs

@@ -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`].


Suggested change

/// This event can be turned into a `Stream` using [`CtrlBreakStream`].

/// This listener can be turned into a `Stream` using [`CtrlBreakStream`].

ericmcbride · 2023-02-17T18:07:50Z

I'll update these suggestions I wanted to do that on my initial go, but for some reason, event stuck with me.

Darksonn

Thank you.

brody4hire · 2023-02-26T19:26:20Z

👍 👍 - much better from an outsider perspective

# 1.26.0 (March 1st, 2023) ### Fixed - sync: don't leak tracing spans in mutex guards ([#5469]) - sync: drop wakers after unlocking the mutex in Notify ([#5471]) - sync: drop wakers outside lock in semaphore ([#5475]) - macros: fix empty `join!` and `try_join!` ([#5504]) ### Added - fs: add `fs::try_exists` ([#4299]) - net: add types for named unix pipes ([#5351]) - sync: add `MappedOwnedMutexGuard` ([#5474]) ### Documented - task: clarify what happens to spawned work during runtime shutdown ([#5394]) - task: clarify `process::Command` docs (#5406) ([#5413]) - sync: add doc aliases for `blocking_*` methods ([#5448]) - task: fix wording with 'unsend' ([#5452]) - signal: updated Documentation for Signals ([#5459]) - sync: fix docs for Send/Sync bounds in broadcast ([#5480]) - io: improve AsyncFd example ([#5481]) - tokio: document supported platforms ([#5483]) - runtime: document the nature of the main future ([#5494]) - sync: document drop behavior for channels ([#5497]) - time: document immediate completion guarantee for timeouts ([#5509]) - runtime: remove extra period in docs ([#5511]) ### Changed - net: use Message Read Mode for named pipes ([#5350]) - chore: update windows-sys to 0.45 ([#5386]) - sync: mark lock guards with `#[clippy::has_significant_drop]` ([#5422]) - sync: reduce contention in watch channel ([#5464]) - time: remove cache padding in timer entries ([#5468]) - time: Improve `Instant::now()` perf with test-util ([#5513]) ### Internal Changes - tests: port proptest fuzz harnesses to use cargo-fuzz ([#5392]) - time: don't store deadline twice in sleep entries ([#5410]) - rt: remove Arc from Clock ([#5434]) - sync: make `notify_waiters` calls atomic ([#5458]) - net: refactor named pipe builders to not use bitfields ([#5477]) - io: use `poll_fn` in `copy_bidirectional` ([#5486]) - fs: add more tests for filesystem functionality ([#5493]) - net: fix test compilation failure ([#5506]) - io: ignore SplitByUtf8BoundaryIfWindows test on miri ([#5507]) ### Unstable - metrics: add a new metric for budget exhaustion yields ([#5517]) [#4299]: #4299 [#5350]: #5350 [#5351]: #5351 [#5386]: #5386 [#5392]: #5392 [#5394]: #5394 [#5410]: #5410 [#5413]: #5413 [#5422]: #5422 [#5434]: #5434 [#5448]: #5448 [#5452]: #5452 [#5458]: #5458 [#5459]: #5459 [#5464]: #5464 [#5468]: #5468 [#5469]: #5469 [#5471]: #5471 [#5474]: #5474 [#5475]: #5475 [#5477]: #5477 [#5480]: #5480 [#5481]: #5481 [#5483]: #5483 [#5486]: #5486 [#5493]: #5493 [#5494]: #5494 [#5497]: #5497 [#5504]: #5504 [#5506]: #5506 [#5507]: #5507 [#5509]: #5509 [#5511]: #5511 [#5513]: #5513 [#5517]: #5517

# 1.26.0 (March 1st, 2023) ### Fixed - macros: fix empty `join!` and `try_join!` ([#5504]) - sync: don't leak tracing spans in mutex guards ([#5469]) - sync: drop wakers after unlocking the mutex in Notify ([#5471]) - sync: drop wakers outside lock in semaphore ([#5475]) ### Added - fs: add `fs::try_exists` ([#4299]) - net: add types for named unix pipes ([#5351]) - sync: add `MappedOwnedMutexGuard` ([#5474]) ### Changed - chore: update windows-sys to 0.45 ([#5386]) - net: use Message Read Mode for named pipes ([#5350]) - sync: mark lock guards with `#[clippy::has_significant_drop]` ([#5422]) - sync: reduce contention in watch channel ([#5464]) - time: remove cache padding in timer entries ([#5468]) - time: Improve `Instant::now()` perf with test-util ([#5513]) ### Internal Changes - io: use `poll_fn` in `copy_bidirectional` ([#5486]) - net: refactor named pipe builders to not use bitfields ([#5477]) - rt: remove Arc from Clock ([#5434]) - sync: make `notify_waiters` calls atomic ([#5458]) - time: don't store deadline twice in sleep entries ([#5410]) ### Unstable - metrics: add a new metric for budget exhaustion yields ([#5517]) ### Documented - io: improve AsyncFd example ([#5481]) - runtime: document the nature of the main future ([#5494]) - runtime: remove extra period in docs ([#5511]) - signal: updated Documentation for Signals ([#5459]) - sync: add doc aliases for `blocking_*` methods ([#5448]) - sync: fix docs for Send/Sync bounds in broadcast ([#5480]) - sync: document drop behavior for channels ([#5497]) - task: clarify what happens to spawned work during runtime shutdown ([#5394]) - task: clarify `process::Command` docs ([#5413]) - task: fix wording with 'unsend' ([#5452]) - time: document immediate completion guarantee for timeouts ([#5509]) - tokio: document supported platforms ([#5483]) [#4299]: #4299 [#5350]: #5350 [#5351]: #5351 [#5386]: #5386 [#5394]: #5394 [#5410]: #5410 [#5413]: #5413 [#5422]: #5422 [#5434]: #5434 [#5448]: #5448 [#5452]: #5452 [#5458]: #5458 [#5459]: #5459 [#5464]: #5464 [#5468]: #5468 [#5469]: #5469 [#5471]: #5471 [#5474]: #5474 [#5475]: #5475 [#5477]: #5477 [#5480]: #5480 [#5481]: #5481 [#5483]: #5483 [#5486]: #5486 [#5494]: #5494 [#5497]: #5497 [#5504]: #5504 [#5509]: #5509 [#5511]: #5511 [#5513]: #5513 [#5517]: #5517

ericmcbride added 2 commits February 15, 2023 19:52

Updated Documentation for Signals

Verified

This commit was signed with the committer’s verified signature.

avedmala Abhinav Vedmala

GPG key ID: D4B49314FC2D83F0

Verified
Learn about vigilant mode

9c688db

Fix Rust Fmt

Verified

This commit was signed with the committer’s verified signature.

avedmala Abhinav Vedmala

GPG key ID: D4B49314FC2D83F0

Verified
Learn about vigilant mode

480fbc2

Darksonn reviewed Feb 17, 2023

View reviewed changes

Darksonn added T-docs A-tokio M-signal labels Feb 17, 2023

brody4hire reviewed Feb 17, 2023

View reviewed changes

update docstrings

Verified

This commit was signed with the committer’s verified signature.

avedmala Abhinav Vedmala

GPG key ID: D4B49314FC2D83F0

Verified
Learn about vigilant mode

a790227

ericmcbride requested a review from brody4hire February 26, 2023 19:16

Darksonn approved these changes Feb 26, 2023

View reviewed changes

Darksonn enabled auto-merge (squash) February 26, 2023 19:19

Darksonn merged commit e23c6f3 into tokio-rs:master Feb 26, 2023

Noah-Kennedy mentioned this pull request Mar 1, 2023

chore: prepare for Tokio v1.26.0 release #5521

Merged

dependabot bot mentioned this pull request Apr 16, 2025

Bump the cargo group across 1 directory with 7 updates hamed210/solana-security-txt#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated Documentation for Signals #5459

Updated Documentation for Signals #5459

ericmcbride commented Feb 16, 2023

Darksonn Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire left a comment

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

brody4hire Feb 17, 2023

ericmcbride commented Feb 17, 2023

Darksonn left a comment

brody4hire commented Feb 26, 2023

		/// `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`.

	/// Creates a new signal which will receive notifications when the current
	/// Creates a new listener which will receive notifications when the current

	/// Creates a new event which receives "ctrl-c" notifications sent to the
	/// Creates a new listener which receives "ctrl-c" notifications sent to the

	/// Represents an event which receives "ctrl-c" notifications sent to the process
	/// Represents a listener which receives "ctrl-c" notifications sent to the process

	/// This event can be turned into a `Stream` using [`CtrlCStream`].
	/// This listener can be turned into a `Stream` using [`CtrlCStream`].

Updated Documentation for Signals #5459

Updated Documentation for Signals #5459

Conversation

ericmcbride commented Feb 16, 2023

Motivation

Solution

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brody4hire left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericmcbride commented Feb 17, 2023

Darksonn left a comment

Choose a reason for hiding this comment

brody4hire commented Feb 26, 2023