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 run_compiled( &self, program: &CompiledGraph, inputs: &[&Tensor], ) -> Result<Vec<Tensor>>

Run a compiled graph through runtime-owned prepared execution.

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 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: &[&Tensor], ) -> Result<ExecutionHandle>

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.