TcpStream::ready() / readable() / writable() returns Result, but the Err are not documented.

[GilShoshan94]

Hi,

TLDR

The errors that TcpStream::ready() / readable() / writable() can return are not documented and it is not clear if they are critical failures unrecoverable, and what they represent.

From searching into the source code it seems pretty unrecoverable and caused by having the Tokio runtime shutting down.

Can someone confirms ?
Or in the case that I am mistaken, can someone explains what does it means to get an error from TcpStream::ready() ?

(By the way, other methods (such as into_std) are neither explicitly documented about their errors. I understand that Tokio is a complex cross platform framework that takes care of a lot of low level details and that it is very hard to expose all the errors in a clear manner, and some other errors are opaque too. I still think that in the public API, if a function returns a Result, it is important to document what can make it fails, if it is recoverable, what it means...)

---

Context

I am trying to build a complex system, and it has to be super robust, which means good error handling.

I am using a Tokio TcpStream and I need to wait for the socket to be readable, so I use readable.
And I use a loop that is inspired by the example given in the documentation.

My issue is that I don't understant when will this method return an Err, all I know is that it's a std::io::Error.

---

Some research

Underneath, it's the more general method TcpStream::ready() that is called.

The error is not documented and I have no idea what it would mean, and so I don't know how to handle it (beside panic in my project).

I dived into the code:

pub async fn ready(&self, interest: Interest) -> io::Result<Ready> {
        let event = self.io.registration().readiness(interest).await?;
        Ok(event.ready)
    }

Following readiness():

impl Registration {
        pub(crate) async fn readiness(&self, interest: Interest) -> io::Result<ReadyEvent> {
            let ev = self.shared.readiness(interest).await;

            if ev.is_shutdown {
                return Err(gone())
            }

            Ok(ev)
        }
...

Ok, so here I can see that there is a boolean flag is_shutdown, that if set, causes an Error.

Following gone() to see what error:

fn gone() -> io::Error {
    io::Error::new(
        io::ErrorKind::Other,
        crate::util::error::RUNTIME_SHUTTING_DOWN_ERROR,
    )
}

Ok, now I see the only possible error is an std::io::Error with ErrorKind::Other.

Let's see what is the crate::util::error::RUNTIME_SHUTTING_DOWN_ERROR:

/// Error string explaining that the Tokio context is shutting down and cannot drive timers.
pub(crate) const RUNTIME_SHUTTING_DOWN_ERROR: &str =
    "A Tokio 1.x context was found, but it is being shutdown.";

---

My conclusion

Ok, it seems pretty clear now that if ready fails, this is because the Tokio runtime is shutting down, so pretty unrecoverable it seems.

Did I get that right ?

[Darksonn]

We cannot exhaustively list all reasons it might fail, but all errors it might return are unrecoverable.

[GilShoshan94]

Thank you Alice.
I will treat it as unrecoverable from now on.