Skip to main content

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 a UseField impl, so the field it reads is chosen by wiring.
  • #[use_type] — adds HasRuntimeType as a supertrait and rewrites the bare Runtime to <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.

  • HasRuntimeType — the companion that declares the runtime type this borrows.
  • CanRun / Runner — the primary consumer, reaching the runtime through HasRuntime to execute work.
  • CanSendRun / SendRunner — the Send-future variant of the runner.
  • #[cgp_getter] — the macro HasRuntime is 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​


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.