Repository: tokio-rs/tokio
File: tokio/src/net/tcp/stream.rs (Rust)

Code before:
        ///
        /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
        /// let stream = TcpStream::connect("127.0.0.1:8080").await?;
        ///
        /// println!("{:?}", stream.linger()?);
        /// # Ok(())
        /// # }
        /// ```
        pub fn linger(&self) -> io::Result<Option<Duration>> {
            socket2::SockRef::from(self).linger()
        }

        /// Sets the linger duration of this socket by setting the `SO_LINGER` option.
        ///
        /// This option controls the action taken when a stream has unsent messages and the stream is
        /// closed. If `SO_LINGER` is set, the system shall block the process until it can transmit the
        /// data or until the time expires.
        ///
        /// If `SO_LINGER` is not specified, and the stream is closed, the system handles the call in a
        /// way that allows the process to continue as quickly as possible.
        ///
        /// This option is deprecated because setting `SO_LINGER` on a socket used with Tokio is
        /// always incorrect as it leads to blocking the thread when the socket is closed. For more
        /// details, please see:
        ///
        /// > Volumes of communications have been devoted the the intricacies of `SO_LINGER` versus
        /// > non-blocking (`O_NONBLOCK`) sockets. From what I can tell, the final word is: don't
        /// > do it. Rely on the `shutdown()`-followed-by-`read()`-eof technique instead.
        /// >
        /// > From [The ultimate `SO_LINGER` page, or: why is my tcp not reliable](https://blog.netherlabs.nl/articles/2009/01/18/the-ultimate-so_linger-page-or-why-is-my-tcp-not-reliable)
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # #![allow(deprecated)]
        /// use tokio::net::TcpStream;
        ///
        /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
        /// let stream = TcpStream::connect("127.0.0.1:8080").await?;
        ///
        /// stream.set_linger(None)?;
        /// # Ok(())
        /// # }
        /// ```
        #[deprecated = "`SO_LINGER` causes the socket to block the thread on drop"]
        pub fn set_linger(&self, dur: Option<Duration>) -> io::Result<()> {
            socket2::SockRef::from(self).set_linger(dur)
        }
    }

    /// Gets the value of the `IP_TTL` option for this socket.

Review comment (suggestion):
```suggestion
        /// > Volumes of communications have been devoted the intricacies of `SO_LINGER` versus
```

Code after:
        ///
        /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
        /// let stream = TcpStream::connect("127.0.0.1:8080").await?;
        ///
        /// println!("{:?}", stream.linger()?);
        /// # Ok(())
        /// # }
        /// ```
        pub fn linger(&self) -> io::Result<Option<Duration>> {
            socket2::SockRef::from(self).linger()
        }

        /// Sets the linger duration of this socket by setting the `SO_LINGER` option.
        ///
        /// This option controls the action taken when a stream has unsent messages and the stream is
        /// closed. If `SO_LINGER` is set, the system shall block the process until it can transmit the
        /// data or until the time expires.
        ///
        /// If `SO_LINGER` is not specified, and the stream is closed, the system handles the call in a
        /// way that allows the process to continue as quickly as possible.
        ///
        /// This option is deprecated because setting `SO_LINGER` on a socket used with Tokio is
        /// always incorrect as it leads to blocking the thread when the socket is closed. For more
        /// details, please see:
        ///
        /// > Volumes of communications have been devoted to the intricacies of `SO_LINGER` versus
        /// > non-blocking (`O_NONBLOCK`) sockets. From what I can tell, the final word is: don't
        /// > do it. Rely on the `shutdown()`-followed-by-`read()`-eof technique instead.
        /// >
        /// > From [The ultimate `SO_LINGER` page, or: why is my tcp not reliable](https://blog.netherlabs.nl/articles/2009/01/18/the-ultimate-so_linger-page-or-why-is-my-tcp-not-reliable)
        ///
        /// # Examples
        ///
        /// ```no_run
        /// # #![allow(deprecated)]
        /// use tokio::net::TcpStream;
        ///
        /// # async fn dox() -> Result<(), Box<dyn std::error::Error>> {
        /// let stream = TcpStream::connect("127.0.0.1:8080").await?;
        ///
        /// stream.set_linger(None)?;
        /// # Ok(())
        /// # }
        /// ```
        #[deprecated = "`SO_LINGER` causes the socket to block the thread on drop"]
        pub fn set_linger(&self, dur: Option<Duration>) -> io::Result<()> {
            socket2::SockRef::from(self).set_linger(dur)
        }
    }

    /// Gets the value of the `IP_TTL` option for this socket.