Skip to main content

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 trait TryComputerRef that implementations target and the wiring key TryComputerRefComponent, while CanTryComputeRef 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.TryComputerRefComponent 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.
  • #[use_type] — adds HasErrorType as a supertrait and rewrites the bare Error to <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.

  • TryComputer — the owned-input counterpart.
  • ComputerRef — the infallible by-reference computer.
  • HandlerRef — the async and fallible by-reference member.
  • HasErrorType — the supertrait supplying the Error this 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​


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.