Skip to main content

PromoteHandler

Fill in the async fallible members of the handler family from an AsyncComputer whose output is a Result.

info

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.

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.