pub struct EagerRuntime { /* private fields */ }Expand description
Shared eager execution context for tensors on a backend.
Reusing one context lets eager tensors share backend state, extension runtime caches, and gradient storage across a computation.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.add(&x, &y)).unwrap();
assert_eq!(z.value().unwrap().as_slice::<f64>().unwrap(), &[3.0]);Implementations§
Source§impl EagerRuntime
impl EagerRuntime
Sourcepub fn new() -> Result<Arc<Self>>
pub fn new() -> Result<Arc<Self>>
Create a shared eager execution context.
The context stores no engine: every operation runs on the engine the caller passes in.
§Examples
use tenferro_ad::EagerRuntime;
let ctx = EagerRuntime::new()?;
assert_eq!(std::sync::Arc::strong_count(&ctx), 1);§Errors
Returns Error::RuntimeStateSource when the prepared-program runtime
cannot be configured, preserving the underlying RuntimeConfigError.
Sourcepub fn with_ad_context(ad: &AdContext) -> Result<Arc<Self>>
pub fn with_ad_context(ad: &AdContext) -> Result<Arc<Self>>
Create a shared eager execution context that uses the semantic
extension rules and AD transform cache of ad.
§Examples
use tenferro_ad::{AdContext, EagerRuntime};
let ad = AdContext::builder().build().unwrap();
let ctx = EagerRuntime::with_ad_context(&ad)?;
assert_eq!(std::sync::Arc::strong_count(&ctx), 1);§Errors
Returns Error::RuntimeStateSource when the prepared-program runtime
cannot be configured.
Sourcepub fn id(&self) -> ContextId
pub fn id(&self) -> ContextId
Return an opaque identifier for this context.
§Examples
use tenferro_ad::{EagerRuntime};
let ctx = EagerRuntime::new()?;
assert_ne!(ctx.id(), EagerRuntime::new()?.id());Sourcepub fn no_grad(&self) -> EagerNoGradGuard
pub fn no_grad(&self) -> EagerNoGradGuard
Disable eager operation recording on the current thread until the guard is dropped.
This is useful for optimizer updates, metric calculations, and other eager computations that should not become part of the AD tape.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64]).unwrap())?;
let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let _guard = ctx.no_grad();
s.mul(&x, &x)
})?;
assert!(!y.tracks_grad());Sourcepub fn capture_trace(&self) -> EagerTraceCaptureGuard
pub fn capture_trace(&self) -> EagerTraceCaptureGuard
Keep semantic-trace recording active for untracked intermediates.
See EagerTraceCaptureGuard for the full contract and an example.
Sourcepub fn install_extension_module(
&self,
module: Arc<dyn ExtensionModule>,
) -> Result<RuntimeEpoch>
pub fn install_extension_module( &self, module: Arc<dyn ExtensionModule>, ) -> Result<RuntimeEpoch>
Install or replace one extension module on this eager context’s runtime.
Eager extension wrappers call this as an idempotent “ensure installed” step. When the exact module instance (same module ID and allocation) is already installed, this is a read-only no-op that returns the current runtime epoch without acquiring the install lock or reconfiguring. The cold or replacement paths keep the transactional install-or-replace behavior, serialized so parallel first-use of the same extension family cannot publish over another thread’s base snapshot.
§Errors
Returns tenferro_runtime::Error::RuntimeState when runtime
reconfiguration fails or the extension module transaction is invalid.
Sourcepub fn clear_caches(&self) -> Result<()>
pub fn clear_caches(&self) -> Result<()>
Clear every cache owned by this eager context.
§Examples
use tenferro_ad::{EagerRuntime};
let ctx = EagerRuntime::new()?;
ctx.clear_caches()?;
assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);
assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);§Errors
Returns tenferro_runtime::Error::RuntimeState when either the
extension cache or AD-transform cache is poisoned.
Sourcepub fn clear_prepared_derivative_cache(&self) -> Result<()>
pub fn clear_prepared_derivative_cache(&self) -> Result<()>
Clear prepared derivative program cache entries.
§Examples
use tenferro_ad::EagerRuntime;
let ctx = EagerRuntime::new()?;
ctx.clear_prepared_derivative_cache()?;
assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);§Errors
Returns tenferro_runtime::Error::RuntimeState if the prepared
derivative cache lock is poisoned.
Sourcepub fn cache_stats(&self) -> Result<EagerRuntimeCacheStats>
pub fn cache_stats(&self) -> Result<EagerRuntimeCacheStats>
Return eager runtime cache-entry and retained-byte stats.
§Examples
use tenferro_ad::{EagerRuntime};
let ctx = EagerRuntime::new()?;
let stats = ctx.cache_stats()?;
assert_eq!(stats.ad_transforms.entries, 0);
assert_eq!(stats.prepared_derivatives.entries, 0);§Errors
Returns tenferro_runtime::Error::RuntimeState when a cache or
AD-transform cache lock is poisoned.
Sourcepub fn ad_transform_cache_limits(&self) -> Result<AdTransformCacheLimits>
pub fn ad_transform_cache_limits(&self) -> Result<AdTransformCacheLimits>
Return the AD transform cache retention limits.
§Examples
use tenferro_ad::EagerRuntime;
let ctx = EagerRuntime::new()?;
assert!(ctx.ad_transform_cache_limits()?.max_entries().get() > 0);§Errors
Returns tenferro_runtime::Error::RuntimeState if the AD-transform
cache lock is poisoned.
Sourcepub fn set_ad_transform_cache_limits(
&self,
limits: AdTransformCacheLimits,
) -> Result<()>
pub fn set_ad_transform_cache_limits( &self, limits: AdTransformCacheLimits, ) -> Result<()>
Replace AD transform cache retention limits.
§Examples
use std::num::NonZeroUsize;
use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
let ctx = EagerRuntime::new()?;
let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
ctx.set_ad_transform_cache_limits(limits)?;
assert_eq!(ctx.ad_transform_cache_limits()?, limits);§Errors
Returns tenferro_runtime::Error::RuntimeState if the AD-transform
cache lock is poisoned while updating limits.
Sourcepub fn clear_ad_transform_caches(&self) -> Result<()>
pub fn clear_ad_transform_caches(&self) -> Result<()>
Clear AD transform cache entries visible through this eager runtime.
§Examples
use tenferro_ad::EagerRuntime;
let ctx = EagerRuntime::new()?;
ctx.clear_ad_transform_caches()?;
assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);§Errors
Returns tenferro_runtime::Error::RuntimeState if the AD-transform
cache lock is poisoned while clearing entries.
Sourcepub fn prepared_derivative_cache_limits(&self) -> Result<AdTransformCacheLimits>
pub fn prepared_derivative_cache_limits(&self) -> Result<AdTransformCacheLimits>
Return prepared derivative cache retention limits.
§Examples
use tenferro_ad::EagerRuntime;
let ctx = EagerRuntime::new()?;
assert!(ctx.prepared_derivative_cache_limits()?.max_entries().get() > 0);§Errors
Returns tenferro_runtime::Error::RuntimeState if the prepared
derivative cache lock is poisoned.
Sourcepub fn set_prepared_derivative_cache_limits(
&self,
limits: AdTransformCacheLimits,
) -> Result<()>
pub fn set_prepared_derivative_cache_limits( &self, limits: AdTransformCacheLimits, ) -> Result<()>
Replace prepared derivative cache retention limits.
§Examples
use std::num::NonZeroUsize;
use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
let ctx = EagerRuntime::new()?;
let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
ctx.set_prepared_derivative_cache_limits(limits)?;
assert_eq!(ctx.prepared_derivative_cache_limits()?, limits);§Errors
Returns tenferro_runtime::Error::RuntimeState if the prepared
derivative cache lock is poisoned.
Sourcepub fn with_eager_session<T, E: From<Error>>(
self: &Arc<Self>,
engine: &mut dyn ExecutionEngine,
f: impl FnOnce(&mut EagerSession<'_>) -> Result<T, E>,
) -> Result<T, E>
pub fn with_eager_session<T, E: From<Error>>( self: &Arc<Self>, engine: &mut dyn ExecutionEngine, f: impl FnOnce(&mut EagerSession<'_>) -> Result<T, E>, ) -> Result<T, E>
Run eager operations on engine.
The callback receives an EagerSession that pairs this runtime with
the borrowed engine; operations recorded through it are differentiable.
Nothing is entered or locked: the engine is simply borrowed for the
callback.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuEngine;
let ctx = EagerRuntime::new()?;
let mut engine = CpuEngine::serial();
let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
let z = ctx.with_eager_session(&mut engine, |s| s.add(&x, &y))?;
assert_eq!(z.value()?.as_slice::<f64>()?, &[3.0]);§Errors
Returns Error::Unsupported when the engine kind cannot be registered
with this runtime or its context identity conflicts with the existing
registration, Error::RuntimeStateSource when the runtime snapshot or
engine registration state is unavailable, and the callback’s own error
unchanged.
Sourcepub fn clear_grads(&self) -> Result<()>
pub fn clear_grads(&self) -> Result<()>
Clear all live gradient slots tracked by this context.
This resets the stored gradients to None without unregistering the
tensors, so future EagerSession::backward calls can accumulate again.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let product = s.mul(&x, &y)?;
s.reduce_sum(&product, Some(&[0]))
})?;
let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
ctx.clear_grads()?;
assert!(x.grad()?.is_none());
assert!(y.grad()?.is_none());§Errors
Returns tenferro_runtime::Error::RuntimeState if a gradient-slot
lock is poisoned while clearing live gradients.
Sourcepub fn constant_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>
pub fn constant_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>
Import a concrete tensor into this context as an untracked constant.
The returned tensor does not participate in gradient tracking.
Use this for fixed masks, quadrature weights, physical constants,
and other data that should not receive gradients. Like
EagerSession::constant_from, it performs no host/device transfer;
use EagerSession::constant_from_host to upload host data into a
device runtime.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let c = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap())?;
let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.add(&x, &c))?;
assert_eq!(z.value()?.as_slice::<f64>().unwrap(), &[4.0, 6.0]);§Errors
Returns tenferro_runtime::Error::RuntimeState when metadata cannot
be registered or the backend lock is poisoned.
Sourcepub fn variable_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>
pub fn variable_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>
Import a concrete tensor into this context as a trainable variable.
The returned tensor participates in gradient tracking; its gradient slot is registered in this context.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let p = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let y = s.exp(&p)?;
s.reduce_sum(&y, Some(&[0]))
})?;
let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
let grad = p.grad().unwrap().unwrap();
assert_eq!(grad.shape(), &[2]);§Errors
Returns tenferro_runtime::Error::RuntimeState when gradient metadata
or the eager backend state cannot be registered.
Trait Implementations§
Auto Trait Implementations§
impl !Freeze for EagerRuntime
impl !RefUnwindSafe for EagerRuntime
impl !UnwindSafe for EagerRuntime
impl Send for EagerRuntime
impl Sync for EagerRuntime
impl Unpin for EagerRuntime
impl UnsafeUnpin for EagerRuntime
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<T, U> Imply<T> for U
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more