PipeHandlers
Compose a type-level list of handlers into a single pipeline, threading each stage's output into the next.
Overview
Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and
PipeHandlers<Providers> generalizes ComposeHandlers from two handlers to
a list of them. It takes a Product! list of providers and folds the
whole pipeline into one nested ComposeHandlers, so the input flows through each stage in turn, on
one context, the type the implementation runs against. It is
the combinator to reach for when wiring a multi-stage transformation: list the stages in order and
let PipeHandlers build the composition. Like every CGP provider, it carries no runtime value; the
list rides in PhantomData.
Usage
Import it from cgp::extra::handler; it is not in the prelude. It takes one type parameter, a
Product! list of handler providers:
use cgp::extra::handler::PipeHandlers;
delegate_components! {
App {
ComputerComponent: PipeHandlers<Product![Double, AddOne, Double]>,
}
}
The list runs left to right: Double, then AddOne on its output, then Double again. Each
stage's output type must match the next stage's input type. Because the fold is generic over the
component key, one list of two or more stages serves as a Computer, TryComputer,
AsyncComputer, or Handler, whichever the wiring asks for, as long as every stage supports that
shape; the fold's ComposeHandlers has no …Ref impl. A one-element list is that element, and an
empty list provides nothing.
Examples
A pipeline of field-reading computers over a context, where Multiply<Field> and Add<Field> read
a factor or an addend from a context field:
use cgp::core::field::traits::HasField;
use cgp::core::field::types::Field;
use cgp::extra::handler::{CanCompute, Computer, ComputerComponent, PipeHandlers};
use cgp::prelude::*;
#[cgp_new_provider]
impl<Context, Code, Field> Computer<Context, Code, u64> for Multiply<Field>
where
Context: HasField<Field, Value = u64>,
{
type Output = u64;
fn compute(context: &Context, _code: PhantomData<Code>, input: u64) -> u64 {
input * context.get_field(PhantomData)
}
}
#[cgp_new_provider]
impl<Context, Code, Field> Computer<Context, Code, u64> for Add<Field>
where
Context: HasField<Field, Value = u64>,
{
type Output = u64;
fn compute(context: &Context, _code: PhantomData<Code>, input: u64) -> u64 {
input + context.get_field(PhantomData)
}
}
#[derive(HasField)]
pub struct MyContext {
pub foo: u64,
pub bar: u64,
pub baz: u64,
}
delegate_components! {
MyContext {
ComputerComponent:
PipeHandlers<Product![
Multiply<Symbol!("foo")>,
Add<Symbol!("bar")>,
Multiply<Symbol!("baz")>,
]>,
}
}
check_components! {
MyContext {
ComputerComponent: ((), u64),
}
}
pub fn demo() {
let context = MyContext { foo: 2, bar: 3, baz: 4 };
assert_eq!(context.compute(PhantomData::<()>, 5), 52); // ((5 * 2) + 3) * 4
}
The list folds to ComposeHandlers<Multiply<…>, ComposeHandlers<Add<…>, Multiply<…>>>. MyContext
is a value context: each stage reads one of its fields.
Stages of mismatched shapes can be reconciled inline, as in
PromoteAsync<Promote<Add<Symbol!("bar")>>>, which lifts a plain Computer stage to the async
Handler shape a Handler pipeline asks for; the context then also needs an error type.
When to use it
Reach for PipeHandlers to compose three or more handlers, or any time a list reads better than
nesting ComposeHandlers by hand. For exactly two, ComposeHandlers is the
plainer choice.
For a pipeline whose stages should stop on a branch of their output, such as an Err value or the
first success, rather than feed every output to the next stage, use
PipeMonadic, the monadic generalization;
PipeMonadic<IdentMonadic, …> reduces to PipeHandlers.
Under the hood
PipeHandlers carries the list in PhantomData and holds no handler impls of its own:
pub struct PipeHandlers<Providers>(pub PhantomData<Providers>);
Instead it delegates every component key to whatever single provider the list folds down to,
computed by an internal ComposeProviders trait that walks the Cons/Nil list. A one-element
list folds to that provider unchanged, and a list Cons<ProviderA, rest> folds to
ComposeHandlers<ProviderA, fold(rest)>:
delegate_components! {
<Component, Provider, Providers: ComposeProviders<Provider = Provider>>
PipeHandlers<Providers> {
Component: Provider,
}
}
Because the delegation is generic over the Component key, the same pipeline answers whichever
handler shape the wiring asks for.
Related constructs
ComposeHandlers— the two-handler combinator this folds a list into.ReturnInput— the identity stage, which leaves a pipeline unchanged.Product!— the type-level list of stages.PipeMonadic— the monadic pipeline that adds short-circuiting.Computer,Handler— the family a pipeline implements.
The ideas behind it:
- Handlers — the computation family and its composition.
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.