AsyncRead and AsyncWrite

[nrc]

Tracking issue for work on AsyncRead and AsyncWrite. The eventual goal is that we have a single, standardised version of these traits in std which are used by all (or at least most mainstream) async runtimes.

Known technical issues:

• should these traits use poll_read/poll_write functions or async fn read/async fn write
• how to handle writing to uninitialised memory in AsyncRead
• how to simultaneously read and write
• how to do vectored IO
• working in no_std scenarios (I believe this only requires moving the Error trait to libcore, which is work in progress
• ensuring these traits work well as trait objects
• using async drop for shutdown?

There are also several closely related traits such as AsyncSeek, and in various libraries, extension traits and AsyncBufRead.

Current implementations:

• Tokio: AsyncRead AsyncWrite
• Futures: AsyncRead AsyncWrite
• Futures-lite: AsyncRead AsyncWrite
• Async-std: Read Write

Smol re-exports the futures versions.

[nrc]

Some resources:

• Async vision doc
• Async foundations issue
• Paper doc on uninit memory
• Blog post on unint memory
• RFC 2930 (on extending Read trait to allow using uninit memory)
• Tokio discussion: 1744, 2716
• Futures crate discussion: 2209

[TennyZhuang]

• should these traits use poll_read/poll_write functions or async fn read/async fn write

async fn is better, but it was blocked by async-trait which is unlikely to be stabilized in the short term. 😞

[ibraheemdev]

It's actually blocked on a dyn-safe (inline) async traits.

[nrc]

I think we have a solution to dyn-safe async traits that doesn't require 'inline' async.

[nrc]

ReadBuf (RFC 2930) has landed on nightly now (rust-lang/rust#81156)

[yoshuawuyts]

Async-std: Read Write
Smol re-exports the futures versions.

Note that async-std also re-exports the futures-io traits, but does so using an alias. This does mean the traits are compatible though. In hindsight we probably should've kept the Async{Read,Write} terminology, but we didn't know that at the time.

[yoshuawuyts]

Another known blocker that I haven't seen mentioned yet: the working group needs to make a decision on the feasibility of async overloading. This will have consequences for the shape and location of the async IO traits.

Async overloading is being tracked on the roadmap, but does not yet have an initiative owner.

[nrc]

Note that async-std also re-exports the futures-io traits

From the docs, they appear to have different definitions? The async-std versions have significantly more methods. Not sure if it a re-export of an earlier version of the futures definition or something more complex than that.

[yoshuawuyts]

From the docs, they appear to have different definitions? The async-std versions have significantly more methods.

yeah, that touches on another thing we probably shouldn't have done: the methods on async_std::io::{Read,Write} don't actually exist on them; they are only compiled in for the docs, to create the appearance that they do. The way they are made available is by importing async_std::io::prelude::* which includes ReadExt and WriteExt. It's very much a hack, but it allowed us to keep using the futures-io types, while still providing a cohesive feel.

The reason why we did this is because we wanted to push the "async-std is an async version of std" idea as far as we could. We wanted to prove out that it is indeed possible to map std's abstractions and usage patterns 1:1 to async Rust. And it worked; we now know that that it indeed can be done - modulo some missing language features like "async closures", "async drop" and "async traits". But perhaps if we had to try this again, we could've just exposed it as async_std::io::{AsyncRead,AsyncReadExt}. Though obviously that's speaking with the benefit of hindsight.

[nrc]

A proposed design: https://www.ncameron.org/blog/async-read-and-write-traits/

I should flesh out the alternatives with examples and/or why they don't meet the stated goals.

[uazu]

Just one comment on the proposed design (which looks fine to me although I'm not really the target audience):

• For the examples where let mut buf = [0; 1024]; is done after the ready call, I'm trying to figure out how this saves memory, since usually stack space is reserved based on the maximum extent required. Does this depend on buf not carrying over any .await, which means it goes onto the real stack instead of into the coroutine context structure? So the aim is to not have the buffer held across any .await?

[nrc]

For the examples where let mut buf = [0; 1024]; is done after the ready call, ...

These are simplified examples, in real life we might use one shared buffer or allocate space on the heap to be used in other functions, etc.

[bestouff]

Shouldn't AsyncRead and AsyncReady be renamed Read and Ready in the "Complete version" code block ?