TryComputerRef
The by-reference member of the handler family's fallible corner: a
TryComputer that borrows its input.
Overview
In Context-Generic Programming (CGP), TryComputerRef is a
TryComputer that takes its input by reference. CGP enables pluggable trait
implementations in Rust, and TryComputerRef is the component that lets a context plug in a
fallible computation that reads its input. A
synchronous computation that can fail and only reads its argument fits it: its method receives
&Input and returns Result<Output, Error>, where Error is the abstract error type of the
context, the type the implementation runs against. It
differs from TryComputer on the input axis alone.
Because it can fail, it has HasErrorType as a
supertrait, which supplies the Error it names in its
Result and ties it to the same error every other fallible component in the context uses. See the
handler family overview for how the members relate and promote.
Definition
CanTryComputeRef is defined as:
#[cgp_component(TryComputerRef)]
#[prefix(@cgp.extra.handler in DefaultNamespace)]
#[derive_delegate(UseDelegate<Code>)]
#[derive_delegate(UseInputDelegate<Input>)]
#[use_type(HasErrorType.Error)]
pub trait CanTryComputeRef<Code, Input> {
type Output;
fn try_compute_ref(
&self,
_code: PhantomData<Code>,
input: &Input,
) -> Result<Self::Output, Error>;
}
Its attributes:
#[cgp_component]— turns the trait into a component: its argument names the provider traitTryComputerRefthat implementations target and the wiring keyTryComputerRefComponent, whileCanTryComputeRefstays 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.TryComputerRefComponentrather 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.#[use_type]— addsHasErrorTypeas a supertrait and rewrites the bareErrorto<Self as HasErrorType>::Error.
Usage
TryComputerRefComponent, the provider trait TryComputerRef, and the consumer trait
CanTryComputeRef are not in the prelude, and are imported from cgp::extra::handler. The method
borrows the input and returns a Result:
fn try_compute_ref(&self, _code: PhantomData<Code>, input: &Input) -> Result<Self::Output, Error>;
A context gains the operation by wiring TryComputerRefComponent to a provider and by wiring an
error type, and the component dispatches on both the Code tag and the Input type. Besides a
hand-written provider, the PromoteRef combinator answers
it from a TryComputer written for &'a Input at every lifetime, and in the
other direction lets a TryComputerRef provider answer try_compute 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 parses a port number from a borrowed setting, raising the parse error into the context's error:
use core::marker::PhantomData;
use core::num::ParseIntError;
use cgp::extra::handler::{CanTryComputeRef, TryComputerRef, TryComputerRefComponent};
use cgp::prelude::*;
use cgp::core::error::{ErrorRaiserComponent, ErrorTypeProviderComponent};
use cgp::extra::error::RaiseFrom;
#[cgp_impl(new ParsePort)]
#[uses(CanRaiseError<ParseIntError>)]
#[use_type(HasErrorType.Error)]
impl<Code> TryComputerRef<Code, String> {
type Output = u16;
fn try_compute_ref(
&self,
_code: PhantomData<Code>,
input: &String,
) -> Result<Self::Output, Error> {
input.trim().parse().map_err(Self::raise_error)
}
}
#[derive(Debug, PartialEq)]
pub struct AppError(pub String);
impl From<ParseIntError> for AppError {
fn from(e: ParseIntError) -> Self {
AppError(e.to_string())
}
}
pub struct App;
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<AppError>,
ErrorRaiserComponent: RaiseFrom,
TryComputerRefComponent: ParsePort,
}
}
check_components! {
App {
TryComputerRefComponent: ((), String),
}
}
pub fn demo() {
let setting = " 8080 ".to_owned();
assert_eq!(App.try_compute_ref(PhantomData::<()>, &setting), Ok(8080));
assert!(App.try_compute_ref(PhantomData::<()>, &"http".to_owned()).is_err());
}
try_compute_ref reads setting without taking it, so the caller still owns it afterwards. App
is an environmental context, and the component is
parameter-targeted: the computation
acts on the Input, while App decides the provider and the error type.
When to use it
Reach for TryComputerRef when a fallible synchronous computation only needs to read its input.
It keeps ownership with the caller while still reporting failure through the context's error type.
Reach for TryComputer instead when the computation takes the input by value,
for ComputerRef when a borrowed-input computation cannot fail, and for
HandlerRef when it must also await.
Related constructs
TryComputer— the owned-input counterpart.ComputerRef— the infallible by-reference computer.HandlerRef— the async and fallible by-reference member.HasErrorType— the supertrait supplying theErrorthis returns.CanRaiseError— converts a concrete source error into that abstract error.PromoteRef— bridges the owned and borrowed forms.
The ideas behind it:
- Handlers — the computation family and its sync, async, fallible, and input-passing axes.
- Modular error handling — the abstract error a fallible computer returns.
Source
TryComputerandTryComputerRef:try_compute.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.