associate-async-io

Async IO traits that use futures instead of poll. This is an experiment to see if using async fn for the futures::io traits is possible.

• Documentation
• Crates.io
• Releases

Why does this exist?

This is useful because currently implementing AsyncRead, AsyncWrite, and Stream require knowledge of Poll, Pin, and arbitrary self types. We think it would be an ergonomics improvement if knowledge of these concepts was not required to implement these traits. Instead once async fn in traits comes around we think that would make a great fit:

pub trait AsyncRead {
    async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
}

pub trait AsyncWrite {
    async fn write(&mut self, buf: &[u8]) -> io::Result<usize>;
}

pub trait AsyncIterator {
    type Item;
    async fn next(&mut self) -> Option<Self::Item>;
}

These would be direct async counterparts to Read, Write and Iterator:

pub trait AsyncRead {
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
}

pub trait AsyncWrite {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize>;
}

pub trait AsyncIterator {
    type Item;
    fn next(&mut self) -> Option<Self::Item>;
}

However currently async fn in traits doesn't work. So we're defining these traits with an associated type instead.

pub trait AsyncRead {
    type Fut: Future<Output = io::Result<usize>>;
    fn read(&mut self, buf: &mut [u8]) -> Self::Fut;
}

pub trait AsyncWrite {
    type Fut: Future<Output = io::Result<usize>>;
    fn write(&mut self, buf: &[u8]) -> Self::Fut;
}

pub trait AsyncIterator {
    type Item;
    type Fut: Future<Output = Option<Self::Item>>;
    fn next(&mut self) -> Self::Fut;
}

Because of compiler reasons this means there currently is the overhead of an extra box. But we think that's fine, as it's unlikely to become a bottleneck, and this would be temporary anyway.

However a limitation is that this can't return borrowed values, as it relies on GATs. Which seems like the most convincing counterpoint to using these traits today.

Examples

#![feature(async_await)]

use futures::executor::block_on;
use associated_async_io::AsyncIterator;
use futures::future::{self, Future};
use std::pin::Pin;

#[derive(Debug)]
struct KittenIterator {
    cursor: usize,
    kittens: Vec<String>,
}

impl KittenIterator {
    fn new(mut kittens: Vec<String>) -> Self {
        kittens.reverse();
        Self { cursor: 0, kittens }
    }
}

impl AsyncIterator for KittenIterator {
    type Item = String;
    type Fut = Pin<Box<Future<Output = Option<Self::Item>>>>;
    fn next(&mut self) -> Self::Fut {
        self.cursor += 1;
        let kitten = self.kittens.pop();
        Box::pin(future::ready(kitten))
    }
}

fn main () {
    block_on(async {
        let kittens = vec!["chashu".to_owned(), "nori".to_owned()];
        let mut kittens = KittenIterator::new(kittens);
        AsyncIterator::next(&mut kittens);
    })
}

Installation

$ cargo add associate-async-io

Safety

This crate uses #![deny(unsafe_code)] to ensure everything is implemented in 100% Safe Rust.

Contributing

Want to join us? Check out our "Contributing" guide and take a look at some of these issues:

• Issues labeled "good first issue"
• Issues labeled "help wanted"

References

None.

License

MIT OR Apache-2.0