tenferro_ops/ad/context.rs
1//! AD context for guard-based shape resolution and value metadata queries.
2//!
3//! During AD graph construction, linalg rules such as SVD, QR, and LU need
4//! concrete matrix dimensions to choose between structurally different
5//! subgraphs. `ShapeGuardContext` records those dimension comparisons as guards
6//! so cached AD graphs can later be invalidated when the observed shape
7//! relationship changes.
8
9use std::cmp::Ordering;
10use std::collections::HashMap;
11use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
12use std::sync::{Mutex, OnceLock};
13
14use computegraph::graph::Graph;
15use computegraph::types::{ValueKey, ValueRef};
16use tenferro_tensor::DType;
17
18#[cfg(feature = "autodiff")]
19use crate::ad::{ADRuleError, ADRuleKind};
20use crate::dim_expr::{DimExpr, DimExprEvalError};
21use crate::shape_extent::ShapeExtent;
22use crate::std_tensor_op::StdTensorOp;
23use crate::sym_dim::SymDim;
24
25type MetadataMap = HashMap<ValueKey<StdTensorOp>, TensorMeta>;
26
27type GlobalMetadataMap = HashMap<ValueKey<StdTensorOp>, GlobalMetadataEntry>;
28
29#[derive(Clone, Debug)]
30struct GlobalMetadataEntry {
31 stack: Vec<GlobalMetadataRegistration>,
32}
33
34#[derive(Clone, Debug)]
35struct GlobalMetadataRegistration {
36 token: u64,
37 meta: TensorMeta,
38}
39
40#[derive(Clone, Debug)]
41struct ScopedGlobalMetadataRegistration {
42 key: ValueKey<StdTensorOp>,
43 token: u64,
44}
45
46/// Error returned when the process-global AD metadata registry is unavailable.
47#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
48pub enum MetadataRegistryError {
49 /// A previous panic poisoned the global metadata mutex.
50 #[error("AD global metadata registry lock poisoned")]
51 LockPoisoned,
52}
53
54/// Error returned when shape-guard metadata cannot be resolved.
55///
56/// # Examples
57///
58/// ```
59/// use tenferro_ops::ShapeGuardError;
60///
61/// let error = ShapeGuardError::LocalWithoutAttachedGraph { local_id: 0 };
62/// assert!(error.to_string().contains("attached graph"));
63/// ```
64#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
65pub enum ShapeGuardError {
66 /// A local graph value was queried before a graph was attached.
67 #[error("cannot resolve local value {local_id} without an attached graph")]
68 LocalWithoutAttachedGraph {
69 /// Graph-local value id.
70 local_id: usize,
71 },
72 /// A local graph value id is outside the attached graph's value table.
73 #[error("local value {local_id} is out of bounds for the attached graph")]
74 LocalOutOfBounds {
75 /// Graph-local value id.
76 local_id: usize,
77 },
78 /// No metadata was registered for the resolved value key.
79 #[error("missing TensorMeta for {key:?}")]
80 MissingMetadata {
81 /// Resolved value key.
82 key: ValueKey<StdTensorOp>,
83 },
84 /// Metadata exists, but at least one axis is only bounded or unknown.
85 #[error("TensorMeta for {key:?} does not have an exact shape; query extents instead")]
86 NonExactShape {
87 /// Resolved value key.
88 key: ValueKey<StdTensorOp>,
89 },
90}
91
92/// Result type used by shape-guard metadata queries.
93///
94/// The error side preserves a [`ShapeGuardFailure`] wrapper so the original
95/// [`ShapeGuardError`] stays available through `typed_source()`.
96///
97/// # Examples
98///
99/// ```
100/// use tenferro_ops::ShapeGuardResult;
101///
102/// let result: ShapeGuardResult<()> = Ok(());
103/// assert!(result.is_ok());
104/// ```
105pub type ShapeGuardResult<T> = Result<T, ShapeGuardFailure>;
106
107#[cfg(feature = "autodiff")]
108impl From<ShapeGuardFailure> for ADRuleError {
109 fn from(err: ShapeGuardFailure) -> Self {
110 ADRuleError::invalid_input(
111 "tenferro.shape_guard",
112 ADRuleKind::Jvp,
113 err.typed_source().to_string(),
114 )
115 }
116}
117
118/// Error returned by a shape-guard metadata query.
119///
120/// The public [`ShapeGuardError`] remains the typed source.
121///
122/// # Examples
123///
124/// ```
125/// use computegraph::types::{ValueKey, ValueRef};
126/// use tenferro_ops::input_key::TensorInputKey;
127/// use tenferro_ops::std_tensor_op::StdTensorOp;
128/// use tenferro_ops::{ShapeGuardContext, ShapeGuardError};
129///
130/// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 8 });
131/// let value = ValueRef::External(key);
132/// let mut ctx = ShapeGuardContext::default();
133/// let failure = ctx.shape_of(&value).unwrap_err();
134/// assert!(matches!(
135/// failure.typed_source(),
136/// ShapeGuardError::MissingMetadata { .. }
137/// ));
138/// ```
139#[derive(Clone, Debug)]
140pub struct ShapeGuardFailure {
141 source: ShapeGuardError,
142}
143
144impl ShapeGuardFailure {
145 fn new(source: ShapeGuardError) -> Self {
146 Self { source }
147 }
148
149 /// Return the original typed shape-guard failure.
150 pub fn typed_source(&self) -> &ShapeGuardError {
151 &self.source
152 }
153
154 /// Consume this boundary error and return its original typed failure.
155 pub fn into_typed_source(self) -> ShapeGuardError {
156 self.source
157 }
158}
159
160impl std::fmt::Display for ShapeGuardFailure {
161 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
162 self.source.fmt(f)
163 }
164}
165
166impl std::error::Error for ShapeGuardFailure {
167 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
168 Some(&self.source)
169 }
170}
171
172impl PartialEq for ShapeGuardFailure {
173 fn eq(&self, other: &Self) -> bool {
174 self.source == other.source
175 }
176}
177
178impl Eq for ShapeGuardFailure {}
179
180/// Global metadata registry.
181///
182/// Stored as a tokenized stack per value key: duplicate scoped registrations
183/// shadow older metadata while they are live, and dropping scopes in any order
184/// removes only the matching token. `ShapeGuardContext::metadata_of` reaches into
185/// the registry lazily via [`lookup_global_metadata`] and caches the result into
186/// the context's local map.
187///
188/// Earlier designs either cloned the whole map up-front into each AD
189/// `ShapeGuardContext` or kept the map in an `Arc` and cloned on every write.
190/// Both variants were quadratic across the monotonically growing registry and
191/// dominated oracle_replay runtime.
192static GLOBAL_METADATA: OnceLock<Mutex<GlobalMetadataMap>> = OnceLock::new();
193static NEXT_GLOBAL_METADATA_TOKEN: AtomicU64 = AtomicU64::new(0);
194
195fn global_metadata_registry() -> &'static Mutex<GlobalMetadataMap> {
196 GLOBAL_METADATA.get_or_init(|| Mutex::new(HashMap::new()))
197}
198
199/// Lifetime token for graph-scoped global metadata.
200///
201/// Dropping the last frontend owner of a traced graph drops this scope and
202/// releases the metadata keys that were registered for that graph graph.
203#[doc(hidden)]
204#[derive(Debug)]
205pub struct GlobalMetadataScope {
206 registrations: Vec<ScopedGlobalMetadataRegistration>,
207}
208
209impl Drop for GlobalMetadataScope {
210 fn drop(&mut self) {
211 release_scoped_global_metadata(&self.registrations);
212 }
213}
214
215/// Per-value tensor metadata used by AD rules.
216///
217/// Shape information is stored as per-axis [`ShapeExtent`] values. Callers must
218/// explicitly choose whether they need an exact shape or only a known bound.
219///
220/// # Examples
221///
222/// ```
223/// use tenferro_ops::{SymDim, TensorMeta};
224/// use tenferro_tensor::DType;
225///
226/// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(2usize), SymDim::from(3usize)]);
227/// assert_eq!(meta.rank(), 2);
228/// ```
229#[derive(Clone, Debug, PartialEq, Eq)]
230pub struct TensorMeta {
231 /// Element dtype of the tensor value.
232 pub dtype: DType,
233 /// Per-axis shape guarantees.
234 pub extents: Vec<ShapeExtent<SymDim>>,
235 /// Canonical identity of an externally defined scalar, when the value carries one.
236 ///
237 /// A semantic program's identity must be reproducible across processes, while an
238 /// externally defined scalar's tag is a process-local `TypeId`, so a traced value
239 /// whose dtype is external declares the stable name here.
240 pub scalar_identity: Option<&'static str>,
241}
242
243impl TensorMeta {
244 /// Construct metadata whose every axis is exact.
245 ///
246 /// # Examples
247 ///
248 /// ```
249 /// use tenferro_ops::{SymDim, TensorMeta};
250 /// use tenferro_tensor::DType;
251 ///
252 /// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]);
253 /// assert_eq!(meta.exact_shape(), Some(vec![SymDim::from(4usize)]));
254 /// ```
255 pub fn exact(dtype: DType, shape: Vec<SymDim>) -> Self {
256 let extents = shape.iter().cloned().map(ShapeExtent::exact).collect();
257 Self {
258 dtype,
259 extents,
260 scalar_identity: None,
261 }
262 }
263
264 /// Construct metadata from per-axis extents.
265 ///
266 /// # Examples
267 ///
268 /// ```
269 /// use tenferro_ops::{ShapeExtent, SymDim, TensorMeta};
270 /// use tenferro_tensor::DType;
271 ///
272 /// let meta = TensorMeta::with_extents(
273 /// DType::F64,
274 /// vec![ShapeExtent::upper_bound(SymDim::from(8usize))],
275 /// );
276 /// assert_eq!(meta.exact_shape(), None);
277 /// ```
278 pub fn with_extents(dtype: DType, extents: Vec<ShapeExtent<SymDim>>) -> Self {
279 Self {
280 dtype,
281 extents,
282 scalar_identity: None,
283 }
284 }
285
286 /// Declare the canonical identity of an externally defined scalar.
287 ///
288 /// # Examples
289 ///
290 /// ```rust
291 /// use tenferro_ops::{SymDim, TensorMeta};
292 /// use tenferro_tensor::DType;
293 ///
294 /// let dtype = DType::External(std::any::TypeId::of::<f64>());
295 /// let meta = TensorMeta::exact(dtype, vec![SymDim::from(2usize)])
296 /// .with_scalar_identity("example.scalar.v1");
297 /// assert_eq!(meta.scalar_identity(), Some("example.scalar.v1"));
298 /// ```
299 #[must_use]
300 pub fn with_scalar_identity(mut self, identity: &'static str) -> Self {
301 self.scalar_identity = Some(identity);
302 self
303 }
304
305 /// Return the declared identity of an externally defined scalar, if any.
306 ///
307 /// # Examples
308 ///
309 /// ```rust
310 /// use tenferro_ops::{SymDim, TensorMeta};
311 /// use tenferro_tensor::DType;
312 ///
313 /// let dtype = DType::External(std::any::TypeId::of::<f64>());
314 /// assert_eq!(TensorMeta::exact(dtype, vec![SymDim::from(1usize)]).scalar_identity(), None);
315 /// assert_eq!(
316 /// TensorMeta::exact(dtype, vec![SymDim::from(1usize)])
317 /// .with_scalar_identity("example.scalar.v1")
318 /// .scalar_identity(),
319 /// Some("example.scalar.v1")
320 /// );
321 /// ```
322 #[must_use]
323 pub const fn scalar_identity(&self) -> Option<&'static str> {
324 self.scalar_identity
325 }
326
327 /// Return the tensor rank known by this metadata record.
328 pub fn rank(&self) -> usize {
329 self.extents.len()
330 }
331
332 /// Return the per-axis shape guarantees.
333 ///
334 /// # Examples
335 ///
336 /// ```
337 /// use tenferro_ops::{SymDim, TensorMeta};
338 /// use tenferro_tensor::DType;
339 ///
340 /// let meta = TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]);
341 /// assert_eq!(meta.extents().len(), 1);
342 /// ```
343 pub fn extents(&self) -> &[ShapeExtent<SymDim>] {
344 &self.extents
345 }
346
347 /// Return the shape only when every axis is exact.
348 ///
349 /// # Examples
350 ///
351 /// ```
352 /// use tenferro_ops::{ShapeExtent, SymDim, TensorMeta};
353 /// use tenferro_tensor::DType;
354 ///
355 /// let meta = TensorMeta::with_extents(
356 /// DType::F64,
357 /// vec![ShapeExtent::upper_bound(SymDim::from(8usize))],
358 /// );
359 /// assert_eq!(meta.exact_shape(), None);
360 /// ```
361 pub fn exact_shape(&self) -> Option<Vec<SymDim>> {
362 self.extents
363 .iter()
364 .map(|extent| extent.as_exact().cloned())
365 .collect()
366 }
367
368 /// Return one known bound per axis when every axis has a bound.
369 ///
370 /// This is intentionally separate from [`TensorMeta::exact_shape`]: a bound
371 /// is not proof of the runtime size.
372 pub fn bound_shape(&self) -> Option<Vec<SymDim>> {
373 self.extents
374 .iter()
375 .map(|extent| extent.bound_expr().cloned())
376 .collect()
377 }
378}
379
380/// A recorded dimension comparison made during AD graph construction.
381///
382/// # Examples
383///
384/// ```
385/// use std::cmp::Ordering;
386/// use tenferro_ops::ShapeGuard;
387///
388/// let guard = ShapeGuard {
389/// dim_a: 5,
390/// dim_b: 3,
391/// ordering: Ordering::Greater,
392/// };
393///
394/// assert_eq!(guard.ordering, Ordering::Greater);
395/// ```
396#[derive(Clone, Debug, PartialEq, Eq)]
397pub struct ShapeGuard {
398 /// First dimension value, such as `m`.
399 pub dim_a: usize,
400 /// Second dimension value, such as `n`.
401 pub dim_b: usize,
402 /// The observed ordering `dim_a.cmp(&dim_b)`.
403 pub ordering: Ordering,
404}
405
406/// AD context providing dimension resolution, guard recording, and value metadata.
407///
408/// # Examples
409///
410/// ```
411/// use tenferro_ops::ShapeGuardContext;
412///
413/// let ctx = ShapeGuardContext::default();
414/// assert!(ctx.guards().is_empty());
415/// ```
416#[derive(Clone, Debug, Default)]
417pub struct ShapeGuardContext {
418 guards: Vec<ShapeGuard>,
419 metadata: MetadataMap,
420 shape_sources: HashMap<u64, ValueKey<StdTensorOp>>,
421 use_global_registry: bool,
422 local_keys: Option<Vec<ValueKey<StdTensorOp>>>,
423 #[cfg(feature = "autodiff")]
424 active_value_keys: Option<std::sync::Arc<std::collections::HashSet<ValueKey<StdTensorOp>>>>,
425}
426
427impl ShapeGuardContext {
428 /// Create a context backed by the global metadata registry.
429 ///
430 /// Instead of cloning the entire global registry up-front (which used
431 /// to be O(N) per AD pass and quadratic across oracle_replay), the
432 /// context keeps a flag and lazily fetches entries from the shared
433 /// [`lookup_global_metadata`] on first miss, caching into its local
434 /// `metadata` map for subsequent reads within the same pass.
435 ///
436 /// # Examples
437 ///
438 /// ```
439 /// let ctx = tenferro_ops::ShapeGuardContext::with_global_metadata();
440 /// assert!(ctx.guards().is_empty());
441 /// ```
442 pub fn with_global_metadata() -> Self {
443 Self {
444 use_global_registry: true,
445 ..Self::default()
446 }
447 }
448
449 #[doc(hidden)]
450 pub fn insert_shape_source(&mut self, tensor_id: u64, key: ValueKey<StdTensorOp>) {
451 self.shape_sources.entry(tensor_id).or_insert(key);
452 }
453
454 #[doc(hidden)]
455 pub fn shape_source(&self, tensor_id: u64) -> Option<&ValueKey<StdTensorOp>> {
456 self.shape_sources.get(&tensor_id)
457 }
458
459 #[cfg(feature = "autodiff")]
460 pub fn with_linearize_active_values(
461 mut self,
462 keys: std::sync::Arc<std::collections::HashSet<ValueKey<StdTensorOp>>>,
463 ) -> Self {
464 self.active_value_keys = Some(keys);
465 self
466 }
467
468 /// Whether a primal value lies on a path from the current linearize targets.
469 ///
470 /// When no active set was attached, every value is treated as active so
471 /// existing callers keep the conservative full JVP graphs.
472 #[cfg(feature = "autodiff")]
473 pub fn is_value_active_in_linearize(&self, key: &ValueKey<StdTensorOp>) -> bool {
474 self.active_value_keys
475 .as_ref()
476 .is_none_or(|set| set.contains(key))
477 }
478
479 /// Returns the guards recorded so far.
480 ///
481 /// # Examples
482 ///
483 /// ```
484 /// use tenferro_ops::ShapeGuardContext;
485 ///
486 /// let ctx = ShapeGuardContext::default();
487 /// assert_eq!(ctx.guards(), &[]);
488 /// ```
489 pub fn guards(&self) -> &[ShapeGuard] {
490 &self.guards
491 }
492
493 /// Clears all recorded guards.
494 ///
495 /// # Examples
496 ///
497 /// ```
498 /// use tenferro_ops::ShapeGuardContext;
499 ///
500 /// let mut ctx = ShapeGuardContext::default();
501 /// ctx.clear_guards();
502 /// assert!(ctx.guards().is_empty());
503 /// ```
504 pub fn clear_guards(&mut self) {
505 self.guards.clear();
506 }
507
508 /// Return the shape metadata for a value reference.
509 ///
510 /// # Examples
511 ///
512 /// ```
513 /// use computegraph::types::{ValueKey, ValueRef};
514 /// use tenferro_ops::input_key::TensorInputKey;
515 /// use tenferro_ops::std_tensor_op::StdTensorOp;
516 /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
517 /// use tenferro_tensor::DType;
518 ///
519 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
520 /// let value = ValueRef::External(key.clone());
521 /// let mut ctx = ShapeGuardContext::default();
522 /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
523 ///
524 /// let shape = ctx.shape_of(&value).unwrap();
525 /// assert_eq!(shape, &[SymDim::from(4usize)]);
526 /// ```
527 ///
528 /// # Errors
529 ///
530 /// Returns [`ShapeGuardError`] when the value cannot be resolved, metadata
531 /// is missing, or the metadata does not describe an exact shape.
532 pub fn shape_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<Vec<SymDim>> {
533 let key = self.resolve_key(val)?.clone();
534 self.ensure_metadata_loaded(&key);
535 let meta = self.metadata.get(&key).ok_or_else(|| {
536 self.shape_guard_failure(ShapeGuardError::MissingMetadata { key: key.clone() })
537 })?;
538 meta.exact_shape()
539 .ok_or_else(|| self.shape_guard_failure(ShapeGuardError::NonExactShape { key }))
540 }
541
542 /// Return the rank for a value reference without requiring exact extents.
543 ///
544 /// Use this when an AD rule only needs axis count or needs to build
545 /// runtime-shape references. Calling [`ShapeGuardContext::shape_of`] in those
546 /// cases would reject valid values such as `DynamicTruncate` outputs whose
547 /// runtime extent is known only as an upper bound.
548 ///
549 /// # Examples
550 ///
551 /// ```
552 /// use computegraph::types::{ValueKey, ValueRef};
553 /// use tenferro_ops::input_key::TensorInputKey;
554 /// use tenferro_ops::std_tensor_op::StdTensorOp;
555 /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
556 /// use tenferro_tensor::DType;
557 ///
558 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
559 /// let value = ValueRef::External(key.clone());
560 /// let mut ctx = ShapeGuardContext::default();
561 /// ctx.insert_metadata(
562 /// key,
563 /// TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
564 /// );
565 ///
566 /// assert_eq!(ctx.rank_of(&value).unwrap(), 1);
567 /// ```
568 ///
569 /// # Errors
570 ///
571 /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
572 /// metadata is unavailable.
573 pub fn rank_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<usize> {
574 self.metadata_of(val).map(TensorMeta::rank)
575 }
576
577 /// Return per-axis shape guarantees for a value reference.
578 ///
579 /// # Examples
580 ///
581 /// ```
582 /// use computegraph::types::{ValueKey, ValueRef};
583 /// use tenferro_ops::input_key::TensorInputKey;
584 /// use tenferro_ops::std_tensor_op::StdTensorOp;
585 /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
586 /// use tenferro_tensor::DType;
587 ///
588 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
589 /// let value = ValueRef::External(key.clone());
590 /// let mut ctx = ShapeGuardContext::default();
591 /// ctx.insert_metadata(
592 /// key,
593 /// TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
594 /// );
595 ///
596 /// let extents = ctx.extents_of(&value).unwrap();
597 /// assert_eq!(extents[0], ShapeExtent::upper_bound(SymDim::from(8usize)));
598 /// ```
599 ///
600 /// # Errors
601 ///
602 /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
603 /// metadata is unavailable.
604 pub fn extents_of(
605 &mut self,
606 val: &ValueRef<StdTensorOp>,
607 ) -> ShapeGuardResult<&[ShapeExtent<SymDim>]> {
608 self.metadata_of(val).map(TensorMeta::extents)
609 }
610
611 /// Return the exact shape for a value reference, if all axes are exact.
612 ///
613 /// # Examples
614 ///
615 /// ```
616 /// use computegraph::types::{ValueKey, ValueRef};
617 /// use tenferro_ops::input_key::TensorInputKey;
618 /// use tenferro_ops::std_tensor_op::StdTensorOp;
619 /// use tenferro_ops::{ShapeExtent, ShapeGuardContext, SymDim, TensorMeta};
620 /// use tenferro_tensor::DType;
621 ///
622 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
623 /// let value = ValueRef::External(key.clone());
624 /// let mut ctx = ShapeGuardContext::default();
625 /// ctx.insert_metadata(
626 /// key,
627 /// TensorMeta::with_extents(DType::F64, vec![ShapeExtent::upper_bound(SymDim::from(8usize))]),
628 /// );
629 ///
630 /// let maybe_shape = ctx.exact_shape_of(&value).unwrap();
631 /// assert_eq!(maybe_shape, None);
632 /// ```
633 ///
634 /// # Errors
635 ///
636 /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
637 /// metadata is unavailable.
638 pub fn exact_shape_of(
639 &mut self,
640 val: &ValueRef<StdTensorOp>,
641 ) -> ShapeGuardResult<Option<Vec<SymDim>>> {
642 self.metadata_of(val).map(TensorMeta::exact_shape)
643 }
644
645 #[doc(hidden)]
646 pub fn shape_if_available(&mut self, val: &ValueRef<StdTensorOp>) -> Option<Vec<SymDim>> {
647 self.metadata_if_available(val)
648 .and_then(TensorMeta::exact_shape)
649 }
650
651 /// Return the dtype metadata for a value reference.
652 ///
653 /// # Examples
654 ///
655 /// ```
656 /// use computegraph::types::{ValueKey, ValueRef};
657 /// use tenferro_ops::input_key::TensorInputKey;
658 /// use tenferro_ops::std_tensor_op::StdTensorOp;
659 /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
660 /// use tenferro_tensor::DType;
661 ///
662 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
663 /// let value = ValueRef::External(key.clone());
664 /// let mut ctx = ShapeGuardContext::default();
665 /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
666 ///
667 /// let dtype = ctx.dtype_of(&value).unwrap();
668 /// assert_eq!(dtype, DType::F64);
669 /// ```
670 ///
671 /// # Errors
672 ///
673 /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
674 /// metadata is unavailable.
675 pub fn dtype_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<DType> {
676 self.metadata_of(val).map(|meta| meta.dtype)
677 }
678
679 /// Return the complete metadata record for a value reference.
680 ///
681 /// # Examples
682 ///
683 /// ```
684 /// use computegraph::types::{ValueKey, ValueRef};
685 /// use tenferro_ops::input_key::TensorInputKey;
686 /// use tenferro_ops::std_tensor_op::StdTensorOp;
687 /// use tenferro_ops::{ShapeGuardContext, SymDim, TensorMeta};
688 /// use tenferro_tensor::DType;
689 ///
690 /// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 1 });
691 /// let value = ValueRef::External(key.clone());
692 /// let mut ctx = ShapeGuardContext::default();
693 /// ctx.insert_metadata(key, TensorMeta::exact(DType::F64, vec![SymDim::from(4usize)]));
694 ///
695 /// let meta = ctx.metadata_of(&value).unwrap();
696 /// assert_eq!(meta.dtype, DType::F64);
697 /// ```
698 ///
699 /// # Errors
700 ///
701 /// Returns [`ShapeGuardError`] when the value cannot be resolved or its
702 /// metadata is unavailable.
703 pub fn metadata_of(&mut self, val: &ValueRef<StdTensorOp>) -> ShapeGuardResult<&TensorMeta> {
704 let key = self.resolve_key(val)?.clone();
705 self.ensure_metadata_loaded(&key);
706 self.metadata
707 .get(&key)
708 .ok_or_else(|| self.shape_guard_failure(ShapeGuardError::MissingMetadata { key }))
709 }
710
711 #[doc(hidden)]
712 pub fn metadata_if_available(&mut self, val: &ValueRef<StdTensorOp>) -> Option<&TensorMeta> {
713 let key = self.resolve_key_if_available(val)?.clone();
714 self.ensure_metadata_loaded(&key);
715 self.metadata.get(&key)
716 }
717
718 #[doc(hidden)]
719 pub fn attach_graph(&mut self, graph: &Graph<StdTensorOp>) {
720 self.local_keys = Some(graph.values().iter().map(|node| node.key.clone()).collect());
721 }
722
723 #[doc(hidden)]
724 pub fn insert_metadata(&mut self, key: ValueKey<StdTensorOp>, meta: TensorMeta) {
725 self.metadata.insert(key, meta);
726 }
727
728 fn resolve_key_if_available<'a>(
729 &'a self,
730 val: &'a ValueRef<StdTensorOp>,
731 ) -> Option<&'a ValueKey<StdTensorOp>> {
732 match val {
733 ValueRef::External(key) => Some(key),
734 ValueRef::Local(local_id) => self
735 .local_keys
736 .as_ref()
737 .and_then(|keys| keys.get(*local_id)),
738 }
739 }
740
741 fn resolve_key<'a>(
742 &'a self,
743 val: &'a ValueRef<StdTensorOp>,
744 ) -> ShapeGuardResult<&'a ValueKey<StdTensorOp>> {
745 match val {
746 ValueRef::External(key) => Ok(key),
747 ValueRef::Local(local_id) if self.local_keys.is_none() => Err(self
748 .shape_guard_failure(ShapeGuardError::LocalWithoutAttachedGraph {
749 local_id: *local_id,
750 })),
751 ValueRef::Local(local_id) => self
752 .local_keys
753 .as_ref()
754 .and_then(|keys| keys.get(*local_id))
755 .ok_or_else(|| {
756 self.shape_guard_failure(ShapeGuardError::LocalOutOfBounds {
757 local_id: *local_id,
758 })
759 }),
760 }
761 }
762
763 fn shape_guard_failure(&self, source: ShapeGuardError) -> ShapeGuardFailure {
764 ShapeGuardFailure::new(source)
765 }
766
767 fn ensure_metadata_loaded(&mut self, key: &ValueKey<StdTensorOp>) {
768 if !self.metadata.contains_key(key) && self.use_global_registry {
769 if let Ok(Some(meta)) = lookup_global_metadata(key) {
770 self.metadata.insert(key.clone(), meta);
771 }
772 }
773 }
774}
775
776/// Look up a single metadata entry from the global registry.
777///
778/// Locks the registry briefly for a single `HashMap::get` + clone.
779///
780/// # Examples
781///
782/// ```
783/// use computegraph::types::ValueKey;
784/// use tenferro_ops::ad::context::lookup_global_metadata;
785/// use tenferro_ops::input_key::TensorInputKey;
786/// use tenferro_ops::std_tensor_op::StdTensorOp;
787///
788/// let key = ValueKey::<StdTensorOp>::Input(TensorInputKey::User { id: 99 });
789/// let meta = lookup_global_metadata(&key).unwrap();
790/// assert!(meta.is_none());
791/// ```
792///
793/// # Errors
794///
795/// Returns [`MetadataRegistryError::LockPoisoned`] when the global metadata
796/// registry lock is poisoned.
797pub fn lookup_global_metadata(
798 key: &ValueKey<StdTensorOp>,
799) -> Result<Option<TensorMeta>, MetadataRegistryError> {
800 let guard = global_metadata_registry()
801 .lock()
802 .map_err(|_| MetadataRegistryError::LockPoisoned)?;
803 Ok(guard
804 .get(key)
805 .and_then(|entry| entry.stack.last())
806 .map(|registration| registration.meta.clone()))
807}
808
809#[doc(hidden)]
810///
811/// # Errors
812///
813/// Returns [`MetadataRegistryError::LockPoisoned`] when the global metadata
814/// registry lock is poisoned.
815pub fn register_scoped_global_metadata_batch<I>(
816 entries: I,
817) -> Result<GlobalMetadataScope, MetadataRegistryError>
818where
819 I: IntoIterator<Item = (ValueKey<StdTensorOp>, TensorMeta)>,
820{
821 let mut guard = global_metadata_registry()
822 .lock()
823 .map_err(|_| MetadataRegistryError::LockPoisoned)?;
824 let mut registrations = Vec::new();
825 for (key, meta) in entries {
826 let token = NEXT_GLOBAL_METADATA_TOKEN.fetch_add(1, AtomicOrdering::Relaxed);
827 let entry = guard
828 .entry(key.clone())
829 .or_insert_with(|| GlobalMetadataEntry { stack: Vec::new() });
830 entry.stack.push(GlobalMetadataRegistration { token, meta });
831 registrations.push(ScopedGlobalMetadataRegistration { key, token });
832 }
833 Ok(GlobalMetadataScope { registrations })
834}
835
836fn release_scoped_global_metadata(registrations: &[ScopedGlobalMetadataRegistration]) {
837 let Ok(mut guard) = global_metadata_registry().lock() else {
838 // Drop cannot return an error. Failing closed here avoids reading or
839 // mutating data from a poisoned registry at the cost of leaking entries
840 // until process exit.
841 return;
842 };
843 for registration in registrations {
844 let should_remove = if let Some(entry) = guard.get_mut(®istration.key) {
845 if let Some(position) = entry
846 .stack
847 .iter()
848 .rposition(|candidate| candidate.token == registration.token)
849 {
850 entry.stack.remove(position);
851 }
852 entry.stack.is_empty()
853 } else {
854 false
855 };
856 if should_remove {
857 guard.remove(®istration.key);
858 }
859 }
860}
861
862/// Resolve a [`DimExpr`] to a concrete `usize`.
863#[doc(hidden)]
864pub fn resolve_dim(dim: &DimExpr) -> Result<usize, DimExprEvalError> {
865 dim.eval(&[])
866}
867
868/// Resolve matrix dimensions and record their ordering as a guard.
869#[doc(hidden)]
870pub fn resolve_and_guard(
871 m: &DimExpr,
872 n: &DimExpr,
873 ctx: &mut ShapeGuardContext,
874) -> Result<(usize, usize), DimExprEvalError> {
875 let m_size = resolve_dim(m)?;
876 let n_size = resolve_dim(n)?;
877 ctx.guards.push(ShapeGuard {
878 dim_a: m_size,
879 dim_b: n_size,
880 ordering: m_size.cmp(&n_size),
881 });
882 Ok((m_size, n_size))
883}