Handler combinators
The providers that build, sequence, and adapt handlers: composing them end to end, running a list in sequence, returning the input unchanged, and lifting one handler shape into another.
Overviewβ
Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and the
handler combinators work across the family of traits that model computation. That family is not one
trait but several related ones, and code is rarely written against all of them at once. A provider
author writes a plain synchronous Computer, a fallible
TryComputer, or an async
Handler, depending on the computation. The combinators let
those single-shape providers be wired where a different shape is expected, and let several providers
be glued into a larger one, on a context, the type the
implementation runs against. Like every CGP provider, each combinator is zero-sized: its type
parameters ride in PhantomData.
Every combinator here, the promotion bundles included, is imported from cgp::extra::handler, as
are the consumer traits such as CanCompute that call them.
The handler familyβ
Every combinator is defined in terms of the handler component traits, so a short orientation helps.
The family shares one method signature: a context reference, a PhantomData<Code> tag selecting the
operation, and an input, producing an associated Output. The members differ on two axes:
Computeris synchronous and infallible.TryComputeris synchronous and fallible, and requires the context to have an error type.AsyncComputeris asynchronous and infallible.Handleris asynchronous and fallible, the most general member.Producertakes no input.
Each of the first four has a β¦Ref companion whose method takes the input by reference. The
promotion combinators trade on the natural orderings among these: a Computer is also a valid
TryComputer and a valid AsyncComputer, and a TryComputer or an AsyncComputer is a valid
Handler. A by-reference handler serves a by-value slot by dereferencing the input, and a by-value
handler serves a by-reference slot only when it accepts the borrow as its input.
The combinators, by roleβ
Composition feeds one handler's output into the next:
ComposeHandlersruns two handlers back to back.PipeHandlersgeneralizes that to a type-level list of handlers.
Identity is the neutral element of composition:
ReturnInputpasses its input straight through.
Promotion lifts one handler shape into another in a single step, so one written implementation satisfies another trait:
Promotelifts aProducerto aComputer, and an infallible member to a fallible one.PromoteAsynclifts a synchronous member into an asynchronous one.PromoteRefbridges by-value and by-reference members, in both directions.TryPromotebridges aResult-valued output and a fallible trait, in both directions.
A lift of two steps chains them, as PromoteAsync<Promote<P>> makes a Handler from a Computer.
Promotion bundles wire a whole cluster of handler components to the right single-step promotion
at once, so a provider author implements one trait and gets the rest of the family. These are what
#[cgp_computer] and
#[cgp_producer] wire a generated provider to:
PromoteComputer,PromoteTryComputer,PromoteProducer,PromoteAsyncComputer, andPromoteHandler, one per base.
A bundle's entries that take one step from the base serve any provider, but an entry that takes its step from a sibling component works only for a provider wired to that same bundle, as the macros wire theirs. Each bundle page says which entries are which.
Input dispatch chooses a handler by the type of the value:
UseInputDelegatekeys a lookup table on the handler'sInputtype. It is the legacy form; theopenstatement ofdelegate_components!dispatches on the input directly.
Related constructsβ
Computer,TryComputer,Handler,Producerβ the components these providers implement.#[cgp_computer]and#[cgp_producer]β generate a single-trait provider and wire the rest of the family through the promotion bundles.Product!β the type-level listPipeHandlerscomposes.UseDelegateβ theCode-keyed sibling ofUseInputDelegate.
The ideas behind it:
- Handlers β the computation family and its sync, async, fallible, and input-passing axes.
Sourceβ
- The combinators are in
cgp-handlerunderproviders/, andUseInputDelegateintypes.rs.
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.