Struct SemanticProgramBuilder

Source

pub struct SemanticProgramBuilder { /* private fields */ }

Expand description

Mutable validation boundary for one semantic program.

Implementations§

Source §

impl SemanticProgramBuilder

Source

pub fn new() -> Self

Construct an empty builder with a fresh opaque identity.

Source

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

Attach a tensor default or large constant to one external input.

§Errors

Returns ProgramBuildError::ForeignValue for a token from another builder, ProgramBuildError::BindingTargetNotInput for a computed value, or ProgramBuildError::DuplicateBinding when the input already has a binding.

Source

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

Add one ordered external input.

§Errors

Returns ProgramBuildError::TooManyValues if the builder cannot represent another value slot.

Source

pub fn validate_value( &self, value: ProgramValue, ) -> Result<(), ProgramBuildError>

Validate that a value belongs to this builder.

§Errors

Returns ProgramBuildError::ForeignValue for a token from another builder or one that does not name an existing value.

Source

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

Borrow metadata for a builder-local value.

§Errors

Returns ProgramBuildError::ForeignValue for a foreign token.

Source

pub fn operation_count(&self) -> usize

Return the number of semantic operations added so far.

Source

pub fn import( &mut self, request: ProgramImport<'_>, ) -> Result<ImportedProgramValues, ProgramBuildError>

Import the dependency closure of ordered source roots atomically.

Empty and duplicate roots are preserved. Tensor bindings remain separate and are remapped only for imported source inputs.

§Errors

Returns ProgramBuildError::ForeignImportRoot for a root outside the source program, ProgramBuildError::ForeignBindings for bindings frozen with another program, ProgramBuildError::InvalidImport for invalid source structure, or ProgramBuildError::TooManyValues when the destination cannot represent the imported values. On error this builder is unchanged.

Source

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

Consume this builder and atomically freeze semantic structure and bindings.

§Errors

Returns ProgramFinishError::ForeignOutput for an output outside this builder, ProgramFinishError::StructuralValidation for invalid SSA structure, or ProgramFinishError::BindingFinalization when a tensor binding does not match its input declaration.

Source

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

Add one canonical core semantic operation.

§Errors

Returns a typed build error for foreign values, wrong arity, invalid metadata, or an unrepresentable output count.

Source

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

Add one extension semantic operation with explicit effects and aliases.

§Examples

use std::any::Any;
use std::hash::Hasher;
use std::sync::Arc;
use tenferro_ops::dim_expr::DimExpr;
use tenferro_ops::ext_op::{
    ExtensionAliasDeclaration, ExtensionEffectDeclaration, ExtensionOp,
};
use tenferro_ops::{ExtensionShapeContext, SymDim};
use tenferro_runtime::program::{ProgramInputSpec, SemanticProgramBuilder};
use tenferro_tensor::DType;

#[derive(Clone, Debug)]
struct Identity;
impl ExtensionOp for Identity {
    fn family_id(&self) -> &'static str { "example.identity.v1" }
    fn payload_hash(&self, hasher: &mut dyn Hasher) {
        hasher.write_u8(1);
    }
    fn payload_eq(&self, other: &dyn ExtensionOp) -> bool {
        other.as_any().is::<Self>()
    }
    fn clone_arc(&self) -> Arc<dyn ExtensionOp> {
        Arc::new(self.clone())
    }
    fn as_any(&self) -> &dyn Any { self }
    fn input_count(&self) -> usize { 1 }
    fn output_count(&self) -> usize { 1 }
    fn infer_output_meta(
        &self,
        context: &mut ExtensionShapeContext<'_>,
    ) -> tenferro_tensor::Result<Vec<(DType, Vec<SymDim>)>> {
        Ok(vec![(
            context.input_dtype(0)?,
            context.input_shape(0)?.to_vec(),
        )])
    }
    fn semantic_effects(&self) -> ExtensionEffectDeclaration<'_> {
        ExtensionEffectDeclaration::Declared(&[])
    }
    fn semantic_aliases(&self) -> ExtensionAliasDeclaration<'_> {
        ExtensionAliasDeclaration::AllFresh
    }
}

let mut builder = SemanticProgramBuilder::new();
let input = builder.input(ProgramInputSpec::new(
    DType::F64,
    [DimExpr::Const(2)],
))?;
let output = builder.add_extension(Arc::new(Identity), &[input])?[0];
let frozen = builder.finish(&[output])?;
assert_eq!(frozen.program.operations().count(), 1);