Expand on using stdin / stdout

[carllerche]

Related: https://github.com/tokio-rs/tokio/issues/709

[k4210]

Hi, @carllerche could you elaborate? Isn't the purpose of tokio stdin to be non-blocking?
By FD you mean file descriptor ? Cheers!

[benkay86]

Per discussion on discord #tokio-users, the documentation for stdin may be using the word "block" loosely. As currently written:

As an additional caveat, reading from the handle may block the calling future indefinitely if there is not enough data available.

I am not sure if my interpretation is entirely accurate, but it might have been clearer to write:

The standard input is more likely to have incomplete data than most objects implementing AsyncRead because it often depends on the user (a human being) for input. Although a call to AsyncRead::poll_read() will not block, code awaiting a future (e.g. AsyncReadExt::read_to_end().await) may wait indefinitely if there is not enough data available. Consider wrapping such calls in a tokio::timeout.

[jebrosen]

As an additional caveat, reading from the handle may block the calling future indefinitely if there is not enough data available. This makes this handle unsuitable for use in any circumstance where immediate reaction to available data is required, e.g. interactive use or when implementing a subprocess driven by requests on the standard input.

On the contrary, this seems like desired behavior to me. Reads will wait (they will not block in the "blocking" sense that should be avoided in async code) for data to be available: stdin.read().await will not complete until the user or calling program has "entered" input (possibly only at a newline depending on terminal emulation and all that jazz), just like the synchronous version would.

EDIT: Accidentally pressed Ctrl+Enter.