Computer
The synchronous, infallible member of the handler family, and the simplest provider to write.
Overview
In Context-Generic Programming (CGP), Computer is for computations that always succeed.
CGP enables pluggable trait implementations in Rust, and Computer is the component that lets a
context plug in an infallible computation. Adding two numbers, formatting a value, or
projecting a field never fails, so returning a Result and requiring an error type would be noise.
A Computer provider names an Output type and produces it from the
context (the type the implementation runs against), a
phantom Code tag naming which computation is wanted, and an Input, with no failure path.
It is the member of the handler family a provider author reaches for
first, because promotion runs one way. The handler combinators
lift a Computer into the fallible and async members by wrapping its output in Ok or its call in
an async method, while a fallible or async provider never loses its failure path or its await.
Writing the narrowest member that fits keeps a provider usable in the most positions.
Definition
CanCompute is defined as:
#[cgp_component(Computer)]
#[prefix(@cgp.extra.handler in DefaultNamespace)]
#[derive_delegate(UseDelegate<Code>)]
#[derive_delegate(UseInputDelegate<Input>)]
pub trait CanCompute<Code, Input> {
type Output;
fn compute(&self, _code: PhantomData<Code>, input: Input) -> Self::Output;
}
Its attributes:
#[cgp_component]— turns the trait into a component: its argument names the provider traitComputerthat implementations target and the wiring keyComputerComponent, whileCanComputestays 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.ComputerComponentrather 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
Computer, ComputerComponent, and the consumer trait CanCompute are all imported from
cgp::extra::handler, since the prelude leaves out the handler family. The consumer method takes
the context, a PhantomData<Code> naming which computation is wanted, and the Input by value, and
returns the associated Output:
fn compute(&self, _code: PhantomData<Code>, input: Input) -> Self::Output;
A context gains the operation by wiring ComputerComponent to a provider. Three sources supply one:
#[cgp_computer]turns a plain function such asfn double(input: u64) -> u64into aComputerprovider, and wires that provider to a promotion bundle so it answers the other members too.- The handler combinators build a computer from other
providers:
ReturnInputreturns its input,PipeHandlersandComposeHandlerschain computers, andPromotelifts aProducerinto aComputer. UseField<Tag>forwards the computation to the value stored in the context'sTagfield, which must itself implementCanCompute.
Wiring a component to a promotion bundle such as
PromoteComputer<Double> lifts a Computer into
the other members. The bundle wraps the output in Ok for TryComputer and
runs the computation inside an async method for AsyncComputer. Its
by-reference entries pass the borrow &Input through as the input, so they work only for a provider
written for &'a Input at every lifetime: a computer over an owned u64 answers compute,
try_compute, and compute_async, but not compute_ref. A fallible function written with
#[cgp_computer] becomes a Computer whose Output is the Result, and
TryPromote reads that Result as the failure path of a
TryComputer.
A context that joins DefaultNamespace binds the provider at the component's prefixed path, since a
bare ComputerComponent entry would conflict with the namespace's own entry for that key (E0119):
delegate_components! {
App {
namespace DefaultNamespace;
@cgp.extra.handler.ComputerComponent: Double,
}
}
The component has three siblings, each differing from Computer on one axis and documented on its
own page: ComputerRef borrows the input,
AsyncComputer is async, and AsyncComputerRef
is both. None of the four has HasErrorType as a
supertrait, because none of them can fail.
Examples
A computer provider that doubles its input, wired into a context directly and, through promotion, as a fallible computer:
use core::marker::PhantomData;
use cgp::extra::handler::{CanCompute, CanTryCompute, PromoteComputer};
use cgp::extra::handler::{Computer, ComputerComponent, TryComputer, TryComputerComponent};
use cgp::prelude::*;
use cgp::core::error::ErrorTypeProviderComponent;
#[cgp_new_provider]
impl<Context, Code> Computer<Context, Code, u64> for Double {
type Output = u64;
fn compute(_context: &Context, _code: PhantomData<Code>, input: u64) -> u64 {
input * 2
}
}
pub struct App;
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
ComputerComponent: Double,
TryComputerComponent: PromoteComputer<Double>,
}
}
check_components! {
App {
[ComputerComponent, TryComputerComponent]: ((), u64),
}
}
pub fn demo() {
assert_eq!(App.compute(PhantomData::<()>, 21), 42);
assert_eq!(App.try_compute(PhantomData::<()>, 21), Ok(42));
}
Double implements the Computer provider trait for any context and any Code, with u64 as both
input and output. App is an environmental
context with no fields, and the component is
parameter-targeted: the computation
acts on the Input value, while App decides the provider. App wires ComputerComponent to
Double, so compute returns 42, and wires TryComputerComponent through the PromoteComputer
bundle, so try_compute returns Ok(42). The fallible member needs an error type, which App sets
to String with ErrorTypeProviderComponent, imported from cgp::core::error. In practice
#[cgp_computer] writes Double from
fn double(input: u64) -> u64 and wires every promotion itself.
When to use it
Reach for Computer for a synchronous transform that cannot fail. It is the default member of
the family to implement, because promotion lifts it into the fallible and async members, so one
Computer provider can answer a fallible or async bound elsewhere in the wiring. Prefer
ComputerRef when the computation only reads its input, and
AsyncComputer when it must await but still cannot fail.
Reach for TryComputer instead when the computation can fail, for
Handler when it is both async and fallible, and for Producer
when it takes no input. A computation that reads its context's fields, names an abstract type, or
calls another trait of the context is written as a provider with
#[cgp_impl], since a #[cgp_computer] function cannot reach its
context.
Common Mistakes
Calling compute on a concrete context by its bare name is ambiguous. A context that delegates
ComputerComponent also implements the Computer provider trait, so in a module that imports both
CanCompute and Computer, App::compute(&App, PhantomData::<()>, 21) has two candidates:
error[E0034]: multiple applicable items in scope
--> src/main.rs:25:18
|
25 | let _ = App::compute(&App, PhantomData::<()>, 21);
| ^^^^^^^ multiple `compute` found
|
= note: candidate #1 is defined in an impl of the trait `CanCompute` for the type `__Context__`
= note: candidate #2 is defined in an impl of the trait `Computer` for the type `__Provider__`
Use method syntax, as in App.compute(PhantomData::<()>, 21), since only the consumer trait takes
self, or name the consumer trait, as in
<App as CanCompute<(), u64>>::compute(&App, PhantomData, 21). The same holds for every member of
the family whose consumer and provider traits are both in scope.
Related constructs
ComputerRef— the by-reference variant that borrows its input.AsyncComputer— the async variant that awaits.AsyncComputerRef— the async, by-reference variant.TryComputer— the fallible synchronous counterpart.Handler— the async and fallible member.Producer— the input-free member of the family.#[cgp_computer]— builds aComputerprovider from a plain function.- Handler combinators — compose computers and promote them into the other members.
UseField— the built-in computer provider that forwards to a context field.
The ideas behind it:
- Handlers — the computation family and its sync, async, fallible, and input-passing axes.
- Dispatching — routing a computation on its
CodeorInput.
Source
- The synchronous computers
Computer/ComputerRef, and theUseFieldcomputer:computer.rs - The async computers
AsyncComputer/AsyncComputerRef:async_computer.rs - The promotion bundles:
promote_all.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.