Skip to main content

HasRuntimeType

Declare the abstract runtime type a context runs against, chosen per context through wiring.

Overview​

In Context-Generic Programming (CGP), HasRuntimeType lets context-generic code name the runtime type a context uses without committing to a concrete one. CGP enables pluggable trait implementations in Rust, and HasRuntimeType is the component that lets a context plug in its runtime type. A runtime is whatever object supplies the services an application needs at execution time, and different deployments want different runtimes: Tokio in production, a mock in tests, an executor in a benchmark. HasRuntimeType gives the context, the type that implements the trait, an abstract associated Runtime type, resolved to a concrete one at wiring time.

The runtime abstraction is split into a type component and a getter component because the two questions are independent. HasRuntimeType answers what the runtime type is, while its companion HasRuntime answers how to obtain the runtime value from a borrow of the context. Some code is generic only over the runtime type: it names types the runtime exposes but never touches a runtime value, and it needs HasRuntimeType alone. Keeping the type separate means such a bound asks for exactly the trait it uses.

Definition​

HasRuntimeType is defined as:

#[cgp_type]
pub trait HasRuntimeType {
type Runtime;
}

pub type RuntimeOf<Context> = <Context as HasRuntimeType>::Runtime;

Its attributes:

  • #[cgp_type] — makes this an abstract-type component rather than a plain trait: it generates the provider trait, the component marker, and a UseType impl, so a context binds the concrete type by wiring.

Usage​

HasRuntimeType is imported from cgp::extra::runtime, with the RuntimeOf alias, the provider trait RuntimeTypeProvider, and the key RuntimeTypeProviderComponent. None of them is in the prelude, and the component carries no #[prefix]. It is an abstract-type component with a single associated type, Runtime, carrying no bound, so any concrete type may be plugged in. A context supplies the type either by implementing HasRuntimeType directly or, more commonly, by wiring RuntimeTypeProviderComponent to UseType<R>:

delegate_components! {
App {
RuntimeTypeProviderComponent: UseType<TokioRuntime>,
}
}

This makes the context resolve HasRuntimeType with Runtime = TokioRuntime, and from then on the alias RuntimeOf<Context> is TokioRuntime. Generic code names the runtime type with the #[use_type] attribute, which imports it as the bare name Runtime, or through the RuntimeOf<Context> alias.

Examples​

A context fixes its runtime type, and generic code names it without committing to a concrete one:

use cgp::prelude::*;
use cgp::extra::runtime::{HasRuntimeType, RuntimeOf, RuntimeTypeProviderComponent};

pub struct TokioRuntime { /* handle, clock, etc. */ }

pub struct App;

delegate_components! {
App {
RuntimeTypeProviderComponent: UseType<TokioRuntime>,
}
}

check_components! {
App {
RuntimeTypeProviderComponent,
}
}

fn describe<Context>() -> &'static str
where
Context: HasRuntimeType,
RuntimeOf<Context>: Default,
{
"the context has a default-constructible runtime type"
}

App resolves HasRuntimeType with Runtime = TokioRuntime through UseType, so RuntimeOf<App> is TokioRuntime. describe names only the runtime type and never a runtime value, which is exactly the case HasRuntimeType serves alone. App is an environmental context, and the component targets it.

When to use it​

Reach for HasRuntimeType when code names the runtime type but never touches a runtime value. That is the narrower of the two runtime components, and asking for it alone keeps a bound honest about what it uses. It is also the type half a context must wire before it can satisfy HasRuntime, because the getter borrows a value of this type.

Reach for HasRuntime instead when a provider actually performs an effect and needs the runtime value, since HasRuntime supertraits this one and gives access to both. For an abstract type that is not the runtime, define your own component with #[cgp_type] rather than reusing this one.

  • HasRuntime — the getter companion that borrows a value of this type.
  • #[cgp_type] — the macro HasRuntimeType is defined with.
  • HasType / TypeProvider — the tag-indexed abstract-type component; a TypeProvider can back this one through its generated WithProvider impl.
  • UseType — the provider that fixes the runtime type in wiring.
  • CanRun / Runner — the task runner whose providers reach the runtime.

The ideas behind it:

  • Abstract types — the associated types a context chooses for itself.

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.