From 04f27f01cb25f63d25e07ed0a48a8ac4135371c8 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 22 Oct 2017 09:27:26 -0400 Subject: [PATCH] Improve docs for UdpSocket::set_nonblocking. Closes https://github.com/rust-lang/rust/issues/44050. --- src/libstd/net/udp.rs | 37 +++++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index 870d11298fe..84ceaa65951 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -721,16 +721,45 @@ impl UdpSocket { /// Moves this UDP socket into or out of nonblocking mode. /// - /// On Unix this corresponds to calling fcntl, and on Windows this - /// corresponds to calling ioctlsocket. + /// This will result in `recv`, `recv_from`, `send`, and `send_to` + /// 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`. + /// + /// [`io::ErrorKind::WouldBlock`]: ../io/enum.ErrorKind.html#variant.WouldBlock /// /// # Examples /// + /// Create a UDP socket bound to `127.0.0.1:7878` and read bytes in + /// nonblocking mode: + /// /// ```no_run + /// use std::io; /// use std::net::UdpSocket; /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_nonblocking(true).expect("set_nonblocking call failed"); + /// let socket = UdpSocket::bind("127.0.0.1:7878").unwrap(); + /// socket.set_nonblocking(true).unwrap(); + /// + /// # fn wait_for_fd() { unimplemented!() } + /// let mut buf = [0; 10]; + /// let (num_bytes_read, _) = loop { + /// match socket.recv_from(&mut buf) { + /// Ok(n) => break n, + /// 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[..num_bytes_read]); /// ``` #[stable(feature = "net2_mutators", since = "1.9.0")] pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {