Skip to main content

CanUseComponent

The context-side check that a context both wires a component and satisfies its provider.

info

Generated machinery​

You are not expected to name CanUseComponent directly. check_components! and delegate_and_check_components! generate the assertion that uses it. What you write is the check; this page explains what a check asserts, so that its failure is legible. A hand-written bound on it is legal, and occasionally useful when probing one case.

Overview​

In Context-Generic Programming (CGP), wiring is lazy: writing a wiring line does not check that the chosen provider's own requirements are met. CGP enables pluggable trait implementations in Rust, and CanUseComponent is the check that a context's choice is complete. That check happens where the trait is first used, usually far from the wiring, and the error there is poor, because asking whether a context, the type the implementation runs against, implements the consumer trait makes the compiler report only the outermost unmet bound. The root cause, often one absent field, does not appear.

CanUseComponent asks the same question along a path the compiler explains. It holds when two things hold together: the context wires the component, with a DelegateComponent entry, and the provider it chose is valid for that context and those parameters, through IsProviderFor. Because IsProviderFor carries the provider's real where bounds, requiring it makes the compiler evaluate and report them, at the check.

Definition​

CanUseComponent is an empty trait whose meaning lives in one blanket impl:

pub trait CanUseComponent<Component, Params: ?Sized = ()> {}

impl<Context, Component, Params: ?Sized> CanUseComponent<Component, Params> for Context
where
Context: DelegateComponent<Component>,
Context::Delegate: IsProviderFor<Component, Context, Params>,
{
}

Self is the context being checked. Component is the component's marker, the key the wiring table uses. Params holds the component's generic parameters, filled by the rule IsProviderFor uses: () for none, one directly, several as a tuple. The two bounds are the two halves of "can use": an entry, and a valid provider behind it.

Usage​

The trait is not in the prelude, since the check macros name it for you; import it from cgp::core::component when you write it yourself. A check_components! entry asserts it, carrying the component's parameters after a colon:

check_components! {
App {
GreeterComponent,
AreaCalculatorComponent: Rectangle,
}
}

The same bounds written by hand hold exactly when that check passes:

pub fn assert_wiring()
where
App:
CanUseComponent<GreeterComponent> + CanUseComponent<AreaCalculatorComponent, Rectangle>,
{
}

Examples​

Two components checked on one context, one without parameters and one with a shape parameter:

use cgp::core::component::CanUseComponent;
use cgp::prelude::*;

#[cgp_auto_getter]
pub trait HasName {
fn name(&self) -> &str;
}

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

#[cgp_impl(new GreetHello)]
#[uses(HasName)]
impl Greeter {
fn greet(&self) -> String {
format!("Hello, {}!", self.name())
}
}

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

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

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

#[derive(HasField)]
pub struct App {
pub name: String,
}

delegate_components! {
App {
GreeterComponent: GreetHello,
AreaCalculatorComponent: RectangleArea,
}
}

check_components! {
App {
GreeterComponent,
AreaCalculatorComponent: Rectangle,
}
}

pub fn assert_wiring()
where
App:
CanUseComponent<GreeterComponent> + CanUseComponent<AreaCalculatorComponent, Rectangle>,
{
}

pub fn demo() {
assert_wiring();

let app = App {
name: "Ada".to_owned(),
};
let rectangle = Rectangle {
width: 3.0,
height: 4.0,
};

assert_eq!(app.greet(), "Hello, Ada!");
assert_eq!(app.area(&rectangle), 12.0);
}

The Greeter check holds because App has the name field GreetHello reads, and the AreaCalculator check holds at Rectangle, the parameter it names. A passing check produces nothing; the build succeeding is the result. Rename the field, and the Greeter check fails with the chain shown on IsProviderFor. App is an environmental context that also holds the name its greeting reads.

When to use it​

Reach for check_components!, which reaches for this trait. What is not optional is that every context's wiring gets checked somehow, since lazy wiring lets an unchecked context compile and fail later. Which macro does it is a matter of scale:

  • delegate_and_check_components! wires and checks in one block, which suits basic wiring and a starter context. It checks each entry keyed on a component name, including -> entries, and wires path keys, => redirects, and statements without checking them.
  • A separate check_components! gives control over what is checked: parameters for a generic component, opened or namespaced wiring, and #[check_providers(...)] per provider layer.
  • #[check_providers(...)] switches the assertion from this trait to IsProviderFor on named providers, which is what localizes a failure in a stack of higher-order providers.

Do not assert it on a provider bundle. A delegate_components! block with a leading new declares a provider that contexts delegate to, not a context, so asserting CanUseComponent on it asks a question it never answers in use. It passes vacuously when the bundled providers need nothing from their context, and fails blaming the bundle when one needs something the real context would supply. Check the bundle through a real context that delegates to it, or assert IsProviderFor on it directly.

Not every unmet bound is a component. Ordinary and blanket traits that a provider requires surface as themselves, and no check macro verifies them.

Under the hood​

check_components! emits a private check trait whose supertrait is this bound, then one empty impl of it per entry. cargo cgp expand on the example shows:

trait __CheckApp<
__Component__,
__Params__: ?Sized,
>: CanUseComponent<__Component__, __Params__> {}
impl __CheckApp<GreeterComponent, ()> for App {}
impl __CheckApp<AreaCalculatorComponent, Rectangle> for App {}

Each impl compiles only if its supertrait holds, so the table is an assertion, and it adds nothing to the binary. The two bounds of the blanket impl then fail differently, which tells you what to fix:

  • The entry bound failing means the wiring is absent. The check's help line names the unimplemented DelegateComponent<Component> for the context, as DelegateComponent shows, and the fix is a wiring line.
  • The provider bound failing means the wiring is incomplete. The component is wired, but the chosen provider's requirements are not met, and the notes carry the provider's unsatisfied bound up through IsProviderFor, as IsProviderFor shows. The fix is to supply the dependency.

The trait is the mirror image of IsProviderFor: the same question, indexed on the context (Self = Context) rather than on the provider (Self = Provider).

Common Mistakes​

It is not the consumer trait. App: CanUseComponent<GreeterComponent> holding is a different statement from App: CanGreet, though in practice one follows the other. The check exists because the two questions produce different diagnostics.

A green check on a provider bundle proves nothing. It can pass vacuously, as When to use it explains, which is why delegate_and_check_components! is the wrong macro for a bundle.

A passing check does not test behavior. It proves the wiring resolves and every dependency exists, not that the provider computes the right thing.

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.