Skip to content

AsyncWrite documentation is confusing #7298

Closed

Description

@AlanStokes

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 that AsyncWrite is an async analog of the core of the Write trait.

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 return Pending, 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 a write method.

Note that this trait also represents that the Write::flush method works very similarly to the write method
You can't call std::Write::flush (or std::Write::write) on an AsyncWrite object. This is presumably trying to say something about poll_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

  1. added
    T-docsTopic: documentation
    A-tokioArea: The main tokio crate
    M-ioModule: tokio/io
    on May 2, 2025
  2. Darksonn commented on May 2, 2025

    @Darksonn
    Member

    Yes, a contribution to improve docs is welcome.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-tokioArea: The main tokio crateM-ioModule: tokio/ioT-docsTopic: documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions