Skip to main content

UseDelegate

Dispatch a generic-parameter component to a different inner provider per type, through a lookup table. Superseded by the open statement.

info

Legacy — read, don't write​

UseDelegate, the #[derive_delegate] attribute that generates its provider impl, and its nested-table wiring are the older way to choose a provider per type. The open statement of delegate_components! does the same job through the RedirectLookup impl every #[cgp_component] already has, with no separate table type and no wrapper.

Prefer open for anything new. This page is here because you will meet UseDelegate in existing code and in the library's own error and handler components, which are still defined with #[derive_delegate]. It is expected to be deprecated once open is shown to cover every dispatch case.

Overview​

Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and UseDelegate chooses a provider based on a type argument rather than on the component alone. An ordinary component picks its provider by looking the component name up in the context's delegation table, where the context is the type the implementation runs against. But when a provider trait carries an extra generic parameter, such as a SourceError to convert or a Shape to measure, the right provider often depends on which concrete type that parameter is. UseDelegate performs a second lookup: it treats one generic parameter as a key and reads the matching inner provider out of a table, so a single wiring entry can fan out to many type-specific providers.

This lets context-generic providers stay generic even when their implementations would otherwise overlap on a parameter. Rather than one provider matching every possible Shape, you write a small provider per shape and let UseDelegate route each concrete shape to its own. The dispatch is type-directed: the key is a real type appearing in the trait, and the table maps that type to the provider responsible for it. Like every CGP provider, UseDelegate holds no runtime value; the Components table is carried in PhantomData.

Usage​

UseDelegate is in the prelude, so use cgp::prelude::*; is enough. It takes one type parameter, the lookup table, and is most often written with an inline nested table using the new keyword:

delegate_components! {
MyApp {
AreaCalculatorComponent:
UseDelegate<new AreaCalculatorComponents {
Rectangle: RectangleArea,
Circle: CircleArea,
}>,
}
}

The new keyword declares the inner table AreaCalculatorComponents in place and maps each concrete type to its provider. The component must be defined with a #[derive_delegate(UseDelegate<Param>)] attribute naming the parameter to dispatch on, which generates the UseDelegate provider impl that reads the table.

Examples​

UseDelegate is wired through a nested table that builds both the outer entry and the inner lookup in one place. Given an area component that dispatches on a Shape parameter:

use cgp::prelude::*;

#[cgp_component(AreaCalculator)]
#[derive_delegate(UseDelegate<Shape>)]
pub trait CanCalculateArea<Shape> {
fn area(&self, shape: &Shape) -> f64;
}

pub struct Rectangle {
pub width: f64,
pub height: f64,
}

pub struct Circle {
pub radius: f64,
}

#[cgp_impl(new RectangleArea)]
impl AreaCalculator<Rectangle> {
fn area(&self, shape: &Rectangle) -> f64 {
shape.width * shape.height
}
}

#[cgp_impl(new CircleArea)]
impl AreaCalculator<Circle> {
fn area(&self, shape: &Circle) -> f64 {
core::f64::consts::PI * shape.radius * shape.radius
}
}

pub struct MyApp;

delegate_components! {
MyApp {
AreaCalculatorComponent:
UseDelegate<new AreaCalculatorComponents {
Rectangle: RectangleArea,
Circle: CircleArea,
}>,
}
}

check_components! {
MyApp {
AreaCalculatorComponent: [Rectangle, Circle],
}
}

pub fn demo() {
assert_eq!(MyApp.area(&Rectangle { width: 2.0, height: 3.0 }), 6.0);
}

The wiring reads in two layers. MyApp delegates AreaCalculatorComponent to UseDelegate<AreaCalculatorComponents>, so its area calculation routes through UseDelegate using that table. The inner table maps the Rectangle type to RectangleArea and the Circle type to CircleArea. The result is that MyApp implements CanCalculateArea<Rectangle> through RectangleArea and CanCalculateArea<Circle> through CircleArea, with UseDelegate selecting between them by the Shape argument. Adding a shape is one more entry in the inner table. MyApp is an environmental context, and the component is parameter-targeted: it measures the Shape, while MyApp decides which provider measures each one.

The same dispatch, written with open for new code, folds the entries into the context's own table:

delegate_components! {
MyApp {
open AreaCalculatorComponent;

@AreaCalculatorComponent.Rectangle: RectangleArea,
@AreaCalculatorComponent.Circle: CircleArea,
}
}

When to use it​

Prefer the open statement for new per-type dispatch. It needs no separate table type, no UseDelegate wrapper, and no #[derive_delegate] on the component, because it rides the RedirectLookup impl every component already generates.

Read UseDelegate when you meet it in existing code, and keep using it where a component is still defined with #[derive_delegate], including CGP's own error and handler families. The dispatching-per-type choice is worked through in #[derive_delegate].

For dispatching on the input type of a handler rather than a Code parameter, the legacy sibling provider is UseInputDelegate. The open statement covers that case too, with a key that has one path segment per type parameter.

Under the hood​

The #[derive_delegate(UseDelegate<Param>)] attribute on a component generates the UseDelegate provider impl, which uses Components as the table and the named parameter as the key. For the CanCalculateArea<Shape> component above, with its #[derive_delegate(UseDelegate<Shape>)] attribute, cargo cgp expand shows:

impl<__Context__, Shape, __Components__, __Delegate__> AreaCalculator<__Context__, Shape>
for UseDelegate<__Components__>
where
__Components__: DelegateComponent<(Shape), Delegate = __Delegate__>,
__Delegate__: AreaCalculator<__Context__, Shape>,
{
fn area(__context__: &__Context__, shape: &Shape) -> f64 {
__Delegate__::area(__context__, shape)
}
}

The mechanism is a single DelegateComponent lookup keyed on (Shape), which is the bare type Shape rather than a one-element tuple; UseDelegate<(A, B)> keys on a real tuple of two parameters. UseDelegate<Components> implements AreaCalculator for a given Shape exactly when Components maps that Shape to a delegate that itself implements AreaCalculator, and the method forwards to it. Only the parameter named inside UseDelegate<...> is the key; the rest pass through unchanged. Each impl is paired with an IsProviderFor impl so dependencies propagate to a check. A component may derive more than one dispatcher when different parameters should be routed differently.

The ideas behind it:

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.