UseContext
Satisfy a provider trait by routing back through the context's own consumer-trait implementation.
Overview
Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and
UseContext turns a context's existing consumer-trait implementation into a provider that other
providers can call. The context is the type the
implementation runs against, and it normally uses a provider through its consumer trait. Sometimes
the implementation another provider wants for a trait is exactly the one the context already
supplies that way. UseContext is that bridge: it is a provider whose method bodies call the
consumer method on the context, so handing a component UseContext means "use whatever this context
already does for this trait."
This makes UseContext the exact dual of the consumer-trait blanket implementation that
#[cgp_component] generates. That blanket impl runs in the
consumer-to-provider direction: a context implements CanEncode by delegating to whichever provider
implements Encoder for it. UseContext runs the other way: it implements the provider trait
Encoder by delegating to whatever CanEncode implementation the context has. One forwards the
consumer trait to a provider; the other forwards a provider trait back to the consumer trait.
UseContext matters most with higher-order providers, which
take another provider as a type parameter. Such a provider can default its inner-provider parameter to
UseContext, so when no inner provider is named, the inner step falls back to whatever the context
already wires for it. That inner step may be a different trait, or the same trait at a
different type, as the example below shows by encoding a Vec<T> through the context's own encoder for
T. Like every CGP provider, UseContext carries no runtime value: it is a unit marker whose self
position is never read.
Usage
UseContext is imported from cgp::core::component. It takes no type parameter and
appears in two places. Most often it is a higher-order provider's default inner provider, written in
the provider's struct definition:
pub struct EncodeVec<Inner = UseContext>(pub PhantomData<Inner>);
It also appears as a type argument inside a wiring entry, where a provider that takes an inner
provider is given UseContext explicitly. The dispatch combinators, such as
MatchWithValueHandlers<Provider = UseContext>, default their per-variant provider to it. It is
never the whole value of an entry for the component it implements, which is the cycle
Common Mistakes describes.
UseContext stands in for a provider trait only where that trait resolves to a different
implementation than the one being wired: a wrapper over another trait, or a per-type dispatch entry
for a different type.
Examples
The idiomatic use is as the default inner provider of a higher-order provider. EncodeVec encodes a
Vec by encoding each element through an inner provider, and defaults that inner provider to
UseContext, so the elements are encoded by whatever the context already wires for their type:
use cgp::core::component::UseContext;
use cgp::prelude::*;
#[cgp_component(Encoder)]
pub trait CanEncode<Value> {
fn encode(&self, value: &Value) -> Vec<u8>;
}
#[cgp_impl(new EncodeAsText)]
impl<Value> Encoder<Value>
where
Value: core::fmt::Display,
{
fn encode(&self, value: &Value) -> Vec<u8> {
value.to_string().into_bytes()
}
}
pub struct EncodeVec<Inner = UseContext>(pub PhantomData<Inner>);
#[cgp_impl(EncodeVec<Inner>)]
#[use_provider(Inner: Encoder<Item>)]
impl<Item, Inner> Encoder<Vec<Item>> {
fn encode(&self, values: &Vec<Item>) -> Vec<u8> {
values
.iter()
.flat_map(|item| Inner::encode(self, item))
.collect()
}
}
pub struct App;
delegate_components! {
App {
open EncoderComponent;
@EncoderComponent.u32: EncodeAsText,
@EncoderComponent.Vec<u32>: EncodeVec,
}
}
check_components! {
App {
EncoderComponent: [u32, Vec<u32>],
}
}
pub fn demo() {
assert_eq!(App.encode(&vec![1u32, 2, 3]), b"123");
}
App is an environmental context, and the
component is parameter-targeted: it
encodes the Value, while App chooses the encoder for each value type. App uses the
open statement to wire the Encoder component per value type,
giving Vec<u32> a bare EncodeVec whose Inner defaults to UseContext. Encoding a Vec<u32>
runs EncodeVec, which calls Inner::encode(self, item) on each element; Inner resolves through
UseContext to App's own CanEncode<u32>, wired to EncodeAsText. So encoding
vec![1u32, 2, 3] produces the bytes of "123". There is no cycle, because the element lookup is
for a different type (u32) than the wired one (Vec<u32>). Naming an explicit inner provider in
place of the UseContext default binds the element encoder directly and bypasses the context's
CanEncode<u32> wiring.
UseContext acts as a default only when the provider's struct definition gives it as the default
generic parameter, as EncodeVec does. A provider without such a default has no inner provider to fall
back to, and the inner provider must always be named.
When to use it
Reach for UseContext as the default inner provider of a higher-order provider, so the wrapper
reuses the context's own wiring for the inner step when no inner provider is named. The inner step may
be a different trait, or the same trait at a different type, as EncodeVec delegates
Encoder<Vec<T>> to the context's Encoder<T>.
The one shape UseContext cannot serve is a component whose only implementation on the context is that
same delegation, which loops; Common Mistakes explains it. When you want a wrapper
over the same trait and the same type, name the inner provider explicitly rather than
defaulting to UseContext.
Under the hood
#[cgp_component] emits a UseContext implementation of the provider
trait for every component it defines, alongside the consumer blanket impl, the provider blanket impl,
the component marker, and the RedirectLookup impl. The generated impl bounds the
context on the consumer trait and forwards each method to it. For a component such as
#[cgp_component(Greeter)]
pub trait CanGreet {
fn greet(&self);
}
the macro generates this UseContext impl (shown with the macro's real placeholder identifiers):
impl<__Context__> Greeter<__Context__> for UseContext
where
__Context__: CanGreet,
{
fn greet(__context__: &__Context__) {
__Context__::greet(__context__)
}
}
The provider method takes the context explicitly and calls the context's own CanGreet::greet. The
impl is paired with a matching IsProviderFor impl carrying
the same where clause, so delegation propagates the dependency and a check reports a missing
consumer-trait implementation precisely:
impl<__Context__> IsProviderFor<GreeterComponent, __Context__, ()> for UseContext
where
__Context__: CanGreet,
{}
Any supertrait bound on the consumer trait is reproduced in
the where clause, so a context must satisfy it before UseContext can stand in as a provider.
Common Mistakes
Wiring a component to UseContext on the context whose only implementation is that same delegation
creates a cycle. If App wired @EncoderComponent.u32: UseContext, then App's CanEncode<u32>
would be implemented by delegating to UseContext, whose Encoder<u32> impl in turn calls App's
CanEncode<u32>. The trait solver chases this in a loop, and a check reports the overflow:
error[E0275]: overflow evaluating the requirement `App: IsProviderFor<EncoderComponent, App, u32>`
cargo cgp check reports the same mistake as [CGP-E020], at a check
or at a method call, and names the provider that closes the loop.
UseContext belongs where the provider trait resolves to a different implementation, such as a
wrapper over another trait or a per-type dispatch entry for a different type. The EncodeVec
example above is safe for exactly that reason: it is wired for Vec<u32>, but its inner
UseContext resolves Encoder<u32>, a different entry.
Related constructs
#[cgp_component]— generates theUseContextimpl for every component, and the consumer blanket implUseContextis the dual of.- Higher-order providers — where
UseContextis the default inner provider. WithContext— theWithProvider-adapted alias ofUseContext, for serving a component from the context's own foundational implementation.WithProvider— itsWithContextalias isWithProvider<UseContext>, adapting a context's own implementation into a component.RedirectLookup— the other#[cgp_component]-generated provider, routing through a separate table rather than back to the context.- Dispatch combinators — default their per-variant provider to
UseContext. delegate_components!— wires it, and itsopenstatement dispatches a component per type as the example does.IsProviderFor— carries the dependencyUseContextpropagates.
The ideas behind it:
- Consumer and provider traits — the two-way split
UseContextbridges. - Higher-order providers — the pattern that makes it useful.
Source
- Struct and the
WithContextalias:use_context.rs - The generated
UseContextimpl:cgp_component/evaluated/to_use_context_impl.rs
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.