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 theasync fninto a method returning-> impl Future, the lint-clean, allocation-free form, which adds noSendbound to the future.#[cgp_component]— turns the trait into a component: its argument names the provider traitAsyncComputerRefthat implementations target and the wiring keyAsyncComputerRefComponent, whileCanComputeAsyncRefstays the consumer trait callers use.#[prefix]— registers the component inDefaultNamespaceunder the path@cgp.extra.handler, so a context that joins that namespace binds its provider at@cgp.extra.handler.AsyncComputerRefComponentrather than at the bare key.#[derive_delegate]— generates the legacyUseDelegateandUseInputDelegateproviders, which dispatch on theCodetag and on theInputtype through an inner table; theopenstatement 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.
Related constructs
AsyncComputer— the owned-input counterpart.ComputerRef— the synchronous by-reference computer.HandlerRef— the fallible async by-reference member.- Handler combinators —
PromoteRefand the promotion bundles.
The ideas behind it:
- Handlers — the computation family and its sync, async, fallible, and input-passing axes.
Source
AsyncComputerandAsyncComputerRef:async_computer.rsPromoteRef:promote_ref.rs- Re-exported through
cgp::extra::handler.
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.