Repository navigation
Description
I was recently trying to understand AsyncWrite (specifically https://docs.rs/tokio/1.44.2/tokio/io/trait.AsyncWrite.html), and found the overview documentation unhelpful in places.
For example:
The trait inherits from std::io::Write
It doesn't. (Technically, trait inheritance doesn't even exist.) I think this is trying to say thatAsyncWriteis an async analog of the core of theWritetrait.
All non-blocking I/O objects must return an error when bytes cannot be written instead of blocking the current thread.
As the text below explains, they returnPending, not an error.
And the term nonblocking isn't really defined, other than this sentence. I wonder if it would be better just to stick to asynchronous.
This trait importantly means that the write method only works in the context of a future’s task.
This trait doesn't have awritemethod.
Note that this trait also represents that the Write::flush method works very similarly to the write method
You can't callstd::Write::flush(orstd::Write::write) on anAsyncWriteobject. This is presumably trying to say something aboutpoll_flush.
Utilities for working with AsyncWrite values are provided by AsyncWriteExt
They're not so much utilities as the methods that a user (rather than an implementor) of the trait would use.
(The documentation for AsyncWriteExt says "Callers will tend to import this trait instead of AsyncWrite", which might usefully be mentioned in the documentation for AsyncWrite.)
More importantly, this is where to look for versions of the std::Write methods that aren't directly represented in AsyncWrite - or at least some of them.
Would you be interested in a contribution that attempted to address these?
Activity
Darksonn commentedon May 2, 2025
Yes, a contribution to improve docs is welcome.