Clarify which TcpStream methods won't work in non-blocking mode

[n-epifanov]

https://doc.rust-lang.org/std/net/struct.TcpStream.html

According to source code, read_to_end(), read_to_string() and read_exact() won't work properly in non-blocking mode (they hit WouldBlock and start misbehaving). If it's an expected behaviour then it should be noted in the docs.

[frewsxcv]

i did some work on this in #45227 which hasn't landed in stable yet, but can be seen in the nightly docs

[n-epifanov]

Oh, so it's just done totally another way! Coming from Python I thought right away "ok, these just don't work then for non-blocking" like readline() in Python :)) Thanks!

[frewsxcv]

According to source code

@NickTime when you have a second, can you point out in the source where it says this?

[n-epifanov]

First I need to say that I don't know Rust well and don't remember clearly the issue. I think I had a problem with read_exact(), my initial thought was to pass it array of u8, since it takes "buf: &mut [u8]". In non-blocking mode it would read some data into array and return an error (https://doc.rust-lang.org/src/std/io/mod.rs.html#689) and I wouldn't know how much data it actually read.
read_to_end() and read_to_string() would work I guess, but one would need to check Vec length to see how much data were received. What puzzled me is that I was supposed to get data length from return value, but was getting just error. And without an example it wasn't clear that I should just call again with same Vec.

[n-epifanov]

@frewsxcv Does it make sense? :)
Another confusing thing for me was since function (read_to_end()) returns error then data (buf) is in inconsistent state and is not supposed to be used anyhow as I thought.

[Rua]

I'd like better documentation on read_exact specifically, in the context of non-blocking I/O. If the read fails with an error, is there a guarantee that no data has been read? And if data has been read, where did it go?

[sfackler]

If the read fails with an error, is there a guarantee that no data has been read?

That is impossible to guarantee.

And if data has been read, where did it go?

It's in the head of the buffer you passed in.

[DevQps]

@NickTime Do you still think this is necessary given that the documentation written by @frewsxcv has now landed in stable as well?

[n-epifanov]

@DevQps sorry for terribly late reply (had a car crash). I haven't been using Rust and now I have no idea.