Producer
The input-free member of the handler family: a synchronous, infallible source of a value.
Overview
In Context-Generic Programming (CGP), Producer is for computations that take no input
and yield a value. CGP enables pluggable trait implementations in Rust, and Producer is the
component that lets a context plug in an input-free computation. A default configuration, a
constant, or a value read entirely from the context (the
type the implementation runs against) has no Input to transform: it needs only the context and a
phantom Code tag naming which value to produce. The rest of the handler
family threads an Input through every method, and Producer is the case
where that input is absent. It is synchronous and infallible, and returns its Output directly.
A producer still feeds the rest of the family. Promotion turns it into a
Computer that ignores whatever input it is given, and from there into the other
members, which is how a constant or a context-derived value enters a pipeline of input-taking
handlers.
Definition
CanProduce is defined as:
#[cgp_component(Producer)]
#[prefix(@cgp.extra.handler in DefaultNamespace)]
#[derive_delegate(UseDelegate<Code>)]
pub trait CanProduce<Code> {
type Output;
fn produce(&self, _code: PhantomData<Code>) -> Self::Output;
}
Its attributes:
#[cgp_component]— turns the trait into a component: its argument names the provider traitProducerthat implementations target and the wiring keyProducerComponent, whileCanProducestays 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.ProducerComponentrather than at the bare key.#[derive_delegate]— generates the legacyUseDelegateprovider, which dispatches on theCodetype through an inner table; theopenstatement replaces it. There is noUseInputDelegate, since there is no input.
Usage
Producer, ProducerComponent, and the consumer trait CanProduce are imported from
cgp::extra::handler. The consumer method takes only the context and a Code tag,
with no Input:
fn produce(&self, _code: PhantomData<Code>) -> Self::Output;
A context gains the operation by wiring ProducerComponent to a provider. The component dispatches
on the Code tag alone, and it has no by-reference or async sibling, since there is no input to
borrow.
In everyday use the provider comes from #[cgp_producer], which
turns a zero-argument function into a Producer provider and wires that provider to the
PromoteProducer<Self> bundle. So a context can wire
any member of the family to it directly, and each member returns the produced value whatever input
it is given:
#[cgp_producer]
fn default_port() -> u16 {
8080
}
delegate_components! {
App {
ErrorTypeProviderComponent: UseType<String>,
[ComputerComponent, HandlerComponent]: DefaultPort,
}
}
The fallible members need the context's error type to form their Result, which is why App wires
ErrorTypeProviderComponent, but they always return Ok. A #[cgp_producer] function cannot reach
its context, since it has no parameters, so a producer that reads a field or calls another trait of
the context is a provider written with #[cgp_impl].
Examples
A producer wired into a context and invoked directly:
use core::marker::PhantomData;
use cgp::extra::handler::{Producer, ProducerComponent};
use cgp::prelude::*;
use cgp::extra::handler::CanProduce;
#[cgp_new_provider]
impl<Context, Code> Producer<Context, Code> for MagicNumber {
type Output = u64;
fn produce(_context: &Context, _code: PhantomData<Code>) -> u64 {
42
}
}
pub struct App;
delegate_components! {
App {
ProducerComponent: MagicNumber,
}
}
check_components! {
App {
ProducerComponent: (),
}
}
pub fn demo() {
assert_eq!(App.produce(PhantomData::<()>), 42);
}
MagicNumber produces 42 for any context and any Code, and App delegates ProducerComponent
to it. App is an environmental context, and the
component is self-targeted: there is no
input to act on, so the operation describes the context itself, and Code is a
selector naming which value is wanted.
When to use it
Reach for Producer for a value that a computation needs but does not compute from an input,
such as a constant, a default, or a value read from the context. It is the family's source, and
promotion lets one producer feed the input-taking members, so a producer can seed a pipeline such as
PipeHandlers<Product![DefaultPort, …]>.
Reach for Computer instead when the value is computed from an input, and for
TryComputer or Handler when producing it can fail or must
await. A #[cgp_producer] function returning a Result is not a fallible producer: the fallible
members wrap the whole Result in Ok, so an Err short-circuits nothing downstream.
Common Mistakes
PromoteProducer<P> answers the fallible and async members only when P is wired to it. Its
ComputerComponent entry works for any producer, but its other entries reach P through P's own
Computer wiring. So a context that wires TryComputerComponent to PromoteProducer<MagicNumber>,
for the hand-written MagicNumber above, fails at the check:
error[E0277]: the trait bound `MagicNumber: DelegateComponent<ComputerComponent>` is not satisfied
...
= note: required for `MagicNumber` to implement `Computer<App, (), ()>`
= note: required for `Promote<MagicNumber>` to implement `IsProviderFor<TryComputerComponent, App, ((), ())>`
Write the producer with #[cgp_producer], which wires it to
PromoteProducer<Self>, or wire the hand-written producer to that bundle yourself, as the macro
does.
Related constructs
Computer— the synchronous input-taking member; a producer promotes into it.TryComputer— the fallible member of the family.Handler— the general async and fallible member.#[cgp_producer]— builds aProducerprovider from a zero-argument function.PromoteProducer— the bundle that lifts a producer into the rest of the family.Promote— the one-step lift from a producer to a computer.
The ideas behind it:
- Handlers — the computation family and its sync, async, fallible, and input-passing axes.
Source
Producer:produce.rsPromote:promote.rs- The
PromoteProducerbundle: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.