PromoteHandler
Fill in the async fallible members of the handler family from an AsyncComputer whose output is a
Result.
Generated machinery
You are not expected to name PromoteHandler directly.
#[cgp_computer] wires the provider it generates for an async fn
returning Result to PromoteHandler<Self>. A context names the bundle to route its own components
through such a provider, or through its HandlerComponent entry, which serves any AsyncComputer
returning Result. This page explains what the bundle emits.
Overview
Context-Generic Programming (CGP) lets one provider answer several related trait calls
through wiring, and PromoteHandler<Provider> starts from an AsyncComputer whose output is a
Result over the context's error type, the base #[cgp_computer] builds for an async fn
returning Result. It fills in the fallible async members on a
context, the type the implementation runs against. Despite
its name, its base is not a Handler: it produces the Handler by reading the base's Result as
the failure path. Like every CGP provider, it carries no runtime value.
Usage
It is not in the prelude; import it from cgp::extra::handler. It takes one type parameter, the
base provider:
delegate_components! {
App {
HandlerComponent: PromoteHandler<CheckedDouble>,
}
}
It also answers AsyncComputerRefComponent, for a base whose input is a borrow, and
HandlerRefComponent, which needs that base wired to the bundle as #[cgp_computer] wires it. A
base over an owned u64 answers only HandlerComponent.
Examples
An async #[cgp_computer] function returning Result answers handle through the bundle:
use cgp::extra::handler::{CanHandle, PromoteHandler};
use cgp::extra::handler::{Handler, HandlerComponent};
use cgp::prelude::*;
use cgp::core::error::ErrorTypeProviderComponent;
#[cgp_computer]
pub async fn checked_double(value: u64) -> Result<u64, String> {
value.checked_mul(2).ok_or_else(|| "overflow".to_owned())
}
pub struct App;
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
HandlerComponent: PromoteHandler<CheckedDouble>,
}
}
check_components! {
App {
HandlerComponent: ((), u64),
}
}
pub async fn demo() {
let code = PhantomData::<()>;
assert_eq!(App.handle(code, 21).await, Ok(42));
assert_eq!(App.handle(code, u64::MAX).await, Err("overflow".to_owned()));
}
The function's error type is String, which must equal App's, since TryPromote passes the Err
through unconverted. App is an
environmental context.
When to use it
Reach for PromoteHandler when the base is an AsyncComputer returning Result, generated
from an async fn or written by hand. For an infallible async base use
PromoteAsyncComputer, and for a synchronous base the bundle that
matches it: PromoteComputer,
PromoteTryComputer, or PromoteProducer.
Under the hood
PromoteHandler is a delegate_components! table over a
generic inner Provider:
delegate_components! {
<Provider>
new PromoteHandler<Provider> {
HandlerComponent: TryPromote<Provider>,
[
AsyncComputerRefComponent,
HandlerRefComponent,
] ->
PromoteAsyncComputer<Provider>,
}
}
It routes HandlerComponent to TryPromote, whose Handler impl reads an
AsyncComputer returning Result as a fallible handler, one step from the base, so it serves a
hand-written base too. The by-reference members forward to
PromoteAsyncComputer's entries, which route through
PromoteRef.
Related constructs
PromoteAsyncComputer— the bundle this forwards its by-reference members to.TryPromote— the lift it routes the handler slot through.PromoteComputer,PromoteTryComputer,PromoteProducer— the bundles for the synchronous bases.Handler— the family member it produces.
The ideas behind it:
- Handlers — the family and its most general member.
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.