Skip to main content

Reflection and compile-time introspection

Context-Generic Programming represents a struct's fields as types, letting generic code read them and select behavior at compile time. CGP extends Rust with pluggable trait implementations, chosen per context and resolved at compile time, as a library on stable Rust whose consumer traits are ordinary Rust traits. This page compares that approach with Bevy's runtime reflection, Zig's comptime, and Rust's experimental reflection API through a generic field writer.

In your terms​

A context is the type a CGP method runs on. It supplies data through fields and chooses implementations through wiring. Here an application context chooses how to write each field type; the struct being written is passed to it as a value.

The reflection vocabulary maps onto CGP by role:

In a reflection systemIn CGP
A type descriptor: TypeInfo, Shape, std.builtin.Type, FieldIdA #[derive(HasFields)] type's Fields, a type rather than a value
A field's name, as a runtime or comptime stringTag::VALUE, a &'static str recovered from a type-level string
A field's type, as an opaque TypeId or ShapeThe field's type, carried as a real type parameter
inline for over @typeInfo, or a walk over a descriptorA trait recursion over the Cons/Nil field list
A registry mapping types to behaviorThe wiring table, written with delegate_components!
Checking that an operation supports a field typeTrait bounds, verified when used or asserted with check_components!

The idea, briefly​

Reflection lets code inspect a type's shape without knowing that type in advance. Serializers, editors, and debuggers use it to find fields by name and type. Systems differ in when they inspect the shape:

  • At runtime: A type carries metadata that the program inspects while it runs, as in Java, Go, C#, Python, and Bevy.
  • Through a generated descriptor: A derive generates a static descriptor that runtime code walks, as in Rust's facet crate.
  • At compile time: The compiler evaluates the introspection and emits only the specialized result, as in Zig's comptime, D, C++26's static reflection (P2996), and Rust's nightly work.

CGP also processes shapes at compile time. Its shape is a type, rather than a compile-time value.

Runtime reflection: Bevy​

Bevy lets code inspect values through a common runtime interface. A type opts in with #[derive(Reflect)]; code can then access its fields by name or downcast it to a concrete type (bevy_reflect documentation). TypeInfo describes the shape, and a TypeRegistry associates types with metadata and behavior. These facilities support scene serialization and editors that work across registered types. A lookup for a missing field or an incorrect downcast can fail at runtime.

Compile-time metaprogramming: Zig's comptime​

Zig makes types available as compile-time values. @typeInfo(T) decomposes a type into a std.builtin.Type describing its shape, inline for unrolls a loop over a compile-time collection, and @field accesses a field by a name known at compile time (Zig language reference). This Zig 0.16 example writes a struct as a JSON-like object:

const std = @import("std");

fn jsonStringify(value: anytype, writer: anytype) !void {
try writer.writeAll("{");
inline for (std.meta.fields(@TypeOf(value)), 0..) |field, i| {
if (i > 0) try writer.writeAll(", ");
try writer.print("\"{s}\": {any}", .{ field.name, @field(value, field.name) });
}
try writer.writeAll("}");
}

Zig resolves the loop and field accesses at compile time, without runtime lookup. A generic comptime routine is checked for each concrete instantiation, so type-dependent errors appear when it is used. Zig can also construct a new nominal type from a std.builtin.Type value through @Type; CGP does not offer that operation.

Compile-time reflection comes to Rust​

Rust libraries can generate either code or metadata from a type declaration. Serde's derives generate serialization implementations that are specialized for each type and serializer. facet generates a const SHAPE descriptor that shared runtime code can inspect, aiming to reduce that duplication.

Rust's experimental type_info feature supplies metadata directly from the compiler. Under #![feature(type_info)], TypeId::of::<T>() gains query methods that reach a type's variants and fields in source order. Each FieldId answers name(), type_id(), and offset(). The source's own doc tests read:

#![feature(type_info)]
use std::any::TypeId;

struct Point { x: u32, y: u32 }

assert_eq!(const { TypeId::of::<Point>().fields(0) }, 2);
assert_eq!(const { TypeId::of::<Point>().field(0, 0).name() }, "x");
assert_eq!(const { TypeId::of::<Point>().field(0, 0).type_id() }, TypeId::of::<u32>());

The API shown here restricts these queries to compile time. Its #[rustc_comptime] marker avoids requiring a runtime table of type descriptions. The Reflection and comptime project goal aims to let libraries such as Bevy inspect types without requiring derives, while leaving full Zig-style comptime outside its immediate scope. The feature remains experimental; consult the tracking issue before relying on its API.

How CGP expresses it​

CGP encodes a type's structure as types and processes it with trait resolution. The example fragments form a field writer modeled on cgp-serde 's SerializeRecordFields provider, which does the same over serde's Serializer. Its context is an environmental context: App stands for an application and chooses how each field type is written. The written Value is a type parameter, so the component is parameter-targeted.

Representing a struct as a field list​

#[derive(HasFields)] represents a struct's structure as a type-level list. The list plays the role of the TypeInfo, Shape, and FieldId descriptors above:

#[derive(HasFields)]
pub struct Config {
pub host: String,
pub port: u16,
}

// generated:
// impl HasFields for Config {
// type Fields = Product![
// Field<Symbol!("host"), String>,
// Field<Symbol!("port"), u16>,
// ];
// }

The list records each field's name and type. Unlike the Rust MVP's opaque TypeId value, Field<Tag, Value> carries the field's actual type as a type parameter. CGP can therefore dispatch on that type. The Extensible records page develops the derive.

Writing fields through trait recursion​

The WriteFields provider writes any type whose field list implements FieldsWriter. That bound requires readable fields and a writer for each field type:

#[cgp_component(ValueWriter)]
pub trait CanWriteValue<Value> {
fn write_value(&self, value: &Value) -> String;
}

#[cgp_impl(new WriteFields)]
impl<Value> ValueWriter<Value>
where
Value: HasFields,
Value::Fields: FieldsWriter<Self, Value>,
{
fn write_value(&self, value: &Value) -> String {
format!("{{{}}}", Value::Fields::write_fields(self, value))
}
}

The FieldsWriter trait takes the place of inline for. It recurses over the Cons/Nil list, with one impl for a non-empty list and a base case for the empty one:

pub trait FieldsWriter<Context, Value> {
fn write_fields(context: &Context, value: &Value) -> String;
}

impl<Context, Value, Tag, FieldValue, Rest> FieldsWriter<Context, Value>
for Cons<Field<Tag, FieldValue>, Rest>
where
Tag: StaticString, // the field name, as a const &'static str
Value: HasField<Tag, Value = FieldValue>, // read this field from the value
Context: CanWriteValue<FieldValue>, // write the field through the context's wiring
Rest: FieldsWriter<Context, Value>, // recurse on the remaining fields
{
fn write_fields(context: &Context, value: &Value) -> String {
let field_value = value.get_field(PhantomData);
let entry = format!("\"{}\": {}", Tag::VALUE, context.write_value(field_value));
let rest = Rest::write_fields(context, value);
if rest.is_empty() { entry } else { format!("{entry}, {rest}") }
}
}

impl<Context, Value> FieldsWriter<Context, Value> for Nil {
fn write_fields(_context: &Context, _value: &Value) -> String {
String::new()
}
}

Each step of a reflective serializer has a counterpart in this code:

  • The loop over fields: The recursion over Cons and Nil.
  • The field name: Tag::VALUE, recovered through the StaticString trait without runtime metadata.
  • Access by name: value.get_field(PhantomData), resolved statically through HasField.
  • Writing each field's value: The Context: CanWriteValue<FieldValue> bound, which dispatches on the field's type through the context's wiring.

The context's wiring then chooses a writer for each type:

delegate_components! {
App {
open ValueWriterComponent;

@ValueWriterComponent.[String, u16]: WriteWithDebug,
@ValueWriterComponent.Config: WriteFields,
}
}

App.write_value(&config); // {"host": "localhost", "port": 8080}

To complete these fragments, Config also needs #[derive(HasField)], App needs a declaration, and config needs a value. The WriteWithDebug provider formats a value with Debug; this illustrates traversal and dispatch rather than a complete JSON serializer. cgp-serde's SerializeRecordFields performs the same recursion over a serde::Serializer. Its deserialization counterpart reads a field name as a runtime string and compares it with each field's compile-time Tag::VALUE.

Against facet and the reflection MVP​

These approaches differ in how they represent and process a type's structure:

ApproachWhat the type's shape becomesWhat processes it
serdeA generated serialization impl per structThe impl calls a chosen serializer
facetData: a const SHAPE generated by a deriveA shared routine, at runtime
Rust MVPData provided by the compiler, without a deriveconst-evaluated code, at compile time
CGPType-level data generated by a deriveA shared trait recursion, monomorphized to direct code

CGP keeps each field's type available to the trait solver. facet's Shape and the MVP's FieldId::type_id() describe it through an opaque value. CGP's Field<Tag, FieldValue> instead carries FieldValue as a type parameter, letting WriteFields require a statically checked writer for that field type. The context's wiring can also select different writers for the same type in different applications. That per-context choice comes from CGP wiring; structural metadata alone does not provide it.

CGP still monomorphizes the recursion for each field list. It avoids writing a serializer per type and adds per-context choice, but it does not provide facet's shared runtime code. CGP also requires a HasFields implementation, usually supplied by a derive; it cannot inspect an arbitrary foreign type without that implementation.

Checking generic code and concrete wiring​

Rust checks CGP's generic implementations against their declared trait bounds. For example, it checks FieldsWriter without knowing which concrete struct it will process. Zig's comptime routines are checked at instantiation, and Rust's reflection experiment can also produce errors during evaluation for a concrete type. Rust still checks a const fn's body against its declared types and bounds.

CGP checks concrete dependencies when an operation is used or explicitly asserted. Wiring is lazy, so a delegation entry alone does not prove that its provider can run. check_components! forces that check for the listed components and parameters, reporting missing dependencies beside the wiring. The type classes page explains the trait-system connection.

Selecting behavior and types through the same wiring​

CGP combines structural access with implementation selection. The Context: CanWriteValue<FieldValue> bound lets the same traversal use different field writers in different contexts. #[cgp_type] also lets a context select an abstract type through wiring. Reflection frameworks can associate behavior with metadata too; Bevy, for example, stores TypeData in its runtime registry. CGP resolves its choices through traits at compile time.

What each approach costs​

Reflection reduces the need to write inspection code for each user type. Runtime descriptors can also support shared code, as facet does, while compile-time introspection can generate direct accesses. Neither approach guarantees a particular compile time or binary size.

Runtime reflection moves some checks into execution. A field lookup by string can fail after a rename, and dynamic dispatch or registry lookup can add runtime work. Compile-time reflection moves those operations into compilation, but type-dependent failures may surface only for a concrete instantiation. Rust's tracking issue explicitly raises this concern.

CGP requires exposed field shapes, explicit wiring, and specialized code for each field list. Learning the type-level representation and tracing recursive trait errors are additional costs. cargo cgp check leads with the root cause for the classes it recognizes, and the tool does not yet reshape every class. The Modularity Hierarchy compares these costs with simpler approaches.

Where reflection is the better choice​

Runtime reflection fits programs that inspect types while running: an editor over live values, a heterogeneous component registry, or deserialization into a type chosen from configuration. Some language reflection systems can also inspect foreign types without a CGP derive. Constructing a new nominal type from a computed shape calls for a facility such as Zig's @Type or C++26's splicers. CGP fits generic operations over known shapes when static field types and per-context behavior matter.

CGP and Rust's emerging compile-time reflection complement each other more than they compete. The MVP produces reflection as const values, which libraries that reflect over values can consume directly. CGP consumes reflection as types, which the MVP does not supply. For CGP to drop its derive, the compiler would need to expose a type's shape as types. Until then, CGP's derive stands in for that compiler-provided view.

What to expect that differs​

CGP's structural interface differs from a reflection API in several ways:

  • Shapes are types. A recursive trait implementation processes a field list; there is no descriptor value to iterate over imperatively.
  • Field types remain available. A Field<Tag, Value> carries Value as a type parameter, so trait bounds can require an operation for that exact type.
  • Shapes must be exposed. Derives such as HasFields and CgpData provide the required traits. CGP cannot inspect an arbitrary foreign type that lacks those implementations.
  • Nominal types must be declared. CGP can compose products and sums, but it cannot generate a new nominal struct or enum from a computed shape as Zig's @Type can.

Where to go next​

These pages develop the constructs and the neighbouring comparisons:

Sources​

The Zig snippet was compiled with Zig 0.16; the Rust snippet is the nightly source's own doc test and is unstable. The CGP snippets were compiled against cgp 0.8.0 with a check_components! assertion on the wired context.


An AI agent wrote this page using the CGP knowledge base. Its CGP code was verified against the library's source and its other snippets against the toolchains named in Sources. See How AI is used in this project.