util: add writev-aware poll_write_buf

[hawkw]

Motivation

In Tokio 0.2, AsyncRead and AsyncWrite had poll_write_buf and
poll_read_buf methods for reading and writing to implementers of
bytes Buf and BufMut traits. In 0.3, these were removed, but
poll_read_buf was added as a free function in tokio-util. However,
there is currently no poll_write_buf.

Now that AsyncWrite has regained support for vectored writes in #3149,
there's a lot of potential benefit in having a poll_write_buf that
uses vectored writes when supported and non-vectored writes when not
supported, so that users don't have to reimplement this.

Solution

This PR adds a poll_write_buf function to tokio_util::io, analogous
to the existing poll_read_buf function.

This function writes from a Buf to an AsyncWrite, advancing the
Buf's internal cursor. In addition, when the AsyncWrite supports
vectored writes (i.e. its is_write_vectored method returns true),
it will use vectored IO.

I copied the documentation for this functions from the docs from Tokio
0.2's AsyncWrite::poll_write_buf , with some minor modifications as
appropriate.

Finally, I fixed a minor issue in the existing docs for poll_read_buf
and read_buf, and updated tokio_util::codec to use poll_write_buf.

Signed-off-by: Eliza Weisman eliza@buoyant.io

[hawkw]

Looks like rustfmt is failing for code in tokio-macros...which this PR doesn't touch at all? Could it be an upstream formatting change?

[taiki-e]

Could it be an upstream formatting change?

Probably something was fixed in Rust 1.48 stable. (It looks like modules that were not previously formatted correctly are now formatted.)

EDIT: filed #3158

[mzabaluev]

Note that there still is a provided implementation of AsyncWriteExt::write_buf in the tokio crate. Should it also make use of these utilities, or be documented as specifically not making use of vectored output, or be slated for removal in a later API revision?

I think an extension method is more convenient than the free-standing function, while the object safety concerns that led to the removal of AsyncWrite::poll_write_buf do not apply to AsyncWriteExt.

[Darksonn]

The write_buf in Tokio should be updated to use vectored IO. This PR is more about the poll_* variant of them not being in Tokio afaik.

[hawkw]

Per a Discord conversation, I'm going to downscope this PR to just add poll_write_buf in tokio-util. I'll make tokio::io::AsyncWriteExt's write_buf method aware of vectored IO in a separate PR.

[hawkw]

@carllerche and @Darksonn, I've updated this PR to just add poll_write_buf in tokio-util --- we can add a writev-aware write_buf to AsyncWriteExt in the tokio crate, instead.

This should be ready for a review. It would be nice to publish tokio-util 0.5.1 when this lands; I can prepare the release PR.

[Darksonn]

Seems ok to me.