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 traitRunnerthat implementations target and the wiring keyRunnerComponent, whileCanRunstays the consumer trait callers use.#[async_trait]— rewrites theasync fninto a method returning-> impl Future, the lint-clean, allocation-free form.#[derive_delegate]— generates aUseDelegateprovider that dispatches on theCodetype, so a context can route eachCodeto its own provider; theopenstatement is the modern sugar for the same dispatch.#[use_type]— addsHasErrorTypeas a supertrait and rewrites the bareErrorto<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.
Related constructs
CanSendRun/SendRunner— the variant whose future isSend, for spawning across threads.HasRuntime— the runtime a runner provider reaches to spawn or await work.HasErrorType— the supertrait supplying theSelf::Errora 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-Codedispatch this uses.
The ideas behind it:
- Handlers — the effectful computation family a runner drives.
- Recovering
Sendbounds — the workaround theSendrunner variant embodies.
Source
CanRun/RunnerandCanSendRun/SendRunner:cgp-run/src/lib.rs, reached from the facade ascgp::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.