net: improve from_std docs
#5332
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
hawkw
reviewed
Jan 6, 2023
tokio/src/net/tcp/socket.rs
Outdated
| @@ -666,6 +666,7 @@ impl TcpSocket { | |||
| /// socket must not have been connected prior to calling this function. This | |||
| /// function is typically used together with crates such as [`socket2`] to | |||
| /// configure socket options that are not available on `TcpSocket`. | |||
| /// It is left up to the user to set the socket in non-blocking mode. | |||
There was a problem hiding this comment.
I wonder if this ought to be explicitly marked as a Note or Warning so that it's very obvious to users? Perhaps the warning also should note what will happen if users don't do this?
There was a problem hiding this comment.
I applied your suggestion and created a more obvious section about this. I did the same with other docs containing the same warning and added missing examples.
Darksonn
added
T-docs
satakuma
changed the title
TcpSocket::from_std_stream docsfrom_std docs
satakuma
commented
Jan 10, 2023
| /// | ||
| /// #[tokio::main] | ||
| /// async fn main() -> Result<(), Box<dyn Error>> { | ||
| /// let tokio_socket = tokio::net::UnixDatagram::bind("127.0.0.1:0")?; |
There was a problem hiding this comment.
Some examples used IP addresses to bind Unix sockets.
Darksonn
reviewed
Jan 10, 2023
tokio/src/net/tcp/listener.rs
Outdated
| /// | ||
| /// The caller is responsible for ensuring that the listener is in | ||
| /// non-blocking mode. Otherwise all I/O operations on the listener | ||
| /// will block the thread, what can cause unexpected behavior. |
There was a problem hiding this comment.
Suggested change
| /// will block the thread, what can cause unexpected behavior. | |
| /// will block the thread, which will cause unexpected behavior. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Unlike documentation for other methods performing conversion from std types, docs for the
TcpSocket::from_std_streammethod do not warn about setting the socket in non-blocking mode.The attached example also doesn't set the socket in non-blocking mode.
Solution
This change adds a suitable comment in the docs and sets the socket in non-blocking mode in the example.