net: document pipe try_read*/try_write* readiness behavior

[barry3406]

Motivation

#7625 reports that calling pipe::Receiver::try_read immediately after creating the receiver returns WouldBlock even when data is already available in the pipe. The same applies to try_read_vectored, try_read_buf, and the try_write* methods on pipe::Sender.

This is intentional: Registration::try_io checks the cached readiness state and short-circuits with WouldBlock until the I/O driver has had a chance to deliver an event for the registration. The same model applies to every other Tokio I/O type. But the pipe docs do not currently call this out, and it's easy to assume try_* is a thin syscall wrapper — which led to the confusion in #7625 (and to my own first attempt at "fixing" it in this PR before @Darksonn and @Thomasdezeeuw kindly explained the actual model).

Solution

Add a # Notes section to all five try_* methods on pipe::Sender and pipe::Receiver explaining that the runtime's I/O driver only delivers readiness events after control has been yielded back to it, and that calling try_* before any .await (such as readable() / writable()) will return WouldBlock even when the operation could otherwise succeed.

No code or behavior changes. The note follows the existing # Notes convention used in udp.rs, tcp/stream.rs, etc., and is positioned between # Return and # Examples to match udp::UdpSocket::try_recv_from which has the same shape.

Verified with the docs.rs-equivalent build from the contributors guide:

RUSTDOCFLAGS="--cfg docsrs --cfg tokio_unstable" RUSTFLAGS="--cfg docsrs --cfg tokio_unstable" cargo +nightly doc -p tokio --all-features --no-deps

No new warnings from pipe.rs, and the rendered HTML on both the Receiver and Sender pages contains all five new # Notes sections.

[Darksonn]

Thanks.

[Darksonn]

Ah, looks like the WouldBlock link doesn't work.

[barry3406]

good catch, fixed in 3c06d4b — added [WouldBlock]: std::io::ErrorKind::WouldBlock reference definitions under each Notes section to match the convention in async_fd.rs. cargo doc --no-deps now resolves cleanly.

[mattiapitossi]

Thanks!