# Async trait methods with polling and extension traits
Rust's trait system doesn't allow async methods in traits. The `async-trait` crate solves this by returning boxed futures.
For most cases `async-trait` works pretty well, however some low-level traits can't afford to do a heap allocation everytime they're called, so other crates like `tokio` started using "extension traits". They basically converted `Read::read` to `AsyncRead::poll_read` which uses polling and provided a new method `AsyncReadExt::read` that returns a future that internally uses `poll_read` (`AsyncReadExt` is automatically implemented for all `AsyncRead`). Since `poll_read` is synchronous, the trait doesn't contain any async methods and can be compiled by Rust. All implementors just have to implement `poll_read` instead of `read`.
Writing extension traits by hand can be very tedious, so the `async_trait_ext` macro can be used take care of writing all that boilerplate code.
## Dynamic trait objects
For a trait like
```rust
#[async_trait_ext]
trait AsyncRead {
async fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Result<usize>;
}
```
`async_trait_ext` by default generates a struct like
```rust
struct AsyncReadRead<'a, SelfTy: AsyncRead>(&'a mut SelfTy, &'a mut [u8]);
```
to implement the future for `AsyncRead::read`. This struct contains Self so it needs to be sized.
However it's also possible to optin to dynamic types by using `async_trait_ext(dynamic)`.
```rust
#[async_trait_ext(dynamic)]
trait AsyncRead {
async fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Result<usize>;
}
```
generates
```rust
struct AsyncReadRead<'a>(&'a mut dyn AsyncRead, &'a mut [u8]);
```
which doesn't need to be sized.
### Provided functions
Sometimes it's usefully to have provided functions for a trait. Marking functions with the `provided` attribute moves them into the extension trait.
Unfortunatly the `type_alias_impl_trait` feature on nightly is required to name the type of an async block. Because of that the `provided` attribute can only be used with the `provided` feature of `async-trait-ext` (not enabled by default).
Example
```rust
#![feature(type_alias_impl_trait)]
#[async_trait_ext(dynamic)]
trait AsyncRead {
async fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Result<usize>;
#[async_fn(provided)]
async fn read_u8<'a>(&'a mut self) -> Result<u8> {
let mut buf = [0];
self.read(&mut buf).await?;
Ok(buf[0])
}
}
```
## Examples
### Non-dynamic
```rust
#[async_trait_ext]
pub trait Lock {
async fn lock(&self) -> Result<LockGuard>;
}
```
expands to
```rust
pub trait Lock {
fn poll_lock(&self, ctx: &mut ::core::task::Context) -> ::core::task::Poll<Result<LockGuard>>;
}
/// the future returned by [`LockExt::lock`]
pub struct LockLock<'__default_lifetime, __Self: Lock>(
&'__default_lifetime __Self,
::core::marker::PhantomData<fn(__Self)>,
::core::marker::PhantomData<&'__default_lifetime ()>,
);
impl<'__default_lifetime, __Self: Lock> ::core::future::Future
for LockLock<'__default_lifetime, __Self>
{
type Output = Result<LockGuard>;
fn poll(
mut self: ::core::pin::Pin<&mut Self>,
cx: &mut ::core::task::Context,
) -> ::core::task::Poll<Self::Output> {
let this = &mut *self;
<__Self as Lock>::poll_lock(this.0.into(), cx)
}
}
pub trait LockExt: Lock + ::core::marker::Sized {
fn lock(&self) -> LockLock<'_, Self>;
}
impl<__IMPL: Lock> LockExt for __IMPL {
fn lock(&self) -> LockLock<'_, Self> {
LockLock(
self,
::core::marker::PhantomData,
::core::marker::PhantomData,
)
}
}
```
### Dynamic
```rust
#[async_trait_ext(dynamic)]
pub trait Write {
async fn write<'a>(&'a mut self, buf: &'a [u8]) -> Result<usize>;
}
```
expands to
```rust
pub trait Write {
fn poll_write<'a>(
&'a mut self,
buf: &'a [u8],
ctx: &mut ::core::task::Context,
) -> ::core::task::Poll<Result<usize>>;
}
/// the future returned by [`WriteExt::write`]
pub struct WriteWrite<'a>(
&'a mut dyn Write,
&'a [u8],
::core::marker::PhantomData<&'a ()>,
);
impl<'a> ::core::future::Future for WriteWrite<'a> {
type Output = Result<usize>;
fn poll(
mut self: ::core::pin::Pin<&mut Self>,
cx: &mut ::core::task::Context,
) -> ::core::task::Poll<Self::Output> {
let this = &mut *self;
Write::poll_write(this.0.into(), this.1.into(), cx)
}
}
pub trait WriteExt: Write {
fn write<'a>(&'a mut self, buf: &'a [u8]) -> WriteWrite<'a>;
}
impl<__IMPL: Write> WriteExt for __IMPL {
fn write<'a>(&'a mut self, buf: &'a [u8]) -> WriteWrite<'a> {
WriteWrite(self, buf, ::core::marker::PhantomData)
}
}
```
### Provided methods
```rust
#![feature(type_alias_impl_trait)]
#[async_trait_ext]
pub trait ReadStatic {
async fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Result<usize>;
#[async_fn(provided)]
async fn read_until<'a>(&'a mut self, byte: u8, mut buf: &'a mut [u8]) -> Result<usize> {
let mut b = [0];
let mut bytes_read = 0;
while !buf.is_empty() {
match self.read(&mut b).await? {
1 if b[0] != byte => {
bytes_read += 1;
buf[0] = b[0];
buf = &mut buf[1..];
}
_ => break,
}
}
Ok(bytes_read)
}
}
```
expands to
```rust
#![feature(type_alias_impl_trait)]
pub trait ReadStatic {
fn poll_read<'a>(
&'a mut self,
buf: &'a mut [u8],
ctx: &mut ::core::task::Context,
) -> ::core::task::Poll<Result<usize>>;
}
/// the future returned by [`ReadStaticExt::read`]
pub struct ReadStaticRead<'a, __Self: ReadStatic>(
&'a mut __Self,
&'a mut [u8],
::core::marker::PhantomData<fn(__Self)>,
::core::marker::PhantomData<&'a ()>,
);
impl<'a, __Self: ReadStatic> ::core::future::Future for ReadStaticRead<'a, __Self> {
type Output = Result<usize>;
fn poll(
mut self: ::core::pin::Pin<&mut Self>,
cx: &mut ::core::task::Context,
) -> ::core::task::Poll<Self::Output> {
let this = &mut *self;
<__Self as ReadStatic>::poll_read(this.0.into(), this.1.into(), cx)
}
}
/// the future returned by [`ReadStaticExt::read_until`]
pub type ReadStaticReadUntil<'a, __Self: ReadStatic> =
impl ::core::future::Future<Output = Result<usize>>;
pub trait ReadStaticExt: ReadStatic + ::core::marker::Sized {
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadStaticRead<'a, Self>;
fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut [u8]) -> ReadStaticReadUntil<'a, Self>;
}
impl<__IMPL: ReadStatic> ReadStaticExt for __IMPL {
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadStaticRead<'a, Self> {
ReadStaticRead(
self,
buf,
::core::marker::PhantomData,
::core::marker::PhantomData,
)
}
fn read_until<'a>(
&'a mut self,
byte: u8,
mut buf: &'a mut [u8],
) -> ReadStaticReadUntil<'a, Self> {
async move {
{
let mut b = [0];
let mut bytes_read = 0;
while !buf.is_empty() {
match self.read(&mut b).await? {
1 if b[0] != byte => {
bytes_read += 1;
buf[0] = b[0];
buf = &mut buf[1..];
}
_ => break,
}
}
Ok(bytes_read)
}
}
}
}
```
### Provided methods + dynamic
```rust
#![feature(type_alias_impl_trait)]
#[async_trait_ext(dynamic)]
pub trait ReadDynamic {
async fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> Result<usize>;
#[async_fn(provided)]
async fn read_until<'a>(&'a mut self, byte: u8, mut buf: &'a mut [u8]) -> Result<usize> {
let mut b = [0];
let mut bytes_read = 0;
while !buf.is_empty() {
match self.read(&mut b).await? {
1 if b[0] != byte => {
bytes_read += 1;
buf[0] = b[0];
buf = &mut buf[1..];
}
_ => break,
}
}
Ok(bytes_read)
}
}
```
expands to
```rust
#![feature(type_alias_impl_trait)]
pub trait ReadDynamic {
fn poll_read<'a>(
&'a mut self,
buf: &'a mut [u8],
ctx: &mut ::core::task::Context,
) -> ::core::task::Poll<Result<usize>>;
}
/// the future returned by [`ReadDynamicExt::read`]
pub struct ReadDynamicRead<'a>(
&'a mut dyn ReadDynamic,
&'a mut [u8],
::core::marker::PhantomData<&'a ()>,
);
impl<'a> ::core::future::Future for ReadDynamicRead<'a> {
type Output = Result<usize>;
fn poll(
mut self: ::core::pin::Pin<&mut Self>,
cx: &mut ::core::task::Context,
) -> ::core::task::Poll<Self::Output> {
let this = &mut *self;
ReadDynamic::poll_read(this.0.into(), this.1.into(), cx)
}
}
/// the future returned by [`ReadDynamicExt::read_until`]
pub type ReadDynamicReadUntil<'a> = impl ::core::future::Future<Output = Result<usize>>;
pub trait ReadDynamicExt: ReadDynamic {
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadDynamicRead<'a>;
fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut [u8]) -> ReadDynamicReadUntil<'a>;
}
impl<__IMPL: ReadDynamic> ReadDynamicExt for __IMPL {
fn read<'a>(&'a mut self, buf: &'a mut [u8]) -> ReadDynamicRead<'a> {
ReadDynamicRead(self, buf, ::core::marker::PhantomData)
}
fn read_until<'a>(&'a mut self, byte: u8, buf: &'a mut [u8]) -> ReadDynamicReadUntil<'a> {
async fn fn_impl<'a>(
this: &mut dyn ReadDynamicExt,
byte: u8,
mut buf: &'a mut [u8],
) -> Result<usize> {
{
let mut b = [0];
let mut bytes_read = 0;
while !buf.is_empty() {
match this.read(&mut b).await? {
1 if b[0] != byte => {
bytes_read += 1;
buf[0] = b[0];
buf = &mut buf[1..];
}
_ => break,
}
}
Ok(bytes_read)
}
}
fn_impl(self, byte, buf)
}
}
```
The tests contain also some examples on how the traits can be used.