Components
A CGP component separates the trait callers use from the trait providers implement.
#[cgp_component] generates the traits and delegation support from one trait definition. Read this
reference before working with components or providers.
What a component is
A component contains a consumer trait, a provider trait, a …Component marker, and blanket impls
that connect them. The consumer trait is the interface callers use, while the provider trait accepts
implementations on separate provider types. This separation allows interchangeable implementations
and trait implementations for types the implementing crate does not own.
Ordinary trait implementations tie an interface to its implementation on a type. The type receiving
.area() also supplies the trait impl, and coherence permits only one impl of that trait for that
type. CGP moves the implementation choice to the provider.
The examples use CGP v0.8.0 and assume use cgp::prelude::*;. They follow a greeting component
(CanGreet, Greeter, and GreetHello) on Person, and an area component (CanCalculateArea,
AreaCalculator, and RectangleArea) on Rectangle.
What #[cgp_component(Greeter)] generates
Applying the macro to a consumer trait produces the consumer trait, the provider trait, the blanket impls that connect them, and the marker struct. Start from the trait, naming the provider trait in the attribute argument:
#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self);
}
The consumer trait is emitted unchanged. This is the self-style trait callers use (CanDoX), so
a caller writes person.greet() exactly as with any trait:
pub trait CanGreet {
fn greet(&self);
}
The provider trait is the same interface with Self moved out into an explicit leading
Context type parameter and every self/Self rewritten to context/Context. It is named in
noun form (SomethingDoer, or …Provider when a noun does not fit). It carries an IsProviderFor
supertrait that captures the component, the context, and a Params tuple of any extra type
parameters, which is () when there are none:
/// Provider trait for [`CanGreet`]. A provider imports this trait's component key, [`GreeterComponent`], beside it.
pub trait Greeter<Context>:
IsProviderFor<GreeterComponent, Context, ()>
{
fn greet(context: &Context);
}
The macro adds that doc line to every provider trait, after the consumer trait's own doc when it has one, so an editor's hover on the trait names the key to import.
Implement a provider trait on a dedicated zero-sized provider struct. The struct serves only as a
type-level marker and is never instantiated. Each provider owns a distinct Self type while
remaining generic over Context, allowing GreetHello, GreetGoodbye, and other implementations
to coexist. See bypassing
coherence
for the coherence rules and modularity hierarchy for when to use this
separation.
How the two traits connect
Generated blanket impls connect consumer calls to the chosen provider. Together they resolve
person.greet() without requiring the caller to name a provider. The macros generate these impls;
you do not write them.
The consumer blanket impl says that any context implementing the provider trait for itself
gets the consumer trait. It forwards context.greet() to Context::greet(self):
impl<Context> CanGreet for Context
where
Context: Greeter<Context>,
{
fn greet(&self) {
Context::greet(self)
}
}
The provider blanket impl lets any provider that delegates this component inherit the provider
trait from whatever it delegates to. The delegation is a type-level table lookup through
DelegateComponent, keyed on the GreeterComponent marker:
impl<Context, Provider> Greeter<Context> for Provider
where
Provider: DelegateComponent<GreeterComponent>
+ IsProviderFor<GreeterComponent, Context, ()>,
Provider::Delegate: Greeter<Context>,
{
fn greet(context: &Context) {
Provider::Delegate::greet(context)
}
}
The component marker is a zero-sized key into those delegation tables:
/// Component marker for [`CanGreet`].
pub struct GreeterComponent;
Attributes on a consumer trait's method are copied onto the provider trait's method declaration.
This matters for #[track_caller]: Rust applies it on a trait method declaration to every impl, so
it reaches the forwarding impls and every provider, and Location::caller() inside a provider
reports the line that called the consumer method.
These examples use readable names for clarity. The emitted code uses reserved identifiers,
__Context__ for the context parameter (overridable) and __Provider__ for the provider parameter,
chosen so they never clash with a user's own type names.
Wiring is the table lookup that ties it all together
Wiring selects the provider that the generated impls use for each component. In this example,
Person delegates GreeterComponent to GreetHello. A call to person.greet() enters the
consumer blanket impl, which requires Person: Greeter<Person>. The provider blanket impl satisfies
that requirement through the delegation entry and forwards the call to GreetHello. Changing the
entry changes the selected behavior:
#[derive(HasField)]
pub struct Person {
pub name: String,
}
delegate_components! {
Person {
GreeterComponent: GreetHello,
}
}
The full table grammar, including per-value dispatch, lives in wiring, and shared tables in namespaces. This file shows only the single-entry form needed to make the resolution concrete.
Why IsProviderFor exists
IsProviderFor exposes missing provider dependencies in compiler errors. It is an empty marker used
as a supertrait on every provider trait. Checking a provider trait directly can yield only “trait
not implemented” because the competing provider blanket impl suppresses Rust's detailed explanation.
The macros implement IsProviderFor with the same where bounds as the provider-trait impl.
Without a competing blanket candidate for this check, Rust reports the specific unsatisfied bound.
An IsProviderFor error therefore identifies a dependency preventing the provider-trait impl from
applying. The macros generate and use the marker; you encounter it in diagnostics:
pub trait IsProviderFor<Component, Context, Params: ?Sized = ()> {}
Writing providers
Prefer #[cgp_impl] when writing providers. It accepts consumer-style signatures and expands to the
explicit provider forms described below. Use those lower-level forms directly only when you need the
native provider-trait structure.
#[cgp_provider] preserves an explicit provider-trait impl and generates an IsProviderFor impl
with the same where bounds, and cargo cgp check reports an impl written without it as [CGP-E039].
The provider struct must already exist, as it does here:
/// Provider `RectangleArea` for [`AreaCalculator`].
pub struct RectangleArea;
#[cgp_provider]
impl<Context> AreaCalculator<Context> for RectangleArea
where
Context: HasDimensions,
{
fn area(context: &Context) -> f64 {
context.width() * context.height()
}
}
The generated marker impl repeats the HasDimensions bound, allowing a missing dependency to appear
by name in an error:
impl<Context> IsProviderFor<AreaCalculatorComponent, Context, ()> for RectangleArea
where
Context: HasDimensions,
{}
The optional attribute argument overrides the component type, which otherwise defaults to the
provider trait's path with Component appended to its last segment. Pass it explicitly only when
that name is not the component's, as Importing the component key
describes.
#[cgp_new_provider] also declares the provider struct. It otherwise behaves like
#[cgp_provider], letting an explicit provider impl introduce its struct in the same block. A
generic provider receives a PhantomData field over its parameters.
#[cgp_impl] lets providers use self, Self, and consumer-style method signatures. The attribute
names the provider, and new declares its struct. Omitting for Context lets the macro insert the
context parameter:
#[cgp_impl(new RectangleArea)]
impl AreaCalculator
where
Self: HasDimensions,
{
fn area(&self) -> f64 {
self.width() * self.height()
}
}
Inside #[cgp_impl], self and Self refer to the context. The macro rewrites them to the context
value and type. The exception is an associated type or const the block declares itself:
Self::Output and Self::LIMIT name the provider's own item, even when a #[uses] trait gives the
context an item of the same name (<Self as HasLimit>::LIMIT reads the context's). The provider
struct remains a type-level name without a runtime instance.
#[cgp_impl] desugars to #[cgp_provider], or to #[cgp_new_provider] when new is given. The
block above is equivalent to writing the context out by hand and lowering it:
#[cgp_new_provider]
impl<__Context__> AreaCalculator<__Context__> for RectangleArea
where
__Context__: HasDimensions,
{
fn area(__context__: &__Context__) -> f64 {
__context__.width() * __context__.height()
}
}
The receiver &self became __context__: &__Context__, where the receiver identifier is the
snake-cased context name wrapped in double underscores, and Self in the where clause became the
context type. When you write for Context explicitly, that name is used instead of __Context__.
Do so when you need to bound or refer to the context readably.
Importing the component key
A provider header names its component's key without writing it. #[cgp_impl], #[cgp_provider],
and #[cgp_new_provider] derive the key from the provider trait's path as the header writes it,
appending Component to the last segment and dropping the trait's generic arguments. impl Greeter
therefore names GreeterComponent, which must be in scope beside the trait, while
impl crate::components::Greeter names crate::components::GreeterComponent, which the module need
not import. A provider in another module than its component imports both names in one line:
mod components {
use cgp::prelude::*;
#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self);
}
}
mod providers {
use cgp::prelude::*;
use crate::components::{Greeter, GreeterComponent};
#[cgp_impl(new GreetHello)]
impl Greeter {
fn greet(&self) {
println!("Hello!");
}
}
}
A module that re-exports a provider trait re-exports its key in the same line, so a provider can
import both from it or name the trait through it. A key from a dependency follows the same rule: a
provider on CGP's Computer imports ComputerComponent beside it from cgp::extra::handler.
A component whose name: renames its key, or gives the key parameters, has no key under the derived
name. Its provider names the key after the provider in the attribute, as
#[cgp_impl(new UnitArea: AreaComponent)] or
#[cgp_impl(new SquareArea: AreaCalculatorComponent<Square>)]. A trait imported under another name
needs the same form, because the macro derives the key from the name the header writes.
A key that does not resolve fails with E0425 on the trait's name in the header:
cannot find type `GreeterComponent` in this scope. cargo cgp check reports it as [CGP-E041]
with the key's import path, and a derived name that is not the component's as [CGP-E070], naming
the key in the attribute form. Each comes with a fix, help: import the component or
help: name the component in the attribute, which an editor running cargo cgp check offers on the
trait's name.
Impl-side dependencies
Impl-side dependencies are provider requirements that the consumer trait does not expose.
RectangleArea requires Context: HasDimensions, while CanCalculateArea declares only area. A
caller bounded by CanCalculateArea need not repeat HasDimensions, so the dependency does not
propagate through callers.
The provider states these requirements in its where clause, and wiring resolves them through the
context. This supplies dependency injection while preserving a smaller consumer interface. See
impl-side
dependencies
for the full explanation and functions and getters for implicit
arguments and getters that read context fields.
Which items belong in one component
Group component items according to the provider choice that determines their implementation. A component trait can contain as many items as an ordinary Rust trait, but one provider supplies them all. Keep items together when one choice determines them; separate items that need independent choices. Single-method components are common because many application operations represent one choice.
A method and its associated output type often belong in one component. The provider chooses both the
operation and its result type. CanCompute, CanHandle, and CanProduce therefore define Output
alongside their methods. Likewise, a CanQueryDatabase component can group Row with query,
preventing a context from independently pairing a Postgres query provider with a SQLite row type.
A getter component can group fields read by their method names. One UseFields provider supplies
all those reads. However, UseField and WithProvider impls are generated only for single-method
getters, so accessing a differently named field requires a separate component.
Grouping independent choices increases the dependencies and forwarding code each provider must support. Every provider must satisfy the union of its methods' dependencies, imposing those requirements on each context that uses it. A higher-order provider must implement every item, including forwarding methods it leaves unchanged.
Contexts using only part of a component must still supply the complete interface. This often leads
to placeholder associated types or unimplemented!() bodies, especially in test mocks. The cost
depends on how unrelated the choices are, rather than simply on the number of items.
Check whether another context could reuse a provider's complete implementation. A consumer trait named after an entity rather than an action may group independent choices. If its providers would not be reusable, implement the trait directly on the context.
Split a component according to the differences between the contexts that need it. Methods with shared dependencies can become components with reusable providers; methods that must differ can receive direct impls on each context. See sizing a component for the procedure and trade-offs.
A consumer trait is still an ordinary trait
Implement a consumer trait directly when provider reuse is unnecessary. An ordinary
impl CanGreet for Person { ... } supports person.greet() without wiring. Use the provider
machinery when the trait needs interchangeable implementations.
Further reference
Consult the online knowledge base for complete macro expansions and accepted syntax:
These conceptual references explain the consumer/provider split:
Continue with the related sub-skills for specific tasks:
- Wiring: Selecting providers for a context.
- Checking: Verifying wiring and diagnosing missing dependencies.
- Functions and getters: Reading context values.
- Higher-order providers: Composing providers.