async-trait

The #[async_trait] macro transforms async fn methods into regular functions that return a pinned, boxed, thread-safe future: Pin<Box<dyn Future + Send + 'async_trait>>.

This transformation allows the trait to be used with dynamic dispatch (dyn Trait), as the return type is now a concrete, sized type (the Pin<Box<...>> wrapper) rather than an opaque, compiler-generated future type.

// Example of how the macro expands an implementation:
impl Advertisement for AutoplayingVideo {
    fn run<'async_trait>(
        &'async_trait self,
    ) -> Pin<Box<dyn std::future::Future<Output = ()> + Send + 'async_trait>>
    where
        Self: Sync + 'async_trait,
    {
        Box::pin(async move {
            /* the original method body */
        })
    }
}

In Rust (up to version 1.75), using async fn in traits prevents the trait from being used as a dyn Trait (dynamic dispatch). The async_trait crate provides an attribute macro that enables async fn in traits while maintaining compatibility with dyn Trait.

To use it, apply the #[async_trait] macro to both the trait definition and the corresponding impl blocks.

use async_trait::async_trait;

#[async_trait]
trait Advertisement {
    async fn run(&self);
}

struct Modal;

#[async_trait]
impl Advertisement for Modal {
    async fn run(&self) {
        // implementation
    }
}

The async fn syntax does not support implicit lifetime elision for types other than & and &mut references. If your method uses types with elided lifetimes (like a type alias type Elided<'a> = &'a usize), you must explicitly name the lifetime or use the '_ placeholder.

Incorrect:

trait Test {
    async fn test(not_okay: Elided, okay: &usize) {}
}

Correct (using named lifetime):

trait Test {
    async fn test<'e>(elided: Elided<'e>) {}
}

Correct (using '_ placeholder):

trait Test {
    async fn test(elided: Elided<'_>) {}
}

By default, #[async_trait] assumes that the futures returned by the trait methods must be Send. If you need to work with non-threadsafe futures (e.g., when you cannot or do not want to require Send or Sync bounds on your types), you can use the ?Send feature flag.

Apply #[async_trait(?Send)] to both the trait definition and the implementation blocks to avoid requiring Send bounds on the async trait methods.

The #[async_trait] macro supports most standard Rust trait features, including:

• Self by value, by reference, by mut reference, or no self
• Any number of arguments and any return value
• Generic type parameters and lifetime parameters
• Associated types
• Mixing async and non-async functions in the same trait
• Default implementations provided by the trait
• Elided lifetimes (when explicitly handled)

Async function syntax in Rust does not allow implicit lifetime elision for types other than & and &mut. When using #[async_trait], you must explicitly name lifetimes or use the anonymous lifetime placeholder '_ for any types that rely on elision.

If you encounter the error error[E0726]: implicit elided lifetime not allowed here, you must update your function signature.

Incorrect:

type Elided<'a> = &'a usize;

#[async_trait]
trait Test {
    async fn test(not_okay: Elided, okay: &usize) {}
}

Correct (using '_):

#[async_trait]
trait Test2 {
    async fn test(elided: Elided<'_>, okay: &usize) {}
}

Correct (using named lifetimes):

#[async_trait]
trait Test {
    async fn test<'e>(elided: Elided<'e>) {}
}

By default, #[async_trait] adds a Send bound to the returned futures, requiring that the trait and its implementations are thread-safe. If you do not need your futures to be Send (e.g., you are not using them across thread boundaries), you can opt out of this requirement by using the ?Send argument.

Apply #[async_trait(?Send)] to both the trait definition and the implementation blocks.