Skip to main content

TensorRead

Enum TensorRead 

Source
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>

Source

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>

Source

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]);
Source

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());
Source

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());
Source

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]);
Source

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);
Source

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]);
Source

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);
Source

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());
Source

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);
Source

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);
Source

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.

Source

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);
Source

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.

Source

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.

Source

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"
);
Source

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.

Source

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<'_>

Source§

type Repr = Erased

The representation results take for this input.
Source§

fn as_read(&self) -> TensorRead<'_>

Borrow this input as a TensorRead. Metadata only; never copies element data. Read more
Source§

impl<'a> Clone for TensorRead<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl<'a> Debug for TensorRead<'a>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for TensorRead<'a>

§

impl<'a> !UnwindSafe for TensorRead<'a>

§

impl<'a> Freeze for TensorRead<'a>

§

impl<'a> Send for TensorRead<'a>

§

impl<'a> Sync for TensorRead<'a>

§

impl<'a> Unpin for TensorRead<'a>

§

impl<'a> UnsafeUnpin for TensorRead<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.