Skip to main content

DelegateComponent

The per-context type-level table mapping a component key to its provider.

info

Generated machinery​

You are not expected to write DelegateComponent impls. delegate_components! emits one per entry of a wiring table, and its namespace header emits the blanket impl that forwards every key through a namespace. What you write is the table. This page explains what the table becomes, so that an expansion or a wiring error naming this trait is legible. The one place you name the trait yourself is a bound that reads an entry, as the Usage section shows.

Overview​

In Context-Generic Programming (CGP), wiring a context, the type the implementation runs against, means recording which provider it uses for each component. CGP enables pluggable trait implementations in Rust, and DelegateComponent is the table that records each choice. DelegateComponent is the trait that record is made of, and one impl is one entry:

impl DelegateComponent<GreeterComponent> for App {
type Delegate = GreetHello;
}

Read that as "in App's table, the entry at GreeterComponent is GreetHello." The key and the value are both types, and the lookup happens while the compiler type-checks, so the table costs nothing at runtime and a wired call compiles to a direct one. Wiring is not a registry or a startup step; it is a set of trait impls the compiler resolves.

The key does not have to be a component name. When it is, the entry gives the context the component's provider trait. When it is any other type, such as a shape or a tag, the same trait is a plain lookup table that a provider reads. One trait covers both, which is why it underlies ordinary wiring and the inner dispatch tables alike.

Definition​

DelegateComponent carries a single associated type and no method:

pub trait DelegateComponent<Key: ?Sized> {
type Delegate;
}

Self is the table: a context, or a provider bundle that owns its own entries. Key is the type being looked up, and it is ?Sized so that an unsized type can serve as a key. Delegate is the value stored at that key: the provider, or a further table, that the entry resolves to. The trait has no data, so the table exists only in the type system.

Usage​

The trait is not in the prelude; import it from cgp::core::component.

Setting an entry, and reading one​

There are two operations, and both are ordinary Rust. Setting an entry is writing the impl, which in practice means writing a delegate_components! line. Reading one is bounding on the trait and projecting the associated type:

pub fn provider_for<Table, Key>() -> PhantomData<<Table as DelegateComponent<Key>>::Delegate>
where
Table: DelegateComponent<Key>,
{
PhantomData
}

The bound is the lookup, and <Table as DelegateComponent<Key>>::Delegate is the value it finds. Rust forbids two impls of one trait for the same Self and Key, so each key maps to exactly one value: the structure is a map, and a duplicate entry is a coherence error rather than a silent overwrite.

What can be a key​

The key's type decides what an entry means, and three kinds occur:

  • A component name, such as GreeterComponent. The provider blanket impl that #[cgp_component] generates reads the entry, so the context gets the component's provider trait, and from it the consumer trait.
  • Any other type, such as a shape or a tag. The table is a dispatch map with no provider trait attached, as the nested tables inside UseDelegate are.
  • A type-level path, a PathCons list, which is how the open statement and namespaces key their entries. The macro emits a path entry with a generic tail, so it matches every longer path beneath it, and RedirectLookup reads it with one lookup on the whole path.

What owns a table​

Self is not always a context. A delegate_components! block with a leading new declares a provider bundle that owns its own table, so several contexts can delegate a group of components to it as one unit. A lookup is shallow: one read yields the immediate Delegate, and chaining happens when that delegate is itself a table, as a bundle is.

Examples​

One component wired on a context, and a table keyed on shapes, each read back with the function from Usage:

use cgp::prelude::*;

#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self) -> String;
}

#[cgp_impl(new GreetHello)]
impl Greeter {
fn greet(&self) -> String {
"Hello!".to_owned()
}
}

pub struct App;

delegate_components! {
App {
GreeterComponent: GreetHello,
}
}

check_components! {
App {
GreeterComponent,
}
}

pub struct Rectangle;
pub struct Circle;
pub struct RectangleArea;
pub struct CircleArea;

delegate_components! {
new AreaComponents {
Rectangle: RectangleArea,
Circle: CircleArea,
}
}

pub fn demo() {
assert_eq!(App.greet(), "Hello!");

// Each read resolves to the entry's value at compile time.
let _: PhantomData<GreetHello> = provider_for::<App, GreeterComponent>();
let _: PhantomData<RectangleArea> = provider_for::<AreaComponents, Rectangle>();
let _: PhantomData<CircleArea> = provider_for::<AreaComponents, Circle>();
}

The App line is one DelegateComponent impl, and through it App gets the Greeter provider trait and then CanGreet, so App.greet() compiles; swapping GreetHello for another provider changes only that line. AreaComponents holds two entries keyed on shapes, with no provider trait attached, which a UseDelegate provider reads to pick an area provider per shape. App is an environmental context.

When to use it​

Write delegate_components!, not DelegateComponent. The macro also emits the IsProviderFor forwarding impl beside each entry, and the provider blanket impl requires both, so a hand-written DelegateComponent impl alone does not wire the component at all. Name the trait yourself only to read an entry in generic code: a dispatcher or a higher-order provider that resolves a key bounds on DelegateComponent<Key> and projects Delegate.

When a trait has exactly one implementation for a context, implement the consumer trait directly on the context instead. A CGP consumer trait is an ordinary trait, so impl CanGreet for App { … } is legal and needs no table entry. Wiring earns its place when the implementation is one of several, is shared between contexts, or composes with a wrapper.

Under the hood​

cargo cgp expand shows what the App line of the example becomes: the entry, and beside it an IsProviderFor impl that forwards the chosen provider's requirements:

impl DelegateComponent<GreeterComponent> for App {
type Delegate = GreetHello;
}
impl<
__Context__,
__Params__: ?Sized,
> IsProviderFor<GreeterComponent, __Context__, __Params__> for App
where
GreetHello: IsProviderFor<GreeterComponent, __Context__, __Params__>,
{}

The reader is the provider blanket impl that #[cgp_component] generates for Greeter. It implements the provider trait for any type that has both an entry and the forwarding impl, and forwards each method to the entry's value:

impl<__Provider__, __Context__> Greeter<__Context__> for __Provider__
where
__Provider__: DelegateComponent<GreeterComponent>
+ IsProviderFor<GreeterComponent, __Context__, ()>,
<__Provider__ as DelegateComponent<
GreeterComponent,
>>::Delegate: Greeter<__Context__>,
{
fn greet(__context__: &__Context__) -> String {
<__Provider__ as DelegateComponent<
GreeterComponent,
>>::Delegate::greet(__context__)
}
}

The routing is the projection, and the call it forwards to is resolved statically. A context that joins a namespace with a namespace N; header gets a blanket entry instead of one per key, which reads each key's value from the namespace trait. For an App that joins a namespace MyNamespace defined with cgp_namespace!, the header becomes:

impl<__Key__, __Value__> DelegateComponent<__Key__> for App
where
__Key__: MyNamespace<App, Delegate = __Value__>,
{
type Delegate = __Value__;
}

That is how a context inherits a whole table while still adding direct entries at the keys the namespace leaves open.

Common Mistakes​

A missing entry and an unsatisfied provider are different errors. A context that never wires the component fails a check on the table entry:

pub struct App;

check_components! {
App {
GreeterComponent,
}
}

rustc names the missing entry in a help line:

error[E0277]: the trait bound `App: CanUseComponent<GreeterComponent>` is not satisfied
...
help: the trait `DelegateComponent<GreeterComponent>` is not implemented for `App`

The fix is a wiring line. A wired component whose provider's dependencies are unmet fails through IsProviderFor instead, and the fix is to supply the dependency.

A hand-written entry does not wire the component. An impl DelegateComponent<GreeterComponent> for App written by hand, without the forwarding impl the macro emits beside it, fails the provider blanket impl's IsProviderFor bound, so App never gets the provider trait and a call fails:

error[E0599]: the method `greet` exists for struct `App`, but its trait bounds were not satisfied

Write the entry with delegate_components!.

Two entries for the same key conflict rather than override. Wiring one component on one context twice, to GreetHello and to a second provider GreetHi, is two impls of each generated trait for one type:

delegate_components! {
App {
GreeterComponent: GreetHello,
GreeterComponent: GreetHi,
}
}

It fails twice, once for the forwarding impl and once for the entry:

error[E0119]: conflicting implementations of trait `IsProviderFor<GreeterComponent, _, _>` for type `App`
...
error[E0119]: conflicting implementations of trait `DelegateComponent<GreeterComponent>` for type `App`

A direct entry for a key the context's namespace already binds conflicts the same way, with the namespace's blanket impl, so a context adds entries only at keys the namespace leaves open.

Self is not always a context. A provider bundle declared with new owns a table too, and an error naming one as the table does not mean something is being used as a context.

The table is resolved at compile time, in full. There is no runtime map to inspect and no way to add an entry dynamically. If you are looking for a place to register something at startup, this is not it.

  • delegate_components!: the macro that generates these impls; what you write instead of the trait.
  • #[cgp_component]: generates the blanket impl that reads the table.
  • IsProviderFor: emitted beside each entry, and required with it.
  • CanUseComponent: combines an entry and a valid provider into one assertion.
  • UseDelegate: reads a table keyed on other types, for dispatch per type.
  • RedirectLookup: reads a path-keyed entry; the mechanism behind open and namespaces.

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.