pub enum TensorRead<'a> {
Tensor(&'a Tensor),
View(TensorView<'a>),
}Expand description
Read-only tensor input accepted by synchronous eager kernels.
TensorRead lets kernels accept either an owned tensor reference or a
borrowed TensorView without forcing callers to materialize first.
The View variant preserves arbitrary strides and offsets, so kernels that
support strided reads can consume transposes, slices, and broadcasts directly.
TensorRead is intentionally borrowed. It is an input-dispatch type, not an
owned lazy tensor value. APIs that need to store a lazy layout result should
keep an owned base tensor plus layout metadata, then expose a TensorRead
only for the duration of kernel dispatch.
§Examples
use tenferro_tensor::{DType, Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
let read = TensorRead::from_tensor(&tensor);
assert_eq!(read.dtype(), DType::F64);
assert_eq!(read.shape(), &[2]);Variants§
Tensor(&'a Tensor)
View(TensorView<'a>)
Implementations§
Source§impl<'a> TensorRead<'a>
impl<'a> TensorRead<'a>
Sourcepub fn try_host(self, op: &'static str) -> Result<TensorView<'a, Host>>
pub fn try_host(self, op: &'static str) -> Result<TensorView<'a, Host>>
Checked narrowing of a read target to a host-marked view.
This is the boundary a CPU entry point crosses once: an owned tensor is
borrowed without copying, an existing view keeps its layout, and the
result is a TensorView<'a, Host> whose consumers read
host elements without re-checking placement. op names the operation
in the error, as the per-entry checks it replaces did.
§Examples
use tenferro_tensor::{DType, Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let host = TensorRead::from_tensor(&tensor).try_host("cholesky")?;
assert_eq!(host.dtype(), DType::F64);§Errors
Returns crate::Error::UnsupportedDType attributed to op for a
tensor built with Tensor::external, which has no preset-scalar view,
and crate::Error::RuntimeState attributed to op when the read
borrows backend (device) storage; download the tensor to host first.
Source§impl<'a> TensorRead<'a>
impl<'a> TensorRead<'a>
Sourcepub fn from_tensor(tensor: &'a Tensor) -> Self
pub fn from_tensor(tensor: &'a Tensor) -> Self
Borrow an owned tensor as a read target without copying it.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let read = TensorRead::from_tensor(&tensor);
assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);Sourcepub fn from_view(view: TensorView<'a>) -> Self
pub fn from_view(view: TensorView<'a>) -> Self
Wrap a borrowed dtype-erased view as a read target.
§Examples
use tenferro_tensor::{TensorRead, TensorView};
let read = TensorRead::from_view(TensorView::i32(&[2], &[3, 4])?);
assert_eq!(read.as_slice::<i32>()?, &[3, 4]);
assert!(read.as_tensor().is_none());Sourcepub fn tensor_view(self) -> Option<TensorView<'a>>
pub fn tensor_view(self) -> Option<TensorView<'a>>
Convert this read target into a dtype-erased tensor view, or None when
it borrows a tensor with an externally defined payload.
Owned tensors are borrowed without copying their storage. Existing
views are returned as is, preserving their layout and placement metadata.
TensorView has one variant per preset scalar (F32 … C64) and none
for a caller-owned element type, so a tensor built from
Tensor::external has no view; read it through
Tensor::external_payload instead.
§Examples
use tenferro_tensor::{DynRank, ErasedHostTensor, Host, Tensor, TensorRead, TypedTensor};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let view = TensorRead::from_tensor(&tensor)
.tensor_view()
.ok_or("a preset f64 tensor has a view")?;
assert_eq!(view.shape(), &[2]);
assert_eq!(view.as_slice::<f64>()?, &[1.0, 2.0]);
let payload = ErasedHostTensor::new(
TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?,
);
let external = Tensor::external(payload);
assert!(TensorRead::from_tensor(&external).tensor_view().is_none());Sourcepub fn as_slice<T: TensorScalar>(&self) -> Result<&'a [T]>
pub fn as_slice<T: TensorScalar>(&self) -> Result<&'a [T]>
Borrow this read target as a typed compact host slice without allocation.
This delegates to TensorView::as_slice. Cloning a TensorRead is a
shallow clone of its borrowed reference or view metadata, so the returned
slice retains the original 'a storage lifetime and never outlives the
storage borrowed by this read target. This method does not materialize,
transfer, or otherwise canonicalize the input.
§Errors
Returns ValidationError::DTypeMismatch when T does not match the
input dtype, ValidationError::NonContiguousViewAsSlice for a
noncompact view, a typed runtime-state host-access error for
backend-owned storage, or crate::Error::UnsupportedDType for a
tensor built with Tensor::external, which has no preset-scalar view.
Backend-owned inputs are never downloaded implicitly.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let read = TensorRead::from_tensor(&tensor);
assert_eq!(read.as_slice::<f64>()?, &[1.0, 2.0]);Sourcepub fn dtype(&self) -> DType
pub fn dtype(&self) -> DType
Return the element dtype of this read target.
§Examples
use tenferro_tensor::{DType, Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1_i64])?;
assert_eq!(TensorRead::from_tensor(&tensor).dtype(), DType::I64);Sourcepub fn shape(&self) -> &[usize]
pub fn shape(&self) -> &[usize]
Return the logical shape of this read target.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
assert_eq!(TensorRead::from_tensor(&tensor).shape(), &[2, 1]);Sourcepub fn placement(&self) -> &Placement
pub fn placement(&self) -> &Placement
Return the placement metadata carried by this read target.
§Examples
use tenferro_tensor::{MemoryKind, Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
let read = TensorRead::from_tensor(&tensor);
assert_eq!(read.placement().memory_kind, MemoryKind::UnpinnedHost);Sourcepub fn is_host_memory(&self) -> bool
pub fn is_host_memory(&self) -> bool
Return whether this read target borrows host-addressed memory.
The one host/device answer a CPU entry point needs, decided by the
payload and never by Placement::memory_kind; it is the same answer
Self::try_host acts on, and the same one
TypedTensor::is_host_memory gives for an owner.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
assert!(TensorRead::from_tensor(&tensor).is_host_memory());Sourcepub fn backend_family(&self) -> Option<&'static str>
pub fn backend_family(&self) -> Option<&'static str>
Return the physical backend family of this read target, when backend-owned.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
assert_eq!(TensorRead::from_tensor(&tensor).backend_family(), None);Sourcepub fn allocation_domain(&self) -> Option<AllocationDomainId>
pub fn allocation_domain(&self) -> Option<AllocationDomainId>
Return the shared allocation domain of this read target, when present.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
assert_eq!(TensorRead::from_tensor(&tensor).allocation_domain(), None);Sourcepub fn strides(&self) -> Result<Vec<isize>>
pub fn strides(&self) -> Result<Vec<isize>>
Return strides in element units; owned tensors report compact column-major strides.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
assert_eq!(TensorRead::from_tensor(&tensor).strides()?, vec![1, 2]);§Errors
Returns crate::Error::Validation with
tenferro_tensor_core::ValidationError::IntegerOverflow when
column-major stride arithmetic overflows.
Sourcepub fn offset(&self) -> isize
pub fn offset(&self) -> isize
Return the physical element offset; owned tensors always start at 0.
§Examples
use tenferro_tensor::{TensorRead, TensorView, TypedTensorView};
let data = [1.0_f64, 2.0, 3.0];
let view = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![1], 1, &data)?);
assert_eq!(TensorRead::from_view(view).offset(), 1);Sourcepub fn layout_linear_offset(&self, indices: &[usize]) -> Result<usize>
pub fn layout_linear_offset(&self, indices: &[usize]) -> Result<usize>
Compute the physical element offset for a logical index.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
let read = TensorRead::from_tensor(&tensor);
assert_eq!(read.layout_linear_offset(&[1, 2])?, 5);
assert!(read.layout_linear_offset(&[2, 0]).is_err());§Errors
Returns crate::Error::Validation with
tenferro_tensor_core::ValidationError::RankMismatch when indices
has the wrong rank, tenferro_tensor_core::ValidationError::InvalidArgument
when an index is outside its axis extent, or
tenferro_tensor_core::ValidationError::IntegerOverflow when offset
arithmetic overflows.
Sourcepub fn is_col_major_contiguous(&self) -> Result<bool>
pub fn is_col_major_contiguous(&self) -> Result<bool>
Return whether this read target is compact column-major.
§Examples
use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
assert!(TensorRead::from_tensor(&tensor).is_col_major_contiguous()?);
let data = [1.0_f64, 2.0, 3.0];
let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
assert!(!TensorRead::from_view(strided).is_col_major_contiguous()?);§Errors
Returns crate::Error::Validation with
tenferro_tensor_core::ValidationError::IntegerOverflow when
compactness arithmetic overflows.
Sourcepub fn layout_summary(&self) -> String
pub fn layout_summary(&self) -> String
Return a compact string summary of this read target’s layout metadata.
§Examples
use tenferro_tensor::{Tensor, TensorRead};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
assert_eq!(
TensorRead::from_tensor(&tensor).layout_summary(),
"shape=[2] strides=[1] offset=0"
);Sourcepub fn assert_col_major_contiguous(&self) -> Result<()>
pub fn assert_col_major_contiguous(&self) -> Result<()>
Assert this read target is compact column-major.
§Examples
use tenferro_tensor::{Tensor, TensorRead, TensorView, TypedTensorView};
let tensor = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
TensorRead::from_tensor(&tensor).assert_col_major_contiguous()?;
let data = [1.0_f64, 2.0, 3.0];
let strided = TensorView::F64(TypedTensorView::from_slice(vec![2], vec![2], 0, &data)?);
assert!(TensorRead::from_view(strided).assert_col_major_contiguous().is_err());§Errors
Returns crate::Error::Validation with
tenferro_tensor_core::ValidationError::IntegerOverflow when
compactness arithmetic overflows, or
tenferro_tensor_core::ValidationError::InvalidArgument when the
view is not compact column-major.
Sourcepub fn as_tensor(&self) -> Option<&'a Tensor>
pub fn as_tensor(&self) -> Option<&'a Tensor>
Return the borrowed owned tensor, or None when this read target is a view.
§Examples
use tenferro_tensor::{Tensor, TensorRead, TensorView};
let tensor = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
assert!(TensorRead::from_tensor(&tensor).as_tensor().is_some());
assert!(TensorRead::from_view(TensorView::f64(&[1], &[1.0])?).as_tensor().is_none());Trait Implementations§
Source§impl AsView for TensorRead<'_>
impl AsView for TensorRead<'_>
Source§fn as_read(&self) -> TensorRead<'_>
fn as_read(&self) -> TensorRead<'_>
TensorRead. Metadata only; never copies
element data. Read more