Life
A lifetime lifted into a type, so a lifetime parameter can travel through machinery that accepts only types.
Overview
In Context-Generic Programming (CGP), Life<'a> turns the lifetime 'a into a type,
because CGP's wiring is parameterized by types and a CGP trait may carry a lifetime of its own. The marker that records a provider's dependencies,
IsProviderFor, takes a tuple of the trait's generic parameters as
one type argument, so that the compiler can match a provider against the exact instantiation asked for. A
lifetime cannot sit in that tuple, because a tuple is a type and its members must be types. So a lifetime
parameter on the trait must first become a type. Life<'a> is that conversion. It packages the lifetime
'a as a concrete type that can stand beside the trait's other type parameters.
Without this lift, a trait that borrows could not record its lifetime in the dependency marker.
Life lets the lifetime pass through IsProviderFor as (Life<'a>, T), so it stays part of the
provider's identity while the marker's argument stays a plain type. The macros insert it, so you
read it in generated code and in errors, and you write it in one place: the
check_components! entry for a component with a lifetime.
Definition
Life is a tuple struct wrapping a single phantom marker over a raw pointer to a borrowed unit:
pub struct Life<'a>(pub PhantomData<*mut &'a ()>);
The struct holds nothing at run time. Its only job is to carry the lifetime 'a in the type system
through PhantomData. It is not in the prelude, so import it from
cgp::core::field::types.
The phantom type *mut &'a () decides how Life<'a> behaves under subtyping. A *mut T is
invariant in T, so wrapping &'a () behind a *mut makes Life<'a> invariant in 'a: a
Life<'long> is neither a subtype nor a supertype of a Life<'short>. The lifetime is therefore an
exact identity wherever subtyping could apply, as in a provider struct holding a
PhantomData<Life<'a>>. Trait resolution itself matches lifetimes exactly whatever the variance, so
the choice affects values and types that contain Life, not which impl the compiler selects.
The raw pointer has a second effect: Life<'a> is neither Send nor Sync. Neither is any struct
holding a PhantomData<Life<'a>>, such as the provider struct #[cgp_impl(new …)] declares for a
provider generic over a lifetime. This rarely matters, because Life and provider structs appear
only at the type level and are never sent between threads, but a bound such as Provider: Send on
such a provider fails with
error[E0277]: `*mut &'static ()` cannot be sent between threads safely.
Behavior
Life does not define methods and does not implement traits of its own. Its entire behavior is to
occupy a type position. In the generated provider trait for a component with a lifetime, the macro
collects the lifetime into the IsProviderFor argument tuple
as Life<'a>, so the provider's dependency obligation reads the same way as for any type parameter.
The provider trait, its blanket forwarding impl, and the impls that satisfy it all agree on the same
(Life<'a>, T) shape. That shared shape lets CGP wire and check a borrowing component like a
non-borrowing one.
A check names the shape itself. A check_components! entry lists a component's parameters in the
form the marker records them, so a component with a lifetime is checked as (Life<'a>, T), with the
lifetime declared on the table, as in
<'a> App<'a> { ReferenceGetterComponent: (Life<'a>, Config) }. A bare ('a, Config) is rejected:
the compiler reads 'a as a trait-object type without a trait and reports
error: at least one trait is required for an object type.
Examples
A borrowing getter component, wired on a context that holds a borrow, and checked with Life in its
parameter tuple:
use cgp::core::field::traits::HasField;
use cgp::core::field::types::Life;
use cgp::prelude::*;
#[cgp_component(ReferenceGetter)]
pub trait HasReference<'a, T: 'a + ?Sized> {
fn get_reference(&self) -> &'a T;
}
pub struct Config {
pub name: String,
}
#[cgp_impl(new GetConfig)]
#[uses(HasField<Symbol!("config"), Value = &'a Config>)]
impl<'a> ReferenceGetter<'a, Config> {
fn get_reference(&self) -> &'a Config {
self.get_field(PhantomData::<Symbol!("config")>)
}
}
#[derive(HasField)]
pub struct App<'a> {
pub config: &'a Config,
}
delegate_components! {
<'a> App<'a> {
ReferenceGetterComponent: GetConfig,
}
}
check_components! {
<'a> App<'a> {
ReferenceGetterComponent: (Life<'a>, Config),
}
}
pub fn demo() {
let config = Config {
name: "demo".to_owned(),
};
let app = App { config: &config };
let config_ref: &Config = app.get_reference();
assert_eq!(config_ref.name, "demo");
}
App is an environmental context: it holds the borrowed configuration a provider reads. The
component is a self-targeted getter, and its T names the type it lends for the lifetime 'a. The
generated provider trait records the lifetime in its dependency marker as the type Life<'a>, as
cargo cgp expand shows:
pub trait ReferenceGetter<
'a,
__Context__,
T: 'a + ?Sized,
>: IsProviderFor<ReferenceGetterComponent, __Context__, (Life<'a>, T)> {
fn get_reference(__context__: &__Context__) -> &'a T;
}
Every impl that satisfies this component, whether through UseContext, a table's forwarding impl,
or a provider you write yourself, carries the same (Life<'a>, T) tuple, so the resolution
machinery preserves the lifetime end to end.
The ?Sized bound on T admits an unsized target such as str, which makes the tuple
(Life<'a>, str) unsized too. IsProviderFor and the table's forwarding impl both accept an
unsized parameter tuple, so the same component wired at str resolves through the table like any
other:
#[cgp_impl(new GetName)]
#[uses(HasField<Symbol!("name"), Value = &'a str>)]
impl<'a> ReferenceGetter<'a, str> {
fn get_reference(&self) -> &'a str {
self.get_field(PhantomData::<Symbol!("name")>)
}
}
#[derive(HasField)]
pub struct Borrowed<'a> {
pub name: &'a str,
}
delegate_components! {
<'a> Borrowed<'a> {
ReferenceGetterComponent: GetName,
}
}
check_components! {
<'a> Borrowed<'a> {
ReferenceGetterComponent: (Life<'a>, str),
}
}
pub fn demo_unsized() {
let text = String::from("demo");
let borrowed = Borrowed { name: &text };
let name: &str = borrowed.get_reference();
assert_eq!(name, "demo");
}
When to use it
You read Life in generated code, and you write it only in a check. The macros insert it
everywhere else.
- Read
Life<'a>in anIsProviderFortuple as the component's lifetime. A dependency marker such asIsProviderFor<..., (Life<'a>, T)>names a lifetime and a type parameter, in that order. - Write
(Life<'a>, T)in acheck_components!entry for a component with a lifetime, and declare'ain the table's generic list. - Hold a lifetime as
PhantomData<Life<'a>>when you declare a provider struct by hand and want the shape#[cgp_new_provider]gives it. A plainPhantomData<&'a ()>also compiles, but it is covariant and keeps the structSend.
Common Mistakes
A lifetime cannot appear directly in the IsProviderFor tuple. The tuple holds types, so a bare
'a is invalid there, and the macro lifts it into Life<'a>. Life in an error means that the component
carries a lifetime.
A higher-order provider with a lifetime loses its dependency propagation. When the component carries a
lifetime, the inner-provider bound of such a stack does not get a marker counterpart, because the rewrite
reads the bound's first generic argument as the context and finds a lifetime there. The stack still
compiles and runs. But it loses the propagation that lets #[check_providers] localize a broken layer.
IsProviderFor records this limitation.
Related constructs
IsProviderFor: whose parameter tuple a lifetime is lifted into asLife<'a>.#[cgp_component]: insertsLifewhen a consumer trait carries a lifetime.check_components!: where a check namesLifein a parameter tuple.PhantomData: the markerLifeis built from, wrapped for invariance.IndexandChars: the other lifts that make a non-type addressable in trait resolution, a number and a string whereLifelifts a lifetime.
The ideas behind it:
- Consumer and provider traits: the provider-trait machinery whose dependency marker carries this lift.
Source
- The type:
life.rs - The macro logic that wraps a trait's lifetime parameters in
Lifewhen building theIsProviderForargument tuple:is_provider_params.rs, with the same lifting in a provider struct'sPhantomDatainempty_struct.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.