Skip to main content

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:

  • Computer is synchronous and infallible.
  • TryComputer is synchronous and fallible, and requires the context to have an error type.
  • AsyncComputer is asynchronous and infallible.
  • Handler is asynchronous and fallible, the most general member.
  • Producer takes 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:

Identity is the neutral element of composition:

Promotion lifts one handler shape into another in a single step, so one written implementation satisfies another trait:

  • Promote lifts a Producer to a Computer, and an infallible member to a fallible one.
  • PromoteAsync lifts a synchronous member into an asynchronous one.
  • PromoteRef bridges by-value and by-reference members, in both directions.
  • TryPromote bridges a Result-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:

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:

  • UseInputDelegate keys a lookup table on the handler's Input type. It is the legacy form; the open statement of delegate_components! dispatches on the input directly.

The ideas behind it:

  • Handlers β€” the computation family and its sync, async, fallible, and input-passing axes.

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.