Struct TraceContext 

pub struct TraceContext { /* private fields */ }

Shared, cloneable handle to one mutable semantic trace.

Cloning the handle does not copy the trace. Values issued by one context cannot be used by another, and the handle is deliberately not Send: the trace is a single-threaded construction value, while eager execution keeps a frozen program instead of a live handle.

Examples

use tenferro_runtime::{DType, TraceContext};

let trace = TraceContext::new();
let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let y = x.reshape([2])?;

// A clone is the same trace; a second context is a different one.
let same = trace.clone();
assert!(same.same_context(&trace));
assert!(!TraceContext::new().same_context(&trace));

Implementations

impl TraceContext

pub fn new() -> Self

Construct an empty trace context.

Examples

use tenferro_runtime::TraceContext;

let mut trace = TraceContext::new();
assert!(trace.finish(&[]).is_ok());

pub fn input( &self, spec: ProgramInputSpec, ) -> Result<TraceValue, ProgramBuildError>

Add one ordered external input.

Errors

Returns ProgramBuildError::TooManyValues if another value cannot be represented, or ProgramBuildError::ReentrantContextBorrow when the context is already borrowed by an operation in progress.

pub fn input_with_default( &self, spec: ProgramInputSpec, tensor: Tensor, ) -> Result<TraceValue, ProgramBuildError>

Add one ordered input and attach its default tensor.

Errors

Returns ProgramBuildError::TooManyValues when another input cannot be represented, ProgramBuildError::BindingTargetNotInput if the new value is not accepted as an input, or ProgramBuildError::DuplicateBinding if it is already bound.

pub fn bind_input( &self, input: TraceValue, tensor: Tensor, ) -> Result<BindingKey, ProgramBuildError>

Attach a tensor default to an existing trace input.

Errors

Returns ProgramBuildError::ForeignValue for another context’s value, ProgramBuildError::BindingTargetNotInput for a computed value, or ProgramBuildError::DuplicateBinding for a repeated binding.

pub fn add_op( &self, op: CoreSemanticOp, inputs: &[TraceValue], ) -> Result<Box<[TraceValue]>, ProgramBuildError>

Add one canonical core semantic operation.

Errors

Returns ProgramBuildError::ForeignValue for an input from another context, ProgramBuildError::Arity for the wrong input count, ProgramBuildError::Metadata / ProgramBuildError::OutputMetadataCount when inference returns invalid metadata, or ProgramBuildError::ReentrantContextBorrow when the context is already borrowed.

pub fn add_extension( &self, op: Arc<dyn ExtensionOp>, inputs: &[TraceValue], ) -> Result<Box<[TraceValue]>, ProgramBuildError>

Add one extension semantic operation.

Errors

Returns ProgramBuildError::ForeignValue or ProgramBuildError::Arity for invalid inputs, ProgramBuildError::UndeclaredExtensionEffects / ProgramBuildError::UndeclaredExtensionAliases for an incomplete extension contract, ProgramBuildError::Metadata when inference fails, or ProgramBuildError::ReentrantContextBorrow when the context is already borrowed.

pub fn value_metadata( &self, value: TraceValue, ) -> Result<ProgramValueMetadata, ProgramBuildError>

Return metadata for a context-owned value.

Errors

Returns ProgramBuildError::ForeignValue for a value from another context, or ProgramBuildError::ReentrantContextBorrow when the context is already borrowed.

pub fn with_extension_caches<R>( &self, f: impl FnOnce(&mut ExtensionCacheStore) -> R, ) -> Result<R, ProgramBuildError>

Run f with the generic trace-time extension cache store.

The store is borrowed only for the call: a live context shares interior mutability, so a &mut borrow cannot escape.

Errors

Returns ProgramBuildError::ReentrantContextBorrow when the context is already borrowed.

pub fn finish( &self, outputs: &[TraceValue], ) -> Result<TracedGraph, ProgramFinishError>

Freeze the ordered closure of outputs without consuming the context.

Later appends do not change the returned graph, and the context stays usable for further tracing.

Errors

Returns ProgramFinishError::ForeignOutput if an output belongs to another context, ProgramFinishError::ReentrantContextBorrow when the context is already borrowed, or a typed structural/binding finalization failure.

impl TraceContext

pub fn input_concrete_shape( &self, dtype: DType, shape: &[usize], ) -> Result<TracedTensor>

Add a placeholder input with a fixed concrete shape.

Examples

use tenferro_runtime::TraceContext;
use tenferro_tensor::DType;

let trace = TraceContext::new();
let x = trace.input_concrete_shape(DType::F64, &[2, 3])?;
assert_eq!(x.rank(), 2);
assert!(x.is_concrete_shape());

Errors

Returns Error::RuntimeState when the trace cannot accept another input or a binding already exists for it.

pub fn input_concrete_shape_declaring_scalar( &self, dtype: DType, shape: &[usize], identity: &'static str, ) -> Result<TracedTensor>

Add a placeholder input of concrete shape declaring an external scalar.

Errors

Returns Error::RuntimeState when the trace cannot accept another input or a binding already exists for it, and Error::RuntimeStateSource wrapping ProgramBuildError::ExternalScalarWithoutIdentity when an externally defined scalar dtype reaches the builder without the declared identity.

pub fn input_symbolic_shape( &self, dtype: DType, rank: usize, ) -> Result<TracedTensor>

Add a placeholder input with symbolic (rank-only) extents.

Examples

use tenferro_runtime::TraceContext;
use tenferro_tensor::DType;

let trace = TraceContext::new();
let x = trace.input_symbolic_shape(DType::F64, 2)?;
assert_eq!(x.rank(), 2);
assert!(!x.is_concrete_shape());

Errors

Returns Error::RuntimeState when the trace cannot accept another input.

pub fn from_tensor_concrete_shape(&self, tensor: Tensor) -> Result<TracedTensor>

Add a constant leaf holding tensor with its concrete shape.

Examples

use tenferro_runtime::{Tensor, TraceContext};

let trace = TraceContext::new();
let x = trace.from_tensor_concrete_shape(
    Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?,
)?;
assert!(x.attached_value().is_some());

Errors

Returns Error::Validation for a malformed tensor or Error::RuntimeState when the trace cannot bind the constant.

pub fn from_tensor_concrete_shape_declaring_scalar( &self, tensor: Tensor, identity: &'static str, ) -> Result<TracedTensor>

Add a constant leaf of concrete shape declaring an external scalar.

Errors

Returns Error::Validation for a malformed tensor, Error::RuntimeState when the trace cannot bind the constant, and Error::RuntimeStateSource wrapping ProgramBuildError::ExternalScalarWithoutIdentity when an externally defined scalar dtype reaches the builder without the declared identity.

pub fn from_tensor_symbolic_shape(&self, tensor: Tensor) -> Result<TracedTensor>

Add a constant leaf holding tensor but advertising symbolic extents.

Errors

Returns Error::RuntimeState when the trace cannot bind the constant.

pub fn from_vec_col_major<T: TensorScalar>( &self, shape: impl IntoShapeVec, data: Vec<T>, ) -> Result<TracedTensor>

Add a constant leaf from compact column-major data.

Errors

Returns Error::TensorRuntime with a typed validation error when the shape and data length disagree.

Trait Implementations

impl Clone for TraceContext

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TraceContext

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

Formats the value using the given formatter.

impl Default for TraceContext

fn default() -> Self

Returns the “default value” for a type.