#[async_trait]
Rewrite a trait's async fn declarations into the lint-clean -> impl Future form that the library's async traits use.
Overview
In Context-Generic Programming (CGP), writing a bare async fn inside a public trait
compiles on stable Rust, and the compiler warns about it. The async_fn_in_trait lint fires because the future such a method returns is opaque: a
caller working through the trait cannot name it, so they cannot require anything of it, most
importantly that it is Send. The hand-written way to silence the lint is to declare the method as
a future-returning function instead, which is correct and obscures the intent:
fn fetch(&self, id: &str) -> impl Future<Output = Result<Vec<u8>, String>>;
#[async_trait] lets you write the natural form and performs that rewrite mechanically:
#[async_trait]
pub trait CanFetch {
async fn fetch(&self, id: &str) -> Result<Vec<u8>, String>;
}
The trait reads as async code, and the declaration the compiler sees is the lint-clean one.
The rewrite is a plain desugaring, not a framework. Unlike the widely-used async-trait crate,
nothing here boxes the future or allocates: it is return-position impl Trait in traits, so the
future is exactly the one the body produces and the call costs what a hand-written future-returning
method costs. That is why the macro is used throughout CGP wherever a trait's methods are
asynchronous: it is how an async method is spelled.
One thing it does not do is add a Send bound, and that omission has consequences the moment a future is
spawned. It is covered under Common Mistakes.
Usage
Apply the attribute to a trait definition. It takes no arguments. Tokens in the argument position are ignored, so it is always written bare:
#[async_trait]
pub trait CanFetch {
async fn fetch(&self, id: &str) -> Result<Vec<u8>, String>;
}
Only methods declared async are touched. Non-async methods, associated types, and associated constants in
the same trait pass through unchanged, so a trait can mix them freely.
Ordering with a host macro
When stacked with another macro, the order follows what that macro needs, and the two cases differ.
With #[cgp_component], the conventional placement is outermost, so it rewrites
the trait before the component macro reads it:
#[async_trait]
#[cgp_component(StorageObjectFetcher)]
pub trait CanFetchStorageObject {
async fn fetch_storage_object(&self, object_id: &str) -> Result<Vec<u8>, String>;
}
Placing it after #[cgp_component] also works, because the component macro copies an attribute it does
not recognize onto each trait it generates, where #[async_trait] then rewrites it. The async components
of the transfer
example are written that way.
With #[cgp_fn], which generates the trait from a function, put it below #[cgp_fn] on
the async fn. #[cgp_fn] copies the attribute onto both items it generates:
#[cgp_fn]
#[async_trait]
pub async fn fetch_storage_object(
&self,
#[implicit] storage_client: &Client,
object_id: &str,
) -> Result<Vec<u8>, String> {
/* ... */
}
Examples
The common case is declaring an asynchronous component. The consumer trait carries the attribute so its method
is a clean declaration, and each provider implements it with an ordinary async fn body:
use cgp::prelude::*;
use cgp::core::error::ErrorTypeProviderComponent;
#[async_trait]
#[cgp_component(StorageObjectFetcher)]
#[use_type(HasErrorType.Error)]
pub trait CanFetchStorageObject {
async fn fetch_storage_object(&self, object_id: &str) -> Result<Vec<u8>, Error>;
}
#[cgp_impl(new FetchFromBucket)]
#[use_type(HasErrorType.Error)]
impl StorageObjectFetcher {
async fn fetch_storage_object(
&self,
#[implicit] bucket_id: &str,
object_id: &str,
) -> Result<Vec<u8>, Error> {
// await a real client here
Ok(format!("{bucket_id}/{object_id}").into_bytes())
}
}
#[derive(HasField)]
pub struct App {
pub bucket_id: String,
}
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
StorageObjectFetcherComponent: FetchFromBucket,
}
}
check_components! {
App {
StorageObjectFetcherComponent,
}
}
App is an environmental context: it stands for
the application and holds the bucket name the provider reads.
Notice the provider needs no #[async_trait] of its own. An async fn is already legal in an impl block,
since only a trait declaration trips the lint, so the provider keeps the natural body while the trait carries
the rewritten signature, and the two agree because an async fn desugars to exactly such a future-returning
method.
When to use it
Use #[async_trait] on every CGP trait with an async method. There is no judgement to make here: it is
how an async method is declared, and the alternative is either a lint warning or writing the impl Future
signature by hand.
The decisions worth making are around it rather than about it.
- Do not put it on an impl block. It is accepted there and does nothing, since the rewrite only applies to trait definitions. Harmless, but it suggests a misunderstanding of where the lint comes from.
- Use the
Send-recovery pattern when a future is spawned, not a different macro. No attribute can add the bound, for the reason in the Common Mistakes. - Consider whether the trait needs to be async at all. The handler family has synchronous members, and the promotion combinators lift a synchronous provider into an async one where a caller needs it. So a computation that does no I/O is better declared synchronous and promoted than declared async out of habit.
- Use the
async-traitcrate instead only if you needdyncompatibility. Boxing makes an async trait object-safe, and this macro deliberately does not box. CGP resolves providers statically, so it does not needdyn; a codebase that does for other reasons is outside what this macro is for.
Under the hood
For each async method the macro removes the async keyword and wraps the return type in
impl ::core::future::Future<Output = …>. A method with no return arrow is treated as returning (). From
this input:
#[async_trait]
pub trait CanFetch {
async fn fetch(&self, id: &str) -> Result<Vec<u8>, String>;
async fn run(&self);
fn sync_method(&self) -> u8;
}
the macro emits:
pub trait CanFetch {
fn fetch(
&self,
id: &str,
) -> impl ::core::future::Future<Output = Result<Vec<u8>, String>>;
fn run(&self) -> impl ::core::future::Future<Output = ()>;
fn sync_method(&self) -> u8;
}
A few things to read off it. The Output is the original return type verbatim. The bodiless run picked up
Output = (). And sync_method was left completely alone, which lets a trait mix async and
synchronous methods.
A method with a default body keeps it, wrapped in async move { … }, so the body is the future the method
returns, as the body of an async fn is. Each by-value parameter bound to a plain name is rebound inside the
block, so the future owns it, and a mut on the parameter moves to the rebinding:
// async fn add(&self, mut value: u32, extra: u32) -> u32 { value += extra; value }
fn add(&self, value: u32, extra: u32) -> impl ::core::future::Future<Output = u32> {
async move {
let mut value = value;
let extra = extra;
value += extra;
value
}
}
The macro rewrites only trait definitions. Applied to anything else, most importantly an impl block,
it returns the tokens unchanged. This passthrough makes the composition work: an async fn is legal in
an impl already, so the provider's body stays as written while the trait's declaration carries the future
type, and the async fn satisfies it because an async fn desugars to precisely that.
The composition with #[cgp_fn] shows both halves at once. #[cgp_fn] first produces a trait
and a blanket impl, attaching #[async_trait] to each:
#[async_trait]
pub trait FetchStorageObject {
async fn fetch_storage_object(&self, object_id: &str) -> Result<Vec<u8>, String>;
}
#[async_trait]
impl<__Context__> FetchStorageObject for __Context__
where
Self: HasField<Symbol!("storage_client"), Value = Client>,
{
async fn fetch_storage_object(&self, object_id: &str) -> Result<Vec<u8>, String> {
let storage_client: &Client =
self.get_field(PhantomData::<Symbol!("storage_client")>);
/* ... */
}
}
#[async_trait] then runs on both. On the trait it rewrites the declaration; on the impl it is a no-op, so
the async fn body survives intact.
Common Mistakes
The generated future carries no Send bound, and this is the limitation that matters in practice. Because
the rewrite produces a bare impl Future<Output = T>, the future is Send only when the concrete future
happens to be, and the trait does not require it. So code that spawns the future onto a multi-threaded,
work-stealing executor cannot express what it needs through this trait.
The bound you would want to write is Return Type Notation (App: CanFetch<fetch(..): Send>), which
is not stabilized, so stable Rust rejects it with return type notation is experimental (E0658).
The workaround is to declare a second, ordinary trait whose method spells + Send on its return
type directly, and to implement it for each concrete context. That pattern is mechanical but
unavoidable; the opacity that makes the rewrite zero-cost is the same opacity that hides the
auto-traits.
Attribute arguments are silently ignored. #[async_trait(anything)] is accepted and discarded rather than
rejected, so a typo'd option gives no feedback. Always write it bare.
On an impl block it does nothing, which is correct but can mislead. Seeing it on a provider suggests the provider needed it; it did not, and removing it changes nothing.
Related constructs
#[cgp_component]— the usual host, with#[async_trait]placed outermost.#[cgp_fn]— the other host, with#[async_trait]placed beneath it.#[cgp_impl]— where a provider writes an ordinaryasync fnbody and needs no attribute.Handler— CGP's built-in async, fallible component, declared this way.#[cgp_computer]— where anasyncfunction selects the async base trait.- Handler combinators — the promotions that lift a synchronous provider into an async one.
The ideas behind it:
- Recovering
Sendbounds — why the future this rewrite produces carries noSendbound, and how to get one back. - Handlers — the component family whose async members are declared this way.
Source
- Entry point:
cgp-async-macro/src/lib.rs - The rewrite:
impl_async.rs - Prelude re-export:
cgp-core/src/prelude.rs
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.