Struct CpuEngine 

pub struct CpuEngine { /* private fields */ }

A caller-held CPU execution engine.

The engine owns one threadteam::Pool (or none for CpuEngine::serial) and the workspace operations write: the buffer pool that recycles outputs, the contraction scratch, and a handle to a CpuPlanCache. It implements tenferro_tensor::Engine, so every operation takes it as &mut.

Examples

use tenferro_cpu::CpuEngine;
use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};

let mut engine = CpuEngine::serial();
let a = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let b = Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0])?;
let c = engine.add_read(TensorRead::from_tensor(&a), TensorRead::from_tensor(&b))?;
assert_eq!(c.as_slice::<f64>()?, &[4.0, 6.0]);

Implementations

impl CpuEngine

pub fn new(pool: Pool) -> Self

An engine that computes on pool, which it takes over.

Every operation may use all workers of the pool; a caller that wants fewer threads builds a smaller pool. Pool::builder reserves the worker stack the providers need by default.

Examples

let pool = tenferro_cpu::Pool::builder().threads(4).build()?;
let engine = tenferro_cpu::CpuEngine::new(pool);
assert_eq!(engine.num_threads(), 4);

pub fn serial() -> Self

An engine with no pool: every operation runs on the calling thread.

A serial engine never starts or enters a pool, so it is safe to use from inside any other pool.

Examples

let engine = tenferro_cpu::CpuEngine::serial();
assert_eq!(engine.num_threads(), 1);

pub fn with_plan_cache(self, plans: CpuPlanCache) -> Self

Use plans as this engine’s plan cache, shared with every other engine that holds a clone of it.

Examples

use tenferro_cpu::{CpuEngine, CpuPlanCache};

let plans = CpuPlanCache::new();
let engine = CpuEngine::serial().with_plan_cache(plans.clone());
assert!(engine.plan_cache().shares_with(&plans));

pub fn plan_cache(&self) -> &CpuPlanCache

The plan cache this engine reads plans from.

Examples

let engine = tenferro_cpu::CpuEngine::serial();
assert_eq!(engine.plan_cache().stats().entries, 0);

pub fn with_runtime_engine_id(self, id: EngineId) -> Self

Run prepared programs under a runtime engine id other than the default crate::runtime_engine_id; it must match the id this engine kind was registered under.

Examples

use tenferro_runtime::EngineId;
let id = EngineId::new("example.cpu.v1")?;
let engine = tenferro_cpu::CpuEngine::serial().with_runtime_engine_id(id.clone());
assert_eq!(tenferro_runtime::ExecutionEngine::target(&engine).engine_id(), &id);

pub fn with_allocation_domain( self, domain: Arc<dyn SharedTensorAllocationDomain>, ) -> Self

Bind outputs and managed inputs to a shared allocation domain.

Examples

let engine = tenferro_cpu::CpuEngine::serial();
assert!(engine.allocation_domain().is_none());

pub fn allocation_domain(&self) -> Option<AllocationDomainId>

The shared allocation domain this engine is bound to, if any.

Examples

assert_eq!(tenferro_cpu::CpuEngine::serial().allocation_domain(), None);

pub fn shared_allocation_domain( &self, ) -> Option<&Arc<dyn SharedTensorAllocationDomain>>

The shared allocator this engine is bound to, if any.

Examples

assert!(tenferro_cpu::CpuEngine::serial().shared_allocation_domain().is_none());

pub fn with_batch_policy(self, policy: CpuBatchPolicy) -> Self

This engine with a different default batch policy.

Examples

use tenferro_cpu::{CpuBatchPolicy, CpuBatchStrategy, CpuEngine};

let engine = CpuEngine::serial()
    .with_batch_policy(CpuBatchPolicy::new(CpuBatchStrategy::Sequential));
assert_eq!(engine.batch_policy().strategy, CpuBatchStrategy::Sequential);

pub fn set_batch_policy(&mut self, policy: CpuBatchPolicy) -> CpuBatchPolicy

Replace the default batch policy, returning the previous one.

For a one-operation override use crate::with_batch_policy.

Examples

use tenferro_cpu::{CpuBatchPolicy, CpuBatchStrategy, CpuEngine};

let mut engine = CpuEngine::serial();
let previous = engine.set_batch_policy(CpuBatchPolicy::new(CpuBatchStrategy::Outer));
assert_eq!(previous.strategy, CpuBatchStrategy::Auto);

pub fn batch_policy(&self) -> CpuBatchPolicy

The default batch policy of this engine.

Examples

use tenferro_cpu::{CpuBatchStrategy, CpuEngine};
assert_eq!(CpuEngine::serial().batch_policy().strategy, CpuBatchStrategy::Auto);

pub fn num_threads(&self) -> usize

The number of workers operations may use: the pool size, or one.

Examples

assert_eq!(tenferro_cpu::CpuEngine::serial().num_threads(), 1);

pub fn has_team(&self) -> bool

Whether the engine runs its parallel work on a reserved threadteam::Team.

true for an engine built from a pool of two or more workers whose members were reserved. false for CpuEngine::serial, for a one-worker pool, and for a pool whose members could not be reserved within about ten seconds of construction (the engine then runs serially and CpuEngine::num_threads reports one). Benchmarks should assert this after construction.

Examples

assert!(!tenferro_cpu::CpuEngine::serial().has_team());
let pool = tenferro_cpu::Pool::builder().threads(2).build()?;
assert!(tenferro_cpu::CpuEngine::new(pool).has_team());

pub fn is_broken(&self) -> bool

Whether an earlier operation broke this engine (see CpuEngineError::Broken).

Examples

assert!(!tenferro_cpu::CpuEngine::serial().is_broken());

pub fn exec(&mut self) -> Result<Exec<'_>>

The provider execution bundle for this engine: a placement token over every worker of its pool, its workspace and its batch policy.

A downstream kernel that calls a provider (cpueinsum, tcontract, tlinalg) directly passes this bundle by &mut, so it uses the same threads, budget and batch policy as tenferro. The bundle is not Clone: it is the engine’s whole thread budget for that one call, and the provider splits it. Getting it applies the same checks as an operation.

Errors

Returns crate::Error::RuntimeState with a CpuEngineError source when the engine is broken.

Examples

let mut engine = tenferro_cpu::CpuEngine::serial();
let exec = engine.exec()?;
assert_eq!(exec.budget(), 1);

pub fn buffer_pool_len(&self) -> usize

Number of retained buffers in the engine’s buffer pool.

Examples

assert_eq!(tenferro_cpu::CpuEngine::serial().buffer_pool_len(), 0);

pub fn buffer_pool_stats(&self) -> BufferPoolStats

Retained-buffer statistics of the engine’s buffer pool.

Examples

assert_eq!(tenferro_cpu::CpuEngine::serial().buffer_pool_stats().buffers, 0);

pub fn buffer_pool_cache_stats(&self) -> CacheStats

The buffer pool as cache statistics (entries and retained bytes).

Examples

assert_eq!(tenferro_cpu::CpuEngine::serial().buffer_pool_cache_stats().entries, 0);

pub fn buffer_pool_limit_bytes(&self) -> usize

The retention limit of recycled buffers, in retained capacity bytes.

Examples

let mut engine = tenferro_cpu::CpuEngine::serial();
engine.set_buffer_pool_limit_bytes(0);
assert_eq!(engine.buffer_pool_limit_bytes(), 0);

pub fn set_buffer_pool_limit_bytes( &mut self, max_retained_capacity_bytes: usize, )

Bound the bytes of recycled buffers and contraction scratch retained between operations; zero disables retention.

Destinations larger than the retention limit cannot be recycled, so repeated calls allocate again and may pay first-touch costs. The default is 100 MiB; raise it when a run keeps producing outputs above that size.

Examples

let mut engine = tenferro_cpu::CpuEngine::serial();
engine.set_buffer_pool_limit_bytes(1 << 20);
assert_eq!(engine.buffer_pool_limit_bytes(), 1 << 20);

pub fn reset_buffer_pool(&mut self)

Drop every retained buffer and contraction scratch.

Examples

let mut engine = tenferro_cpu::CpuEngine::serial();
engine.reset_buffer_pool();
assert_eq!(engine.buffer_pool_len(), 0);

Trait Implementations

impl Debug for CpuEngine

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

Formats the value using the given formatter.

impl Engine for CpuEngine

fn gather_read( &mut self, operand: TensorRead<'_>, start_indices: TensorRead<'_>, config: &GatherConfig, ) -> Result<Tensor>

Gather with both operands taken as reads.

fn vdot_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Compute the all-axis conjugating dot product without transferring either input.

fn norm_squared_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Compute the all-axis sum of squared magnitudes without taking a square root.

fn fused_activation_read( &mut self, op: ActivationOp, input: TensorRead<'_>, ) -> Result<Option<Tensor>>

Compute a fused activation in one pass, or decline with Ok(None).

fn softmax_read( &mut self, input: TensorRead<'_>, axis: usize, ) -> Result<Option<Tensor>>

Fused real-float softmax along axis.

fn axpby_read_into_accum( &mut self, alpha: ContractionScalar, x: TensorRead<'_>, beta: ContractionScalar, y: TensorWrite<'_>, ) -> Result<()>

Apply y <- alpha * x + beta * y in one pass into caller-owned storage.

fn native_engine(&mut self) -> Option<NativeSessionRef<'_>>

Return this engine’s backend-leaf native capability, if it has one.

impl ExecutionEngine for CpuEngine

fn target(&self) -> EngineTarget

Immutable description used by crate::Runtime::prepare.

fn take_extension_caches(&mut self) -> ExtensionCacheStore

Move this engine’s extension caches out for the duration of one run.

fn restore_extension_caches(&mut self, caches: ExtensionCacheStore)

Return the extension caches taken by Self::take_extension_caches.

fn mark_broken(&mut self)

Record that an extension callback panicked while the runtime had lent this engine’s extension caches to it.

fn as_any_mut(&mut self) -> &mut dyn Any

Typed access for prepared operations that execute against the concrete engine type instead of the Engine operations.

fn event_domain_driver(&self) -> Arc<dyn EventDomainDriver>

The driver that opens this engine’s event-domain runs.

fn retire_run(&mut self, run: Box<dyn EventDomainRun>) -> Result<(), Error>

Take ownership of an event-domain run whose launches may still be running.

fn synchronize(&mut self) -> Result<(), Error>

Block until the work this engine queued has completed.

impl SessionCachedDot for CpuEngine

fn dot_general_read_into_accum_cached( &mut self, cache_slot: Option<usize>, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, accumulation: DotGeneralAccumulation, out: TensorWrite<'_>, ) -> Result<()>

Apply session-cached scaled dot-general accumulation into output.

impl TensorAnalytic for CpuEngine

fn exp_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn log_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn sin_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn cos_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn tanh_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn sqrt_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn rsqrt_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn pow_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Examples

fn expm1_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn log1p_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn erf_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Elementwise error function erf(x) = 2/sqrt(pi) * integral_0^x exp(-t^2) dt.

impl TensorBackendCapability for CpuEngine

fn backend_id(&self) -> BackendId

fn capabilities(&self) -> &'static [OperationCapability]

fn capability(&self, query: CapabilityQuery) -> Option<OperationCapability>

Look up one operation/dtype capability for this backend.

fn require_capability( &self, query: CapabilityQuery, axis: CapabilityAxis, ) -> Result<OperationCapability, Error>

Require support for one operation/dtype/axis, returning a structured unsupported error otherwise.

impl TensorBuffer for CpuEngine

fn reclaim_buffer(&mut self, tensor: Tensor)

impl TensorDeviceTransfer for CpuEngine

fn download_to_host(&mut self, tensor: TensorRead<'_>) -> Result<Tensor>

Explicitly copy a provider-owned read target into host storage.

fn upload_host_tensor(&mut self, tensor: TensorRead<'_>) -> Result<Tensor>

Explicitly copy a host read target into provider storage.

impl TensorDot for CpuEngine

fn dot_general_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, out: TensorWrite<'_>, ) -> Result<()>

Overwrite caller-provided output with dot-general from read inputs.

fn dot_general_read_into_accum( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, config: &DotGeneralConfig, accumulation: DotGeneralAccumulation, out: TensorWrite<'_>, ) -> Result<()>

Apply scaled dot-general accumulation into caller-provided output.

impl TensorElementwise for CpuEngine

fn elementwise_read_into( &mut self, op: ElementwiseReadOp, inputs: &[TensorRead<'_>], out: TensorWrite<'_>, ) -> Result<()>

Execute an elementwise operation into caller-owned storage.

fn add_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Elementwise addition accepting either owned tensors or borrowed views.

fn sub_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Elementwise subtraction accepting either owned tensors or borrowed views.

fn mul_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Examples

fn neg_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn conj_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn div_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Examples

fn rem(&mut self, lhs: &Tensor, rhs: &Tensor) -> Result<Tensor>

Elementwise remainder.

fn rem_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Elementwise remainder accepting owned tensors or borrowed views.

fn abs_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn sign_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Examples

fn maximum_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Examples

fn minimum_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, ) -> Result<Tensor>

Examples

fn compare_read( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, dir: &CompareDir, ) -> Result<Tensor>

Errors

fn select_read( &mut self, pred: TensorRead<'_>, on_true: TensorRead<'_>, on_false: TensorRead<'_>, ) -> Result<Tensor>

Errors

fn clamp_read( &mut self, input: TensorRead<'_>, lower: TensorRead<'_>, upper: TensorRead<'_>, ) -> Result<Tensor>

Errors

fn add_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise addition.

fn add_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise addition from reads.

fn sub_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise subtraction.

fn sub_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise subtraction from reads.

fn mul_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise multiplication.

fn mul_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise multiplication from reads.

fn neg_into( &mut self, input: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise negation.

fn neg_read_into( &mut self, input: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise negation from a read.

fn conj_into( &mut self, input: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise conjugation.

fn conj_read_into( &mut self, input: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise conjugation from a read.

fn div_into( &mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise division.

fn div_read_into( &mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>, out: TensorWrite<'_>, ) -> Result<(), Error>

Overwrite caller-provided output with elementwise division from reads.

impl TensorFusion for CpuEngine

impl TensorIndexing for CpuEngine

fn gather( &mut self, operand: &Tensor, start_indices: &Tensor, config: &GatherConfig, ) -> Result<Tensor>

Errors

fn scatter( &mut self, operand: &Tensor, indices: &Tensor, updates: &Tensor, config: &ScatterConfig, ) -> Result<Tensor>

Errors

fn dynamic_update_slice_read( &mut self, operand: TensorRead<'_>, update: TensorRead<'_>, starts: TensorRead<'_>, ) -> Result<Tensor>

Dynamic-update-slice with every input taken as a read.

fn scatter_read( &mut self, operand: TensorRead<'_>, indices: TensorRead<'_>, updates: TensorRead<'_>, config: &ScatterConfig, ) -> Result<Tensor>

Scatter with every input taken as a read.

fn slice(&mut self, input: &Tensor, config: &SliceConfig) -> Result<Tensor>

Errors

fn slice_read( &mut self, input: TensorRead<'_>, config: &SliceConfig, ) -> Result<Tensor>

Slice with the input taken as a read.

fn dynamic_slice_read( &mut self, input: TensorRead<'_>, starts: TensorRead<'_>, slice_sizes: &[usize], ) -> Result<Tensor>

Dynamic slice with every input taken as a read.

fn dynamic_slice( &mut self, input: &Tensor, starts: &Tensor, slice_sizes: &[usize], ) -> Result<Tensor>

Errors

fn dynamic_update_slice( &mut self, operand: &Tensor, update: &Tensor, starts: &Tensor, ) -> Result<Tensor>

Errors

fn pad(&mut self, input: &Tensor, config: &PadConfig) -> Result<Tensor>

Errors

fn pad_read( &mut self, input: TensorRead<'_>, config: &PadConfig, ) -> Result<Tensor>

Pad with the input taken as a read.

fn concatenate(&mut self, inputs: &[&Tensor], axis: usize) -> Result<Tensor>

Errors

fn concatenate_read( &mut self, inputs: &[TensorRead<'_>], axis: usize, ) -> Result<Tensor>

Concatenate with every input taken as a read.

fn reverse(&mut self, input: &Tensor, axes: &[usize]) -> Result<Tensor>

Errors

fn reverse_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor>

Reverse with the input taken as a read.

impl TensorReduction for CpuEngine

fn reduce_sum_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor>

Sum elements across axes from an owned tensor or borrowed view.

fn reduce_prod_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor>

Multiply elements across axes from an owned tensor or borrowed view.

fn reduce_max_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor>

Take maximum values across axes from an owned tensor or borrowed view.

fn reduce_min_read( &mut self, input: TensorRead<'_>, axes: &[usize], ) -> Result<Tensor>

Take minimum values across axes from an owned tensor or borrowed view.

impl TensorStructural for CpuEngine

fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> Result<Tensor>

Materialize an owned tensor or borrowed view into fresh compact storage.

fn copy_read_into( &mut self, src: TensorRead<'_>, dst: TensorWrite<'_>, ) -> Result<()>

Overwrite caller-provided storage from a readable tensor or view.

fn transpose_read( &mut self, input: TensorRead<'_>, perm: &[usize], ) -> Result<Tensor>

Examples

fn reshape_read( &mut self, input: TensorRead<'_>, shape: &[usize], ) -> Result<Tensor>

Examples

fn broadcast_in_dim_read( &mut self, input: TensorRead<'_>, shape: &[usize], dims: &[usize], ) -> Result<Tensor>

Errors

fn tril_read(&mut self, input: TensorRead<'_>, k: i64) -> Result<Tensor>

Lower-triangular mask with the input taken as a read.

fn triu_read(&mut self, input: TensorRead<'_>, k: i64) -> Result<Tensor>

Upper-triangular mask with the input taken as a read.

fn extract_diagonal_read( &mut self, input: TensorRead<'_>, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Extract the diagonal with the input taken as a read.

fn embed_diagonal_read( &mut self, input: TensorRead<'_>, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Embed the input as a diagonal with the input taken as a read.

fn cast(&mut self, input: &Tensor, to: DType) -> Result<Tensor>

Cast a tensor to another dtype using explicit dtype projection.

fn extract_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

fn embed_diagonal( &mut self, input: &Tensor, axis_a: usize, axis_b: usize, ) -> Result<Tensor>

Errors

fn tril(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

fn triu(&mut self, input: &Tensor, k: i64) -> Result<Tensor>

Errors

fn convert(&mut self, input: &Tensor, to: DType) -> Result<Tensor, Error>

Convert a tensor to another dtype using checked dtype conversion.

impl<T, R> TensorViewCanonicalization<T, R> for CpuEngine

where T: TensorScalar + PoolScalar, R: TensorRank, R::Shape: Send + Sync, R::Strides: Send + Sync,

Typed view canonicalization runs on the engine.

fn to_contiguous( &mut self, view: &TypedTensorView<'_, T, R>, ) -> Result<TypedTensor<T, R>>

Errors

fn copy_into( &mut self, src: &TypedTensorView<'_, T, R>, dst: &mut TypedTensorViewMut<'_, T, R>, ) -> Result<()>

Errors