Skip to main content

AsyncComputerRef

The async, by-reference member of the handler family: an AsyncComputer that borrows its input.

Overview​

In Context-Generic Programming (CGP), AsyncComputerRef combines two of the family's axes: it is asynchronous like AsyncComputer and takes its input by reference like ComputerRef. CGP enables pluggable trait implementations in Rust, and AsyncComputerRef is the component that lets a context plug in an async computation that reads its input. A computation that must await and only reads its argument, while still never failing, fits it: its method is async, receives &Input, and returns the Output directly with no failure path. It runs against a context, the type the implementation runs against.

Like the other computers it never names an error type, so it does not have HasErrorType as a supertrait. See the handler family overview for how the members relate and promote.

Definition​

CanComputeAsyncRef is defined as:

#[async_trait]
#[cgp_component(AsyncComputerRef)]
#[prefix(@cgp.extra.handler in DefaultNamespace)]
#[derive_delegate(UseDelegate<Code>)]
#[derive_delegate(UseInputDelegate<Input>)]
pub trait CanComputeAsyncRef<Code, Input> {
type Output;

async fn compute_async_ref(&self, _code: PhantomData<Code>, input: &Input) -> Self::Output;
}

Its attributes:

  • #[async_trait] — rewrites the async fn into a method returning -> impl Future, the lint-clean, allocation-free form, which adds no Send bound to the future.
  • #[cgp_component] — turns the trait into a component: its argument names the provider trait AsyncComputerRef that implementations target and the wiring key AsyncComputerRefComponent, while CanComputeAsyncRef stays the consumer trait callers use.
  • #[prefix] — registers the component in DefaultNamespace under the path @cgp.extra.handler, so a context that joins that namespace binds its provider at @cgp.extra.handler.AsyncComputerRefComponent rather than at the bare key.
  • #[derive_delegate] — generates the legacy UseDelegate and UseInputDelegate providers, which dispatch on the Code tag and on the Input type through an inner table; the open statement replaces both, dispatching on either parameter or on the pair.

Usage​

AsyncComputerRef, AsyncComputerRefComponent, and the consumer trait CanComputeAsyncRef are not in the prelude, and are imported from cgp::extra::handler. The method is async and borrows the input:

async fn compute_async_ref(&self, _code: PhantomData<Code>, input: &Input) -> Self::Output;

A context gains the operation by wiring AsyncComputerRefComponent to a provider, and the component dispatches on both the Code tag and the Input type. Besides a hand-written provider, the PromoteRef combinator answers it from an AsyncComputer written for &'a Input at every lifetime, which is the entry every promotion bundle uses. The same combinator serves the reverse direction: an AsyncComputerRef provider answers compute_async for an owned input that dereferences to its Input. See ComputerRef for the two directions, which work the same way here.

Examples​

A provider that counts the words of a borrowed string, wired into a context and awaited:

use core::marker::PhantomData;
use cgp::extra::handler::{AsyncComputerRef, AsyncComputerRefComponent, CanComputeAsyncRef};
use cgp::prelude::*;

#[cgp_new_provider]
impl<Context, Code> AsyncComputerRef<Context, Code, String> for CountWords {
type Output = usize;

async fn compute_async_ref(
_context: &Context,
_code: PhantomData<Code>,
input: &String,
) -> usize {
input.split_whitespace().count()
}
}

pub struct App;

delegate_components! {
App {
AsyncComputerRefComponent: CountWords,
}
}

check_components! {
App {
AsyncComputerRefComponent: ((), String),
}
}

pub async fn run(app: &App, text: &String) -> usize {
app.compute_async_ref(PhantomData::<()>, text).await
}

run awaits the computation while the caller keeps ownership of text. App is an environmental context, and the component is parameter-targeted: the computation acts on the Input, while App decides the provider.

When to use it​

Reach for AsyncComputerRef when a computation is async and infallible and only reads its input. That is a narrow combination, so code often implements a simpler member and lets promotion bridge to this one, which works when that member takes the borrow as its input.

Reach for AsyncComputer when the computation takes the input by value, for ComputerRef when a borrowed-input computation needs no awaiting, and for HandlerRef when a borrowed-input async computation can also fail.

The ideas behind it:

  • Handlers — the computation family and its sync, async, fallible, and input-passing axes.

Source​


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.