The handler family
In Context-Generic Programming (CGP), the handler family models a computation as a
swappable component, so a pipeline step, an I/O call, or a type-level interpreter is wired and
composed the same way as any other component. Every member
turns an Input into an Output under a phantom Code tag, against a
context, the type the implementation runs against. The
members differ along three axes: synchronous or async, infallible or fallible, and taking the input
by value, by reference, or not at all. This page maps the family; each member has its own page for
the full detail.
The one distinction that organizes the rest is which corner of those axes a member sits in.
Computer is the simplest, a synchronous transform that cannot fail.
TryComputer adds a failure path, returning a Result in the context's
abstract error type. AsyncComputer makes the computer async instead, and
Handler is both async and fallible, the most general corner.
Producer is the odd one out on the input axis: it takes no input and yields a
value from the context and a Code tag alone.
The family is built to be written from its narrowest member and promoted outward. A Computer
promotes into a TryComputer by wrapping its output in Ok, into an AsyncComputer by running
inside an async method, and into a Handler in two such steps. A Producer promotes into a
Computer by ignoring the input it is given. A by-reference member answers the owned-input one by
dereferencing the input, and the reverse works only for a provider that takes the borrow as its
input. Promotion never removes a failure path or an await, so a provider author implements the
narrowest member that fits and lets the wiring lift it where a more capable one is required. Generic
code bounded by CanHandle therefore accepts a provider written for any owned-input member, once
the context wires the matching promotion.
The family has nine members in all, because each of the four input-taking corners carries a
by-reference sibling, a component of its own whose method takes &Input:
Computer with ComputerRef,
AsyncComputer with AsyncComputerRef,
TryComputer with TryComputerRef, and
Handler with HandlerRef. Producer has no
such sibling, because it has no input to borrow, and no async one either. The variant pages lean on
their base member for the shared model.
Every member of the family is imported from cgp::extra::handler: the consumer traits
(CanCompute, CanTryCompute, CanHandle, CanProduce, and their siblings), the provider traits,
their wiring keys, the promotion bundles, and the one-step promotion providers. The prelude carries
only the macros that define handlers, #[cgp_computer], #[cgp_producer], and
#[cgp_auto_dispatch]. A provider written with #[cgp_impl] on Computer also needs
ComputerComponent in scope, because the macro names the key the trait belongs to, unless its header
names the trait by path, as impl<Code> cgp::extra::handler::Computer<Code, u64>; see
Importing the component key.
Two wiring details apply to every member. Because a context that delegates a member also implements
its provider trait, calling a method on a concrete context by its bare name, as
App::compute(&App, …), is ambiguous (E0034) whenever the consumer trait and that provider trait
are both in scope; method syntax, App.compute(…), is not. Every member registers under
@cgp.extra.handler in DefaultNamespace, so a context that joins that namespace binds a member at
a path such as @cgp.extra.handler.ComputerComponent, since a bare-key entry would conflict with
the namespace's own (E0119).
You rarely implement a member of this family by hand. Providers come from
#[cgp_computer] and
#[cgp_producer], which turn a plain function into a provider and
wire it to a promotion bundle, so one function answers the rest of the family, and they are composed
and routed with the handler combinators, the dispatch
combinators, and the monad
providers. A fallible member has
HasErrorType as a supertrait, and
an effectful one reaches the runtime through HasRuntime.
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.