tenferro_tensor/types.rs
1use num_complex::{Complex, Complex32, Complex64};
2use num_traits::{One, Zero};
3use std::any::Any;
4use std::fmt::Debug;
5use std::marker::PhantomData;
6use std::mem::{align_of, needs_drop, offset_of, size_of};
7use std::num::NonZeroUsize;
8use std::ops::Deref;
9use std::sync::atomic::{AtomicU64, Ordering};
10
11use crate::config::SliceConfig;
12use crate::error::ReinterpretError;
13pub use tenferro_tensor_core::{DType, DynRank, Rank, TensorLayout, TensorRank};
14use tenferro_tensor_core::{ShapeVec, StrideVec};
15use tenferro_tensor_core::{SliceSpec as CoreSliceSpec, ValidationError};
16use tinyvec::TinyVec;
17
18use crate::storage::{
19 AllocationGroup, AllocationSlot, BackendAllocation, DescriptorSlot, GroupError, GroupReadView,
20 GroupWriteView,
21};
22
23mod accessors;
24mod col_major;
25mod shape_packing;
26mod strided_view;
27#[cfg(test)]
28mod tests;
29
30pub use col_major::{ColMajorView, ColMajorViewMut};
31pub use strided_view::StridedSliceSpec;
32
33pub(crate) fn shape_vec(shape: &[usize]) -> ShapeVec {
34 shape.iter().copied().collect()
35}
36
37pub(crate) fn stride_vec(strides: &[isize]) -> StrideVec {
38 strides.iter().copied().collect()
39}
40
41pub(crate) fn shape_vec_zeros(len: usize) -> ShapeVec {
42 std::iter::repeat_n(0, len).collect()
43}
44
45fn representation_pair_error(
46 op: &'static str,
47 from: DType,
48 to: DType,
49 message: impl Into<String>,
50) -> crate::Error {
51 crate::Error::unsupported_dtype_conversion(op, from, to, message)
52}
53
54fn validate_representation_pair(op: &'static str, from: DType, to: DType) -> crate::Result<()> {
55 let valid = match (from, to) {
56 (DType::C32, DType::F32) | (DType::F32, DType::C32) => {
57 size_of::<Complex32>() == 2 * size_of::<f32>()
58 && align_of::<Complex32>() == align_of::<f32>()
59 && offset_of!(Complex32, re) == 0
60 && offset_of!(Complex32, im) == size_of::<f32>()
61 && !needs_drop::<Complex32>()
62 && !needs_drop::<f32>()
63 }
64 (DType::C64, DType::F64) | (DType::F64, DType::C64) => {
65 size_of::<Complex64>() == 2 * size_of::<f64>()
66 && align_of::<Complex64>() == align_of::<f64>()
67 && offset_of!(Complex64, re) == 0
68 && offset_of!(Complex64, im) == size_of::<f64>()
69 && !needs_drop::<Complex64>()
70 && !needs_drop::<f64>()
71 }
72 _ => false,
73 };
74 if valid {
75 Ok(())
76 } else {
77 Err(representation_pair_error(
78 op,
79 from,
80 to,
81 "only the sealed Complex<f32><->f32 and Complex<f64><->f64 representations are supported",
82 ))
83 }
84}
85
86fn reinterpret_complex_to_real_layout(
87 shape: &[usize],
88 strides: &[isize],
89 offset: isize,
90 complex_buffer_len: usize,
91 op: &'static str,
92) -> crate::Result<TensorLayout<DynRank>> {
93 let real_buffer_len = complex_buffer_len
94 .checked_mul(2)
95 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
96 let rank = shape
97 .len()
98 .checked_add(1)
99 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
100 let mut real_shape = ShapeVec::with_capacity(rank);
101 real_shape.push(2);
102 real_shape.extend_from_slice(shape);
103 let mut real_strides = StrideVec::with_capacity(rank);
104 real_strides.push(1);
105 for &stride in strides {
106 real_strides.push(
107 stride
108 .checked_mul(2)
109 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
110 );
111 }
112 let real_offset = offset
113 .checked_mul(2)
114 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
115 TensorLayout::from_parts(real_shape, real_strides, real_offset, real_buffer_len)
116 .map_err(|err| tensor_layout_error(op, err))
117}
118
119fn reinterpret_real_to_complex_layout(
120 shape: &[usize],
121 strides: &[isize],
122 offset: isize,
123 real_buffer_len: usize,
124 op: &'static str,
125) -> crate::Result<TensorLayout<DynRank>> {
126 if shape.first().copied() != Some(2) {
127 return Err(crate::Error::invalid_argument(
128 op,
129 "shape",
130 "the leading extent must be 2 for a complex reinterpretation",
131 ));
132 }
133 if strides.first().copied() != Some(1) {
134 return Err(crate::Error::invalid_argument(
135 op,
136 "strides",
137 "the leading stride must be 1 for a complex reinterpretation",
138 ));
139 }
140 if offset % 2 != 0 {
141 return Err(crate::Error::invalid_argument(
142 op,
143 "offset",
144 "the offset must be divisible by 2 for a complex reinterpretation",
145 ));
146 }
147 let mut complex_strides = StrideVec::with_capacity(strides.len() - 1);
148 for &stride in &strides[1..] {
149 if stride % 2 != 0 {
150 return Err(crate::Error::invalid_argument(
151 op,
152 "strides",
153 "all non-leading strides must be divisible by 2",
154 ));
155 }
156 complex_strides.push(stride / 2);
157 }
158 let complex_buffer_len = real_buffer_len / 2;
159 TensorLayout::from_parts(
160 shape[1..].iter().copied().collect(),
161 complex_strides,
162 offset / 2,
163 complex_buffer_len,
164 )
165 .map_err(|err| tensor_layout_error(op, err))
166}
167
168fn reinterpret_host_slice<'a, T: TensorScalar, U: TensorScalar>(
169 data: &'a [T],
170 op: &'static str,
171) -> crate::Result<&'a [U]> {
172 let byte_len = data
173 .len()
174 .checked_mul(size_of::<T>())
175 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
176 if !byte_len.is_multiple_of(size_of::<U>()) {
177 return Err(crate::Error::validation(
178 op,
179 ValidationError::ViewOutOfBounds,
180 ));
181 }
182 if data.as_ptr().align_offset(align_of::<U>()) != 0 {
183 return Err(crate::Error::invalid_argument(
184 op,
185 "alignment",
186 "the source allocation is not aligned for the target representation",
187 ));
188 }
189 // SAFETY: `validate_representation_pair` seals the only supported pairs;
190 // sizes, alignment, field order, and drop properties are checked before
191 // exposing the borrowed target slice.
192 Ok(unsafe { std::slice::from_raw_parts(data.as_ptr().cast::<U>(), byte_len / size_of::<U>()) })
193}
194
195fn reinterpret_host_slice_mut<'a, T: TensorScalar, U: TensorScalar>(
196 data: &'a mut [T],
197 op: &'static str,
198) -> crate::Result<&'a mut [U]> {
199 let byte_len = data
200 .len()
201 .checked_mul(size_of::<T>())
202 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
203 if !byte_len.is_multiple_of(size_of::<U>()) {
204 return Err(crate::Error::validation(
205 op,
206 ValidationError::ViewOutOfBounds,
207 ));
208 }
209 if data.as_mut_ptr().align_offset(align_of::<U>()) != 0 {
210 return Err(crate::Error::invalid_argument(
211 op,
212 "alignment",
213 "the source allocation is not aligned for the target representation",
214 ));
215 }
216 // SAFETY: the mutable source borrow is unique and the sealed pair has no
217 // padding or drop glue, so the target slice covers the same bytes exactly.
218 Ok(unsafe {
219 std::slice::from_raw_parts_mut(data.as_mut_ptr().cast::<U>(), byte_len / size_of::<U>())
220 })
221}
222
223/// Memory location for tensor storage.
224///
225/// # Examples
226///
227/// ```rust
228/// use tenferro_tensor::MemoryKind;
229///
230/// let kind = MemoryKind::UnpinnedHost;
231/// ```
232#[derive(Clone, Debug, PartialEq, Eq, Hash)]
233pub enum MemoryKind {
234 Device,
235 PinnedHost,
236 UnpinnedHost,
237 Managed,
238 Other(String),
239}
240
241/// Compute device family.
242///
243/// # Examples
244///
245/// ```rust
246/// use tenferro_tensor::DeviceKind;
247///
248/// let kind = DeviceKind::Cpu;
249/// ```
250#[derive(Clone, Debug, PartialEq, Eq, Hash)]
251pub enum DeviceKind {
252 Cpu,
253 Gpu(GpuBackendKind),
254 Other(String),
255}
256
257/// GPU backend family used by placement metadata.
258///
259/// # Examples
260///
261/// ```rust
262/// use tenferro_tensor::GpuBackendKind;
263///
264/// let kind = GpuBackendKind::Cuda;
265/// let webgpu = GpuBackendKind::WebGpu;
266/// assert_ne!(kind, webgpu);
267/// ```
268#[derive(Clone, Debug, PartialEq, Eq, Hash)]
269pub enum GpuBackendKind {
270 Cuda,
271 WebGpu,
272 Rocm,
273 /// Apple GPU through Metal (design `metal-backend.md`, issue tenferro-rs#2402).
274 Metal,
275 Other(String),
276}
277
278/// Concrete compute device identifier.
279///
280/// # Examples
281///
282/// ```rust
283/// use tenferro_tensor::{DeviceId, DeviceKind, GpuBackendKind};
284///
285/// let device = DeviceId {
286/// kind: DeviceKind::Gpu(GpuBackendKind::Cuda),
287/// ordinal: 0,
288/// };
289/// ```
290#[derive(Clone, Debug, PartialEq, Eq, Hash)]
291pub struct DeviceId {
292 pub kind: DeviceKind,
293 pub ordinal: usize,
294}
295
296/// Caller-stable identity for a CPU execution domain.
297///
298/// Domain IDs are metadata supplied by the caller or execution coordinator;
299/// creating an ID does not allocate a process-global identity.
300///
301/// # Examples
302///
303/// ```rust
304/// use tenferro_tensor::CpuDomainId;
305///
306/// let domain = CpuDomainId::new(17);
307/// assert_eq!(domain.as_u64(), 17);
308/// ```
309#[repr(transparent)]
310#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
311pub struct CpuDomainId(u64);
312
313impl CpuDomainId {
314 /// Create a caller-stable CPU domain identity.
315 ///
316 /// # Examples
317 ///
318 /// ```rust
319 /// use tenferro_tensor::CpuDomainId;
320 ///
321 /// assert_eq!(CpuDomainId::new(3), CpuDomainId::new(3));
322 /// ```
323 pub const fn new(id: u64) -> Self {
324 Self(id)
325 }
326
327 /// Return the caller-supplied integer identity.
328 ///
329 /// # Examples
330 ///
331 /// ```rust
332 /// use tenferro_tensor::CpuDomainId;
333 ///
334 /// assert_eq!(CpuDomainId::new(9).as_u64(), 9);
335 /// ```
336 pub const fn as_u64(self) -> u64 {
337 self.0
338 }
339}
340
341/// Placement metadata for a tensor buffer.
342///
343/// # Examples
344///
345/// ```rust
346/// use tenferro_tensor::{DeviceId, DeviceKind, GpuBackendKind, MemoryKind, Placement};
347///
348/// let placement = Placement {
349/// memory_kind: MemoryKind::Device,
350/// device: Some(DeviceId {
351/// kind: DeviceKind::Gpu(GpuBackendKind::Cuda),
352/// ordinal: 0,
353/// }),
354/// cpu_affinity: None,
355/// };
356/// assert!(placement.cpu_affinity.is_none());
357/// ```
358#[derive(Clone, Debug, PartialEq, Eq, Hash)]
359pub struct Placement {
360 /// Storage memory class, independent of execution routing metadata.
361 pub memory_kind: MemoryKind,
362 /// Device that owns or addresses the storage, when applicable.
363 pub device: Option<DeviceId>,
364 /// Preferred or producing CPU execution domain for routing and locality.
365 ///
366 /// This tag is not proof of allocation ownership, page residency, NUMA
367 /// pinning, or worker-affinity enforcement. Backend allocation-domain
368 /// metadata remains attached to the buffer independently.
369 pub cpu_affinity: Option<CpuDomainId>,
370}
371
372impl Default for Placement {
373 fn default() -> Self {
374 default_placement()
375 }
376}
377
378/// Backend-owned buffer handle.
379///
380/// `BackendStorageHandle::new` creates an empty opaque handle. Use
381/// [`BackendStorageHandle::new_with_len`] when test or adapter code needs to model a
382/// non-empty backend allocation.
383///
384/// # Examples
385///
386/// ```rust
387/// use tenferro_tensor::BackendStorageHandle;
388///
389/// let handle = BackendStorageHandle::<f64>::new(7);
390/// ```
391pub struct BackendStorageHandle<T> {
392 id: u64,
393 len: usize,
394 allocation_domain: AllocationDomainId,
395 _phantom: std::marker::PhantomData<T>,
396}
397
398/// Identity of a backend-owned allocation domain.
399///
400/// Domains let cooperating backends accept shared allocations without treating
401/// another context's physically similar buffer as compatible.
402///
403/// # Examples
404///
405/// ```rust
406/// use tenferro_tensor::AllocationDomainId;
407///
408/// assert_ne!(AllocationDomainId::fresh(), AllocationDomainId::fresh());
409/// ```
410#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
411pub struct AllocationDomainId(u64);
412
413impl AllocationDomainId {
414 /// Create a process-unique allocation-domain identity.
415 ///
416 /// # Examples
417 ///
418 /// ```rust
419 /// use tenferro_tensor::AllocationDomainId;
420 ///
421 /// let domain = AllocationDomainId::fresh();
422 /// assert_eq!(domain, domain);
423 /// ```
424 pub fn fresh() -> Self {
425 static NEXT_DOMAIN_ID: AtomicU64 = AtomicU64::new(1);
426 Self(NEXT_DOMAIN_ID.fetch_add(1, Ordering::Relaxed))
427 }
428}
429
430/// Stable physical identity of one backend allocation.
431///
432/// # Examples
433///
434/// ```rust
435/// use tenferro_tensor::AllocationId;
436///
437/// assert_eq!(AllocationId::from_backend_id(7), AllocationId::from_backend_id(7));
438/// ```
439#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
440pub struct AllocationId(u64);
441
442impl AllocationId {
443 /// Wrap an allocation identity supplied by the owning backend.
444 ///
445 /// # Examples
446 ///
447 /// ```rust
448 /// use tenferro_tensor::AllocationId;
449 ///
450 /// let id = AllocationId::from_backend_id(3);
451 /// assert_eq!(id, AllocationId::from_backend_id(3));
452 /// ```
453 pub const fn from_backend_id(id: u64) -> Self {
454 Self(id)
455 }
456}
457
458/// Typed failure returned by guarded backend host access.
459///
460/// # Examples
461///
462/// ```rust
463/// use tenferro_tensor::HostAccessError;
464///
465/// let error = HostAccessError::Unsupported { backend: "opaque" };
466/// assert!(error.to_string().contains("opaque"));
467/// ```
468#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
469#[non_exhaustive]
470pub enum HostAccessError {
471 /// The backend does not expose guarded host access for this allocation.
472 #[error("backend `{backend}` does not support guarded host access")]
473 Unsupported { backend: &'static str },
474 /// The allocation belongs to another shared-allocation domain.
475 #[error("allocation belongs to domain {actual:?}, expected {expected:?}")]
476 ForeignDomain {
477 expected: AllocationDomainId,
478 actual: AllocationDomainId,
479 },
480 /// Another host mapping overlaps this allocation.
481 #[error("the allocation already has an active host mapping")]
482 OverlappingHostMapping,
483 /// GPU work currently owns or has reserved the allocation.
484 #[error("GPU access is in progress for the allocation")]
485 GpuAccessInProgress,
486 /// Host mapping is active while GPU access was requested.
487 #[error("the allocation is mapped for host access")]
488 MappedForHost,
489 /// The backend failed to complete the map operation.
490 #[error("backend host mapping failed: {message}")]
491 BackendFailure { message: String },
492 /// The source did not cover the full write-only mapping.
493 #[error("host write length mismatch: expected {expected}, got {actual}")]
494 LengthMismatch { expected: usize, actual: usize },
495}
496
497/// Metadata sealed at the tensor/root boundary before a provider launch.
498///
499/// Providers receive this request exactly once for a prepared access. Binding
500/// code consumes the resulting opaque state and does not receive replacement
501/// storage, ranges, or raw pointers.
502#[doc(hidden)]
503#[derive(Clone, Copy, Debug)]
504pub struct DeviceAccessRequest<'a> {
505 allocation_domain: AllocationDomainId,
506 allocation_id: AllocationId,
507 byte_len: usize,
508 element_size: usize,
509 shape: &'a [usize],
510 strides: &'a [isize],
511 offset: isize,
512}
513
514impl<'a> DeviceAccessRequest<'a> {
515 pub(crate) fn new(
516 allocation_domain: AllocationDomainId,
517 allocation_id: AllocationId,
518 byte_len: usize,
519 element_size: usize,
520 shape: &'a [usize],
521 strides: &'a [isize],
522 offset: isize,
523 ) -> Self {
524 Self {
525 allocation_domain,
526 allocation_id,
527 byte_len,
528 element_size,
529 shape,
530 strides,
531 offset,
532 }
533 }
534
535 pub fn allocation_domain(&self) -> AllocationDomainId {
536 self.allocation_domain
537 }
538
539 pub fn allocation_id(&self) -> AllocationId {
540 self.allocation_id
541 }
542
543 pub fn byte_len(&self) -> usize {
544 self.byte_len
545 }
546
547 pub fn element_size(&self) -> usize {
548 self.element_size
549 }
550
551 pub fn shape(&self) -> &[usize] {
552 self.shape
553 }
554
555 pub fn strides(&self) -> &[isize] {
556 self.strides
557 }
558
559 pub fn offset(&self) -> isize {
560 self.offset
561 }
562}
563
564/// Typed failure returned while preparing a provider-native device access.
565#[doc(hidden)]
566#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
567pub enum DeviceAccessError {
568 #[error("backend `{backend}` does not support prepared device access")]
569 Unsupported { backend: &'static str },
570 #[error("prepared device access request is invalid: {message}")]
571 InvalidRequest { message: String },
572 #[error("provider device preparation failed: {message}")]
573 ProviderFailure { message: String },
574}
575
576/// Opaque provider-prepared state retained for one device binding.
577#[doc(hidden)]
578pub trait PreparedDeviceAccess: Debug {
579 fn as_any(&self) -> &dyn Any;
580
581 fn into_any(self: Box<Self>) -> Box<dyn Any>;
582}
583
584trait ReadGuardAccess<T> {
585 fn as_slice(&self) -> &[T];
586}
587
588impl<T, G> ReadGuardAccess<T> for G
589where
590 G: Deref,
591 G::Target: AsRef<[T]>,
592{
593 fn as_slice(&self) -> &[T] {
594 self.deref().as_ref()
595 }
596}
597
598/// Closure-scoped read mapping of a backend allocation.
599///
600/// # Examples
601///
602/// ```rust
603/// use tenferro_tensor::HostReadGuard;
604///
605/// let guard = HostReadGuard::new(vec![1_u32, 2]);
606/// assert_eq!(&*guard, &[1, 2]);
607/// ```
608pub struct HostReadGuard<'a, T> {
609 access: Box<dyn ReadGuardAccess<T> + 'a>,
610}
611
612impl<T> Debug for HostReadGuard<'_, T> {
613 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
614 formatter
615 .debug_struct("HostReadGuard")
616 .field("len", &self.len())
617 .finish_non_exhaustive()
618 }
619}
620
621impl<'a, T> HostReadGuard<'a, T> {
622 /// Wrap a backend-native read guard without exposing its concrete type.
623 ///
624 /// # Examples
625 ///
626 /// ```rust
627 /// use tenferro_tensor::HostReadGuard;
628 ///
629 /// let guard = HostReadGuard::new(vec![3_i32]);
630 /// assert_eq!(guard[0], 3);
631 /// ```
632 pub fn new<G>(guard: G) -> Self
633 where
634 G: Deref + 'a,
635 G::Target: AsRef<[T]>,
636 T: 'a,
637 {
638 Self {
639 access: Box::new(guard),
640 }
641 }
642
643 /// Borrow the mapped elements as a rank-1 host view.
644 ///
645 /// The view lends the mapping's shared borrow, so the guard stays alive for
646 /// as long as the view is used and no copy or transfer happens.
647 ///
648 /// # Examples
649 ///
650 /// ```rust
651 /// use tenferro_tensor::HostReadGuard;
652 ///
653 /// let guard = HostReadGuard::new(vec![3_i32, 4]);
654 /// let view = guard.as_view()?;
655 /// assert_eq!(view.shape(), &[2]);
656 /// assert_eq!(view.get(&[1]), Some(&4));
657 /// # Ok::<(), tenferro_tensor::Error>(())
658 /// ```
659 ///
660 /// # Errors
661 ///
662 /// Returns [`crate::Error::Validation`] with
663 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] or
664 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
665 /// mapped length cannot be represented as a rank-1 layout.
666 pub fn as_view(&self) -> crate::Result<TypedTensorView<'_, T, DynRank>>
667 where
668 T: 'static,
669 {
670 let data: &[T] = self;
671 TypedTensorView::from_slice(vec![data.len()], vec![1], 0, data)
672 }
673}
674
675impl<T> Deref for HostReadGuard<'_, T> {
676 type Target = [T];
677
678 fn deref(&self) -> &Self::Target {
679 self.access.as_slice()
680 }
681}
682
683/// Backend-neutral owner of one shared tensor allocation domain.
684///
685/// CPU operation crates use this object-safe boundary to allocate results in
686/// the same managed domain without depending on a GPU provider crate.
687///
688/// # Examples
689///
690/// ```rust
691/// use std::sync::Arc;
692/// use tenferro_tensor::SharedTensorAllocationDomain;
693///
694/// let _domain: Option<Arc<dyn SharedTensorAllocationDomain>> = None;
695/// ```
696pub trait SharedTensorAllocationDomain: Debug + Send + Sync + 'static {
697 /// Return the stable identity shared by every allocation from this owner.
698 fn id(&self) -> AllocationDomainId;
699
700 /// Allocate an uninitialized compact column-major tensor in this domain.
701 ///
702 /// # Errors
703 ///
704 /// Returns a typed validation, unsupported-dtype, or backend allocation error.
705 fn allocate(&self, dtype: DType, shape: &[usize]) -> crate::Result<Tensor>;
706}
707
708type HostWriteCopy<'a, T> = dyn FnMut(&[T]) -> Result<(), HostAccessError> + 'a;
709
710/// Closure-scoped write-only mapping of a backend allocation.
711///
712/// # Examples
713///
714/// ```rust
715/// use tenferro_tensor::{HostAccessError, HostWriteGuard};
716///
717/// let mut written = Vec::new();
718/// {
719/// let mut guard = HostWriteGuard::new(2, |source: &[u32]| {
720/// written.extend_from_slice(source);
721/// Ok::<(), HostAccessError>(())
722/// });
723/// guard.copy_from_slice(&[4, 5]).unwrap();
724/// }
725/// assert_eq!(written, [4, 5]);
726/// ```
727pub struct HostWriteGuard<'a, T> {
728 len: usize,
729 copy: Box<HostWriteCopy<'a, T>>,
730}
731
732impl<T> Debug for HostWriteGuard<'_, T> {
733 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
734 formatter
735 .debug_struct("HostWriteGuard")
736 .field("len", &self.len)
737 .finish_non_exhaustive()
738 }
739}
740
741impl<'a, T> HostWriteGuard<'a, T> {
742 /// Wrap a backend-native write guard without exposing its concrete type.
743 ///
744 /// # Examples
745 ///
746 /// ```rust
747 /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
748 ///
749 /// let guard = HostWriteGuard::new(0, |_source: &[f32]| Ok::<(), HostAccessError>(()));
750 /// assert!(guard.is_empty());
751 /// ```
752 ///
753 /// # Errors
754 ///
755 /// Construction is infallible. A callback failure such as
756 /// [`HostAccessError::BackendFailure`] is returned later by
757 /// [`Self::copy_from_slice`].
758 pub fn new<F>(len: usize, copy: F) -> Self
759 where
760 F: FnMut(&[T]) -> Result<(), HostAccessError> + 'a,
761 T: 'a,
762 {
763 Self {
764 len,
765 copy: Box::new(copy),
766 }
767 }
768
769 /// Number of elements covered by this write-only mapping.
770 ///
771 /// # Examples
772 ///
773 /// ```rust
774 /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
775 ///
776 /// let guard = HostWriteGuard::new(2, |_source: &[f32]| Ok::<(), HostAccessError>(()));
777 /// assert_eq!(guard.len(), 2);
778 /// ```
779 pub fn len(&self) -> usize {
780 self.len
781 }
782
783 /// Returns `true` when this mapping covers no elements.
784 ///
785 /// # Examples
786 ///
787 /// ```rust
788 /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
789 ///
790 /// let guard = HostWriteGuard::new(0, |_source: &[f32]| Ok::<(), HostAccessError>(()));
791 /// assert!(guard.is_empty());
792 /// ```
793 pub fn is_empty(&self) -> bool {
794 self.len == 0
795 }
796
797 /// Replace the full mapped allocation contents.
798 ///
799 /// # Examples
800 ///
801 /// ```rust
802 /// use tenferro_tensor::{HostAccessError, HostWriteGuard};
803 ///
804 /// let mut guard = HostWriteGuard::new(1, |_source: &[f32]| Ok::<(), HostAccessError>(()));
805 /// guard.copy_from_slice(&[1.0]).unwrap();
806 /// ```
807 ///
808 /// # Errors
809 ///
810 /// Returns [`HostAccessError::LengthMismatch`] when `source` does not cover
811 /// the complete mapping, or the typed backend error returned by the owning
812 /// write guard.
813 pub fn copy_from_slice(&mut self, source: &[T]) -> Result<(), HostAccessError> {
814 if source.len() != self.len {
815 return Err(HostAccessError::LengthMismatch {
816 expected: self.len,
817 actual: source.len(),
818 });
819 }
820 (self.copy)(source)
821 }
822}
823
824impl<T> Debug for BackendStorageHandle<T> {
825 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
826 f.debug_struct("BackendStorageHandle")
827 .field("id", &self.id)
828 .finish()
829 }
830}
831
832impl<T> BackendStorageHandle<T> {
833 /// Create a new backend buffer handle.
834 ///
835 /// # Examples
836 ///
837 /// ```rust
838 /// use tenferro_tensor::BackendStorageHandle;
839 ///
840 /// let handle = BackendStorageHandle::<f64>::new(1);
841 /// assert_eq!(tenferro_tensor::BackendStorage::len(&handle), 0);
842 /// ```
843 pub fn new(id: u64) -> Self {
844 Self::new_with_len(id, 0)
845 }
846
847 /// Create a new backend buffer handle with a logical element count.
848 ///
849 /// # Examples
850 ///
851 /// ```rust
852 /// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
853 ///
854 /// let handle = BackendStorageHandle::<f64>::new_with_len(1, 4);
855 /// assert_eq!(BackendStorage::len(&handle), 4);
856 /// ```
857 pub fn new_with_len(id: u64, len: usize) -> Self {
858 Self {
859 id,
860 len,
861 // Synthetic opaque handles are test/adapter allocations. Give
862 // each one an explicit domain so root import never fabricates
863 // identity from a missing provider field.
864 allocation_domain: AllocationDomainId::fresh(),
865 _phantom: std::marker::PhantomData,
866 }
867 }
868}
869
870/// Opaque backend-owned tensor buffer.
871///
872/// Tensor core never inspects backend-native allocations directly. Backend
873/// crates store their own concrete handle types behind this trait and
874/// downcast inside the owning backend only.
875///
876/// # Examples
877///
878/// ```rust
879/// use std::sync::Arc;
880/// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
881///
882/// let buffer: Arc<dyn BackendStorage<f64>> = Arc::new(BackendStorageHandle::<f64>::new_with_len(7, 2));
883/// assert_eq!(buffer.backend_family(), "opaque");
884/// assert_eq!(buffer.len(), 2);
885/// ```
886pub trait BackendStorage<T>: Debug + Send + Sync + 'static {
887 /// Stable backend family identifier.
888 fn backend_family(&self) -> &'static str;
889
890 /// Number of logical elements in the backend allocation.
891 fn len(&self) -> usize;
892
893 /// Returns `true` when the backend allocation is empty.
894 fn is_empty(&self) -> bool {
895 self.len() == 0
896 }
897
898 /// Return the shared-allocation domain, when this buffer belongs to one.
899 fn allocation_domain(&self) -> Option<AllocationDomainId> {
900 None
901 }
902
903 /// Return the stable physical allocation identity, when available.
904 fn allocation_id(&self) -> Option<AllocationId> {
905 None
906 }
907
908 /// Prepare one provider-native device access from the root-owned buffer.
909 ///
910 /// The returned state is consumed by the provider binding path. Providers
911 /// that do not expose device launches return [`DeviceAccessError::Unsupported`].
912 #[doc(hidden)]
913 fn prepare_device_access(
914 &self,
915 _request: DeviceAccessRequest<'_>,
916 ) -> Result<Box<dyn PreparedDeviceAccess>, DeviceAccessError> {
917 Err(DeviceAccessError::Unsupported {
918 backend: self.backend_family(),
919 })
920 }
921
922 /// Map the allocation for closure-scoped host reads.
923 ///
924 /// # Errors
925 ///
926 /// The default returns [`HostAccessError::Unsupported`]. Host-visible
927 /// backends return typed overlap, pending-GPU, or backend mapping failures.
928 fn map_read(&self) -> Result<HostReadGuard<'_, T>, HostAccessError> {
929 Err(HostAccessError::Unsupported {
930 backend: self.backend_family(),
931 })
932 }
933
934 /// Map the allocation for closure-scoped host writes.
935 ///
936 /// The mutable receiver keeps write authority with the owning tensor or
937 /// provider object; borrowed views do not clone or share that authority.
938 ///
939 /// # Errors
940 ///
941 /// The default returns [`HostAccessError::Unsupported`]. Host-visible
942 /// backends return typed overlap, pending-GPU, or backend mapping failures.
943 fn map_write(&mut self) -> Result<HostWriteGuard<'_, T>, HostAccessError> {
944 Err(HostAccessError::Unsupported {
945 backend: self.backend_family(),
946 })
947 }
948
949 /// Borrow the allocation as shared memory the CPU and the device both address.
950 ///
951 /// A provider implements this only for an allocation whose elements are
952 /// readable at the same address from the host and from the device (a shared
953 /// allocation domain). **The call is the wait**: an implementation waits for
954 /// its pending device writes before it hands out the borrow, so there is no
955 /// separate fence call and no copy, and the borrow itself is the only host
956 /// access that exists for such an allocation.
957 ///
958 /// This is deliberately a borrow rather than a closure-scoped guard like
959 /// [`Self::map_read`]: a shared allocation is never mapped or unmapped, and
960 /// a CPU kernel needs a `StridedView<'a, T>` that outlives such a guard.
961 /// Exclusive CPU writes still go through [`Self::map_write`] and the
962 /// ownership kernel's exclusive capability.
963 ///
964 /// # Examples
965 ///
966 /// ```rust
967 /// use tenferro_tensor::{BackendStorage, BackendStorageHandle};
968 ///
969 /// // An opaque handle exposes no shared memory, so it keeps the refusal.
970 /// let buffer = BackendStorageHandle::<f32>::new_with_len(1, 4);
971 /// assert!(buffer.shared_host_slice().is_err());
972 /// ```
973 ///
974 /// # Errors
975 ///
976 /// The default returns [`HostAccessError::Unsupported`], so every
977 /// device-local backend refuses shared host access exactly as before. A
978 /// provider that cannot serve the borrow returns its own typed failure.
979 fn shared_host_slice(&self) -> Result<&[T], HostAccessError> {
980 Err(HostAccessError::Unsupported {
981 backend: self.backend_family(),
982 })
983 }
984
985 /// Type-erased access for the backend crate that owns the concrete handle.
986 fn as_any(&self) -> &dyn Any;
987}
988
989impl<T: Send + Sync + 'static> BackendStorage<T> for BackendStorageHandle<T> {
990 fn backend_family(&self) -> &'static str {
991 "opaque"
992 }
993
994 fn len(&self) -> usize {
995 self.len
996 }
997
998 fn allocation_domain(&self) -> Option<AllocationDomainId> {
999 Some(self.allocation_domain)
1000 }
1001
1002 fn allocation_id(&self) -> Option<AllocationId> {
1003 Some(AllocationId::from_backend_id(self.id))
1004 }
1005
1006 fn as_any(&self) -> &dyn Any {
1007 self
1008 }
1009}
1010
1011/// Tensor storage.
1012///
1013/// # Examples
1014///
1015/// ```rust
1016/// use tenferro_tensor::StorageBuffer;
1017///
1018/// let host = StorageBuffer::Host(vec![1.0_f64, 2.0]);
1019/// ```
1020#[derive(Debug)]
1021pub enum StorageBuffer<T> {
1022 Host(Vec<T>),
1023 Backend(Box<dyn BackendStorage<T>>),
1024}
1025
1026impl<T: 'static> StorageBuffer<T> {
1027 /// Return the physical element count in this buffer.
1028 ///
1029 /// # Examples
1030 ///
1031 /// ```rust
1032 /// use tenferro_tensor::StorageBuffer;
1033 ///
1034 /// assert_eq!(StorageBuffer::Host(vec![1_i32, 2]).len(), 2);
1035 /// ```
1036 pub fn len(&self) -> usize {
1037 match self {
1038 Self::Host(data) => data.len(),
1039 Self::Backend(buffer) => buffer.len(),
1040 }
1041 }
1042
1043 /// Return whether this buffer has no physical elements.
1044 ///
1045 /// # Examples
1046 ///
1047 /// ```rust
1048 /// use tenferro_tensor::StorageBuffer;
1049 ///
1050 /// assert!(StorageBuffer::<i32>::Host(Vec::new()).is_empty());
1051 /// ```
1052 pub fn is_empty(&self) -> bool {
1053 self.len() == 0
1054 }
1055
1056 /// Return whether the storage is backend-owned rather than host-owned.
1057 ///
1058 /// # Examples
1059 ///
1060 /// ```rust
1061 /// use tenferro_tensor::StorageBuffer;
1062 ///
1063 /// assert!(!StorageBuffer::Host(vec![1_i32]).is_backend());
1064 /// ```
1065 pub fn is_backend(&self) -> bool {
1066 matches!(self, Self::Backend(_))
1067 }
1068}
1069
1070/// Sealed marker for the plain and pooled host payload of a [`TypedTensor`].
1071///
1072/// `TypedTensor<T, R, Host>` owns host elements directly, so it offers
1073/// infallible host access (`as_slice`, `get`, `get_mut`, `Index`/`IndexMut`)
1074/// and [`Clone`] without a runtime device check. `T` needs no `Copy`,
1075/// [`TensorScalar`] or arithmetic bound for that.
1076///
1077/// # Examples
1078///
1079/// ```
1080/// use tenferro_tensor::{DynRank, Host, TypedTensor};
1081///
1082/// let tensor: TypedTensor<f64, DynRank, Host> =
1083/// TypedTensor::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1084/// assert_eq!(tensor.as_slice(), &[1.0, 2.0]);
1085/// assert_eq!(tensor[&[1]], 2.0);
1086/// # Ok::<(), tenferro_tensor::Error>(())
1087/// ```
1088#[derive(Debug)]
1089pub struct Host;
1090
1091/// Sealed marker for the group-backed payload of a [`TypedTensor`].
1092///
1093/// `TypedTensor<T, R, Gpu>` carries provider allocation authority, identity
1094/// and retirement state through its allocation group, so host access stays
1095/// fallible and must be prepared or mapped explicitly. The marker is not proof
1096/// of a particular device ordinal or provider.
1097///
1098/// # Examples
1099///
1100/// ```
1101/// use tenferro_tensor::{DynRank, Gpu, Host, TypedTensor};
1102///
1103/// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1104/// let gpu: TypedTensor<f64, DynRank, Gpu> = host.promote()?;
1105/// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
1106/// # Ok::<(), tenferro_tensor::Error>(())
1107/// ```
1108#[derive(Debug)]
1109pub struct Gpu;
1110
1111/// Sealed marker for the runtime union of the host and group-backed payloads.
1112///
1113/// This is the default representation: one type for ordinary tensors that may
1114/// be host-resident or backend-resident at runtime.
1115///
1116/// # Examples
1117///
1118/// ```
1119/// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
1120///
1121/// let host = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1122/// let dynamic: TypedTensor<i32, DynRank, Dynamic> = host.into_dynamic();
1123/// assert_eq!(dynamic.host_data()?, &[1, 2]);
1124/// # Ok::<(), tenferro_tensor::Error>(())
1125/// ```
1126#[derive(Debug)]
1127pub struct Dynamic;
1128
1129mod representation_sealed {
1130 pub trait Sealed {}
1131 impl Sealed for super::Host {}
1132 impl Sealed for super::Gpu {}
1133 impl Sealed for super::Dynamic {}
1134}
1135
1136/// Sealed selector for the owned payload representation of a [`TypedTensor`].
1137///
1138/// The three markers are [`Host`], [`Gpu`] and [`Dynamic`]. The trait is
1139/// sealed: downstream crates select an existing representation, they do not
1140/// define one.
1141///
1142/// # Examples
1143///
1144/// ```
1145/// use tenferro_tensor::{Dynamic, DynRank, Host, Representation, TypedTensor};
1146///
1147/// fn extent<D: Representation>(tensor: &TypedTensor<f64, DynRank, D>) -> usize {
1148/// tensor.shape()[0]
1149/// }
1150/// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![3], vec![0.0; 3])?;
1151/// assert_eq!(extent(&host), 3);
1152/// let dynamic: TypedTensor<f64, DynRank, Dynamic> = host.into_dynamic();
1153/// assert_eq!(extent(&dynamic), 3);
1154/// # Ok::<(), tenferro_tensor::Error>(())
1155/// ```
1156pub trait Representation: representation_sealed::Sealed + 'static {
1157 /// Owned payload stored for this representation.
1158 #[doc(hidden)]
1159 type Storage<T, R: TensorRank>;
1160
1161 /// Placement given to an owner of this representation built without one.
1162 ///
1163 /// Placement metadata is fixed when a [`Host`] or [`Gpu`] owner is built:
1164 /// only a [`Dynamic`] owner can replace it afterwards, through
1165 /// [`TypedTensor::set_placement`]. [`Host`] constructors use this
1166 /// placement, unpinned host memory with no device and no CPU affinity.
1167 /// [`Gpu`] and [`Dynamic`] use the same default when no placement is
1168 /// supplied; a device-resident owner receives its device placement from
1169 /// the constructor that adopts the backend buffer.
1170 ///
1171 /// # Examples
1172 ///
1173 /// ```
1174 /// use tenferro_tensor::{DynRank, Host, MemoryKind, Representation, TypedTensor};
1175 ///
1176 /// let expected = <Host as Representation>::default_placement();
1177 /// assert_eq!(expected.memory_kind, MemoryKind::UnpinnedHost);
1178 /// assert!(expected.device.is_none());
1179 /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0])?;
1180 /// assert_eq!(host.placement(), &expected);
1181 /// # Ok::<(), tenferro_tensor::Error>(())
1182 /// ```
1183 fn default_placement() -> Placement;
1184}
1185
1186impl Representation for Host {
1187 #[doc(hidden)]
1188 type Storage<T, R: TensorRank> = HostStorage<T>;
1189
1190 fn default_placement() -> Placement {
1191 default_placement()
1192 }
1193}
1194
1195impl Representation for Gpu {
1196 #[doc(hidden)]
1197 type Storage<T, R: TensorRank> = GroupStorage<R>;
1198
1199 fn default_placement() -> Placement {
1200 // The only Gpu constructor without an explicit placement is
1201 // `TypedTensor<_, _, Host>::promote`, which keeps the host owner's
1202 // placement: unpinned host memory on the CPU provider.
1203 default_placement()
1204 }
1205}
1206
1207impl Representation for Dynamic {
1208 #[doc(hidden)]
1209 type Storage<T, R: TensorRank> = DynamicStorage<T, R>;
1210
1211 fn default_placement() -> Placement {
1212 default_placement()
1213 }
1214}
1215
1216/// Directly owned plain or pooled host elements.
1217#[doc(hidden)]
1218pub struct HostStorage<T> {
1219 data: HostData<T>,
1220}
1221
1222/// Group-backed payload: provider allocation authority, identity and retirement.
1223#[doc(hidden)]
1224pub struct GroupStorage<R: TensorRank> {
1225 group: Box<OwnedTensorGroup<R>>,
1226}
1227
1228/// Runtime union of the [`Host`] and [`Gpu`] owned payloads.
1229#[doc(hidden)]
1230pub enum DynamicStorage<T, R: TensorRank> {
1231 Host(HostStorage<T>),
1232 Group(GroupStorage<R>),
1233}
1234
1235impl<T> std::fmt::Debug for HostStorage<T> {
1236 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1237 self.data.fmt(formatter)
1238 }
1239}
1240
1241impl<R: TensorRank> std::fmt::Debug for GroupStorage<R> {
1242 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1243 formatter
1244 .debug_struct("GroupStorage")
1245 .field("group", &self.group)
1246 .finish()
1247 }
1248}
1249
1250impl<T, R: TensorRank> std::fmt::Debug for DynamicStorage<T, R> {
1251 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1252 match self {
1253 Self::Host(host) => formatter.debug_tuple("Host").field(host).finish(),
1254 Self::Group(group) => formatter.debug_tuple("Group").field(group).finish(),
1255 }
1256 }
1257}
1258
1259/// Owned compact column-major typed tensor.
1260///
1261/// `T` is the element type, `R` the rank metadata (default [`DynRank`]) and `D`
1262/// the owned representation (default [`Dynamic`]). Shape and placement live on
1263/// the tensor itself, once, never inside a storage arm.
1264///
1265/// No bound is imposed on `T` by the type: plain host adoption only needs the
1266/// constructor's own requirements, and `T: Clone` is required only by the
1267/// copying constructors. A preset [`TensorScalar`] appears only where a dtype
1268/// identity or a numerical capability is actually used, never for plain host
1269/// ownership.
1270///
1271/// Owned tensors are compact column-major. Arbitrary strides and metadata-only
1272/// layout changes are represented by [`TypedTensorView`] and
1273/// [`TypedTensorViewMut`].
1274///
1275/// # Examples
1276///
1277/// ```
1278/// use tenferro_tensor::{DynRank, Host, Rank, Tensor, TypedTensor};
1279///
1280/// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
1281/// assert_eq!(t.shape(), &[2, 2]);
1282///
1283/// let static_rank = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
1284/// assert_eq!(static_rank.rank(), 2);
1285///
1286/// let host: TypedTensor<i32, DynRank, Host> =
1287/// TypedTensor::from_host_vec_col_major(vec![2], vec![1, 2]).unwrap();
1288/// assert_eq!(host.get(&[1])?, &2);
1289///
1290/// let dynamic = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1291/// assert_eq!(dynamic.shape(), &[2, 2]);
1292/// # Ok::<(), tenferro_tensor::Error>(())
1293/// ```
1294pub struct TypedTensor<T, R: TensorRank = DynRank, D: Representation = Dynamic> {
1295 shape: R::Shape,
1296 placement: Placement,
1297 /// Column-major element strides, cached at construction so a strided view of
1298 /// this tensor borrows its layout instead of recomputing it per operation.
1299 layout: StrideVec,
1300 storage: D::Storage<T, R>,
1301}
1302
1303/// Validate and adopt a column-major host vector as a statically host-owned tensor.
1304fn typed_host_tensor_from_vec_col_major<T, R: TensorRank>(
1305 shape: impl tenferro_tensor_core::IntoRankShape<R>,
1306 data: Vec<T>,
1307 op: &'static str,
1308) -> crate::Result<TypedTensor<T, R, Host>> {
1309 let shape = shape
1310 .into_rank_shape()
1311 .map_err(|err| tensor_layout_error(op, err))?;
1312 let layout = tenferro_tensor_core::col_major_strides(shape.as_ref())
1313 .map_err(|err| tensor_layout_error(op, err))?;
1314 try_checked_shape_len(shape.as_ref(), data.len(), op)?;
1315 Ok(TypedTensor {
1316 shape,
1317 placement: <Host as Representation>::default_placement(),
1318 layout,
1319 storage: HostStorage {
1320 data: HostData::new(data),
1321 },
1322 })
1323}
1324
1325/// Reorder explicit row-major host values into column-major order.
1326fn row_major_reorder<T: Clone, R: TensorRank>(
1327 shape: impl tenferro_tensor_core::IntoRankShape<R>,
1328 data: Vec<T>,
1329 op: &'static str,
1330) -> crate::Result<(R::Shape, Vec<T>)> {
1331 let shape = shape
1332 .into_rank_shape()
1333 .map_err(|err| tensor_layout_error(op, err))?;
1334 tenferro_tensor_core::col_major_strides(shape.as_ref())
1335 .map_err(|err| tensor_layout_error(op, err))?;
1336 try_checked_shape_len(shape.as_ref(), data.len(), op)?;
1337 let mut row_strides = shape_vec_zeros(shape.as_ref().len());
1338 let mut stride = 1usize;
1339 for axis in (0..row_strides.len()).rev() {
1340 row_strides[axis] = stride;
1341 stride = stride
1342 .checked_mul(shape.as_ref()[axis])
1343 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
1344 }
1345 let mut coordinates = shape_vec_zeros(row_strides.len());
1346 let mut source_offset = 0usize;
1347 let mut reordered = Vec::with_capacity(data.len());
1348 for _ in 0..data.len() {
1349 reordered.push(data[source_offset].clone());
1350 for axis in 0..coordinates.len() {
1351 coordinates[axis] += 1;
1352 if coordinates[axis] < shape.as_ref()[axis] {
1353 source_offset += row_strides[axis];
1354 break;
1355 }
1356 coordinates[axis] = 0;
1357 source_offset -= row_strides[axis] * (shape.as_ref()[axis] - 1);
1358 }
1359 }
1360 Ok((shape, reordered))
1361}
1362
1363impl<T, R: TensorRank> TypedTensor<T, R, Host> {
1364 /// Adopt a column-major host `Vec<T>` as a statically host-owned tensor.
1365 ///
1366 /// The payload is the caller's vector itself; `T` needs no `Copy`,
1367 /// [`TensorScalar`] or arithmetic bound, and no group, session or device is
1368 /// involved.
1369 ///
1370 /// # Examples
1371 /// ```
1372 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1373 /// struct Custom(String);
1374 /// let tensor = TypedTensor::<Custom, Rank<2>, Host>::from_host_vec_col_major(
1375 /// [1, 2], vec![Custom("a".into()), Custom("b".into())],
1376 /// )?;
1377 /// assert_eq!(tensor[&[0, 1]].0.as_str(), "b");
1378 /// # Ok::<(), tenferro_tensor::Error>(())
1379 /// ```
1380 /// # Errors
1381 /// Returns [`crate::Error::Validation`] for a rank mismatch, shape/data
1382 /// length mismatch or shape/stride arithmetic overflow.
1383 pub fn from_host_vec_col_major(
1384 shape: impl tenferro_tensor_core::IntoRankShape<R>,
1385 data: Vec<T>,
1386 ) -> crate::Result<Self> {
1387 typed_host_tensor_from_vec_col_major(shape, data, "from_host_vec_col_major")
1388 }
1389
1390 /// Explicitly import row-major host values into column-major storage.
1391 ///
1392 /// Clones each input element once.
1393 ///
1394 /// # Examples
1395 /// ```
1396 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1397 /// let tensor = TypedTensor::<i32, Rank<2>, Host>::from_host_vec_row_major(
1398 /// [2, 3], vec![1, 2, 3, 4, 5, 6],
1399 /// )?;
1400 /// assert_eq!(tensor[&[1, 0]], 4);
1401 /// assert_eq!(tensor[&[0, 2]], 3);
1402 /// # Ok::<(), tenferro_tensor::Error>(())
1403 /// ```
1404 /// # Errors
1405 /// Returns [`crate::Error::Validation`] for a rank, shape-length or stride
1406 /// overflow, or when the shape product disagrees with the input length.
1407 pub fn from_host_vec_row_major(
1408 shape: impl tenferro_tensor_core::IntoRankShape<R>,
1409 data: Vec<T>,
1410 ) -> crate::Result<Self>
1411 where
1412 T: Clone,
1413 {
1414 let (shape, data) = row_major_reorder(shape, data, "from_host_vec_row_major")?;
1415 typed_host_tensor_from_vec_col_major(shape, data, "from_host_vec_row_major")
1416 }
1417
1418 /// Borrow the owned host elements.
1419 ///
1420 /// # Examples
1421 /// ```
1422 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1423 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1424 /// assert_eq!(tensor.as_slice(), &[1, 2]);
1425 /// # Ok::<(), tenferro_tensor::Error>(())
1426 /// ```
1427 pub fn as_slice(&self) -> &[T] {
1428 self.storage.data.as_slice()
1429 }
1430
1431 /// Alias of [`Self::as_slice`].
1432 ///
1433 /// # Examples
1434 ///
1435 /// ```
1436 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1437 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1438 /// assert_eq!(tensor.host_data(), &[1, 2]);
1439 /// # Ok::<(), tenferro_tensor::Error>(())
1440 /// ```
1441 pub fn host_data(&self) -> &[T] {
1442 self.as_slice()
1443 }
1444
1445 /// Exclusively borrow the owned host elements.
1446 ///
1447 /// # Examples
1448 ///
1449 /// ```
1450 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1451 /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1452 /// tensor.host_data_mut()[0] = 5;
1453 /// assert_eq!(tensor.as_slice(), &[5, 2]);
1454 /// # Ok::<(), tenferro_tensor::Error>(())
1455 /// ```
1456 pub fn host_data_mut(&mut self) -> &mut [T] {
1457 self.storage.data.as_mut_slice()
1458 }
1459
1460 /// Borrow one element by checked column-major multi-index.
1461 ///
1462 /// # Examples
1463 ///
1464 /// ```
1465 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1466 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 2], vec![1, 2, 3, 4])?;
1467 /// assert_eq!(tensor.get(&[1, 1])?, &4);
1468 /// assert!(tensor.get(&[2, 0]).is_err());
1469 /// # Ok::<(), tenferro_tensor::Error>(())
1470 /// ```
1471 ///
1472 /// # Errors
1473 /// Returns [`crate::Error::Validation`] for a wrong rank, an out-of-range
1474 /// coordinate or offset arithmetic overflow.
1475 pub fn get(&self, indices: &[usize]) -> crate::Result<&T> {
1476 let offset = self.linear_offset(indices)?;
1477 self.as_slice().get(offset).ok_or_else(|| {
1478 crate::Error::validation("TypedTensor::get", ValidationError::ViewOutOfBounds)
1479 })
1480 }
1481
1482 /// Exclusively borrow one element by checked column-major multi-index.
1483 ///
1484 /// # Examples
1485 ///
1486 /// ```
1487 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1488 /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1489 /// *tensor.get_mut(&[1])? = 9;
1490 /// assert_eq!(tensor.as_slice(), &[1, 9]);
1491 /// # Ok::<(), tenferro_tensor::Error>(())
1492 /// ```
1493 ///
1494 /// # Errors
1495 /// Returns [`crate::Error::Validation`] for a wrong rank, an out-of-range
1496 /// coordinate or offset arithmetic overflow.
1497 pub fn get_mut(&mut self, indices: &[usize]) -> crate::Result<&mut T> {
1498 let offset = self.linear_offset(indices)?;
1499 self.host_data_mut().get_mut(offset).ok_or_else(|| {
1500 crate::Error::validation("TypedTensor::get_mut", ValidationError::ViewOutOfBounds)
1501 })
1502 }
1503
1504 /// Consume this tensor and return the original host vector.
1505 ///
1506 /// # Examples
1507 ///
1508 /// ```
1509 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1510 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1511 /// assert_eq!(tensor.into_host_vec(), vec![1, 2]);
1512 /// # Ok::<(), tenferro_tensor::Error>(())
1513 /// ```
1514 pub fn into_host_vec(self) -> Vec<T> {
1515 self.storage.data.into_vec()
1516 }
1517
1518 /// Consume this tensor and return its shape and column-major host vector.
1519 ///
1520 /// # Examples
1521 ///
1522 /// ```
1523 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1524 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 1], vec![1, 2])?;
1525 /// let (shape, data) = tensor.into_vec_col_major();
1526 /// assert_eq!(shape, vec![2, 1]);
1527 /// assert_eq!(data, vec![1, 2]);
1528 /// # Ok::<(), tenferro_tensor::Error>(())
1529 /// ```
1530 pub fn into_vec_col_major(self) -> (Vec<usize>, Vec<T>) {
1531 let shape = self.shape().to_vec();
1532 (shape, self.into_host_vec())
1533 }
1534
1535 /// Make an explicit independent host copy with the same placement.
1536 ///
1537 /// # Examples
1538 /// ```
1539 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1540 /// let tensor = TypedTensor::<String, DynRank, Host>::from_host_vec_col_major(vec![1], vec!["a".into()])?;
1541 /// let copy = tensor.clone();
1542 /// assert_eq!(copy[&[0]], "a");
1543 /// # Ok::<(), tenferro_tensor::Error>(())
1544 /// ```
1545 pub fn duplicate(&self) -> Self
1546 where
1547 T: Clone,
1548 {
1549 let mut copy = typed_host_tensor_from_vec_col_major::<T, R>(
1550 self.shape.clone(),
1551 self.as_slice().to_vec(),
1552 "TypedTensor::duplicate",
1553 )
1554 .unwrap_or_else(|err| unreachable!("a validated host owner re-copies: {err}"));
1555 copy.placement = self.placement.clone();
1556 copy
1557 }
1558
1559 /// Move this host owner into the runtime union without copying or regrouping.
1560 ///
1561 /// # Examples
1562 /// ```
1563 /// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
1564 /// let host = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7])?;
1565 /// let dynamic: TypedTensor<i32, DynRank, Dynamic> = host.into_dynamic();
1566 /// assert_eq!(dynamic.host_data()?, &[7]);
1567 /// # Ok::<(), tenferro_tensor::Error>(())
1568 /// ```
1569 pub fn into_dynamic(self) -> TypedTensor<T, R, Dynamic> {
1570 TypedTensor {
1571 shape: self.shape,
1572 placement: self.placement,
1573 layout: self.layout,
1574 storage: DynamicStorage::Host(self.storage),
1575 }
1576 }
1577
1578 /// Borrow this host owner as a typed view.
1579 ///
1580 /// # Examples
1581 ///
1582 /// ```
1583 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1584 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1585 /// let view = tensor.as_view();
1586 /// assert_eq!(view.shape(), &[2]);
1587 /// assert_eq!(view.as_host_slice(), &[1, 2]);
1588 /// # Ok::<(), tenferro_tensor::Error>(())
1589 /// ```
1590 pub fn as_view(&self) -> TypedTensorView<'_, T, R, Host> {
1591 TypedTensorView {
1592 buffer: TensorStorageRef::Host(self.as_slice()),
1593 root: None,
1594 layout: self.layout(),
1595 placement: self.placement.clone(),
1596 _representation: std::marker::PhantomData,
1597 }
1598 }
1599
1600 /// Exclusively borrow this host owner as a mutable typed view.
1601 ///
1602 /// # Examples
1603 ///
1604 /// ```
1605 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1606 /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1607 /// tensor.as_view_mut().as_host_slice_mut()[1] = 4;
1608 /// assert_eq!(tensor.as_slice(), &[1, 4]);
1609 /// # Ok::<(), tenferro_tensor::Error>(())
1610 /// ```
1611 pub fn as_view_mut(&mut self) -> TypedTensorViewMut<'_, T, R, Host> {
1612 let layout = self.layout();
1613 let placement = self.placement.clone();
1614 TypedTensorViewMut {
1615 buffer: TensorStorageRefMut::Host(self.storage.data.as_mut_slice()),
1616 root: None,
1617 layout,
1618 placement,
1619 _representation: std::marker::PhantomData,
1620 }
1621 }
1622}
1623
1624impl<T: Clone, R: TensorRank> Clone for TypedTensor<T, R, Host> {
1625 fn clone(&self) -> Self {
1626 self.duplicate()
1627 }
1628}
1629
1630impl<T, R: TensorRank> std::ops::Index<&[usize]> for TypedTensor<T, R, Host> {
1631 type Output = T;
1632
1633 /// # Panics
1634 ///
1635 /// Panics when the index has the wrong rank or is out of bounds, like any
1636 /// other slice indexing. Use [`TypedTensor::get`] for the checked form.
1637 fn index(&self, indices: &[usize]) -> &T {
1638 match self.get(indices) {
1639 Ok(value) => value,
1640 Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1641 }
1642 }
1643}
1644
1645impl<T, R: TensorRank> std::ops::IndexMut<&[usize]> for TypedTensor<T, R, Host> {
1646 /// # Panics
1647 ///
1648 /// Panics when the index has the wrong rank or is out of bounds, like any
1649 /// other slice indexing. Use [`TypedTensor::get_mut`] for the checked form.
1650 fn index_mut(&mut self, indices: &[usize]) -> &mut T {
1651 match self.get_mut(indices) {
1652 Ok(value) => value,
1653 Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1654 }
1655 }
1656}
1657
1658impl<T, const N: usize> std::ops::Index<[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1659 type Output = T;
1660
1661 /// # Panics
1662 ///
1663 /// Panics when an index is out of bounds, like any other slice indexing.
1664 /// Use [`TypedTensor::get`] for the checked form.
1665 ///
1666 /// # Examples
1667 ///
1668 /// ```rust
1669 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1670 /// let tensor =
1671 /// TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1672 /// assert_eq!(tensor[[0, 1]], 3);
1673 /// # Ok::<(), tenferro_tensor::Error>(())
1674 /// ```
1675 fn index(&self, indices: [usize; N]) -> &T {
1676 match self.get(&indices) {
1677 Ok(value) => value,
1678 Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1679 }
1680 }
1681}
1682
1683impl<T, const N: usize> std::ops::Index<&[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1684 type Output = T;
1685
1686 /// The `&[usize; N]` spelling, which keeps a bare `&[i, j]` literal
1687 /// resolving as an integer index rather than forcing `usize` inference to
1688 /// choose between the slice and array spellings.
1689 ///
1690 /// # Panics
1691 ///
1692 /// Panics when an index is out of bounds, like any other slice indexing.
1693 /// Use [`TypedTensor::get`] for the checked form.
1694 ///
1695 /// # Examples
1696 ///
1697 /// ```rust
1698 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1699 /// let tensor =
1700 /// TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1701 /// assert_eq!(tensor[&[0, 1]], 3);
1702 /// # Ok::<(), tenferro_tensor::Error>(())
1703 /// ```
1704 fn index(&self, indices: &[usize; N]) -> &T {
1705 std::ops::Index::index(self, *indices)
1706 }
1707}
1708
1709impl<T, const N: usize> std::ops::IndexMut<[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1710 /// # Panics
1711 ///
1712 /// Panics when an index is out of bounds, like any other slice indexing.
1713 /// Use [`TypedTensor::get_mut`] for the checked form.
1714 ///
1715 /// # Examples
1716 ///
1717 /// ```rust
1718 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1719 /// let mut tensor =
1720 /// TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1721 /// tensor[[1, 0]] = 7;
1722 /// assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);
1723 /// # Ok::<(), tenferro_tensor::Error>(())
1724 /// ```
1725 fn index_mut(&mut self, indices: [usize; N]) -> &mut T {
1726 match self.get_mut(&indices) {
1727 Ok(value) => value,
1728 Err(err) => panic!("TypedTensor host index {indices:?} is invalid: {err}"),
1729 }
1730 }
1731}
1732
1733impl<T, const N: usize> std::ops::IndexMut<&[usize; N]> for TypedTensor<T, Rank<N>, Host> {
1734 /// # Panics
1735 ///
1736 /// Panics when an index is out of bounds, like any other slice indexing.
1737 /// Use [`TypedTensor::get_mut`] for the checked form.
1738 ///
1739 /// # Examples
1740 ///
1741 /// ```rust
1742 /// use tenferro_tensor::{Host, Rank, TypedTensor};
1743 /// let mut tensor =
1744 /// TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
1745 /// tensor[&[1, 0]] = 7;
1746 /// assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);
1747 /// # Ok::<(), tenferro_tensor::Error>(())
1748 /// ```
1749 fn index_mut(&mut self, indices: &[usize; N]) -> &mut T {
1750 std::ops::IndexMut::index_mut(self, *indices)
1751 }
1752}
1753
1754impl<T, const N: usize> std::ops::Index<[usize; N]> for TypedTensor<T, Rank<N>> {
1755 type Output = T;
1756
1757 /// # Panics
1758 ///
1759 /// Panics when an index is out of bounds or when the storage is not
1760 /// host-accessible, like any other slice indexing. Use
1761 /// [`TypedTensor::get`] for the checked form.
1762 ///
1763 /// # Examples
1764 ///
1765 /// ```rust
1766 /// use tenferro_tensor::{Rank, TypedTensor};
1767 /// let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
1768 /// assert_eq!(tensor[[0, 1]], 3.);
1769 /// # Ok::<(), tenferro_tensor::Error>(())
1770 /// ```
1771 fn index(&self, indices: [usize; N]) -> &T {
1772 match self.get(&indices) {
1773 Ok(value) => value,
1774 Err(err) => panic!("TypedTensor index {indices:?} is invalid: {err}"),
1775 }
1776 }
1777}
1778
1779impl<T, const N: usize> std::ops::IndexMut<[usize; N]> for TypedTensor<T, Rank<N>> {
1780 /// # Panics
1781 ///
1782 /// Panics when an index is out of bounds or when the storage is not
1783 /// host-accessible, like any other slice indexing. Use
1784 /// [`TypedTensor::get_mut`] for the checked form.
1785 ///
1786 /// # Examples
1787 ///
1788 /// ```rust
1789 /// use tenferro_tensor::{Rank, TypedTensor};
1790 /// let mut tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
1791 /// tensor[[1, 0]] = 7.;
1792 /// assert_eq!(tensor.as_slice()?, &[1., 7., 3., 4.]);
1793 /// # Ok::<(), tenferro_tensor::Error>(())
1794 /// ```
1795 fn index_mut(&mut self, indices: [usize; N]) -> &mut T {
1796 match self.get_mut(&indices) {
1797 Ok(value) => value,
1798 Err(err) => panic!("TypedTensor index {indices:?} is invalid: {err}"),
1799 }
1800 }
1801}
1802
1803/// Read mapping over a host slice, as one owning guard.
1804fn host_read_guard<T>(data: &[T]) -> HostReadGuard<'_, T> {
1805 HostReadGuard::new(data)
1806}
1807
1808/// Write mapping over an exclusive host slice, as one owning guard.
1809fn host_write_guard<T: Clone>(data: &mut [T]) -> HostWriteGuard<'_, T> {
1810 let len = data.len();
1811 HostWriteGuard::new(len, move |source| {
1812 data.clone_from_slice(source);
1813 Ok(())
1814 })
1815}
1816
1817/// Promote a plain host payload into a group-backed root without copying elements.
1818fn promote_host_group<T: TensorScalar, R: TensorRank>(
1819 shape: R::Shape,
1820 host: HostData<T>,
1821) -> crate::Result<OwnedTensorGroup<R>> {
1822 let recycler = host.recycler.clone();
1823 let mut group = OwnedTensorGroup::from_host_vec(shape, host.into_vec())?;
1824 if let Some(recycler) = recycler {
1825 group
1826 .group
1827 .set_host_recycler(group.allocation_index.index(), recycler)
1828 .map_err(|error| crate::Error::runtime_state_source("TypedTensor::promote", error))?;
1829 }
1830 Ok(group)
1831}
1832
1833impl<T, R: TensorRank> TypedTensor<T, R, Host> {
1834 /// Borrow the owned host elements through one owning read mapping.
1835 ///
1836 /// The guard retains the exclusive borrow of this owner, so no other access
1837 /// can overlap it while the mapping is alive.
1838 ///
1839 /// # Examples
1840 /// ```
1841 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1842 /// let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1843 /// let guard = tensor.map_read();
1844 /// assert_eq!(&guard[..], &[1, 2]);
1845 /// # Ok::<(), tenferro_tensor::Error>(())
1846 /// ```
1847 pub fn map_read(&self) -> HostReadGuard<'_, T> {
1848 host_read_guard(self.as_slice())
1849 }
1850
1851 /// Exclusively borrow the owned host elements through one owning write mapping.
1852 ///
1853 /// Publish data with [`HostWriteGuard::copy_from_slice`]; the mapping is
1854 /// released when the guard is dropped.
1855 ///
1856 /// # Examples
1857 /// ```
1858 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1859 /// let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
1860 /// tensor.map_write().copy_from_slice(&[3, 4]).unwrap();
1861 /// assert_eq!(tensor.as_slice(), &[3, 4]);
1862 /// # Ok::<(), tenferro_tensor::Error>(())
1863 /// ```
1864 pub fn map_write(&mut self) -> HostWriteGuard<'_, T>
1865 where
1866 T: Clone,
1867 {
1868 host_write_guard(self.host_data_mut())
1869 }
1870}
1871
1872impl<T: TensorScalar, R: TensorRank> TypedTensor<T, R, Host> {
1873 /// Promote this plain host owner into a group-backed owner.
1874 ///
1875 /// The payload is adopted as a provider root: no element is copied and a
1876 /// pooled return target survives the promotion.
1877 ///
1878 /// # Examples
1879 /// ```
1880 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
1881 /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
1882 /// let gpu = host.promote()?;
1883 /// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
1884 /// # Ok::<(), tenferro_tensor::Error>(())
1885 /// ```
1886 /// # Errors
1887 /// Returns [`crate::Error::RuntimeState`] when the new allocation group
1888 /// rejects the promoted root or its recycler.
1889 pub fn promote(self) -> crate::Result<TypedTensor<T, R, Gpu>> {
1890 let TypedTensor {
1891 shape,
1892 placement,
1893 layout,
1894 storage,
1895 } = self;
1896 let group = promote_host_group(shape.clone(), storage.data)?;
1897 Ok(TypedTensor {
1898 shape,
1899 placement,
1900 layout,
1901 storage: GroupStorage {
1902 group: Box::new(group),
1903 },
1904 })
1905 }
1906}
1907
1908impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
1909 /// Borrow host elements through one owning read mapping.
1910 ///
1911 /// # Examples
1912 ///
1913 /// ```
1914 /// use tenferro_tensor::TypedTensor;
1915 /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
1916 /// let guard = tensor.map_read()?;
1917 /// assert_eq!(&guard[..], &[1, 2]);
1918 /// # Ok::<(), tenferro_tensor::Error>(())
1919 /// ```
1920 ///
1921 /// # Errors
1922 /// Returns [`crate::Error::HostAccess`] with
1923 /// [`HostAccessError::Unsupported`] when the group's allocation is not
1924 /// host-accessible, or [`crate::Error::Validation`] with
1925 /// [`ValidationError::NonContiguousViewAsSlice`] or
1926 /// [`ValidationError::ViewOutOfBounds`] when the owner has no contiguous
1927 /// logical extent inside its backing storage.
1928 pub fn map_read(&self) -> crate::Result<HostReadGuard<'_, T>> {
1929 match &self.storage {
1930 DynamicStorage::Host(host) => Ok(host_read_guard(host.data.as_slice())),
1931 DynamicStorage::Group(core) => {
1932 // A root-preserving extraction exports only its descriptor
1933 // extent (#2023), so the mapping must not expose the root.
1934 let range = group_logical_range(&core.group, "TypedTensor::map_read")?;
1935 let data = core.group.host_slice::<T>()?;
1936 data.get(range).map(host_read_guard).ok_or_else(|| {
1937 crate::Error::validation(
1938 "TypedTensor::map_read",
1939 ValidationError::ViewOutOfBounds,
1940 )
1941 })
1942 }
1943 }
1944 }
1945
1946 /// Exclusively borrow host elements through one owning write mapping.
1947 ///
1948 /// Publish data with [`HostWriteGuard::copy_from_slice`].
1949 ///
1950 /// # Examples
1951 ///
1952 /// ```
1953 /// use tenferro_tensor::{Error, TypedTensor};
1954 /// let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
1955 /// tensor
1956 /// .map_write()?
1957 /// .copy_from_slice(&[3, 4])
1958 /// .map_err(|err| Error::host_access("map_write", err))?;
1959 /// assert_eq!(tensor.host_data()?, &[3, 4]);
1960 /// # Ok::<(), tenferro_tensor::Error>(())
1961 /// ```
1962 ///
1963 /// # Errors
1964 /// Returns [`crate::Error::HostAccess`] with
1965 /// [`HostAccessError::Unsupported`] when the group's allocation is not
1966 /// host-writable, or [`crate::Error::Validation`] with
1967 /// [`ValidationError::NonContiguousViewAsSlice`] or
1968 /// [`ValidationError::ViewOutOfBounds`] when the owner has no contiguous
1969 /// logical extent inside its backing storage.
1970 pub fn map_write(&mut self) -> crate::Result<HostWriteGuard<'_, T>>
1971 where
1972 T: Clone,
1973 {
1974 match &mut self.storage {
1975 DynamicStorage::Host(host) => Ok(host_write_guard(host.data.as_mut_slice())),
1976 DynamicStorage::Group(core) => {
1977 let range = group_logical_range(&core.group, "TypedTensor::map_write")?;
1978 let data = core.group.host_slice_mut::<T>()?;
1979 data.get_mut(range).map(host_write_guard).ok_or_else(|| {
1980 crate::Error::validation(
1981 "TypedTensor::map_write",
1982 ValidationError::ViewOutOfBounds,
1983 )
1984 })
1985 }
1986 }
1987 }
1988}
1989
1990impl<T, R: TensorRank> TypedTensor<T, R, Gpu> {
1991 /// Adopt a backend-owned buffer as a statically group-backed owner.
1992 ///
1993 /// A host buffer belongs to the [`Host`] representation; pass it to
1994 /// `TypedTensor::<T, R, Host>` instead of silently regrouping it here.
1995 ///
1996 /// # Examples
1997 /// ```
1998 /// use tenferro_tensor::{BackendStorageHandle, Placement, StorageBuffer, TypedTensor};
1999 /// let handle = BackendStorageHandle::<f32>::new_with_len(1, 2);
2000 /// let gpu = TypedTensor::<f32, tenferro_tensor::DynRank, tenferro_tensor::Gpu>::from_backend_buffer_col_major(
2001 /// vec![2],
2002 /// StorageBuffer::Backend(Box::new(handle)),
2003 /// Placement::default(),
2004 /// )?;
2005 /// assert!(gpu.is_backend_buffer());
2006 /// # Ok::<(), tenferro_tensor::Error>(())
2007 /// ```
2008 /// # Errors
2009 /// Returns [`crate::Error::Validation`] when the compact shape disagrees
2010 /// with the buffer length, [`crate::Error::RuntimeState`] for a host buffer,
2011 /// or a runtime-state error when the allocation group cannot be built.
2012 pub fn from_backend_buffer_col_major(
2013 shape: impl tenferro_tensor_core::IntoRankShape<R>,
2014 buffer: StorageBuffer<T>,
2015 placement: Placement,
2016 ) -> crate::Result<Self>
2017 where
2018 T: TensorScalar + Send + Sync + 'static,
2019 {
2020 let op = "TypedTensor::from_backend_buffer_col_major";
2021 let layout = try_compact_layout(shape, op)?;
2022 try_checked_shape_len(layout.shape(), buffer.len(), op)?;
2023 let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
2024 .map_err(|err| tensor_layout_error(op, err))?;
2025 match buffer {
2026 StorageBuffer::Host(_) => Err(crate::Error::runtime_state(
2027 op,
2028 "a host buffer is plain host storage; use TypedTensor::<T, R, Host>::from_vec_col_major",
2029 )),
2030 StorageBuffer::Backend(buffer) => {
2031 let group = OwnedTensorGroup::from_backend_buffer(
2032 group_shape.clone(),
2033 StorageBuffer::Backend(buffer),
2034 placement.clone(),
2035 )?;
2036 Ok(TypedTensor {
2037 shape: group_shape,
2038 placement,
2039 layout: stride_vec(layout.strides()),
2040 storage: GroupStorage {
2041 group: Box::new(group),
2042 },
2043 })
2044 }
2045 }
2046 }
2047
2048 /// Move this group-backed owner into the runtime union without rewriting it.
2049 ///
2050 /// # Examples
2051 ///
2052 /// ```
2053 /// use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
2054 /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
2055 /// let dynamic: TypedTensor<f64, DynRank, Dynamic> = gpu.into_dynamic();
2056 /// assert_eq!(dynamic.host_data()?, &[7.0]);
2057 /// # Ok::<(), tenferro_tensor::Error>(())
2058 /// ```
2059 pub fn into_dynamic(self) -> TypedTensor<T, R, Dynamic> {
2060 TypedTensor {
2061 shape: self.shape,
2062 placement: self.placement,
2063 layout: self.layout,
2064 storage: DynamicStorage::Group(self.storage),
2065 }
2066 }
2067
2068 /// Whether this group's descriptor names a non-CPU provider.
2069 ///
2070 /// # Examples
2071 ///
2072 /// ```
2073 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2074 /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
2075 /// // A promoted host payload stays on the CPU provider.
2076 /// assert!(!gpu.is_backend_buffer());
2077 /// # Ok::<(), tenferro_tensor::Error>(())
2078 /// ```
2079 pub fn is_backend_buffer(&self) -> bool {
2080 self.storage.group.is_backend_buffer()
2081 }
2082
2083 /// Borrow host elements when the group's allocation is host-accessible.
2084 ///
2085 /// # Examples
2086 ///
2087 /// ```
2088 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2089 /// let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
2090 /// assert_eq!(gpu.host_data()?, &[1.0, 2.0]);
2091 /// # Ok::<(), tenferro_tensor::Error>(())
2092 /// ```
2093 ///
2094 /// # Errors
2095 /// Returns [`crate::Error::RuntimeState`] for a device-only allocation and
2096 /// the non-compact-descriptor validation error for a strided owner.
2097 pub fn host_data(&self) -> crate::Result<&[T]> {
2098 let data = self.storage.group.host_slice::<T>()?;
2099 let range = group_logical_range(&self.storage.group, "TypedTensor::host_data")?;
2100 data.get(range).ok_or_else(|| {
2101 crate::Error::validation("TypedTensor::host_data", ValidationError::ViewOutOfBounds)
2102 })
2103 }
2104
2105 /// Exclusively borrow host elements when the group's allocation is host-accessible.
2106 ///
2107 /// # Examples
2108 ///
2109 /// ```
2110 /// use tenferro_tensor::{DynRank, Host, TypedTensor};
2111 /// let mut gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
2112 /// gpu.host_data_mut()?[0] = 3.0;
2113 /// assert_eq!(gpu.host_data()?, &[3.0, 2.0]);
2114 /// # Ok::<(), tenferro_tensor::Error>(())
2115 /// ```
2116 ///
2117 /// # Errors
2118 /// Returns [`crate::Error::RuntimeState`] for a device-only allocation and
2119 /// the non-compact-descriptor validation error for a strided owner.
2120 pub fn host_data_mut(&mut self) -> crate::Result<&mut [T]> {
2121 let range = group_logical_range(&self.storage.group, "TypedTensor::host_data_mut")?;
2122 let data = self.storage.group.host_slice_mut::<T>()?;
2123 data.get_mut(range).ok_or_else(|| {
2124 crate::Error::validation(
2125 "TypedTensor::host_data_mut",
2126 ValidationError::ViewOutOfBounds,
2127 )
2128 })
2129 }
2130
2131 /// Prepare this group-backed owner for one provider-native read binding.
2132 ///
2133 /// # Errors
2134 /// Returns a provider preparation error when the group has no device-read
2135 /// path for this layout.
2136 #[doc(hidden)]
2137 pub fn prepare_device_read(
2138 &self,
2139 op: &'static str,
2140 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
2141 where
2142 T: TensorScalar + 'static,
2143 {
2144 let layout = group_physical_layout(&self.storage.group);
2145 self.storage
2146 .group
2147 .prepare_device_read_for_layout::<T>(&layout)
2148 .map_err(|error| crate::Error::runtime_state_source(op, error))
2149 }
2150
2151 /// Prepare this group-backed owner for one provider-native write binding.
2152 ///
2153 /// # Errors
2154 /// Returns a provider preparation error when the group has no device-write
2155 /// path for this layout.
2156 #[doc(hidden)]
2157 pub fn prepare_device_write(
2158 &mut self,
2159 op: &'static str,
2160 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
2161 where
2162 T: TensorScalar + 'static,
2163 {
2164 let layout = group_physical_layout(&self.storage.group);
2165 self.storage
2166 .group
2167 .prepare_device_write_for_layout::<T>(&layout)
2168 .map_err(|error| crate::Error::runtime_state_source(op, error))
2169 }
2170}
2171
2172impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
2173 /// Checked narrowing to the statically host-owned representation.
2174 ///
2175 /// Fails without consuming ownership of the source tensor.
2176 ///
2177 /// # Examples
2178 /// ```
2179 /// use tenferro_tensor::TypedTensor;
2180 /// let dynamic = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![7])?;
2181 /// let host = dynamic.into_host().unwrap();
2182 /// assert_eq!(host.as_slice(), &[7]);
2183 /// # Ok::<(), tenferro_tensor::Error>(())
2184 /// ```
2185 /// # Errors
2186 /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is
2187 /// group-backed rather than plain host storage.
2188 #[allow(clippy::result_large_err)]
2189 pub fn into_host(self) -> Result<TypedTensor<T, R, Host>, ReinterpretError<Self>> {
2190 let TypedTensor {
2191 shape,
2192 placement,
2193 layout,
2194 storage,
2195 } = self;
2196 match storage {
2197 // This is the only way a value becomes `TypedTensor<_, _, Host>`, so it is where the
2198 // representation's one invariant is established: a host-backed tensor never carries a
2199 // device memory label. `TypedTensor::set_placement` refuses that label on host storage,
2200 // and the buffers that reach here are built with a matching one, so the narrowing only
2201 // has to move the payload across; an entry point that takes `Host` may skip a runtime
2202 // placement check (the CPU entry points narrow once, through `TensorRead::try_host`).
2203 DynamicStorage::Host(host) => Ok(TypedTensor {
2204 shape,
2205 placement,
2206 layout,
2207 storage: host,
2208 }),
2209 DynamicStorage::Group(group) => Err(ReinterpretError::new(
2210 TypedTensor {
2211 shape,
2212 placement,
2213 layout,
2214 storage: DynamicStorage::Group(group),
2215 },
2216 crate::Error::runtime_state(
2217 "TypedTensor::into_host",
2218 "the tensor is group-backed rather than plain host storage",
2219 ),
2220 )),
2221 }
2222 }
2223
2224 /// Checked narrowing to the group-backed representation.
2225 ///
2226 /// Fails without consuming ownership of the source tensor.
2227 ///
2228 /// # Examples
2229 ///
2230 /// ```
2231 /// use tenferro_tensor::{DynRank, Gpu, Host, TypedTensor};
2232 /// let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![2.0])?;
2233 /// let dynamic = host.promote()?.into_dynamic();
2234 /// let gpu: TypedTensor<f64, DynRank, Gpu> = dynamic.into_gpu().map_err(|f| f.into_parts().1)?;
2235 /// assert_eq!(gpu.host_data()?, &[2.0]);
2236 /// let plain = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![2.0])?;
2237 /// assert!(plain.into_gpu().is_err());
2238 /// # Ok::<(), tenferro_tensor::Error>(())
2239 /// ```
2240 ///
2241 /// # Errors
2242 /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is a
2243 /// plain host owner rather than a group-backed one.
2244 #[allow(clippy::result_large_err)]
2245 pub fn into_gpu(self) -> Result<TypedTensor<T, R, Gpu>, ReinterpretError<Self>> {
2246 let TypedTensor {
2247 shape,
2248 placement,
2249 layout,
2250 storage,
2251 } = self;
2252 match storage {
2253 DynamicStorage::Group(group) => Ok(TypedTensor {
2254 shape,
2255 placement,
2256 layout,
2257 storage: group,
2258 }),
2259 DynamicStorage::Host(host) => Err(ReinterpretError::new(
2260 TypedTensor {
2261 shape,
2262 placement,
2263 layout,
2264 storage: DynamicStorage::Host(host),
2265 },
2266 crate::Error::runtime_state(
2267 "TypedTensor::into_gpu",
2268 "the tensor is a plain host owner rather than group-backed storage",
2269 ),
2270 )),
2271 }
2272 }
2273}
2274
2275impl<T, R: TensorRank> TypedTensor<T, R, Dynamic> {
2276 /// Replace placement metadata without changing the storage buffer.
2277 ///
2278 /// Placement is metadata on top of the payload, and it must describe it:
2279 /// a plain host payload accepts [`MemoryKind::PinnedHost`],
2280 /// [`MemoryKind::UnpinnedHost`] or [`MemoryKind::Other`], a backend payload
2281 /// accepts [`MemoryKind::Device`], [`MemoryKind::Managed`] or
2282 /// [`MemoryKind::Other`], and the two contradicting pairs are refused.
2283 /// This is the only place a payload and a label meet after construction, so
2284 /// refusing here is what lets every consumer answer "is this host memory?"
2285 /// from the payload alone instead of re-reading the label.
2286 ///
2287 /// Only the runtime union can be relabelled. A [`Host`] or [`Gpu`] owner
2288 /// keeps the placement it was built with; move it through `into_dynamic()`
2289 /// first to relabel it.
2290 ///
2291 /// ```compile_fail
2292 /// use tenferro_tensor::{DynRank, Host, Placement, TypedTensor};
2293 /// let mut host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0])?;
2294 /// host.set_placement(Placement::default());
2295 /// # Ok::<(), tenferro_tensor::Error>(())
2296 /// ```
2297 ///
2298 /// # Examples
2299 ///
2300 /// ```rust
2301 /// use tenferro_tensor::{MemoryKind, Placement, TypedTensor};
2302 ///
2303 /// let mut t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
2304 /// t.set_placement(Placement {
2305 /// memory_kind: MemoryKind::PinnedHost,
2306 /// device: None,
2307 /// cpu_affinity: None,
2308 /// })?;
2309 /// assert_eq!(t.placement().memory_kind, MemoryKind::PinnedHost);
2310 /// # Ok::<(), tenferro_tensor::Error>(())
2311 /// ```
2312 ///
2313 /// # Errors
2314 ///
2315 /// Returns [`crate::Error::RuntimeState`] when `placement.memory_kind`
2316 /// names a memory class the payload cannot be, and stores nothing in that
2317 /// case.
2318 pub fn set_placement(&mut self, placement: Placement) -> crate::Result<()> {
2319 validate_placement_for_payload(
2320 "TypedTensor::set_placement",
2321 self.is_host_memory(),
2322 &placement,
2323 )?;
2324 self.placement = placement;
2325 Ok(())
2326 }
2327
2328 /// Replace only CPU routing/locality metadata without changing storage.
2329 ///
2330 /// Device, memory kind, backend allocation domain, and allocation identity
2331 /// remain unchanged.
2332 ///
2333 /// # Examples
2334 ///
2335 /// ```rust
2336 /// use tenferro_tensor::{CpuDomainId, TypedTensor};
2337 ///
2338 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0])?;
2339 /// tensor.set_cpu_affinity(Some(CpuDomainId::new(4)));
2340 /// assert_eq!(tensor.placement().cpu_affinity, Some(CpuDomainId::new(4)));
2341 /// # Ok::<(), tenferro_tensor::Error>(())
2342 /// ```
2343 pub fn set_cpu_affinity(&mut self, cpu_affinity: Option<CpuDomainId>) {
2344 self.placement.cpu_affinity = cpu_affinity;
2345 }
2346
2347 /// Whether this owner's payload is host-addressed memory.
2348 ///
2349 /// This is the one host/device answer in the workspace: the payload
2350 /// decides, never [`Placement::memory_kind`]. A plain host payload and a
2351 /// CPU-resident allocation group are host memory; a group backed by another
2352 /// provider is not. CPU and linalg entry points both ask this question, so
2353 /// a tensor cannot be host memory for one and device memory for the other.
2354 /// [`Self::set_placement`] refuses a label this answer contradicts, so the
2355 /// two never disagree.
2356 ///
2357 /// # Examples
2358 ///
2359 /// ```rust
2360 /// use tenferro_tensor::TypedTensor;
2361 ///
2362 /// let host = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
2363 /// assert!(host.is_host_memory());
2364 /// assert!(host.as_view().is_host_memory());
2365 /// # Ok::<(), tenferro_tensor::Error>(())
2366 /// ```
2367 pub fn is_host_memory(&self) -> bool {
2368 match &self.storage {
2369 DynamicStorage::Host(_) => true,
2370 // The same root fact `as_view()` reads to choose a host slice over a
2371 // root handle, so an owner and its views cannot answer differently.
2372 DynamicStorage::Group(core) => core.group.payload_is_host_memory(),
2373 }
2374 }
2375
2376 /// Layout that reflects the owned storage rather than the compact shape.
2377 ///
2378 /// [`Self::layout`] reports the compact construction layout. A
2379 /// root-preserving extraction may instead carry a nonzero descriptor offset
2380 /// and fewer logical elements than the backing root, so callers that
2381 /// canonicalize an owned tensor must use this accessor.
2382 pub(crate) fn physical_layout(&self) -> TensorLayout<R> {
2383 match &self.storage {
2384 DynamicStorage::Host(_) => TensorLayout::<R>::compact(self.shape.clone())
2385 .unwrap_or_else(|err| unreachable!("validated owned shape: {err}")),
2386 DynamicStorage::Group(core) => group_physical_layout(&core.group),
2387 }
2388 }
2389}
2390
2391/// Descriptor layout of a group-backed owner over its whole backing root.
2392///
2393/// The descriptor is the storage truth for a root-preserving extraction, so its
2394/// offset and backing length override the compact logical shape cached on the
2395/// tensor.
2396fn group_physical_layout<R: TensorRank>(core: &OwnedTensorGroup<R>) -> TensorLayout<R> {
2397 let descriptor = core
2398 .group
2399 .descriptor_layout(core.slot)
2400 .unwrap_or_else(|| unreachable!("a live group carries its descriptor layout"));
2401 let shape = R::shape_from_vec(shape_vec(descriptor.shape()))
2402 .unwrap_or_else(|err| unreachable!("validated descriptor shape: {err:?}"));
2403 let strides = R::strides_from_vec(stride_vec(descriptor.strides()))
2404 .unwrap_or_else(|err| unreachable!("validated descriptor strides: {err:?}"));
2405 let buffer_len = core
2406 .group
2407 .descriptor_backing_len(core.slot)
2408 .unwrap_or_else(|| unreachable!("a live group carries its root length"));
2409 TensorLayout::<R>::from_parts(shape, strides, descriptor.offset(), buffer_len)
2410 .unwrap_or_else(|err| unreachable!("validated descriptor layout: {err:?}"))
2411}
2412
2413/// Contiguous logical element range of a group-backed owner inside its root.
2414fn group_logical_range<R: TensorRank>(
2415 core: &OwnedTensorGroup<R>,
2416 op: &'static str,
2417) -> crate::Result<std::ops::Range<usize>> {
2418 core.group
2419 .descriptor_logical_range(core.slot)
2420 .ok_or_else(|| crate::Error::validation(op, ValidationError::NonContiguousViewAsSlice))
2421}
2422
2423impl<T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensor<T, R, D> {
2424 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2425 formatter
2426 .debug_struct("TypedTensor")
2427 .field("shape", &self.shape.as_ref())
2428 .field("placement", &self.placement)
2429 .finish_non_exhaustive()
2430 }
2431}
2432
2433impl<T, R: TensorRank, D: Representation> TypedTensor<T, R, D> {
2434 /// Number of elements in the tensor.
2435 ///
2436 /// # Examples
2437 ///
2438 /// ```rust
2439 /// use tenferro_tensor::TypedTensor;
2440 ///
2441 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2442 /// assert_eq!(t.n_elements(), 6);
2443 /// ```
2444 pub fn n_elements(&self) -> usize {
2445 // Invariant: owned tensor constructors validate compact shape length against buffer length.
2446 match try_shape_product(self.shape(), "TypedTensor::n_elements") {
2447 Ok(n) => n,
2448 Err(err) => {
2449 unreachable!("TypedTensor compact shape is validated at construction: {err}")
2450 }
2451 }
2452 }
2453
2454 /// Tensor shape.
2455 ///
2456 /// # Examples
2457 ///
2458 /// ```
2459 /// use tenferro_tensor::TypedTensor;
2460 ///
2461 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
2462 /// assert_eq!(t.shape(), &[2]);
2463 /// ```
2464 pub fn shape(&self) -> &[usize] {
2465 self.shape.as_ref()
2466 }
2467
2468 /// Column-major element strides of this compact tensor.
2469 ///
2470 /// The layout is cached at construction, so views of a tensor borrow it
2471 /// rather than computing (and allocating) it once per operation.
2472 ///
2473 /// # Examples
2474 ///
2475 /// ```
2476 /// use tenferro_tensor::TypedTensor;
2477 ///
2478 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2479 /// assert_eq!(t.strides(), &[1, 2]);
2480 /// ```
2481 pub fn strides(&self) -> &[isize] {
2482 &self.layout
2483 }
2484
2485 /// Tensor rank.
2486 ///
2487 /// # Examples
2488 ///
2489 /// ```
2490 /// use tenferro_tensor::TypedTensor;
2491 ///
2492 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2493 /// assert_eq!(t.rank(), 2);
2494 /// ```
2495 pub fn rank(&self) -> usize {
2496 self.shape().len()
2497 }
2498
2499 /// Tensor layout metadata.
2500 ///
2501 /// Owned typed tensors are always compact column-major layouts.
2502 ///
2503 /// # Examples
2504 ///
2505 /// ```
2506 /// use tenferro_tensor::TypedTensor;
2507 ///
2508 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
2509 /// assert_eq!(t.layout().strides(), &[1, 2]);
2510 /// ```
2511 pub fn layout(&self) -> TensorLayout<R> {
2512 TensorLayout::compact(self.shape.clone())
2513 .unwrap_or_else(|err| unreachable!("validated owned shape: {err}"))
2514 }
2515
2516 /// Return placement metadata for this tensor.
2517 ///
2518 /// # Examples
2519 ///
2520 /// ```
2521 /// use tenferro_tensor::{MemoryKind, TypedTensor};
2522 ///
2523 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
2524 /// assert_eq!(t.placement().memory_kind, MemoryKind::UnpinnedHost);
2525 /// ```
2526 pub fn placement(&self) -> &Placement {
2527 &self.placement
2528 }
2529
2530 /// Compute the checked compact column-major offset of an element.
2531 ///
2532 /// # Examples
2533 /// ```
2534 /// use tenferro_tensor::TypedTensor;
2535 /// let tensor = TypedTensor::<String>::from_vec_col_major([2, 3], vec![String::new(); 6])?;
2536 /// assert_eq!(tensor.linear_offset(&[1, 2])?, 5);
2537 /// # Ok::<(), tenferro_tensor::Error>(())
2538 /// ```
2539 /// # Errors
2540 /// Wrong rank, out-of-range coordinates or arithmetic overflow return
2541 /// [`crate::Error::Validation`].
2542 pub fn linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
2543 try_linear_offset_for_shape(self.shape(), indices, "TypedTensor::linear_offset")
2544 }
2545
2546 /// Consume this tensor and return its layout metadata.
2547 ///
2548 /// # Examples
2549 ///
2550 /// ```
2551 /// use tenferro_tensor::TypedTensor;
2552 ///
2553 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
2554 /// assert!(t.into_layout().is_compact_col_major().unwrap());
2555 /// ```
2556 pub fn into_layout(self) -> TensorLayout<R> {
2557 self.layout()
2558 }
2559
2560 /// Compute the physical element offset for a logical index.
2561 ///
2562 /// # Examples
2563 ///
2564 /// ```rust
2565 /// use tenferro_tensor::TypedTensor;
2566 ///
2567 /// let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
2568 /// assert_eq!(t.layout_linear_offset(&[1, 2])?, 5);
2569 /// # Ok::<(), tenferro_tensor::Error>(())
2570 /// ```
2571 /// # Errors
2572 ///
2573 /// Returns [`crate::Error::Validation`] with
2574 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
2575 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
2576 /// when an index is outside its axis extent, or
2577 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
2578 /// arithmetic overflows.
2579 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
2580 try_linear_offset_for_shape(self.shape(), indices, "TypedTensor::layout_linear_offset")
2581 }
2582
2583 /// Return whether this owned tensor is compact column-major.
2584 ///
2585 /// # Examples
2586 ///
2587 /// ```rust
2588 /// use tenferro_tensor::TypedTensor;
2589 ///
2590 /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2591 /// assert!(t.is_col_major_contiguous()?);
2592 /// # Ok::<(), tenferro_tensor::Error>(())
2593 /// ```
2594 /// # Errors
2595 ///
2596 /// Returns [`crate::Error::Validation`] with
2597 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
2598 /// compactness arithmetic overflows.
2599 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
2600 self.layout()
2601 .is_compact_col_major()
2602 .map_err(|err| tensor_layout_error("TypedTensor::is_col_major_contiguous", err))
2603 }
2604
2605 /// Return a compact string summary of this tensor's layout metadata.
2606 ///
2607 /// # Examples
2608 ///
2609 /// ```rust
2610 /// use tenferro_tensor::TypedTensor;
2611 ///
2612 /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2613 /// assert!(t.layout_summary().contains("shape=[2]"));
2614 /// # Ok::<(), tenferro_tensor::Error>(())
2615 /// ```
2616 pub fn layout_summary(&self) -> String {
2617 let layout = self.layout();
2618 layout_summary(self.shape(), layout.strides(), layout.offset())
2619 }
2620
2621 /// Assert this tensor is compact column-major.
2622 ///
2623 /// # Examples
2624 ///
2625 /// ```rust
2626 /// use tenferro_tensor::TypedTensor;
2627 ///
2628 /// let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
2629 /// t.assert_col_major_contiguous()?;
2630 /// # Ok::<(), tenferro_tensor::Error>(())
2631 /// ```
2632 /// # Errors
2633 ///
2634 /// Returns [`crate::Error::Validation`] with
2635 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
2636 /// compactness arithmetic overflows, or
2637 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
2638 /// tensor is not compact column-major.
2639 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
2640 let layout = self.layout();
2641 assert_layout_col_major_contiguous(
2642 self.is_col_major_contiguous()?,
2643 self.shape(),
2644 layout.strides(),
2645 layout.offset(),
2646 "TypedTensor::assert_col_major_contiguous",
2647 )
2648 }
2649}
2650
2651struct HostData<T> {
2652 buffer: StorageBuffer<T>,
2653 recycler: Option<std::sync::Weak<dyn crate::HostBufferRecycler<T>>>,
2654}
2655
2656impl<T> std::fmt::Debug for HostData<T> {
2657 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2658 formatter
2659 .debug_struct("HostData")
2660 .field("pooled", &self.recycler.is_some())
2661 .finish_non_exhaustive()
2662 }
2663}
2664
2665impl<T> HostData<T> {
2666 fn new(data: Vec<T>) -> Self {
2667 Self {
2668 buffer: StorageBuffer::Host(data),
2669 recycler: None,
2670 }
2671 }
2672
2673 fn into_vec(mut self) -> Vec<T> {
2674 self.recycler = None;
2675 match std::mem::replace(&mut self.buffer, StorageBuffer::Host(Vec::new())) {
2676 StorageBuffer::Host(data) => data,
2677 StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2678 }
2679 }
2680
2681 fn as_slice(&self) -> &[T] {
2682 match &self.buffer {
2683 StorageBuffer::Host(data) => data,
2684 StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2685 }
2686 }
2687
2688 fn as_mut_slice(&mut self) -> &mut [T] {
2689 match &mut self.buffer {
2690 StorageBuffer::Host(data) => data,
2691 StorageBuffer::Backend(_) => unreachable!("plain host storage is host-owned"),
2692 }
2693 }
2694}
2695
2696impl<T> Drop for HostData<T> {
2697 fn drop(&mut self) {
2698 let Some(recycler) = self.recycler.take().and_then(|weak| weak.upgrade()) else {
2699 return;
2700 };
2701 if let StorageBuffer::Host(data) = &mut self.buffer {
2702 recycler.recycle(std::mem::take(data));
2703 }
2704 }
2705}
2706
2707/// The sole owner handle for host tensors. The allocation group owns the
2708/// provider root; the descriptor slot carries only the logical view metadata.
2709pub(crate) struct OwnedTensorGroup<R: TensorRank> {
2710 group: AllocationGroup,
2711 slot: DescriptorSlot,
2712 allocation_index: AllocationSlot,
2713 // INVARIANT: this non-owning address points into the group root, whose host
2714 // vector cannot resize while the owning tensor is borrowed. It is stored as
2715 // `NonZeroUsize` rather than `NonNull<u8>`: the niche keeps the field at one
2716 // word, and unlike `NonNull` it preserves the `Send`/`Sync` auto traits the
2717 // typed tensor contract requires.
2718 host_ptr: Option<NonZeroUsize>,
2719 host_byte_len: usize,
2720 _rank: PhantomData<R>,
2721}
2722
2723impl<R: TensorRank> Debug for OwnedTensorGroup<R> {
2724 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2725 formatter
2726 .debug_struct("OwnedTensorGroup")
2727 .field("slot", &self.slot)
2728 .finish_non_exhaustive()
2729 }
2730}
2731
2732impl<R: TensorRank> OwnedTensorGroup<R> {
2733 fn from_host_vec<T: TensorScalar>(shape: R::Shape, data: Vec<T>) -> crate::Result<Self> {
2734 let (group, slot) = AllocationGroup::from_host_vec::<T, R>(shape, data)
2735 .map_err(|error| group_error("TypedTensor::from_host_vec", error))?;
2736 let allocation_index = group
2737 .allocation_index(slot)
2738 .map_err(|error| group_error("TypedTensor::from_host_vec", error))?;
2739 let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
2740 Ok(Self {
2741 group,
2742 slot,
2743 allocation_index,
2744 host_ptr,
2745 host_byte_len,
2746 _rank: PhantomData,
2747 })
2748 }
2749
2750 fn from_backend_buffer<T: TensorScalar + Send + Sync + 'static>(
2751 shape: R::Shape,
2752 buffer: StorageBuffer<T>,
2753 placement: Placement,
2754 ) -> crate::Result<Self> {
2755 let (mut group, slot) = AllocationGroup::from_backend_buffer::<T, R>(shape, buffer)
2756 .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2757 group
2758 .set_descriptor_placement(slot, placement)
2759 .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2760 let allocation_index = group
2761 .allocation_index(slot)
2762 .map_err(|error| group_error("TypedTensor::from_backend_buffer", error))?;
2763 let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
2764 Ok(Self {
2765 group,
2766 slot,
2767 allocation_index,
2768 host_ptr,
2769 host_byte_len,
2770 _rank: PhantomData,
2771 })
2772 }
2773
2774 fn view<T: TensorScalar>(&self) -> crate::Result<GroupReadView<'_, T, R>> {
2775 self.group
2776 .view(self.slot)
2777 .map_err(|error| group_error("TypedTensor::group_view", error))
2778 }
2779
2780 fn view_dyn<T: TensorScalar>(&self) -> crate::Result<GroupReadView<'_, T, DynRank>> {
2781 self.group
2782 .view(self.slot)
2783 .map_err(|error| group_error("TypedTensor::group_view", error))
2784 }
2785
2786 fn view_mut<T: TensorScalar>(&mut self) -> crate::Result<GroupWriteView<'_, T, R>> {
2787 self.group
2788 .view_mut(self.slot)
2789 .map_err(|error| group_error("TypedTensor::group_view_mut", error))
2790 }
2791
2792 fn view_mut_dyn<T: TensorScalar>(&mut self) -> crate::Result<GroupWriteView<'_, T, DynRank>> {
2793 self.group
2794 .view_mut(self.slot)
2795 .map_err(|error| group_error("TypedTensor::group_view_mut", error))
2796 }
2797
2798 fn prepare_device_read_for_layout<T: TensorScalar>(
2799 &self,
2800 layout: &TensorLayout<R>,
2801 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>> {
2802 self.group
2803 .prepare_device_read_for_layout::<T, R>(self.slot, layout)
2804 .map_err(|error| {
2805 crate::Error::runtime_state_source("TypedTensor::prepare_device_read", error)
2806 })
2807 }
2808
2809 fn prepare_device_write_for_layout<T: TensorScalar>(
2810 &mut self,
2811 layout: &TensorLayout<R>,
2812 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>> {
2813 self.group
2814 .prepare_device_write_for_layout::<T, R>(self.slot, layout)
2815 .map_err(|error| {
2816 crate::Error::runtime_state_source("TypedTensor::prepare_device_write", error)
2817 })
2818 }
2819
2820 fn host_buffer<T: 'static>(&self) -> Option<&StorageBuffer<T>> {
2821 self.group.host_buffer_at::<T>(self.allocation_index)
2822 }
2823
2824 fn host_slice<T>(&self) -> crate::Result<&[T]> {
2825 let Some(pointer) = self.host_ptr else {
2826 return Err(crate::Error::runtime_state(
2827 "TypedTensor::host_data",
2828 "backend storage cannot be borrowed as host data; download explicitly first",
2829 ));
2830 };
2831 let element_size = size_of::<T>();
2832 let Some(element_count) = self.host_byte_len.checked_div(element_size) else {
2833 return Err(crate::Error::runtime_state(
2834 "TypedTensor::host_data",
2835 "host allocation byte length is not aligned to the requested dtype",
2836 ));
2837 };
2838 // SAFETY: the pointer and byte length were captured from the unique
2839 // root's full host allocation; the root cannot resize while borrowed.
2840 Ok(unsafe { std::slice::from_raw_parts(pointer.get() as *const T, element_count) })
2841 }
2842
2843 fn host_slice_mut<T>(&mut self) -> crate::Result<&mut [T]> {
2844 let Some(pointer) = self.host_ptr else {
2845 return Err(crate::Error::runtime_state(
2846 "TypedTensor::host_data_mut",
2847 "backend storage cannot be borrowed as host data; download explicitly first",
2848 ));
2849 };
2850 let element_size = size_of::<T>();
2851 let Some(element_count) = self.host_byte_len.checked_div(element_size) else {
2852 return Err(crate::Error::runtime_state(
2853 "TypedTensor::host_data_mut",
2854 "host allocation byte length is not aligned to the requested dtype",
2855 ));
2856 };
2857 // SAFETY: the pointer and byte length were captured from the unique
2858 // root; this method has the only mutable borrow of that root.
2859 Ok(unsafe { std::slice::from_raw_parts_mut(pointer.get() as *mut T, element_count) })
2860 }
2861
2862 fn backend_buffer<T: 'static>(&self) -> Option<&StorageBuffer<T>> {
2863 self.group.backend_buffer::<T>(self.slot)
2864 }
2865
2866 fn backend_buffer_mut<T: 'static>(&mut self) -> Option<&mut StorageBuffer<T>> {
2867 self.group.backend_buffer_mut::<T>(self.slot)
2868 }
2869
2870 // INVARIANT: the failure carrier must return the unchanged group owner, so
2871 // the wide `(Self, Error)` pair is deliberate rather than a boxing bug.
2872 #[allow(clippy::result_large_err)]
2873 fn into_host_vec<T: 'static>(self) -> std::result::Result<Vec<T>, (Self, crate::Error)> {
2874 if self.backend_buffer::<T>().is_some() {
2875 return Err((
2876 self,
2877 crate::Error::runtime_state(
2878 "TypedTensor::into_host_vec",
2879 "backend buffers cannot be exported as host Vec; download the tensor first",
2880 ),
2881 ));
2882 }
2883 let OwnedTensorGroup {
2884 group,
2885 slot,
2886 allocation_index,
2887 host_ptr,
2888 host_byte_len,
2889 ..
2890 } = self;
2891 match group.into_host_vec::<T>(slot) {
2892 Ok(data) => Ok(data),
2893 Err((group, error)) => Err((
2894 OwnedTensorGroup {
2895 group,
2896 slot,
2897 allocation_index,
2898 host_ptr,
2899 host_byte_len,
2900 _rank: PhantomData,
2901 },
2902 crate::Error::runtime_state("TypedTensor::into_host_vec", error),
2903 )),
2904 }
2905 }
2906
2907 fn into_parts(self) -> (AllocationGroup, DescriptorSlot) {
2908 (self.group, self.slot)
2909 }
2910
2911 #[allow(clippy::result_large_err)]
2912 fn reinterpret<T: TensorScalar, U: TensorScalar>(
2913 self,
2914 shape: Vec<usize>,
2915 strides: Vec<isize>,
2916 offset: isize,
2917 ) -> Result<OwnedTensorGroup<DynRank>, (Self, crate::Error)> {
2918 let OwnedTensorGroup {
2919 group,
2920 slot,
2921 allocation_index,
2922 host_ptr,
2923 host_byte_len,
2924 _rank: _,
2925 } = self;
2926 match group.reinterpret_descriptor::<T, U>(slot, shape, strides, offset) {
2927 Ok(group) => Ok(OwnedTensorGroup {
2928 group,
2929 slot,
2930 allocation_index,
2931 host_ptr,
2932 host_byte_len,
2933 _rank: PhantomData,
2934 }),
2935 Err((group, error)) => Err((
2936 OwnedTensorGroup {
2937 group,
2938 slot,
2939 allocation_index,
2940 host_ptr,
2941 host_byte_len,
2942 _rank: PhantomData,
2943 },
2944 group_error("TypedTensor::reinterpret", error),
2945 )),
2946 }
2947 }
2948}
2949
2950fn host_metadata<T: TensorScalar>(
2951 group: &AllocationGroup,
2952 slot: DescriptorSlot,
2953) -> (Option<NonZeroUsize>, usize) {
2954 group
2955 .host_root_metadata::<T>(slot)
2956 .map_or((None, 0), |(pointer, byte_len)| {
2957 // INVARIANT: `host_root_metadata` reports the base address of the group's live
2958 // host allocation, which is non-null for any slice, empty included.
2959 (NonZeroUsize::new(pointer), byte_len)
2960 })
2961}
2962
2963fn group_error(op: &'static str, error: GroupError) -> crate::Error {
2964 crate::Error::runtime_state(op, error.to_string())
2965}
2966
2967/// Borrowed tensor buffer reference used by read-only typed views.
2968///
2969/// # Examples
2970///
2971/// ```rust
2972/// use tenferro_tensor::TensorStorageRef;
2973///
2974/// let data = [1_i32, 2];
2975/// let buffer = TensorStorageRef::Host(&data);
2976/// assert_eq!(buffer.len(), 2);
2977/// ```
2978#[derive(Debug)]
2979pub enum TensorStorageRef<'a, T> {
2980 Host(&'a [T]),
2981 Backend(&'a dyn BackendStorage<T>),
2982 #[doc(hidden)]
2983 Root(&'a dyn BackendAllocation),
2984}
2985
2986impl<T> Clone for TensorStorageRef<'_, T> {
2987 fn clone(&self) -> Self {
2988 match self {
2989 Self::Host(data) => Self::Host(data),
2990 Self::Backend(buffer) => Self::Backend(*buffer),
2991 Self::Root(allocation) => Self::Root(*allocation),
2992 }
2993 }
2994}
2995
2996impl<T: 'static> TensorStorageRef<'_, T> {
2997 /// Return the logical length of the backing allocation.
2998 ///
2999 /// # Examples
3000 ///
3001 /// ```rust
3002 /// use tenferro_tensor::TensorStorageRef;
3003 ///
3004 /// let data = [1_i32, 2, 3];
3005 /// assert_eq!(TensorStorageRef::Host(&data).len(), 3);
3006 /// ```
3007 pub fn len(&self) -> usize {
3008 match self {
3009 Self::Host(data) => data.len(),
3010 Self::Backend(buffer) => buffer.len(),
3011 Self::Root(allocation) => allocation
3012 .root_extent()
3013 .byte_len()
3014 .checked_div(std::mem::size_of::<T>())
3015 .unwrap_or(0),
3016 }
3017 }
3018
3019 /// Return whether the backing allocation is empty.
3020 ///
3021 /// # Examples
3022 ///
3023 /// ```rust
3024 /// use tenferro_tensor::TensorStorageRef;
3025 ///
3026 /// let data: [f64; 0] = [];
3027 /// assert!(TensorStorageRef::Host(&data).is_empty());
3028 /// ```
3029 pub fn is_empty(&self) -> bool {
3030 self.len() == 0
3031 }
3032}
3033
3034/// Borrowed tensor buffer reference used by mutable typed views.
3035///
3036/// Backend buffers can be represented for residency metadata, but this crate
3037/// does not expose host mutation for backend-native allocations.
3038///
3039/// # Examples
3040///
3041/// ```rust
3042/// use tenferro_tensor::TensorStorageRefMut;
3043///
3044/// let mut data = [1_i32, 2];
3045/// let buffer = TensorStorageRefMut::Host(&mut data);
3046/// assert_eq!(buffer.len(), 2);
3047/// ```
3048#[derive(Debug)]
3049pub enum TensorStorageRefMut<'a, T> {
3050 Host(&'a mut [T]),
3051 Backend(&'a mut dyn BackendStorage<T>),
3052}
3053
3054impl<T: 'static> TensorStorageRefMut<'_, T> {
3055 /// Return the logical length of the backing allocation.
3056 ///
3057 /// # Examples
3058 ///
3059 /// ```rust
3060 /// use tenferro_tensor::TensorStorageRefMut;
3061 ///
3062 /// let mut data = [1_i32, 2, 3];
3063 /// assert_eq!(TensorStorageRefMut::Host(&mut data).len(), 3);
3064 /// ```
3065 pub fn len(&self) -> usize {
3066 match self {
3067 Self::Host(data) => data.len(),
3068 Self::Backend(buffer) => buffer.len(),
3069 }
3070 }
3071
3072 /// Return whether the backing allocation is empty.
3073 ///
3074 /// # Examples
3075 ///
3076 /// ```rust
3077 /// use tenferro_tensor::TensorStorageRefMut;
3078 ///
3079 /// let mut data: [f64; 0] = [];
3080 /// assert!(TensorStorageRefMut::Host(&mut data).is_empty());
3081 /// ```
3082 pub fn is_empty(&self) -> bool {
3083 self.len() == 0
3084 }
3085}
3086
3087/// Read-only borrowed view of typed tensor storage with arbitrary strides.
3088///
3089/// `TypedTensorView` is the typed representation for layout-only tensor
3090/// transformations. It borrows an existing host or backend allocation and
3091/// carries a logical shape, strides, and an offset. Slicing, reshaping when
3092/// stride-compatible, and [`transpose_view`](TypedTensorView::transpose_view)
3093/// update only metadata and do not copy storage.
3094///
3095/// Materialize through [`TensorStructural::to_contiguous_read`](crate::TensorStructural::to_contiguous_read)
3096/// on the active backend session when a compact owned [`TypedTensor`] is
3097/// required. Use [`TypedTensorView::as_slice`] only when the current view is
3098/// contiguous in the requested layout.
3099///
3100/// # Examples
3101///
3102/// ```rust
3103/// use tenferro_tensor::{Rank, TypedTensorView};
3104///
3105/// let data = [1_i32, 2, 3, 4];
3106/// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &data)?;
3107/// assert_eq!(view.get(&[1, 1]), Some(&4));
3108/// # Ok::<(), tenferro_tensor::Error>(())
3109/// ```
3110/// Borrowed typed view of one tensor representation.
3111///
3112/// The buffer stays concrete on purpose: a generic-associated buffer would make
3113/// the projection invariant in `'a`, and the borrowed-read surface relies on
3114/// `TensorRead<'long>` shortening to `TensorRead<'short>`. `D` therefore marks
3115/// which representation produced the view - `Host` is only ever built from host
3116/// slices, with no retained region.
3117pub struct TypedTensorView<'a, T, R: TensorRank = DynRank, D: Representation = Dynamic> {
3118 buffer: TensorStorageRef<'a, T>,
3119 root: Option<GroupReadView<'a, T, R>>,
3120 layout: TensorLayout<R>,
3121 placement: Placement,
3122 _representation: std::marker::PhantomData<D>,
3123}
3124
3125impl<'a, T, R: TensorRank, D: Representation> Clone for TypedTensorView<'a, T, R, D> {
3126 fn clone(&self) -> Self {
3127 Self {
3128 buffer: self.buffer.clone(),
3129 root: self.root.clone(),
3130 layout: self.layout.clone(),
3131 placement: self.placement.clone(),
3132 _representation: std::marker::PhantomData,
3133 }
3134 }
3135}
3136
3137impl<'a, T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensorView<'a, T, R, D> {
3138 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3139 formatter
3140 .debug_struct("TypedTensorView")
3141 .field("shape", &self.layout.shape())
3142 .field("placement", &self.placement)
3143 .finish_non_exhaustive()
3144 }
3145}
3146
3147impl<'a, T: 'static> TypedTensorView<'a, T, DynRank> {
3148 /// Create a borrowed dynamic-rank view over compact column-major host data.
3149 ///
3150 /// # Examples
3151 ///
3152 /// ```rust
3153 /// use tenferro_tensor::TypedTensorView;
3154 ///
3155 /// let data = [1_i32, 2, 3, 4];
3156 /// let view = TypedTensorView::from_col_major(&[2, 2], &data)?;
3157 /// assert_eq!(view.strides(), &[1, 2]);
3158 /// # Ok::<(), tenferro_tensor::Error>(())
3159 /// ```
3160 ///
3161 /// # Errors
3162 ///
3163 /// Returns [`crate::Error::Validation`] with
3164 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when compact
3165 /// strides or reachable bounds overflow, or
3166 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3167 /// requested shape reaches beyond `data`.
3168 pub fn from_col_major(shape: &[usize], data: &'a [T]) -> crate::Result<Self> {
3169 let layout = TensorLayout::<DynRank>::compact(shape_vec(shape))
3170 .map_err(|err| tensor_layout_error("TypedTensorView::from_col_major", err))?;
3171 Self::from_buffer_ref(
3172 shape_vec(layout.shape()),
3173 stride_vec(layout.strides()),
3174 layout.offset(),
3175 TensorStorageRef::Host(data),
3176 default_placement(),
3177 "TypedTensorView::from_col_major",
3178 )
3179 }
3180
3181 /// Create a borrowed host view from explicit layout metadata.
3182 ///
3183 /// # Examples
3184 ///
3185 /// ```rust
3186 /// use tenferro_tensor::TypedTensorView;
3187 ///
3188 /// let data = [1_i32, 2, 3];
3189 /// let view = TypedTensorView::from_slice(vec![3], vec![-1], 2, &data)?;
3190 /// assert_eq!(view.get(&[2]), Some(&1));
3191 /// # Ok::<(), tenferro_tensor::Error>(())
3192 /// ```
3193 ///
3194 /// # Errors
3195 ///
3196 /// Returns [`crate::Error::Validation`] with
3197 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `shape` and
3198 /// `strides` have different ranks,
3199 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3200 /// reachable layout exceeds `data`, or
3201 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when layout
3202 /// arithmetic overflows.
3203 pub fn from_slice(
3204 shape: impl AsRef<[usize]>,
3205 strides: impl AsRef<[isize]>,
3206 offset: isize,
3207 data: &'a [T],
3208 ) -> crate::Result<Self> {
3209 Self::from_buffer_ref(
3210 shape_vec(shape.as_ref()),
3211 stride_vec(strides.as_ref()),
3212 offset,
3213 TensorStorageRef::Host(data),
3214 default_placement(),
3215 "TypedTensorView::from_slice",
3216 )
3217 }
3218}
3219
3220impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3221 /// Create a rank-generic borrowed host view from explicit layout metadata.
3222 ///
3223 /// # Examples
3224 ///
3225 /// ```rust
3226 /// use tenferro_tensor::{Rank, TypedTensorView};
3227 ///
3228 /// let data = [1_i32, 2, 3, 4];
3229 /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &data)?;
3230 /// assert_eq!(view.get(&[1, 1]), Some(&4));
3231 /// # Ok::<(), tenferro_tensor::Error>(())
3232 /// ```
3233 ///
3234 /// # Errors
3235 ///
3236 /// Returns [`crate::Error::Validation`] with
3237 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the typed
3238 /// rank does not match `shape` or `strides`,
3239 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
3240 /// reachable layout exceeds `data`, or
3241 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when layout
3242 /// arithmetic overflows.
3243 pub fn from_slice_ranked(
3244 shape: impl Into<R::Shape>,
3245 strides: impl Into<R::Strides>,
3246 offset: isize,
3247 data: &'a [T],
3248 ) -> crate::Result<Self> {
3249 Self::from_buffer_ref(
3250 shape,
3251 strides,
3252 offset,
3253 TensorStorageRef::Host(data),
3254 default_placement(),
3255 "TypedTensorView::from_slice_ranked",
3256 )
3257 }
3258}
3259
3260impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3261 fn from_buffer_ref(
3262 shape: impl Into<R::Shape>,
3263 strides: impl Into<R::Strides>,
3264 offset: isize,
3265 buffer: TensorStorageRef<'a, T>,
3266 placement: Placement,
3267 op: &'static str,
3268 ) -> crate::Result<Self> {
3269 let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
3270 .map_err(|err| tensor_layout_error(op, err))?;
3271 Ok(Self {
3272 buffer,
3273 root: None,
3274 layout,
3275 placement,
3276 _representation: std::marker::PhantomData,
3277 })
3278 }
3279}
3280
3281impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Dynamic> {
3282 /// The host elements this view borrows, or `None` when it borrows a
3283 /// backend buffer.
3284 ///
3285 /// The one match that decides host memory for borrowed views. Both
3286 /// [`Self::is_host_memory`] and [`Self::try_host`] read it, so the
3287 /// predicate and the narrowing cannot drift apart.
3288 fn host_elements(&self) -> Option<&'a [T]> {
3289 match &self.buffer {
3290 TensorStorageRef::Host(data) => Some(*data),
3291 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => None,
3292 }
3293 }
3294
3295 /// Whether this view borrows host-addressed memory.
3296 ///
3297 /// The same answer [`Self::try_host`] acts on and
3298 /// [`TypedTensor::is_host_memory`] gives for the owner: the borrowed payload
3299 /// decides, never [`Placement::memory_kind`].
3300 ///
3301 /// # Examples
3302 ///
3303 /// ```rust
3304 /// use tenferro_tensor::TypedTensor;
3305 ///
3306 /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
3307 /// assert!(tensor.as_view().is_host_memory());
3308 /// # Ok::<(), tenferro_tensor::Error>(())
3309 /// ```
3310 pub fn is_host_memory(&self) -> bool {
3311 self.host_elements().is_some()
3312 }
3313
3314 /// Checked narrowing of a borrowed view to the host representation.
3315 ///
3316 /// This is the one place a borrowed dynamic view becomes `Host`-marked: it
3317 /// succeeds exactly when the view borrows host elements (a plain host
3318 /// owner, a host slice, or a CPU-resident allocation group) and keeps the
3319 /// layout and the placement label. It runs [`Self::is_host_memory`], so a
3320 /// CPU entry point that narrows here and a CPU entry point that validates
3321 /// without narrowing reach the same verdict. A consumer that receives the
3322 /// result reads it through [`TypedTensorView::as_host_slice`] without a
3323 /// further check.
3324 ///
3325 /// # Examples
3326 ///
3327 /// ```rust
3328 /// use tenferro_tensor::TypedTensor;
3329 ///
3330 /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
3331 /// let host = tensor.as_view().try_host("example")?;
3332 /// assert_eq!(host.as_host_slice(), &[1.0, 2.0]);
3333 /// # Ok::<(), tenferro_tensor::Error>(())
3334 /// ```
3335 ///
3336 /// # Errors
3337 ///
3338 /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
3339 /// borrows backend (device) storage; download the tensor to host first.
3340 pub fn try_host(self, op: &'static str) -> crate::Result<TypedTensorView<'a, T, R, Host>> {
3341 let Some(data) = self.host_elements() else {
3342 return Err(crate::Error::runtime_state(
3343 op,
3344 "CPU backend received a backend buffer; download the tensor to host before CPU execution",
3345 ));
3346 };
3347 Ok(TypedTensorView {
3348 buffer: TensorStorageRef::Host(data),
3349 // A host-marked view carries no retained region: the borrow of
3350 // `data` is what keeps the owner alive for `'a`.
3351 root: None,
3352 layout: self.layout,
3353 placement: self.placement,
3354 _representation: std::marker::PhantomData,
3355 })
3356 }
3357}
3358
3359impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Host> {
3360 /// Widen a host-marked view to the runtime union without copying.
3361 ///
3362 /// # Examples
3363 ///
3364 /// ```rust
3365 /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3366 ///
3367 /// let data = [1_i32, 2];
3368 /// let host: TypedTensorView<'_, i32, DynRank, Host> =
3369 /// TypedTensorView::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &data)?;
3370 /// let dynamic = host.into_dynamic();
3371 /// assert_eq!(dynamic.host_storage()?, &[1, 2]);
3372 /// # Ok::<(), tenferro_tensor::Error>(())
3373 /// ```
3374 pub fn into_dynamic(self) -> TypedTensorView<'a, T, R, Dynamic> {
3375 TypedTensorView {
3376 buffer: self.buffer,
3377 root: self.root,
3378 layout: self.layout,
3379 placement: self.placement,
3380 _representation: std::marker::PhantomData,
3381 }
3382 }
3383}
3384
3385impl<'a, T: 'static, R: TensorRank> TypedTensorView<'a, T, R, Host> {
3386 /// Create a representation-marked view over an explicit host layout.
3387 ///
3388 /// A `Host`-marked view is only ever built from a host slice, so it carries
3389 /// no retained region and its host slice needs no runtime check.
3390 ///
3391 /// # Examples
3392 ///
3393 /// ```rust
3394 /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3395 ///
3396 /// let data = [1_i32, 2, 3, 4];
3397 /// let view: TypedTensorView<'_, i32, DynRank, Host> =
3398 /// TypedTensorView::from_host_slice(vec![2, 2].as_slice(), vec![1, 2].as_slice(), 0, &data)?;
3399 /// assert_eq!(view.as_host_slice(), &[1, 2, 3, 4]);
3400 /// # Ok::<(), tenferro_tensor::Error>(())
3401 /// ```
3402 ///
3403 /// # Errors
3404 ///
3405 /// Returns [`crate::Error::Validation`] with
3406 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `strides`
3407 /// has a different rank, or
3408 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] /
3409 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
3410 /// reachable layout leaves `data` or overflows.
3411 pub fn from_host_slice(
3412 shape: impl Into<R::Shape>,
3413 strides: impl Into<R::Strides>,
3414 offset: isize,
3415 data: &'a [T],
3416 ) -> crate::Result<Self> {
3417 // Built here rather than through the shared helper so that the Host
3418 // marker can only ever be paired with a host slice.
3419 let buffer = TensorStorageRef::Host(data);
3420 let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
3421 .map_err(|err| tensor_layout_error("TypedTensorView::from_host_slice", err))?;
3422 Ok(Self {
3423 buffer,
3424 root: None,
3425 layout,
3426 placement: default_placement(),
3427 _representation: std::marker::PhantomData,
3428 })
3429 }
3430
3431 /// Borrow the host elements without a runtime representation check.
3432 ///
3433 /// # Examples
3434 ///
3435 /// ```rust
3436 /// use tenferro_tensor::{DynRank, Host, TypedTensorView};
3437 ///
3438 /// let data = [1_i32, 2];
3439 /// let view: TypedTensorView<'_, i32, DynRank, Host> =
3440 /// TypedTensorView::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &data)?;
3441 /// assert_eq!(view.as_host_slice(), &[1, 2]);
3442 /// # Ok::<(), tenferro_tensor::Error>(())
3443 /// ```
3444 ///
3445 /// # Panics
3446 ///
3447 /// Panics only if a `Host`-marked view was built from non-host storage,
3448 /// which no constructor in this crate does.
3449 pub fn as_host_slice(&self) -> &'a [T] {
3450 match &self.buffer {
3451 TensorStorageRef::Host(data) => data,
3452 // INVARIANT: `Host`-marked views are constructed only by
3453 // `from_host_slice` and by `TypedTensor<_, _, Host>::as_view`.
3454 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3455 unreachable!("a Host-marked view always borrows host storage")
3456 }
3457 }
3458 }
3459}
3460
3461impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorView<'a, T, R, D> {
3462 /// Erase a borrowed view's rank and dtype for session dispatch without
3463 /// allocating tensor storage or promoting it into an allocation group.
3464 /// Common ranks use the existing inline shape and stride metadata.
3465 ///
3466 /// # Examples
3467 ///
3468 /// ```rust
3469 /// use tenferro_tensor::{Rank, TypedTensorView};
3470 /// let data = [1.0_f64, 2.0];
3471 /// let view = TypedTensorView::<_, Rank<1>>::from_slice_ranked([2], [1], 0, &data)?;
3472 /// let read = view.into_tensor_read()?;
3473 /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
3474 /// # Ok::<(), tenferro_tensor::Error>(())
3475 /// ```
3476 /// # Errors
3477 /// Returns [`crate::Error::Validation`] with
3478 /// [`ValidationError::IntegerOverflow`] for unrepresentable metadata or
3479 /// [`ValidationError::ViewOutOfBounds`] if the layout leaves its allocation.
3480 pub fn into_tensor_read(self) -> crate::Result<TensorRead<'a>>
3481 where
3482 T: TensorScalar,
3483 {
3484 let layout = TensorLayout::<DynRank>::from_parts(
3485 shape_vec(self.layout.shape()),
3486 stride_vec(self.layout.strides()),
3487 self.layout.offset(),
3488 self.buffer.len(),
3489 )
3490 .map_err(|err| tensor_layout_error("TypedTensorView::into_tensor_read", err))?;
3491 let view = TypedTensorView {
3492 buffer: self.buffer,
3493 root: self.root.map(GroupReadView::into_dyn),
3494 layout,
3495 placement: self.placement,
3496 _representation: std::marker::PhantomData,
3497 };
3498 Ok(TensorRead::from_view(T::tensor_view(view)))
3499 }
3500
3501 /// Return the logical shape.
3502 ///
3503 /// # Examples
3504 ///
3505 /// ```rust
3506 /// use tenferro_tensor::TypedTensorView;
3507 ///
3508 /// let data = [0_i32; 2];
3509 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3510 /// assert_eq!(view.shape(), &[2]);
3511 /// # Ok::<(), tenferro_tensor::Error>(())
3512 /// ```
3513 pub fn shape(&self) -> &[usize] {
3514 self.layout.shape()
3515 }
3516
3517 /// Return the logical rank carried by this view.
3518 ///
3519 /// # Examples
3520 ///
3521 /// ```
3522 /// use tenferro_tensor::TypedTensorView;
3523 ///
3524 /// let data = [0_i32; 6];
3525 /// let view = TypedTensorView::from_slice(vec![2, 3], vec![1, 2], 0, &data)?;
3526 /// assert_eq!(view.rank(), 2);
3527 /// # Ok::<(), tenferro_tensor::Error>(())
3528 /// ```
3529 pub fn rank(&self) -> usize {
3530 self.shape().len()
3531 }
3532
3533 /// Return strides in element units.
3534 ///
3535 /// # Examples
3536 ///
3537 /// ```rust
3538 /// use tenferro_tensor::TypedTensorView;
3539 ///
3540 /// let data = [0_i32; 2];
3541 /// let view = TypedTensorView::from_slice(vec![2], vec![-1], 1, &data)?;
3542 /// assert_eq!(view.strides(), &[-1]);
3543 /// # Ok::<(), tenferro_tensor::Error>(())
3544 /// ```
3545 pub fn strides(&self) -> &[isize] {
3546 self.layout.strides()
3547 }
3548
3549 /// Return the physical element offset.
3550 ///
3551 /// # Examples
3552 ///
3553 /// ```rust
3554 /// use tenferro_tensor::TypedTensorView;
3555 ///
3556 /// let data = [1_i32, 2];
3557 /// let view = TypedTensorView::from_slice(vec![1], vec![1], 1, &data)?;
3558 /// assert_eq!(view.offset(), 1);
3559 /// # Ok::<(), tenferro_tensor::Error>(())
3560 /// ```
3561 pub fn offset(&self) -> isize {
3562 self.layout.offset()
3563 }
3564
3565 /// Return the borrowed host storage backing this view.
3566 ///
3567 /// This exposes the entire backing host allocation, not just the logical
3568 /// slice covered by this view. Use [`TypedTensorView::as_slice`] when the
3569 /// caller needs the contiguous logical region instead.
3570 ///
3571 /// # Examples
3572 ///
3573 /// ```rust
3574 /// use tenferro_tensor::TypedTensorView;
3575 ///
3576 /// let data = [1_i32, 2];
3577 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3578 /// assert_eq!(view.host_storage()?, &[1, 2]);
3579 /// # Ok::<(), tenferro_tensor::Error>(())
3580 /// ```
3581 ///
3582 /// # Errors
3583 ///
3584 /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
3585 /// buffer; backend storage must be downloaded before host inspection.
3586 pub fn host_storage(&self) -> crate::Result<&'a [T]> {
3587 match &self.buffer {
3588 TensorStorageRef::Host(data) => Ok(data),
3589 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3590 Err(crate::Error::runtime_state(
3591 "TypedTensorView::host_storage",
3592 "backend buffers cannot expose host storage; download explicitly first",
3593 ))
3594 }
3595 }
3596 }
3597
3598 /// Return the number of logical elements in this view.
3599 ///
3600 /// # Examples
3601 ///
3602 /// ```rust
3603 /// use tenferro_tensor::TypedTensorView;
3604 ///
3605 /// let data = [0_i32; 6];
3606 /// let view = TypedTensorView::from_slice(vec![2, 3], vec![1, 2], 0, &data)?;
3607 /// assert_eq!(view.n_elements(), 6);
3608 /// # Ok::<(), tenferro_tensor::Error>(())
3609 /// ```
3610 pub fn n_elements(&self) -> usize {
3611 // Invariant: public view constructors validate logical element count.
3612 match checked_view_element_count(self.shape(), "TypedTensorView::n_elements") {
3613 Ok(n) => n,
3614 Err(err) => {
3615 unreachable!("TypedTensorView layout shape is validated at construction: {err}")
3616 }
3617 }
3618 }
3619
3620 /// Return layout metadata for this view.
3621 ///
3622 /// # Examples
3623 ///
3624 /// ```rust
3625 /// use tenferro_tensor::TypedTensorView;
3626 ///
3627 /// let data = [1_i32, 2];
3628 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3629 /// assert!(view.layout().is_compact_col_major().unwrap());
3630 /// # Ok::<(), tenferro_tensor::Error>(())
3631 /// ```
3632 pub fn layout(&self) -> &TensorLayout<R> {
3633 &self.layout
3634 }
3635
3636 /// Return placement metadata for this view.
3637 ///
3638 /// # Examples
3639 ///
3640 /// ```rust
3641 /// use tenferro_tensor::{MemoryKind, TypedTensorView};
3642 ///
3643 /// let data = [1_i32];
3644 /// let view = TypedTensorView::from_slice(vec![1], vec![1], 0, &data)?;
3645 /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
3646 /// # Ok::<(), tenferro_tensor::Error>(())
3647 /// ```
3648 pub fn placement(&self) -> &Placement {
3649 &self.placement
3650 }
3651
3652 /// Return the backend allocation for backend integrations.
3653 #[doc(hidden)]
3654 pub fn backing_len(&self) -> usize {
3655 self.buffer.len()
3656 }
3657
3658 /// Return the backend allocation for backend integrations.
3659 #[doc(hidden)]
3660 pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>> {
3661 match &self.buffer {
3662 TensorStorageRef::Host(_) => None,
3663 TensorStorageRef::Backend(buffer) => Some(*buffer),
3664 TensorStorageRef::Root(_) => {
3665 self.root
3666 .as_ref()?
3667 .backend_buffer()
3668 .and_then(|buffer| match buffer {
3669 StorageBuffer::Host(_) => None,
3670 StorageBuffer::Backend(buffer) => Some(buffer.as_ref()),
3671 })
3672 }
3673 }
3674 }
3675
3676 /// Return the backend allocation with the view's storage lifetime.
3677 ///
3678 /// [`Self::backend_buffer`] keeps the borrow of the view itself, which is
3679 /// enough to start a provider mapping but not to carry a shared-memory
3680 /// borrow out of this call. A CPU admission point needs the latter, so this
3681 /// accessor resolves through the root the view already holds instead.
3682 #[doc(hidden)]
3683 pub fn shared_backend_storage(&self) -> Option<&'a dyn BackendStorage<T>>
3684 where
3685 T: 'static,
3686 {
3687 match &self.buffer {
3688 TensorStorageRef::Host(_) => None,
3689 TensorStorageRef::Backend(buffer) => Some(*buffer),
3690 TensorStorageRef::Root(allocation) => {
3691 let allocation = allocation
3692 .as_any()
3693 .downcast_ref::<crate::storage::BackendStorageAllocation<T>>()?;
3694 match allocation.buffer() {
3695 StorageBuffer::Host(_) => None,
3696 StorageBuffer::Backend(buffer) => Some(buffer.as_ref()),
3697 }
3698 }
3699 }
3700 }
3701
3702 /// Return the provider family for this view when it is backend-owned.
3703 #[doc(hidden)]
3704 pub fn backend_family(&self) -> Option<&'static str>
3705 where
3706 T: TensorScalar + 'static,
3707 {
3708 self.root
3709 .as_ref()
3710 .and_then(|root| {
3711 root.backend_allocation()
3712 .map(|_| root.provider_kind().as_str())
3713 })
3714 .or_else(|| self.backend_buffer().map(|buffer| buffer.backend_family()))
3715 }
3716
3717 /// Return the shared allocation domain for this view when backend-owned.
3718 #[doc(hidden)]
3719 pub fn allocation_domain(&self) -> Option<AllocationDomainId>
3720 where
3721 T: TensorScalar + 'static,
3722 {
3723 self.root
3724 .as_ref()
3725 .and_then(|root| root.backend_identity().map(|(domain, _)| domain))
3726 .or_else(|| {
3727 self.backend_buffer()
3728 .and_then(|buffer| buffer.allocation_domain())
3729 })
3730 }
3731
3732 /// Return the physical allocation identity for this view when backend-owned.
3733 #[doc(hidden)]
3734 pub fn allocation_id(&self) -> Option<AllocationId>
3735 where
3736 T: TensorScalar + 'static,
3737 {
3738 self.root
3739 .as_ref()
3740 .and_then(|root| root.backend_identity().map(|(_, id)| id))
3741 .or_else(|| {
3742 self.backend_buffer()
3743 .and_then(|buffer| buffer.allocation_id())
3744 })
3745 }
3746
3747 /// Prepare this backend view for one provider-native read binding.
3748 #[doc(hidden)]
3749 pub fn prepare_device_read(
3750 &self,
3751 op: &'static str,
3752 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
3753 where
3754 T: TensorScalar + 'static,
3755 {
3756 if let Some(root) = &self.root {
3757 return root
3758 .prepare_device_read_for_layout(&self.layout)
3759 .map_err(|error| crate::Error::runtime_state_source(op, error));
3760 }
3761 let buffer = self.backend_buffer().ok_or_else(|| {
3762 crate::Error::runtime_state_source(
3763 op,
3764 crate::AccessError::Unsupported { backend: "host" },
3765 )
3766 })?;
3767 prepare_backend_access(buffer, &self.layout, op)
3768 }
3769
3770 /// Compute the physical element offset for a logical index.
3771 ///
3772 /// # Examples
3773 ///
3774 /// ```rust
3775 /// use tenferro_tensor::TypedTensorView;
3776 ///
3777 /// let data = [1_i32, 2, 3];
3778 /// let view = TypedTensorView::from_slice(vec![3], vec![-1], 2, &data)?;
3779 /// assert_eq!(view.linear_offset(&[2]), Some(0));
3780 /// # Ok::<(), tenferro_tensor::Error>(())
3781 /// ```
3782 pub fn linear_offset(&self, indices: &[usize]) -> Option<usize> {
3783 checked_view_offset(self.shape(), self.strides(), self.offset(), indices)
3784 }
3785
3786 /// Compute the physical element offset for a logical index, returning a typed error.
3787 ///
3788 /// # Examples
3789 ///
3790 /// ```rust
3791 /// use tenferro_tensor::TypedTensorView;
3792 ///
3793 /// let data = [1_i32, 2, 3];
3794 /// let view = TypedTensorView::from_slice([3], [-1], 2, &data)?;
3795 /// assert_eq!(view.layout_linear_offset(&[2])?, 0);
3796 /// # Ok::<(), tenferro_tensor::Error>(())
3797 /// ```
3798 ///
3799 /// # Errors
3800 ///
3801 /// Returns [`crate::Error::Validation`] with
3802 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
3803 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
3804 /// when an index is outside its axis extent, or
3805 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
3806 /// arithmetic overflows.
3807 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
3808 checked_view_offset_result(
3809 self.shape(),
3810 self.strides(),
3811 self.offset(),
3812 indices,
3813 "TypedTensorView::layout_linear_offset",
3814 )
3815 }
3816
3817 /// Return whether this view is compact column-major.
3818 ///
3819 /// # Examples
3820 ///
3821 /// ```rust
3822 /// use tenferro_tensor::TypedTensorView;
3823 ///
3824 /// let data = [1_i32, 2];
3825 /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3826 /// assert!(view.is_col_major_contiguous()?);
3827 /// # Ok::<(), tenferro_tensor::Error>(())
3828 /// ```
3829 ///
3830 /// # Errors
3831 ///
3832 /// Returns [`crate::Error::Validation`] with
3833 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] if compactness
3834 /// arithmetic overflows.
3835 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
3836 self.layout
3837 .is_compact_col_major()
3838 .map_err(|err| tensor_layout_error("TypedTensorView::is_col_major_contiguous", err))
3839 }
3840
3841 /// Return a compact string summary of this view's layout metadata.
3842 ///
3843 /// # Examples
3844 ///
3845 /// ```rust
3846 /// use tenferro_tensor::TypedTensorView;
3847 ///
3848 /// let data = [1_i32, 2];
3849 /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3850 /// assert!(view.layout_summary().contains("shape=[2]"));
3851 /// # Ok::<(), tenferro_tensor::Error>(())
3852 /// ```
3853 pub fn layout_summary(&self) -> String {
3854 layout_summary(self.shape(), self.strides(), self.offset())
3855 }
3856
3857 /// Assert this view is compact column-major.
3858 ///
3859 /// # Examples
3860 ///
3861 /// ```rust
3862 /// use tenferro_tensor::TypedTensorView;
3863 ///
3864 /// let data = [1_i32, 2];
3865 /// let view = TypedTensorView::from_slice([2], [1], 0, &data)?;
3866 /// view.assert_col_major_contiguous()?;
3867 /// # Ok::<(), tenferro_tensor::Error>(())
3868 /// ```
3869 ///
3870 /// # Errors
3871 ///
3872 /// Returns [`crate::Error::Validation`] with
3873 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
3874 /// compactness arithmetic overflows, or
3875 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
3876 /// view is not compact column-major.
3877 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
3878 assert_layout_col_major_contiguous(
3879 self.is_col_major_contiguous()?,
3880 self.shape(),
3881 self.strides(),
3882 self.offset(),
3883 "TypedTensorView::assert_col_major_contiguous",
3884 )
3885 }
3886
3887 /// Borrow one host element by logical index.
3888 ///
3889 /// Returns `None` for out-of-bounds indices and backend buffers.
3890 ///
3891 /// # Examples
3892 ///
3893 /// ```rust
3894 /// use tenferro_tensor::TypedTensorView;
3895 ///
3896 /// let data = [1_i32, 2];
3897 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3898 /// assert_eq!(view.get(&[1]), Some(&2));
3899 /// # Ok::<(), tenferro_tensor::Error>(())
3900 /// ```
3901 pub fn get(&self, indices: &[usize]) -> Option<&T> {
3902 let offset = self.linear_offset(indices)?;
3903 match &self.buffer {
3904 TensorStorageRef::Host(data) => data.get(offset),
3905 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => None,
3906 }
3907 }
3908
3909 /// Borrow the contiguous host slice covered by this view.
3910 ///
3911 /// Returns an explicit error for backend buffers and for non-contiguous
3912 /// layouts. This method never downloads or materializes backend data.
3913 ///
3914 /// # Examples
3915 ///
3916 /// ```rust
3917 /// use tenferro_tensor::TypedTensorView;
3918 ///
3919 /// let data = [1_i32, 2, 3];
3920 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 1, &data)?;
3921 /// assert_eq!(view.as_slice()?, &[2, 3]);
3922 /// # Ok::<(), tenferro_tensor::Error>(())
3923 /// ```
3924 ///
3925 /// # Errors
3926 ///
3927 /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
3928 /// buffer, [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]
3929 /// when the layout is not compact column-major,
3930 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the view
3931 /// offset is negative, or [`crate::Error::Validation`] with
3932 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] or
3933 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
3934 /// requested host range is invalid.
3935 pub fn as_slice(&self) -> crate::Result<&'a [T]> {
3936 let data = match &self.buffer {
3937 TensorStorageRef::Host(data) => data,
3938 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
3939 return Err(crate::Error::runtime_state(
3940 "TypedTensorView::as_slice",
3941 "backend buffers cannot be inspected as host slices; download explicitly first",
3942 ))
3943 }
3944 };
3945 contiguous_layout_slice(self.layout(), data, "TypedTensorView::as_slice")
3946 }
3947
3948 /// Borrow the compact logical region through a scoped host mapping.
3949 ///
3950 /// Backend integrations must validate placement and allocation-domain ownership
3951 /// before mapping. The guard cannot escape the callback; no transfer is performed.
3952 ///
3953 /// # Errors
3954 ///
3955 /// Returns a host-access or provider-preparation error when mapping fails,
3956 /// or a validation/unsupported error for a non-contiguous or invalid layout.
3957 #[doc(hidden)]
3958 pub fn with_host_read<U>(&self, f: impl FnOnce(&[T]) -> U) -> crate::Result<U>
3959 where
3960 T: TensorScalar + 'static,
3961 {
3962 const OP: &str = "TypedTensorView::with_host_read";
3963 if !self.is_col_major_contiguous()? {
3964 return Err(crate::Error::unsupported(
3965 OP,
3966 "host guard access requires a compact descriptor",
3967 ));
3968 }
3969 if let Some(buffer) = self.backend_buffer() {
3970 let guard = buffer
3971 .map_read()
3972 .map_err(|error| crate::Error::host_access(OP, error))?;
3973 return Ok(f(contiguous_layout_slice(self.layout(), &guard, OP)?));
3974 }
3975 if let Some(root) = &self.root {
3976 let prepared = root
3977 .prepare_host_read_for_layout(self.layout())
3978 .map_err(|error| crate::Error::runtime_state_source(OP, error))?;
3979 let slice = prepared.as_slice().ok_or_else(|| {
3980 crate::Error::unsupported(OP, "host guard access requires a compact descriptor")
3981 })?;
3982 return Ok(f(slice));
3983 }
3984 Ok(f(self.as_slice()?))
3985 }
3986
3987 /// Explicitly duplicate a compact host view into a new owner.
3988 ///
3989 /// Backend views require an explicit provider canonicalization or download
3990 /// boundary; this method never transfers or materializes them implicitly.
3991 ///
3992 /// # Examples
3993 ///
3994 /// ```
3995 /// use tenferro_tensor::TypedTensorView;
3996 ///
3997 /// let data = [1_i32, 2];
3998 /// let view = TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?;
3999 /// let copy = view.duplicate()?;
4000 /// assert_eq!(copy.as_slice()?, &[1, 2]);
4001 /// # Ok::<(), tenferro_tensor::Error>(())
4002 /// ```
4003 ///
4004 /// # Errors
4005 ///
4006 /// Returns [`crate::Error::HostAccess`] or
4007 /// [`ValidationError::NonContiguousViewAsSlice`] when the view is backend
4008 /// owned or not contiguous, and [`ValidationError::InvalidArgument`] when
4009 /// the static-rank shape cannot be reconstructed.
4010 pub fn duplicate(&self) -> crate::Result<TypedTensor<T, R>>
4011 where
4012 T: Clone,
4013 {
4014 let data = self.as_slice()?.to_vec();
4015 let shape = R::shape_from_vec(shape_vec(self.shape()))
4016 .map_err(|err| tensor_layout_error("TypedTensorView::duplicate", err))?;
4017 let mut tensor = TypedTensor::from_vec_col_major(shape, data)?;
4018 tensor.set_placement(self.placement.clone())?;
4019 Ok(tensor)
4020 }
4021
4022 /// Explicitly copy a host view, including strided/offset views, to a compact owner.
4023 ///
4024 /// # Examples
4025 /// ```
4026 /// use tenferro_tensor::{Rank, TypedTensorView};
4027 /// let storage = [1, 4, 2, 5, 3, 6];
4028 /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked(
4029 /// [2, 3], [1, 2], 0, &storage,
4030 /// )?;
4031 /// let transposed = view.transpose_view([1, 0])?;
4032 /// assert_eq!(transposed.to_col_major()?.as_slice()?, &[1, 2, 3, 4, 5, 6]);
4033 /// # Ok::<(), tenferro_tensor::Error>(())
4034 /// ```
4035 /// # Errors
4036 /// Backend-only storage returns [`crate::Error::RuntimeState`]; invalid
4037 /// layout or rank conversion returns [`crate::Error::Validation`].
4038 pub fn to_col_major(&self) -> crate::Result<TypedTensor<T, R>>
4039 where
4040 T: Clone,
4041 {
4042 let data = self.host_storage()?;
4043 let mut coordinates = shape_vec_zeros(self.shape().len());
4044 let element_count = self.n_elements();
4045 let mut copied = Vec::with_capacity(element_count);
4046 for _ in 0..element_count {
4047 let offset = self.layout_linear_offset(&coordinates)?;
4048 let value = data.get(offset).ok_or_else(|| {
4049 crate::Error::validation(
4050 "TypedTensorView::to_col_major",
4051 ValidationError::ViewOutOfBounds,
4052 )
4053 })?;
4054 copied.push(value.clone());
4055 for axis in 0..coordinates.len() {
4056 coordinates[axis] += 1;
4057 if coordinates[axis] < self.shape()[axis] {
4058 break;
4059 }
4060 coordinates[axis] = 0;
4061 }
4062 }
4063 let shape = R::shape_from_vec(shape_vec(self.shape()))
4064 .map_err(|err| tensor_layout_error("TypedTensorView::to_col_major", err))?;
4065 let mut tensor = TypedTensor::from_vec_col_major(shape, copied)?;
4066 tensor.set_placement(self.placement.clone())?;
4067 Ok(tensor)
4068 }
4069
4070 /// Return a metadata-only axis permutation.
4071 ///
4072 /// # Examples
4073 ///
4074 /// ```rust
4075 /// use tenferro_tensor::{Rank, TypedTensorView};
4076 ///
4077 /// let data = [1_i32, 2, 3, 4, 5, 6];
4078 /// let view = TypedTensorView::<_, Rank<2>>::from_slice_ranked([2, 3], [1, 2], 0, &data)?;
4079 /// let transposed = view.transpose_view([1, 0])?;
4080 /// assert_eq!(transposed.shape(), &[3, 2]);
4081 /// # Ok::<(), tenferro_tensor::Error>(())
4082 /// ```
4083 /// # Errors
4084 ///
4085 /// Returns [`crate::Error::Validation`] with
4086 /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
4087 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
4088 /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
4089 /// not a valid permutation of the view rank.
4090 pub fn transpose_view(&self, axes: impl AsRef<[usize]>) -> crate::Result<Self> {
4091 let layout = self
4092 .layout
4093 .transpose_view(axes)
4094 .map_err(|err| tensor_layout_error("TypedTensorView::transpose_view", err))?;
4095 Ok(Self {
4096 buffer: self.buffer.clone(),
4097 root: self.root.clone(),
4098 layout,
4099 placement: self.placement.clone(),
4100 _representation: std::marker::PhantomData,
4101 })
4102 }
4103
4104 /// Return a metadata-only slice using one [`StridedSliceSpec`] per axis.
4105 ///
4106 /// # Examples
4107 ///
4108 /// ```rust
4109 /// use tenferro_tensor::{StridedSliceSpec, TypedTensorView};
4110 ///
4111 /// let data = [1_i32, 2, 3];
4112 /// let view = TypedTensorView::from_slice(vec![3], vec![1], 0, &data)?;
4113 /// let reversed = view.slice_view(&[StridedSliceSpec::reverse()])?;
4114 /// assert_eq!(reversed.get(&[0]), Some(&3));
4115 /// # Ok::<(), tenferro_tensor::Error>(())
4116 /// ```
4117 /// # Errors
4118 ///
4119 /// Returns [`crate::Error::Validation`] with
4120 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the slice
4121 /// count differs from the view rank,
4122 /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
4123 /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
4124 /// invalid slice, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
4125 /// for slice arithmetic overflow, or
4126 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4127 /// resulting layout exceeds the backing buffer.
4128 pub fn slice_view(&self, slices: &[StridedSliceSpec]) -> crate::Result<Self> {
4129 let specs = core_slice_specs(slices, self.shape(), "TypedTensorView::slice_view")?;
4130 let layout = self
4131 .layout
4132 .slice_view(specs, self.buffer.len())
4133 .map_err(|err| tensor_layout_error("TypedTensorView::slice_view", err))?;
4134 Ok(Self {
4135 buffer: self.buffer.clone(),
4136 root: self.root.clone(),
4137 layout,
4138 placement: self.placement.clone(),
4139 _representation: std::marker::PhantomData,
4140 })
4141 }
4142
4143 /// Return a metadata-only slice along one axis.
4144 ///
4145 /// # Examples
4146 ///
4147 /// ```rust
4148 /// use tenferro_tensor::{StridedSliceSpec, TypedTensorView};
4149 ///
4150 /// let data = [1_i32, 2, 3, 4];
4151 /// let view = TypedTensorView::from_slice(vec![2, 2], vec![1, 2], 0, &data)?;
4152 /// assert_eq!(view.slice_axis_view(1, StridedSliceSpec::reverse())?.get(&[0, 0]), Some(&3));
4153 /// # Ok::<(), tenferro_tensor::Error>(())
4154 /// ```
4155 /// # Errors
4156 ///
4157 /// Returns [`crate::Error::Validation`] with
4158 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`] when `axis`
4159 /// is outside the view rank, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
4160 /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
4161 /// invalid slice, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
4162 /// for slice arithmetic overflow, or
4163 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4164 /// resulting layout exceeds the backing buffer.
4165 pub fn slice_axis_view(&self, axis: usize, slice: StridedSliceSpec) -> crate::Result<Self> {
4166 let slices = slice_axis_specs(
4167 self.shape().len(),
4168 axis,
4169 slice,
4170 "TypedTensorView::slice_axis_view",
4171 )?;
4172 self.slice_view(&slices)
4173 }
4174
4175 /// Return a metadata-only dynamic-rank reshape for contiguous column-major views.
4176 ///
4177 /// # Examples
4178 ///
4179 /// ```rust
4180 /// use tenferro_tensor::TypedTensorView;
4181 ///
4182 /// let data = [1_i32, 2, 3, 4];
4183 /// let view = TypedTensorView::from_slice(vec![2, 2], vec![1, 2], 0, &data)?;
4184 /// assert_eq!(view.reshape_view(&[4])?.shape(), &[4]);
4185 /// # Ok::<(), tenferro_tensor::Error>(())
4186 /// ```
4187 /// # Errors
4188 ///
4189 /// Returns [`crate::Error::Validation`] with
4190 /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
4191 /// the source is not compact column-major,
4192 /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
4193 /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
4194 /// records the counts) when element counts differ,
4195 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for shape
4196 /// arithmetic overflow, or
4197 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4198 /// reshaped view exceeds the backing buffer.
4199 pub fn reshape_view(
4200 &self,
4201 shape: &[usize],
4202 ) -> crate::Result<TypedTensorView<'a, T, DynRank, D>> {
4203 let layout = reshape_layout_dyn(
4204 &self.layout,
4205 shape,
4206 self.buffer.len(),
4207 "TypedTensorView::reshape_view",
4208 )?;
4209 Ok(TypedTensorView {
4210 buffer: self.buffer.clone(),
4211 root: self.root.as_ref().map(GroupReadView::clone_dyn),
4212 layout,
4213 placement: self.placement.clone(),
4214 _representation: std::marker::PhantomData,
4215 })
4216 }
4217}
4218
4219impl<'a, R: TensorRank> TypedTensorView<'a, Complex32, R> {
4220 /// Borrow this complex view as an interleaved real view without copying.
4221 ///
4222 /// The result has dynamic rank because reinterpretation prepends the
4223 /// component axis `[2, ...]`. Only `Complex32 <-> f32` is sealed in this
4224 /// API; this is representation reinterpretation, not numeric conversion.
4225 ///
4226 /// # Examples
4227 ///
4228 /// ```
4229 /// use tenferro_tensor::{Complex32, TypedTensorView};
4230 ///
4231 /// let data = [Complex32::new(1.0, 2.0)];
4232 /// let view = TypedTensorView::from_col_major(&[1], &data)?;
4233 /// let real = view.as_real_view()?;
4234 /// assert_eq!(real.shape(), &[2, 1]);
4235 /// assert_eq!(real.as_slice()?, &[1.0_f32, 2.0]);
4236 /// # Ok::<(), tenferro_tensor::Error>(())
4237 /// ```
4238 ///
4239 /// # Errors
4240 ///
4241 /// Returns an error when the view layout is not a valid sealed
4242 /// representation or when backend reinterpretation is unsupported.
4243 pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'a, f32, DynRank>> {
4244 let op = "TypedTensorView::as_real_view";
4245 validate_representation_pair(op, DType::C32, DType::F32)?;
4246 let layout = reinterpret_complex_to_real_layout(
4247 self.shape(),
4248 self.strides(),
4249 self.offset(),
4250 self.buffer.len(),
4251 op,
4252 )?;
4253 let buffer = match &self.buffer {
4254 TensorStorageRef::Host(data) => {
4255 TensorStorageRef::Host(reinterpret_host_slice::<Complex32, f32>(data, op)?)
4256 }
4257 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4258 return Err(crate::Error::unsupported(
4259 op,
4260 "backend representation reinterpretation is enabled by the provider phases",
4261 ))
4262 }
4263 };
4264 Ok(TypedTensorView {
4265 buffer,
4266 root: None,
4267 layout,
4268 placement: self.placement.clone(),
4269 _representation: std::marker::PhantomData,
4270 })
4271 }
4272}
4273
4274impl<'a, R: TensorRank> TypedTensorView<'a, Complex64, R> {
4275 /// Borrow this complex view as an interleaved real view without copying.
4276 ///
4277 /// The result has dynamic rank because reinterpretation prepends the
4278 /// component axis `[2, ...]`. Only `Complex64 <-> f64` is sealed in this
4279 /// API; this is representation reinterpretation, not numeric conversion.
4280 ///
4281 /// # Examples
4282 ///
4283 /// ```
4284 /// use tenferro_tensor::{Complex64, TypedTensorView};
4285 ///
4286 /// let data = [Complex64::new(1.0, 2.0)];
4287 /// let view = TypedTensorView::from_col_major(&[1], &data)?;
4288 /// let real = view.as_real_view()?;
4289 /// assert_eq!(real.shape(), &[2, 1]);
4290 /// assert_eq!(real.as_slice()?, &[1.0_f64, 2.0]);
4291 /// # Ok::<(), tenferro_tensor::Error>(())
4292 /// ```
4293 ///
4294 /// # Errors
4295 ///
4296 /// Returns an error when the view layout is not a valid sealed
4297 /// representation or when backend reinterpretation is unsupported.
4298 pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'a, f64, DynRank>> {
4299 let op = "TypedTensorView::as_real_view";
4300 validate_representation_pair(op, DType::C64, DType::F64)?;
4301 let layout = reinterpret_complex_to_real_layout(
4302 self.shape(),
4303 self.strides(),
4304 self.offset(),
4305 self.buffer.len(),
4306 op,
4307 )?;
4308 let buffer = match &self.buffer {
4309 TensorStorageRef::Host(data) => {
4310 TensorStorageRef::Host(reinterpret_host_slice::<Complex64, f64>(data, op)?)
4311 }
4312 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4313 return Err(crate::Error::unsupported(
4314 op,
4315 "backend representation reinterpretation is enabled by the provider phases",
4316 ))
4317 }
4318 };
4319 Ok(TypedTensorView {
4320 buffer,
4321 root: None,
4322 layout,
4323 placement: self.placement.clone(),
4324 _representation: std::marker::PhantomData,
4325 })
4326 }
4327}
4328
4329impl<'a, R: TensorRank> TypedTensorView<'a, f32, R> {
4330 /// Borrow this interleaved real view as a complex view without copying.
4331 ///
4332 /// The source must have a leading extent and stride of `2` and `1`, and
4333 /// every remaining stride plus the offset must be divisible by `2`.
4334 ///
4335 /// # Examples
4336 ///
4337 /// ```
4338 /// use tenferro_tensor::{Complex32, TypedTensorView};
4339 ///
4340 /// let data = [1.0_f32, 2.0];
4341 /// let view = TypedTensorView::from_col_major(&[2, 1], &data)?;
4342 /// let complex = view.as_complex_view()?;
4343 /// assert_eq!(complex.shape(), &[1]);
4344 /// assert_eq!(complex.as_slice()?, &[Complex32::new(1.0, 2.0)]);
4345 /// # Ok::<(), tenferro_tensor::Error>(())
4346 /// ```
4347 ///
4348 /// # Errors
4349 ///
4350 /// Returns an error when the view layout is not a valid sealed
4351 /// representation or when backend reinterpretation is unsupported.
4352 pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'a, Complex32, DynRank>> {
4353 let op = "TypedTensorView::as_complex_view";
4354 validate_representation_pair(op, DType::F32, DType::C32)?;
4355 let layout = reinterpret_real_to_complex_layout(
4356 self.shape(),
4357 self.strides(),
4358 self.offset(),
4359 self.buffer.len(),
4360 op,
4361 )?;
4362 let buffer = match &self.buffer {
4363 TensorStorageRef::Host(data) => {
4364 TensorStorageRef::Host(reinterpret_host_slice::<f32, Complex32>(data, op)?)
4365 }
4366 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4367 return Err(crate::Error::unsupported(
4368 op,
4369 "backend representation reinterpretation is enabled by the provider phases",
4370 ))
4371 }
4372 };
4373 Ok(TypedTensorView {
4374 buffer,
4375 root: None,
4376 layout,
4377 placement: self.placement.clone(),
4378 _representation: std::marker::PhantomData,
4379 })
4380 }
4381}
4382
4383impl<'a, R: TensorRank> TypedTensorView<'a, f64, R> {
4384 /// Borrow this interleaved real view as a complex view without copying.
4385 ///
4386 /// The source must have a leading extent and stride of `2` and `1`, and
4387 /// every remaining stride plus the offset must be divisible by `2`.
4388 ///
4389 /// # Examples
4390 ///
4391 /// ```
4392 /// use tenferro_tensor::{Complex64, TypedTensorView};
4393 ///
4394 /// let data = [1.0_f64, 2.0];
4395 /// let view = TypedTensorView::from_col_major(&[2, 1], &data)?;
4396 /// let complex = view.as_complex_view()?;
4397 /// assert_eq!(complex.shape(), &[1]);
4398 /// assert_eq!(complex.as_slice()?, &[Complex64::new(1.0, 2.0)]);
4399 /// # Ok::<(), tenferro_tensor::Error>(())
4400 /// ```
4401 ///
4402 /// # Errors
4403 ///
4404 /// Returns an error when the view layout is not a valid sealed
4405 /// representation or when backend reinterpretation is unsupported.
4406 pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'a, Complex64, DynRank>> {
4407 let op = "TypedTensorView::as_complex_view";
4408 validate_representation_pair(op, DType::F64, DType::C64)?;
4409 let layout = reinterpret_real_to_complex_layout(
4410 self.shape(),
4411 self.strides(),
4412 self.offset(),
4413 self.buffer.len(),
4414 op,
4415 )?;
4416 let buffer = match &self.buffer {
4417 TensorStorageRef::Host(data) => {
4418 TensorStorageRef::Host(reinterpret_host_slice::<f64, Complex64>(data, op)?)
4419 }
4420 TensorStorageRef::Backend(_) | TensorStorageRef::Root(_) => {
4421 return Err(crate::Error::unsupported(
4422 op,
4423 "backend representation reinterpretation is enabled by the provider phases",
4424 ))
4425 }
4426 };
4427 Ok(TypedTensorView {
4428 buffer,
4429 root: None,
4430 layout,
4431 placement: self.placement.clone(),
4432 _representation: std::marker::PhantomData,
4433 })
4434 }
4435}
4436
4437/// Mutable borrowed view of typed tensor storage with arbitrary strides.
4438///
4439/// # Examples
4440///
4441/// ```rust
4442/// use tenferro_tensor::TypedTensorViewMut;
4443///
4444/// let mut data = [1_i32, 2, 3];
4445/// let mut view = TypedTensorViewMut::from_slice(vec![3], vec![-1], 2, &mut data)?;
4446/// *view.get_mut(&[2]).unwrap() = 10;
4447/// assert_eq!(view.as_read_only().get(&[2]), Some(&10));
4448/// # Ok::<(), tenferro_tensor::Error>(())
4449/// ```
4450/// Exclusive typed view of one tensor representation.
4451///
4452/// As with [`TypedTensorView`], the buffer stays concrete so the view keeps its
4453/// lifetime covariance, and `D` marks which representation produced the view.
4454pub struct TypedTensorViewMut<'a, T, R: TensorRank = DynRank, D: Representation = Dynamic> {
4455 buffer: TensorStorageRefMut<'a, T>,
4456 root: Option<GroupWriteView<'a, T, R>>,
4457 layout: TensorLayout<R>,
4458 placement: Placement,
4459 _representation: std::marker::PhantomData<D>,
4460}
4461
4462impl<'a, T, R: TensorRank, D: Representation> std::fmt::Debug for TypedTensorViewMut<'a, T, R, D> {
4463 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4464 formatter
4465 .debug_struct("TypedTensorViewMut")
4466 .field("shape", &self.layout.shape())
4467 .field("placement", &self.placement)
4468 .finish_non_exhaustive()
4469 }
4470}
4471
4472/// Pair of mutable tensor views returned by disjoint multi-slice operations.
4473///
4474/// # Examples
4475///
4476/// ```rust
4477/// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut, TypedTensorViewMutSplit};
4478///
4479/// let mut data = [1_i32, 2, 3, 4];
4480/// let mut view = TypedTensorViewMut::from_slice(vec![4], vec![1], 0, &mut data)?;
4481/// let pair: TypedTensorViewMutSplit<'_, i32> = view
4482/// .try_multi_slice_mut(
4483/// &[StridedSliceSpec::new(0, Some(2), 1)],
4484/// &[StridedSliceSpec::new(2, Some(4), 1)],
4485/// )
4486/// ?
4487/// .unwrap();
4488/// assert_eq!(pair.0.shape(), &[2]);
4489/// assert_eq!(pair.1.shape(), &[2]);
4490/// # Ok::<(), tenferro_tensor::Error>(())
4491/// ```
4492pub type TypedTensorViewMutSplit<'a, T, R = DynRank> =
4493 (TypedTensorViewMut<'a, T, R>, TypedTensorViewMut<'a, T, R>);
4494
4495impl<'a, T: 'static> TypedTensorViewMut<'a, T, DynRank> {
4496 /// Create a mutable dynamic-rank view over compact column-major host data.
4497 ///
4498 /// # Examples
4499 ///
4500 /// ```rust
4501 /// use tenferro_tensor::TypedTensorViewMut;
4502 ///
4503 /// let mut data = [1_i32, 2, 3, 4];
4504 /// let view = TypedTensorViewMut::from_col_major(&[2, 2], &mut data)?;
4505 /// assert_eq!(view.strides(), &[1, 2]);
4506 /// # Ok::<(), tenferro_tensor::Error>(())
4507 /// ```
4508 /// # Errors
4509 ///
4510 /// Returns [`crate::Error::Validation`] with
4511 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
4512 /// shape or offset arithmetic overflow, or
4513 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4514 /// compact shape reaches beyond `data`.
4515 pub fn from_col_major(shape: &[usize], data: &'a mut [T]) -> crate::Result<Self> {
4516 let layout = TensorLayout::<DynRank>::compact(shape_vec(shape))
4517 .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_col_major", err))?;
4518 Self::from_buffer_ref_mut(
4519 shape_vec(layout.shape()),
4520 stride_vec(layout.strides()),
4521 layout.offset(),
4522 TensorStorageRefMut::Host(data),
4523 default_placement(),
4524 "TypedTensorViewMut::from_col_major",
4525 )
4526 }
4527
4528 /// Create a mutable host view from explicit layout metadata.
4529 ///
4530 /// Layouts where distinct logical elements can alias the same physical
4531 /// element are rejected.
4532 ///
4533 /// # Examples
4534 ///
4535 /// ```rust
4536 /// use tenferro_tensor::TypedTensorViewMut;
4537 ///
4538 /// let mut data = [1_i32, 2];
4539 /// assert!(TypedTensorViewMut::from_slice(vec![2], vec![0], 0, &mut data).is_err());
4540 /// ```
4541 /// # Errors
4542 ///
4543 /// Returns [`crate::Error::Validation`] with
4544 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `shape` and
4545 /// `strides` have different ranks,
4546 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4547 /// layout reaches beyond `data`,
4548 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
4549 /// logical elements alias, or
4550 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
4551 /// arithmetic overflow.
4552 pub fn from_slice(
4553 shape: impl AsRef<[usize]>,
4554 strides: impl AsRef<[isize]>,
4555 offset: isize,
4556 data: &'a mut [T],
4557 ) -> crate::Result<Self> {
4558 Self::from_buffer_ref_mut(
4559 shape_vec(shape.as_ref()),
4560 stride_vec(strides.as_ref()),
4561 offset,
4562 TensorStorageRefMut::Host(data),
4563 default_placement(),
4564 "TypedTensorViewMut::from_slice",
4565 )
4566 }
4567}
4568
4569impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4570 /// Create a rank-generic mutable host view from explicit layout metadata.
4571 ///
4572 /// # Examples
4573 ///
4574 /// ```rust
4575 /// use tenferro_tensor::{Rank, TypedTensorViewMut};
4576 ///
4577 /// let mut data = [1_i32, 2, 3, 4];
4578 /// let view = TypedTensorViewMut::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &mut data)?;
4579 /// assert_eq!(view.shape(), &[2, 2]);
4580 /// # Ok::<(), tenferro_tensor::Error>(())
4581 /// ```
4582 /// # Errors
4583 ///
4584 /// Returns [`crate::Error::Validation`] with
4585 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the typed
4586 /// rank does not match `shape` or `strides`,
4587 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
4588 /// layout reaches beyond `data`,
4589 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
4590 /// logical elements alias, or
4591 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
4592 /// arithmetic overflow.
4593 pub fn from_slice_ranked(
4594 shape: impl Into<R::Shape>,
4595 strides: impl Into<R::Strides>,
4596 offset: isize,
4597 data: &'a mut [T],
4598 ) -> crate::Result<Self> {
4599 Self::from_buffer_ref_mut(
4600 shape,
4601 strides,
4602 offset,
4603 TensorStorageRefMut::Host(data),
4604 default_placement(),
4605 "TypedTensorViewMut::from_slice_ranked",
4606 )
4607 }
4608}
4609
4610impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4611 fn from_buffer_ref_mut(
4612 shape: impl Into<R::Shape>,
4613 strides: impl Into<R::Strides>,
4614 offset: isize,
4615 buffer: TensorStorageRefMut<'a, T>,
4616 placement: Placement,
4617 op: &'static str,
4618 ) -> crate::Result<Self> {
4619 let layout = TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
4620 .map_err(|err| tensor_layout_error(op, err))?;
4621 layout
4622 .validate_mutable_no_overlap()
4623 .map_err(|err| tensor_layout_error(op, err))?;
4624 Ok(Self {
4625 buffer,
4626 root: None,
4627 layout,
4628 placement,
4629 _representation: std::marker::PhantomData,
4630 })
4631 }
4632}
4633
4634impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Dynamic> {
4635 /// Whether this mutable view writes host-addressed memory.
4636 ///
4637 /// The one host/device answer for a write target, decided by the borrowed
4638 /// payload and never by [`Placement::memory_kind`]; it is the same answer
4639 /// [`Self::try_mut_host`] acts on.
4640 ///
4641 /// # Examples
4642 ///
4643 /// ```rust
4644 /// use tenferro_tensor::TypedTensor;
4645 ///
4646 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
4647 /// assert!(tensor.as_view_mut().is_host_memory());
4648 /// # Ok::<(), tenferro_tensor::Error>(())
4649 /// ```
4650 pub fn is_host_memory(&self) -> bool {
4651 matches!(self.buffer, TensorStorageRefMut::Host(_))
4652 }
4653
4654 /// Checked narrowing of a mutable view to the host representation.
4655 ///
4656 /// The mutable counterpart of [`TypedTensorView::try_host`]: it succeeds
4657 /// exactly when the view writes host elements (a plain host owner, a host
4658 /// slice, or a CPU-resident allocation group) and keeps the layout and the
4659 /// placement label. A consumer that receives the result writes it through
4660 /// [`TypedTensorViewMut::as_host_slice_mut`] without a further check.
4661 ///
4662 /// # Examples
4663 ///
4664 /// ```rust
4665 /// use tenferro_tensor::TypedTensor;
4666 ///
4667 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
4668 /// let mut host = tensor.as_view_mut().try_mut_host("example")?;
4669 /// host.as_host_slice_mut()[0] = 5.0;
4670 /// assert_eq!(tensor.as_slice()?, &[5.0, 2.0]);
4671 /// # Ok::<(), tenferro_tensor::Error>(())
4672 /// ```
4673 ///
4674 /// # Errors
4675 ///
4676 /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
4677 /// borrows backend (device) storage; download the tensor to host first.
4678 pub fn try_mut_host(
4679 self,
4680 op: &'static str,
4681 ) -> crate::Result<TypedTensorViewMut<'a, T, R, Host>> {
4682 match self.buffer {
4683 TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
4684 buffer: TensorStorageRefMut::Host(data),
4685 // A host-marked view carries no retained region: the exclusive
4686 // borrow of `data` is what keeps the owner alive for `'a`, and
4687 // the group child has no drop-time obligation.
4688 root: None,
4689 layout: self.layout,
4690 placement: self.placement,
4691 _representation: std::marker::PhantomData,
4692 }),
4693 TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4694 op,
4695 "CPU backend received a backend buffer; download the tensor to host before CPU execution",
4696 )),
4697 }
4698 }
4699}
4700
4701impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Host> {
4702 /// Widen a host-marked mutable view to the runtime union without copying.
4703 ///
4704 /// # Examples
4705 ///
4706 /// ```rust
4707 /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4708 ///
4709 /// let mut data = [1_i32, 2];
4710 /// let host: TypedTensorViewMut<'_, i32, DynRank, Host> =
4711 /// TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4712 /// let dynamic = host.into_dynamic();
4713 /// assert_eq!(dynamic.as_read_only().host_storage()?, &[1, 2]);
4714 /// # Ok::<(), tenferro_tensor::Error>(())
4715 /// ```
4716 pub fn into_dynamic(self) -> TypedTensorViewMut<'a, T, R, Dynamic> {
4717 TypedTensorViewMut {
4718 buffer: self.buffer,
4719 root: self.root,
4720 layout: self.layout,
4721 placement: self.placement,
4722 _representation: std::marker::PhantomData,
4723 }
4724 }
4725}
4726
4727impl<'a, T: 'static, R: TensorRank> TypedTensorViewMut<'a, T, R, Host> {
4728 /// Create a representation-marked mutable view over an explicit host layout.
4729 ///
4730 /// # Examples
4731 ///
4732 /// ```rust
4733 /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4734 ///
4735 /// let mut data = [1_i32, 2];
4736 /// let mut view: TypedTensorViewMut<'_, i32, DynRank, Host> =
4737 /// TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4738 /// view.slice_view(&[tenferro_tensor::StridedSliceSpec::all()])?;
4739 /// # Ok::<(), tenferro_tensor::Error>(())
4740 /// ```
4741 ///
4742 /// # Errors
4743 ///
4744 /// Returns [`crate::Error::Validation`] with
4745 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `strides`
4746 /// has a different rank, [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`]
4747 /// when logical elements alias, or
4748 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] /
4749 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when the
4750 /// reachable layout leaves `data` or overflows.
4751 pub fn from_host_slice(
4752 shape: impl Into<R::Shape>,
4753 strides: impl Into<R::Strides>,
4754 offset: isize,
4755 data: &'a mut [T],
4756 ) -> crate::Result<Self> {
4757 // Built here rather than through the shared helper so that the Host
4758 // marker can only ever be paired with a host slice.
4759 let buffer = TensorStorageRefMut::Host(data);
4760 let layout =
4761 TensorLayout::from_parts(shape.into(), strides.into(), offset, buffer.len())
4762 .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_host_slice", err))?;
4763 layout
4764 .validate_mutable_no_overlap()
4765 .map_err(|err| tensor_layout_error("TypedTensorViewMut::from_host_slice", err))?;
4766 Ok(Self {
4767 buffer,
4768 root: None,
4769 layout,
4770 placement: default_placement(),
4771 _representation: std::marker::PhantomData,
4772 })
4773 }
4774
4775 /// Exclusively borrow the host elements without a runtime check.
4776 ///
4777 /// # Examples
4778 ///
4779 /// ```
4780 /// use tenferro_tensor::{DynRank, Host, TypedTensorViewMut};
4781 ///
4782 /// let mut data = [1_i32, 2];
4783 /// let mut view: TypedTensorViewMut<'_, i32, DynRank, Host> =
4784 /// TypedTensorViewMut::from_host_slice(vec![2].as_slice(), vec![1].as_slice(), 0, &mut data)?;
4785 /// view.as_host_slice_mut()[0] = 5;
4786 /// assert_eq!(data, [5, 2]);
4787 /// # Ok::<(), tenferro_tensor::Error>(())
4788 /// ```
4789 ///
4790 /// # Panics
4791 ///
4792 /// Panics only if a `Host`-marked view was built from non-host storage,
4793 /// which no constructor in this crate does.
4794 pub fn as_host_slice_mut(&mut self) -> &mut [T] {
4795 match &mut self.buffer {
4796 TensorStorageRefMut::Host(data) => data,
4797 // INVARIANT: `Host`-marked views are constructed only by
4798 // `from_host_slice` and by `TypedTensor<_, _, Host>::as_view_mut`.
4799 TensorStorageRefMut::Backend(_) => {
4800 unreachable!("a Host-marked view always borrows host storage")
4801 }
4802 }
4803 }
4804}
4805
4806impl<'a, T: 'static, R: TensorRank, D: Representation> TypedTensorViewMut<'a, T, R, D> {
4807 /// Return the logical shape.
4808 ///
4809 /// # Examples
4810 ///
4811 /// ```rust
4812 /// use tenferro_tensor::TypedTensorViewMut;
4813 ///
4814 /// let mut data = [0_i32; 2];
4815 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4816 /// assert_eq!(view.shape(), &[2]);
4817 /// # Ok::<(), tenferro_tensor::Error>(())
4818 /// ```
4819 pub fn shape(&self) -> &[usize] {
4820 self.layout.shape()
4821 }
4822
4823 /// Return the logical rank carried by this mutable view.
4824 ///
4825 /// # Examples
4826 ///
4827 /// ```
4828 /// use tenferro_tensor::TypedTensorViewMut;
4829 ///
4830 /// let mut data = [0_i32; 6];
4831 /// let view = TypedTensorViewMut::from_slice(vec![2, 3], vec![1, 2], 0, &mut data)?;
4832 /// assert_eq!(view.rank(), 2);
4833 /// # Ok::<(), tenferro_tensor::Error>(())
4834 /// ```
4835 pub fn rank(&self) -> usize {
4836 self.shape().len()
4837 }
4838
4839 /// Return strides in element units.
4840 ///
4841 /// # Examples
4842 ///
4843 /// ```rust
4844 /// use tenferro_tensor::TypedTensorViewMut;
4845 ///
4846 /// let mut data = [0_i32; 2];
4847 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![-1], 1, &mut data)?;
4848 /// assert_eq!(view.strides(), &[-1]);
4849 /// # Ok::<(), tenferro_tensor::Error>(())
4850 /// ```
4851 pub fn strides(&self) -> &[isize] {
4852 self.layout.strides()
4853 }
4854
4855 /// Return the physical element offset.
4856 ///
4857 /// # Examples
4858 ///
4859 /// ```rust
4860 /// use tenferro_tensor::TypedTensorViewMut;
4861 ///
4862 /// let mut data = [1_i32, 2];
4863 /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 1, &mut data)?;
4864 /// assert_eq!(view.offset(), 1);
4865 /// # Ok::<(), tenferro_tensor::Error>(())
4866 /// ```
4867 pub fn offset(&self) -> isize {
4868 self.layout.offset()
4869 }
4870
4871 /// Return the borrowed host storage backing this view.
4872 ///
4873 /// This exposes the entire backing host allocation, not just the logical
4874 /// slice covered by this view. Use [`TypedTensorViewMut::as_read_only`]
4875 /// with [`TypedTensorView::as_slice`] when the caller needs the contiguous
4876 /// logical region instead.
4877 ///
4878 /// # Examples
4879 ///
4880 /// ```rust
4881 /// use tenferro_tensor::TypedTensorViewMut;
4882 ///
4883 /// let mut data = [1_i32, 2];
4884 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4885 /// assert_eq!(view.host_storage()?, &[1, 2]);
4886 /// # Ok::<(), tenferro_tensor::Error>(())
4887 /// ```
4888 /// # Errors
4889 ///
4890 /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
4891 /// buffer; backend storage must be downloaded before host inspection.
4892 pub fn host_storage(&self) -> crate::Result<&[T]> {
4893 match &self.buffer {
4894 TensorStorageRefMut::Host(data) => Ok(data),
4895 TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4896 "TypedTensorViewMut::host_storage",
4897 "backend buffers cannot expose host storage; download explicitly first",
4898 )),
4899 }
4900 }
4901
4902 /// Mutably borrow the host storage backing this view.
4903 ///
4904 /// This exposes the entire backing host allocation, not just the logical
4905 /// slice covered by this view. Prefer scalar element accessors when mutating
4906 /// a logical region; tensor-sized copies belong to an active backend.
4907 ///
4908 /// # Examples
4909 ///
4910 /// ```rust
4911 /// use tenferro_tensor::TypedTensorViewMut;
4912 ///
4913 /// let mut data = [1_i32, 2];
4914 /// let mut view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4915 /// view.host_storage_mut()?[0] = 3;
4916 /// assert_eq!(view.get(&[0]), Some(&3));
4917 /// # Ok::<(), tenferro_tensor::Error>(())
4918 /// ```
4919 /// # Errors
4920 ///
4921 /// Returns [`crate::Error::RuntimeState`] when this view wraps a backend
4922 /// buffer; backend storage must be downloaded before host inspection.
4923 pub fn host_storage_mut(&mut self) -> crate::Result<&mut [T]> {
4924 match &mut self.buffer {
4925 TensorStorageRefMut::Host(data) => Ok(data),
4926 TensorStorageRefMut::Backend(_) => Err(crate::Error::runtime_state(
4927 "TypedTensorViewMut::host_storage_mut",
4928 "backend buffers cannot expose mutable host storage; download explicitly first",
4929 )),
4930 }
4931 }
4932
4933 /// Return the number of logical elements in this view.
4934 ///
4935 /// # Examples
4936 ///
4937 /// ```rust
4938 /// use tenferro_tensor::TypedTensorViewMut;
4939 ///
4940 /// let mut data = [0_i32; 6];
4941 /// let view = TypedTensorViewMut::from_slice(vec![2, 3], vec![1, 2], 0, &mut data)?;
4942 /// assert_eq!(view.n_elements(), 6);
4943 /// # Ok::<(), tenferro_tensor::Error>(())
4944 /// ```
4945 pub fn n_elements(&self) -> usize {
4946 // Invariant: public mutable view constructors validate logical element count.
4947 match checked_view_element_count(self.shape(), "TypedTensorViewMut::n_elements") {
4948 Ok(n) => n,
4949 Err(err) => {
4950 unreachable!("TypedTensorViewMut layout shape is validated at construction: {err}")
4951 }
4952 }
4953 }
4954
4955 /// Return layout metadata for this view.
4956 ///
4957 /// # Examples
4958 ///
4959 /// ```rust
4960 /// use tenferro_tensor::TypedTensorViewMut;
4961 ///
4962 /// let mut data = [1_i32, 2];
4963 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
4964 /// assert!(view.layout().is_compact_col_major().unwrap());
4965 /// # Ok::<(), tenferro_tensor::Error>(())
4966 /// ```
4967 pub fn layout(&self) -> &TensorLayout<R> {
4968 &self.layout
4969 }
4970
4971 /// Return placement metadata for this view.
4972 ///
4973 /// # Examples
4974 ///
4975 /// ```rust
4976 /// use tenferro_tensor::{MemoryKind, TypedTensorViewMut};
4977 ///
4978 /// let mut data = [1_i32];
4979 /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
4980 /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
4981 /// # Ok::<(), tenferro_tensor::Error>(())
4982 /// ```
4983 pub fn placement(&self) -> &Placement {
4984 &self.placement
4985 }
4986
4987 /// Return the backend allocation for backend integrations.
4988 #[doc(hidden)]
4989 pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>> {
4990 match &self.buffer {
4991 TensorStorageRefMut::Host(_) => None,
4992 TensorStorageRefMut::Backend(buffer) => Some(&**buffer),
4993 }
4994 }
4995
4996 /// Prepare this backend view for one provider-native write binding.
4997 #[doc(hidden)]
4998 pub fn prepare_device_write(
4999 &mut self,
5000 op: &'static str,
5001 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
5002 where
5003 T: TensorScalar + 'static,
5004 {
5005 let layout = self.layout.clone();
5006 if self.root.is_none() {
5007 let buffer = self.backend_buffer().ok_or_else(|| {
5008 crate::Error::runtime_state_source(
5009 op,
5010 crate::AccessError::Unsupported { backend: "host" },
5011 )
5012 })?;
5013 return prepare_backend_access(buffer, &self.layout, op);
5014 }
5015 let root = self
5016 .root
5017 .as_mut()
5018 .ok_or_else(|| crate::Error::runtime_state(op, "expected a root-backed tensor view"))?;
5019 root.prepare_device_write_for_layout(&layout)
5020 .map_err(|error| crate::Error::runtime_state_source(op, error))
5021 }
5022
5023 /// Compute the physical element offset for a logical index.
5024 ///
5025 /// # Examples
5026 ///
5027 /// ```rust
5028 /// use tenferro_tensor::TypedTensorViewMut;
5029 ///
5030 /// let mut data = [1_i32, 2, 3];
5031 /// let view = TypedTensorViewMut::from_slice(vec![3], vec![-1], 2, &mut data)?;
5032 /// assert_eq!(view.linear_offset(&[2]), Some(0));
5033 /// # Ok::<(), tenferro_tensor::Error>(())
5034 /// ```
5035 pub fn linear_offset(&self, indices: &[usize]) -> Option<usize> {
5036 checked_view_offset(self.shape(), self.strides(), self.offset(), indices)
5037 }
5038
5039 /// Compute the physical element offset for a logical index, returning a typed error.
5040 ///
5041 /// # Examples
5042 ///
5043 /// ```rust
5044 /// use tenferro_tensor::TypedTensorViewMut;
5045 ///
5046 /// let mut data = [1_i32, 2, 3];
5047 /// let view = TypedTensorViewMut::from_slice([3], [-1], 2, &mut data)?;
5048 /// assert_eq!(view.layout_linear_offset(&[2])?, 0);
5049 /// # Ok::<(), tenferro_tensor::Error>(())
5050 /// ```
5051 /// # Errors
5052 ///
5053 /// Returns [`crate::Error::Validation`] with
5054 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
5055 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
5056 /// when an index is outside its axis extent, or
5057 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
5058 /// arithmetic overflows.
5059 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
5060 checked_view_offset_result(
5061 self.shape(),
5062 self.strides(),
5063 self.offset(),
5064 indices,
5065 "TypedTensorViewMut::layout_linear_offset",
5066 )
5067 }
5068
5069 /// Return whether this mutable view is compact column-major.
5070 ///
5071 /// # Examples
5072 ///
5073 /// ```rust
5074 /// use tenferro_tensor::TypedTensorViewMut;
5075 ///
5076 /// let mut data = [1_i32, 2];
5077 /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5078 /// assert!(view.is_col_major_contiguous()?);
5079 /// # Ok::<(), tenferro_tensor::Error>(())
5080 /// ```
5081 /// # Errors
5082 ///
5083 /// Returns [`crate::Error::Validation`] with
5084 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
5085 /// compactness arithmetic overflows.
5086 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
5087 self.layout
5088 .is_compact_col_major()
5089 .map_err(|err| tensor_layout_error("TypedTensorViewMut::is_col_major_contiguous", err))
5090 }
5091
5092 /// Return a compact string summary of this mutable view's layout metadata.
5093 ///
5094 /// # Examples
5095 ///
5096 /// ```rust
5097 /// use tenferro_tensor::TypedTensorViewMut;
5098 ///
5099 /// let mut data = [1_i32, 2];
5100 /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5101 /// assert!(view.layout_summary().contains("shape=[2]"));
5102 /// # Ok::<(), tenferro_tensor::Error>(())
5103 /// ```
5104 pub fn layout_summary(&self) -> String {
5105 layout_summary(self.shape(), self.strides(), self.offset())
5106 }
5107
5108 /// Assert this mutable view is compact column-major.
5109 ///
5110 /// # Examples
5111 ///
5112 /// ```rust
5113 /// use tenferro_tensor::TypedTensorViewMut;
5114 ///
5115 /// let mut data = [1_i32, 2];
5116 /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?;
5117 /// view.assert_col_major_contiguous()?;
5118 /// # Ok::<(), tenferro_tensor::Error>(())
5119 /// ```
5120 /// # Errors
5121 ///
5122 /// Returns [`crate::Error::Validation`] with
5123 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
5124 /// compactness arithmetic overflows, or
5125 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
5126 /// view is not compact column-major.
5127 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
5128 assert_layout_col_major_contiguous(
5129 self.is_col_major_contiguous()?,
5130 self.shape(),
5131 self.strides(),
5132 self.offset(),
5133 "TypedTensorViewMut::assert_col_major_contiguous",
5134 )
5135 }
5136
5137 /// Borrow one host element by logical index.
5138 ///
5139 /// # Examples
5140 ///
5141 /// ```rust
5142 /// use tenferro_tensor::TypedTensorViewMut;
5143 ///
5144 /// let mut data = [1_i32, 2];
5145 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5146 /// assert_eq!(view.get(&[1]), Some(&2));
5147 /// # Ok::<(), tenferro_tensor::Error>(())
5148 /// ```
5149 pub fn get(&self, indices: &[usize]) -> Option<&T> {
5150 let offset = self.linear_offset(indices)?;
5151 match &self.buffer {
5152 TensorStorageRefMut::Host(data) => data.get(offset),
5153 TensorStorageRefMut::Backend(_) => None,
5154 }
5155 }
5156
5157 /// Mutably borrow one host element by logical index.
5158 ///
5159 /// # Examples
5160 ///
5161 /// ```rust
5162 /// use tenferro_tensor::TypedTensorViewMut;
5163 ///
5164 /// let mut data = [1_i32, 2];
5165 /// let mut view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5166 /// *view.get_mut(&[1]).unwrap() = 20;
5167 /// assert_eq!(view.get(&[1]), Some(&20));
5168 /// # Ok::<(), tenferro_tensor::Error>(())
5169 /// ```
5170 pub fn get_mut(&mut self, indices: &[usize]) -> Option<&mut T> {
5171 let offset = self.linear_offset(indices)?;
5172 match &mut self.buffer {
5173 TensorStorageRefMut::Host(data) => data.get_mut(offset),
5174 TensorStorageRefMut::Backend(_) => None,
5175 }
5176 }
5177
5178 /// Borrow this mutable view as a read-only view.
5179 ///
5180 /// # Examples
5181 ///
5182 /// ```rust
5183 /// use tenferro_tensor::TypedTensorViewMut;
5184 ///
5185 /// let mut data = [1_i32];
5186 /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
5187 /// assert_eq!(view.as_read_only().get(&[0]), Some(&1));
5188 /// # Ok::<(), tenferro_tensor::Error>(())
5189 /// ```
5190 /// Explicitly duplicate the compact host data visible through this
5191 /// mutable view into a new owner.
5192 ///
5193 /// # Errors
5194 ///
5195 /// Returns [`crate::Error::HostAccess`] or
5196 /// [`ValidationError::NonContiguousViewAsSlice`] when the view is backend
5197 /// owned or not contiguous, and [`ValidationError::InvalidArgument`] when
5198 /// the static-rank shape cannot be reconstructed.
5199 ///
5200 /// # Examples
5201 ///
5202 /// ```
5203 /// use tenferro_tensor::TypedTensorViewMut;
5204 ///
5205 /// let mut data = [1_i32, 2];
5206 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5207 /// let copy = view.duplicate()?;
5208 /// assert_eq!(copy.as_slice()?, &[1, 2]);
5209 /// # Ok::<(), tenferro_tensor::Error>(())
5210 /// ```
5211 pub fn duplicate(&self) -> crate::Result<TypedTensor<T, R>>
5212 where
5213 T: Clone,
5214 {
5215 self.as_read_only().duplicate()
5216 }
5217
5218 /// Explicitly copy this host view to a compact column-major owner.
5219 ///
5220 /// # Examples
5221 /// ```
5222 /// use tenferro_tensor::TypedTensorViewMut;
5223 /// let mut values = ["a".to_owned(), "b".to_owned()];
5224 /// let view = TypedTensorViewMut::from_slice([2], [1], 0, &mut values)?;
5225 /// assert_eq!(view.to_col_major()?.as_slice()?, &["a", "b"]);
5226 /// # Ok::<(), tenferro_tensor::Error>(())
5227 /// ```
5228 /// # Errors
5229 /// Backend-only storage returns [`crate::Error::RuntimeState`]; invalid
5230 /// layout or rank conversion returns [`crate::Error::Validation`].
5231 pub fn to_col_major(&self) -> crate::Result<TypedTensor<T, R>>
5232 where
5233 T: Clone,
5234 {
5235 self.as_read_only().to_col_major()
5236 }
5237
5238 /// Borrow this mutable view as a read-only typed view over the same storage.
5239 ///
5240 /// # Examples
5241 ///
5242 /// ```
5243 /// use tenferro_tensor::TypedTensorViewMut;
5244 ///
5245 /// let mut data = [1_i32, 2];
5246 /// let view = TypedTensorViewMut::from_slice(vec![2], vec![1], 0, &mut data)?;
5247 /// assert_eq!(view.as_read_only().as_slice()?, &[1, 2]);
5248 /// # Ok::<(), tenferro_tensor::Error>(())
5249 /// ```
5250 pub fn as_read_only(&self) -> TypedTensorView<'_, T, R, D> {
5251 let buffer = match &self.buffer {
5252 TensorStorageRefMut::Host(data) => TensorStorageRef::Host(data),
5253 TensorStorageRefMut::Backend(buffer) => TensorStorageRef::Backend(&**buffer),
5254 };
5255 TypedTensorView {
5256 buffer,
5257 root: None,
5258 layout: self.layout.clone(),
5259 placement: self.placement.clone(),
5260 _representation: std::marker::PhantomData,
5261 }
5262 }
5263
5264 /// Convert this mutable view into a read-only view.
5265 ///
5266 /// # Examples
5267 ///
5268 /// ```rust
5269 /// use tenferro_tensor::TypedTensorViewMut;
5270 ///
5271 /// let mut data = [1_i32];
5272 /// let view = TypedTensorViewMut::from_slice(vec![1], vec![1], 0, &mut data)?;
5273 /// assert_eq!(view.into_read_only().get(&[0]), Some(&1));
5274 /// # Ok::<(), tenferro_tensor::Error>(())
5275 /// ```
5276 pub fn into_read_only(self) -> TypedTensorView<'a, T, R, D> {
5277 let buffer = match self.buffer {
5278 TensorStorageRefMut::Host(data) => TensorStorageRef::Host(data),
5279 TensorStorageRefMut::Backend(buffer) => TensorStorageRef::Backend(buffer),
5280 };
5281 TypedTensorView {
5282 buffer,
5283 root: None,
5284 layout: self.layout,
5285 placement: self.placement,
5286 _representation: std::marker::PhantomData,
5287 }
5288 }
5289
5290 /// Consume this mutable view and return a metadata-only axis permutation.
5291 ///
5292 /// # Examples
5293 ///
5294 /// ```rust
5295 /// use tenferro_tensor::{Rank, TypedTensorViewMut};
5296 ///
5297 /// let mut data = [1_i32, 2, 3, 4];
5298 /// let view = TypedTensorViewMut::<_, Rank<2>>::from_slice_ranked([2, 2], [1, 2], 0, &mut data)?;
5299 /// let transposed = view.transpose_view([1, 0])?;
5300 /// assert_eq!(transposed.strides(), &[2, 1]);
5301 /// # Ok::<(), tenferro_tensor::Error>(())
5302 /// ```
5303 /// # Errors
5304 ///
5305 /// Returns [`crate::Error::Validation`] with
5306 /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
5307 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
5308 /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
5309 /// not a valid permutation, [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`]
5310 /// when the permutation creates aliases, or
5311 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5312 /// arithmetic overflow.
5313 pub fn transpose_view(
5314 self,
5315 axes: impl AsRef<[usize]>,
5316 ) -> crate::Result<TypedTensorViewMut<'a, T, R>> {
5317 let Self {
5318 buffer,
5319 root,
5320 layout,
5321 placement,
5322 _representation: std::marker::PhantomData,
5323 } = self;
5324 let layout = layout
5325 .transpose_view(axes)
5326 .map_err(|err| tensor_layout_error("TypedTensorViewMut::transpose_view", err))?;
5327 layout
5328 .validate_mutable_no_overlap()
5329 .map_err(|err| tensor_layout_error("TypedTensorViewMut::transpose_view", err))?;
5330 match buffer {
5331 TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5332 buffer: TensorStorageRefMut::Host(data),
5333 root,
5334 layout,
5335 placement,
5336 _representation: std::marker::PhantomData,
5337 }),
5338 TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5339 buffer: TensorStorageRefMut::Backend(buffer),
5340 root,
5341 layout,
5342 placement,
5343 _representation: std::marker::PhantomData,
5344 }),
5345 }
5346 }
5347
5348 /// Return a mutable metadata-only slice using one [`StridedSliceSpec`] per axis.
5349 ///
5350 /// # Examples
5351 ///
5352 /// ```rust
5353 /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5354 ///
5355 /// let mut data = [1_i32, 2, 3];
5356 /// let mut view = TypedTensorViewMut::from_slice(vec![3], vec![1], 0, &mut data)?;
5357 /// *view.slice_view(&[StridedSliceSpec::reverse()])?.get_mut(&[0]).unwrap() = 30;
5358 /// assert_eq!(view.get(&[2]), Some(&30));
5359 /// # Ok::<(), tenferro_tensor::Error>(())
5360 /// ```
5361 /// # Errors
5362 ///
5363 /// Returns [`crate::Error::Validation`] with
5364 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when the slice
5365 /// count differs from the view rank,
5366 /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
5367 /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
5368 /// invalid slice, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5369 /// when the result exceeds the backing buffer,
5370 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5371 /// logical elements alias, or
5372 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5373 /// arithmetic overflow.
5374 pub fn slice_view(
5375 &mut self,
5376 slices: &[StridedSliceSpec],
5377 ) -> crate::Result<TypedTensorViewMut<'_, T, R>> {
5378 let specs = core_slice_specs(slices, self.shape(), "TypedTensorViewMut::slice_view")?;
5379 let layout = self
5380 .layout
5381 .slice_view(specs, self.buffer.len())
5382 .map_err(|err| tensor_layout_error("TypedTensorViewMut::slice_view", err))?;
5383 layout
5384 .validate_mutable_no_overlap()
5385 .map_err(|err| tensor_layout_error("TypedTensorViewMut::slice_view", err))?;
5386 let placement = self.placement.clone();
5387 match &mut self.buffer {
5388 TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5389 buffer: TensorStorageRefMut::Host(data),
5390 root: None,
5391 layout,
5392 placement,
5393 _representation: std::marker::PhantomData,
5394 }),
5395 TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5396 buffer: TensorStorageRefMut::Backend(*buffer),
5397 root: None,
5398 layout,
5399 placement,
5400 _representation: std::marker::PhantomData,
5401 }),
5402 }
5403 }
5404
5405 /// Return a mutable metadata-only slice along one axis.
5406 ///
5407 /// # Examples
5408 ///
5409 /// ```rust
5410 /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5411 ///
5412 /// let mut data = [1_i32, 2, 3, 4];
5413 /// let mut view = TypedTensorViewMut::from_slice(vec![2, 2], vec![1, 2], 0, &mut data)?;
5414 /// assert_eq!(view.slice_axis_view(1, StridedSliceSpec::reverse())?.get(&[0, 0]), Some(&3));
5415 /// # Ok::<(), tenferro_tensor::Error>(())
5416 /// ```
5417 /// # Errors
5418 ///
5419 /// Returns [`crate::Error::Validation`] with
5420 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`] when `axis`
5421 /// is outside the view rank, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
5422 /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for an
5423 /// invalid slice, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5424 /// when the result exceeds the backing buffer,
5425 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5426 /// logical elements alias, or
5427 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5428 /// arithmetic overflow.
5429 pub fn slice_axis_view(
5430 &mut self,
5431 axis: usize,
5432 slice: StridedSliceSpec,
5433 ) -> crate::Result<TypedTensorViewMut<'_, T, R>> {
5434 let slices = slice_axis_specs(
5435 self.shape().len(),
5436 axis,
5437 slice,
5438 "TypedTensorViewMut::slice_axis_view",
5439 )?;
5440 self.slice_view(&slices)
5441 }
5442
5443 /// Return two mutable metadata-only slices when their physical ranges are disjoint.
5444 ///
5445 /// # Examples
5446 ///
5447 /// ```rust
5448 /// use tenferro_tensor::{StridedSliceSpec, TypedTensorViewMut};
5449 ///
5450 /// let mut data = [1_i32, 2, 3, 4];
5451 /// let mut view = TypedTensorViewMut::from_slice(vec![4], vec![1], 0, &mut data)?;
5452 /// let (left, right) = view
5453 /// .try_multi_slice_mut(
5454 /// &[StridedSliceSpec::new(0, Some(2), 1)],
5455 /// &[StridedSliceSpec::new(2, Some(4), 1)],
5456 /// )
5457 /// ?
5458 /// .unwrap();
5459 /// assert_eq!(left.shape(), &[2]);
5460 /// assert_eq!(right.shape(), &[2]);
5461 /// # Ok::<(), tenferro_tensor::Error>(())
5462 /// ```
5463 /// # Errors
5464 ///
5465 /// Returns [`crate::Error::Validation`] with
5466 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for either
5467 /// slice count, [`tenferro_tensor_core::ValidationError::InvalidSliceStep`]
5468 /// or [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for
5469 /// invalid parameters, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
5470 /// when a result exceeds the backing buffer,
5471 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5472 /// a result aliases, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
5473 /// for a negative reachable offset, or
5474 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
5475 /// arithmetic overflow. The method returns `Ok(None)` when the two ranges
5476 /// overlap or the view uses backend storage.
5477 pub fn try_multi_slice_mut(
5478 &mut self,
5479 first: &[StridedSliceSpec],
5480 second: &[StridedSliceSpec],
5481 ) -> crate::Result<Option<TypedTensorViewMutSplit<'_, T, R>>> {
5482 let op = "TypedTensorViewMut::try_multi_slice_mut";
5483 let first_specs = core_slice_specs(first, self.shape(), op)?;
5484 let second_specs = core_slice_specs(second, self.shape(), op)?;
5485 let buffer_len = self.buffer.len();
5486 let first_layout = self
5487 .layout
5488 .slice_view(first_specs, buffer_len)
5489 .map_err(|err| tensor_layout_error(op, err))?;
5490 let second_layout = self
5491 .layout
5492 .slice_view(second_specs, buffer_len)
5493 .map_err(|err| tensor_layout_error(op, err))?;
5494 first_layout
5495 .validate_mutable_no_overlap()
5496 .map_err(|err| tensor_layout_error(op, err))?;
5497 second_layout
5498 .validate_mutable_no_overlap()
5499 .map_err(|err| tensor_layout_error(op, err))?;
5500
5501 match (
5502 reachable_layout_span(
5503 first_layout.shape(),
5504 first_layout.strides(),
5505 first_layout.offset(),
5506 )?,
5507 reachable_layout_span(
5508 second_layout.shape(),
5509 second_layout.strides(),
5510 second_layout.offset(),
5511 )?,
5512 ) {
5513 (Some(first_span), Some(second_span)) => {
5514 let first_offset = adjusted_view_offset(first_layout.offset(), first_span.0)?;
5515 let second_offset = adjusted_view_offset(second_layout.offset(), second_span.0)?;
5516 let (first_data, second_data) = match &mut self.buffer {
5517 TensorStorageRefMut::Host(data) => {
5518 match split_two_mut_ranges(data, first_span, second_span) {
5519 Some(ranges) => ranges,
5520 None => return Ok(None),
5521 }
5522 }
5523 TensorStorageRefMut::Backend(_) => return Ok(None),
5524 };
5525 let first_view = view_mut_from_layout_and_slice(
5526 &first_layout,
5527 first_offset,
5528 first_data,
5529 self.placement.clone(),
5530 )?;
5531 let second_view = view_mut_from_layout_and_slice(
5532 &second_layout,
5533 second_offset,
5534 second_data,
5535 self.placement.clone(),
5536 )?;
5537 Ok(Some((first_view, second_view)))
5538 }
5539 (None, Some(second_span)) => {
5540 let second_offset = adjusted_view_offset(second_layout.offset(), second_span.0)?;
5541 let (_, after_start) = match &mut self.buffer {
5542 TensorStorageRefMut::Host(data) => data.split_at_mut(second_span.0),
5543 TensorStorageRefMut::Backend(_) => return Ok(None),
5544 };
5545 let (second_data, _) = after_start.split_at_mut(second_span.1 - second_span.0 + 1);
5546 let first_view = view_mut_from_layout_and_slice(
5547 &first_layout,
5548 0,
5549 &mut [],
5550 self.placement.clone(),
5551 )?;
5552 let second_view = view_mut_from_layout_and_slice(
5553 &second_layout,
5554 second_offset,
5555 second_data,
5556 self.placement.clone(),
5557 )?;
5558 Ok(Some((first_view, second_view)))
5559 }
5560 (Some(first_span), None) => {
5561 let first_offset = adjusted_view_offset(first_layout.offset(), first_span.0)?;
5562 let (_, after_start) = match &mut self.buffer {
5563 TensorStorageRefMut::Host(data) => data.split_at_mut(first_span.0),
5564 TensorStorageRefMut::Backend(_) => return Ok(None),
5565 };
5566 let (first_data, _) = after_start.split_at_mut(first_span.1 - first_span.0 + 1);
5567 let first_view = view_mut_from_layout_and_slice(
5568 &first_layout,
5569 first_offset,
5570 first_data,
5571 self.placement.clone(),
5572 )?;
5573 let second_view = view_mut_from_layout_and_slice(
5574 &second_layout,
5575 0,
5576 &mut [],
5577 self.placement.clone(),
5578 )?;
5579 Ok(Some((first_view, second_view)))
5580 }
5581 (None, None) => {
5582 let first_view = view_mut_from_layout_and_slice(
5583 &first_layout,
5584 0,
5585 &mut [],
5586 self.placement.clone(),
5587 )?;
5588 let second_view = view_mut_from_layout_and_slice(
5589 &second_layout,
5590 0,
5591 &mut [],
5592 self.placement.clone(),
5593 )?;
5594 Ok(Some((first_view, second_view)))
5595 }
5596 }
5597 }
5598
5599 /// Return a mutable metadata-only dynamic-rank reshape for contiguous views.
5600 ///
5601 /// # Examples
5602 ///
5603 /// ```rust
5604 /// use tenferro_tensor::TypedTensorViewMut;
5605 ///
5606 /// let mut data = [1_i32, 2, 3, 4];
5607 /// let mut view = TypedTensorViewMut::from_slice(vec![2, 2], vec![1, 2], 0, &mut data)?;
5608 /// assert_eq!(view.reshape_view(&[4])?.shape(), &[4]);
5609 /// # Ok::<(), tenferro_tensor::Error>(())
5610 /// ```
5611 /// # Errors
5612 ///
5613 /// Returns [`crate::Error::Validation`] with
5614 /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
5615 /// the source is not compact column-major,
5616 /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
5617 /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
5618 /// records the counts) when element counts differ,
5619 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
5620 /// the reshaped layout aliases, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
5621 /// for shape or layout arithmetic overflow, or
5622 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
5623 /// reshaped view exceeds the backing buffer.
5624 pub fn reshape_view(
5625 &mut self,
5626 shape: &[usize],
5627 ) -> crate::Result<TypedTensorViewMut<'_, T, DynRank, D>> {
5628 let layout = reshape_layout_dyn(
5629 &self.layout,
5630 shape,
5631 self.buffer.len(),
5632 "TypedTensorViewMut::reshape_view",
5633 )?;
5634 layout
5635 .validate_mutable_no_overlap()
5636 .map_err(|err| tensor_layout_error("TypedTensorViewMut::reshape_view", err))?;
5637 let placement = self.placement.clone();
5638 match &mut self.buffer {
5639 TensorStorageRefMut::Host(data) => Ok(TypedTensorViewMut {
5640 buffer: TensorStorageRefMut::Host(data),
5641 root: None,
5642 layout,
5643 placement,
5644 _representation: std::marker::PhantomData,
5645 }),
5646 TensorStorageRefMut::Backend(buffer) => Ok(TypedTensorViewMut {
5647 buffer: TensorStorageRefMut::Backend(*buffer),
5648 root: None,
5649 layout,
5650 placement,
5651 _representation: std::marker::PhantomData,
5652 }),
5653 }
5654 }
5655}
5656
5657impl<'a, R: TensorRank> TypedTensorViewMut<'a, Complex32, R> {
5658 /// Borrow this mutable complex view as an interleaved real view.
5659 ///
5660 /// This changes only the typed descriptor and borrows the same host
5661 /// allocation. The result has dynamic rank because the component axis is
5662 /// prepended. Backend-native buffers are rejected until their provider
5663 /// phase supplies the corresponding mapping capability.
5664 ///
5665 /// # Examples
5666 ///
5667 /// ```
5668 /// use tenferro_tensor::{Complex32, TypedTensorViewMut};
5669 ///
5670 /// let mut data = [Complex32::new(1.0, 2.0)];
5671 /// let mut view = TypedTensorViewMut::from_col_major(&[1], &mut data)?;
5672 /// let real = view.as_real_view_mut()?;
5673 /// assert_eq!(real.shape(), &[2, 1]);
5674 /// assert_eq!(real.as_read_only().as_slice()?, &[1.0_f32, 2.0]);
5675 /// # Ok::<(), tenferro_tensor::Error>(())
5676 /// ```
5677 ///
5678 /// # Errors
5679 ///
5680 /// Returns an error when the view layout is not injective, the sealed
5681 /// representation is invalid, or backend reinterpretation is unsupported.
5682 pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f32, DynRank>> {
5683 let op = "TypedTensorViewMut::as_real_view_mut";
5684 validate_representation_pair(op, DType::C32, DType::F32)?;
5685 let layout = reinterpret_complex_to_real_layout(
5686 self.shape(),
5687 self.strides(),
5688 self.offset(),
5689 self.buffer.len(),
5690 op,
5691 )?;
5692 layout
5693 .validate_mutable_no_overlap()
5694 .map_err(|err| tensor_layout_error(op, err))?;
5695 let buffer = match &mut self.buffer {
5696 TensorStorageRefMut::Host(data) => {
5697 TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex32, f32>(data, op)?)
5698 }
5699 TensorStorageRefMut::Backend(_) => {
5700 return Err(crate::Error::unsupported(
5701 op,
5702 "backend representation reinterpretation is enabled by the provider phases",
5703 ))
5704 }
5705 };
5706 Ok(TypedTensorViewMut {
5707 buffer,
5708 root: None,
5709 layout,
5710 placement: self.placement.clone(),
5711 _representation: std::marker::PhantomData,
5712 })
5713 }
5714}
5715
5716impl<'a, R: TensorRank> TypedTensorViewMut<'a, Complex64, R> {
5717 /// Borrow this mutable complex view as an interleaved real view.
5718 ///
5719 /// This changes only the typed descriptor and borrows the same host
5720 /// allocation. The result has dynamic rank because the component axis is
5721 /// prepended. Backend-native buffers are rejected until their provider
5722 /// phase supplies the corresponding mapping capability.
5723 ///
5724 /// # Examples
5725 ///
5726 /// ```
5727 /// use tenferro_tensor::{Complex64, TypedTensorViewMut};
5728 ///
5729 /// let mut data = [Complex64::new(1.0, 2.0)];
5730 /// let mut view = TypedTensorViewMut::from_col_major(&[1], &mut data)?;
5731 /// let real = view.as_real_view_mut()?;
5732 /// assert_eq!(real.shape(), &[2, 1]);
5733 /// assert_eq!(real.as_read_only().as_slice()?, &[1.0_f64, 2.0]);
5734 /// # Ok::<(), tenferro_tensor::Error>(())
5735 /// ```
5736 ///
5737 /// # Errors
5738 ///
5739 /// Returns an error when the view layout is not injective, the sealed
5740 /// representation is invalid, or backend reinterpretation is unsupported.
5741 pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f64, DynRank>> {
5742 let op = "TypedTensorViewMut::as_real_view_mut";
5743 validate_representation_pair(op, DType::C64, DType::F64)?;
5744 let layout = reinterpret_complex_to_real_layout(
5745 self.shape(),
5746 self.strides(),
5747 self.offset(),
5748 self.buffer.len(),
5749 op,
5750 )?;
5751 layout
5752 .validate_mutable_no_overlap()
5753 .map_err(|err| tensor_layout_error(op, err))?;
5754 let buffer = match &mut self.buffer {
5755 TensorStorageRefMut::Host(data) => {
5756 TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex64, f64>(data, op)?)
5757 }
5758 TensorStorageRefMut::Backend(_) => {
5759 return Err(crate::Error::unsupported(
5760 op,
5761 "backend representation reinterpretation is enabled by the provider phases",
5762 ))
5763 }
5764 };
5765 Ok(TypedTensorViewMut {
5766 buffer,
5767 root: None,
5768 layout,
5769 placement: self.placement.clone(),
5770 _representation: std::marker::PhantomData,
5771 })
5772 }
5773}
5774
5775impl<'a, R: TensorRank> TypedTensorViewMut<'a, f32, R> {
5776 /// Borrow this mutable interleaved real view as a complex view.
5777 ///
5778 /// The source must have a leading extent and stride of `2` and `1`, and
5779 /// all remaining strides plus the offset must be divisible by `2`.
5780 ///
5781 /// # Examples
5782 ///
5783 /// ```
5784 /// use tenferro_tensor::{Complex32, TypedTensorViewMut};
5785 ///
5786 /// let mut data = [1.0_f32, 2.0];
5787 /// let mut view = TypedTensorViewMut::from_col_major(&[2, 1], &mut data)?;
5788 /// let complex = view.as_complex_view_mut()?;
5789 /// assert_eq!(complex.shape(), &[1]);
5790 /// assert_eq!(complex.as_read_only().as_slice()?, &[Complex32::new(1.0, 2.0)]);
5791 /// # Ok::<(), tenferro_tensor::Error>(())
5792 /// ```
5793 ///
5794 /// # Errors
5795 ///
5796 /// Returns an error when the view layout is not injective, the sealed
5797 /// representation is invalid, or backend reinterpretation is unsupported.
5798 pub fn as_complex_view_mut(
5799 &mut self,
5800 ) -> crate::Result<TypedTensorViewMut<'_, Complex32, DynRank>> {
5801 let op = "TypedTensorViewMut::as_complex_view_mut";
5802 validate_representation_pair(op, DType::F32, DType::C32)?;
5803 let layout = reinterpret_real_to_complex_layout(
5804 self.shape(),
5805 self.strides(),
5806 self.offset(),
5807 self.buffer.len(),
5808 op,
5809 )?;
5810 layout
5811 .validate_mutable_no_overlap()
5812 .map_err(|err| tensor_layout_error(op, err))?;
5813 let buffer = match &mut self.buffer {
5814 TensorStorageRefMut::Host(data) => {
5815 TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f32, Complex32>(data, op)?)
5816 }
5817 TensorStorageRefMut::Backend(_) => {
5818 return Err(crate::Error::unsupported(
5819 op,
5820 "backend representation reinterpretation is enabled by the provider phases",
5821 ))
5822 }
5823 };
5824 Ok(TypedTensorViewMut {
5825 buffer,
5826 root: None,
5827 layout,
5828 placement: self.placement.clone(),
5829 _representation: std::marker::PhantomData,
5830 })
5831 }
5832}
5833
5834impl<'a, R: TensorRank> TypedTensorViewMut<'a, f64, R> {
5835 /// Borrow this mutable interleaved real view as a complex view.
5836 ///
5837 /// The source must have a leading extent and stride of `2` and `1`, and
5838 /// all remaining strides plus the offset must be divisible by `2`.
5839 ///
5840 /// # Examples
5841 ///
5842 /// ```
5843 /// use tenferro_tensor::{Complex64, TypedTensorViewMut};
5844 ///
5845 /// let mut data = [1.0_f64, 2.0];
5846 /// let mut view = TypedTensorViewMut::from_col_major(&[2, 1], &mut data)?;
5847 /// let complex = view.as_complex_view_mut()?;
5848 /// assert_eq!(complex.shape(), &[1]);
5849 /// assert_eq!(complex.as_read_only().as_slice()?, &[Complex64::new(1.0, 2.0)]);
5850 /// # Ok::<(), tenferro_tensor::Error>(())
5851 /// ```
5852 ///
5853 /// # Errors
5854 ///
5855 /// Returns an error when the view layout is not injective, the sealed
5856 /// representation is invalid, or backend reinterpretation is unsupported.
5857 pub fn as_complex_view_mut(
5858 &mut self,
5859 ) -> crate::Result<TypedTensorViewMut<'_, Complex64, DynRank>> {
5860 let op = "TypedTensorViewMut::as_complex_view_mut";
5861 validate_representation_pair(op, DType::F64, DType::C64)?;
5862 let layout = reinterpret_real_to_complex_layout(
5863 self.shape(),
5864 self.strides(),
5865 self.offset(),
5866 self.buffer.len(),
5867 op,
5868 )?;
5869 layout
5870 .validate_mutable_no_overlap()
5871 .map_err(|err| tensor_layout_error(op, err))?;
5872 let buffer = match &mut self.buffer {
5873 TensorStorageRefMut::Host(data) => {
5874 TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f64, Complex64>(data, op)?)
5875 }
5876 TensorStorageRefMut::Backend(_) => {
5877 return Err(crate::Error::unsupported(
5878 op,
5879 "backend representation reinterpretation is enabled by the provider phases",
5880 ))
5881 }
5882 };
5883 Ok(TypedTensorViewMut {
5884 buffer,
5885 root: None,
5886 layout,
5887 placement: self.placement.clone(),
5888 _representation: std::marker::PhantomData,
5889 })
5890 }
5891}
5892
5893/// Sealed trait for scalar types that can be stored in a [`Tensor`].
5894///
5895/// This trait is implemented for `f64`, `f32`, `i32`, `i64`, `bool`,
5896/// [`Complex64`], and [`Complex32`].
5897///
5898/// # Examples
5899///
5900/// ```
5901/// use tenferro_tensor::TensorScalar;
5902///
5903/// let tensor = <f64 as TensorScalar>::into_tensor(vec![2], vec![1.0, 2.0])?;
5904/// assert_eq!(tensor.as_slice::<f64>()?, [1.0, 2.0].as_slice());
5905/// # Ok::<(), tenferro_tensor::Error>(())
5906/// ```
5907pub trait TensorScalar: Copy + Clone + Send + Sync + 'static + private::Sealed {
5908 /// Real-valued counterpart of this scalar type.
5909 type Real: TensorScalar;
5910
5911 /// The [`DType`] tag corresponding to this scalar type.
5912 ///
5913 /// # Examples
5914 ///
5915 /// ```
5916 /// use tenferro_tensor::{DType, TensorScalar};
5917 ///
5918 /// assert_eq!(f64::dtype(), DType::F64);
5919 /// assert_eq!(f32::dtype(), DType::F32);
5920 /// ```
5921 fn dtype() -> DType;
5922
5923 /// Build the crate's default scalar set from validated column-major data.
5924 ///
5925 /// # Examples
5926 ///
5927 /// ```
5928 /// use tenferro_tensor::{DType, TensorScalar};
5929 ///
5930 /// let set = <f64 as TensorScalar>::into_default_scalars(vec![2], vec![1.0, 2.0])?;
5931 /// assert_eq!(set.dtype(), DType::F64);
5932 /// # Ok::<(), tenferro_tensor::Error>(())
5933 /// ```
5934 ///
5935 /// # Errors
5936 ///
5937 /// Returns a validation error carrying
5938 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when the shape product
5939 /// differs from `data.len()`, or [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
5940 /// when shape arithmetic overflows.
5941 fn into_default_scalars(
5942 shape: Vec<usize>,
5943 data: Vec<Self>,
5944 ) -> crate::Result<crate::DefaultScalars>;
5945
5946 /// Borrow the default scalar set's values when it holds this scalar type.
5947 ///
5948 /// Returns `None` when the set currently holds another member.
5949 ///
5950 /// # Examples
5951 ///
5952 /// ```
5953 /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5954 ///
5955 /// let set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5956 /// assert_eq!(<f64 as TensorScalar>::default_scalars_slice(&set), Some(&[1.0, 2.0][..]));
5957 /// assert!(<f32 as TensorScalar>::default_scalars_slice(&set).is_none());
5958 /// # Ok::<(), tenferro_tensor::Error>(())
5959 /// ```
5960 fn default_scalars_slice(set: &crate::DefaultScalars) -> Option<&[Self]>;
5961
5962 /// Exclusively borrow the default scalar set's values when it holds this scalar type.
5963 ///
5964 /// Returns `None` when the set currently holds another member.
5965 ///
5966 /// # Examples
5967 ///
5968 /// ```
5969 /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5970 ///
5971 /// let mut set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5972 /// if let Some(values) = <f64 as TensorScalar>::default_scalars_slice_mut(&mut set) {
5973 /// values[0] = 5.0;
5974 /// }
5975 /// assert_eq!(set.as_slice::<f64>()?, &[5.0, 2.0]);
5976 /// # Ok::<(), tenferro_tensor::Error>(())
5977 /// ```
5978 fn default_scalars_slice_mut(set: &mut crate::DefaultScalars) -> Option<&mut [Self]>;
5979
5980 /// Move the host tensor out of the default scalar set when it holds this scalar type.
5981 ///
5982 /// Returns `None` when the set currently holds another member.
5983 ///
5984 /// # Examples
5985 ///
5986 /// ```
5987 /// use tenferro_tensor::{DefaultScalars, TensorScalar};
5988 ///
5989 /// let set = DefaultScalars::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
5990 /// let host = <f64 as TensorScalar>::from_default_scalars(set);
5991 /// assert_eq!(host.as_ref().map(|t| t.shape()), Some(&[2][..]));
5992 /// assert_eq!(host.as_ref().map(|t| t.as_slice()), Some(&[1.0, 2.0][..]));
5993 /// # Ok::<(), tenferro_tensor::Error>(())
5994 /// ```
5995 fn from_default_scalars(set: crate::DefaultScalars)
5996 -> Option<TypedTensor<Self, DynRank, Host>>;
5997
5998 /// Wrap typed column-major data into a [`Tensor`] enum variant.
5999 ///
6000 /// # Examples
6001 ///
6002 /// ```
6003 /// use tenferro_tensor::{DType, TensorScalar};
6004 ///
6005 /// let tensor = <f64 as TensorScalar>::into_tensor(vec![2], vec![1.0, 2.0])?;
6006 /// assert_eq!(tensor.dtype(), DType::F64);
6007 /// assert_eq!(tensor.shape(), &[2]);
6008 /// assert!(<f64 as TensorScalar>::into_tensor(vec![3], vec![1.0]).is_err());
6009 /// # Ok::<(), tenferro_tensor::Error>(())
6010 /// ```
6011 ///
6012 /// # Errors
6013 ///
6014 /// Returns [`crate::Error::Validation`] with
6015 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
6016 /// the shape product differs from `data.len()`, or
6017 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
6018 /// arithmetic overflows.
6019 fn into_tensor(shape: Vec<usize>, data: Vec<Self>) -> crate::Result<Tensor>;
6020
6021 /// Wrap a typed tensor into its dynamic [`Tensor`] enum variant.
6022 ///
6023 /// # Examples
6024 ///
6025 /// ```
6026 /// use tenferro_tensor::{DType, Tensor, TensorScalar, TypedTensor};
6027 ///
6028 /// let typed = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![3.0])?;
6029 /// let tensor = <f64 as TensorScalar>::typed_tensor_into_tensor(typed);
6030 /// assert!(matches!(tensor.dtype(), DType::F64));
6031 /// # Ok::<(), tenferro_tensor::Error>(())
6032 /// ```
6033 fn typed_tensor_into_tensor(tensor: TypedTensor<Self>) -> Tensor;
6034
6035 /// Borrow a typed tensor as a dtype-erased [`TensorRead`] view.
6036 ///
6037 /// This keeps the typed tensor borrowed instead of copying host data into
6038 /// a new dynamic tensor.
6039 ///
6040 /// # Examples
6041 ///
6042 /// ```
6043 /// use tenferro_tensor::{DType, TensorScalar, TypedTensor};
6044 ///
6045 /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
6046 /// let read = f64::tensor_read(&tensor);
6047 /// assert_eq!(read.dtype(), DType::F64);
6048 /// assert_eq!(read.shape(), &[2]);
6049 /// ```
6050 fn tensor_read(tensor: &TypedTensor<Self>) -> TensorRead<'_>;
6051
6052 /// Wrap a typed borrowed view as a dtype-erased [`TensorView`].
6053 ///
6054 /// # Examples
6055 ///
6056 /// ```
6057 /// use tenferro_tensor::{DType, TensorScalar, TypedTensorView};
6058 ///
6059 /// let data = [1.0_f64];
6060 /// let view = TypedTensorView::from_col_major(&[1], &data)?;
6061 /// assert_eq!(f64::tensor_view(view).dtype(), DType::F64);
6062 /// # Ok::<(), tenferro_tensor::Error>(())
6063 /// ```
6064 fn tensor_view<'a>(view: TypedTensorView<'a, Self>) -> TensorView<'a>;
6065
6066 /// Wrap a typed mutable borrowed view as a dtype-erased [`TensorViewMut`].
6067 ///
6068 /// # Examples
6069 ///
6070 /// ```
6071 /// use tenferro_tensor::{DType, TensorScalar, TypedTensorViewMut};
6072 ///
6073 /// let mut data = [1.0_f64, 2.0];
6074 /// let view = TypedTensorViewMut::from_col_major(&[2], &mut data)?;
6075 /// let erased = f64::tensor_view_mut(view);
6076 /// assert_eq!(erased.dtype(), DType::F64);
6077 /// assert_eq!(erased.shape(), &[2]);
6078 /// # Ok::<(), tenferro_tensor::Error>(())
6079 /// ```
6080 fn tensor_view_mut<'a>(view: TypedTensorViewMut<'a, Self>) -> TensorViewMut<'a>;
6081
6082 /// Mutably borrow a typed tensor as a dtype-erased [`TensorWrite`] view.
6083 ///
6084 /// This keeps the typed output borrowed instead of wrapping it in a
6085 /// temporary dynamic tensor.
6086 ///
6087 /// # Examples
6088 ///
6089 /// ```
6090 /// use tenferro_tensor::{DType, TensorScalar, TypedTensor};
6091 ///
6092 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![0.0]).unwrap();
6093 /// let write = f64::tensor_write(&mut tensor);
6094 /// assert_eq!(write.dtype(), DType::F64);
6095 /// ```
6096 fn tensor_write(tensor: &mut TypedTensor<Self>) -> TensorWrite<'_>;
6097
6098 /// Borrow the host data from a [`Tensor`].
6099 ///
6100 /// # Examples
6101 ///
6102 /// ```
6103 /// use tenferro_tensor::{Tensor, TensorScalar};
6104 ///
6105 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6106 /// assert_eq!(<f64 as TensorScalar>::as_slice(&tensor)?, &[1.0, 2.0]);
6107 /// assert!(<f32 as TensorScalar>::as_slice(&tensor).is_err());
6108 /// # Ok::<(), tenferro_tensor::Error>(())
6109 /// ```
6110 ///
6111 /// # Errors
6112 ///
6113 /// Returns [`crate::Error::Validation`] with
6114 /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `tensor`
6115 /// is not the scalar type represented by this implementation, or
6116 /// [`crate::Error::RuntimeState`] when the matching tensor uses backend
6117 /// storage that has not been downloaded.
6118 fn as_slice(tensor: &Tensor) -> crate::Result<&[Self]>;
6119
6120 /// Mutably borrow the host data from a [`Tensor`].
6121 ///
6122 /// # Examples
6123 ///
6124 /// ```
6125 /// use tenferro_tensor::{Tensor, TensorScalar};
6126 ///
6127 /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?;
6128 /// <f64 as TensorScalar>::as_slice_mut(&mut tensor)?[0] = 3.0;
6129 ///
6130 /// assert_eq!(tensor.as_slice::<f64>()?, &[3.0]);
6131 /// # Ok::<(), tenferro_tensor::Error>(())
6132 /// ```
6133 /// # Errors
6134 ///
6135 /// Returns [`crate::Error::Validation`] with
6136 /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `tensor`
6137 /// is not the scalar type represented by this implementation, or
6138 /// [`crate::Error::RuntimeState`] when the matching tensor uses backend
6139 /// storage that has not been downloaded.
6140 fn as_slice_mut(tensor: &mut Tensor) -> crate::Result<&mut [Self]>;
6141
6142 /// Extract a [`TypedTensor<Self>`] from a dynamic [`Tensor`].
6143 ///
6144 /// # Examples
6145 ///
6146 /// ```
6147 /// use tenferro_tensor::{Tensor, TensorScalar};
6148 ///
6149 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6150 /// let Ok(typed) = <f64 as TensorScalar>::into_typed(tensor) else {
6151 /// panic!("the dtype matches by construction")
6152 /// };
6153 ///
6154 /// assert_eq!(typed.as_slice()?, &[1.0, 2.0]);
6155 /// # Ok::<(), tenferro_tensor::Error>(())
6156 /// ```
6157 /// # Errors
6158 ///
6159 /// Returns [`ReinterpretError`] carrying the unchanged tensor when it is
6160 /// not the scalar type represented by this implementation, with
6161 /// [`crate::Error::Validation`] and
6162 /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] as the cause.
6163 fn into_typed(
6164 tensor: Tensor,
6165 ) -> std::result::Result<TypedTensor<Self>, ReinterpretError<Tensor>>;
6166}
6167
6168mod private {
6169 pub trait Sealed {}
6170
6171 impl Sealed for f64 {}
6172 impl Sealed for f32 {}
6173 impl Sealed for i32 {}
6174 impl Sealed for i64 {}
6175 impl Sealed for bool {}
6176 impl Sealed for num_complex::Complex64 {}
6177 impl Sealed for num_complex::Complex32 {}
6178}
6179
6180macro_rules! impl_tensor_scalar {
6181 ($ty:ty, $real:ty, $dtype:ident, $variant:ident) => {
6182 impl TensorScalar for $ty {
6183 type Real = $real;
6184
6185 #[inline]
6186 fn dtype() -> DType {
6187 DType::$dtype
6188 }
6189
6190 fn into_default_scalars(
6191 shape: Vec<usize>,
6192 data: Vec<Self>,
6193 ) -> crate::Result<crate::DefaultScalars> {
6194 TypedTensor::<Self, DynRank, Host>::from_host_vec_col_major(shape, data).map(
6195 |tensor| {
6196 crate::DefaultScalars::from_payload(
6197 crate::default_scalars::DefaultScalarsValue::$variant(tensor),
6198 )
6199 },
6200 )
6201 }
6202
6203 fn default_scalars_slice(set: &crate::DefaultScalars) -> Option<&[Self]> {
6204 match set.payload() {
6205 crate::default_scalars::DefaultScalarsValue::$variant(tensor) => {
6206 Some(tensor.as_slice())
6207 }
6208 _ => None,
6209 }
6210 }
6211
6212 fn default_scalars_slice_mut(set: &mut crate::DefaultScalars) -> Option<&mut [Self]> {
6213 match set.payload_mut() {
6214 crate::default_scalars::DefaultScalarsValue::$variant(tensor) => {
6215 Some(tensor.host_data_mut())
6216 }
6217 _ => None,
6218 }
6219 }
6220
6221 fn from_default_scalars(
6222 set: crate::DefaultScalars,
6223 ) -> Option<TypedTensor<Self, DynRank, Host>> {
6224 match set.into_payload() {
6225 crate::default_scalars::DefaultScalarsValue::$variant(tensor) => Some(tensor),
6226 _ => None,
6227 }
6228 }
6229
6230 fn into_tensor(shape: Vec<usize>, data: Vec<Self>) -> crate::Result<Tensor> {
6231 TypedTensor::from_vec_col_major(shape, data).map(Self::typed_tensor_into_tensor)
6232 }
6233
6234 fn typed_tensor_into_tensor(tensor: TypedTensor<Self>) -> Tensor {
6235 Tensor {
6236 payload: TensorPayload::Native(PresetTensor::$variant(tensor)),
6237 }
6238 }
6239
6240 fn tensor_read(tensor: &TypedTensor<Self>) -> TensorRead<'_> {
6241 TensorRead::from_view(TensorView::$variant(tensor.as_view()))
6242 }
6243
6244 #[inline]
6245 fn tensor_view<'a>(view: TypedTensorView<'a, Self>) -> TensorView<'a> {
6246 TensorView::$variant(view)
6247 }
6248
6249 #[inline]
6250 fn tensor_view_mut<'a>(view: TypedTensorViewMut<'a, Self>) -> TensorViewMut<'a> {
6251 TensorViewMut::$variant(view)
6252 }
6253
6254 fn tensor_write(tensor: &mut TypedTensor<Self>) -> TensorWrite<'_> {
6255 TensorWrite::from_view(TensorViewMut::$variant(tensor.as_view_mut()))
6256 }
6257
6258 fn as_slice(tensor: &Tensor) -> crate::Result<&[Self]> {
6259 tensor
6260 .as_typed::<Self>()
6261 .ok_or_else(|| {
6262 crate::Error::validation(
6263 "Tensor::as_slice",
6264 ValidationError::DTypeMismatch {
6265 expected: Self::dtype(),
6266 actual: tensor.dtype(),
6267 },
6268 )
6269 })?
6270 .host_data()
6271 }
6272
6273 fn as_slice_mut(tensor: &mut Tensor) -> crate::Result<&mut [Self]> {
6274 let actual = tensor.dtype();
6275 let typed = tensor.as_typed_mut::<Self>().ok_or_else(|| {
6276 crate::Error::validation(
6277 "Tensor::as_slice_mut",
6278 ValidationError::DTypeMismatch {
6279 expected: Self::dtype(),
6280 actual,
6281 },
6282 )
6283 })?;
6284 typed.host_data_mut()
6285 }
6286
6287 fn into_typed(
6288 tensor: Tensor,
6289 ) -> std::result::Result<TypedTensor<Self>, ReinterpretError<Tensor>> {
6290 let actual = tensor.dtype();
6291 match tensor.payload {
6292 TensorPayload::Native(PresetTensor::$variant(typed)) => Ok(typed),
6293 payload => Err(ReinterpretError::new(
6294 Tensor { payload },
6295 crate::Error::validation(
6296 "TensorScalar::into_typed",
6297 ValidationError::DTypeMismatch {
6298 expected: Self::dtype(),
6299 actual,
6300 },
6301 ),
6302 )),
6303 }
6304 }
6305 }
6306 };
6307}
6308
6309impl_tensor_scalar!(f64, f64, F64, F64);
6310impl_tensor_scalar!(f32, f32, F32, F32);
6311impl_tensor_scalar!(i64, i64, I64, I64);
6312impl_tensor_scalar!(i32, i32, I32, I32);
6313impl_tensor_scalar!(bool, bool, Bool, Bool);
6314impl_tensor_scalar!(Complex64, f64, C64, C64);
6315impl_tensor_scalar!(Complex32, f32, C32, C32);
6316
6317/// Dynamic tensor enum over the supported scalar types.
6318///
6319/// The enum keeps dtype dynamic and rank dynamic. Use
6320/// [`TypedTensor<T, R>`](TypedTensor) directly when the scalar type or rank
6321/// should be represented in Rust's type system.
6322///
6323/// # Examples
6324///
6325/// ```rust
6326/// use tenferro_tensor::{Tensor, TypedTensor};
6327///
6328/// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap());
6329/// assert_eq!(t.shape(), &[2]);
6330///
6331/// let erased = Tensor::from_vec_col_major(vec![1, 2], vec![1.0_f64, 2.0]).unwrap();
6332/// assert_eq!(erased.shape().len(), 2);
6333/// ```
6334/// The owning payload behind the erased [`Tensor`].
6335///
6336/// `Native` stores a preset scalar owner directly; `External` retains its
6337/// existing explicit caller-owned host payload.
6338#[derive(Debug)]
6339enum TensorPayload {
6340 Native(PresetTensor),
6341 External(crate::ErasedHostTensor, Placement),
6342}
6343
6344#[derive(Debug)]
6345enum PresetTensor {
6346 F32(TypedTensor<f32>),
6347 F64(TypedTensor<f64>),
6348 I32(TypedTensor<i32>),
6349 I64(TypedTensor<i64>),
6350 Bool(TypedTensor<bool>),
6351 C32(TypedTensor<Complex32>),
6352 C64(TypedTensor<Complex64>),
6353}
6354
6355macro_rules! with_preset {
6356 ($preset:expr, |$value:ident| $body:expr) => {
6357 match $preset {
6358 PresetTensor::F32($value) => $body,
6359 PresetTensor::F64($value) => $body,
6360 PresetTensor::I32($value) => $body,
6361 PresetTensor::I64($value) => $body,
6362 PresetTensor::Bool($value) => $body,
6363 PresetTensor::C32($value) => $body,
6364 PresetTensor::C64($value) => $body,
6365 }
6366 };
6367}
6368
6369/// Dynamic tensor over the supported scalar types.
6370///
6371/// The erased tensor keeps dtype and rank dynamic: each preset scalar retains its
6372/// typed owner without constructing a group, while caller-owned scalars remain
6373/// `External` payloads recovered by their own type. Use [`TypedTensor<T, R>`](TypedTensor)
6374/// directly when the scalar type or rank should be represented in Rust's type system.
6375///
6376/// # Examples
6377///
6378/// ```
6379/// use tenferro_tensor::{DType, Tensor};
6380///
6381/// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6382/// assert_eq!(tensor.dtype(), DType::F64);
6383/// # Ok::<(), tenferro_tensor::Error>(())
6384/// ```
6385#[derive(Debug)]
6386pub struct Tensor {
6387 payload: TensorPayload,
6388}
6389
6390impl<R: TensorRank> OwnedTensorGroup<R> {
6391 /// Whether this group's slot is host-addressed memory.
6392 fn payload_is_host_memory(&self) -> bool {
6393 !self.group.slot_root_is_backend(self.slot)
6394 }
6395
6396 /// Whether this group's descriptor names a non-CPU provider.
6397 fn is_backend_buffer(&self) -> bool {
6398 !matches!(
6399 self.group.provider_kind(self.slot),
6400 None | Some(crate::storage::ProviderKind::Cpu)
6401 )
6402 }
6403}
6404
6405impl Tensor {
6406 /// Carry an externally defined scalar as a caller-owned payload.
6407 ///
6408 /// The payload keeps its own element type and is recovered by that type, so no
6409 /// bytes are reinterpreted. Placement defaults to unpinned host memory, which
6410 /// is where a caller-owned payload lives.
6411 ///
6412 /// # Examples
6413 ///
6414 /// ```rust
6415 /// use tenferro_tensor::{DType, Tensor};
6416 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6417 ///
6418 /// let payload = ErasedHostTensor::new(
6419 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6420 /// );
6421 /// let element = payload.element_type_id();
6422 /// let tensor = Tensor::external(payload);
6423 /// assert_eq!(tensor.dtype(), DType::External(element));
6424 /// assert_eq!(tensor.shape(), &[1]);
6425 /// # Ok::<(), tenferro_tensor::Error>(())
6426 /// ```
6427 #[must_use]
6428 pub fn external(payload: crate::ErasedHostTensor) -> Self {
6429 Self {
6430 payload: TensorPayload::External(payload, Placement::default()),
6431 }
6432 }
6433
6434 /// Build a tensor from a typed one, without naming its variant.
6435 ///
6436 /// A call site that constructs a tensor from a typed tensor should use this rather than a variant, so
6437 /// that changing how the erased representation is stored changes this function and not its 1290 call
6438 /// sites. The variants remain until the removal's last step, so both forms currently produce the same
6439 /// value.
6440 ///
6441 /// # Examples
6442 ///
6443 /// ```
6444 /// use tenferro_tensor::Tensor;
6445 ///
6446 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
6447 /// let typed = tensor.into_typed::<f64>().unwrap();
6448 /// let rebuilt = Tensor::from_typed(typed);
6449 /// assert_eq!(rebuilt.as_typed::<f64>().unwrap().shape(), &[2]);
6450 /// # Ok::<(), tenferro_tensor::Error>(())
6451 /// ```
6452 #[must_use]
6453 pub fn from_typed<T: TensorScalar>(typed: TypedTensor<T>) -> Self {
6454 T::typed_tensor_into_tensor(typed)
6455 }
6456
6457 /// Borrow the erased payload of an externally defined tensor.
6458 ///
6459 /// This is the counterpart of [`Tensor::external`] for dispatch: a table that matches on
6460 /// [`Tensor::dtype`] reaches the externally defined tag and needs the payload that tag stands
6461 /// for, just as the typed tags reach theirs through [`Tensor::as_typed`]. Every other tag
6462 /// returns `None`.
6463 ///
6464 /// # Examples
6465 ///
6466 /// ```
6467 /// use tenferro_tensor::Tensor;
6468 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6469 ///
6470 /// let payload = ErasedHostTensor::new(
6471 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6472 /// );
6473 /// let tensor = Tensor::external(payload);
6474 /// assert!(tensor.external_payload().is_some());
6475 /// # Ok::<(), tenferro_tensor::Error>(())
6476 /// ```
6477 #[must_use]
6478 pub fn external_payload(&self) -> Option<&crate::ErasedHostTensor> {
6479 match &self.payload {
6480 TensorPayload::External(payload, _) => Some(payload),
6481 TensorPayload::Native(_) => None,
6482 }
6483 }
6484
6485 /// Carry an externally defined payload with an explicit placement.
6486 ///
6487 /// [`Tensor::external`] defaults the placement to unpinned host memory, which is where
6488 /// a caller-owned payload normally lives; this entry point is for a caller that knows
6489 /// the placement it wants.
6490 ///
6491 /// # Examples
6492 ///
6493 /// ```
6494 /// use tenferro_tensor::{Placement, Tensor};
6495 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6496 ///
6497 /// let payload = ErasedHostTensor::new(
6498 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6499 /// );
6500 /// let tensor = Tensor::external_with_placement(payload, Placement::default());
6501 /// assert!(tensor.external_payload().is_some());
6502 /// # Ok::<(), tenferro_tensor::Error>(())
6503 /// ```
6504 #[must_use]
6505 pub fn external_with_placement(payload: crate::ErasedHostTensor, placement: Placement) -> Self {
6506 Self {
6507 payload: TensorPayload::External(payload, placement),
6508 }
6509 }
6510
6511 /// Mutably borrow the erased payload of an externally defined tensor.
6512 ///
6513 /// The counterpart of [`Tensor::external_payload`] for callers that update the payload
6514 /// in place, such as a mutation test that checks the copy boundary.
6515 ///
6516 /// # Examples
6517 ///
6518 /// ```
6519 /// use tenferro_tensor::Tensor;
6520 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, TypedTensor};
6521 ///
6522 /// let mut tensor = Tensor::external(ErasedHostTensor::new(
6523 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![1.0_f64])?,
6524 /// ));
6525 /// assert!(tensor.external_payload_mut().is_some());
6526 /// # Ok::<(), tenferro_tensor::Error>(())
6527 /// ```
6528 #[must_use]
6529 pub fn external_payload_mut(&mut self) -> Option<&mut crate::ErasedHostTensor> {
6530 match &mut self.payload {
6531 TensorPayload::External(payload, _) => Some(payload),
6532 TensorPayload::Native(_) => None,
6533 }
6534 }
6535
6536 pub(crate) fn into_group_parts(self) -> (AllocationGroup, DescriptorSlot) {
6537 match self.payload {
6538 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.into_group_parts()),
6539 // INVARIANT: a caller-owned payload has no allocation group.
6540 TensorPayload::External(..) => {
6541 unreachable!("an externally defined payload has no allocation group")
6542 }
6543 }
6544 }
6545}
6546
6547/// Dynamic read-only borrowed tensor view.
6548///
6549/// `TensorView` keeps dtype erased while borrowing typed view metadata and
6550/// storage. Use [`TypedTensorView`] directly when the scalar type is statically
6551/// known.
6552///
6553/// # Examples
6554///
6555/// ```
6556/// use tenferro_tensor::{DType, TensorView, TypedTensorView};
6557///
6558/// let data = [1_i32, 2, 3, 4];
6559/// let typed = TypedTensorView::from_slice([2, 2], [1, 2], 0, &data)?;
6560/// let view = TensorView::I32(typed);
6561///
6562/// assert_eq!(view.dtype(), DType::I32);
6563/// assert_eq!(view.shape(), &[2, 2]);
6564/// # Ok::<(), tenferro_tensor::Error>(())
6565/// ```
6566///
6567/// `D` marks the representation the view was proven to borrow, as on
6568/// [`TypedTensorView`]. The default [`Dynamic`] view may borrow host or backend
6569/// storage; a `TensorView<'a, Host>` comes only from
6570/// [`TensorView::try_host`] or [`TensorRead::try_host`], so every arm borrows
6571/// host storage and a consumer reads it without a further placement check.
6572#[derive(Debug)]
6573pub enum TensorView<'a, D: Representation = Dynamic> {
6574 F32(TypedTensorView<'a, f32, DynRank, D>),
6575 F64(TypedTensorView<'a, f64, DynRank, D>),
6576 I32(TypedTensorView<'a, i32, DynRank, D>),
6577 I64(TypedTensorView<'a, i64, DynRank, D>),
6578 Bool(TypedTensorView<'a, bool, DynRank, D>),
6579 C32(TypedTensorView<'a, Complex<f32>, DynRank, D>),
6580 C64(TypedTensorView<'a, Complex<f64>, DynRank, D>),
6581}
6582
6583// Written by hand because the representation markers are not `Clone`: the
6584// derive would demand `D: Clone` although no marker value is ever stored.
6585impl<D: Representation> Clone for TensorView<'_, D> {
6586 fn clone(&self) -> Self {
6587 match self {
6588 Self::F32(view) => Self::F32(view.clone()),
6589 Self::F64(view) => Self::F64(view.clone()),
6590 Self::I32(view) => Self::I32(view.clone()),
6591 Self::I64(view) => Self::I64(view.clone()),
6592 Self::Bool(view) => Self::Bool(view.clone()),
6593 Self::C32(view) => Self::C32(view.clone()),
6594 Self::C64(view) => Self::C64(view.clone()),
6595 }
6596 }
6597}
6598
6599/// Apply one expression to every arm of a [`TensorView`], keeping the arm.
6600macro_rules! map_tensor_view {
6601 ($view:expr, |$typed:ident| $body:expr) => {
6602 match $view {
6603 TensorView::F32($typed) => TensorView::F32($body),
6604 TensorView::F64($typed) => TensorView::F64($body),
6605 TensorView::I32($typed) => TensorView::I32($body),
6606 TensorView::I64($typed) => TensorView::I64($body),
6607 TensorView::Bool($typed) => TensorView::Bool($body),
6608 TensorView::C32($typed) => TensorView::C32($body),
6609 TensorView::C64($typed) => TensorView::C64($body),
6610 }
6611 };
6612}
6613
6614impl<'a> TensorView<'a> {
6615 /// Checked narrowing of a dtype-erased view to the host representation.
6616 ///
6617 /// See [`TypedTensorView::try_host`]: the narrowing succeeds exactly when
6618 /// the view borrows host elements, and a consumer of the
6619 /// `TensorView<'a, Host>` it returns needs no further placement check.
6620 ///
6621 /// # Examples
6622 ///
6623 /// ```rust
6624 /// use tenferro_tensor::{DType, TensorView};
6625 ///
6626 /// let host = TensorView::f64(&[2], &[1.0, 2.0])?.try_host("example")?;
6627 /// assert_eq!(host.dtype(), DType::F64);
6628 /// assert_eq!(host.shape(), &[2]);
6629 /// # Ok::<(), tenferro_tensor::Error>(())
6630 /// ```
6631 ///
6632 /// # Errors
6633 ///
6634 /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
6635 /// borrows backend (device) storage; download the tensor to host first.
6636 pub fn try_host(self, op: &'static str) -> crate::Result<TensorView<'a, Host>> {
6637 Ok(map_tensor_view!(self, |view| view.try_host(op)?))
6638 }
6639}
6640
6641impl<'a> TensorView<'a, Host> {
6642 /// Widen a host-marked view to the runtime union without copying.
6643 ///
6644 /// # Examples
6645 ///
6646 /// ```rust
6647 /// use tenferro_tensor::{DType, TensorView};
6648 ///
6649 /// let host = TensorView::i32(&[2], &[3, 4])?.try_host("example")?;
6650 /// let dynamic = host.into_dynamic();
6651 /// assert_eq!(dynamic.as_slice::<i32>()?, &[3, 4]);
6652 /// # Ok::<(), tenferro_tensor::Error>(())
6653 /// ```
6654 pub fn into_dynamic(self) -> TensorView<'a> {
6655 map_tensor_view!(self, |view| view.into_dynamic())
6656 }
6657
6658 /// The element dtype of this host view.
6659 ///
6660 /// # Examples
6661 ///
6662 /// ```rust
6663 /// use tenferro_tensor::{DType, TensorView};
6664 ///
6665 /// let host = TensorView::i64(&[1], &[7])?.try_host("example")?;
6666 /// assert_eq!(host.dtype(), DType::I64);
6667 /// # Ok::<(), tenferro_tensor::Error>(())
6668 /// ```
6669 pub fn dtype(&self) -> DType {
6670 match self {
6671 Self::F32(_) => DType::F32,
6672 Self::F64(_) => DType::F64,
6673 Self::I32(_) => DType::I32,
6674 Self::I64(_) => DType::I64,
6675 Self::Bool(_) => DType::Bool,
6676 Self::C32(_) => DType::C32,
6677 Self::C64(_) => DType::C64,
6678 }
6679 }
6680
6681 /// The logical shape of this host view.
6682 ///
6683 /// # Examples
6684 ///
6685 /// ```rust
6686 /// use tenferro_tensor::TensorView;
6687 ///
6688 /// let host = TensorView::f32(&[2], &[1.0, 2.0])?.try_host("example")?;
6689 /// assert_eq!(host.shape(), &[2]);
6690 /// # Ok::<(), tenferro_tensor::Error>(())
6691 /// ```
6692 pub fn shape(&self) -> &[usize] {
6693 match self {
6694 Self::F32(view) => view.shape(),
6695 Self::F64(view) => view.shape(),
6696 Self::I32(view) => view.shape(),
6697 Self::I64(view) => view.shape(),
6698 Self::Bool(view) => view.shape(),
6699 Self::C32(view) => view.shape(),
6700 Self::C64(view) => view.shape(),
6701 }
6702 }
6703
6704 /// Whether the view covers its whole host buffer in compact column-major
6705 /// order from offset zero, so it reads exactly like an owned tensor.
6706 ///
6707 /// # Examples
6708 ///
6709 /// ```rust
6710 /// use tenferro_tensor::{Tensor, TensorRead};
6711 ///
6712 /// let tensor = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
6713 /// let host = TensorRead::from_tensor(&tensor).try_host("example")?;
6714 /// assert!(host.is_owned_layout());
6715 /// # Ok::<(), tenferro_tensor::Error>(())
6716 /// ```
6717 pub fn is_owned_layout(&self) -> bool {
6718 fn owned<T: 'static>(view: &TypedTensorView<'_, T, DynRank, Host>) -> bool {
6719 view.offset() == 0
6720 && view.backing_len() == view.n_elements()
6721 && matches!(view.is_col_major_contiguous(), Ok(true))
6722 }
6723 match self {
6724 Self::F32(view) => owned(view),
6725 Self::F64(view) => owned(view),
6726 Self::I32(view) => owned(view),
6727 Self::I64(view) => owned(view),
6728 Self::Bool(view) => owned(view),
6729 Self::C32(view) => owned(view),
6730 Self::C64(view) => owned(view),
6731 }
6732 }
6733}
6734
6735/// Dynamic mutable borrowed tensor view.
6736///
6737/// `TensorViewMut` is the mutable counterpart to [`TensorView`]. It keeps the
6738/// dtype erased while preserving the typed mutable view's shape, strides, and
6739/// offset metadata.
6740///
6741/// # Examples
6742///
6743/// ```
6744/// use tenferro_tensor::{DType, TensorViewMut, TypedTensorViewMut};
6745///
6746/// let mut data = [1.0_f64, 2.0];
6747/// let view = TensorViewMut::F64(TypedTensorViewMut::from_slice([2], [1], 0, &mut data)?);
6748/// assert_eq!(view.dtype(), DType::F64);
6749/// # Ok::<(), tenferro_tensor::Error>(())
6750/// ```
6751///
6752/// `D` marks the representation the view was proven to borrow, as on
6753/// [`TypedTensorViewMut`]. The default [`Dynamic`] view may borrow host or
6754/// backend storage; a `TensorViewMut<'a, Host>` comes only from
6755/// [`TensorViewMut::try_mut_host`] or [`TensorWrite::try_mut_host`], so every
6756/// arm borrows host storage and a consumer writes it without a further
6757/// placement check.
6758#[allow(clippy::large_enum_variant)]
6759#[derive(Debug)]
6760pub enum TensorViewMut<'a, D: Representation = Dynamic> {
6761 F32(TypedTensorViewMut<'a, f32, DynRank, D>),
6762 F64(TypedTensorViewMut<'a, f64, DynRank, D>),
6763 I32(TypedTensorViewMut<'a, i32, DynRank, D>),
6764 I64(TypedTensorViewMut<'a, i64, DynRank, D>),
6765 Bool(TypedTensorViewMut<'a, bool, DynRank, D>),
6766 C32(TypedTensorViewMut<'a, Complex<f32>, DynRank, D>),
6767 C64(TypedTensorViewMut<'a, Complex<f64>, DynRank, D>),
6768}
6769
6770/// Apply one expression to every arm of a [`TensorViewMut`], keeping the arm.
6771macro_rules! map_tensor_view_mut {
6772 ($view:expr, |$typed:ident| $body:expr) => {
6773 match $view {
6774 TensorViewMut::F32($typed) => TensorViewMut::F32($body),
6775 TensorViewMut::F64($typed) => TensorViewMut::F64($body),
6776 TensorViewMut::I32($typed) => TensorViewMut::I32($body),
6777 TensorViewMut::I64($typed) => TensorViewMut::I64($body),
6778 TensorViewMut::Bool($typed) => TensorViewMut::Bool($body),
6779 TensorViewMut::C32($typed) => TensorViewMut::C32($body),
6780 TensorViewMut::C64($typed) => TensorViewMut::C64($body),
6781 }
6782 };
6783}
6784
6785impl<'a> TensorViewMut<'a> {
6786 /// Checked narrowing of a dtype-erased mutable view to the host
6787 /// representation.
6788 ///
6789 /// See [`TypedTensorViewMut::try_mut_host`]: the narrowing succeeds exactly
6790 /// when the view borrows host elements, and a consumer of the
6791 /// `TensorViewMut<'a, Host>` it returns needs no further placement check.
6792 ///
6793 /// # Examples
6794 ///
6795 /// ```rust
6796 /// use tenferro_tensor::{DType, TensorViewMut};
6797 ///
6798 /// let mut data = [1.0_f64, 2.0];
6799 /// let host = TensorViewMut::f64(&[2], &mut data)?.try_mut_host("example")?;
6800 /// assert_eq!(host.dtype(), DType::F64);
6801 /// assert_eq!(host.shape(), &[2]);
6802 /// # Ok::<(), tenferro_tensor::Error>(())
6803 /// ```
6804 ///
6805 /// # Errors
6806 ///
6807 /// Returns [`crate::Error::RuntimeState`] attributed to `op` when the view
6808 /// borrows backend (device) storage; download the tensor to host first.
6809 pub fn try_mut_host(self, op: &'static str) -> crate::Result<TensorViewMut<'a, Host>> {
6810 Ok(map_tensor_view_mut!(self, |view| view.try_mut_host(op)?))
6811 }
6812}
6813
6814impl<'a> TensorViewMut<'a, Host> {
6815 /// Widen a host-marked mutable view to the runtime union without copying.
6816 ///
6817 /// # Examples
6818 ///
6819 /// ```rust
6820 /// use tenferro_tensor::TensorViewMut;
6821 ///
6822 /// let mut data = [3_i32, 4];
6823 /// let host = TensorViewMut::i32(&[2], &mut data)?.try_mut_host("example")?;
6824 /// let dynamic = host.into_dynamic();
6825 /// assert_eq!(dynamic.as_read_only().as_slice::<i32>()?, &[3, 4]);
6826 /// # Ok::<(), tenferro_tensor::Error>(())
6827 /// ```
6828 pub fn into_dynamic(self) -> TensorViewMut<'a> {
6829 map_tensor_view_mut!(self, |view| view.into_dynamic())
6830 }
6831
6832 /// The element dtype of this host view.
6833 ///
6834 /// # Examples
6835 ///
6836 /// ```rust
6837 /// use tenferro_tensor::{DType, TensorViewMut};
6838 ///
6839 /// let mut data = [7_i64];
6840 /// let host = TensorViewMut::i64(&[1], &mut data)?.try_mut_host("example")?;
6841 /// assert_eq!(host.dtype(), DType::I64);
6842 /// # Ok::<(), tenferro_tensor::Error>(())
6843 /// ```
6844 pub fn dtype(&self) -> DType {
6845 match self {
6846 Self::F32(_) => DType::F32,
6847 Self::F64(_) => DType::F64,
6848 Self::I32(_) => DType::I32,
6849 Self::I64(_) => DType::I64,
6850 Self::Bool(_) => DType::Bool,
6851 Self::C32(_) => DType::C32,
6852 Self::C64(_) => DType::C64,
6853 }
6854 }
6855
6856 /// The logical shape of this host view.
6857 ///
6858 /// # Examples
6859 ///
6860 /// ```rust
6861 /// use tenferro_tensor::TensorViewMut;
6862 ///
6863 /// let mut data = [1.0_f32, 2.0];
6864 /// let host = TensorViewMut::f32(&[2], &mut data)?.try_mut_host("example")?;
6865 /// assert_eq!(host.shape(), &[2]);
6866 /// # Ok::<(), tenferro_tensor::Error>(())
6867 /// ```
6868 pub fn shape(&self) -> &[usize] {
6869 match self {
6870 Self::F32(view) => view.shape(),
6871 Self::F64(view) => view.shape(),
6872 Self::I32(view) => view.shape(),
6873 Self::I64(view) => view.shape(),
6874 Self::Bool(view) => view.shape(),
6875 Self::C32(view) => view.shape(),
6876 Self::C64(view) => view.shape(),
6877 }
6878 }
6879
6880 /// The strides of this host view in element units.
6881 ///
6882 /// # Examples
6883 ///
6884 /// ```rust
6885 /// use tenferro_tensor::TensorViewMut;
6886 ///
6887 /// let mut data = [0.0_f64; 6];
6888 /// let host = TensorViewMut::f64(&[2, 3], &mut data)?.try_mut_host("example")?;
6889 /// assert_eq!(host.strides(), &[1, 2]);
6890 /// # Ok::<(), tenferro_tensor::Error>(())
6891 /// ```
6892 pub fn strides(&self) -> &[isize] {
6893 match self {
6894 Self::F32(view) => view.strides(),
6895 Self::F64(view) => view.strides(),
6896 Self::I32(view) => view.strides(),
6897 Self::I64(view) => view.strides(),
6898 Self::Bool(view) => view.strides(),
6899 Self::C32(view) => view.strides(),
6900 Self::C64(view) => view.strides(),
6901 }
6902 }
6903}
6904
6905/// Read-only tensor input accepted by synchronous eager kernels.
6906///
6907/// `TensorRead` lets kernels accept either an owned tensor reference or a
6908/// borrowed [`TensorView`] without forcing callers to materialize first.
6909/// The `View` variant preserves arbitrary strides and offsets, so kernels that
6910/// support strided reads can consume transposes, slices, and broadcasts directly.
6911///
6912/// `TensorRead` is intentionally borrowed. It is an input-dispatch type, not an
6913/// owned lazy tensor value. APIs that need to store a lazy layout result should
6914/// keep an owned base tensor plus layout metadata, then expose a `TensorRead`
6915/// only for the duration of kernel dispatch.
6916///
6917/// # Examples
6918///
6919/// ```
6920/// use tenferro_tensor::{DType, Tensor, TensorRead};
6921///
6922/// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
6923/// let read = TensorRead::from_tensor(&tensor);
6924///
6925/// assert_eq!(read.dtype(), DType::F64);
6926/// assert_eq!(read.shape(), &[2]);
6927/// ```
6928// Keep borrowed views inline to avoid allocation on read-only tensor dispatch paths.
6929#[allow(clippy::large_enum_variant)]
6930#[derive(Clone, Debug)]
6931pub enum TensorRead<'a> {
6932 Tensor(&'a Tensor),
6933 View(TensorView<'a>),
6934}
6935
6936/// Mutable typed tensor output accepted by synchronous eager kernels.
6937///
6938/// `TypedTensorWrite` is the typed counterpart to [`TensorWrite`]. It accepts
6939/// either an owned compact [`TypedTensor`] or an arbitrary-strided mutable
6940/// [`TypedTensorViewMut`] without erasing the scalar type at the public API
6941/// boundary.
6942///
6943/// # Examples
6944///
6945/// ```
6946/// use tenferro_tensor::{TypedTensorViewMut, TypedTensorWrite};
6947///
6948/// let mut data = [0.0_f64, 1.0, 0.0, 2.0];
6949/// let view = TypedTensorViewMut::from_slice([2], [2], 1, &mut data)?;
6950/// let write = TypedTensorWrite::from_view(view).into_tensor_write();
6951/// assert_eq!(write.shape(), &[2]);
6952/// assert_eq!(write.strides()?, [2]);
6953/// # Ok::<(), tenferro_tensor::Error>(())
6954/// ```
6955#[allow(clippy::large_enum_variant)]
6956#[derive(Debug)]
6957pub enum TypedTensorWrite<'a, T> {
6958 /// An owned compact typed tensor borrowed mutably for the write.
6959 Tensor(&'a mut TypedTensor<T>),
6960 /// An arbitrary-strided mutable typed tensor view.
6961 View(TypedTensorViewMut<'a, T>),
6962}
6963
6964impl<'a, T> TypedTensorWrite<'a, T> {
6965 /// Create a writable target from an owned typed tensor.
6966 ///
6967 /// # Examples
6968 ///
6969 /// ```
6970 /// use tenferro_tensor::{TypedTensor, TypedTensorWrite};
6971 ///
6972 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![0.0])?;
6973 /// let write = TypedTensorWrite::from_tensor(&mut tensor);
6974 /// assert!(matches!(write, TypedTensorWrite::Tensor(_)));
6975 /// # Ok::<(), tenferro_tensor::Error>(())
6976 /// ```
6977 pub fn from_tensor(tensor: &'a mut TypedTensor<T>) -> Self {
6978 Self::Tensor(tensor)
6979 }
6980
6981 /// Create a writable target from a mutable typed tensor view.
6982 ///
6983 /// # Examples
6984 ///
6985 /// ```
6986 /// use tenferro_tensor::{TypedTensorViewMut, TypedTensorWrite};
6987 ///
6988 /// let mut data = [0.0_f64, 1.0];
6989 /// let view = TypedTensorViewMut::from_col_major(&[2], &mut data)?;
6990 /// let write = TypedTensorWrite::from_view(view);
6991 /// assert!(matches!(write, TypedTensorWrite::View(_)));
6992 /// # Ok::<(), tenferro_tensor::Error>(())
6993 /// ```
6994 pub fn from_view(view: TypedTensorViewMut<'a, T>) -> Self {
6995 Self::View(view)
6996 }
6997}
6998
6999impl<'a, T: TensorScalar> TypedTensorWrite<'a, T> {
7000 /// Erase the scalar type while preserving the output layout.
7001 ///
7002 /// # Examples
7003 ///
7004 /// ```
7005 /// use tenferro_tensor::{DType, TypedTensor, TypedTensorWrite};
7006 ///
7007 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![0.0; 2])?;
7008 /// let write = TypedTensorWrite::from_tensor(&mut tensor).into_tensor_write();
7009 /// assert_eq!(write.dtype(), DType::F64);
7010 /// assert_eq!(write.shape(), &[2]);
7011 /// # Ok::<(), tenferro_tensor::Error>(())
7012 /// ```
7013 pub fn into_tensor_write(self) -> TensorWrite<'a> {
7014 match self {
7015 Self::Tensor(tensor) => T::tensor_write(tensor),
7016 Self::View(view) => TensorWrite::from_view(T::tensor_view_mut(view)),
7017 }
7018 }
7019}
7020
7021impl<'a, T> From<&'a mut TypedTensor<T>> for TypedTensorWrite<'a, T> {
7022 fn from(tensor: &'a mut TypedTensor<T>) -> Self {
7023 Self::from_tensor(tensor)
7024 }
7025}
7026
7027impl<'a, T> From<TypedTensorViewMut<'a, T>> for TypedTensorWrite<'a, T> {
7028 fn from(view: TypedTensorViewMut<'a, T>) -> Self {
7029 Self::from_view(view)
7030 }
7031}
7032
7033/// Mutable tensor output accepted by synchronous eager kernels.
7034///
7035/// `TensorWrite` mirrors [`TensorRead`] for output dispatch: it can target an
7036/// owned compact [`Tensor`] or a borrowed mutable [`TensorViewMut`]. The target
7037/// is never resized.
7038///
7039/// # Examples
7040///
7041/// ```
7042/// use tenferro_tensor::{Tensor, TensorWrite};
7043///
7044/// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?;
7045/// let write = TensorWrite::from_tensor(&mut tensor);
7046/// assert_eq!(write.shape(), &[1]);
7047/// # Ok::<(), tenferro_tensor::Error>(())
7048/// ```
7049#[allow(clippy::large_enum_variant)]
7050#[derive(Debug)]
7051pub enum TensorWrite<'a> {
7052 Tensor(&'a mut Tensor),
7053 View(TensorViewMut<'a>),
7054}
7055
7056/// Owned tensor value with one move-only physical owner and metadata-only layout.
7057///
7058/// `TensorValue` is intentionally not cloneable. View transformations consume
7059/// the value and move its existing owner; [`TensorValue::duplicate`] is the
7060/// explicit boundary for creating another physical allocation.
7061///
7062/// # Examples
7063///
7064/// ```
7065/// use tenferro_tensor::{Tensor, TensorValue};
7066/// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7067/// let view = value.transpose_view([1, 0])?;
7068/// assert_eq!(view.strides(), &[2, 1]);
7069/// assert!(view.is_view());
7070/// # Ok::<(), tenferro_tensor::Error>(())
7071/// ```
7072#[derive(Debug)]
7073pub struct TensorValue {
7074 owner: Tensor,
7075 layout: TensorLayout<DynRank>,
7076}
7077
7078/// A consuming view transformation failed while retaining its unchanged owner.
7079///
7080/// # Examples
7081///
7082/// ```
7083/// use tenferro_tensor::{Tensor, TensorValue};
7084/// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7085/// let failure = value.try_reshape_view([3]).unwrap_err();
7086/// let (recovered, cause) = failure.into_parts();
7087/// assert_eq!(recovered.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7088/// assert!(matches!(cause, tenferro_tensor::Error::Validation { .. }));
7089/// # Ok::<(), tenferro_tensor::Error>(())
7090/// ```
7091#[derive(Debug)]
7092pub struct TensorValueViewError {
7093 value: TensorValue,
7094 source: crate::Error,
7095}
7096
7097impl TensorValueViewError {
7098 /// Return the unchanged value and the typed validation/backend error.
7099 ///
7100 /// # Examples
7101 ///
7102 /// ```
7103 /// use tenferro_tensor::{Tensor, TensorValue};
7104 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([1], vec![7.])?);
7105 /// let (value, error) = value.try_reshape_view([2]).unwrap_err().into_parts();
7106 /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[7.]);
7107 /// assert!(matches!(error, tenferro_tensor::Error::Validation { .. }));
7108 /// # Ok::<(), tenferro_tensor::Error>(())
7109 /// ```
7110 pub fn into_parts(self) -> (TensorValue, crate::Error) {
7111 (self.value, self.source)
7112 }
7113
7114 fn new(value: TensorValue, source: crate::Error) -> Self {
7115 Self { value, source }
7116 }
7117}
7118
7119impl std::fmt::Display for TensorValueViewError {
7120 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
7121 std::fmt::Display::fmt(&self.source, formatter)
7122 }
7123}
7124
7125impl std::error::Error for TensorValueViewError {
7126 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
7127 Some(&self.source)
7128 }
7129}
7130
7131impl TensorValue {
7132 /// Explicitly duplicate the physical owner represented by this value.
7133 ///
7134 /// # Examples
7135 ///
7136 /// ```
7137 /// use tenferro_tensor::{Tensor, TensorValue};
7138 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7139 /// let copy = value.duplicate()?.into_tensor()?;
7140 /// assert_eq!(copy.as_slice::<f64>()?, &[3., 4.]);
7141 /// assert_eq!(value.shape(), &[2]);
7142 /// # Ok::<(), tenferro_tensor::Error>(())
7143 /// ```
7144 ///
7145 /// # Errors
7146 ///
7147 /// Returns [`crate::Error::RuntimeState`] or [`crate::Error::Unsupported`]
7148 /// when the backend/storage owner cannot be duplicated.
7149 pub fn duplicate(&self) -> crate::Result<Self> {
7150 let tensor = duplicate_backing_storage(&self.owner)?;
7151 Self::from_parts(
7152 tensor,
7153 self.shape().to_vec(),
7154 self.strides().to_vec(),
7155 self.offset(),
7156 )
7157 }
7158
7159 /// Retain a compact tensor as a move-only value.
7160 ///
7161 /// # Examples
7162 ///
7163 /// ```
7164 /// use tenferro_tensor::{Tensor, TensorValue};
7165 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7166 /// assert!(!value.is_view());
7167 /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7168 /// # Ok::<(), tenferro_tensor::Error>(())
7169 /// ```
7170 pub fn from_tensor(tensor: Tensor) -> Self {
7171 let layout = tensor_layout(&tensor);
7172 Self {
7173 owner: tensor,
7174 layout,
7175 }
7176 }
7177
7178 /// # Errors
7179 ///
7180 /// Returns [`ValidationError::InvalidArgument`] or
7181 /// [`ValidationError::IntegerOverflow`] when the supplied layout is
7182 /// invalid for the tensor's physical buffer.
7183 ///
7184 /// # Examples
7185 ///
7186 /// ```
7187 /// use tenferro_tensor::{Tensor, TensorValue};
7188 /// let tensor = Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
7189 /// let view = TensorValue::from_parts(tensor, vec![2], vec![1], 2)?;
7190 /// assert_eq!(view.shape(), &[2]);
7191 /// assert_eq!(view.offset(), 2);
7192 /// # Ok::<(), tenferro_tensor::Error>(())
7193 /// ```
7194 pub fn from_parts(
7195 tensor: Tensor,
7196 shape: Vec<usize>,
7197 strides: Vec<isize>,
7198 offset: isize,
7199 ) -> crate::Result<Self> {
7200 let layout = TensorLayout::from_parts(
7201 shape_vec(&shape),
7202 stride_vec(&strides),
7203 offset,
7204 tensor_buffer_len(&tensor),
7205 )
7206 .map_err(|err| tensor_layout_error("TensorValue::from_parts", err))?;
7207 Ok(Self {
7208 owner: tensor,
7209 layout,
7210 })
7211 }
7212
7213 // INVARIANT: unchanged-owner recovery is part of the consuming ownership
7214 // contract, so this intentionally carries the large move-only error.
7215 #[doc(hidden)]
7216 /// Move the value's sole physical owner into an allocation group.
7217 ///
7218 /// This preserves metadata-only views without copying. The consumed value
7219 /// always contains one unique owner, so no compatibility fallback exists.
7220 ///
7221 /// # Errors
7222 ///
7223 /// Returns the unchanged value when descriptor publication fails because
7224 /// of [`ValidationError::InvalidArgument`] or
7225 /// [`ValidationError::IntegerOverflow`].
7226 #[allow(clippy::result_large_err)]
7227 pub fn try_into_group_parts(
7228 self,
7229 ) -> std::result::Result<(AllocationGroup, DescriptorSlot, DType, Vec<usize>), Self> {
7230 let Self { owner, layout } = self;
7231 if owner.external_payload().is_some() {
7232 // A caller-owned payload owns no allocation group, so it is returned
7233 // unchanged instead of being forced into one.
7234 return Err(Self { owner, layout });
7235 }
7236 let dtype = owner.dtype();
7237 let shape = layout.shape().to_vec();
7238 let strides = layout.strides().to_vec();
7239 let offset = layout.offset();
7240 let (group, slot) = owner.into_group_parts();
7241 match group.update_descriptor_layout(slot, shape, strides, offset) {
7242 Ok(group) => Ok((group, slot, dtype, layout.shape().to_vec())),
7243 Err((_group, _error)) => {
7244 unreachable!("TensorValue layout was validated before group ownership transfer")
7245 }
7246 }
7247 }
7248
7249 /// Consume a value with its owner's original layout and return that owner.
7250 ///
7251 /// # Examples
7252 ///
7253 /// ```
7254 /// use tenferro_tensor::{Tensor, TensorValue};
7255 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7256 /// assert_eq!(value.into_tensor()?.as_slice::<f64>()?, &[3., 4.]);
7257 /// # Ok::<(), tenferro_tensor::Error>(())
7258 /// ```
7259 ///
7260 /// # Errors
7261 ///
7262 /// Returns [`crate::Error::Unsupported`] when the value's metadata-only
7263 /// view differs from its physical owner's layout.
7264 pub fn into_tensor(self) -> crate::Result<Tensor> {
7265 if self.layout != tensor_layout(&self.owner) {
7266 return Err(crate::Error::unsupported(
7267 "TensorValue::into_tensor",
7268 "a metadata-only view has no compact tensor owner",
7269 ));
7270 }
7271 Ok(self.owner)
7272 }
7273
7274 ///
7275 /// # Examples
7276 ///
7277 /// ```
7278 /// use tenferro_tensor::{Tensor, TensorValue};
7279 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7280 /// assert_eq!(value.as_tensor().unwrap().as_slice::<f64>()?, &[1., 2., 3., 4.]);
7281 /// assert!(value.transpose_view([1, 0])?.as_tensor().is_none());
7282 /// # Ok::<(), tenferro_tensor::Error>(())
7283 /// ```
7284 pub fn as_tensor(&self) -> Option<&Tensor> {
7285 (self.layout == tensor_layout(&self.owner)).then_some(&self.owner)
7286 }
7287
7288 ///
7289 /// # Examples
7290 ///
7291 /// ```
7292 /// use tenferro_tensor::{Tensor, TensorValue};
7293 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7294 /// assert!(!value.is_view());
7295 /// assert!(value.transpose_view([1, 0])?.is_view());
7296 /// # Ok::<(), tenferro_tensor::Error>(())
7297 /// ```
7298 pub fn is_view(&self) -> bool {
7299 self.as_tensor().is_none()
7300 }
7301
7302 ///
7303 /// # Examples
7304 ///
7305 /// ```
7306 /// use tenferro_tensor::{Tensor, TensorValue};
7307 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7308 /// assert_eq!(value.dtype(), tenferro_tensor::DType::F64);
7309 /// # Ok::<(), tenferro_tensor::Error>(())
7310 /// ```
7311 pub fn dtype(&self) -> DType {
7312 self.owner.dtype()
7313 }
7314
7315 ///
7316 /// # Examples
7317 ///
7318 /// ```
7319 /// use tenferro_tensor::{Tensor, TensorValue};
7320 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7321 /// assert_eq!(value.reshape_view([4])?.shape(), &[4]);
7322 /// # Ok::<(), tenferro_tensor::Error>(())
7323 /// ```
7324 pub fn shape(&self) -> &[usize] {
7325 self.layout.shape()
7326 }
7327
7328 ///
7329 /// # Examples
7330 ///
7331 /// ```
7332 /// use tenferro_tensor::{Tensor, TensorValue};
7333 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7334 /// assert_eq!(value.transpose_view([1, 0])?.strides(), &[2, 1]);
7335 /// # Ok::<(), tenferro_tensor::Error>(())
7336 /// ```
7337 pub fn strides(&self) -> &[isize] {
7338 self.layout.strides()
7339 }
7340
7341 ///
7342 /// # Examples
7343 ///
7344 /// ```
7345 /// use tenferro_tensor::{Tensor, TensorValue};
7346 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7347 /// assert_eq!(value.offset(), 0);
7348 /// # Ok::<(), tenferro_tensor::Error>(())
7349 /// ```
7350 pub fn offset(&self) -> isize {
7351 self.layout.offset()
7352 }
7353
7354 /// Borrow this value as a dtype-erased view, or `None` when it holds an
7355 /// externally defined payload.
7356 ///
7357 /// [`TensorView`] has one variant per preset scalar (`F32` ... `C64`) and none
7358 /// for a caller-owned element type, so a value built from
7359 /// [`Tensor::external`] has no view; read it through
7360 /// [`Tensor::external_payload`] instead.
7361 ///
7362 /// # Examples
7363 ///
7364 /// ```
7365 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, Tensor, TensorValue, TypedTensor};
7366 ///
7367 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7368 /// let view = value.tensor_view().ok_or("a preset f64 value has a view")?;
7369 /// assert_eq!(view.shape(), &[2, 2]);
7370 /// assert_eq!(view.dtype(), tenferro_tensor::DType::F64);
7371 ///
7372 /// let payload = ErasedHostTensor::new(
7373 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1., 2.])?,
7374 /// );
7375 /// let external = TensorValue::from_tensor(Tensor::external(payload));
7376 /// assert!(external.tensor_view().is_none());
7377 /// # Ok::<(), Box<dyn std::error::Error>>(())
7378 /// ```
7379 #[must_use]
7380 pub fn tensor_view(&self) -> Option<TensorView<'_>> {
7381 tensor_view_with_layout(&self.owner, self.layout.clone())
7382 }
7383
7384 /// Borrow this value as a [`TensorRead`], or `None` when it is a
7385 /// metadata-only view of an externally defined payload.
7386 ///
7387 /// A value whose layout equals its owner's is borrowed as the owner tensor,
7388 /// whatever its dtype. Any other value is borrowed through
7389 /// [`TensorValue::tensor_view`], which has no variant for a payload built with
7390 /// [`Tensor::external`].
7391 ///
7392 /// # Examples
7393 ///
7394 /// ```
7395 /// use tenferro_tensor::{Tensor, TensorValue};
7396 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7397 /// let read = value.tensor_read().ok_or("a preset f64 value has a read")?;
7398 /// assert_eq!(read.shape(), &[2, 2]);
7399 /// assert_eq!(read.dtype(), tenferro_tensor::DType::F64);
7400 /// # Ok::<(), Box<dyn std::error::Error>>(())
7401 /// ```
7402 #[must_use]
7403 pub fn tensor_read(&self) -> Option<TensorRead<'_>> {
7404 match self.as_tensor() {
7405 Some(tensor) => Some(TensorRead::from_tensor(tensor)),
7406 None => self.tensor_view().map(TensorRead::from_view),
7407 }
7408 }
7409
7410 /// # Errors
7411 ///
7412 /// Returns [`crate::Error::Validation`] with
7413 /// [`tenferro_tensor_core::ValidationError::InvalidPermutationLength`],
7414 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
7415 /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] when `axes` is
7416 /// not a valid permutation of the value rank.
7417 ///
7418 /// # Examples
7419 ///
7420 /// ```
7421 /// use tenferro_tensor::{Tensor, TensorValue};
7422 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7423 /// let view = value.transpose_view([1, 0])?;
7424 /// assert_eq!(view.strides(), &[2, 1]);
7425 /// assert!(view.is_view());
7426 /// # Ok::<(), tenferro_tensor::Error>(())
7427 /// ```
7428 pub fn transpose_view(self, axes: impl AsRef<[usize]>) -> crate::Result<Self> {
7429 let layout = self
7430 .layout
7431 .transpose_view(axes)
7432 .map_err(|err| tensor_layout_error("TensorValue::transpose_view", err))?;
7433 Ok(Self {
7434 owner: self.owner,
7435 layout,
7436 })
7437 }
7438
7439 // INVARIANT: unchanged-owner recovery is part of the consuming view
7440 // contract, so this intentionally carries the large move-only error.
7441 /// # Errors
7442 ///
7443 /// Returns [`crate::Error::Validation`] with
7444 /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`] when
7445 /// the source is not compact column-major,
7446 /// [`tenferro_tensor_core::ValidationError::ShapeMismatch`] (whose
7447 /// [`tenferro_tensor_core::ShapeMismatch::ReshapeElementCount`] source
7448 /// records the counts) when element counts differ,
7449 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for shape
7450 /// arithmetic overflow, or
7451 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7452 /// reshaped view exceeds the backing buffer.
7453 #[allow(clippy::result_large_err)]
7454 ///
7455 /// # Examples
7456 ///
7457 /// ```
7458 /// use tenferro_tensor::{Tensor, TensorValue};
7459 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7460 /// let (recovered, error) = value.try_reshape_view([3]).unwrap_err().into_parts();
7461 /// assert_eq!(recovered.into_tensor()?.as_slice::<f64>()?, &[1., 2., 3., 4.]);
7462 /// assert!(matches!(error, tenferro_tensor::Error::Validation { .. }));
7463 /// # Ok::<(), tenferro_tensor::Error>(())
7464 /// ```
7465 pub fn try_reshape_view(
7466 self,
7467 shape: impl tenferro_tensor_core::IntoShapeVec,
7468 ) -> std::result::Result<Self, TensorValueViewError> {
7469 let shape = shape.into_shape_vec();
7470 let layout = match reshape_layout_dyn(
7471 &self.layout,
7472 &shape,
7473 tensor_buffer_len(&self.owner),
7474 "TensorValue::reshape_view",
7475 ) {
7476 Ok(layout) => layout,
7477 Err(error) => return Err(TensorValueViewError::new(self, error)),
7478 };
7479 Ok(Self {
7480 owner: self.owner,
7481 layout,
7482 })
7483 }
7484
7485 /// # Errors
7486 ///
7487 /// Returns [`crate::Error::Validation`] with
7488 /// [`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]
7489 /// when the source is not compact, [`tenferro_tensor_core::ValidationError::ShapeMismatch`]
7490 /// when element counts differ, or [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
7491 /// / [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] for invalid
7492 /// target-shape arithmetic or bounds.
7493 ///
7494 /// # Examples
7495 ///
7496 /// ```
7497 /// use tenferro_tensor::{Tensor, TensorValue};
7498 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7499 /// let view = value.reshape_view([4])?;
7500 /// assert_eq!(view.shape(), &[4]);
7501 /// assert_eq!(view.strides(), &[1]);
7502 /// # Ok::<(), tenferro_tensor::Error>(())
7503 /// ```
7504 pub fn reshape_view(
7505 self,
7506 shape: impl tenferro_tensor_core::IntoShapeVec,
7507 ) -> crate::Result<Self> {
7508 self.try_reshape_view(shape).map_err(|error| error.source)
7509 }
7510
7511 /// # Errors
7512 ///
7513 /// Returns [`crate::Error::Validation`] with
7514 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when a slice
7515 /// vector does not match the value rank,
7516 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when a bound
7517 /// or stride cannot be represented or is invalid,
7518 /// [`tenferro_tensor_core::ValidationError::InvalidSliceStep`] or
7519 /// [`tenferro_tensor_core::ValidationError::InvalidSliceBounds`] for slice
7520 /// parameters, [`tenferro_tensor_core::ValidationError::IntegerOverflow`]
7521 /// for slice arithmetic overflow, or
7522 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7523 /// result exceeds the backing buffer.
7524 ///
7525 /// # Examples
7526 ///
7527 /// ```
7528 /// use tenferro_tensor::{Tensor, TensorValue};
7529 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?);
7530 /// let view = value.slice_view(&tenferro_tensor::SliceConfig {
7531 /// starts: vec![0, 1], limits: vec![2, 2], strides: vec![1, 1],
7532 /// })?;
7533 /// assert_eq!(view.shape(), &[2, 1]);
7534 /// assert_eq!(view.offset(), 2);
7535 /// # Ok::<(), tenferro_tensor::Error>(())
7536 /// ```
7537 pub fn slice_view(self, config: &SliceConfig) -> crate::Result<Self> {
7538 let op = "TensorValue::slice_view";
7539 if config.starts.len() != self.shape().len()
7540 || config.limits.len() != self.shape().len()
7541 || config.strides.len() != self.shape().len()
7542 {
7543 return Err(crate::Error::validation(
7544 op,
7545 ValidationError::RankMismatch {
7546 expected: self.shape().len(),
7547 actual: config.starts.len(),
7548 },
7549 ));
7550 }
7551 // The per-axis specs stay inline: a metadata-only slice must not
7552 // allocate its own scratch at rank <= 8 (#2040).
7553 let mut specs = TinyVec::<[CoreSliceSpec; 8]>::with_capacity(self.shape().len());
7554 for (((&start, &limit), &stride), &axis_len) in config
7555 .starts
7556 .iter()
7557 .zip(config.limits.iter())
7558 .zip(config.strides.iter())
7559 .zip(self.shape())
7560 {
7561 let start = isize::try_from(start).map_err(|_| {
7562 crate::Error::invalid_argument(
7563 op,
7564 "slice start",
7565 "slice start does not fit in isize",
7566 )
7567 })?;
7568 let limit = isize::try_from(limit).map_err(|_| {
7569 crate::Error::invalid_argument(
7570 op,
7571 "slice limit",
7572 "slice limit does not fit in isize",
7573 )
7574 })?;
7575 let stride = isize::try_from(stride).map_err(|_| {
7576 crate::Error::invalid_argument(
7577 op,
7578 "slice stride",
7579 "slice stride does not fit in isize",
7580 )
7581 })?;
7582 specs.push(core_slice_spec(
7583 StridedSliceSpec::new(start, Some(limit), stride),
7584 axis_len,
7585 op,
7586 )?);
7587 }
7588 let layout = self
7589 .layout
7590 .slice_view(&specs, tensor_buffer_len(&self.owner))
7591 .map_err(|err| tensor_layout_error(op, err))?;
7592 Ok(Self {
7593 owner: self.owner,
7594 layout,
7595 })
7596 }
7597
7598 /// # Errors
7599 ///
7600 /// Returns [`crate::Error::Validation`] with
7601 /// [`tenferro_tensor_core::ValidationError::RankMismatch`],
7602 /// [`tenferro_tensor_core::ValidationError::AxisOutOfBounds`], or
7603 /// [`tenferro_tensor_core::ValidationError::DuplicateAxis`] for invalid
7604 /// dimension mappings,
7605 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] for
7606 /// incompatible extents,
7607 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
7608 /// result exceeds the backing buffer, or
7609 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
7610 /// arithmetic overflow.
7611 ///
7612 /// # Examples
7613 ///
7614 /// ```
7615 /// use tenferro_tensor::{Tensor, TensorValue};
7616 /// let value = TensorValue::from_tensor(Tensor::from_vec_col_major([2], vec![3., 4.])?);
7617 /// let view = value.broadcast_in_dim_view([2, 3], [0])?;
7618 /// assert_eq!(view.shape(), &[2, 3]);
7619 /// assert_eq!(view.strides(), &[1, 0]);
7620 /// # Ok::<(), tenferro_tensor::Error>(())
7621 /// ```
7622 pub fn broadcast_in_dim_view(
7623 self,
7624 shape: impl tenferro_tensor_core::IntoShapeVec,
7625 dims: impl AsRef<[usize]>,
7626 ) -> crate::Result<Self> {
7627 let shape = shape.into_shape_vec();
7628 let layout = self
7629 .layout
7630 .broadcast_in_dim_view::<DynRank>(shape, dims, tensor_buffer_len(&self.owner))
7631 .map_err(|err| tensor_layout_error("TensorValue::broadcast_in_dim_view", err))?;
7632 Ok(Self {
7633 owner: self.owner,
7634 layout,
7635 })
7636 }
7637}
7638
7639/// Copy a value's backing storage into a fresh owned tensor carrying `layout`.
7640///
7641/// A value layout is relative to its owner's backing root. For a plain compact
7642/// owner that root is the owner itself, and [`TypedTensor::duplicate`] is
7643/// enough. A root-preserving extraction (#2023) exports only its descriptor
7644/// extent over a wider root, so the copy has to carry the root and be rebased
7645/// onto the same descriptor layout.
7646fn duplicate_backing_storage(tensor: &Tensor) -> crate::Result<Tensor> {
7647 fn typed<T: TensorScalar>(tensor: &TypedTensor<T>) -> crate::Result<Tensor> {
7648 // The owner's descriptor, not the outer value layout: the copy is an
7649 // owner of the same kind, and a value layout may be a strided view over
7650 // it that the owner must not adopt.
7651 let layout = tensor.physical_layout();
7652 // `as_view().host_storage()` reports the whole root for a host owner
7653 // (including one produced by an owning reinterpretation) and refuses a
7654 // backend owner, which `buffer()` cannot express.
7655 let root = tensor.as_view().host_storage()?.to_vec();
7656 let op = "TensorValue::duplicate";
7657 let (group, slot) =
7658 AllocationGroup::from_host_vec::<T, DynRank>(shape_vec(&[root.len()]), root)
7659 .map_err(|error| crate::Error::runtime_state_source(op, error))?;
7660 let group = group
7661 .update_descriptor_layout(
7662 slot,
7663 layout.shape().to_vec(),
7664 layout.strides().to_vec(),
7665 layout.offset(),
7666 )
7667 .map_err(|(_, error)| crate::Error::runtime_state_source(op, error))?;
7668 let allocation = group
7669 .allocation_index(slot)
7670 .unwrap_or_else(|_| unreachable!("the duplicate group carries a live descriptor"));
7671 let descriptor_layout = group
7672 .descriptor_layout(slot)
7673 .unwrap_or_else(|| unreachable!("the duplicate group carries a live descriptor"));
7674 let placement = tensor.placement().clone();
7675 Ok(tensor_from_group(
7676 group,
7677 slot,
7678 allocation,
7679 T::dtype(),
7680 descriptor_layout,
7681 placement,
7682 ))
7683 }
7684
7685 match &tensor.payload {
7686 // A caller-owned payload keeps its existing duplication route: it has no
7687 // allocation group to rebuild.
7688 TensorPayload::External(..) => tensor.duplicate(),
7689 TensorPayload::Native(preset) => with_preset!(preset, |inner| typed(inner)),
7690 }
7691}
7692
7693fn tensor_layout(tensor: &Tensor) -> TensorLayout<DynRank> {
7694 match &tensor.payload {
7695 // A caller-owned payload carries its own view layout, so strides and offset
7696 // come from the payload rather than from a compact assumption.
7697 TensorPayload::External(payload, _) => TensorLayout::<DynRank>::from_parts(
7698 shape_vec(payload.shape()),
7699 stride_vec(payload.strides()),
7700 payload.offset(),
7701 payload.payload_element_count(),
7702 )
7703 .unwrap_or_else(|_| {
7704 // INVARIANT: a payload is built from a validated host tensor, and the
7705 // only layout change is a permutation, so its strides stay inside the
7706 // payload it was created from and this construction cannot fail.
7707 unreachable!("a validated payload yields a layout inside its own storage")
7708 }),
7709 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.physical_layout()),
7710 }
7711}
7712
7713fn tensor_buffer_len(tensor: &Tensor) -> usize {
7714 match &tensor.payload {
7715 // A caller-owned payload stores its element count directly.
7716 TensorPayload::External(payload, _) => payload.element_count(),
7717 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.buffer_len()),
7718 }
7719}
7720
7721fn prepare_backend_access<'a, T: 'static, R: TensorRank>(
7722 buffer: &'a dyn BackendStorage<T>,
7723 layout: &'a TensorLayout<R>,
7724 op: &'static str,
7725) -> crate::Result<Box<dyn PreparedDeviceAccess + 'a>> {
7726 let domain = buffer.allocation_domain().ok_or_else(|| {
7727 crate::Error::runtime_state(op, "backend buffer is missing an allocation domain")
7728 })?;
7729 let allocation_id = buffer.allocation_id().ok_or_else(|| {
7730 crate::Error::runtime_state(op, "backend buffer is missing an allocation identity")
7731 })?;
7732 let byte_len = buffer
7733 .len()
7734 .checked_mul(size_of::<T>())
7735 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
7736 let request = DeviceAccessRequest::new(
7737 domain,
7738 allocation_id,
7739 byte_len,
7740 size_of::<T>(),
7741 layout.shape(),
7742 layout.strides(),
7743 layout.offset(),
7744 );
7745 buffer
7746 .prepare_device_access(request)
7747 .map_err(|error| crate::Error::runtime_state_source(op, error))
7748}
7749
7750fn cast_view_slice<S: 'static, T: TensorScalar>(source: &[S]) -> crate::Result<&[T]> {
7751 if size_of::<S>() != size_of::<T>() || align_of::<S>() != align_of::<T>() {
7752 return Err(crate::Error::invalid_argument(
7753 "TensorView::as_slice",
7754 "dtype",
7755 "matching dtypes must have identical scalar layout",
7756 ));
7757 }
7758 // SAFETY: the dtype check above is exhaustive over the sealed scalar set;
7759 // equal size/alignment preserve the element boundaries and the source
7760 // slice remains borrowed for the returned lifetime.
7761 Ok(unsafe { std::slice::from_raw_parts(source.as_ptr().cast::<T>(), source.len()) })
7762}
7763
7764/// Re-layout a borrowed typed view while keeping its buffer, retained root and
7765/// placement.
7766///
7767/// #2143 item 1: an eager implicit broadcast is a metadata change, so the view
7768/// keeps reading the same storage through zero strides instead of copying the
7769/// broadcast tensor into a fresh allocation.
7770fn broadcast_typed_view<'a, T: 'static, R: TensorRank>(
7771 view: TypedTensorView<'a, T, R>,
7772 shape: &[usize],
7773 dims: &[usize],
7774) -> crate::Result<TypedTensorView<'a, T, R>> {
7775 let shape = R::shape_from_vec(shape_vec(shape))
7776 .map_err(|err| tensor_layout_error("TensorRead::broadcast_in_dim_view", err))?;
7777 let layout = view
7778 .layout()
7779 .broadcast_in_dim_view::<R>(shape, dims, view.backing_len())
7780 .map_err(|err| tensor_layout_error("TensorRead::broadcast_in_dim_view", err))?;
7781 Ok(TypedTensorView {
7782 buffer: view.buffer,
7783 root: view.root,
7784 layout,
7785 placement: view.placement,
7786 _representation: std::marker::PhantomData,
7787 })
7788}
7789
7790/// Borrow `tensor` as a preset-scalar view with `layout`, or `None` for an
7791/// externally defined payload: `TensorView` has one variant per preset scalar and
7792/// none for a caller-owned element type, and [`Tensor::external`] is public, so
7793/// that case is reachable and is answered rather than asserted away (#2486).
7794fn tensor_view_with_layout(
7795 tensor: &Tensor,
7796 layout: TensorLayout<DynRank>,
7797) -> Option<TensorView<'_>> {
7798 Some(match tensor.dtype() {
7799 DType::F32 => TensorView::F32(typed_view_with_layout(
7800 tensor
7801 .as_typed::<f32>()
7802 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7803 layout,
7804 )),
7805 DType::F64 => TensorView::F64(typed_view_with_layout(
7806 tensor
7807 .as_typed::<f64>()
7808 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7809 layout,
7810 )),
7811 DType::I32 => TensorView::I32(typed_view_with_layout(
7812 tensor
7813 .as_typed::<i32>()
7814 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7815 layout,
7816 )),
7817 DType::I64 => TensorView::I64(typed_view_with_layout(
7818 tensor
7819 .as_typed::<i64>()
7820 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7821 layout,
7822 )),
7823 DType::Bool => TensorView::Bool(typed_view_with_layout(
7824 tensor
7825 .as_typed::<bool>()
7826 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7827 layout,
7828 )),
7829 DType::C32 => TensorView::C32(typed_view_with_layout(
7830 tensor
7831 .as_typed::<Complex<f32>>()
7832 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7833 layout,
7834 )),
7835 DType::C64 => TensorView::C64(typed_view_with_layout(
7836 tensor
7837 .as_typed::<Complex<f64>>()
7838 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm")),
7839 layout,
7840 )),
7841 DType::External(_) => return None,
7842 })
7843}
7844
7845fn typed_view_with_layout<T: TensorScalar + 'static>(
7846 tensor: &TypedTensor<T>,
7847 layout: TensorLayout<DynRank>,
7848) -> TypedTensorView<'_, T> {
7849 match &tensor.storage {
7850 DynamicStorage::Host(HostStorage { data }) => TypedTensorView {
7851 buffer: TensorStorageRef::Host(data.as_slice()),
7852 root: None,
7853 layout,
7854 placement: tensor.placement.clone(),
7855 _representation: std::marker::PhantomData,
7856 },
7857 DynamicStorage::Group(core) => {
7858 let root = core.group.view::<T>().unwrap_or_else(|error| {
7859 unreachable!("typed tensor group descriptor mismatch: {error}")
7860 });
7861 let buffer = if let Some(allocation) = root.backend_allocation() {
7862 TensorStorageRef::Root(allocation)
7863 } else {
7864 TensorStorageRef::Host(tensor.group_host_slice())
7865 };
7866 TypedTensorView {
7867 buffer,
7868 root: Some(root),
7869 layout,
7870 placement: tensor.placement.clone(),
7871 _representation: std::marker::PhantomData,
7872 }
7873 }
7874 }
7875}
7876
7877pub(crate) fn tensor_view_from_group<'a, T: TensorScalar>(
7878 view: GroupReadView<'a, T, DynRank>,
7879) -> crate::Result<TensorView<'a>> {
7880 let buffer = if let Some(allocation) = view.backend_allocation() {
7881 TensorStorageRef::Root(allocation)
7882 } else {
7883 let storage = view.storage_buffer();
7884 match storage {
7885 Some(StorageBuffer::Host(data)) => TensorStorageRef::Host(data),
7886 Some(StorageBuffer::Backend(buffer)) => TensorStorageRef::Backend(buffer.as_ref()),
7887 // A sealed representation reinterpretation changes the descriptor's
7888 // dtype while the host root keeps its own, so the typed downcast
7889 // above cannot see it.
7890 None => match view.host_root_slice() {
7891 Some(data) => TensorStorageRef::Host(data),
7892 None => {
7893 return Err(crate::Error::runtime_state(
7894 "AllocationGroup::tensor_read",
7895 "group descriptor has no backing storage",
7896 ));
7897 }
7898 },
7899 }
7900 };
7901 let layout = view.descriptor().layout().clone();
7902 let placement = view.descriptor().placement().clone();
7903 let typed = TypedTensorView {
7904 buffer,
7905 root: Some(view.clone()),
7906 layout,
7907 placement,
7908 _representation: std::marker::PhantomData,
7909 };
7910 Ok(T::tensor_view(typed))
7911}
7912
7913pub(crate) fn tensor_from_group(
7914 group: AllocationGroup,
7915 slot: DescriptorSlot,
7916 allocation_index: AllocationSlot,
7917 dtype: DType,
7918 layout: TensorLayout<DynRank>,
7919 placement: Placement,
7920) -> Tensor {
7921 fn typed<T: TensorScalar>(
7922 group: AllocationGroup,
7923 slot: DescriptorSlot,
7924 allocation_index: AllocationSlot,
7925 layout: TensorLayout<DynRank>,
7926 placement: Placement,
7927 ) -> TypedTensor<T> {
7928 let descriptor_dtype = group
7929 .descriptor_dtype(slot)
7930 .unwrap_or_else(|| unreachable!("tensor_from_group requires a live typed descriptor"));
7931 assert_eq!(
7932 descriptor_dtype,
7933 T::dtype(),
7934 "managed typed owner must match its descriptor dtype",
7935 );
7936 let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
7937 TypedTensor {
7938 shape: shape_vec(layout.shape()),
7939 placement,
7940 layout: stride_vec(layout.strides()),
7941 storage: DynamicStorage::Group(GroupStorage {
7942 group: Box::new(OwnedTensorGroup {
7943 group,
7944 slot,
7945 allocation_index,
7946 host_ptr,
7947 host_byte_len,
7948 _rank: PhantomData,
7949 }),
7950 }),
7951 }
7952 }
7953
7954 match dtype {
7955 DType::F32 => <f32 as TensorScalar>::typed_tensor_into_tensor(typed::<f32>(
7956 group,
7957 slot,
7958 allocation_index,
7959 layout,
7960 placement,
7961 )),
7962 DType::F64 => <f64 as TensorScalar>::typed_tensor_into_tensor(typed::<f64>(
7963 group,
7964 slot,
7965 allocation_index,
7966 layout,
7967 placement,
7968 )),
7969 DType::I32 => <i32 as TensorScalar>::typed_tensor_into_tensor(typed::<i32>(
7970 group,
7971 slot,
7972 allocation_index,
7973 layout,
7974 placement,
7975 )),
7976 DType::I64 => <i64 as TensorScalar>::typed_tensor_into_tensor(typed::<i64>(
7977 group,
7978 slot,
7979 allocation_index,
7980 layout,
7981 placement,
7982 )),
7983 DType::Bool => <bool as TensorScalar>::typed_tensor_into_tensor(typed::<bool>(
7984 group,
7985 slot,
7986 allocation_index,
7987 layout,
7988 placement,
7989 )),
7990 DType::C32 => <Complex<f32> as TensorScalar>::typed_tensor_into_tensor(
7991 typed::<Complex<f32>>(group, slot, allocation_index, layout, placement),
7992 ),
7993 DType::C64 => <Complex<f64> as TensorScalar>::typed_tensor_into_tensor(
7994 typed::<Complex<f64>>(group, slot, allocation_index, layout, placement),
7995 ),
7996 // INVARIANT: an allocation group is created from a sealed preset scalar,
7997 // so it can never carry an externally defined one. External payloads are
7998 // caller-owned and do not enter a group.
7999 DType::External(_) => unreachable!("allocation groups are preset-typed"),
8000 }
8001}
8002
8003/// Wrap an `f64` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8004///
8005/// # Examples
8006///
8007/// ```
8008/// use tenferro_tensor::{Tensor, TypedTensor};
8009///
8010/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
8011/// let tensor: Tensor = typed.into();
8012/// assert_eq!(tensor.shape(), &[2]);
8013/// ```
8014impl From<TypedTensor<f64>> for Tensor {
8015 fn from(t: TypedTensor<f64>) -> Self {
8016 Tensor::from_typed(t)
8017 }
8018}
8019
8020/// Wrap an `f32` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8021///
8022/// # Examples
8023///
8024/// ```
8025/// use tenferro_tensor::{Tensor, TypedTensor};
8026///
8027/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f32, 2.0]).unwrap();
8028/// let tensor: Tensor = typed.into();
8029/// assert_eq!(tensor.shape(), &[2]);
8030/// ```
8031impl From<TypedTensor<f32>> for Tensor {
8032 fn from(t: TypedTensor<f32>) -> Self {
8033 Tensor::from_typed(t)
8034 }
8035}
8036
8037/// Wrap an `i64` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8038///
8039/// # Examples
8040///
8041/// ```
8042/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8043///
8044/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i64, 2]).unwrap();
8045/// let tensor: Tensor = typed.into();
8046/// assert_eq!(tensor.dtype(), DType::I64);
8047/// assert_eq!(tensor.shape(), &[2]);
8048/// ```
8049impl From<TypedTensor<i64>> for Tensor {
8050 fn from(t: TypedTensor<i64>) -> Self {
8051 Tensor::from_typed(t)
8052 }
8053}
8054
8055/// Wrap an `i32` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8056///
8057/// # Examples
8058///
8059/// ```
8060/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8061///
8062/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i32, 2]).unwrap();
8063/// let tensor: Tensor = typed.into();
8064/// assert_eq!(tensor.dtype(), DType::I32);
8065/// assert_eq!(tensor.shape(), &[2]);
8066/// ```
8067impl From<TypedTensor<i32>> for Tensor {
8068 fn from(t: TypedTensor<i32>) -> Self {
8069 Tensor::from_typed(t)
8070 }
8071}
8072
8073/// Wrap a `bool` [`TypedTensor`] into the corresponding [`Tensor`] variant.
8074///
8075/// # Examples
8076///
8077/// ```
8078/// use tenferro_tensor::{DType, Tensor, TypedTensor};
8079///
8080/// let typed = TypedTensor::from_vec_col_major(vec![2], vec![true, false]).unwrap();
8081/// let tensor: Tensor = typed.into();
8082/// assert_eq!(tensor.dtype(), DType::Bool);
8083/// assert_eq!(tensor.shape(), &[2]);
8084/// ```
8085impl From<TypedTensor<bool>> for Tensor {
8086 fn from(t: TypedTensor<bool>) -> Self {
8087 Tensor::from_typed(t)
8088 }
8089}
8090
8091/// Wrap a [`Complex64`] [`TypedTensor`] into the corresponding [`Tensor`]
8092/// variant.
8093///
8094/// # Examples
8095///
8096/// ```
8097/// use num_complex::Complex64;
8098/// use tenferro_tensor::{Tensor, TypedTensor};
8099///
8100/// let typed = TypedTensor::from_vec_col_major(
8101/// vec![1],
8102/// vec![Complex64::new(1.0, 2.0)],
8103/// ).unwrap();
8104/// let tensor: Tensor = typed.into();
8105/// assert_eq!(tensor.shape(), &[1]);
8106/// ```
8107impl From<TypedTensor<Complex<f64>>> for Tensor {
8108 fn from(t: TypedTensor<Complex<f64>>) -> Self {
8109 Tensor::from_typed(t)
8110 }
8111}
8112
8113/// Wrap a [`Complex32`] [`TypedTensor`] into the corresponding [`Tensor`]
8114/// variant.
8115///
8116/// # Examples
8117///
8118/// ```
8119/// use num_complex::Complex32;
8120/// use tenferro_tensor::{Tensor, TypedTensor};
8121///
8122/// let typed = TypedTensor::from_vec_col_major(
8123/// vec![1],
8124/// vec![Complex32::new(1.0, 2.0)],
8125/// ).unwrap();
8126/// let tensor: Tensor = typed.into();
8127/// assert_eq!(tensor.shape(), &[1]);
8128/// ```
8129impl From<TypedTensor<Complex<f32>>> for Tensor {
8130 fn from(t: TypedTensor<Complex<f32>>) -> Self {
8131 Tensor::from_typed(t)
8132 }
8133}
8134
8135impl<'a> TensorView<'a> {
8136 /// Create a dynamic `f32` view over compact column-major host data.
8137 ///
8138 /// # Examples
8139 ///
8140 /// ```
8141 /// use tenferro_tensor::{DType, TensorView};
8142 ///
8143 /// let data = [1.0_f32, 2.0];
8144 /// let view = TensorView::f32(&[2], &data)?;
8145 /// assert_eq!(view.dtype(), DType::F32);
8146 /// # Ok::<(), tenferro_tensor::Error>(())
8147 /// ```
8148 /// # Errors
8149 ///
8150 /// Returns [`crate::Error::Validation`] with
8151 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8152 /// shape or offset arithmetic overflow, or
8153 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8154 /// compact shape reaches beyond `data`.
8155 pub fn f32(shape: &'a [usize], data: &'a [f32]) -> crate::Result<Self> {
8156 Ok(Self::F32(TypedTensorView::from_col_major(shape, data)?))
8157 }
8158
8159 /// Create a dynamic `f64` view over compact column-major host data.
8160 ///
8161 /// # Examples
8162 ///
8163 /// ```
8164 /// use tenferro_tensor::{DType, TensorView};
8165 ///
8166 /// let data = [1.0_f64, 2.0];
8167 /// let view = TensorView::f64(&[2], &data)?;
8168 /// assert_eq!(view.dtype(), DType::F64);
8169 /// # Ok::<(), tenferro_tensor::Error>(())
8170 /// ```
8171 /// # Errors
8172 ///
8173 /// Returns [`crate::Error::Validation`] with
8174 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8175 /// shape or offset arithmetic overflow, or
8176 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8177 /// compact shape reaches beyond `data`.
8178 pub fn f64(shape: &'a [usize], data: &'a [f64]) -> crate::Result<Self> {
8179 Ok(Self::F64(TypedTensorView::from_col_major(shape, data)?))
8180 }
8181
8182 /// Create a dynamic `i64` view over compact column-major host data.
8183 ///
8184 /// # Examples
8185 ///
8186 /// ```
8187 /// use tenferro_tensor::{DType, TensorView};
8188 ///
8189 /// let data = [1_i64, 2];
8190 /// let view = TensorView::i64(&[2], &data)?;
8191 /// assert_eq!(view.dtype(), DType::I64);
8192 /// # Ok::<(), tenferro_tensor::Error>(())
8193 /// ```
8194 /// # Errors
8195 ///
8196 /// Returns [`crate::Error::Validation`] with
8197 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8198 /// shape or offset arithmetic overflow, or
8199 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8200 /// compact shape reaches beyond `data`.
8201 pub fn i64(shape: &'a [usize], data: &'a [i64]) -> crate::Result<Self> {
8202 Ok(Self::I64(TypedTensorView::from_col_major(shape, data)?))
8203 }
8204
8205 /// Create a dynamic `i32` view over compact column-major host data.
8206 ///
8207 /// # Examples
8208 ///
8209 /// ```
8210 /// use tenferro_tensor::{DType, TensorView};
8211 ///
8212 /// let data = [1_i32, 2];
8213 /// let view = TensorView::i32(&[2], &data)?;
8214 /// assert_eq!(view.dtype(), DType::I32);
8215 /// # Ok::<(), tenferro_tensor::Error>(())
8216 /// ```
8217 /// # Errors
8218 ///
8219 /// Returns [`crate::Error::Validation`] with
8220 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8221 /// shape or offset arithmetic overflow, or
8222 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8223 /// compact shape reaches beyond `data`.
8224 pub fn i32(shape: &'a [usize], data: &'a [i32]) -> crate::Result<Self> {
8225 Ok(Self::I32(TypedTensorView::from_col_major(shape, data)?))
8226 }
8227
8228 /// Create a dynamic `bool` view over compact column-major host data.
8229 ///
8230 /// # Examples
8231 ///
8232 /// ```
8233 /// use tenferro_tensor::{DType, TensorView};
8234 ///
8235 /// let data = [true, false];
8236 /// let view = TensorView::bool(&[2], &data)?;
8237 /// assert_eq!(view.dtype(), DType::Bool);
8238 /// # Ok::<(), tenferro_tensor::Error>(())
8239 /// ```
8240 /// # Errors
8241 ///
8242 /// Returns [`crate::Error::Validation`] with
8243 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8244 /// shape or offset arithmetic overflow, or
8245 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8246 /// compact shape reaches beyond `data`.
8247 pub fn bool(shape: &'a [usize], data: &'a [bool]) -> crate::Result<Self> {
8248 Ok(Self::Bool(TypedTensorView::from_col_major(shape, data)?))
8249 }
8250
8251 /// Create a dynamic `Complex32` view over compact column-major host data.
8252 ///
8253 /// # Examples
8254 ///
8255 /// ```
8256 /// use num_complex::Complex32;
8257 /// use tenferro_tensor::{DType, TensorView};
8258 ///
8259 /// let data = [Complex32::new(1.0, 2.0)];
8260 /// let view = TensorView::c32(&[1], &data)?;
8261 /// assert_eq!(view.dtype(), DType::C32);
8262 /// # Ok::<(), tenferro_tensor::Error>(())
8263 /// ```
8264 /// # Errors
8265 ///
8266 /// Returns [`crate::Error::Validation`] with
8267 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8268 /// shape or offset arithmetic overflow, or
8269 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8270 /// compact shape reaches beyond `data`.
8271 pub fn c32(shape: &'a [usize], data: &'a [Complex32]) -> crate::Result<Self> {
8272 Ok(Self::C32(TypedTensorView::from_col_major(shape, data)?))
8273 }
8274
8275 /// Create a dynamic `Complex64` view over compact column-major host data.
8276 ///
8277 /// # Examples
8278 ///
8279 /// ```
8280 /// use num_complex::Complex64;
8281 /// use tenferro_tensor::{DType, TensorView};
8282 ///
8283 /// let data = [Complex64::new(1.0, 2.0)];
8284 /// let view = TensorView::c64(&[1], &data)?;
8285 /// assert_eq!(view.dtype(), DType::C64);
8286 /// # Ok::<(), tenferro_tensor::Error>(())
8287 /// ```
8288 /// # Errors
8289 ///
8290 /// Returns [`crate::Error::Validation`] with
8291 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for compact
8292 /// shape or offset arithmetic overflow, or
8293 /// [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`] when the
8294 /// compact shape reaches beyond `data`.
8295 pub fn c64(shape: &'a [usize], data: &'a [Complex64]) -> crate::Result<Self> {
8296 Ok(Self::C64(TypedTensorView::from_col_major(shape, data)?))
8297 }
8298
8299 /// Return the element dtype of this borrowed view.
8300 ///
8301 /// # Examples
8302 ///
8303 /// ```
8304 /// use tenferro_tensor::{DType, TensorView};
8305 ///
8306 /// let view = TensorView::f64(&[2], &[1.0, 2.0])?;
8307 /// assert_eq!(view.dtype(), DType::F64);
8308 /// # Ok::<(), tenferro_tensor::Error>(())
8309 /// ```
8310 pub fn dtype(&self) -> DType {
8311 match self {
8312 Self::F32(_) => DType::F32,
8313 Self::F64(_) => DType::F64,
8314 Self::I32(_) => DType::I32,
8315 Self::I64(_) => DType::I64,
8316 Self::Bool(_) => DType::Bool,
8317 Self::C32(_) => DType::C32,
8318 Self::C64(_) => DType::C64,
8319 }
8320 }
8321
8322 /// Return the logical shape of this borrowed view.
8323 ///
8324 /// # Examples
8325 ///
8326 /// ```
8327 /// use tenferro_tensor::TensorView;
8328 ///
8329 /// let view = TensorView::i32(&[2, 1], &[1, 2])?;
8330 /// assert_eq!(view.shape(), &[2, 1]);
8331 /// # Ok::<(), tenferro_tensor::Error>(())
8332 /// ```
8333 pub fn shape(&self) -> &[usize] {
8334 match self {
8335 Self::F32(t) => t.shape(),
8336 Self::F64(t) => t.shape(),
8337 Self::I32(t) => t.shape(),
8338 Self::I64(t) => t.shape(),
8339 Self::Bool(t) => t.shape(),
8340 Self::C32(t) => t.shape(),
8341 Self::C64(t) => t.shape(),
8342 }
8343 }
8344
8345 /// Borrow a contiguous host slice when the requested scalar matches this view's dtype.
8346 ///
8347 /// Backend buffers and non-contiguous views return an explicit error. No
8348 /// download or materialization is performed.
8349 ///
8350 /// # Errors
8351 ///
8352 /// Returns [`ValidationError::DTypeMismatch`] when `T` does not match the
8353 /// view dtype, [`ValidationError::NonContiguousViewAsSlice`] for a
8354 /// non-contiguous layout, or [`crate::Error::HostAccess`] for unavailable
8355 /// backend host access.
8356 pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&'a [T]> {
8357 if self.dtype() != T::dtype() {
8358 return Err(crate::Error::validation(
8359 "TensorView::as_slice",
8360 ValidationError::DTypeMismatch {
8361 expected: T::dtype(),
8362 actual: self.dtype(),
8363 },
8364 ));
8365 }
8366 match self {
8367 Self::F32(view) => cast_view_slice(view.as_slice()?),
8368 Self::F64(view) => cast_view_slice(view.as_slice()?),
8369 Self::I32(view) => cast_view_slice(view.as_slice()?),
8370 Self::I64(view) => cast_view_slice(view.as_slice()?),
8371 Self::Bool(view) => cast_view_slice(view.as_slice()?),
8372 Self::C32(view) => cast_view_slice(view.as_slice()?),
8373 Self::C64(view) => cast_view_slice(view.as_slice()?),
8374 }
8375 }
8376
8377 /// Reinterpret a complex view as its sealed real representation.
8378 ///
8379 /// # Examples
8380 ///
8381 /// ```
8382 /// use tenferro_tensor::{Complex64, DType, TensorView};
8383 ///
8384 /// let data = [Complex64::new(1.0, 2.0)];
8385 /// let real = TensorView::c64(&[1], &data)?.as_real_view()?;
8386 /// assert_eq!(real.dtype(), DType::F64);
8387 /// assert_eq!(real.as_slice::<f64>()?, &[1.0, 2.0]);
8388 /// # Ok::<(), tenferro_tensor::Error>(())
8389 /// ```
8390 ///
8391 /// # Errors
8392 ///
8393 /// Returns [`crate::Error::Unsupported`] for the wrong dtype pair and
8394 /// [`ValidationError::InvalidArgument`] or
8395 /// [`ValidationError::ViewOutOfBounds`] for invalid layout metadata.
8396 pub fn as_real_view(&self) -> crate::Result<Self> {
8397 match self {
8398 Self::C32(t) => t.as_real_view().map(Self::F32),
8399 Self::C64(t) => t.as_real_view().map(Self::F64),
8400 _ => Err(crate::Error::unsupported(
8401 "TensorView::as_real_view",
8402 "only complex views have a sealed real representation",
8403 )),
8404 }
8405 }
8406
8407 /// Reinterpret a real view as its sealed complex representation.
8408 ///
8409 /// # Examples
8410 ///
8411 /// ```
8412 /// use tenferro_tensor::{Complex64, DType, TensorView};
8413 ///
8414 /// let data = [1.0_f64, 2.0];
8415 /// let complex = TensorView::f64(&[2, 1], &data)?.as_complex_view()?;
8416 /// assert_eq!(complex.dtype(), DType::C64);
8417 /// assert_eq!(complex.as_slice::<Complex64>()?, &[Complex64::new(1.0, 2.0)]);
8418 /// # Ok::<(), tenferro_tensor::Error>(())
8419 /// ```
8420 ///
8421 /// # Errors
8422 ///
8423 /// Returns [`crate::Error::Unsupported`] for the wrong dtype pair and
8424 /// [`ValidationError::InvalidArgument`] or
8425 /// [`ValidationError::ViewOutOfBounds`] for invalid layout metadata.
8426 pub fn as_complex_view(&self) -> crate::Result<Self> {
8427 match self {
8428 Self::F32(t) => t.as_complex_view().map(Self::C32),
8429 Self::F64(t) => t.as_complex_view().map(Self::C64),
8430 _ => Err(crate::Error::unsupported(
8431 "TensorView::as_complex_view",
8432 "only real views have a sealed complex representation",
8433 )),
8434 }
8435 }
8436
8437 /// Return the placement metadata carried by this borrowed view.
8438 ///
8439 /// # Examples
8440 ///
8441 /// ```
8442 /// use tenferro_tensor::{MemoryKind, TensorView};
8443 ///
8444 /// let view = TensorView::f64(&[1], &[1.0])?;
8445 /// assert_eq!(view.placement().memory_kind, MemoryKind::UnpinnedHost);
8446 /// # Ok::<(), tenferro_tensor::Error>(())
8447 /// ```
8448 pub fn placement(&self) -> &Placement {
8449 match self {
8450 Self::F32(t) => t.placement(),
8451 Self::F64(t) => t.placement(),
8452 Self::I32(t) => t.placement(),
8453 Self::I64(t) => t.placement(),
8454 Self::Bool(t) => t.placement(),
8455 Self::C32(t) => t.placement(),
8456 Self::C64(t) => t.placement(),
8457 }
8458 }
8459
8460 /// Return the physical backend family, when this view is backend-owned.
8461 ///
8462 /// # Examples
8463 ///
8464 /// ```rust
8465 /// use tenferro_tensor::TensorView;
8466 ///
8467 /// let view = TensorView::f64(&[1], &[1.0])?;
8468 /// assert_eq!(view.backend_family(), None);
8469 /// # Ok::<(), tenferro_tensor::Error>(())
8470 /// ```
8471 pub fn backend_family(&self) -> Option<&'static str> {
8472 match self {
8473 Self::F32(t) => t.backend_family(),
8474 Self::F64(t) => t.backend_family(),
8475 Self::I32(t) => t.backend_family(),
8476 Self::I64(t) => t.backend_family(),
8477 Self::Bool(t) => t.backend_family(),
8478 Self::C32(t) => t.backend_family(),
8479 Self::C64(t) => t.backend_family(),
8480 }
8481 }
8482
8483 /// Return whether this view borrows host-addressed memory.
8484 ///
8485 /// See [`TypedTensorView::is_host_memory`]; the borrowed payload answers,
8486 /// not the placement label.
8487 ///
8488 /// # Examples
8489 ///
8490 /// ```rust
8491 /// use tenferro_tensor::TensorView;
8492 ///
8493 /// let view = TensorView::f64(&[1], &[1.0])?;
8494 /// assert!(view.is_host_memory());
8495 /// # Ok::<(), tenferro_tensor::Error>(())
8496 /// ```
8497 pub fn is_host_memory(&self) -> bool {
8498 match self {
8499 Self::F32(t) => t.is_host_memory(),
8500 Self::F64(t) => t.is_host_memory(),
8501 Self::I32(t) => t.is_host_memory(),
8502 Self::I64(t) => t.is_host_memory(),
8503 Self::Bool(t) => t.is_host_memory(),
8504 Self::C32(t) => t.is_host_memory(),
8505 Self::C64(t) => t.is_host_memory(),
8506 }
8507 }
8508
8509 /// Return the shared allocation domain, when this view has one.
8510 ///
8511 /// # Examples
8512 ///
8513 /// ```
8514 /// use tenferro_tensor::TensorView;
8515 ///
8516 /// let view = TensorView::f64(&[1], &[1.0])?;
8517 /// assert_eq!(view.allocation_domain(), None);
8518 /// # Ok::<(), tenferro_tensor::Error>(())
8519 /// ```
8520 pub fn allocation_domain(&self) -> Option<AllocationDomainId> {
8521 match self {
8522 Self::F32(t) => t.allocation_domain(),
8523 Self::F64(t) => t.allocation_domain(),
8524 Self::I32(t) => t.allocation_domain(),
8525 Self::I64(t) => t.allocation_domain(),
8526 Self::Bool(t) => t.allocation_domain(),
8527 Self::C32(t) => t.allocation_domain(),
8528 Self::C64(t) => t.allocation_domain(),
8529 }
8530 }
8531
8532 /// Return strides in element units.
8533 ///
8534 /// # Examples
8535 ///
8536 /// ```
8537 /// use tenferro_tensor::TensorView;
8538 ///
8539 /// let data = [0.0_f64; 6];
8540 /// let view = TensorView::f64(&[2, 3], &data)?;
8541 /// assert_eq!(view.strides(), &[1, 2]);
8542 /// # Ok::<(), tenferro_tensor::Error>(())
8543 /// ```
8544 pub fn strides(&self) -> &[isize] {
8545 match self {
8546 Self::F32(t) => t.strides(),
8547 Self::F64(t) => t.strides(),
8548 Self::I32(t) => t.strides(),
8549 Self::I64(t) => t.strides(),
8550 Self::Bool(t) => t.strides(),
8551 Self::C32(t) => t.strides(),
8552 Self::C64(t) => t.strides(),
8553 }
8554 }
8555
8556 /// Return the physical element offset.
8557 pub fn offset(&self) -> isize {
8558 match self {
8559 Self::F32(t) => t.offset(),
8560 Self::F64(t) => t.offset(),
8561 Self::I32(t) => t.offset(),
8562 Self::I64(t) => t.offset(),
8563 Self::Bool(t) => t.offset(),
8564 Self::C32(t) => t.offset(),
8565 Self::C64(t) => t.offset(),
8566 }
8567 }
8568
8569 /// Compute the physical element offset for a logical index.
8570 /// # Errors
8571 ///
8572 /// Returns [`crate::Error::Validation`] with
8573 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
8574 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
8575 /// when an index is outside its axis extent, or
8576 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
8577 /// arithmetic overflows.
8578 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
8579 match self {
8580 Self::F32(t) => t.layout_linear_offset(indices),
8581 Self::F64(t) => t.layout_linear_offset(indices),
8582 Self::I32(t) => t.layout_linear_offset(indices),
8583 Self::I64(t) => t.layout_linear_offset(indices),
8584 Self::Bool(t) => t.layout_linear_offset(indices),
8585 Self::C32(t) => t.layout_linear_offset(indices),
8586 Self::C64(t) => t.layout_linear_offset(indices),
8587 }
8588 }
8589
8590 /// Return whether this view is compact column-major.
8591 /// # Errors
8592 ///
8593 /// Returns [`crate::Error::Validation`] with
8594 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8595 /// compactness arithmetic overflows.
8596 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
8597 match self {
8598 Self::F32(t) => t.is_col_major_contiguous(),
8599 Self::F64(t) => t.is_col_major_contiguous(),
8600 Self::I32(t) => t.is_col_major_contiguous(),
8601 Self::I64(t) => t.is_col_major_contiguous(),
8602 Self::Bool(t) => t.is_col_major_contiguous(),
8603 Self::C32(t) => t.is_col_major_contiguous(),
8604 Self::C64(t) => t.is_col_major_contiguous(),
8605 }
8606 }
8607
8608 /// Return a compact string summary of this view's layout metadata.
8609 pub fn layout_summary(&self) -> String {
8610 layout_summary(self.shape(), self.strides(), self.offset())
8611 }
8612
8613 /// Assert this view is compact column-major.
8614 /// # Errors
8615 ///
8616 /// Returns [`crate::Error::Validation`] with
8617 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8618 /// compactness arithmetic overflows, or
8619 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8620 /// view is not compact column-major.
8621 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
8622 assert_layout_col_major_contiguous(
8623 self.is_col_major_contiguous()?,
8624 self.shape(),
8625 self.strides(),
8626 self.offset(),
8627 "TensorView::assert_col_major_contiguous",
8628 )
8629 }
8630
8631 /// Explicitly duplicate a compact host view into a fresh tensor.
8632 ///
8633 /// Backend views and non-contiguous layouts return a typed error; this
8634 /// operation never downloads or silently canonicalizes a view.
8635 ///
8636 /// # Examples
8637 ///
8638 /// ```
8639 /// use tenferro_tensor::{TensorView, TypedTensorView};
8640 ///
8641 /// let data = [1_i32, 2];
8642 /// let view = TensorView::I32(TypedTensorView::from_slice(vec![2], vec![1], 0, &data)?);
8643 /// let copy = view.duplicate()?;
8644 /// assert_eq!(copy.shape(), &[2]);
8645 /// # Ok::<(), tenferro_tensor::Error>(())
8646 /// ```
8647 ///
8648 /// # Errors
8649 ///
8650 /// Returns [`crate::Error::HostAccess`] for backend-owned views,
8651 /// [`ValidationError::NonContiguousViewAsSlice`] for non-contiguous views,
8652 /// or [`ValidationError::InvalidArgument`] for invalid layout metadata.
8653 pub fn duplicate(&self) -> crate::Result<Tensor> {
8654 fn duplicate_typed<T: TensorScalar>(
8655 view: &TypedTensorView<'_, T>,
8656 ) -> crate::Result<TypedTensor<T>> {
8657 let mut tensor = TypedTensor::<T>::from_vec_col_major(
8658 view.shape().to_vec(),
8659 view.as_slice()?.to_vec(),
8660 )?;
8661 tensor.set_placement(view.placement().clone())?;
8662 Ok(tensor)
8663 }
8664
8665 match self {
8666 Self::F32(view) => duplicate_typed(view).map(Tensor::from_typed),
8667 Self::F64(view) => duplicate_typed(view).map(Tensor::from_typed),
8668 Self::I32(view) => duplicate_typed(view).map(Tensor::from_typed),
8669 Self::I64(view) => duplicate_typed(view).map(Tensor::from_typed),
8670 Self::Bool(view) => duplicate_typed(view).map(Tensor::from_typed),
8671 Self::C32(view) => duplicate_typed(view).map(Tensor::from_typed),
8672 Self::C64(view) => duplicate_typed(view).map(Tensor::from_typed),
8673 }
8674 }
8675}
8676
8677macro_rules! tensor_view_mut_constructor {
8678 ($name:ident, $variant:ident, $scalar:ty) => {
8679 /// Create a dynamic mutable view over compact column-major host data.
8680 ///
8681 /// # Errors
8682 ///
8683 /// Returns [`crate::Error::Validation`] with
8684 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8685 /// compact layout arithmetic overflows, or
8686 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8687 /// requested shape exceeds `data`.
8688 pub fn $name(shape: &'a [usize], data: &'a mut [$scalar]) -> crate::Result<Self> {
8689 Ok(Self::$variant(TypedTensorViewMut::from_col_major(
8690 shape, data,
8691 )?))
8692 }
8693 };
8694}
8695
8696impl<'a> TensorViewMut<'a> {
8697 tensor_view_mut_constructor!(f32, F32, f32);
8698 tensor_view_mut_constructor!(f64, F64, f64);
8699 tensor_view_mut_constructor!(i32, I32, i32);
8700 tensor_view_mut_constructor!(i64, I64, i64);
8701 tensor_view_mut_constructor!(bool, Bool, bool);
8702 tensor_view_mut_constructor!(c32, C32, Complex32);
8703 tensor_view_mut_constructor!(c64, C64, Complex64);
8704
8705 pub fn dtype(&self) -> DType {
8706 match self {
8707 Self::F32(_) => DType::F32,
8708 Self::F64(_) => DType::F64,
8709 Self::I32(_) => DType::I32,
8710 Self::I64(_) => DType::I64,
8711 Self::Bool(_) => DType::Bool,
8712 Self::C32(_) => DType::C32,
8713 Self::C64(_) => DType::C64,
8714 }
8715 }
8716
8717 pub fn shape(&self) -> &[usize] {
8718 match self {
8719 Self::F32(t) => t.shape(),
8720 Self::F64(t) => t.shape(),
8721 Self::I32(t) => t.shape(),
8722 Self::I64(t) => t.shape(),
8723 Self::Bool(t) => t.shape(),
8724 Self::C32(t) => t.shape(),
8725 Self::C64(t) => t.shape(),
8726 }
8727 }
8728
8729 /// Return strides in element units.
8730 ///
8731 /// # Examples
8732 ///
8733 /// ```
8734 /// use tenferro_tensor::TensorViewMut;
8735 ///
8736 /// let mut data = [0.0_f64; 6];
8737 /// let view = TensorViewMut::f64(&[2, 3], &mut data)?;
8738 /// assert_eq!(view.strides(), &[1, 2]);
8739 /// # Ok::<(), tenferro_tensor::Error>(())
8740 /// ```
8741 pub fn strides(&self) -> &[isize] {
8742 match self {
8743 Self::F32(t) => t.strides(),
8744 Self::F64(t) => t.strides(),
8745 Self::I32(t) => t.strides(),
8746 Self::I64(t) => t.strides(),
8747 Self::Bool(t) => t.strides(),
8748 Self::C32(t) => t.strides(),
8749 Self::C64(t) => t.strides(),
8750 }
8751 }
8752
8753 pub fn offset(&self) -> isize {
8754 match self {
8755 Self::F32(t) => t.offset(),
8756 Self::F64(t) => t.offset(),
8757 Self::I32(t) => t.offset(),
8758 Self::I64(t) => t.offset(),
8759 Self::Bool(t) => t.offset(),
8760 Self::C32(t) => t.offset(),
8761 Self::C64(t) => t.offset(),
8762 }
8763 }
8764
8765 /// Return whether this mutable view writes host-addressed memory.
8766 ///
8767 /// See [`TypedTensorViewMut::is_host_memory`]; it is the same answer
8768 /// [`Self::try_mut_host`] acts on.
8769 ///
8770 /// # Examples
8771 ///
8772 /// ```rust
8773 /// use tenferro_tensor::TensorViewMut;
8774 ///
8775 /// let mut data = [1.0_f64, 2.0];
8776 /// let view = TensorViewMut::f64(&[2], &mut data)?;
8777 /// assert!(view.is_host_memory());
8778 /// # Ok::<(), tenferro_tensor::Error>(())
8779 /// ```
8780 pub fn is_host_memory(&self) -> bool {
8781 match self {
8782 Self::F32(t) => t.is_host_memory(),
8783 Self::F64(t) => t.is_host_memory(),
8784 Self::I32(t) => t.is_host_memory(),
8785 Self::I64(t) => t.is_host_memory(),
8786 Self::Bool(t) => t.is_host_memory(),
8787 Self::C32(t) => t.is_host_memory(),
8788 Self::C64(t) => t.is_host_memory(),
8789 }
8790 }
8791
8792 /// Compute the physical element offset for a logical index.
8793 ///
8794 /// # Errors
8795 ///
8796 /// Returns [`crate::Error::Validation`] with
8797 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
8798 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
8799 /// when an index is outside its axis extent, or
8800 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
8801 /// arithmetic overflows.
8802 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
8803 match self {
8804 Self::F32(t) => t.layout_linear_offset(indices),
8805 Self::F64(t) => t.layout_linear_offset(indices),
8806 Self::I32(t) => t.layout_linear_offset(indices),
8807 Self::I64(t) => t.layout_linear_offset(indices),
8808 Self::Bool(t) => t.layout_linear_offset(indices),
8809 Self::C32(t) => t.layout_linear_offset(indices),
8810 Self::C64(t) => t.layout_linear_offset(indices),
8811 }
8812 }
8813
8814 /// Return whether this view is compact column-major.
8815 ///
8816 /// # Errors
8817 ///
8818 /// Returns [`crate::Error::Validation`] with
8819 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8820 /// compactness arithmetic overflows.
8821 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
8822 match self {
8823 Self::F32(t) => t.is_col_major_contiguous(),
8824 Self::F64(t) => t.is_col_major_contiguous(),
8825 Self::I32(t) => t.is_col_major_contiguous(),
8826 Self::I64(t) => t.is_col_major_contiguous(),
8827 Self::Bool(t) => t.is_col_major_contiguous(),
8828 Self::C32(t) => t.is_col_major_contiguous(),
8829 Self::C64(t) => t.is_col_major_contiguous(),
8830 }
8831 }
8832
8833 pub fn layout_summary(&self) -> String {
8834 layout_summary(self.shape(), self.strides(), self.offset())
8835 }
8836
8837 /// Assert this view is compact column-major.
8838 ///
8839 /// # Errors
8840 ///
8841 /// Returns [`crate::Error::Validation`] with
8842 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
8843 /// compactness arithmetic overflows, or
8844 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
8845 /// view is not compact column-major.
8846 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
8847 assert_layout_col_major_contiguous(
8848 self.is_col_major_contiguous()?,
8849 self.shape(),
8850 self.strides(),
8851 self.offset(),
8852 "TensorViewMut::assert_col_major_contiguous",
8853 )
8854 }
8855
8856 /// Explicitly duplicate the compact host data visible through this
8857 /// mutable view into a new tensor owner.
8858 ///
8859 /// # Examples
8860 ///
8861 /// ```
8862 /// use tenferro_tensor::{TensorViewMut, TypedTensorViewMut};
8863 ///
8864 /// let mut data = [1_i32, 2];
8865 /// let view = TensorViewMut::I32(TypedTensorViewMut::from_slice(
8866 /// vec![2], vec![1], 0, &mut data,
8867 /// )?);
8868 /// let copy = view.duplicate()?;
8869 /// assert_eq!(copy.shape(), &[2]);
8870 /// # Ok::<(), tenferro_tensor::Error>(())
8871 /// ```
8872 ///
8873 /// # Errors
8874 ///
8875 /// Returns [`crate::Error::HostAccess`] for backend-owned views,
8876 /// [`ValidationError::NonContiguousViewAsSlice`] for non-contiguous views,
8877 /// or [`ValidationError::InvalidArgument`] for invalid layout metadata.
8878 pub fn duplicate(&self) -> crate::Result<Tensor> {
8879 self.as_read_only().duplicate()
8880 }
8881
8882 /// Borrow this mutable view as a read-only dtype-erased view.
8883 ///
8884 /// # Examples
8885 ///
8886 /// ```
8887 /// use tenferro_tensor::TensorViewMut;
8888 ///
8889 /// let mut data = [1.0_f64, 2.0];
8890 /// let view = TensorViewMut::f64(&[2], &mut data)?;
8891 /// assert_eq!(view.as_read_only().as_slice::<f64>()?, &[1.0, 2.0]);
8892 /// # Ok::<(), tenferro_tensor::Error>(())
8893 /// ```
8894 pub fn as_read_only(&self) -> TensorView<'_> {
8895 match self {
8896 Self::F32(t) => TensorView::F32(t.as_read_only()),
8897 Self::F64(t) => TensorView::F64(t.as_read_only()),
8898 Self::I32(t) => TensorView::I32(t.as_read_only()),
8899 Self::I64(t) => TensorView::I64(t.as_read_only()),
8900 Self::Bool(t) => TensorView::Bool(t.as_read_only()),
8901 Self::C32(t) => TensorView::C32(t.as_read_only()),
8902 Self::C64(t) => TensorView::C64(t.as_read_only()),
8903 }
8904 }
8905}
8906
8907impl<'a> TensorRead<'a> {
8908 /// Checked narrowing of a read target to a host-marked view.
8909 ///
8910 /// This is the boundary a CPU entry point crosses once: an owned tensor is
8911 /// borrowed without copying, an existing view keeps its layout, and the
8912 /// result is a [`TensorView<'a, Host>`](TensorView) whose consumers read
8913 /// host elements without re-checking placement. `op` names the operation
8914 /// in the error, as the per-entry checks it replaces did.
8915 ///
8916 /// # Examples
8917 ///
8918 /// ```rust
8919 /// use tenferro_tensor::{DType, Tensor, TensorRead};
8920 ///
8921 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8922 /// let host = TensorRead::from_tensor(&tensor).try_host("cholesky")?;
8923 /// assert_eq!(host.dtype(), DType::F64);
8924 /// # Ok::<(), tenferro_tensor::Error>(())
8925 /// ```
8926 ///
8927 /// # Errors
8928 ///
8929 /// Returns [`crate::Error::UnsupportedDType`] attributed to `op` for a
8930 /// tensor built with [`Tensor::external`], which has no preset-scalar view,
8931 /// and [`crate::Error::RuntimeState`] attributed to `op` when the read
8932 /// borrows backend (device) storage; download the tensor to host first.
8933 pub fn try_host(self, op: &'static str) -> crate::Result<TensorView<'a, Host>> {
8934 let dtype = self.dtype();
8935 self.tensor_view()
8936 .ok_or_else(|| {
8937 crate::Error::unsupported_dtype(
8938 op,
8939 dtype,
8940 "an externally defined payload has no host tensor view",
8941 )
8942 })?
8943 .try_host(op)
8944 }
8945}
8946
8947impl<'a> TensorRead<'a> {
8948 /// Borrow an owned tensor as a read target without copying it.
8949 ///
8950 /// # Examples
8951 ///
8952 /// ```
8953 /// use tenferro_tensor::{Tensor, TensorRead};
8954 ///
8955 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8956 /// let read = TensorRead::from_tensor(&tensor);
8957 /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
8958 /// # Ok::<(), tenferro_tensor::Error>(())
8959 /// ```
8960 pub fn from_tensor(tensor: &'a Tensor) -> Self {
8961 Self::Tensor(tensor)
8962 }
8963
8964 /// Wrap a borrowed dtype-erased view as a read target.
8965 ///
8966 /// # Examples
8967 ///
8968 /// ```
8969 /// use tenferro_tensor::{TensorRead, TensorView};
8970 ///
8971 /// let read = TensorRead::from_view(TensorView::i32(&[2], &[3, 4])?);
8972 /// assert_eq!(read.as_slice::<i32>()?, &[3, 4]);
8973 /// assert!(read.as_tensor().is_none());
8974 /// # Ok::<(), tenferro_tensor::Error>(())
8975 /// ```
8976 #[inline]
8977 pub fn from_view(view: TensorView<'a>) -> Self {
8978 Self::View(view)
8979 }
8980
8981 /// Convert this read target into a dtype-erased tensor view, or `None` when
8982 /// it borrows a tensor with an externally defined payload.
8983 ///
8984 /// Owned tensors are borrowed without copying their storage. Existing
8985 /// views are returned as is, preserving their layout and placement metadata.
8986 /// [`TensorView`] has one variant per preset scalar (`F32` ... `C64`) and none
8987 /// for a caller-owned element type, so a tensor built from
8988 /// [`Tensor::external`] has no view; read it through
8989 /// [`Tensor::external_payload`] instead.
8990 ///
8991 /// # Examples
8992 ///
8993 /// ```rust
8994 /// use tenferro_tensor::{DynRank, ErasedHostTensor, Host, Tensor, TensorRead, TypedTensor};
8995 ///
8996 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
8997 /// let view = TensorRead::from_tensor(&tensor)
8998 /// .tensor_view()
8999 /// .ok_or("a preset f64 tensor has a view")?;
9000 /// assert_eq!(view.shape(), &[2]);
9001 /// assert_eq!(view.as_slice::<f64>()?, &[1.0, 2.0]);
9002 ///
9003 /// let payload = ErasedHostTensor::new(
9004 /// TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?,
9005 /// );
9006 /// let external = Tensor::external(payload);
9007 /// assert!(TensorRead::from_tensor(&external).tensor_view().is_none());
9008 /// # Ok::<(), Box<dyn std::error::Error>>(())
9009 /// ```
9010 #[must_use]
9011 pub fn tensor_view(self) -> Option<TensorView<'a>> {
9012 match self {
9013 Self::Tensor(tensor) => tensor_view_with_layout(tensor, tensor_layout(tensor)),
9014 Self::View(view) => Some(view),
9015 }
9016 }
9017
9018 /// Build a metadata-only stride-0 broadcast of this read.
9019 ///
9020 /// An owned preset is borrowed and an existing view keeps its buffer,
9021 /// retained root and placement, so the result copies no elements and
9022 /// allocates no storage. A caller that can consume a read-only operand
9023 /// should use this instead of the materializing session
9024 /// `broadcast_in_dim_read`.
9025 ///
9026 /// # Examples
9027 ///
9028 /// ```
9029 /// use tenferro_tensor::{Tensor, TensorRead};
9030 ///
9031 /// let tensor = Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?;
9032 /// let read = TensorRead::from_tensor(&tensor).broadcast_in_dim_view(&[2, 3], &[1])?;
9033 /// assert_eq!(read.shape(), &[2, 3]);
9034 /// assert_eq!(read.strides()?, vec![0, 1]);
9035 /// # Ok::<(), tenferro_tensor::Error>(())
9036 /// ```
9037 ///
9038 /// # Errors
9039 ///
9040 /// Returns [`crate::Error::UnsupportedDType`] for a caller-owned payload,
9041 /// which has no borrowed view, or a validation error when `dims` does not
9042 /// map this read's layout into `shape`.
9043 #[doc(hidden)]
9044 pub fn broadcast_in_dim_view(self, shape: &[usize], dims: &[usize]) -> crate::Result<Self> {
9045 let dtype = self.dtype();
9046 let view = self.tensor_view().ok_or_else(|| {
9047 crate::Error::unsupported_dtype(
9048 "TensorRead::broadcast_in_dim_view",
9049 dtype,
9050 "a caller-owned payload has no borrowed broadcast view",
9051 )
9052 })?;
9053 Ok(Self::View(match view {
9054 TensorView::F32(view) => TensorView::F32(broadcast_typed_view(view, shape, dims)?),
9055 TensorView::F64(view) => TensorView::F64(broadcast_typed_view(view, shape, dims)?),
9056 TensorView::I32(view) => TensorView::I32(broadcast_typed_view(view, shape, dims)?),
9057 TensorView::I64(view) => TensorView::I64(broadcast_typed_view(view, shape, dims)?),
9058 TensorView::Bool(view) => TensorView::Bool(broadcast_typed_view(view, shape, dims)?),
9059 TensorView::C32(view) => TensorView::C32(broadcast_typed_view(view, shape, dims)?),
9060 TensorView::C64(view) => TensorView::C64(broadcast_typed_view(view, shape, dims)?),
9061 }))
9062 }
9063
9064 /// Borrow this read target as a typed compact host slice without allocation.
9065 ///
9066 /// This delegates to [`TensorView::as_slice`]. Cloning a `TensorRead` is a
9067 /// shallow clone of its borrowed reference or view metadata, so the returned
9068 /// slice retains the original `'a` storage lifetime and never outlives the
9069 /// storage borrowed by this read target. This method does not materialize,
9070 /// transfer, or otherwise canonicalize the input.
9071 ///
9072 /// # Errors
9073 ///
9074 /// Returns [`ValidationError::DTypeMismatch`] when `T` does not match the
9075 /// input dtype, [`ValidationError::NonContiguousViewAsSlice`] for a
9076 /// noncompact view, a typed runtime-state host-access error for
9077 /// backend-owned storage, or [`crate::Error::UnsupportedDType`] for a
9078 /// tensor built with [`Tensor::external`], which has no preset-scalar view.
9079 /// Backend-owned inputs are never downloaded implicitly.
9080 ///
9081 /// # Examples
9082 ///
9083 /// ```
9084 /// use tenferro_tensor::{Tensor, TensorRead};
9085 ///
9086 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9087 /// let read = TensorRead::from_tensor(&tensor);
9088 /// assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);
9089 /// # Ok::<(), tenferro_tensor::Error>(())
9090 /// ```
9091 pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&'a [T]> {
9092 self.clone()
9093 .tensor_view()
9094 .ok_or_else(|| {
9095 crate::Error::unsupported_dtype(
9096 "TensorRead::as_slice",
9097 self.dtype(),
9098 "a caller-owned payload has no preset-scalar host slice; read it through Tensor::external_payload",
9099 )
9100 })?
9101 .as_slice()
9102 }
9103
9104 /// Return the element dtype of this read target.
9105 ///
9106 /// # Examples
9107 ///
9108 /// ```
9109 /// use tenferro_tensor::{DType, Tensor, TensorRead};
9110 ///
9111 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1_i64])?;
9112 /// assert_eq!(TensorRead::from_tensor(&tensor).dtype(), DType::I64);
9113 /// # Ok::<(), tenferro_tensor::Error>(())
9114 /// ```
9115 pub fn dtype(&self) -> DType {
9116 match self {
9117 Self::Tensor(tensor) => tensor.dtype(),
9118 Self::View(view) => view.dtype(),
9119 }
9120 }
9121
9122 /// Return the logical shape of this read target.
9123 ///
9124 /// # Examples
9125 ///
9126 /// ```
9127 /// use tenferro_tensor::{Tensor, TensorRead};
9128 ///
9129 /// let tensor = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
9130 /// assert_eq!(TensorRead::from_tensor(&tensor).shape(), &[2, 1]);
9131 /// # Ok::<(), tenferro_tensor::Error>(())
9132 /// ```
9133 pub fn shape(&self) -> &[usize] {
9134 match self {
9135 Self::Tensor(tensor) => tensor.shape(),
9136 Self::View(view) => view.shape(),
9137 }
9138 }
9139
9140 /// Return the placement metadata carried by this read target.
9141 ///
9142 /// # Examples
9143 ///
9144 /// ```
9145 /// use tenferro_tensor::{MemoryKind, Tensor, TensorRead};
9146 ///
9147 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9148 /// let read = TensorRead::from_tensor(&tensor);
9149 /// assert_eq!(read.placement().memory_kind, MemoryKind::UnpinnedHost);
9150 /// # Ok::<(), tenferro_tensor::Error>(())
9151 /// ```
9152 pub fn placement(&self) -> &Placement {
9153 match self {
9154 Self::Tensor(tensor) => tensor.placement(),
9155 Self::View(view) => view.placement(),
9156 }
9157 }
9158
9159 /// Return whether this read target borrows host-addressed memory.
9160 ///
9161 /// The one host/device answer a CPU entry point needs, decided by the
9162 /// payload and never by [`Placement::memory_kind`]; it is the same answer
9163 /// [`Self::try_host`] acts on, and the same one
9164 /// [`TypedTensor::is_host_memory`] gives for an owner.
9165 ///
9166 /// # Examples
9167 ///
9168 /// ```rust
9169 /// use tenferro_tensor::{Tensor, TensorRead};
9170 ///
9171 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9172 /// assert!(TensorRead::from_tensor(&tensor).is_host_memory());
9173 /// # Ok::<(), tenferro_tensor::Error>(())
9174 /// ```
9175 pub fn is_host_memory(&self) -> bool {
9176 match self {
9177 Self::Tensor(tensor) => tensor.is_host_memory(),
9178 Self::View(view) => view.is_host_memory(),
9179 }
9180 }
9181
9182 /// Return the physical backend family of this read target, when backend-owned.
9183 ///
9184 /// # Examples
9185 ///
9186 /// ```
9187 /// use tenferro_tensor::{Tensor, TensorRead};
9188 ///
9189 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9190 /// assert_eq!(TensorRead::from_tensor(&tensor).backend_family(), None);
9191 /// # Ok::<(), tenferro_tensor::Error>(())
9192 /// ```
9193 pub fn backend_family(&self) -> Option<&'static str> {
9194 match self {
9195 Self::Tensor(tensor) => match tensor.dtype() {
9196 // A caller-owned payload is host memory without backend family.
9197 DType::External(_) => None,
9198 DType::F32 => tensor.as_typed::<f32>().and_then(|t| t.backend_family()),
9199 DType::F64 => tensor.as_typed::<f64>().and_then(|t| t.backend_family()),
9200 DType::I32 => tensor.as_typed::<i32>().and_then(|t| t.backend_family()),
9201 DType::I64 => tensor.as_typed::<i64>().and_then(|t| t.backend_family()),
9202 DType::Bool => tensor.as_typed::<bool>().and_then(|t| t.backend_family()),
9203 DType::C32 => tensor
9204 .as_typed::<Complex<f32>>()
9205 .and_then(|t| t.backend_family()),
9206 DType::C64 => tensor
9207 .as_typed::<Complex<f64>>()
9208 .and_then(|t| t.backend_family()),
9209 },
9210 Self::View(view) => view.backend_family(),
9211 }
9212 }
9213
9214 /// Return the shared allocation domain of this read target, when present.
9215 ///
9216 /// # Examples
9217 ///
9218 /// ```
9219 /// use tenferro_tensor::{Tensor, TensorRead};
9220 ///
9221 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9222 /// assert_eq!(TensorRead::from_tensor(&tensor).allocation_domain(), None);
9223 /// # Ok::<(), tenferro_tensor::Error>(())
9224 /// ```
9225 pub fn allocation_domain(&self) -> Option<AllocationDomainId> {
9226 match self {
9227 Self::Tensor(tensor) => match tensor.dtype() {
9228 // A caller-owned payload has no allocation domain.
9229 DType::External(_) => None,
9230 DType::F32 => tensor.as_typed::<f32>().and_then(|t| t.allocation_domain()),
9231 DType::F64 => tensor.as_typed::<f64>().and_then(|t| t.allocation_domain()),
9232 DType::I32 => tensor.as_typed::<i32>().and_then(|t| t.allocation_domain()),
9233 DType::I64 => tensor.as_typed::<i64>().and_then(|t| t.allocation_domain()),
9234 DType::Bool => tensor
9235 .as_typed::<bool>()
9236 .and_then(|t| t.allocation_domain()),
9237 DType::C32 => tensor
9238 .as_typed::<Complex<f32>>()
9239 .and_then(|t| t.allocation_domain()),
9240 DType::C64 => tensor
9241 .as_typed::<Complex<f64>>()
9242 .and_then(|t| t.allocation_domain()),
9243 },
9244 Self::View(view) => view.allocation_domain(),
9245 }
9246 }
9247
9248 /// Return strides in element units; owned tensors report compact column-major strides.
9249 ///
9250 /// # Examples
9251 ///
9252 /// ```
9253 /// use tenferro_tensor::{Tensor, TensorRead};
9254 ///
9255 /// let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9256 /// assert_eq!(TensorRead::from_tensor(&tensor).strides()?, vec![1, 2]);
9257 /// # Ok::<(), tenferro_tensor::Error>(())
9258 /// ```
9259 ///
9260 /// # Errors
9261 ///
9262 /// Returns [`crate::Error::Validation`] with
9263 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9264 /// column-major stride arithmetic overflows.
9265 pub fn strides(&self) -> crate::Result<Vec<isize>> {
9266 match self {
9267 Self::Tensor(tensor) => Ok(col_major_strides(tensor.shape())?.into_vec()),
9268 Self::View(view) => Ok(view.strides().to_vec()),
9269 }
9270 }
9271
9272 /// Return the physical element offset; owned tensors always start at `0`.
9273 ///
9274 /// # Examples
9275 ///
9276 /// ```
9277 /// use tenferro_tensor::{TensorRead, TensorView, TypedTensorView};
9278 ///
9279 /// let data = [1.0_f64, 2.0, 3.0];
9280 /// let view = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![1], 1, &data)?);
9281 /// assert_eq!(TensorRead::from_view(view).offset(), 1);
9282 /// # Ok::<(), tenferro_tensor::Error>(())
9283 /// ```
9284 pub fn offset(&self) -> isize {
9285 match self {
9286 Self::Tensor(_) => 0,
9287 Self::View(view) => view.offset(),
9288 }
9289 }
9290
9291 /// Compute the physical element offset for a logical index.
9292 ///
9293 /// # Examples
9294 ///
9295 /// ```
9296 /// use tenferro_tensor::{Tensor, TensorRead};
9297 ///
9298 /// let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9299 /// let read = TensorRead::from_tensor(&tensor);
9300 /// assert_eq!(read.layout_linear_offset(&[1, 2])?, 5);
9301 /// assert!(read.layout_linear_offset(&[2, 0]).is_err());
9302 /// # Ok::<(), tenferro_tensor::Error>(())
9303 /// ```
9304 ///
9305 /// # Errors
9306 ///
9307 /// Returns [`crate::Error::Validation`] with
9308 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
9309 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
9310 /// when an index is outside its axis extent, or
9311 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
9312 /// arithmetic overflows.
9313 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
9314 match self {
9315 Self::Tensor(tensor) => tensor.layout_linear_offset(indices),
9316 Self::View(view) => view.layout_linear_offset(indices),
9317 }
9318 }
9319
9320 /// Return whether this read target is compact column-major.
9321 ///
9322 /// # Examples
9323 ///
9324 /// ```
9325 /// use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
9326 ///
9327 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9328 /// assert!(TensorRead::from_tensor(&tensor).is_col_major_contiguous()?);
9329 /// let data = [1.0_f64, 2.0, 3.0];
9330 /// let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
9331 /// assert!(!TensorRead::from_view(strided).is_col_major_contiguous()?);
9332 /// # Ok::<(), tenferro_tensor::Error>(())
9333 /// ```
9334 ///
9335 /// # Errors
9336 ///
9337 /// Returns [`crate::Error::Validation`] with
9338 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9339 /// compactness arithmetic overflows.
9340 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
9341 match self {
9342 Self::Tensor(tensor) => tensor.is_col_major_contiguous(),
9343 Self::View(view) => view.is_col_major_contiguous(),
9344 }
9345 }
9346
9347 /// Return a compact string summary of this read target's layout metadata.
9348 ///
9349 /// # Examples
9350 ///
9351 /// ```
9352 /// use tenferro_tensor::{Tensor, TensorRead};
9353 ///
9354 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9355 /// assert_eq!(
9356 /// TensorRead::from_tensor(&tensor).layout_summary(),
9357 /// "shape=[2] strides=[1] offset=0"
9358 /// );
9359 /// # Ok::<(), tenferro_tensor::Error>(())
9360 /// ```
9361 pub fn layout_summary(&self) -> String {
9362 let strides = match self.strides() {
9363 Ok(strides) => strides,
9364 Err(err) => return format!("layout unavailable: {err}"),
9365 };
9366 layout_summary(self.shape(), &strides, self.offset())
9367 }
9368
9369 /// Assert this read target is compact column-major.
9370 ///
9371 /// # Examples
9372 ///
9373 /// ```
9374 /// use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
9375 ///
9376 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9377 /// TensorRead::from_tensor(&tensor).assert_col_major_contiguous()?;
9378 /// let data = [1.0_f64, 2.0, 3.0];
9379 /// let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
9380 /// assert!(TensorRead::from_view(strided).assert_col_major_contiguous().is_err());
9381 /// # Ok::<(), tenferro_tensor::Error>(())
9382 /// ```
9383 ///
9384 /// # Errors
9385 ///
9386 /// Returns [`crate::Error::Validation`] with
9387 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9388 /// compactness arithmetic overflows, or
9389 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
9390 /// view is not compact column-major.
9391 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
9392 let strides = self.strides()?;
9393 assert_layout_col_major_contiguous(
9394 self.is_col_major_contiguous()?,
9395 self.shape(),
9396 &strides,
9397 self.offset(),
9398 "TensorRead::assert_col_major_contiguous",
9399 )
9400 }
9401
9402 /// Return the borrowed owned tensor, or `None` when this read target is a view.
9403 ///
9404 /// # Examples
9405 ///
9406 /// ```
9407 /// use tenferro_tensor::{Tensor, TensorRead, TensorView};
9408 ///
9409 /// let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
9410 /// assert!(TensorRead::from_tensor(&tensor).as_tensor().is_some());
9411 /// assert!(TensorRead::from_view(TensorView::f64(&[1], &[1.0])?).as_tensor().is_none());
9412 /// # Ok::<(), tenferro_tensor::Error>(())
9413 /// ```
9414 pub fn as_tensor(&self) -> Option<&'a Tensor> {
9415 match self {
9416 Self::Tensor(tensor) => Some(*tensor),
9417 Self::View(_) => None,
9418 }
9419 }
9420}
9421
9422impl<'a> TensorWrite<'a> {
9423 /// Checked narrowing of a write target to a host-marked mutable view.
9424 ///
9425 /// The write counterpart of [`TensorRead::try_host`]: an owned tensor is
9426 /// borrowed mutably without copying, an existing view keeps its layout, and
9427 /// the result is a [`TensorViewMut<'a, Host>`](TensorViewMut) whose
9428 /// consumers write host elements without re-checking placement. `op` names
9429 /// the operation in the error.
9430 ///
9431 /// # Examples
9432 ///
9433 /// ```rust
9434 /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9435 ///
9436 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![0.0_f64; 2])?;
9437 /// let host = TensorWrite::from_tensor(&mut tensor).try_mut_host("solve_read_into")?;
9438 /// assert_eq!(host.dtype(), DType::F64);
9439 /// assert_eq!(host.shape(), &[2]);
9440 /// # Ok::<(), tenferro_tensor::Error>(())
9441 /// ```
9442 ///
9443 /// # Errors
9444 ///
9445 /// Returns [`crate::Error::UnsupportedDType`] attributed to `op` for a
9446 /// tensor built with [`Tensor::external`], which has no preset-scalar view,
9447 /// and [`crate::Error::RuntimeState`] attributed to `op` when the target
9448 /// borrows backend (device) storage; download the tensor to host first.
9449 pub fn try_mut_host(self, op: &'static str) -> crate::Result<TensorViewMut<'a, Host>> {
9450 match self {
9451 Self::Tensor(tensor) => {
9452 let dtype = tensor.dtype();
9453 tensor_view_mut_of(tensor).ok_or_else(|| {
9454 crate::Error::unsupported_dtype(
9455 op,
9456 dtype,
9457 "an externally defined payload has no host tensor view",
9458 )
9459 })?
9460 }
9461 Self::View(view) => view,
9462 }
9463 .try_mut_host(op)
9464 }
9465}
9466
9467/// Mutably borrow an owned tensor as a dtype-erased view, or `None` when it
9468/// holds an externally defined payload ([`TensorViewMut`] has no arm for it).
9469fn tensor_view_mut_of(tensor: &mut Tensor) -> Option<TensorViewMut<'_>> {
9470 Some(match tensor.dtype() {
9471 DType::F32 => TensorViewMut::F32(tensor.as_typed_mut::<f32>()?.as_view_mut()),
9472 DType::F64 => TensorViewMut::F64(tensor.as_typed_mut::<f64>()?.as_view_mut()),
9473 DType::I32 => TensorViewMut::I32(tensor.as_typed_mut::<i32>()?.as_view_mut()),
9474 DType::I64 => TensorViewMut::I64(tensor.as_typed_mut::<i64>()?.as_view_mut()),
9475 DType::Bool => TensorViewMut::Bool(tensor.as_typed_mut::<bool>()?.as_view_mut()),
9476 DType::C32 => TensorViewMut::C32(tensor.as_typed_mut::<Complex32>()?.as_view_mut()),
9477 DType::C64 => TensorViewMut::C64(tensor.as_typed_mut::<Complex64>()?.as_view_mut()),
9478 DType::External(_) => return None,
9479 })
9480}
9481
9482impl<'a> TensorWrite<'a> {
9483 /// Borrow an owned tensor as a writable target without copying it.
9484 ///
9485 /// # Examples
9486 ///
9487 /// ```
9488 /// use tenferro_tensor::{Tensor, TensorWrite};
9489 ///
9490 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9491 /// let write = TensorWrite::from_tensor(&mut tensor);
9492 /// assert_eq!(write.shape(), &[2]);
9493 /// # Ok::<(), tenferro_tensor::Error>(())
9494 /// ```
9495 pub fn from_tensor(tensor: &'a mut Tensor) -> Self {
9496 Self::Tensor(tensor)
9497 }
9498
9499 /// Wrap a borrowed mutable dtype-erased view as a writable target.
9500 ///
9501 /// # Examples
9502 ///
9503 /// ```
9504 /// use tenferro_tensor::{DType, TensorViewMut, TensorWrite};
9505 ///
9506 /// let mut data = [1.0_f64, 2.0];
9507 /// let write = TensorWrite::from_view(TensorViewMut::f64(&[2], &mut data)?);
9508 /// assert_eq!(write.dtype(), DType::F64);
9509 /// assert_eq!(write.as_read().as_slice::<f64>()?, &[1.0, 2.0]);
9510 /// # Ok::<(), tenferro_tensor::Error>(())
9511 /// ```
9512 pub fn from_view(view: TensorViewMut<'a>) -> Self {
9513 Self::View(view)
9514 }
9515
9516 /// Borrow this writable target as a read-only tensor input.
9517 ///
9518 /// This is useful for explicit read-modify-write kernels such as
9519 /// accumulation updates. The returned view borrows through `&self`, so it
9520 /// cannot outlive the current read-only borrow of the writable target.
9521 ///
9522 /// # Examples
9523 ///
9524 /// ```rust
9525 /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9526 ///
9527 /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?;
9528 /// let write = TensorWrite::from_tensor(&mut tensor);
9529 /// let read = write.as_read();
9530 /// assert_eq!(read.dtype(), DType::F64);
9531 /// # Ok::<(), tenferro_tensor::Error>(())
9532 /// ```
9533 pub fn as_read(&self) -> TensorRead<'_> {
9534 match self {
9535 Self::Tensor(tensor) => TensorRead::from_tensor(tensor),
9536 Self::View(view) => TensorRead::from_view(view.as_read_only()),
9537 }
9538 }
9539
9540 /// Return the element dtype of this writable target.
9541 ///
9542 /// # Examples
9543 ///
9544 /// ```
9545 /// use tenferro_tensor::{DType, Tensor, TensorWrite};
9546 ///
9547 /// let mut tensor = Tensor::from_vec_col_major(vec![1], vec![1_i32])?;
9548 /// assert_eq!(TensorWrite::from_tensor(&mut tensor).dtype(), DType::I32);
9549 /// # Ok::<(), tenferro_tensor::Error>(())
9550 /// ```
9551 pub fn dtype(&self) -> DType {
9552 match self {
9553 Self::Tensor(tensor) => tensor.dtype(),
9554 Self::View(view) => view.dtype(),
9555 }
9556 }
9557
9558 /// Return the logical shape of this writable target.
9559 ///
9560 /// # Examples
9561 ///
9562 /// ```
9563 /// use tenferro_tensor::{Tensor, TensorWrite};
9564 ///
9565 /// let mut tensor = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
9566 /// assert_eq!(TensorWrite::from_tensor(&mut tensor).shape(), &[2, 1]);
9567 /// # Ok::<(), tenferro_tensor::Error>(())
9568 /// ```
9569 pub fn shape(&self) -> &[usize] {
9570 match self {
9571 Self::Tensor(tensor) => tensor.shape(),
9572 Self::View(view) => view.shape(),
9573 }
9574 }
9575
9576 /// Return strides in element units; owned tensors report compact column-major strides.
9577 ///
9578 /// # Examples
9579 ///
9580 /// ```
9581 /// use tenferro_tensor::{Tensor, TensorWrite};
9582 ///
9583 /// let mut tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9584 /// assert_eq!(TensorWrite::from_tensor(&mut tensor).strides()?, vec![1, 2]);
9585 /// # Ok::<(), tenferro_tensor::Error>(())
9586 /// ```
9587 ///
9588 /// # Errors
9589 ///
9590 /// Returns [`crate::Error::Validation`] with
9591 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9592 /// column-major stride arithmetic overflows.
9593 pub fn strides(&self) -> crate::Result<Vec<isize>> {
9594 match self {
9595 Self::Tensor(tensor) => Ok(col_major_strides(tensor.shape())?.into_vec()),
9596 Self::View(view) => Ok(view.strides().to_vec()),
9597 }
9598 }
9599
9600 /// Return whether this write target writes host-addressed memory.
9601 ///
9602 /// The one host/device answer for an output, decided by the payload and
9603 /// never by [`Placement::memory_kind`]. It is the same answer
9604 /// [`Self::try_mut_host`] acts on.
9605 ///
9606 /// # Examples
9607 ///
9608 /// ```rust
9609 /// use tenferro_tensor::{Tensor, TensorWrite};
9610 ///
9611 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![0.0_f64; 2])?;
9612 /// assert!(TensorWrite::from_tensor(&mut tensor).is_host_memory());
9613 /// # Ok::<(), tenferro_tensor::Error>(())
9614 /// ```
9615 pub fn is_host_memory(&self) -> bool {
9616 match self {
9617 Self::Tensor(tensor) => tensor.is_host_memory(),
9618 Self::View(view) => view.is_host_memory(),
9619 }
9620 }
9621
9622 /// Return the physical element offset; owned tensors always start at `0`.
9623 ///
9624 /// # Examples
9625 ///
9626 /// ```
9627 /// use tenferro_tensor::{TensorViewMut, TensorWrite, TypedTensorViewMut};
9628 ///
9629 /// let mut data = [1.0_f64, 2.0, 3.0];
9630 /// let view = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![1], 1, &mut data)?);
9631 /// assert_eq!(TensorWrite::from_view(view).offset(), 1);
9632 /// # Ok::<(), tenferro_tensor::Error>(())
9633 /// ```
9634 pub fn offset(&self) -> isize {
9635 match self {
9636 Self::Tensor(_) => 0,
9637 Self::View(view) => view.offset(),
9638 }
9639 }
9640
9641 /// Compute the physical element offset for a logical index.
9642 ///
9643 /// # Examples
9644 ///
9645 /// ```
9646 /// use tenferro_tensor::{Tensor, TensorWrite};
9647 ///
9648 /// let mut tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
9649 /// let write = TensorWrite::from_tensor(&mut tensor);
9650 /// assert_eq!(write.layout_linear_offset(&[1, 2])?, 5);
9651 /// assert!(write.layout_linear_offset(&[0]).is_err());
9652 /// # Ok::<(), tenferro_tensor::Error>(())
9653 /// ```
9654 ///
9655 /// # Errors
9656 ///
9657 /// Returns [`crate::Error::Validation`] with
9658 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
9659 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
9660 /// when an index is outside its axis extent, or
9661 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
9662 /// arithmetic overflows.
9663 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
9664 match self {
9665 Self::Tensor(tensor) => tensor.layout_linear_offset(indices),
9666 Self::View(view) => view.layout_linear_offset(indices),
9667 }
9668 }
9669
9670 /// Return whether this writable target is compact column-major.
9671 ///
9672 /// # Examples
9673 ///
9674 /// ```
9675 /// use tenferro_tensor::{Tensor, TensorViewMut, TensorWrite, TypedTensorViewMut};
9676 ///
9677 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9678 /// assert!(TensorWrite::from_tensor(&mut tensor).is_col_major_contiguous()?);
9679 /// let mut data = [1.0_f64, 2.0, 3.0];
9680 /// let strided = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![2], 0, &mut data)?);
9681 /// assert!(!TensorWrite::from_view(strided).is_col_major_contiguous()?);
9682 /// # Ok::<(), tenferro_tensor::Error>(())
9683 /// ```
9684 ///
9685 /// # Errors
9686 ///
9687 /// Returns [`crate::Error::Validation`] with
9688 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9689 /// compactness arithmetic overflows.
9690 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
9691 match self {
9692 Self::Tensor(tensor) => tensor.is_col_major_contiguous(),
9693 Self::View(view) => view.is_col_major_contiguous(),
9694 }
9695 }
9696
9697 /// Return a compact string summary of this writable target's layout metadata.
9698 ///
9699 /// # Examples
9700 ///
9701 /// ```
9702 /// use tenferro_tensor::{Tensor, TensorWrite};
9703 ///
9704 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9705 /// assert_eq!(
9706 /// TensorWrite::from_tensor(&mut tensor).layout_summary(),
9707 /// "shape=[2] strides=[1] offset=0"
9708 /// );
9709 /// # Ok::<(), tenferro_tensor::Error>(())
9710 /// ```
9711 pub fn layout_summary(&self) -> String {
9712 let strides = match self.strides() {
9713 Ok(strides) => strides,
9714 Err(err) => return format!("layout unavailable: {err}"),
9715 };
9716 layout_summary(self.shape(), &strides, self.offset())
9717 }
9718
9719 /// Assert this writable target is compact column-major.
9720 ///
9721 /// # Examples
9722 ///
9723 /// ```
9724 /// use tenferro_tensor::{Tensor, TensorViewMut, TensorWrite, TypedTensorViewMut};
9725 ///
9726 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
9727 /// TensorWrite::from_tensor(&mut tensor).assert_col_major_contiguous()?;
9728 /// let mut data = [1.0_f64, 2.0, 3.0];
9729 /// let strided = TensorViewMut::F64(TypedTensorViewMut::from_slice(vec![2], vec![2], 0, &mut data)?);
9730 /// assert!(TensorWrite::from_view(strided).assert_col_major_contiguous().is_err());
9731 /// # Ok::<(), tenferro_tensor::Error>(())
9732 /// ```
9733 ///
9734 /// # Errors
9735 ///
9736 /// Returns [`crate::Error::Validation`] with
9737 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
9738 /// compactness arithmetic overflows, or
9739 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
9740 /// view is not compact column-major.
9741 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
9742 let strides = self.strides()?;
9743 assert_layout_col_major_contiguous(
9744 self.is_col_major_contiguous()?,
9745 self.shape(),
9746 &strides,
9747 self.offset(),
9748 "TensorWrite::assert_col_major_contiguous",
9749 )
9750 }
9751}
9752
9753/// Column-major strides derived from a shape.
9754///
9755/// # Examples
9756///
9757/// ```rust
9758/// use tenferro_tensor::col_major_strides;
9759///
9760/// assert_eq!(col_major_strides(&[2, 3])?.as_slice(), &[1, 2]);
9761/// # Ok::<(), tenferro_tensor::Error>(())
9762/// ```
9763/// # Errors
9764///
9765/// Returns [`crate::Error::Validation`] with
9766/// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when a
9767/// column-major stride product overflows.
9768pub fn col_major_strides(shape: &[usize]) -> crate::Result<StrideVec> {
9769 // Inline for common ranks: every compact destination on the CPU and CUDA
9770 // paths derives its strides here, so the heap is off this path entirely.
9771 let mut strides = StrideVec::with_capacity(shape.len());
9772 let mut stride = 1isize;
9773 for &extent in shape {
9774 strides.push(stride);
9775 let extent = isize::try_from(extent).map_err(|_| {
9776 crate::Error::validation("col_major_strides", ValidationError::IntegerOverflow)
9777 })?;
9778 stride = stride.checked_mul(extent).ok_or_else(|| {
9779 crate::Error::validation("col_major_strides", ValidationError::IntegerOverflow)
9780 })?;
9781 }
9782 Ok(strides)
9783}
9784
9785fn try_linear_offset_for_shape(
9786 shape: &[usize],
9787 indices: &[usize],
9788 op: &'static str,
9789) -> crate::Result<usize> {
9790 if indices.len() != shape.len() {
9791 return Err(crate::Error::validation(
9792 op,
9793 ValidationError::RankMismatch {
9794 expected: shape.len(),
9795 actual: indices.len(),
9796 },
9797 ));
9798 }
9799 let mut offset = 0usize;
9800 let mut stride = 1usize;
9801 for (axis, (&idx, &extent)) in indices.iter().zip(shape).enumerate() {
9802 if idx >= extent {
9803 return Err(crate::Error::invalid_argument(
9804 op,
9805 "index",
9806 format!("index {idx} out of bounds for axis {axis} extent {extent}"),
9807 ));
9808 }
9809 offset =
9810 offset
9811 .checked_add(idx.checked_mul(stride).ok_or_else(|| {
9812 crate::Error::validation(op, ValidationError::IntegerOverflow)
9813 })?)
9814 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
9815 stride = stride
9816 .checked_mul(extent)
9817 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
9818 }
9819 Ok(offset)
9820}
9821
9822fn checked_view_offset_result(
9823 shape: &[usize],
9824 strides: &[isize],
9825 base_offset: isize,
9826 indices: &[usize],
9827 op: &'static str,
9828) -> crate::Result<usize> {
9829 if indices.len() != shape.len() {
9830 return Err(crate::Error::validation(
9831 op,
9832 ValidationError::RankMismatch {
9833 expected: shape.len(),
9834 actual: indices.len(),
9835 },
9836 ));
9837 }
9838 for (axis, (&index, &extent)) in indices.iter().zip(shape).enumerate() {
9839 if index >= extent {
9840 return Err(crate::Error::invalid_argument(
9841 op,
9842 "index",
9843 format!("index {index} out of bounds for axis {axis} extent {extent}"),
9844 ));
9845 }
9846 }
9847 checked_view_offset(shape, strides, base_offset, indices)
9848 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9849}
9850
9851fn layout_summary(shape: &[usize], strides: &[isize], offset: isize) -> String {
9852 format!("shape={shape:?} strides={strides:?} offset={offset}")
9853}
9854
9855fn assert_layout_col_major_contiguous(
9856 is_contiguous: bool,
9857 shape: &[usize],
9858 strides: &[isize],
9859 offset: isize,
9860 op: &'static str,
9861) -> crate::Result<()> {
9862 if is_contiguous {
9863 Ok(())
9864 } else {
9865 Err(crate::Error::invalid_argument(
9866 op,
9867 "layout",
9868 format!(
9869 "expected compact column-major layout, got {}",
9870 layout_summary(shape, strides, offset)
9871 ),
9872 ))
9873 }
9874}
9875
9876fn try_shape_product(shape: &[usize], op: &'static str) -> crate::Result<usize> {
9877 shape.iter().try_fold(1usize, |acc, &dim| {
9878 acc.checked_mul(dim)
9879 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9880 })
9881}
9882
9883fn try_checked_shape_len(shape: &[usize], data_len: usize, op: &'static str) -> crate::Result<()> {
9884 let n = try_shape_product(shape, op)?;
9885 if data_len != n {
9886 return Err(crate::Error::validation(
9887 op,
9888 ValidationError::ShapeDataLengthMismatch {
9889 expected: n,
9890 actual: data_len,
9891 },
9892 ));
9893 }
9894 Ok(())
9895}
9896
9897fn try_compact_layout<R: TensorRank>(
9898 shape: impl tenferro_tensor_core::IntoRankShape<R>,
9899 op: &'static str,
9900) -> crate::Result<TensorLayout<R>> {
9901 let shape = shape
9902 .into_rank_shape()
9903 .map_err(|err| tensor_layout_error(op, err))?;
9904 TensorLayout::compact(shape).map_err(|err| tensor_layout_error(op, err))
9905}
9906
9907fn tensor_layout_error(
9908 op: &'static str,
9909 err: tenferro_tensor_core::ValidationError,
9910) -> crate::Error {
9911 crate::Error::validation(op, err)
9912}
9913
9914fn checked_view_element_count(shape: &[usize], op: &'static str) -> crate::Result<usize> {
9915 if shape.contains(&0) {
9916 return Ok(0);
9917 }
9918 shape.iter().try_fold(1usize, |product, &dim| {
9919 product
9920 .checked_mul(dim)
9921 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))
9922 })
9923}
9924
9925fn checked_view_offset(
9926 shape: &[usize],
9927 strides: &[isize],
9928 base_offset: isize,
9929 indices: &[usize],
9930) -> Option<usize> {
9931 if indices.len() != shape.len() {
9932 return None;
9933 }
9934
9935 let mut offset = base_offset;
9936 for ((&index, &extent), &stride) in indices.iter().zip(shape).zip(strides) {
9937 if index >= extent {
9938 return None;
9939 }
9940 let index = isize::try_from(index).ok()?;
9941 let delta = index.checked_mul(stride)?;
9942 offset = offset.checked_add(delta)?;
9943 }
9944
9945 usize::try_from(offset).ok()
9946}
9947
9948fn reachable_layout_span(
9949 shape: &[usize],
9950 strides: &[isize],
9951 offset: isize,
9952) -> crate::Result<Option<(usize, usize)>> {
9953 if shape.contains(&0) {
9954 return Ok(None);
9955 }
9956
9957 let mut min_offset = offset;
9958 let mut max_offset = offset;
9959 for (&extent, &stride) in shape.iter().zip(strides) {
9960 let steps = isize::try_from(extent.saturating_sub(1)).map_err(|_| {
9961 crate::Error::validation(
9962 "TypedTensorViewMut::try_multi_slice_mut",
9963 ValidationError::IntegerOverflow,
9964 )
9965 })?;
9966 let end = stride.checked_mul(steps).ok_or_else(|| {
9967 crate::Error::validation(
9968 "TypedTensorViewMut::try_multi_slice_mut",
9969 ValidationError::IntegerOverflow,
9970 )
9971 })?;
9972 let (axis_min, axis_max) = if end < 0 { (end, 0) } else { (0, end) };
9973 min_offset = min_offset.checked_add(axis_min).ok_or_else(|| {
9974 crate::Error::validation(
9975 "TypedTensorViewMut::try_multi_slice_mut",
9976 ValidationError::IntegerOverflow,
9977 )
9978 })?;
9979 max_offset = max_offset.checked_add(axis_max).ok_or_else(|| {
9980 crate::Error::validation(
9981 "TypedTensorViewMut::try_multi_slice_mut",
9982 ValidationError::IntegerOverflow,
9983 )
9984 })?;
9985 }
9986
9987 let min_offset = usize::try_from(min_offset).map_err(|_| {
9988 crate::Error::invalid_argument(
9989 "TypedTensorViewMut::try_multi_slice_mut",
9990 "layout",
9991 "minimum reachable offset is negative",
9992 )
9993 })?;
9994 let max_offset = usize::try_from(max_offset).map_err(|_| {
9995 crate::Error::invalid_argument(
9996 "TypedTensorViewMut::try_multi_slice_mut",
9997 "layout",
9998 "maximum reachable offset is negative",
9999 )
10000 })?;
10001 Ok(Some((min_offset, max_offset)))
10002}
10003
10004fn split_two_mut_ranges<T>(
10005 data: &mut [T],
10006 first: (usize, usize),
10007 second: (usize, usize),
10008) -> Option<(&mut [T], &mut [T])> {
10009 if first.1 < second.0 {
10010 let (_, after_first_start) = data.split_at_mut(first.0);
10011 let (first_slice, after_first) = after_first_start.split_at_mut(first.1 - first.0 + 1);
10012 let (_, after_gap) = after_first.split_at_mut(second.0 - first.1 - 1);
10013 let (second_slice, _) = after_gap.split_at_mut(second.1 - second.0 + 1);
10014 Some((first_slice, second_slice))
10015 } else if second.1 < first.0 {
10016 let (_, after_second_start) = data.split_at_mut(second.0);
10017 let (second_slice, after_second) = after_second_start.split_at_mut(second.1 - second.0 + 1);
10018 let (_, after_gap) = after_second.split_at_mut(first.0 - second.1 - 1);
10019 let (first_slice, _) = after_gap.split_at_mut(first.1 - first.0 + 1);
10020 Some((first_slice, second_slice))
10021 } else {
10022 None
10023 }
10024}
10025
10026fn adjusted_view_offset(offset: isize, span_start: usize) -> crate::Result<isize> {
10027 let span_start = isize::try_from(span_start).map_err(|_| {
10028 crate::Error::validation(
10029 "TypedTensorViewMut::try_multi_slice_mut",
10030 ValidationError::IntegerOverflow,
10031 )
10032 })?;
10033 offset.checked_sub(span_start).ok_or_else(|| {
10034 crate::Error::validation(
10035 "TypedTensorViewMut::try_multi_slice_mut",
10036 ValidationError::IntegerOverflow,
10037 )
10038 })
10039}
10040
10041fn view_mut_from_layout_and_slice<'a, T: 'static, R: TensorRank>(
10042 layout: &TensorLayout<R>,
10043 offset: isize,
10044 data: &'a mut [T],
10045 placement: Placement,
10046) -> crate::Result<TypedTensorViewMut<'a, T, R>> {
10047 let shape = R::shape_from_vec(shape_vec(layout.shape()))
10048 .map_err(|err| tensor_layout_error("TypedTensorViewMut::try_multi_slice_mut", err))?;
10049 let strides = R::strides_from_vec(stride_vec(layout.strides()))
10050 .map_err(|err| tensor_layout_error("TypedTensorViewMut::try_multi_slice_mut", err))?;
10051 TypedTensorViewMut::from_buffer_ref_mut(
10052 shape,
10053 strides,
10054 offset,
10055 TensorStorageRefMut::Host(data),
10056 placement,
10057 "TypedTensorViewMut::try_multi_slice_mut",
10058 )
10059}
10060
10061fn contiguous_layout_slice<'a, T, R: TensorRank>(
10062 layout: &TensorLayout<R>,
10063 data: &'a [T],
10064 op: &'static str,
10065) -> crate::Result<&'a [T]> {
10066 if !layout
10067 .is_compact_col_major()
10068 .map_err(|err| tensor_layout_error(op, err))?
10069 {
10070 return Err(crate::Error::validation(
10071 op,
10072 ValidationError::NonContiguousViewAsSlice,
10073 ));
10074 }
10075 let len = checked_view_element_count(layout.shape(), op)?;
10076 let start = usize::try_from(layout.offset())
10077 .map_err(|_| crate::Error::invalid_argument(op, "layout", "view offset is negative"))?;
10078 let end = start
10079 .checked_add(len)
10080 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10081 data.get(start..end)
10082 .ok_or_else(|| crate::Error::validation(op, ValidationError::ViewOutOfBounds))
10083}
10084
10085fn relaxed_col_major_contiguous(
10086 shape: &[usize],
10087 strides: &[isize],
10088 op: &'static str,
10089) -> crate::Result<bool> {
10090 if shape.contains(&0) {
10091 return Ok(true);
10092 }
10093
10094 let mut expected = 1isize;
10095 for (&extent, &stride) in shape.iter().zip(strides) {
10096 if extent <= 1 {
10097 continue;
10098 }
10099 if stride != expected {
10100 return Ok(false);
10101 }
10102 let extent = isize::try_from(extent)
10103 .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10104 expected = expected
10105 .checked_mul(extent)
10106 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10107 }
10108 Ok(true)
10109}
10110
10111fn reshape_layout_dyn<R: TensorRank>(
10112 layout: &TensorLayout<R>,
10113 shape: &[usize],
10114 buffer_len: usize,
10115 op: &'static str,
10116) -> crate::Result<TensorLayout<DynRank>> {
10117 match layout.reshape_view_as::<DynRank>(shape_vec(shape), buffer_len) {
10118 Ok(layout) => Ok(layout),
10119 Err(err) => {
10120 if !relaxed_col_major_contiguous(layout.shape(), layout.strides(), op)? {
10121 return Err(tensor_layout_error(op, err));
10122 }
10123 let from = checked_view_element_count(layout.shape(), op)?;
10124 let to = checked_view_element_count(shape, op)?;
10125 if from != to {
10126 return Err(tensor_layout_error(
10127 op,
10128 tenferro_tensor_core::ShapeMismatch::ReshapeElementCount { from, to }.into(),
10129 ));
10130 }
10131 TensorLayout::<DynRank>::compact(shape_vec(shape))
10132 .and_then(|compact| {
10133 TensorLayout::from_parts(
10134 shape_vec(compact.shape()),
10135 stride_vec(compact.strides()),
10136 layout.offset(),
10137 buffer_len,
10138 )
10139 })
10140 .map_err(|err| tensor_layout_error(op, err))
10141 }
10142 }
10143}
10144
10145fn core_slice_specs(
10146 slices: &[StridedSliceSpec],
10147 shape: &[usize],
10148 op: &'static str,
10149) -> crate::Result<TinyVec<[CoreSliceSpec; 8]>> {
10150 if slices.len() != shape.len() {
10151 return Err(crate::Error::validation(
10152 op,
10153 ValidationError::RankMismatch {
10154 expected: shape.len(),
10155 actual: slices.len(),
10156 },
10157 ));
10158 }
10159
10160 let mut specs = TinyVec::<[CoreSliceSpec; 8]>::with_capacity(slices.len());
10161 for (slice, &axis_len) in slices.iter().zip(shape) {
10162 specs.push(core_slice_spec(*slice, axis_len, op)?);
10163 }
10164 Ok(specs)
10165}
10166
10167fn core_slice_spec(
10168 slice: StridedSliceSpec,
10169 axis_len: usize,
10170 op: &'static str,
10171) -> crate::Result<CoreSliceSpec> {
10172 if slice.step() == 0 {
10173 return Err(crate::Error::validation(
10174 op,
10175 ValidationError::InvalidSliceStep { step: slice.step() },
10176 ));
10177 }
10178
10179 let start = normalize_strided_bound(slice.start(), axis_len, op, "slice start")?;
10180 let end = match slice.end() {
10181 Some(end) => normalize_strided_bound(end, axis_len, op, "slice end")?,
10182 None => isize::try_from(axis_len)
10183 .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10184 };
10185
10186 if slice.step() > 0 {
10187 return Ok(CoreSliceSpec {
10188 start,
10189 end,
10190 step: slice.step(),
10191 });
10192 }
10193
10194 if start >= end {
10195 // `core`'s negative-step contract requires the inclusive `start` to
10196 // point at an element (`start < axis_len`). An empty selection is
10197 // step-sign independent, so encode the `start == axis_len` boundary at
10198 // the last element instead of re-encoding it verbatim (which `core`
10199 // would reject as out of bounds).
10200 let empty_start = if axis_len == 0 {
10201 start
10202 } else {
10203 start.min(axis_len as isize - 1)
10204 };
10205 return Ok(CoreSliceSpec {
10206 start: empty_start,
10207 end: empty_start,
10208 step: slice.step(),
10209 });
10210 }
10211
10212 Ok(CoreSliceSpec {
10213 start: end
10214 .checked_sub(1)
10215 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10216 end: start
10217 .checked_sub(1)
10218 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?,
10219 step: slice.step(),
10220 })
10221}
10222
10223fn normalize_strided_bound(
10224 bound: isize,
10225 axis_len: usize,
10226 op: &'static str,
10227 role: &'static str,
10228) -> crate::Result<isize> {
10229 let original_axis_len = axis_len;
10230 let axis_len = isize::try_from(axis_len)
10231 .map_err(|_| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
10232 let bound = if bound < 0 {
10233 axis_len
10234 .checked_add(bound)
10235 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?
10236 } else {
10237 bound
10238 };
10239 if !(0..=axis_len).contains(&bound) {
10240 let (start, end) = if role == "slice start" {
10241 (bound, bound)
10242 } else {
10243 (0, bound)
10244 };
10245 return Err(crate::Error::validation(
10246 op,
10247 ValidationError::InvalidSliceBounds {
10248 start,
10249 end,
10250 axis_len: original_axis_len,
10251 },
10252 ));
10253 }
10254 Ok(bound)
10255}
10256
10257fn slice_axis_specs(
10258 rank: usize,
10259 axis: usize,
10260 slice: StridedSliceSpec,
10261 op: &'static str,
10262) -> crate::Result<Vec<StridedSliceSpec>> {
10263 if axis >= rank {
10264 return Err(crate::Error::validation(
10265 op,
10266 ValidationError::AxisOutOfBounds {
10267 axis: isize::try_from(axis).unwrap_or(isize::MAX),
10268 rank,
10269 },
10270 ));
10271 }
10272
10273 let mut slices = vec![StridedSliceSpec::all(); rank];
10274 slices[axis] = slice;
10275 Ok(slices)
10276}
10277
10278pub(crate) fn default_placement() -> Placement {
10279 Placement {
10280 memory_kind: MemoryKind::UnpinnedHost,
10281 device: None,
10282 cpu_affinity: None,
10283 }
10284}
10285
10286/// Refuse a label a payload demonstrably contradicts.
10287///
10288/// One fact has one owner: the payload. A plain host payload is a Rust slice, so
10289/// `MemoryKind::Device` or `Managed` on one names memory it definitely does not
10290/// have; that is the contradiction this check refuses, and it is what keeps
10291/// "host memory labelled device-resident" out of the workspace.
10292///
10293/// The opposite direction stays legal on purpose. A backend payload is an opaque
10294/// [`BackendAllocation`](crate::BackendAllocation), so this crate cannot decide
10295/// whether the handle is device memory or host-mapped; the runtime labels such a
10296/// payload with the caller's storage class, and `MemoryKind::Other` is likewise
10297/// unmodelled. Refusing those would turn a routing key into an unrepresentable
10298/// state without removing a single alias risk.
10299///
10300/// Enforced where an owned tensor is built with an explicit placement and in
10301/// [`TypedTensor::set_placement`], the only two ways a payload and a label meet.
10302fn validate_placement_for_payload(
10303 op: &'static str,
10304 payload_is_host: bool,
10305 placement: &Placement,
10306) -> crate::Result<()> {
10307 let contradicts = payload_is_host
10308 && matches!(
10309 placement.memory_kind,
10310 MemoryKind::Device | MemoryKind::Managed
10311 );
10312 if contradicts {
10313 return Err(crate::Error::runtime_state(
10314 op,
10315 format!(
10316 "the placement says {:?} but the payload is plain host memory; a host payload cannot be device memory",
10317 placement.memory_kind
10318 ),
10319 ));
10320 }
10321 Ok(())
10322}
10323
10324fn typed_tensor_from_vec_col_major<T, R: TensorRank>(
10325 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10326 data: Vec<T>,
10327 op: &'static str,
10328) -> crate::Result<TypedTensor<T, R>> {
10329 try_typed_tensor_from_vec_col_major(shape, data, op)
10330}
10331
10332fn try_typed_tensor_from_vec_col_major<T, R: TensorRank>(
10333 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10334 data: Vec<T>,
10335 op: &'static str,
10336) -> crate::Result<TypedTensor<T, R>> {
10337 let shape = shape
10338 .into_rank_shape()
10339 .map_err(|err| tensor_layout_error(op, err))?;
10340 let layout = tenferro_tensor_core::col_major_strides(shape.as_ref())
10341 .map_err(|err| tensor_layout_error(op, err))?;
10342 try_checked_shape_len(shape.as_ref(), data.len(), op)?;
10343 Ok(TypedTensor {
10344 shape,
10345 placement: default_placement(),
10346 layout,
10347 storage: DynamicStorage::Host(HostStorage {
10348 data: HostData::new(data),
10349 }),
10350 })
10351}
10352
10353fn typed_tensor_zeros<T: TensorScalar + Zero, R: TensorRank>(
10354 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10355) -> crate::Result<TypedTensor<T, R>> {
10356 try_typed_tensor_zeros(shape)
10357}
10358
10359fn try_typed_tensor_zeros<T: TensorScalar + Clone + Zero, R: TensorRank>(
10360 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10361) -> crate::Result<TypedTensor<T, R>> {
10362 let layout = try_compact_layout(shape, "zeros")?;
10363 let n = try_shape_product(layout.shape(), "zeros")?;
10364 typed_tensor_from_vec_col_major(
10365 R::shape_from_vec(shape_vec(layout.shape()))
10366 .map_err(|err| tensor_layout_error("zeros", err))?,
10367 vec![T::zero(); n],
10368 "zeros",
10369 )
10370}
10371
10372fn typed_tensor_ones<T: TensorScalar + One + Zero, R: TensorRank>(
10373 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10374) -> crate::Result<TypedTensor<T, R>> {
10375 try_typed_tensor_ones(shape)
10376}
10377
10378fn try_typed_tensor_ones<T: TensorScalar + Clone + One + Zero, R: TensorRank>(
10379 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10380) -> crate::Result<TypedTensor<T, R>> {
10381 let layout = try_compact_layout(shape, "ones")?;
10382 let n = try_shape_product(layout.shape(), "ones")?;
10383 typed_tensor_from_vec_col_major(
10384 R::shape_from_vec(shape_vec(layout.shape()))
10385 .map_err(|err| tensor_layout_error("ones", err))?,
10386 vec![T::one(); n],
10387 "ones",
10388 )
10389}
10390
10391fn typed_tensor_from_buffer_col_major<T: TensorScalar + Send + Sync + 'static, R: TensorRank>(
10392 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10393 buffer: StorageBuffer<T>,
10394 placement: Placement,
10395) -> crate::Result<TypedTensor<T, R>> {
10396 try_typed_tensor_from_buffer_col_major(shape, buffer, placement)
10397}
10398
10399#[doc(hidden)]
10400fn typed_tensor_from_backend_allocation<T: TensorScalar + Send + Sync + 'static, R: TensorRank>(
10401 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10402 allocation: Box<dyn crate::BackendAllocation>,
10403 placement: Placement,
10404) -> crate::Result<TypedTensor<T, R>> {
10405 let layout = try_compact_layout(shape, "from_backend_allocation")?;
10406 let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
10407 .map_err(|err| tensor_layout_error("from_backend_allocation", err))?;
10408 let shape = group_shape.clone();
10409 let (mut group, slot) =
10410 AllocationGroup::from_backend_allocation::<T, R>(group_shape, allocation)
10411 .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10412 group
10413 .set_descriptor_placement(slot, placement.clone())
10414 .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10415 let allocation_index = group
10416 .allocation_index(slot)
10417 .map_err(|error| group_error("TypedTensor::from_backend_allocation", error))?;
10418 let (host_ptr, host_byte_len) = host_metadata::<T>(&group, slot);
10419 Ok(TypedTensor {
10420 shape,
10421 placement,
10422 layout: stride_vec(layout.strides()),
10423 storage: DynamicStorage::Group(GroupStorage {
10424 group: Box::new(OwnedTensorGroup {
10425 group,
10426 slot,
10427 allocation_index,
10428 host_ptr,
10429 host_byte_len,
10430 _rank: PhantomData,
10431 }),
10432 }),
10433 })
10434}
10435
10436fn try_typed_tensor_from_buffer_col_major<
10437 T: TensorScalar + Send + Sync + 'static,
10438 R: TensorRank,
10439>(
10440 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10441 buffer: StorageBuffer<T>,
10442 placement: Placement,
10443) -> crate::Result<TypedTensor<T, R>> {
10444 let layout = try_compact_layout(shape, "from_buffer_col_major")?;
10445 let len = buffer.len();
10446 try_checked_shape_len(layout.shape(), len, "from_buffer_col_major")?;
10447 let group_shape = R::shape_from_vec(shape_vec(layout.shape()))
10448 .map_err(|err| tensor_layout_error("from_buffer_col_major", err))?;
10449 match buffer {
10450 StorageBuffer::Host(data) => {
10451 validate_placement_for_payload("from_buffer_col_major", true, &placement)?;
10452 Ok(TypedTensor {
10453 shape: group_shape,
10454 placement,
10455 layout: stride_vec(layout.strides()),
10456 storage: DynamicStorage::Host(HostStorage {
10457 data: HostData::new(data),
10458 }),
10459 })
10460 }
10461 StorageBuffer::Backend(buffer) => {
10462 let group = OwnedTensorGroup::from_backend_buffer(
10463 group_shape.clone(),
10464 StorageBuffer::Backend(buffer),
10465 placement.clone(),
10466 )?;
10467 Ok(TypedTensor {
10468 shape: group_shape,
10469 placement,
10470 layout: stride_vec(layout.strides()),
10471 storage: DynamicStorage::Group(GroupStorage {
10472 group: Box::new(group),
10473 }),
10474 })
10475 }
10476 }
10477}
10478
10479impl<T: TensorScalar + Zero, R: TensorRank> TypedTensor<T, R> {
10480 /// Allocate a zero-filled tensor.
10481 ///
10482 /// # Examples
10483 ///
10484 /// ```rust
10485 /// use tenferro_tensor::TypedTensor;
10486 ///
10487 /// let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
10488 /// assert_eq!(t.n_elements(), 6);
10489 /// ```
10490 /// # Errors
10491 ///
10492 /// Returns [`crate::Error::Validation`] with
10493 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
10494 /// product or compact-stride arithmetic overflows.
10495 /// A vector or slice with a different static rank returns
10496 /// [`tenferro_tensor_core::ValidationError::RankMismatch`].
10497 pub fn zeros(shape: impl tenferro_tensor_core::IntoRankShape<R>) -> crate::Result<Self> {
10498 typed_tensor_zeros(shape)
10499 }
10500}
10501
10502impl<T: TensorScalar + One + Zero, R: TensorRank> TypedTensor<T, R> {
10503 /// Allocate a one-filled tensor.
10504 ///
10505 /// # Examples
10506 ///
10507 /// ```rust
10508 /// use tenferro_tensor::TypedTensor;
10509 ///
10510 /// let t = TypedTensor::<f64>::ones(vec![2]).unwrap();
10511 /// assert_eq!(t.host_data().unwrap(), &[1.0, 1.0]);
10512 /// ```
10513 /// # Errors
10514 ///
10515 /// Returns [`crate::Error::Validation`] with
10516 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
10517 /// product or compact-stride arithmetic overflows.
10518 /// A vector or slice with a different static rank returns
10519 /// [`tenferro_tensor_core::ValidationError::RankMismatch`].
10520 pub fn ones(shape: impl tenferro_tensor_core::IntoRankShape<R>) -> crate::Result<Self> {
10521 typed_tensor_ones(shape)
10522 }
10523}
10524
10525impl<T, R: TensorRank> TypedTensor<T, R> {
10526 /// Adopt a column-major host `Vec<T>` with no scalar, copy or thread-safety bound.
10527 ///
10528 /// # Examples
10529 /// ```
10530 /// use tenferro_tensor::{Rank, TypedTensor};
10531 /// struct Custom(String);
10532 /// let tensor = TypedTensor::<Custom, Rank<2>>::from_vec_col_major(
10533 /// [1, 2], vec![Custom("a".into()), Custom("b".into())],
10534 /// )?;
10535 /// assert_eq!(tensor.get(&[0, 1])?.0.as_str(), "b");
10536 /// # Ok::<(), tenferro_tensor::Error>(())
10537 /// ```
10538 /// # Errors
10539 /// Returns [`crate::Error::Validation`] for a rank mismatch, shape/data
10540 /// length mismatch or shape/stride arithmetic overflow.
10541 pub fn from_vec_col_major(
10542 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10543 data: Vec<T>,
10544 ) -> crate::Result<Self> {
10545 typed_tensor_from_vec_col_major(shape, data, "from_vec_col_major")
10546 }
10547
10548 /// Explicitly import row-major host values into column-major storage.
10549 ///
10550 /// Clones each input element once; no backend or scalar registration is used.
10551 ///
10552 /// # Examples
10553 /// ```
10554 /// use tenferro_tensor::{Rank, TypedTensor};
10555 /// let tensor = TypedTensor::<i32, Rank<2>>::from_vec_row_major(
10556 /// [2, 3], vec![1, 2, 3, 4, 5, 6],
10557 /// )?;
10558 /// assert_eq!(tensor.get(&[1, 0])?, &4);
10559 /// assert_eq!(tensor.get(&[0, 2])?, &3);
10560 /// # Ok::<(), tenferro_tensor::Error>(())
10561 /// ```
10562 /// # Errors
10563 /// Returns [`crate::Error::Validation`] for a rank, shape-length or stride overflow,
10564 /// or when the shape product disagrees with the input length.
10565 pub fn from_vec_row_major(
10566 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10567 data: Vec<T>,
10568 ) -> crate::Result<Self>
10569 where
10570 T: Clone,
10571 {
10572 let op = "from_vec_row_major";
10573 let (shape, reordered) = row_major_reorder(shape, data, op)?;
10574 typed_tensor_from_vec_col_major(shape, reordered, op)
10575 }
10576
10577 /// Consume this compact tensor and return the original host `Vec<T>`.
10578 ///
10579 /// # Examples
10580 ///
10581 /// ```
10582 /// use tenferro_tensor::TypedTensor;
10583 /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
10584 /// let data = tensor.into_host_vec().map_err(|failure| failure.into_parts().1)?;
10585 /// assert_eq!(data, vec![1, 2]);
10586 /// # Ok::<(), tenferro_tensor::Error>(())
10587 /// ```
10588 ///
10589 /// # Errors
10590 /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10591 /// storage is device-only, the managed root cannot export a host vector, or
10592 /// a group-backed descriptor is not compact column-major
10593 /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
10594 pub fn into_host_vec(self) -> std::result::Result<Vec<T>, ReinterpretError<Self>>
10595 where
10596 T: 'static,
10597 {
10598 let TypedTensor {
10599 shape,
10600 placement,
10601 layout,
10602 storage,
10603 } = self;
10604 match storage {
10605 DynamicStorage::Host(HostStorage { data }) => Ok(data.into_vec()),
10606 DynamicStorage::Group(GroupStorage { group }) => {
10607 let range = match group_logical_range(&group, "TypedTensor::into_host_vec") {
10608 Ok(range) => range,
10609 Err(error) => {
10610 return Err(ReinterpretError::new(
10611 TypedTensor {
10612 shape,
10613 placement,
10614 layout,
10615 storage: DynamicStorage::Group(GroupStorage { group }),
10616 },
10617 error,
10618 ))
10619 }
10620 };
10621 match group.into_host_vec::<T>() {
10622 Ok(mut data) => {
10623 // INVARIANT: the live descriptor's compact logical range
10624 // was validated inside its root span, so the exported
10625 // vector covers it.
10626 debug_assert!(range.end <= data.len(), "descriptor range exceeds its root");
10627 data.truncate(range.end);
10628 data.drain(..range.start);
10629 // The exported vector represents the logical extent only,
10630 // so it must not retain the root's capacity.
10631 data.shrink_to_fit();
10632 Ok(data)
10633 }
10634 Err((group, error)) => Err(ReinterpretError::new(
10635 TypedTensor {
10636 shape,
10637 placement,
10638 layout,
10639 storage: DynamicStorage::Group(GroupStorage {
10640 group: Box::new(group),
10641 }),
10642 },
10643 error,
10644 )),
10645 }
10646 }
10647 }
10648 }
10649
10650 /// Consume the original host vector along with its column-major shape.
10651 ///
10652 /// # Examples
10653 ///
10654 /// ```
10655 /// use tenferro_tensor::TypedTensor;
10656 /// let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2, 1], vec![1, 2])?;
10657 /// let (shape, data) = tensor.into_vec_col_major().map_err(|failure| failure.into_parts().1)?;
10658 /// assert_eq!(shape, vec![2, 1]);
10659 /// assert_eq!(data, vec![1, 2]);
10660 /// # Ok::<(), tenferro_tensor::Error>(())
10661 /// ```
10662 ///
10663 /// # Errors
10664 /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10665 /// storage is device-only, the managed root cannot export a host vector, or
10666 /// a group-backed descriptor is not compact column-major
10667 /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
10668 pub fn into_vec_col_major(
10669 self,
10670 ) -> std::result::Result<(Vec<usize>, Vec<T>), ReinterpretError<Self>>
10671 where
10672 T: 'static,
10673 {
10674 let shape = self.shape().to_vec();
10675 match self.into_host_vec() {
10676 Ok(data) => Ok((shape, data)),
10677 Err(failure) => Err(failure),
10678 }
10679 }
10680
10681 /// Borrow the plain host values of this tensor.
10682 ///
10683 /// A group-backed owner extracted from a larger root exposes only its
10684 /// logical, compact values; [`Self::as_view`] retains the whole backing
10685 /// root when a caller needs to inspect elements outside the extent.
10686 ///
10687 /// # Examples
10688 ///
10689 /// ```
10690 /// use tenferro_tensor::TypedTensor;
10691 /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
10692 /// assert_eq!(tensor.host_data()?, &[1.0, 2.0]);
10693 /// # Ok::<(), tenferro_tensor::Error>(())
10694 /// ```
10695 ///
10696 /// # Errors
10697 /// Returns [`crate::Error::RuntimeState`] for device-only storage and the
10698 /// non-compact-descriptor validation error for a strided owner.
10699 pub fn host_data(&self) -> crate::Result<&[T]> {
10700 match &self.storage {
10701 DynamicStorage::Host(HostStorage { data }) => Ok(data.as_slice()),
10702 DynamicStorage::Group(core) => {
10703 let data = core.group.host_slice::<T>()?;
10704 let range = group_logical_range(&core.group, "TypedTensor::host_data")?;
10705 data.get(range).ok_or_else(|| {
10706 crate::Error::validation(
10707 "TypedTensor::host_data",
10708 ValidationError::ViewOutOfBounds,
10709 )
10710 })
10711 }
10712 }
10713 }
10714
10715 /// Borrow the logical host values as a flat column-major slice without
10716 /// copying.
10717 ///
10718 /// This is the value view of [`Self::host_data`]: a root-preserving
10719 /// extraction exposes only its compact logical slice, never the root prefix
10720 /// and never elements outside its extent.
10721 ///
10722 /// # Examples
10723 /// ```
10724 /// use tenferro_tensor::TypedTensor;
10725 /// let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
10726 /// assert_eq!(tensor.as_slice()?, &["a", "b"]);
10727 /// # Ok::<(), tenferro_tensor::Error>(())
10728 /// ```
10729 /// # Errors
10730 /// Device-only storage returns [`crate::Error::RuntimeState`].
10731 pub fn as_slice(&self) -> crate::Result<&[T]> {
10732 self.host_data()
10733 }
10734
10735 /// Mutably borrow the plain host values of this tensor.
10736 ///
10737 /// The exclusive borrow covers exactly the logical, compact values of a
10738 /// root-preserving owner, so writes cannot reach elements outside its
10739 /// extent.
10740 ///
10741 /// # Examples
10742 ///
10743 /// ```
10744 /// use tenferro_tensor::TypedTensor;
10745 /// let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
10746 /// tensor.host_data_mut()?[0] = 5.0;
10747 /// assert_eq!(tensor.host_data()?, &[5.0, 2.0]);
10748 /// # Ok::<(), tenferro_tensor::Error>(())
10749 /// ```
10750 ///
10751 /// # Errors
10752 /// Returns [`crate::Error::RuntimeState`] for device-only storage and the
10753 /// non-compact-descriptor validation error for a strided owner.
10754 pub fn host_data_mut(&mut self) -> crate::Result<&mut [T]> {
10755 match &mut self.storage {
10756 DynamicStorage::Host(HostStorage { data }) => Ok(data.as_mut_slice()),
10757 DynamicStorage::Group(core) => {
10758 let range = group_logical_range(&core.group, "TypedTensor::host_data_mut")?;
10759 let data = core.group.host_slice_mut::<T>()?;
10760 data.get_mut(range).ok_or_else(|| {
10761 crate::Error::validation(
10762 "TypedTensor::host_data_mut",
10763 ValidationError::ViewOutOfBounds,
10764 )
10765 })
10766 }
10767 }
10768 }
10769
10770 /// Borrow an element by checked column-major multi-index.
10771 ///
10772 /// # Examples
10773 /// ```
10774 /// use tenferro_tensor::TypedTensor;
10775 /// let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
10776 /// assert_eq!(tensor.get(&[1])?, "b");
10777 /// # Ok::<(), tenferro_tensor::Error>(())
10778 /// ```
10779 /// # Errors
10780 /// Invalid rank, coordinates or offset return [`crate::Error::Validation`];
10781 /// device-only storage returns [`crate::Error::RuntimeState`].
10782 pub fn get(&self, indices: &[usize]) -> crate::Result<&T> {
10783 let offset = self.linear_offset(indices)?;
10784 self.host_data()?.get(offset).ok_or_else(|| {
10785 crate::Error::validation("TypedTensor::get", ValidationError::ViewOutOfBounds)
10786 })
10787 }
10788
10789 /// Exclusively borrow an element by checked column-major multi-index.
10790 ///
10791 /// # Examples
10792 /// ```
10793 /// use tenferro_tensor::TypedTensor;
10794 /// let mut tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
10795 /// *tensor.get_mut(&[0])? = "b".into();
10796 /// assert_eq!(tensor.get(&[0])?, "b");
10797 /// # Ok::<(), tenferro_tensor::Error>(())
10798 /// ```
10799 /// # Errors
10800 /// Invalid rank, coordinates or offset return [`crate::Error::Validation`];
10801 /// device-only storage returns [`crate::Error::RuntimeState`].
10802 pub fn get_mut(&mut self, indices: &[usize]) -> crate::Result<&mut T> {
10803 let offset = self.linear_offset(indices)?;
10804 self.host_data_mut()?.get_mut(offset).ok_or_else(|| {
10805 crate::Error::validation("TypedTensor::get_mut", ValidationError::ViewOutOfBounds)
10806 })
10807 }
10808
10809 /// Make an explicit independent host copy with the same shape and placement.
10810 ///
10811 /// The dynamic `TypedTensor` does not implement [`Clone`] (only the
10812 /// host-only representation does): the copy reads host data, rejects
10813 /// device-only storage, and creates a new owner, so it is fallible. See
10814 /// [`Tensor::duplicate`] for the sharing alternatives.
10815 ///
10816 /// # Examples
10817 /// ```
10818 /// use tenferro_tensor::TypedTensor;
10819 /// let tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
10820 /// assert_eq!(tensor.duplicate()?.get(&[0])?, "a");
10821 /// # Ok::<(), tenferro_tensor::Error>(())
10822 /// ```
10823 /// # Errors
10824 /// Device-only storage returns [`crate::Error::RuntimeState`]; invalid
10825 /// host metadata returns [`crate::Error::Validation`].
10826 pub fn duplicate(&self) -> crate::Result<Self>
10827 where
10828 T: Clone,
10829 {
10830 let mut copy = Self::from_vec_col_major(
10831 R::shape_from_vec(shape_vec(self.shape()))
10832 .map_err(|err| tensor_layout_error("TypedTensor::duplicate", err))?,
10833 self.host_data()?.to_vec(),
10834 )?;
10835 copy.set_placement(self.placement().clone())?;
10836 Ok(copy)
10837 }
10838
10839 /// Create a tensor from an existing buffer and compact column-major layout.
10840 ///
10841 /// This preserves the owned tensor invariant that layout metadata is
10842 /// compact column-major, including for backend-owned buffers.
10843 ///
10844 /// # Examples
10845 ///
10846 /// ```
10847 /// use tenferro_tensor::{StorageBuffer, Placement, TypedTensor};
10848 ///
10849 /// let tensor = TypedTensor::<f64>::from_buffer_col_major(
10850 /// vec![2],
10851 /// StorageBuffer::Host(vec![1.0, 2.0]),
10852 /// Placement {
10853 /// memory_kind: tenferro_tensor::MemoryKind::UnpinnedHost,
10854 /// device: None,
10855 /// cpu_affinity: None,
10856 /// },
10857 /// )
10858 /// .unwrap();
10859 /// assert_eq!(tensor.shape(), &[2]);
10860 /// ```
10861 /// # Errors
10862 ///
10863 /// Returns [`crate::Error::Validation`] with
10864 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
10865 /// the shape product differs from the buffer length,
10866 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape or
10867 /// stride arithmetic overflows, or
10868 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when a supplied
10869 /// rank-specific shape cannot be represented.
10870 pub fn from_buffer_col_major(
10871 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10872 buffer: StorageBuffer<T>,
10873 placement: Placement,
10874 ) -> crate::Result<Self>
10875 where
10876 T: TensorScalar + Send + Sync + 'static,
10877 {
10878 typed_tensor_from_buffer_col_major(shape, buffer, placement)
10879 }
10880
10881 /// Consume a scalar-independent provider root into one compact tensor.
10882 #[doc(hidden)]
10883 pub fn from_backend_allocation(
10884 shape: impl tenferro_tensor_core::IntoRankShape<R>,
10885 allocation: Box<dyn crate::BackendAllocation>,
10886 placement: Placement,
10887 ) -> crate::Result<Self>
10888 where
10889 T: TensorScalar + Send + Sync + 'static,
10890 {
10891 typed_tensor_from_backend_allocation(shape, allocation, placement)
10892 }
10893
10894 /// Convert this tensor into static rank metadata after validating its rank.
10895 ///
10896 /// The buffer and placement are preserved. This method changes only the
10897 /// compile-time rank marker on the owned compact column-major tensor.
10898 ///
10899 /// # Examples
10900 ///
10901 /// ```
10902 /// use tenferro_tensor::{Rank, TypedTensor};
10903 ///
10904 /// let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![1.0; 6]).unwrap();
10905 /// let Ok(ranked) = tensor.try_into_rank::<2>() else {
10906 /// panic!("a rank-2 tensor converts to two axes")
10907 /// };
10908 /// assert_eq!(ranked.shape(), &[2, 3]);
10909 /// # Ok::<(), tenferro_tensor::Error>(())
10910 /// ```
10911 /// # Errors
10912 ///
10913 /// Returns [`ReinterpretError`] carrying the unchanged tensor when the
10914 /// typed rank does not match the existing shape, with
10915 /// [`crate::Error::Validation`] and
10916 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] as the cause,
10917 /// or when the compact rank layout overflows.
10918 pub fn try_into_rank<const N: usize>(
10919 self,
10920 ) -> std::result::Result<TypedTensor<T, Rank<N>>, ReinterpretError<Self>> {
10921 let op = "TypedTensor::try_into_rank";
10922 let actual = self.shape().len();
10923 let shape: [usize; N] = match self.shape().try_into() {
10924 Ok(shape) => shape,
10925 Err(_) => {
10926 return Err(ReinterpretError::new(
10927 self,
10928 tensor_layout_error(
10929 op,
10930 ValidationError::RankMismatch {
10931 expected: N,
10932 actual,
10933 },
10934 ),
10935 ))
10936 }
10937 };
10938 let layout = match TensorLayout::<Rank<N>>::compact(shape) {
10939 Ok(layout) => layout,
10940 Err(error) => return Err(ReinterpretError::new(self, tensor_layout_error(op, error))),
10941 };
10942 let TypedTensor {
10943 placement, storage, ..
10944 } = self;
10945 let storage = match storage {
10946 DynamicStorage::Host(host) => DynamicStorage::Host(host),
10947 DynamicStorage::Group(GroupStorage { group }) => DynamicStorage::Group(GroupStorage {
10948 group: Box::new(OwnedTensorGroup {
10949 group: group.group,
10950 slot: group.slot,
10951 allocation_index: group.allocation_index,
10952 host_ptr: group.host_ptr,
10953 host_byte_len: group.host_byte_len,
10954 _rank: PhantomData,
10955 }),
10956 }),
10957 };
10958 Ok(TypedTensor {
10959 shape,
10960 placement,
10961 layout: stride_vec(layout.strides()),
10962 storage,
10963 })
10964 }
10965
10966 /// Return the storage backing this tensor.
10967 ///
10968 /// This is an explicit storage-inspection API for backend glue and tests.
10969 /// Host value inspection should prefer [`TypedTensor::host_data`] when the
10970 /// caller requires host storage.
10971 ///
10972 /// # Panics
10973 ///
10974 /// Panics only if the typed descriptor and its single group owner are
10975 /// internally inconsistent.
10976 ///
10977 /// # Examples
10978 ///
10979 /// ```
10980 /// use tenferro_tensor::{StorageBuffer, TypedTensor};
10981 ///
10982 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
10983 /// assert!(matches!(t.buffer(), StorageBuffer::Host(_)));
10984 /// ```
10985 pub fn buffer(&self) -> &StorageBuffer<T>
10986 where
10987 T: 'static,
10988 {
10989 match &self.storage {
10990 DynamicStorage::Host(HostStorage { data }) => &data.buffer,
10991 DynamicStorage::Group(core) => core
10992 .group
10993 .host_buffer::<T>()
10994 .or_else(|| core.group.backend_buffer::<T>())
10995 .unwrap_or_else(|| unreachable!("typed tensor group storage mismatch")),
10996 }
10997 }
10998
10999 /// Return the provider family for this tensor when backend-owned.
11000 #[doc(hidden)]
11001 pub fn backend_family(&self) -> Option<&'static str>
11002 where
11003 T: TensorScalar + 'static,
11004 {
11005 self.as_view().backend_family()
11006 }
11007
11008 /// Return the opaque backend buffer for backend-owned tensors.
11009 #[doc(hidden)]
11010 pub fn backend_buffer(&self) -> Option<&dyn BackendStorage<T>>
11011 where
11012 T: 'static,
11013 {
11014 match &self.storage {
11015 DynamicStorage::Host(..) => None,
11016 DynamicStorage::Group(core) => match core.group.backend_buffer::<T>() {
11017 Some(StorageBuffer::Backend(buffer)) => Some(buffer.as_ref()),
11018 Some(StorageBuffer::Host(_)) | None => None,
11019 },
11020 }
11021 }
11022
11023 /// Return the mutable backend buffer for an exclusive owner borrow.
11024 #[doc(hidden)]
11025 pub fn backend_buffer_mut(&mut self) -> Option<&mut dyn BackendStorage<T>>
11026 where
11027 T: 'static,
11028 {
11029 let DynamicStorage::Group(core) = &mut self.storage else {
11030 return None;
11031 };
11032 match core.group.backend_buffer_mut::<T>()? {
11033 StorageBuffer::Host(_) => None,
11034 StorageBuffer::Backend(buffer) => Some(buffer.as_mut()),
11035 }
11036 }
11037
11038 /// Prepare this backend tensor for one provider-native read binding.
11039 #[doc(hidden)]
11040 pub fn prepare_device_read(
11041 &self,
11042 op: &'static str,
11043 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
11044 where
11045 T: TensorScalar + 'static,
11046 {
11047 let DynamicStorage::Group(core) = &self.storage else {
11048 return Err(crate::Error::runtime_state_source(
11049 op,
11050 crate::AccessError::Unsupported { backend: "host" },
11051 ));
11052 };
11053 let layout = self.physical_layout();
11054 core.group
11055 .prepare_device_read_for_layout::<T>(&layout)
11056 .map_err(|error| crate::Error::runtime_state_source(op, error))
11057 }
11058
11059 /// Prepare this backend tensor for one provider-native write binding.
11060 #[doc(hidden)]
11061 pub fn prepare_device_write(
11062 &mut self,
11063 op: &'static str,
11064 ) -> crate::Result<Box<dyn PreparedDeviceAccess + '_>>
11065 where
11066 T: TensorScalar + 'static,
11067 {
11068 let layout = self.physical_layout();
11069 let DynamicStorage::Group(core) = &mut self.storage else {
11070 return Err(crate::Error::runtime_state_source(
11071 op,
11072 crate::AccessError::Unsupported { backend: "host" },
11073 ));
11074 };
11075 core.group
11076 .prepare_device_write_for_layout::<T>(&layout)
11077 .map_err(|error| crate::Error::runtime_state_source(op, error))
11078 }
11079
11080 /// Element count of the tensor's backing storage.
11081 ///
11082 /// A root-preserving owner reports its whole backing root, not just the
11083 /// logical view extent, so layout validation for views and reshapes bounds
11084 /// against the real allocation.
11085 pub(crate) fn buffer_len(&self) -> usize
11086 where
11087 T: 'static,
11088 {
11089 match &self.storage {
11090 DynamicStorage::Host(HostStorage { data }) => data.as_slice().len(),
11091 DynamicStorage::Group(core) => core
11092 .group
11093 .group
11094 .descriptor_backing_len(core.group.slot)
11095 .unwrap_or_else(|| unreachable!("typed tensor group descriptor mismatch")),
11096 }
11097 }
11098
11099 /// Return the shared-allocation domain carried by the backend buffer.
11100 ///
11101 /// # Examples
11102 ///
11103 /// ```rust
11104 /// use tenferro_tensor::TypedTensor;
11105 ///
11106 /// let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
11107 /// assert_eq!(tensor.allocation_domain(), None);
11108 /// # Ok::<(), tenferro_tensor::Error>(())
11109 /// ```
11110 pub fn allocation_domain(&self) -> Option<AllocationDomainId>
11111 where
11112 T: 'static,
11113 {
11114 match &self.storage {
11115 DynamicStorage::Host(..) => None,
11116 DynamicStorage::Group(core) => core
11117 .group
11118 .group
11119 .backend_identity(core.group.slot)
11120 .map(|(domain, _)| domain),
11121 }
11122 }
11123
11124 /// Return the stable physical backend allocation identity.
11125 ///
11126 /// # Examples
11127 ///
11128 /// ```rust
11129 /// use tenferro_tensor::TypedTensor;
11130 ///
11131 /// let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
11132 /// assert_eq!(tensor.allocation_id(), None);
11133 /// # Ok::<(), tenferro_tensor::Error>(())
11134 /// ```
11135 pub fn allocation_id(&self) -> Option<AllocationId>
11136 where
11137 T: 'static,
11138 {
11139 match &self.storage {
11140 DynamicStorage::Host(..) => None,
11141 DynamicStorage::Group(core) => core
11142 .group
11143 .group
11144 .backend_identity(core.group.slot)
11145 .map(|(_, allocation)| allocation),
11146 }
11147 }
11148
11149 /// Borrow this tensor as a typed view preserving rank and layout metadata.
11150 ///
11151 /// The view carries the descriptor's physical layout, so a root-preserving
11152 /// extraction exposes its full backing allocation with the logical slice at
11153 /// the descriptor offset.
11154 ///
11155 /// # Panics
11156 ///
11157 /// Panics only if the typed descriptor and its single group owner are
11158 /// internally inconsistent.
11159 ///
11160 /// # Examples
11161 ///
11162 /// ```rust
11163 /// use tenferro_tensor::{Rank, TypedTensor};
11164 ///
11165 /// let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
11166 /// let view = tensor.as_view();
11167 /// assert_eq!(view.strides(), &[1, 2]);
11168 /// ```
11169 pub fn as_view(&self) -> TypedTensorView<'_, T, R>
11170 where
11171 T: 'static,
11172 {
11173 let layout = self.physical_layout();
11174 let placement = self.placement.clone();
11175 match &self.storage {
11176 DynamicStorage::Host(HostStorage { data }) => TypedTensorView {
11177 buffer: TensorStorageRef::Host(data.as_slice()),
11178 root: None,
11179 layout,
11180 placement,
11181 _representation: std::marker::PhantomData,
11182 },
11183 DynamicStorage::Group(core) => {
11184 // Managed owners are constructed only with their matching preset T.
11185 let root = core
11186 .group
11187 .group
11188 .view_raw::<T, R>(core.group.slot)
11189 .unwrap_or_else(|error| {
11190 unreachable!("typed tensor group descriptor mismatch: {error}")
11191 });
11192 let buffer = if let Some(allocation) = root.backend_allocation() {
11193 TensorStorageRef::Root(allocation)
11194 } else {
11195 TensorStorageRef::Host(core.group.host_slice::<T>().unwrap_or_default())
11196 };
11197 TypedTensorView {
11198 buffer,
11199 root: Some(root),
11200 layout,
11201 placement,
11202 _representation: std::marker::PhantomData,
11203 }
11204 }
11205 }
11206 }
11207
11208 /// Mutably borrow this tensor as a typed view preserving rank and layout metadata.
11209 ///
11210 /// # Panics
11211 ///
11212 /// Panics only if the typed descriptor and its single group owner are
11213 /// internally inconsistent.
11214 ///
11215 /// # Examples
11216 ///
11217 /// ```rust
11218 /// use tenferro_tensor::TypedTensor;
11219 ///
11220 /// let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![1]).unwrap();
11221 /// *tensor.as_view_mut().get_mut(&[0]).unwrap() = 2;
11222 /// assert_eq!(tensor.as_slice().unwrap(), &[2]);
11223 /// ```
11224 pub fn as_view_mut(&mut self) -> TypedTensorViewMut<'_, T, R>
11225 where
11226 T: TensorScalar + 'static,
11227 {
11228 let layout = self.physical_layout();
11229 let placement = self.placement.clone();
11230 match &mut self.storage {
11231 DynamicStorage::Host(HostStorage { data }) => TypedTensorViewMut {
11232 buffer: TensorStorageRefMut::Host(data.as_mut_slice()),
11233 root: None,
11234 layout,
11235 placement,
11236 _representation: std::marker::PhantomData,
11237 },
11238 DynamicStorage::Group(core) => {
11239 let mut root = core.group.view_mut::<T>().unwrap_or_else(|error| {
11240 unreachable!("typed tensor group descriptor mismatch: {error}")
11241 });
11242 let buffer = if let Some(StorageBuffer::Backend(buffer)) = root.backend_buffer_mut()
11243 {
11244 TensorStorageRefMut::Backend(buffer.as_mut())
11245 } else {
11246 TensorStorageRefMut::Host(root.host_slice_mut().unwrap_or_else(|error| {
11247 unreachable!("typed tensor group descriptor is not host-backed: {error}")
11248 }))
11249 };
11250 TypedTensorViewMut {
11251 buffer,
11252 root: Some(root),
11253 layout,
11254 placement,
11255 _representation: std::marker::PhantomData,
11256 }
11257 }
11258 }
11259 }
11260
11261 /// Borrow a read-only strided region view over this tensor's backend
11262 /// (device) buffer from explicit layout metadata.
11263 ///
11264 /// This is a metadata-only view: no data is copied or transferred. The
11265 /// layout's reachable element span is validated against the backend
11266 /// buffer's physical length. Host-backed tensors are rejected with an
11267 /// explicit backend error; host regions are expressed with
11268 /// [`TypedTensorView::from_slice`] over host storage instead.
11269 ///
11270 /// # Examples
11271 ///
11272 /// ```rust
11273 /// use tenferro_tensor::TypedTensor;
11274 ///
11275 /// // Host tensors are rejected: this constructor is for backend buffers.
11276 /// let host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
11277 /// let err = host.backend_region_view(vec![2, 2], vec![1, 2], 0).unwrap_err();
11278 /// assert!(err.to_string().contains("backend"));
11279 /// ```
11280 /// # Errors
11281 ///
11282 /// Returns [`crate::Error::RuntimeState`] when this tensor is host-backed;
11283 /// backend region views require a backend buffer. It returns
11284 /// [`crate::Error::Validation`] with
11285 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for incompatible
11286 /// shape/stride ranks, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
11287 /// when the region exceeds the backend buffer, or
11288 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
11289 /// arithmetic overflow.
11290 pub fn backend_region_view(
11291 &self,
11292 shape: Vec<usize>,
11293 strides: Vec<isize>,
11294 offset: isize,
11295 ) -> crate::Result<TypedTensorView<'_, T, DynRank>>
11296 where
11297 T: TensorScalar + 'static,
11298 {
11299 let op = "TypedTensor::backend_region_view";
11300 let DynamicStorage::Group(core) = &self.storage else {
11301 return Err(crate::Error::runtime_state(op, "expected a backend (device) allocation; host tensors use TypedTensorView::from_slice over host storage"));
11302 };
11303 let root = core.group.view_dyn::<T>()?;
11304 let Some(allocation) = root.backend_allocation() else {
11305 return Err(crate::Error::runtime_state(
11306 op,
11307 "expected a backend (device) allocation; host tensors use \
11308 TypedTensorView::from_slice over host storage",
11309 ));
11310 };
11311 let element_len = allocation
11312 .root_extent()
11313 .byte_len()
11314 .checked_div(size_of::<T>())
11315 .ok_or_else(|| crate::Error::validation(op, ValidationError::IntegerOverflow))?;
11316 let layout =
11317 TensorLayout::from_parts(shape_vec(&shape), stride_vec(&strides), offset, element_len)
11318 .map_err(|err| tensor_layout_error(op, err))?;
11319 Ok(TypedTensorView {
11320 buffer: TensorStorageRef::Root(allocation),
11321 root: Some(root),
11322 layout,
11323 placement: self.placement.clone(),
11324 _representation: std::marker::PhantomData,
11325 })
11326 }
11327
11328 /// Borrow a mutable strided region view over this tensor's backend
11329 /// (device) buffer from explicit layout metadata.
11330 ///
11331 /// This is the mutable counterpart of
11332 /// [`TypedTensor::backend_region_view`]. The layout's reachable element
11333 /// span is validated against the backend buffer's physical length, and
11334 /// layouts whose logical elements alias the same physical element are
11335 /// rejected. Host-backed tensors are rejected with an explicit backend
11336 /// error; mutable host regions must go through
11337 /// [`TypedTensorViewMut::try_multi_slice_mut`] or host constructors.
11338 ///
11339 /// The returned view borrows the tensor's backend owner exclusively for its
11340 /// lifetime. This keeps write authority tied to the owner; a second mutable
11341 /// region view must be created only after the first borrow ends.
11342 ///
11343 /// # Examples
11344 ///
11345 /// ```rust
11346 /// use tenferro_tensor::TypedTensor;
11347 ///
11348 /// // Host tensors are rejected: this constructor is for backend buffers.
11349 /// let mut host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
11350 /// let err = host.backend_region_view_mut(vec![2, 2], vec![1, 2], 0).unwrap_err();
11351 /// assert!(err.to_string().contains("backend"));
11352 /// ```
11353 /// # Errors
11354 ///
11355 /// Returns [`crate::Error::RuntimeState`] when this tensor is host-backed;
11356 /// mutable backend region views require a backend buffer. It returns
11357 /// [`crate::Error::Validation`] with
11358 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] for incompatible
11359 /// shape/stride ranks, [`tenferro_tensor_core::ValidationError::ViewOutOfBounds`]
11360 /// when the region exceeds the backend buffer,
11361 /// [`tenferro_tensor_core::ValidationError::OverlappingMutableLayout`] when
11362 /// logical elements alias, or
11363 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] for layout
11364 /// arithmetic overflow.
11365 pub fn backend_region_view_mut(
11366 &mut self,
11367 shape: Vec<usize>,
11368 strides: Vec<isize>,
11369 offset: isize,
11370 ) -> crate::Result<TypedTensorViewMut<'_, T, DynRank>>
11371 where
11372 T: TensorScalar + 'static,
11373 {
11374 let op = "TypedTensor::backend_region_view_mut";
11375 let placement = self.placement.clone();
11376 let DynamicStorage::Group(core) = &mut self.storage else {
11377 return Err(crate::Error::runtime_state(op, "expected a backend (device) buffer; mutable host regions use TypedTensorViewMut host constructors or try_multi_slice_mut"));
11378 };
11379 let mut root = core.group.view_mut_dyn::<T>()?;
11380 let Some(StorageBuffer::Backend(buffer)) = root.backend_buffer_mut() else {
11381 return Err(crate::Error::runtime_state(
11382 op,
11383 "expected a backend (device) buffer; mutable host regions use \
11384 TypedTensorViewMut host constructors or try_multi_slice_mut",
11385 ));
11386 };
11387 let layout = TensorLayout::from_parts(
11388 shape_vec(&shape),
11389 stride_vec(&strides),
11390 offset,
11391 buffer.len(),
11392 )
11393 .map_err(|err| tensor_layout_error(op, err))?;
11394 layout
11395 .validate_mutable_no_overlap()
11396 .map_err(|err| tensor_layout_error(op, err))?;
11397 Ok(TypedTensorViewMut {
11398 buffer: TensorStorageRefMut::Backend(buffer.as_mut()),
11399 root: Some(root),
11400 layout,
11401 placement,
11402 _representation: std::marker::PhantomData,
11403 })
11404 }
11405
11406 /// Consume this tensor and return its logical host storage, layout, and
11407 /// placement.
11408 ///
11409 /// A root-preserving owner exports only its compact logical values, exactly
11410 /// like [`TypedTensor::into_host_vec`].
11411 ///
11412 /// # Examples
11413 ///
11414 /// ```
11415 /// use tenferro_tensor::{StorageBuffer, TypedTensor};
11416 ///
11417 /// let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
11418 /// let Ok((buffer, layout, placement)) = t.into_parts() else {
11419 /// panic!("a plain host owner extracts")
11420 /// };
11421 /// assert!(matches!(buffer, StorageBuffer::Host(_)));
11422 /// assert_eq!(layout.shape(), &[2]);
11423 /// assert!(placement.device.is_none());
11424 /// # Ok::<(), tenferro_tensor::Error>(())
11425 /// ```
11426 ///
11427 /// # Errors
11428 ///
11429 /// Returns [`ReinterpretError`] carrying the unchanged tensor when it uses
11430 /// backend storage (download it before extracting host storage) or when a
11431 /// group-backed descriptor is not compact column-major
11432 /// ([`tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice`]).
11433 pub fn into_parts(
11434 self,
11435 ) -> std::result::Result<(StorageBuffer<T>, TensorLayout<R>, Placement), ReinterpretError<Self>>
11436 where
11437 T: TensorScalar,
11438 {
11439 let placement = self.placement().clone();
11440 let layout = TensorLayout::<R>::compact(
11441 R::shape_from_vec(shape_vec(self.shape()))
11442 .unwrap_or_else(|err| unreachable!("validated owned shape: {err:?}")),
11443 )
11444 .unwrap_or_else(|err| unreachable!("validated owned shape: {err}"));
11445 // The export contract is identical to `into_host_vec`; reuse it rather
11446 // than repeating the descriptor rebase and its failure recovery.
11447 match self.into_host_vec() {
11448 Ok(data) => Ok((StorageBuffer::Host(data), layout, placement)),
11449 Err(error) => Err(error),
11450 }
11451 }
11452}
11453
11454impl<T: TensorScalar, R: TensorRank> TypedTensor<T, R> {
11455 fn into_managed(self) -> Self {
11456 let TypedTensor {
11457 shape,
11458 placement,
11459 layout,
11460 storage,
11461 } = self;
11462 match storage {
11463 DynamicStorage::Host(HostStorage { data }) => {
11464 let group = promote_host_group::<T, R>(shape.clone(), data)
11465 .unwrap_or_else(|err| unreachable!("a validated host owner promotes: {err}"));
11466 Self {
11467 shape,
11468 placement,
11469 layout,
11470 storage: DynamicStorage::Group(GroupStorage {
11471 group: Box::new(group),
11472 }),
11473 }
11474 }
11475 DynamicStorage::Group(core) => Self {
11476 shape,
11477 placement,
11478 layout,
11479 storage: DynamicStorage::Group(core),
11480 },
11481 }
11482 }
11483
11484 fn into_group_parts(self) -> (AllocationGroup, DescriptorSlot) {
11485 let TypedTensor {
11486 placement, storage, ..
11487 } = self.into_managed();
11488 let DynamicStorage::Group(GroupStorage { group }) = storage else {
11489 unreachable!("explicit group promotion produces managed storage")
11490 };
11491 let (mut group, slot) = group.into_parts();
11492 group.publish_live_descriptor_placement(slot, placement);
11493 (group, slot)
11494 }
11495
11496 /// Construct a backend-pooled host tensor with weak final-owner reclamation.
11497 /// Explicit Vec extraction disarms reclamation; aliases and retained groups
11498 /// keep the original root alive. The recycler must not acquire session locks.
11499 ///
11500 /// # Errors
11501 /// Returns validation errors for invalid shape/length and runtime-state errors
11502 /// if the freshly created host root cannot attach its recycler.
11503 #[doc(hidden)]
11504 pub fn from_vec_col_major_with_recycler(
11505 shape: impl tenferro_tensor_core::IntoRankShape<R>,
11506 data: Vec<T>,
11507 recycler: std::sync::Weak<dyn crate::HostBufferRecycler<T>>,
11508 ) -> crate::Result<Self> {
11509 let mut tensor = Self::from_vec_col_major(shape, data)?;
11510 if let DynamicStorage::Host(HostStorage { data }) = &mut tensor.storage {
11511 data.recycler = Some(recycler);
11512 }
11513 Ok(tensor)
11514 }
11515
11516 /// Borrow compact host-visible storage through one synchronization guard.
11517 #[doc(hidden)]
11518 pub fn with_host_read<U>(&self, f: impl FnOnce(&[T]) -> U) -> crate::Result<U>
11519 where
11520 T: TensorScalar + 'static,
11521 {
11522 self.as_view().with_host_read(f)
11523 }
11524
11525 /// Borrow compact host-visible storage through one exclusive write guard.
11526 #[doc(hidden)]
11527 pub fn with_host_write<U>(&mut self, f: impl FnOnce(&mut [T]) -> U) -> crate::Result<U>
11528 where
11529 T: TensorScalar + 'static,
11530 {
11531 match &mut self.storage {
11532 DynamicStorage::Host(HostStorage { data }) => Ok(f(data.as_mut_slice())),
11533 DynamicStorage::Group(core) => {
11534 let slot = core.group.slot;
11535 let mut view = core
11536 .group
11537 .group
11538 .view_mut::<T, R>(slot)
11539 .map_err(|error| group_error("TypedTensor::with_host_write", error))?;
11540 let mut prepared = view.prepare_host_write().map_err(|error| {
11541 crate::Error::runtime_state("TypedTensor::with_host_write", error.to_string())
11542 })?;
11543 let slice = prepared.as_slice_mut().ok_or_else(|| {
11544 crate::Error::unsupported(
11545 "TypedTensor::with_host_write",
11546 "host guard access requires a compact descriptor",
11547 )
11548 })?;
11549 Ok(f(slice))
11550 }
11551 }
11552 }
11553
11554 /// Whole backing host buffer, including bytes outside a root-preserving
11555 /// extraction's logical extent (#2023).
11556 ///
11557 /// A mutable reinterpretation rebases the descriptor over the whole root,
11558 /// so it must borrow that root rather than the exported logical slice.
11559 fn backing_host_slice_mut(&mut self) -> crate::Result<&mut [T]> {
11560 match &mut self.storage {
11561 DynamicStorage::Host(HostStorage { data }) => Ok(data.as_mut_slice()),
11562 DynamicStorage::Group(core) => core.group.host_slice_mut::<T>(),
11563 }
11564 }
11565
11566 fn group_host_slice(&self) -> &[T] {
11567 let DynamicStorage::Group(core) = &self.storage else {
11568 return &[];
11569 };
11570 core.group
11571 .view::<T>()
11572 .ok()
11573 .and_then(|view| view.host_slice().ok())
11574 .unwrap_or_default()
11575 }
11576}
11577
11578/// Layout builder used by an owning representation reinterpretation.
11579type ReinterpretLayoutFn =
11580 fn(&[usize], &[isize], isize, usize, &'static str) -> crate::Result<TensorLayout<DynRank>>;
11581
11582fn reinterpret_owned<S: TensorScalar, U: TensorScalar, R: TensorRank>(
11583 owner: TypedTensor<S, R>,
11584 from: DType,
11585 to: DType,
11586 make_layout: ReinterpretLayoutFn,
11587 op: &'static str,
11588) -> Result<TypedTensor<U>, ReinterpretError<TypedTensor<S, R>>> {
11589 if let Err(error) = validate_representation_pair(op, from, to) {
11590 return Err(ReinterpretError::new(owner, error));
11591 }
11592 if matches!(to, DType::C32 | DType::C64) && !owner.buffer_len().is_multiple_of(2) {
11593 return Err(ReinterpretError::new(
11594 owner,
11595 crate::Error::invalid_argument(
11596 op,
11597 "buffer",
11598 "the owned real buffer must contain an even number of elements",
11599 ),
11600 ));
11601 }
11602 let source_layout = owner.physical_layout();
11603 let target_layout = match make_layout(
11604 source_layout.shape(),
11605 source_layout.strides(),
11606 source_layout.offset(),
11607 owner.buffer_len(),
11608 op,
11609 ) {
11610 Ok(layout) => layout,
11611 Err(error) => return Err(ReinterpretError::new(owner, error)),
11612 };
11613 // Only an explicit owning representation conversion promotes a plain owner;
11614 // borrowed session dispatch never passes through a group.
11615 let TypedTensor {
11616 shape,
11617 placement,
11618 layout,
11619 storage,
11620 } = owner.into_managed();
11621 let DynamicStorage::Group(GroupStorage { group }) = storage else {
11622 unreachable!("explicit group promotion produces managed storage")
11623 };
11624 match group.reinterpret::<S, U>(
11625 target_layout.shape().to_vec(),
11626 target_layout.strides().to_vec(),
11627 target_layout.offset(),
11628 ) {
11629 Ok(group) => Ok(TypedTensor {
11630 shape: shape_vec(target_layout.shape()),
11631 placement,
11632 layout: stride_vec(target_layout.strides()),
11633 storage: DynamicStorage::Group(GroupStorage {
11634 group: Box::new(group),
11635 }),
11636 }),
11637 Err((group, error)) => Err(ReinterpretError::new(
11638 TypedTensor {
11639 shape,
11640 placement,
11641 layout,
11642 storage: DynamicStorage::Group(GroupStorage {
11643 group: Box::new(group),
11644 }),
11645 },
11646 error,
11647 )),
11648 }
11649}
11650
11651impl<R: TensorRank> TypedTensor<Complex32, R> {
11652 /// Borrow this tensor as an interleaved `f32` view without copying.
11653 ///
11654 /// # Errors
11655 ///
11656 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11657 /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11658 /// invalid tensor layout.
11659 pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'_, f32, DynRank>> {
11660 self.as_view().as_real_view()
11661 }
11662
11663 /// Borrow this tensor mutably as an interleaved `f32` view without copying.
11664 ///
11665 /// # Errors
11666 ///
11667 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11668 /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11669 /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11670 /// invalid representation metadata.
11671 pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f32, DynRank>> {
11672 let op = "TypedTensor::as_real_view_mut";
11673 validate_representation_pair(op, DType::C32, DType::F32)?;
11674 let source_layout = self.physical_layout();
11675 let layout = reinterpret_complex_to_real_layout(
11676 self.shape(),
11677 source_layout.strides(),
11678 source_layout.offset(),
11679 self.buffer_len(),
11680 op,
11681 )?;
11682 layout
11683 .validate_mutable_no_overlap()
11684 .map_err(|err| tensor_layout_error(op, err))?;
11685 if self.backend_buffer().is_some() {
11686 return Err(crate::Error::unsupported(
11687 op,
11688 "backend representation reinterpretation is enabled by the provider phases",
11689 ));
11690 }
11691 let placement = self.placement().clone();
11692 let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex32, f32>(
11693 self.backing_host_slice_mut()?,
11694 op,
11695 )?);
11696 Ok(TypedTensorViewMut {
11697 buffer,
11698 root: None,
11699 layout,
11700 placement,
11701 _representation: std::marker::PhantomData,
11702 })
11703 }
11704
11705 /// Consume this tensor and reinterpret its owner as `f32` without copying.
11706 ///
11707 /// A failed operation returns the unchanged owner through
11708 /// [`ReinterpretError::into_owner`].
11709 ///
11710 /// # Errors
11711 ///
11712 /// Returns [`ReinterpretError::error`] containing
11713 /// [`ValidationError::InvalidArgument`] or
11714 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11715 /// owner.
11716 pub fn into_real(self) -> Result<TypedTensor<f32, DynRank>, ReinterpretError<Self>> {
11717 reinterpret_owned(
11718 self,
11719 DType::C32,
11720 DType::F32,
11721 reinterpret_complex_to_real_layout,
11722 "TypedTensor::into_real",
11723 )
11724 }
11725}
11726
11727impl<R: TensorRank> TypedTensor<Complex64, R> {
11728 /// Borrow this tensor as an interleaved `f64` view without copying.
11729 ///
11730 /// # Errors
11731 ///
11732 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11733 /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11734 /// invalid tensor layout.
11735 pub fn as_real_view(&self) -> crate::Result<TypedTensorView<'_, f64, DynRank>> {
11736 self.as_view().as_real_view()
11737 }
11738
11739 /// Borrow this tensor mutably as an interleaved `f64` view without copying.
11740 ///
11741 /// # Errors
11742 ///
11743 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11744 /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11745 /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11746 /// invalid representation metadata.
11747 pub fn as_real_view_mut(&mut self) -> crate::Result<TypedTensorViewMut<'_, f64, DynRank>> {
11748 let op = "TypedTensor::as_real_view_mut";
11749 validate_representation_pair(op, DType::C64, DType::F64)?;
11750 let source_layout = self.physical_layout();
11751 let layout = reinterpret_complex_to_real_layout(
11752 self.shape(),
11753 source_layout.strides(),
11754 source_layout.offset(),
11755 self.buffer_len(),
11756 op,
11757 )?;
11758 layout
11759 .validate_mutable_no_overlap()
11760 .map_err(|err| tensor_layout_error(op, err))?;
11761 if self.backend_buffer().is_some() {
11762 return Err(crate::Error::unsupported(
11763 op,
11764 "backend representation reinterpretation is enabled by the provider phases",
11765 ));
11766 }
11767 let placement = self.placement().clone();
11768 let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<Complex64, f64>(
11769 self.backing_host_slice_mut()?,
11770 op,
11771 )?);
11772 Ok(TypedTensorViewMut {
11773 buffer,
11774 root: None,
11775 layout,
11776 placement,
11777 _representation: std::marker::PhantomData,
11778 })
11779 }
11780
11781 /// Consume this tensor and reinterpret its owner as `f64` without copying.
11782 ///
11783 /// A failed operation returns the unchanged owner through
11784 /// [`ReinterpretError::into_owner`].
11785 ///
11786 /// # Errors
11787 ///
11788 /// Returns [`ReinterpretError::error`] containing
11789 /// [`ValidationError::InvalidArgument`] or
11790 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11791 /// owner.
11792 pub fn into_real(self) -> Result<TypedTensor<f64, DynRank>, ReinterpretError<Self>> {
11793 reinterpret_owned(
11794 self,
11795 DType::C64,
11796 DType::F64,
11797 reinterpret_complex_to_real_layout,
11798 "TypedTensor::into_real",
11799 )
11800 }
11801}
11802
11803impl<R: TensorRank> TypedTensor<f32, R> {
11804 /// Borrow this tensor as a complex view without copying.
11805 ///
11806 /// # Errors
11807 ///
11808 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11809 /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11810 /// invalid tensor layout.
11811 pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'_, Complex32, DynRank>> {
11812 self.as_view().as_complex_view()
11813 }
11814
11815 /// Borrow this tensor mutably as a complex view without copying.
11816 ///
11817 /// # Errors
11818 ///
11819 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11820 /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11821 /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11822 /// invalid representation metadata.
11823 pub fn as_complex_view_mut(
11824 &mut self,
11825 ) -> crate::Result<TypedTensorViewMut<'_, Complex32, DynRank>> {
11826 let op = "TypedTensor::as_complex_view_mut";
11827 validate_representation_pair(op, DType::F32, DType::C32)?;
11828 let source_layout = self.physical_layout();
11829 let layout = reinterpret_real_to_complex_layout(
11830 self.shape(),
11831 source_layout.strides(),
11832 source_layout.offset(),
11833 self.buffer_len(),
11834 op,
11835 )?;
11836 layout
11837 .validate_mutable_no_overlap()
11838 .map_err(|err| tensor_layout_error(op, err))?;
11839 if self.backend_buffer().is_some() {
11840 return Err(crate::Error::unsupported(
11841 op,
11842 "backend representation reinterpretation is enabled by the provider phases",
11843 ));
11844 }
11845 let placement = self.placement().clone();
11846 let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f32, Complex32>(
11847 self.backing_host_slice_mut()?,
11848 op,
11849 )?);
11850 Ok(TypedTensorViewMut {
11851 buffer,
11852 root: None,
11853 layout,
11854 placement,
11855 _representation: std::marker::PhantomData,
11856 })
11857 }
11858
11859 /// Consume this tensor and reinterpret its owner as `Complex32` without copying.
11860 ///
11861 /// The compact source must have an even physical element count. A failed
11862 /// operation returns the unchanged owner through
11863 /// [`ReinterpretError::into_owner`].
11864 ///
11865 /// # Errors
11866 ///
11867 /// Returns [`ReinterpretError::error`] containing
11868 /// [`ValidationError::InvalidArgument`] or
11869 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11870 /// owner.
11871 pub fn into_complex(self) -> Result<TypedTensor<Complex32, DynRank>, ReinterpretError<Self>> {
11872 reinterpret_owned(
11873 self,
11874 DType::F32,
11875 DType::C32,
11876 reinterpret_real_to_complex_layout,
11877 "TypedTensor::into_complex",
11878 )
11879 }
11880}
11881
11882impl<R: TensorRank> TypedTensor<f64, R> {
11883 /// Borrow this tensor as a complex view without copying.
11884 ///
11885 /// # Errors
11886 ///
11887 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11888 /// that is not supported, or [`ValidationError::ViewOutOfBounds`] for an
11889 /// invalid tensor layout.
11890 pub fn as_complex_view(&self) -> crate::Result<TypedTensorView<'_, Complex64, DynRank>> {
11891 self.as_view().as_complex_view()
11892 }
11893
11894 /// Borrow this tensor mutably as a complex view without copying.
11895 ///
11896 /// # Errors
11897 ///
11898 /// Returns [`crate::Error::Unsupported`] for backend reinterpretation
11899 /// that is not supported, [`ValidationError::OverlappingMutableLayout`]
11900 /// for a non-injective layout, or [`ValidationError::ViewOutOfBounds`] for
11901 /// invalid representation metadata.
11902 pub fn as_complex_view_mut(
11903 &mut self,
11904 ) -> crate::Result<TypedTensorViewMut<'_, Complex64, DynRank>> {
11905 let op = "TypedTensor::as_complex_view_mut";
11906 validate_representation_pair(op, DType::F64, DType::C64)?;
11907 let source_layout = self.physical_layout();
11908 let layout = reinterpret_real_to_complex_layout(
11909 self.shape(),
11910 source_layout.strides(),
11911 source_layout.offset(),
11912 self.buffer_len(),
11913 op,
11914 )?;
11915 layout
11916 .validate_mutable_no_overlap()
11917 .map_err(|err| tensor_layout_error(op, err))?;
11918 if self.backend_buffer().is_some() {
11919 return Err(crate::Error::unsupported(
11920 op,
11921 "backend representation reinterpretation is enabled by the provider phases",
11922 ));
11923 }
11924 let placement = self.placement().clone();
11925 let buffer = TensorStorageRefMut::Host(reinterpret_host_slice_mut::<f64, Complex64>(
11926 self.backing_host_slice_mut()?,
11927 op,
11928 )?);
11929 Ok(TypedTensorViewMut {
11930 buffer,
11931 root: None,
11932 layout,
11933 placement,
11934 _representation: std::marker::PhantomData,
11935 })
11936 }
11937
11938 /// Consume this tensor and reinterpret its owner as `Complex64` without copying.
11939 ///
11940 /// The compact source must have an even physical element count. A failed
11941 /// operation returns the unchanged owner through
11942 /// [`ReinterpretError::into_owner`].
11943 ///
11944 /// # Errors
11945 ///
11946 /// Returns [`ReinterpretError::error`] containing
11947 /// [`ValidationError::InvalidArgument`] or
11948 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
11949 /// owner.
11950 pub fn into_complex(self) -> Result<TypedTensor<Complex64, DynRank>, ReinterpretError<Self>> {
11951 reinterpret_owned(
11952 self,
11953 DType::F64,
11954 DType::C64,
11955 reinterpret_real_to_complex_layout,
11956 "TypedTensor::into_complex",
11957 )
11958 }
11959}
11960
11961impl Tensor {
11962 /// Borrow a complex tensor as its sealed interleaved real representation.
11963 ///
11964 /// # Errors
11965 ///
11966 /// Returns [`crate::Error::Unsupported`] for a non-complex dtype and
11967 /// [`ValidationError::ViewOutOfBounds`] or
11968 /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
11969 pub fn as_real_view(&self) -> crate::Result<TensorView<'_>> {
11970 match self.dtype() {
11971 DType::C32 => self
11972 .as_typed::<Complex<f32>>()
11973 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
11974 .as_real_view()
11975 .map(TensorView::F32),
11976 DType::C64 => self
11977 .as_typed::<Complex<f64>>()
11978 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
11979 .as_real_view()
11980 .map(TensorView::F64),
11981 other => Err(crate::Error::unsupported_dtype_conversion(
11982 "Tensor::as_real_view",
11983 other,
11984 DType::F32,
11985 "only complex tensors have a sealed real representation view",
11986 )),
11987 }
11988 }
11989
11990 /// Borrow a complex tensor mutably as its sealed interleaved real representation.
11991 ///
11992 /// # Errors
11993 ///
11994 /// Returns [`crate::Error::Unsupported`] for a non-complex dtype and
11995 /// [`ValidationError::ViewOutOfBounds`] or
11996 /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
11997 pub fn as_real_view_mut(&mut self) -> crate::Result<TensorViewMut<'_>> {
11998 match self.dtype() {
11999 DType::C32 => self
12000 .as_typed_mut::<Complex<f32>>()
12001 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12002 .as_real_view_mut()
12003 .map(TensorViewMut::F32),
12004 DType::C64 => self
12005 .as_typed_mut::<Complex<f64>>()
12006 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12007 .as_real_view_mut()
12008 .map(TensorViewMut::F64),
12009 other => Err(crate::Error::unsupported_dtype_conversion(
12010 "Tensor::as_real_view_mut",
12011 other,
12012 DType::F32,
12013 "only complex tensors have a sealed real representation view",
12014 )),
12015 }
12016 }
12017
12018 /// Consume a complex tensor and reinterpret its owner as real without copying.
12019 ///
12020 /// # Errors
12021 ///
12022 /// Returns [`ReinterpretError::error`] containing
12023 /// [`ValidationError::InvalidArgument`] or
12024 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
12025 /// owner.
12026 pub fn into_real(self) -> Result<Self, ReinterpretError<Self>> {
12027 let dtype = self.dtype();
12028 match dtype {
12029 DType::C32 => {
12030 let tensor = <Complex<f32> as TensorScalar>::into_typed(self)
12031 .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12032 tensor
12033 .into_real()
12034 .map(Tensor::from_typed::<f32>)
12035 .map_err(|error| {
12036 let (owner, error) = error.into_parts();
12037 ReinterpretError::new(Tensor::from_typed::<Complex<f32>>(owner), error)
12038 })
12039 }
12040 DType::C64 => {
12041 let tensor = <Complex<f64> as TensorScalar>::into_typed(self)
12042 .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12043 tensor
12044 .into_real()
12045 .map(Tensor::from_typed::<f64>)
12046 .map_err(|error| {
12047 let (owner, error) = error.into_parts();
12048 ReinterpretError::new(Tensor::from_typed::<Complex<f64>>(owner), error)
12049 })
12050 }
12051 _ => Err(ReinterpretError::new(
12052 self,
12053 crate::Error::unsupported(
12054 "Tensor::into_real",
12055 "only complex tensors have a sealed real representation",
12056 ),
12057 )),
12058 }
12059 }
12060
12061 /// Borrow an interleaved real tensor as its sealed complex representation.
12062 ///
12063 /// # Errors
12064 ///
12065 /// Returns [`crate::Error::Unsupported`] for a non-real dtype and
12066 /// [`ValidationError::ViewOutOfBounds`] or
12067 /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
12068 pub fn as_complex_view(&self) -> crate::Result<TensorView<'_>> {
12069 match self.dtype() {
12070 DType::F32 => self
12071 .as_typed::<f32>()
12072 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12073 .as_complex_view()
12074 .map(TensorView::C32),
12075 DType::F64 => self
12076 .as_typed::<f64>()
12077 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12078 .as_complex_view()
12079 .map(TensorView::C64),
12080 other => Err(crate::Error::unsupported_dtype_conversion(
12081 "Tensor::as_complex_view",
12082 other,
12083 DType::C32,
12084 "only real tensors can have a sealed complex representation view",
12085 )),
12086 }
12087 }
12088
12089 /// Borrow an interleaved real tensor mutably as its sealed complex representation.
12090 ///
12091 /// # Errors
12092 ///
12093 /// Returns [`crate::Error::Unsupported`] for a non-real dtype and
12094 /// [`ValidationError::ViewOutOfBounds`] or
12095 /// [`ValidationError::InvalidArgument`] for invalid layout metadata.
12096 pub fn as_complex_view_mut(&mut self) -> crate::Result<TensorViewMut<'_>> {
12097 match self.dtype() {
12098 DType::F32 => self
12099 .as_typed_mut::<f32>()
12100 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12101 .as_complex_view_mut()
12102 .map(TensorViewMut::C32),
12103 DType::F64 => self
12104 .as_typed_mut::<f64>()
12105 .unwrap_or_else(|| unreachable!("the dtype guard selects this arm"))
12106 .as_complex_view_mut()
12107 .map(TensorViewMut::C64),
12108 other => Err(crate::Error::unsupported_dtype_conversion(
12109 "Tensor::as_complex_view_mut",
12110 other,
12111 DType::C32,
12112 "only real tensors can have a sealed complex representation view",
12113 )),
12114 }
12115 }
12116
12117 /// Consume a real tensor and reinterpret its owner as complex without copying.
12118 ///
12119 /// # Errors
12120 ///
12121 /// Returns [`ReinterpretError::error`] containing
12122 /// [`ValidationError::InvalidArgument`] or
12123 /// [`ValidationError::ViewOutOfBounds`] while retaining the unchanged
12124 /// owner.
12125 pub fn into_complex(self) -> Result<Self, ReinterpretError<Self>> {
12126 let dtype = self.dtype();
12127 match dtype {
12128 DType::F32 => {
12129 let tensor = <f32 as TensorScalar>::into_typed(self)
12130 .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12131 tensor
12132 .into_complex()
12133 .map(Tensor::from_typed::<Complex<f32>>)
12134 .map_err(|error| {
12135 let (owner, error) = error.into_parts();
12136 ReinterpretError::new(Tensor::from_typed::<f32>(owner), error)
12137 })
12138 }
12139 DType::F64 => {
12140 let tensor = <f64 as TensorScalar>::into_typed(self)
12141 .unwrap_or_else(|_| unreachable!("the dtype guard selects this arm"));
12142 tensor
12143 .into_complex()
12144 .map(Tensor::from_typed::<Complex<f64>>)
12145 .map_err(|error| {
12146 let (owner, error) = error.into_parts();
12147 ReinterpretError::new(Tensor::from_typed::<f64>(owner), error)
12148 })
12149 }
12150 _ => Err(ReinterpretError::new(
12151 self,
12152 crate::Error::unsupported(
12153 "Tensor::into_complex",
12154 "only real tensors have a sealed complex representation",
12155 ),
12156 )),
12157 }
12158 }
12159
12160 /// Make an explicit owning copy of this dtype-erased tensor.
12161 ///
12162 /// `Tensor` deliberately does not implement [`Clone`]: copying can fail
12163 /// (device-only storage is rejected) and allocates a new, independent
12164 /// owner, so it is an explicit fallible call rather than an infallible
12165 /// `clone()`. The copy shares nothing with `self`; mutating one never
12166 /// affects the other. To share one tensor between several users without
12167 /// copying, wrap it in [`std::sync::Arc`] or borrow views of it.
12168 ///
12169 /// # Examples
12170 ///
12171 /// ```
12172 /// use std::sync::Arc;
12173 /// use tenferro_tensor::Tensor;
12174 ///
12175 /// let weights = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12176 /// // Two independent owners of the same values.
12177 /// let copy = weights.duplicate()?;
12178 /// assert_eq!(copy.as_slice::<f64>()?, weights.as_slice::<f64>()?);
12179 ///
12180 /// // A shared, read-only handle instead of a copy.
12181 /// let shared = Arc::new(weights);
12182 /// let other = Arc::clone(&shared);
12183 /// assert_eq!(other.shape(), &[2]);
12184 /// # Ok::<(), tenferro_tensor::Error>(())
12185 /// ```
12186 ///
12187 /// # Errors
12188 ///
12189 /// Returns [`crate::Error::RuntimeState`] or [`crate::Error::Unsupported`]
12190 /// when the selected backend/storage owner cannot be duplicated.
12191 pub fn duplicate(&self) -> crate::Result<Self> {
12192 match &self.payload {
12193 // A caller-owned payload is copied through its own entry point, which
12194 // keeps its element type and its view; sharing the payload instead
12195 // would alias the caller's storage.
12196 TensorPayload::External(payload, placement) => Ok(Self {
12197 payload: TensorPayload::External(payload.duplicate(), placement.clone()),
12198 }),
12199 TensorPayload::Native(_) => match self.dtype() {
12200 DType::F32 => self.duplicate_typed::<f32>(),
12201 DType::F64 => self.duplicate_typed::<f64>(),
12202 DType::I32 => self.duplicate_typed::<i32>(),
12203 DType::I64 => self.duplicate_typed::<i64>(),
12204 DType::Bool => self.duplicate_typed::<bool>(),
12205 DType::C32 => self.duplicate_typed::<Complex<f32>>(),
12206 DType::C64 => self.duplicate_typed::<Complex<f64>>(),
12207 DType::External(_) => unreachable!("a native payload carries a preset dtype"),
12208 },
12209 }
12210 }
12211
12212 /// Duplicate a preset tensor through its typed owner.
12213 fn duplicate_typed<T: TensorScalar>(&self) -> crate::Result<Self> {
12214 self.as_typed::<T>()
12215 .unwrap_or_else(|| unreachable!("the caller selected this arm from the dtype"))
12216 .duplicate()
12217 .map(Self::from_typed)
12218 }
12219
12220 /// Create a tensor from a shape and column-major flat data.
12221 ///
12222 /// This is the `Tensor`-level equivalent of
12223 /// `TypedTensor::<T>::from_vec_col_major`.
12224 ///
12225 /// # Examples
12226 ///
12227 /// ```
12228 /// use tenferro_tensor::Tensor;
12229 ///
12230 /// let t = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 3.0, 2.0, 4.0]).unwrap();
12231 /// assert_eq!(t.shape(), &[2, 2]);
12232 /// assert_eq!(t.as_slice::<f64>().unwrap(), &[1.0, 3.0, 2.0, 4.0]);
12233 /// ```
12234 /// # Errors
12235 ///
12236 /// Returns [`crate::Error::Validation`] with
12237 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
12238 /// the shape product differs from `data.len()`, or
12239 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
12240 /// arithmetic overflows.
12241 pub fn from_vec_col_major<T: TensorScalar>(
12242 shape: impl tenferro_tensor_core::IntoShapeVec,
12243 data: Vec<T>,
12244 ) -> crate::Result<Self> {
12245 // Build the typed owner once and wrap it: routing the shape through
12246 // `T::into_tensor(Vec<usize>, _)` costs an exact-size `Vec` per construction
12247 // that the destination cannot keep, because the erased payload stores the
12248 // inline shape the typed constructor already produces (#2177).
12249 Ok(Self::from_typed(TypedTensor::<T>::from_vec_col_major(
12250 shape, data,
12251 )?))
12252 }
12253
12254 /// Create a tensor from a shape and row-major (C-order) flat data.
12255 ///
12256 /// The values are reordered once into tenferro's column-major storage;
12257 /// no row-major owner is created. Use this for buffers authored in
12258 /// PyTorch/NumPy/C order instead of passing them to
12259 /// [`Self::from_vec_col_major`], which would reinterpret them silently.
12260 /// This is the `Tensor`-level equivalent of
12261 /// `TypedTensor::<T>::from_vec_row_major`.
12262 ///
12263 /// # Examples
12264 ///
12265 /// ```
12266 /// use tenferro_tensor::Tensor;
12267 ///
12268 /// // Row-major [[1, 2, 3], [4, 5, 6]].
12269 /// let t = Tensor::from_vec_row_major(vec![2, 3], vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0])?;
12270 /// assert_eq!(t.shape(), &[2, 3]);
12271 /// assert_eq!(t.as_slice::<f64>()?, &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);
12272 /// # Ok::<(), tenferro_tensor::Error>(())
12273 /// ```
12274 /// # Errors
12275 ///
12276 /// Returns [`crate::Error::Validation`] with
12277 /// [`tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch`] when
12278 /// the shape product differs from `data.len()`, or
12279 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when shape
12280 /// arithmetic overflows.
12281 pub fn from_vec_row_major<T: TensorScalar>(
12282 shape: impl tenferro_tensor_core::IntoShapeVec,
12283 data: Vec<T>,
12284 ) -> crate::Result<Self> {
12285 // The reorder keeps its own `op` name, and the shape comes back as the inline
12286 // vector the typed constructor takes, so neither `.to_vec()` in the erased
12287 // route is needed (#2177).
12288 let (shape, reordered) = row_major_reorder::<T, tenferro_tensor_core::DynRank>(
12289 shape,
12290 data,
12291 "Tensor::from_vec_row_major",
12292 )?;
12293 Ok(Self::from_typed(TypedTensor::<T>::from_vec_col_major(
12294 shape, reordered,
12295 )?))
12296 }
12297
12298 /// Tensor shape.
12299 ///
12300 /// # Examples
12301 ///
12302 /// ```rust
12303 /// use tenferro_tensor::{Tensor, TypedTensor};
12304 ///
12305 /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap());
12306 /// assert_eq!(t.shape(), &[2]);
12307 /// ```
12308 pub fn shape(&self) -> &[usize] {
12309 match &self.payload {
12310 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.shape()),
12311 // The payload keeps its shape from construction.
12312 TensorPayload::External(payload, _) => payload.shape(),
12313 }
12314 }
12315
12316 /// Tensor dtype tag.
12317 ///
12318 /// # Examples
12319 ///
12320 /// ```rust
12321 /// use tenferro_tensor::{DType, Tensor, TypedTensor};
12322 ///
12323 /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![], vec![1.0]).unwrap());
12324 /// assert_eq!(t.dtype(), DType::F64);
12325 /// ```
12326 pub fn dtype(&self) -> DType {
12327 match &self.payload {
12328 TensorPayload::Native(preset) => match preset {
12329 PresetTensor::F32(_) => DType::F32,
12330 PresetTensor::F64(_) => DType::F64,
12331 PresetTensor::I32(_) => DType::I32,
12332 PresetTensor::I64(_) => DType::I64,
12333 PresetTensor::Bool(_) => DType::Bool,
12334 PresetTensor::C32(_) => DType::C32,
12335 PresetTensor::C64(_) => DType::C64,
12336 },
12337 // The payload carries its own element identity.
12338 TensorPayload::External(payload, _) => DType::External(payload.element_type_id()),
12339 }
12340 }
12341
12342 /// Return placement metadata for this dtype-erased tensor.
12343 ///
12344 /// # Examples
12345 ///
12346 /// ```rust
12347 /// use tenferro_tensor::{MemoryKind, Tensor};
12348 ///
12349 /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
12350 /// assert_eq!(t.placement().memory_kind, MemoryKind::UnpinnedHost);
12351 /// ```
12352 pub fn placement(&self) -> &Placement {
12353 match &self.payload {
12354 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.placement()),
12355 // The placement is stored with the payload.
12356 TensorPayload::External(_, placement) => placement,
12357 }
12358 }
12359
12360 /// Return whether this tensor is backed by backend-native storage.
12361 ///
12362 /// # Examples
12363 ///
12364 /// ```rust
12365 /// use tenferro_tensor::Tensor;
12366 ///
12367 /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
12368 /// assert!(!t.is_backend_buffer());
12369 /// ```
12370 pub fn is_backend_buffer(&self) -> bool {
12371 match &self.payload {
12372 TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12373 matches!(&typed.storage, DynamicStorage::Group(core) if core.group.is_backend_buffer())
12374 }),
12375 // A caller-owned payload is host memory, never a backend buffer.
12376 TensorPayload::External(..) => false,
12377 }
12378 }
12379
12380 /// Return whether this tensor's payload is host-addressed memory.
12381 ///
12382 /// The one host/device answer, decided by the payload and never by
12383 /// [`Placement::memory_kind`]: the same answer
12384 /// [`TypedTensor::is_host_memory`] gives for a typed owner and
12385 /// [`TensorRead::is_host_memory`] for a read target. A caller-owned payload
12386 /// holds host bytes, so it is host memory; erasing its dtype, not its
12387 /// placement, is what makes a preset-scalar view unavailable.
12388 ///
12389 /// # Examples
12390 ///
12391 /// ```rust
12392 /// use tenferro_tensor::{Tensor, TensorRead};
12393 ///
12394 /// let t = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
12395 /// assert!(t.is_host_memory());
12396 /// assert!(TensorRead::from_tensor(&t).is_host_memory());
12397 /// # Ok::<(), tenferro_tensor::Error>(())
12398 /// ```
12399 pub fn is_host_memory(&self) -> bool {
12400 match &self.payload {
12401 TensorPayload::Native(preset) => with_preset!(preset, |typed| typed.is_host_memory()),
12402 TensorPayload::External(..) => true,
12403 }
12404 }
12405
12406 /// Compute the physical element offset for a logical index.
12407 ///
12408 /// # Examples
12409 ///
12410 /// ```rust
12411 /// use tenferro_tensor::Tensor;
12412 ///
12413 /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12414 /// assert_eq!(t.layout_linear_offset(&[1])?, 1);
12415 /// # Ok::<(), tenferro_tensor::Error>(())
12416 /// ```
12417 /// # Errors
12418 ///
12419 /// Returns [`crate::Error::Validation`] with
12420 /// [`tenferro_tensor_core::ValidationError::RankMismatch`] when `indices`
12421 /// has the wrong rank, [`tenferro_tensor_core::ValidationError::InvalidArgument`]
12422 /// when an index is outside its axis extent, or
12423 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when offset
12424 /// arithmetic overflows.
12425 pub fn layout_linear_offset(&self, indices: &[usize]) -> crate::Result<usize> {
12426 match &self.payload {
12427 TensorPayload::Native(_) => {
12428 let layout = tensor_layout(self);
12429 checked_view_offset_result(
12430 layout.shape(),
12431 layout.strides(),
12432 layout.offset(),
12433 indices,
12434 "Tensor::layout_linear_offset",
12435 )
12436 }
12437 // A caller-owned payload's owner resolves its own offsets.
12438 TensorPayload::External(..) => Err(crate::Error::unsupported_dtype(
12439 "layout_linear_offset",
12440 self.dtype(),
12441 "an externally defined payload resolves its own offsets",
12442 )),
12443 }
12444 }
12445
12446 /// Return whether this tensor is compact column-major.
12447 ///
12448 /// # Examples
12449 ///
12450 /// ```rust
12451 /// use tenferro_tensor::Tensor;
12452 ///
12453 /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12454 /// assert!(t.is_col_major_contiguous()?);
12455 /// # Ok::<(), tenferro_tensor::Error>(())
12456 /// ```
12457 /// # Errors
12458 ///
12459 /// Returns [`crate::Error::Validation`] with
12460 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
12461 /// compactness arithmetic overflows.
12462 pub fn is_col_major_contiguous(&self) -> crate::Result<bool> {
12463 match &self.payload {
12464 TensorPayload::Native(_) => tensor_layout(self)
12465 .is_compact_col_major()
12466 .map_err(|err| tensor_layout_error("Tensor::is_col_major_contiguous", err)),
12467 // The payload is a compact column-major host tensor by construction.
12468 TensorPayload::External(..) => Ok(true),
12469 }
12470 }
12471
12472 /// Return a compact string summary of this tensor's layout metadata.
12473 ///
12474 /// # Examples
12475 ///
12476 /// ```rust
12477 /// use tenferro_tensor::Tensor;
12478 ///
12479 /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12480 /// assert!(t.layout_summary().contains("shape=[2]"));
12481 /// # Ok::<(), tenferro_tensor::Error>(())
12482 /// ```
12483 pub fn layout_summary(&self) -> String {
12484 let layout = tensor_layout(self);
12485 layout_summary(layout.shape(), layout.strides(), layout.offset())
12486 }
12487
12488 /// Assert this tensor is compact column-major.
12489 ///
12490 /// # Examples
12491 ///
12492 /// ```rust
12493 /// use tenferro_tensor::Tensor;
12494 ///
12495 /// let t = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12496 /// t.assert_col_major_contiguous()?;
12497 /// # Ok::<(), tenferro_tensor::Error>(())
12498 /// ```
12499 /// # Errors
12500 ///
12501 /// Returns [`crate::Error::Validation`] with
12502 /// [`tenferro_tensor_core::ValidationError::IntegerOverflow`] when
12503 /// compactness arithmetic overflows, or
12504 /// [`tenferro_tensor_core::ValidationError::InvalidArgument`] when the
12505 /// tensor is not compact column-major.
12506 pub fn assert_col_major_contiguous(&self) -> crate::Result<()> {
12507 let layout = tensor_layout(self);
12508 assert_layout_col_major_contiguous(
12509 self.is_col_major_contiguous()?,
12510 layout.shape(),
12511 layout.strides(),
12512 layout.offset(),
12513 "Tensor::assert_col_major_contiguous",
12514 )
12515 }
12516
12517 /// Try to borrow the host data as a typed slice.
12518 ///
12519 /// Returns an error if the tensor dtype does not match `T`.
12520 ///
12521 /// # Examples
12522 ///
12523 /// ```
12524 /// use tenferro_tensor::{Tensor, TypedTensor};
12525 ///
12526 /// let t = Tensor::from_typed(TypedTensor::from_vec_col_major(vec![3], vec![1.0, 2.0, 3.0]).unwrap());
12527 /// assert_eq!(t.as_slice::<f64>().unwrap(), [1.0, 2.0, 3.0].as_slice());
12528 /// assert!(t.as_slice::<f32>().is_err());
12529 /// ```
12530 /// # Errors
12531 ///
12532 /// Returns [`crate::Error::Validation`] with
12533 /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] when `T` does
12534 /// not match the tensor dtype, or [`crate::Error::RuntimeState`] when the
12535 /// matching tensor uses backend storage that has not been downloaded.
12536 pub fn as_slice<T: TensorScalar>(&self) -> crate::Result<&[T]> {
12537 T::as_slice(self)
12538 }
12539
12540 /// Borrow the typed tensor when the requested scalar matches this tensor's dtype.
12541 ///
12542 /// This is the accessor tag-based dispatch needs: it recovers the typed tensor — and with it the
12543 /// device buffer — from a value whose element type is only known at run time, so a caller can
12544 /// dispatch on [`Tensor::dtype`] instead of matching every variant. An externally defined scalar
12545 /// is not a typed tensor, so it returns `None` rather than guessing a representation.
12546 ///
12547 /// # Examples
12548 ///
12549 /// ```
12550 /// use tenferro_tensor::Tensor;
12551 ///
12552 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12553 /// assert!(tensor.as_typed::<f64>().is_some());
12554 /// assert!(tensor.as_typed::<f32>().is_none());
12555 /// assert_eq!(tensor.as_typed::<f64>().unwrap().shape(), &[2]);
12556 /// # Ok::<(), tenferro_tensor::Error>(())
12557 /// ```
12558 #[must_use]
12559 pub fn as_typed<T: TensorScalar>(&self) -> Option<&TypedTensor<T>> {
12560 if self.dtype() != T::dtype() {
12561 return None;
12562 }
12563 match &self.payload {
12564 TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12565 (typed as &dyn Any).downcast_ref::<TypedTensor<T>>()
12566 }),
12567 TensorPayload::External(..) => None,
12568 }
12569 }
12570
12571 /// Mutably borrow the typed tensor when the requested scalar matches this tensor's dtype.
12572 ///
12573 /// This is the mutable half of [`Tensor::as_typed`], for the tables whose arm calls a method that
12574 /// needs `&mut`, such as marking a freshly allocated output with its placement. An externally
12575 /// defined scalar is not a typed tensor, so it returns `None` for the same reason.
12576 ///
12577 /// # Examples
12578 ///
12579 /// ```
12580 /// use tenferro_tensor::Tensor;
12581 ///
12582 /// let mut tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12583 /// assert!(tensor.as_typed_mut::<f64>().is_some());
12584 /// assert!(tensor.as_typed_mut::<f32>().is_none());
12585 /// # Ok::<(), tenferro_tensor::Error>(())
12586 /// ```
12587 #[must_use]
12588 pub fn as_typed_mut<T: TensorScalar>(&mut self) -> Option<&mut TypedTensor<T>> {
12589 if self.dtype() != T::dtype() {
12590 return None;
12591 }
12592 match &mut self.payload {
12593 TensorPayload::Native(preset) => with_preset!(preset, |typed| {
12594 (typed as &mut dyn Any).downcast_mut::<TypedTensor<T>>()
12595 }),
12596 TensorPayload::External(..) => None,
12597 }
12598 }
12599
12600 /// Consume this tensor and return the owned typed tensor when the dtype matches.
12601 ///
12602 /// This is the consuming counterpart of [`Tensor::as_typed`], for the tables whose arm hands the typed
12603 /// tensor to a function that takes it by value — reusing its buffer rather than copying it.
12604 ///
12605 /// # Examples
12606 ///
12607 /// ```
12608 /// use tenferro_tensor::Tensor;
12609 ///
12610 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
12611 /// assert!(tensor.into_typed::<f64>().is_ok());
12612 ///
12613 /// let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f32, 2.0])?;
12614 /// assert!(tensor.into_typed::<f64>().is_err());
12615 /// # Ok::<(), tenferro_tensor::Error>(())
12616 /// ```
12617 /// # Errors
12618 ///
12619 /// Returns [`ReinterpretError`] carrying the unchanged tensor when `T` is
12620 /// not this tensor's dtype, with [`crate::Error::Validation`] and
12621 /// [`tenferro_tensor_core::ValidationError::DTypeMismatch`] as the cause.
12622 /// A matching tensor is handed over as it is, including one whose storage
12623 /// lives in a backend buffer.
12624 pub fn into_typed<T: TensorScalar>(
12625 self,
12626 ) -> std::result::Result<TypedTensor<T>, ReinterpretError<Self>> {
12627 T::into_typed(self)
12628 }
12629
12630 /// Consume this tensor and return its owned column-major buffer when the
12631 /// dtype matches.
12632 ///
12633 /// # Examples
12634 ///
12635 /// ```
12636 /// use tenferro_tensor::Tensor;
12637 ///
12638 /// let t = Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap();
12639 /// assert_eq!(t.into_vec_col_major::<f64>().unwrap().1, vec![2.0]);
12640 /// ```
12641 /// # Errors
12642 ///
12643 /// Returns [`ReinterpretError`] carrying the unchanged tensor when `T` does
12644 /// not match the tensor dtype or when the matching tensor uses backend
12645 /// storage that has not been downloaded.
12646 pub fn into_vec_col_major<T: TensorScalar>(
12647 self,
12648 ) -> std::result::Result<(Vec<usize>, Vec<T>), ReinterpretError<Self>> {
12649 let typed = T::into_typed(self)?;
12650 match typed.into_vec_col_major() {
12651 Ok(parts) => Ok(parts),
12652 Err(failure) => {
12653 let (owner, error) = failure.into_parts();
12654 Err(ReinterpretError::new(Tensor::from_typed(owner), error))
12655 }
12656 }
12657 }
12658}
12659
12660// INVARIANT: retained for crate-local layout tests while tensor indexing
12661// helpers remain split across the tensor and CPU crates.
12662#[allow(dead_code)]
12663pub(crate) fn flat_to_multi(mut flat: usize, shape: &[usize], out: &mut [usize]) {
12664 for i in 0..shape.len() {
12665 if shape[i] == 0 {
12666 out[i] = 0;
12667 } else {
12668 out[i] = flat % shape[i];
12669 flat /= shape[i];
12670 }
12671 }
12672}