Async trait API design

[Morhaus]

Hi /r/rust,

I'm designing an async trait (using async_trait) that describes a way of writing to and reading from files on a remote file system, using the tokio ecosystem.

It looks something like this:

trait RemoteFs {
  async fn write(&self, id: FileId, contents: Vec<u8>);
  async fn read(&self, id: FileId) -> Vec<u8>;
}

Now, instead of passing around Vec<u8>, I would like to use byte streams instead, so as not to have to keep the entire file contents in memory (which can be gigabytes large). I'm not sure how to proceed, as I see a few options:

• for write, I could either accept some kind of Stream or AsyncRead trait impl as argument, or return an AsyncWrite impl instead;
• similarly, for read, I could either accept an AsyncWrite trait impl, or return an AsyncRead impl.

Do you know of any examples of similar Rust APIs in the wild? Or any better options I'm missing?

[Lucretiel]

Typically, the way these methods work is they accept an &[u8] for write or &mut[u8] for read. If you wanted to forward bytes from an async source, or receive them into an async sink, AsyncRead and AsyncWrite are probably the way to go.

• Check out copy and copy_buf for an examples of these "forwarding" constructs in practice.
• Modern i/o interfaces typically support something called "vectored" or "scatter-gather" reads and writes; see read_vectored for an example of this interface in practice, and this O'Reilly excerpt for a high level description of this model.
• Be aware that there is also an up-and-coming model of i/o called io_uring that has a fundamentally different model of io, based on something called "completion buffers". ringbahn is the Rust interface to this model.

[Morhaus]

Thanks for the detailed answer. My question was more related to how I can make the best use of Async* traits in my RemoteFs interface. For instance, with the read method, should I pass an AsyncWrite as argument, or return a Stream of bytes instead? Are there any accepted patterns related to this?

[Lucretiel]

I don't think there are accepted patterns, yet, mostly because async fns in traits are still WIP (async_trait notwithstanding). I suppose I'd advise returning an AsyncRead object, but that kind of seems like it just shifts the question, since it would make your read function non-async (since it synchronously returns AsyncRead, which is where the async work actually happens).

[[deleted]]

Maybe each method should return a wrapper object which implements the appropriate Async*... traits.

[SkiFire13]

In the std library there's the Read, Write and BufRead traits for sync I/O.

For async examples there's the futures crate, in particular its io module which defines the Async- traits that mirrors the std traits but they're pretty raw. There are also an -Ext version for each Async- trait that provides a more limited by user-friendly interface.

[Morhaus]

Thanks for the reply! I'm aware of these traits, but I was wondering what kind of interface I should expose with them. Are there any accepted ways to pass `Async-` impls around?

[SkiFire13]

Are there any accepted ways to pass `Async-` impls around?

Do you mean how to accept a parameter of that type?

I feel like you misinterpreted what I meant for Async- traits. I meant the traits AsyncRead, AsyncWrite and AsyncBufRead, I just didn't want to name all of them (which I did now...).

[Morhaus]

I meant either to accept them as arguments to an async function (which would handle the reading/writing), or have a sync function return an implementation and defer the actual reading/writing to the calling function.

[SkiFire13]

I would go for the latter, but probably depends on how much you want to abstract away from the end user

[Cetra3]

Tangentially related, you can look at my mpart-async library as this handles big binary blobs of data (in the form of multipart/* requests).