Refactor part 4

Cargo.toml

@@ -1,21 +1,34 @@
 [package]
-name = "socket2"
-version = "0.4.0-dev"
-authors = ["Alex Crichton <alex@alexcrichton.com>"]
-license = "MIT/Apache-2.0"
-readme = "README.md"
-repository = "https://github.com/alexcrichton/socket2-rs"
-homepage = "https://github.com/alexcrichton/socket2-rs"
+name          = "socket2"
+version       = "0.4.0-dev"
+authors       = ["Alex Crichton <alex@alexcrichton.com>"]
+license       = "MIT/Apache-2.0"
+readme        = "README.md"
+repository    = "https://github.com/rust-lang/socket2-rs"
+homepage      = "https://github.com/rust-lang/socket2-rs"
+documentation = "https://docs.rs/socket2"
 description = """
 Utilities for handling networking sockets with a maximal amount of configuration
 possible intended.
 """
-edition = "2018"
+keywords      = ["io", "socket", "network"]
+categories    = ["api-bindings", "network-programming"]
+edition       = "2018"
+include       = [
+  "Cargo.toml",
+  "LICENSE-APACHE",
+  "LICENSE-MIT",
+  "README.md",
+  "src/**/*.rs",
+]
 
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
+[package.metadata.playground]
+features = ["all"]
+
 [target."cfg(windows)".dependencies.winapi]
 version = "0.3.3"
 features = ["handleapi", "ws2def", "ws2ipdef", "ws2tcpip", "minwindef"]

src/socket.rs

@@ -41,6 +41,14 @@ use crate::{Domain, Protocol, SockAddr, Type};
 /// [`TcpStream`]: std::net::TcpStream
 /// [`UdpSocket`]: std::net::UdpSocket
 ///
+/// # Notes
+///
+/// Some methods that set options on `Socket` require two system calls to set
+/// there options without overwriting previously set options. We do this by
+/// first getting the current settings, applying the desired changes and than
+/// updating the settings. This means that the operation is **not** atomic. This
+/// can lead to a data race when two threads are changing options in parallel.
+///
 /// # Examples
 ///
 /// Creating a new socket setting all advisable flags.
@@ -58,19 +66,20 @@ use crate::{Domain, Protocol, SockAddr, Type};
 /// #[cfg(any(target_os = "android", target_os = "dragonfly", target_os = "freebsd", target_os = "linux", target_os = "netbsd", target_os = "openbsd"))]
 /// let ty = ty.cloexec();
 ///
+/// // On windows set `WSA_FLAG_NO_HANDLE_INHERIT`.
+/// #[cfg(windows)]
+/// let ty = ty.no_inherit();
+///
 /// let socket = Socket::new(domain, ty, Some(protocol))?;
 ///
 /// // On platforms that don't support `SOCK_CLOEXEC`, use `FD_CLOEXEC`.
 /// #[cfg(all(not(windows), not(any(target_os = "android", target_os = "dragonfly", target_os = "freebsd", target_os = "linux", target_os = "netbsd", target_os = "openbsd"))))]
-/// socket.set_cloexec()?;
+/// socket.set_cloexec(true)?;
 ///
 /// // On macOS and iOS set `NOSIGPIPE`.
 /// #[cfg(target_vendor = "apple")]
-/// socket.set_nosigpipe()?;
+/// socket.set_nosigpipe(true)?;
 ///
-/// // On windows set `HANDLE_FLAG_INHERIT`.
-/// #[cfg(windows)]
-/// socket.set_no_inherit()?;
 /// # drop(socket);
 /// # Ok(())
 /// # }
@@ -198,26 +207,44 @@ impl Socket {
         sys::accept(self.inner).map(|(inner, addr)| (Socket { inner }, addr))
     }
 
-    /// Returns the socket address of the local half of this TCP connection.
+    /// Returns the socket address of the local half of this socket.
+    ///
+    /// # Notes
+    ///
+    /// Depending on the OS this may return an error if the socket is not
+    /// [bound].
+    ///
+    /// [bound]: Socket::bind
     pub fn local_addr(&self) -> io::Result<SockAddr> {
-        self.inner().local_addr()
+        sys::getsockname(self.inner)
     }
 
-    /// Returns the socket address of the remote peer of this TCP connection.
+    /// Returns the socket address of the remote peer of this socket.
+    ///
+    /// # Notes
+    ///
+    /// This returns an error if the socket is not [`connect`ed].
+    ///
+    /// [`connect`ed]: Socket::connect
     pub fn peer_addr(&self) -> io::Result<SockAddr> {
-        self.inner().peer_addr()
+        sys::getpeername(self.inner)
     }
 
     /// Creates a new independently owned handle to the underlying socket.
     ///
-    /// The returned `TcpStream` is a reference to the same stream that this
-    /// object references. Both handles will read and write the same stream of
-    /// data, and options set on one stream will be propagated to the other
-    /// stream.
+    /// # Notes
+    ///
+    /// On Unix this uses `F_DUPFD_CLOEXEC` and thus sets the `FD_CLOEXEC` on
+    /// the returned socket.
+    ///
+    /// On Windows this uses `WSA_FLAG_NO_HANDLE_INHERIT` setting inheriting to
+    /// false.
+    ///
+    /// On Windows this can **not** be used function cannot be used on a
+    /// QOS-enabled socket, see
+    /// <https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaduplicatesocketw>.
     pub fn try_clone(&self) -> io::Result<Socket> {
-        self.inner()
-            .try_clone()
-            .map(|s| Socket { inner: s.inner() })
+        sys::try_clone(self.inner).map(|inner| Socket { inner })
     }
 
     /// Get the value of the `SO_ERROR` option on this socket.
@@ -226,23 +253,27 @@ impl Socket {
     /// the field in the process. This can be useful for checking errors between
     /// calls.
     pub fn take_error(&self) -> io::Result<Option<io::Error>> {
-        self.inner().take_error()
+        sys::take_error(self.inner)
     }
 
     /// Moves this TCP stream into or out of nonblocking mode.
     ///
-    /// On Unix this corresponds to calling fcntl, and on Windows this
-    /// corresponds to calling ioctlsocket.
+    /// # Notes
+    ///
+    /// On Unix this corresponds to calling `fcntl` (un)setting `O_NONBLOCK`.
+    ///
+    /// On Windows this corresponds to calling `ioctlsocket` (un)setting
+    /// `FIONBIO`.
     pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> {
-        self.inner().set_nonblocking(nonblocking)
+        sys::set_nonblocking(self.inner, nonblocking)
     }
 
     /// Shuts down the read, write, or both halves of this connection.
     ///
     /// This function will cause all pending and future I/O on the specified
     /// portions to return immediately with an appropriate value.
     pub fn shutdown(&self, how: Shutdown) -> io::Result<()> {
-        self.inner().shutdown(how)
+        sys::shutdown(self.inner, how)
     }
 
     /// Receives data on the socket from the remote address to which it is