Struct Runtime 

pub struct Runtime(/* private fields */);

Runtime owner for immutable configuration snapshots.

Examples

use tenferro_runtime::Runtime;

let runtime = Runtime::builder().build()?;
assert_eq!(runtime.snapshot()?.engine_count(), 0);

Implementations

impl Runtime

pub fn builder() -> RuntimeConfigBuilder

Return a consuming runtime configuration builder.

pub fn id(&self) -> RuntimeId

Return this runtime’s opaque identity.

pub fn snapshot(&self) -> Result<Arc<RuntimeConfigSnapshot>, RuntimeStateError>

Clone the current immutable runtime snapshot.

Errors

Returns RuntimeStateError::Poisoned when the active snapshot lock was poisoned by another thread.

pub fn epoch(&self) -> Result<RuntimeEpoch, RuntimeStateError>

Return the currently published runtime epoch without locking the active snapshot.

Errors

Returns RuntimeStateError only if runtime state invariants have been violated internally.

pub fn prepared_cache_limits( &self, ) -> Result<PreparedPlanCacheLimits, RuntimeStateError>

Return current prepared-plan cache limits.

Examples

use tenferro_runtime::Runtime;

let runtime = Runtime::builder().build()?;
assert_eq!(runtime.prepared_cache_limits()?, Default::default());

Errors

Returns RuntimeStateError when the runtime-owned prepared cache state cannot be accessed.

pub fn set_prepared_cache_limits( &self, limits: PreparedPlanCacheLimits, ) -> Result<(), RuntimeStateError>

Replace current prepared-plan cache limits and evict retained entries until the new limits are satisfied.

Examples

use std::num::NonZeroUsize;
use tenferro_runtime::{PreparedPlanCacheLimits, Runtime};

let runtime = Runtime::builder().build()?;
runtime.set_prepared_cache_limits(PreparedPlanCacheLimits {
    max_entries: NonZeroUsize::new(1).unwrap(),
    max_retained_bytes: NonZeroUsize::new(1024).unwrap(),
    max_in_flight_entries: NonZeroUsize::new(1).unwrap(),
    max_queued_distinct_keys: NonZeroUsize::new(1).unwrap(),
})?;
assert_eq!(runtime.prepared_cache_limits()?.max_entries.get(), 1);

Errors

Returns RuntimeStateError when the runtime-owned prepared cache state cannot be accessed.

pub fn clear_prepared_cache(&self) -> Result<(), RuntimeStateError>

Clear the runtime-owned prepared-plan cache.

Examples

use tenferro_runtime::Runtime;

let runtime = Runtime::builder().build()?;
runtime.clear_prepared_cache()?;

Errors

Returns RuntimeStateError when the runtime-owned prepared cache state cannot be accessed.

pub fn cache_stats(&self) -> Result<RuntimeCacheStats, RuntimeCacheError>

Return aggregate cache statistics for the runtime and registered cache owners.

Examples

use tenferro_runtime::Runtime;

let runtime = Runtime::builder().build()?;
assert_eq!(runtime.cache_stats()?.prepared_plans.entries, 0);

Errors

Returns RuntimeCacheError when the runtime cache or a registered cache owner cannot report statistics.

pub fn clear_caches(&self) -> Result<(), RuntimeCacheError>

Clear runtime-owned prepared plans and all registered engine/extension cache owners.

Examples

use tenferro_runtime::Runtime;

let runtime = Runtime::builder().build()?;
runtime.clear_caches()?;

Errors

Returns RuntimeCacheError when the runtime cache or a registered cache owner cannot be cleared.

pub fn prepare_extension_immediate( &self, engine_id: &EngineId, op: &dyn ExtensionOp, signature: &InputSignature, ) -> Result<PrepareCapability>

Resolve and prepare a single extension operation for immediate eager execution against one exact engine, bypassing SemanticProgram planning and the prepared-program cache.

Provider selection is pinned to engine_id (the eager context’s exact engine); the op is prepared only when that engine is executable, owns the family’s extension slot, and accepts every input signature entry. Capability resolution happens before any planning fields are built. Returns PrepareCapability::Unsupported when engine_id is not registered, is not executable, or has no extension slot for the op’s family so callers may fall back to the compiled path.

Examples

use std::any::Any;
use std::hash::Hasher;
use std::sync::Arc;

use tenferro_cpu::CpuBackend;
use tenferro_ops::ExtensionShapeContext;
use tenferro_runtime::extension::ExtensionOp;
use tenferro_runtime::{
    ExtensionEngine, ExtensionModule, ExtensionModuleError, ExtensionModuleId,
    ExtensionModuleRegistrar, ExtensionPlanningConfig, InputSignature, PrepareCapability,
    PrepareError, PrepareOptions, Runtime, UnsupportedReason, Tensor, TensorRead,
};
use tenferro_tensor::DType;

#[derive(Debug)]
struct Probe;

impl ExtensionOp for Probe {
    fn family_id(&self) -> &'static str { "tenferro-tests.immediate-probe.v1" }
    fn payload_hash(&self, _hasher: &mut dyn Hasher) {}
    fn payload_eq(&self, other: &dyn ExtensionOp) -> bool { other.as_any().downcast_ref::<Self>().is_some() }
    fn clone_arc(&self) -> Arc<dyn ExtensionOp> { Arc::new(Self) }
    fn as_any(&self) -> &dyn Any { self }
    fn input_count(&self) -> usize { 1 }
    fn output_count(&self) -> usize { 1 }
    fn infer_output_meta(&self, ctx: &mut ExtensionShapeContext<'_>) -> tenferro_tensor::Result<Vec<(DType, Vec<tenferro_ops::SymDim>)>> {
        Ok(vec![(ctx.input_dtype(0)?, ctx.input_shape(0)?.to_vec())])
    }
}

#[derive(Debug)]
struct Config;

impl ExtensionPlanningConfig for Config {
    fn family_id(&self) -> &'static str { Probe.family_id() }
    fn as_any(&self) -> &dyn Any { self }
    fn payload_hash(&self, _state: &mut dyn Hasher) {}
    fn payload_eq(&self, other: &dyn ExtensionPlanningConfig) -> bool { other.as_any().downcast_ref::<Self>().is_some() }
    fn retained_bytes(&self) -> usize { 0 }
}

#[derive(Debug)]
struct Module(ExtensionModuleId);

impl ExtensionModule for Module {
    fn module_id(&self) -> &ExtensionModuleId { &self.0 }
    fn configure(&self, registrar: &mut ExtensionModuleRegistrar<'_>) -> Result<(), ExtensionModuleError> {
        let Ok(engine_id) = tenferro_cpu::runtime_engine_id() else {
            // Best-effort: an unresolvable engine id keeps the op unsupported.
            return Ok(());
        };
        registrar.register_engine(Arc::new(NoopEngine { engine_id: engine_id.clone() }))?;
        registrar.register_planning_config(engine_id, Arc::new(Config))?;
        Ok(())
    }
}

#[derive(Debug)]
struct NoopEngine { engine_id: tenferro_runtime::EngineId }

impl ExtensionEngine for NoopEngine {
    fn family_id(&self) -> &'static str { Probe.family_id() }
    fn engine_id(&self) -> &tenferro_runtime::EngineId { &self.engine_id }
    fn context_identity(&self) -> tenferro_runtime::ExecutionContextIdentity { tenferro_runtime::ExecutionContextIdentity::of::<CpuBackend>() }
    fn prepare(&self, _request: tenferro_runtime::ExtensionPrepareRequest<'_>) -> Result<PrepareCapability, PrepareError> {
        Ok(PrepareCapability::Unsupported(UnsupportedReason::Operation { operation: Probe.family_id() }))
    }
}

let backend = CpuBackend::new();
let mut builder = Runtime::builder();
builder.register_engine(tenferro_cpu::runtime_engine_registration(&backend)?)?;
builder.install_extension_module(Arc::new(Module(ExtensionModuleId::new("tenferro-tests.immediate-probe.module")?)))?;
let runtime = builder.build()?;
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
let signature = InputSignature::from_reads(&[TensorRead::from_tensor(&tensor)])?;
let engine_id = tenferro_cpu::runtime_engine_id()?;
let capability = runtime.prepare_extension_immediate(&engine_id, &Probe, &signature)?;
assert!(matches!(capability, PrepareCapability::Unsupported { .. }));

Errors

Returns crate::Error::RuntimeState when the snapshot cannot be read or an engine’s preparation fails, with the typed [PrepareError]/RuntimeStateError source retained.

pub fn run_compiled( &self, program: &CompiledGraph, inputs: &[&Tensor], ) -> Result<Vec<Tensor>>

Run a compiled graph synchronously with borrowed tensor inputs.

The borrows remain valid until this call returns; this surface never detaches work. Asynchronous Self::submit accepts only the owning super::execution::ExecutionInputs package.

Examples

use tenferro_runtime::{Runtime, TracedTensor, GraphCompiler};

let runtime = Runtime::builder().build()?;
let x = TracedTensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
let program = GraphCompiler::new().compile(&x)?;
let error = runtime.run_compiled(&program, &[]).unwrap_err();
assert!(error.to_string().contains("no eligible engine"));

Errors

Returns crate::Error::UnboundPlaceholder when no explicit inputs are supplied and a semantic input has no bound default tensor. Returns crate::Error::GraphInputCountMismatch, crate::Error::PlaceholderDtypeMismatch, crate::Error::PlaceholderRankMismatch, crate::Error::PlaceholderShapeMismatch, or crate::Error::PlaceholderShapeBoundExceeded when ordered runtime inputs do not match the compiled graph metadata. Returns crate::Error::RuntimeState when runtime preparation, schedule validation, snapshot access, stale epoch checks, or execution-bridge resolution fails, including crate::PrepareError::NoInputIngress when no engine accepts an input’s physical backend/allocation domain, crate::PrepareError::MissingTransferProvider when ingress cannot reach its first scheduled consumer, a runtime with no eligible engine, or no execution bridge for the prepared engine. Backend execution may also return concrete backend variants such as crate::Error::Unsupported, crate::Error::Validation, or crate::Error::Extension.

pub fn execute_scoped_read_only<'env>( &self, program: &CompiledGraph, inputs: ScopedReadInputs<'env>, ) -> Result<ScopedExecutionOutcome<'env>, ScopedSubmitRejected<'env>>

Execute borrowed read-only inputs synchronously through retirement.

Host/CPU providers may complete this call. Asynchronous device providers reject before admission and return the unchanged borrowed package through crate::ScopedSubmitRejected.

Errors

Returns crate::Error::Unsupported when the selected asynchronous provider cannot execute borrowed inputs synchronously, or crate::ScopedSubmitRejected when pre-admission validation fails. Provider execution failures are reported as crate::runtime::execution::ScopedExecutionOutcome::RetiredFailed.

pub fn prepare_compiled( &self, program: &CompiledGraph, inputs: &[&Tensor], ) -> Result<PreparedCompiledGraph>

Prepare a compiled graph for repeated execution with the same runtime.

Preparation validates the supplied input metadata, selects a runtime engine, and caches the staged execution plan. Use Self::run_prepared for steady-state execution when the same compiled graph is run many times.

Errors

Returns crate::Error::UnboundPlaceholder when no explicit inputs are supplied and a semantic input has no bound default tensor. Returns crate::Error::GraphInputCountMismatch, crate::Error::PlaceholderDtypeMismatch, crate::Error::PlaceholderRankMismatch, crate::Error::PlaceholderShapeMismatch, or crate::Error::PlaceholderShapeBoundExceeded when ordered runtime inputs do not match the compiled graph metadata. Returns crate::Error::RuntimeState when runtime preparation, schedule validation, snapshot access, stale epoch checks, or execution-bridge resolution fails, including crate::PrepareError::NoInputIngress when no engine accepts an input’s physical backend/allocation domain, crate::PrepareError::MissingTransferProvider when ingress cannot reach its first scheduled consumer, a runtime with no eligible engine, or no execution bridge for the prepared engine.

pub fn run_prepared( &self, prepared: &PreparedCompiledGraph, inputs: &[&Tensor], ) -> Result<Vec<Tensor>>

Run a graph previously prepared by Self::prepare_compiled.

Errors

Returns metadata validation errors for incompatible inputs, a runtime state error with crate::InputIngressContractError as its typed source when an input’s physical residency does not match the prepared ingress, or a runtime state error if the prepared handle belongs to a different runtime or a stale runtime epoch.

pub fn submit( &self, program: &CompiledGraph, inputs: ExecutionInputs, ) -> Result<ExecutionHandle, SubmitError>

Submit a compiled graph for asynchronous runtime-owned execution.

Dropping the returned handle detaches the observer without blocking. Use super::execution::ExecutionHandle::wait to observe completion.

Errors

Returns the same crate::PrepareError::InputSignature, crate::PrepareError::Specialization, crate::PrepareError::NoEligibleEngine, crate::PrepareError::NoInputIngress, and crate::PrepareError::MissingTransferProvider failures as Self::run_compiled before the worker is submitted. Returns a runtime state error with crate::SubmissionError as its typed source if the operating system rejects worker creation after admission.

pub fn run_compiled_values( &self, program: &CompiledGraph, inputs: &[&Tensor], ) -> Result<Vec<TensorValue>>

Run a compiled graph and preserve lazy owned output views.

Examples

use tenferro_runtime::{Runtime, TracedTensor, GraphCompiler};

let runtime = Runtime::builder().build()?;
let x = TracedTensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
let program = GraphCompiler::new().compile(&x)?;
let error = runtime.run_compiled_values(&program, &[]).unwrap_err();
assert!(error.to_string().contains("no eligible engine"));

Errors

Returns crate::Error::UnboundPlaceholder when no explicit inputs are supplied and a semantic input has no bound default tensor. Returns crate::Error::GraphInputCountMismatch, crate::Error::PlaceholderDtypeMismatch, crate::Error::PlaceholderRankMismatch, crate::Error::PlaceholderShapeMismatch, or crate::Error::PlaceholderShapeBoundExceeded when ordered runtime inputs do not match the compiled graph metadata. Returns crate::Error::RuntimeState when runtime preparation, schedule validation, snapshot access, stale epoch checks, or execution-bridge resolution fails, including crate::PrepareError::NoInputIngress when no engine accepts an input’s physical backend/allocation domain, crate::PrepareError::MissingTransferProvider when ingress cannot reach its first scheduled consumer, a runtime with no eligible engine, or no execution bridge for the prepared engine. Backend execution may also return concrete backend variants such as crate::Error::Unsupported, crate::Error::Validation, or crate::Error::Extension.

pub fn reconfigure( &self, edit: impl FnOnce(&mut RuntimeReconfiguration<'_>) -> Result<(), RuntimeConfigError>, ) -> Result<RuntimeEpoch, RuntimeReconfigureError>

Transactionally edit and publish runtime configuration.

No user callback runs while the publication lock is held. If another writer publishes over the same base snapshot, this call returns RuntimeReconfigureError::ConcurrentReconfiguration and publishes nothing.

Errors

Returns RuntimeReconfigureError when state access, edit validation, identity allocation, epoch advancement, or compare-and-publish fails. Invalid transfer endpoints are reported as the typed RuntimeConfigError::UnknownTransferEndpointEngine or RuntimeConfigError::UnsupportedTransferEndpointStorage source of RuntimeReconfigureError::Edit.

Trait Implementations

impl Clone for Runtime

fn clone(&self) -> Runtime

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Runtime

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.