Skip to main content

CanRun

Run a task named at the type level to a Result<(), Error>, with the behavior chosen through wiring.

Overview​

In Context-Generic Programming (CGP), CanRun<Code> gives a context a uniform way to execute a unit of work selected at the type level. CGP enables pluggable trait implementations in Rust, and CanRun is the component that lets a context plug in a task runner per code. The unit of work is identified by a Code type parameter, a phantom tag rather than a value, so a single context, the type the implementation runs against, can host many distinct tasks, one per Code, and dispatch each to its own provider. Running a task here means invoking the provider wired for that Code and awaiting an asynchronous Result<(), Error>: the task either completes or produces the context's abstract error. The component carries no input or output beyond success-or-error, so it models a fire-and-complete action rather than a transformation, which separates it from the handler family that maps an Input to an Output.

CanRun is the execution layer that ties a CGP application together: a runner provider typically reaches the context's runtime through HasRuntime to spawn or await work, and dispatches to other components to do the actual job. Application code calls CanRun to set everything in motion. Its companion CanSendRun is the variant whose returned future is Send, for when the work must cross a thread boundary.

Definition​

CanRun is defined as:

#[cgp_component(Runner)]
#[async_trait]
#[derive_delegate(UseDelegate<Code>)]
#[use_type(HasErrorType.Error)]
pub trait CanRun<Code> {
async fn run(&self, _code: PhantomData<Code>) -> Result<(), Error>;
}

Its attributes:

  • #[cgp_component] — turns the trait into a component: its argument names the provider trait Runner that implementations target and the wiring key RunnerComponent, while CanRun stays the consumer trait callers use.
  • #[async_trait] — rewrites the async fn into a method returning -> impl Future, the lint-clean, allocation-free form.
  • #[derive_delegate] — generates a UseDelegate provider that dispatches on the Code type, so a context can route each Code to its own provider; the open statement is the modern sugar for the same dispatch.
  • #[use_type] — adds HasErrorType as a supertrait and rewrites the bare Error to <Self as HasErrorType>::Error.

Usage​

CanRun is imported from cgp::extra::run, with its provider trait Runner and its key RunnerComponent; none of them is in the prelude, and the component carries no #[prefix]. Its method is async and takes only a Code tag:

async fn run(&self, _code: PhantomData<Code>) -> Result<(), Error>;

A context gains the operation by wiring RunnerComponent to a provider. Because the component dispatches on Code, the idiomatic way a context hosts several tasks is the open statement, routing each task tag to its own provider:

delegate_components! {
App {
open RunnerComponent;

@RunnerComponent.ActionA: RunWithFooBar,
@RunnerComponent.ActionB: SpawnAndRun<ActionA>,
}
}

With this wiring, app.run(PhantomData::<ActionA>) runs the RunWithFooBar provider while app.run(PhantomData::<ActionB>) runs SpawnAndRun<ActionA>. A runner provider is a normal CGP provider written for the Runner provider trait; it receives &Context and the PhantomData<Code> tag and may call other components on the context, fetching values or performing effects, before it completes. Existing code often wires the same dispatch with the older UseDelegate<Code> table, which the open statement supersedes.

Examples​

A spawning runner provider requires the context to be CanSendRun so it can hand a Send future to a spawner, and runs an inner task on a background thread. spawn stands for any function with the signature of tokio::spawn, which requires a Send + 'static future. The wiring is the open table from Usage:

#[cgp_impl(new SpawnAndRun<InCode>: RunnerComponent)]
#[use_type(HasErrorType.Error)]
impl<Code, InCode> Runner<Code>
where
Self: 'static + Send + Clone + CanSendRun<InCode>,
{
async fn run(&self, _code: PhantomData<Code>) -> Result<(), Error> {
let context = self.clone();

spawn(async move {
let _ = context.send_run(PhantomData).await;
});

Ok(())
}
}

SpawnAndRun<InCode> runs the task Code by cloning the context and spawning the inner task InCode. The spawner requires a Send + 'static future, which context.send_run(PhantomData::<InCode>) returns, so the bound Self: CanSendRun<InCode> makes the spawn type-check. None of the abstract task or error types carry Send bounds; that requirement is discharged only at the concrete CanSendRun proxy. App is an environmental context, and the task is a type-level Code selector the wiring dispatches on.

When to use it​

Reach for CanRun to model a unit of work a context executes to completion, such as a background job, a startup action, or a scheduled task, especially when one context hosts several such tasks that should each dispatch to their own provider. It is the entry point application code calls, and it composes with HasRuntime for the runtime the work runs on.

Reach for the handler family instead when the work transforms an Input into an Output rather than only succeeding or failing, and reach for CanSendRun when the future must be Send to be spawned across threads. For a synchronous action that cannot fail, a plain method or a Computer is simpler than a runner.

  • CanSendRun / SendRunner — the variant whose future is Send, for spawning across threads.
  • HasRuntime — the runtime a runner provider reaches to spawn or await work.
  • HasErrorType — the supertrait supplying the Self::Error a task fails with.
  • Handler family — the computation components a runner dispatches to, which transform an input rather than only completing.
  • #[derive_delegate] — generates the per-Code dispatch this uses.

The ideas behind it:

Source​

  • CanRun / Runner and CanSendRun / SendRunner: cgp-run/src/lib.rs, reached from the facade as cgp::extra::run.
  • The #[cgp_component] and #[derive_delegate] expansions they rely on: cgp-macro-core/src/

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.