Skip to main content

tenferro_runtime/
extension.rs

1//! Public surface for out-of-tree extension primitives.
2//!
3//! This module exposes the Stage 6 `ExtensionOp` mechanism through the
4//! runtime crate. External crates implement
5//! [`ExtensionOp`] and build traced graphs containing the extension via
6//! [`apply`].
7//!
8//! See `docs/spec/extension-op.md` for the normative contract.
9//!
10//! # Examples
11//!
12//! ```rust
13//! use tenferro_runtime::extension::{apply, ExtensionOp};
14//!
15//! // Construct an `Arc<dyn ExtensionOp>` and call `apply(op, &[input])`
16//! // to lower it into a `TracedTensor`.
17//! ```
18
19use std::sync::Arc;
20
21use computegraph::GraphOperation;
22use tenferro_ops::std_tensor_op::StdTensorOp;
23
24use crate::error::{Error, ErrorPhase, Result};
25use crate::trace_ops::{append_core, append_extension, finish_derived};
26use crate::traced::{ensure_same_context, TracedTensor};
27
28pub use crate::compiler::CompilerOptions;
29#[doc(hidden)]
30pub use crate::shape_infer::{
31    infer_output_dtype, infer_output_extents, infer_output_shapes, promote_dtype,
32    promote_dtype_for_binary_op, promote_dtypes,
33};
34pub use tenferro_extension_macros::define_extension_runtime;
35pub use tenferro_ops::ext_op::{
36    ExtensionAlias, ExtensionAliasDeclaration, ExtensionEffect, ExtensionEffectAccess,
37    ExtensionEffectDeclaration, ExtensionOp,
38};
39pub use tenferro_ops::{ExtensionFamilyId, ExtensionShapeContext, SymDim};
40
41pub use crate::extension_cache::{
42    ExtensionCacheKey, ExtensionCacheLimits, ExtensionCacheSelector, ExtensionCacheStore,
43};
44pub use crate::extension_execution_context::ExtensionExecutionContext;
45pub use crate::runtime::{ExtensionModule, ExtensionModuleId, ExtensionModuleRegistrar};
46
47/// Apply an extension op in the traced graph.
48///
49/// The `op` value is cloned into a `StdTensorOp::Extension(Arc<dyn ExtensionOp>)`
50/// carrier. The returned vector contains one [`TracedTensor`] per declared
51/// output slot of the extension. Output shapes are inferred via
52/// [`ExtensionOp::infer_output_meta`] using the input shape hints.
53///
54/// `inputs.len()` must equal `op.input_count()`, and each input's
55/// `shape_hint` must be present (i.e. the extension must be used on
56/// tensors whose rank is known at graph-build time). For symbolic-shape
57/// composition, pass concrete tensors to [`crate::Runtime::run`] at
58/// evaluation time.
59///
60/// # Examples
61///
62/// ```rust
63/// # use std::any::Any;
64/// use std::sync::Arc;
65/// use tenferro_runtime::extension::{apply, ExtensionOp, ExtensionShapeContext};
66/// use tenferro_runtime::{TraceContext, DType, SymDim, TracedTensor};
67///
68/// # #[derive(Clone, Debug)]
69/// # struct IdentityExt;
70/// # impl ExtensionOp for IdentityExt {
71/// #     fn family_id(&self) -> &'static str { "example.identity.v1" }
72/// #     fn payload_hash(&self, _hasher: &mut dyn std::hash::Hasher) {}
73/// #     fn payload_eq(&self, other: &dyn ExtensionOp) -> bool {
74/// #         other.as_any().downcast_ref::<IdentityExt>().is_some()
75/// #     }
76/// #     fn clone_arc(&self) -> Arc<dyn ExtensionOp> { Arc::new(self.clone()) }
77/// #     fn as_any(&self) -> &dyn Any { self }
78/// #     fn input_count(&self) -> usize { 1 }
79/// #     fn output_count(&self) -> usize { 1 }
80/// #     fn infer_output_meta(
81/// #         &self,
82/// #         ctx: &mut ExtensionShapeContext<'_>,
83/// #     ) -> tenferro_tensor::Result<Vec<(DType, Vec<SymDim>)>> {
84/// #         Ok(vec![(ctx.input_dtype(0)?, ctx.input_shape(0)?.to_vec())])
85/// #     }
86/// #     // The program builder validates these two declarations when the op is
87/// #     // appended, so an extension must state them explicitly.
88/// #     fn semantic_effects(&self) -> tenferro_runtime::extension::ExtensionEffectDeclaration<'_> {
89/// #         tenferro_runtime::extension::ExtensionEffectDeclaration::Declared(&[])
90/// #     }
91/// #     fn semantic_aliases(&self) -> tenferro_runtime::extension::ExtensionAliasDeclaration<'_> {
92/// #         tenferro_runtime::extension::ExtensionAliasDeclaration::AllFresh
93/// #     }
94/// # }
95/// let op: Arc<dyn ExtensionOp> = Arc::new(IdentityExt);
96/// let trace = TraceContext::new();
97/// let a = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
98/// let outputs = apply(op, &[&a])?;
99/// assert_eq!(outputs.len(), 1);
100/// # Ok::<(), tenferro_runtime::Error>(())
101/// ```
102///
103/// # Errors
104///
105/// Returns [`Error::Validation`] with `ValidationError::InvalidArgument` when
106/// the extension receives the wrong number of traced inputs or produces an
107/// unknown output shape. Canonical metadata inference failures, including a
108/// returned metadata count that differs from [`ExtensionOp::output_count`],
109/// are returned as [`Error::TensorRuntime`] containing the typed tensor
110/// validation source, while poisoned metadata state is retained as
111/// [`Error::RuntimeStateSource`].
112pub fn apply(op: Arc<dyn ExtensionOp>, inputs: &[&TracedTensor]) -> Result<Vec<TracedTensor>> {
113    if inputs.len() != op.input_count() {
114        return Err(Error::invalid_argument(
115            "extension::apply",
116            ErrorPhase::GraphBuild,
117            "inputs",
118            format!(
119                "op family {:?} expects {} inputs, got {}",
120                op.family_id(),
121                op.input_count(),
122                inputs.len()
123            ),
124        ));
125    }
126    let Some(first) = inputs.first() else {
127        return Err(Error::invalid_argument(
128            "extension::apply",
129            ErrorPhase::GraphBuild,
130            "inputs",
131            "an extension op needs at least one traced input",
132        ));
133    };
134    for input in inputs.iter().skip(1) {
135        ensure_same_context(first, input)?;
136    }
137    let values: Vec<_> = inputs.iter().map(|input| input.value).collect();
138    let outputs = append_extension(&first.ctx, op, &values)?;
139    outputs
140        .iter()
141        .map(|&value| finish_derived(&first.ctx, value))
142        .collect()
143}
144
145/// Apply one standard primitive op to traced inputs in their shared context.
146///
147/// # Errors
148///
149/// Returns [`Error::Validation`] with `ValidationError::InvalidArgument` when the
150/// input count or a traced input does not fit the op, and the same typed build
151/// failures as [`apply`] when the derived output cannot be finished.
152pub fn apply_standard_op(op: StdTensorOp, inputs: &[&TracedTensor]) -> Result<Vec<TracedTensor>> {
153    let expected = op.input_count();
154    if inputs.len() != expected {
155        return Err(Error::invalid_argument(
156            "extension::apply_standard_op",
157            ErrorPhase::GraphBuild,
158            "inputs",
159            format!("op expects {expected} inputs, got {}", inputs.len()),
160        ));
161    }
162    let Some(first) = inputs.first() else {
163        return Err(Error::invalid_argument(
164            "extension::apply_standard_op",
165            ErrorPhase::GraphBuild,
166            "inputs",
167            "a standard op needs at least one traced input",
168        ));
169    };
170    for input in inputs.iter().skip(1) {
171        ensure_same_context(first, input)?;
172    }
173    let values: Vec<_> = inputs.iter().map(|input| input.value).collect();
174    let outputs = append_core(&first.ctx, &op, &values)?;
175    outputs
176        .iter()
177        .map(|&value| finish_derived(&first.ctx, value))
178        .collect()
179}
180
181#[cfg(test)]
182mod tests;