@@ -721,16 +721,45 @@ impl UdpSocket {
721
721
722
722
/// Moves this UDP socket into or out of nonblocking mode.
723
723
///
724
- /// On Unix this corresponds to calling fcntl, and on Windows this
725
- /// corresponds to calling ioctlsocket.
724
+ /// This will result in `recv`, `recv_from`, `send`, and `send_to`
725
+ /// operations becoming nonblocking, i.e. immediately returning from their
726
+ /// calls. If the IO operation is successful, `Ok` is returned and no
727
+ /// further action is required. If the IO operation could not be completed
728
+ /// and needs to be retried, an error with kind
729
+ /// [`io::ErrorKind::WouldBlock`] is returned.
730
+ ///
731
+ /// On Unix platforms, calling this method corresponds to calling `fcntl`
732
+ /// `FIONBIO`. On Windows calling this method corresponds to calling
733
+ /// `ioctlsocket` `FIONBIO`.
734
+ ///
735
+ /// [`io::ErrorKind::WouldBlock`]: ../io/enum.ErrorKind.html#variant.WouldBlock
726
736
///
727
737
/// # Examples
728
738
///
739
+ /// Create a UDP socket bound to `127.0.0.1:7878` and read bytes in
740
+ /// nonblocking mode:
741
+ ///
729
742
/// ```no_run
743
+ /// use std::io;
730
744
/// use std::net::UdpSocket;
731
745
///
732
- /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
733
- /// socket.set_nonblocking(true).expect("set_nonblocking call failed");
746
+ /// let socket = UdpSocket::bind("127.0.0.1:7878").unwrap();
747
+ /// socket.set_nonblocking(true).unwrap();
748
+ ///
749
+ /// # fn wait_for_fd() { unimplemented!() }
750
+ /// let mut buf = [0; 10];
751
+ /// let (num_bytes_read, _) = loop {
752
+ /// match socket.recv_from(&mut buf) {
753
+ /// Ok(n) => break n,
754
+ /// Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
755
+ /// // wait until network socket is ready, typically implemented
756
+ /// // via platform-specific APIs such as epoll or IOCP
757
+ /// wait_for_fd();
758
+ /// }
759
+ /// Err(e) => panic!("encountered IO error: {}", e),
760
+ /// }
761
+ /// };
762
+ /// println!("bytes: {:?}", &buf[..num_bytes_read]);
734
763
/// ```
735
764
#[ stable( feature = "net2_mutators" , since = "1.9.0" ) ]
736
765
pub fn set_nonblocking ( & self , nonblocking : bool ) -> io:: Result < ( ) > {
0 commit comments