Trait Runtime 

pub trait Runtime:
    Send
    + Sync
    + 'static {
    // Required methods
    fn spawn_on_current_core(
        &self,
        future: Pin<Box<dyn Future<Output = ()> + 'static>>,
    );
    fn spawn_on_core(
        &self,
        core_id: CoreId,
        future: Pin<Box<dyn Future<Output = ()> + Send + 'static>>,
    ) -> Result<(), SpawnError>;
    fn spawn_factory_on_core(
        &self,
        core_id: CoreId,
        factory: Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = ()> + 'static>> + Send + 'static>,
    ) -> Result<(), SpawnError>;
    fn spawn_background_blocking(
        &self,
        work: Box<dyn FnOnce() -> Result<Box<dyn Any + Send>, ProximaError> + Send>,
    ) -> BackgroundHandle<Box<dyn Any + Send>>;
    fn timer_at(
        &self,
        deadline: Instant,
    ) -> Pin<Box<dyn Future<Output = ()> + 'static>>;
    fn num_cores(&self) -> usize;
    fn current_core(&self) -> CoreId;
}

Per-core executor abstraction. Implementations select the concrete threading + I/O model:

• Default: tokio current-thread runtimes, one per pinned CPU core, spawned at app construction (this crate’s tokio module, feature tokio; the umbrella spells the same switch runtime-tokio).
• Alternatives: monoio, glommio, custom kernels — all addressable via the same trait surface.

Futures spawned via spawn_on_current_core are !Send by intent: each task is pinned to its core for life. spawn_on_core and spawn_background_blocking are the explicit cross-thread escape hatches.

Required Methods

fn spawn_on_current_core( &self, future: Pin<Box<dyn Future<Output = ()> + 'static>>, )

Spawn a future on the current core’s executor. Future is !Send by default — it lives on this thread until completion. Use this for per-connection handlers, per-request work, and runtime-internal bookkeeping.

fn spawn_on_core( &self, core_id: CoreId, future: Pin<Box<dyn Future<Output = ()> + Send + 'static>>, ) -> Result<(), SpawnError>

Spawn a future on a designated core’s executor. The future must be Send because it traverses the per-core message channel before the target core picks it up.

Returns Err(SpawnError::InboxFull) when the target core’s inbox lane is at capacity — callers must explicitly choose to retry (use spawn_on_core_blocking_with) or shed load. The future is consumed on Err; retrying requires rebuilding it. Returns Err(SpawnError::Disconnected) when the target core has shut down.

fn spawn_factory_on_core( &self, core_id: CoreId, factory: Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = ()> + 'static>> + Send + 'static>, ) -> Result<(), SpawnError>

Cross-thread dispatch of a future factory: a Send closure that runs on the target core and there constructs a ?Send future. The factory and its captures cross the per-core channel; the future itself is built locally on the destination core and stays there for life. This is what lets a caller (e.g. App::run_until_signal running on outer tokio) inject a per-core listener loop that internally awaits ?Send Pipe::calls.

Same back-pressure semantics as Self::spawn_on_core: returns Err(SpawnError::InboxFull) on saturation (factory is consumed), Err(SpawnError::Disconnected) on shutdown.

fn spawn_background_blocking( &self, work: Box<dyn FnOnce() -> Result<Box<dyn Any + Send>, ProximaError> + Send>, ) -> BackgroundHandle<Box<dyn Any + Send>>

Submit a CPU-bound blocking task to the background work-stealing pool. The returned handle is Send so the awaiter (which lives on a per-core runtime) can park until the result is ready, then resume on its core.

fn timer_at( &self, deadline: Instant, ) -> Pin<Box<dyn Future<Output = ()> + 'static>>

Yield a future that resolves at deadline. Used for timeouts and scheduled work. Implementations drive the timer via their per-core timer wheel. Only available with std because Instant requires std — keeps &dyn Runtime object-safe without an associated type.

fn num_cores(&self) -> usize

Number of pinned cores. Stable across the lifetime of the runtime.

fn current_core(&self) -> CoreId

The current core’s id. Implementations panic if called from outside a runtime worker thread — that’s a bug at the call site, not a recoverable error.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors