Change:
These docs currently just refer to POSIX and Win32 APIs, without explaining what they do (or even linking to docs for the corresponding platform APIs): I'd like to have more information here about how other TcpStream methods change their behavior after calling this, possibly with an example.
I'd be happy to make the changes, though I actually don't know what the effects of using are. If anyone knows, would be great if you could share
This will result in , , and operations not blocking, i.e. immediately returning from their calls. If the IO operation could be completed correctly, no further action is required. If it could not, or are returned on Unix platforms and is returned on Windows. All of these are mapped to , so on the Rust side of the things, you can simply check whether the return value of the IO operation has kind , and in this case take the appropriate action.
Opened a PR for TCP methods: I'll do another PR for the UDP instance of this in a follow-up PR when I have some more time.

Discussion:
/// Moves this TCP stream into or out of nonblocking mode. /// <del> /// On Unix this corresponds to calling fcntl, and on Windows this /// corresponds to calling ioctlsocket. </del> <ins> /// This will result in `read`, `write`, `recv` and `send` operations /// becoming nonblocking, i.e. immediately returning from their calls. /// If the IO operation is successful, `Ok` is returned and no further /// action is required. If the IO operation could not be completed and needs /// to be retried, an error with kind [`io::ErrorKind::WouldBlock`] is /// returned. /// /// On Unix platforms, calling this method corresponds to calling `fcntl` /// `FIONBIO`. On Windows calling this method corresponds to calling /// `ioctlsocket` `FIONBIO`. </ins> /// /// # Examples /// <ins> /// Reading bytes from a TCP stream in non-blocking mode: /// </ins> /// ```no_run <ins> /// use std::io::{self, Read}; </ins> /// use std::net::TcpStream; /// <del> /// let stream = TcpStream::connect("127.0.0.1:8080") ///                        .expect("Couldn't connect to the server..."); </del> <ins> /// let mut stream = TcpStream::connect("127.0.0.1:7878") ///     .expect("Couldn't connect to the server..."); </ins> /// stream.set_nonblocking(true).expect("set_nonblocking call failed"); <ins> /// /// # fn wait_for_fd() { unimplemented!() } /// let mut buf = vec![]; /// loop { ///     match stream.read_to_end(&mut buf) { ///         Ok(_) => break, ///         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => { ///             // wait until network socket is ready, typically implemented ///             // via platform-specific APIs such as epoll or IOCP ///             wait_for_fd(); ///         } ///         Err(e) => panic!("encountered IO error: {}", e), ///     }; /// }; /// println!("bytes: {:?}", buf); </ins> /// ``` <ins> /// /// [`io::ErrorKind::WouldBlock`]: ../io/enum.ErrorKind.html#variant.WouldBlock </ins> #[stable(feature = "net2_mutators", since = "1.9.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { self.0.set_nonblocking(nonblocking)

/// Moves this TCP stream into or out of nonblocking mode. /// <del> /// On Unix this corresponds to calling fcntl, and on Windows this /// corresponds to calling ioctlsocket. </del> <ins> /// This will result in the `accept` operation becoming nonblocking, /// i.e. immediately returning from their calls. If the IO operation is /// successful, `Ok` is returned and no further action is required. If the /// IO operation could not be completed and needs to be retried, an error /// with kind [`io::ErrorKind::WouldBlock`] is returned. /// /// On Unix platforms, calling this method corresponds to calling `fcntl` /// `FIONBIO`. On Windows calling this method corresponds to calling /// `ioctlsocket` `FIONBIO`. </ins> /// /// # Examples /// <ins> /// Bind a TCP listener to an address, listen for connections, and read /// bytes in nonblocking mode: /// </ins> /// ```no_run <ins> /// use std::io; </ins> /// use std::net::TcpListener; /// <del> /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); </del> <ins> /// let listener = TcpListener::bind("127.0.0.1:7878").unwrap(); </ins> /// listener.set_nonblocking(true).expect("Cannot set non-blocking"); <ins> /// /// # fn wait_for_fd() { unimplemented!() } /// # fn handle_connection(stream: std::net::TcpStream) { unimplemented!() } /// for stream in listener.incoming() { ///     match stream { ///         Ok(s) => { ///             // do something with the TcpStream ///             handle_connection(s); ///         } ///         Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => { ///             // wait until network socket is ready, typically implemented ///             // via platform-specific APIs such as epoll or IOCP ///             wait_for_fd(); ///             continue; ///         } ///         Err(e) => panic!("encountered IO error: {}", e), ///     } /// } </ins> /// ``` <ins> /// /// [`io::ErrorKind::WouldBlock`]: ../io/enum.ErrorKind.html#variant.WouldBlock </ins> #[stable(feature = "net2_mutators", since = "1.9.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { self.0.set_nonblocking(nonblocking)