HasRuntime
Hand out a borrow of the context's runtime value, so effectful code reaches it generically.
Overview
In Context-Generic Programming (CGP), HasRuntime lets context-generic code obtain the
runtime it runs against without naming a concrete one. CGP enables pluggable trait implementations
in Rust, and HasRuntime is the getter that lets a context plug in its runtime value.
A runtime here is whatever object provides the services an application needs at execution time,
spawning tasks, sleeping, opening sockets, reading the clock, and different deployments want different
runtimes: Tokio in production, a mock in tests, a single-threaded executor in a benchmark. Rather than
thread a concrete runtime type through every signature, the context, the type the method runs
on, which supplies the values it needs as its fields, stores one runtime value,
and HasRuntime is the getter that borrows it.
HasRuntime answers how to obtain the runtime value; its companion
HasRuntimeType answers what the runtime type is. The two are split because
the questions are independent: some code names only the runtime type and never touches a value, and
needs HasRuntimeType alone, while code that performs effects needs HasRuntime, which supertraits
HasRuntimeType so the value's type is always in scope. HasRuntime is the seam where context-generic
logic meets the concrete async machinery, which is why it underpins the CanRun family
of task runners.
Definition
HasRuntime is defined as:
#[cgp_getter]
#[use_type(HasRuntimeType.Runtime)]
pub trait HasRuntime {
fn runtime(&self) -> &Runtime;
}
Its attributes:
#[cgp_getter]— makes this a getter component: it derives the provider name from the trait name and generates aUseFieldimpl, so the field it reads is chosen by wiring.#[use_type]— addsHasRuntimeTypeas a supertrait and rewrites the bareRuntimeto<Self as HasRuntimeType>::Runtime.
Usage
HasRuntime is imported from cgp::extra::runtime, with its provider trait RuntimeGetter and its
key RuntimeGetterComponent. None of the runtime names is in the prelude. It is a getter component:
its method borrows the runtime value out of a borrow of the context, returning &Runtime, where
Runtime is the abstract type supplied by
HasRuntimeType:
fn runtime(&self) -> &Runtime;
A context supplies the value either by implementing HasRuntime directly or, more commonly, by wiring
RuntimeGetterComponent to a UseField provider that names the field
holding the runtime. Because HasRuntime supertraits HasRuntimeType, a context cannot satisfy it
without also having declared its runtime type, which keeps the returned &Runtime well-defined. A
context that stores its runtime in a runtime field wires:
delegate_components! {
App {
RuntimeTypeProviderComponent: UseType<TokioRuntime>,
RuntimeGetterComponent: UseField<Symbol!("runtime")>,
}
}
One entry fixes the abstract runtime type, and the other says where the value lives. Context-generic
providers then depend on HasRuntime and call self.runtime() to obtain a &RuntimeOf,
never naming the concrete runtime. Declare that dependency with
#[uses(HasRuntime)] on a provider.
Examples
A context declares its runtime type and the field holding the value, and a provider reaches the runtime generically:
use cgp::core::field::impls::UseField;
use cgp::prelude::*;
use cgp::extra::runtime::{
HasRuntime, RuntimeGetterComponent, RuntimeOf, RuntimeTypeProviderComponent,
};
pub struct TokioRuntime { /* handle, clock, etc. */ }
#[derive(HasField)]
pub struct App {
pub runtime: TokioRuntime,
}
delegate_components! {
App {
RuntimeTypeProviderComponent: UseType<TokioRuntime>,
RuntimeGetterComponent: UseField<Symbol!("runtime")>,
}
}
check_components! {
App {
RuntimeTypeProviderComponent,
RuntimeGetterComponent,
}
}
fn runtime_of<Context>(context: &Context) -> &RuntimeOf<Context>
where
Context: HasRuntime,
{
context.runtime()
}
App resolves HasRuntimeType with Runtime = TokioRuntime through UseType, and resolves
HasRuntime by reading its runtime field through UseField. runtime_of names neither
TokioRuntime nor any field, so swapping UseType<TokioRuntime> for UseType<MockRuntime> in a test
context retargets it at the mock with no change to its body. App is an environmental context, and
the component targets it.
When to use it
Reach for HasRuntime in any provider that performs an effect against the runtime, such as spawning
a task, awaiting a timer, or opening a connection, and reach it as a #[uses(HasRuntime)] dependency so
the bound stays off the consumer trait. It is the standard way effectful CGP code stays generic over the
runtime, and it makes the same task-running code reusable across a Tokio context, a mock, and a
test executor with only a wiring change.
Reach for HasRuntimeType alone when code names the runtime type but never
touches a value, which asks for exactly the trait it uses. Do not reach for HasRuntime when a
value the provider needs is not really the runtime but an ordinary context field, where an
#[implicit] argument is simpler.
Related constructs
HasRuntimeType— the companion that declares the runtime type this borrows.CanRun/Runner— the primary consumer, reaching the runtime throughHasRuntimeto execute work.CanSendRun/SendRunner— theSend-future variant of the runner.#[cgp_getter]— the macroHasRuntimeis defined with.UseField— the provider that reads the runtime value from a named field.
The ideas behind it:
- Handlers — the effectful computation family that reaches the runtime through this getter.
- Abstract types — the abstract runtime type a context chooses for itself.
Source
HasRuntimeand itsRuntimeGetterprovider trait:has_runtime.rs- Re-exported through
cgp::extra::runtime:cgp-runtime/src/lib.rs - The
#[cgp_getter]expansion it relies on:cgp-macro-core/src/types/
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.