use core::fmt;
use crate::shapes::{OperationKind, ShapeBuf, ShapeError, StrideBuf};
use crate::tensor::device::DeviceId;
use crate::tensor::dtype::{ConstDType, DTypeDescriptor};
#[derive(
Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
)]
pub enum LayoutClass {
Strided,
Contiguous,
ScalarLeft,
ScalarRight,
ContiguousLastAxis,
RowWise,
ChannelWise,
}
impl LayoutClass {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Strided => "strided",
Self::Contiguous => "contiguous",
Self::ScalarLeft => "scalar-left",
Self::ScalarRight => "scalar-right",
Self::ContiguousLastAxis => "contiguous-last-axis",
Self::RowWise => "row-wise",
Self::ChannelWise => "channel-wise",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Alignment(usize);
impl Alignment {
pub const BYTE: Self = Self(1);
pub const fn of<T>() -> Self {
Self(core::mem::align_of::<T>())
}
pub fn new(bytes: usize) -> Result<Self, MetaError> {
if bytes.is_power_of_two() {
Ok(Self(bytes))
} else {
Err(MetaError::InvalidAlignment { bytes })
}
}
#[must_use]
pub const fn bytes(self) -> usize {
self.0
}
#[must_use]
pub const fn supports(self, required_bytes: usize) -> bool {
required_bytes.is_power_of_two() && self.0 >= required_bytes
}
fn after_offset_bytes(self, offset_bytes: usize) -> Self {
if offset_bytes == 0 {
return self;
}
let offset_alignment = 1usize << offset_bytes.trailing_zeros();
Self(core::cmp::min(self.0, offset_alignment))
}
}
impl Default for Alignment {
fn default() -> Self {
Self::BYTE
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MetaError {
Shape(ShapeError),
InvalidAlignment {
bytes: usize,
},
OutOfBounds {
offset_elements: usize,
span_elements: usize,
capacity_elements: usize,
},
}
impl From<ShapeError> for MetaError {
fn from(error: ShapeError) -> Self {
Self::Shape(error)
}
}
impl fmt::Display for MetaError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Shape(error) => fmt::Display::fmt(error, f),
Self::InvalidAlignment { bytes } => write!(
f,
"invalid storage alignment {bytes}: expected a non-zero power of two"
),
Self::OutOfBounds {
offset_elements,
span_elements,
capacity_elements,
} => write!(
f,
"storage view out of bounds: offset {offset_elements} + span {span_elements} exceeds capacity {capacity_elements}"
),
}
}
}
#[cfg(feature = "std")]
impl std::error::Error for MetaError {}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TensorMeta {
fields: TensorMetaFields,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TensorMetaFields {
pub shape: ShapeBuf,
pub strides: StrideBuf,
pub offset_elements: usize,
pub dtype: DTypeDescriptor,
pub device: DeviceId,
pub layout: LayoutClass,
pub alignment: Alignment,
}
impl core::ops::Deref for TensorMeta {
type Target = TensorMetaFields;
fn deref(&self) -> &Self::Target {
&self.fields
}
}
impl TensorMeta {
pub const UNALLOCATED: Self = Self {
fields: TensorMetaFields {
shape: ShapeBuf::SCALAR,
strides: StrideBuf::EMPTY,
offset_elements: 0,
dtype: <f32 as ConstDType>::DESCRIPTOR,
device: DeviceId::CPU,
layout: LayoutClass::Contiguous,
alignment: Alignment::BYTE,
},
};
pub fn try_new(
shape: ShapeBuf,
strides: StrideBuf,
offset_elements: usize,
dtype: DTypeDescriptor,
device: DeviceId,
allocation_alignment: Alignment,
capacity_elements: usize,
) -> Result<Self, MetaError> {
let span_elements = strides.checked_span(&shape, OperationKind::Storage)?;
let end =
offset_elements
.checked_add(span_elements)
.ok_or(ShapeError::ArithmeticOverflow {
operation: OperationKind::Storage,
expression: "storage offset + view span",
})?;
if end > capacity_elements {
return Err(MetaError::OutOfBounds {
offset_elements,
span_elements,
capacity_elements,
});
}
let offset_bytes = dtype.size_bytes(offset_elements, OperationKind::Storage)?;
let layout = if strides.is_contiguous_for(&shape) {
LayoutClass::Contiguous
} else {
LayoutClass::Strided
};
Ok(Self {
fields: TensorMetaFields {
shape,
strides,
offset_elements,
dtype,
device,
layout,
alignment: allocation_alignment.after_offset_bytes(offset_bytes),
},
})
}
pub fn contiguous(
shape: ShapeBuf,
dtype: DTypeDescriptor,
device: DeviceId,
allocation_alignment: Alignment,
capacity_elements: usize,
) -> Result<Self, MetaError> {
let strides = StrideBuf::contiguous_for(&shape, OperationKind::Storage)?;
Self::try_new(
shape,
strides,
0,
dtype,
device,
allocation_alignment,
capacity_elements,
)
}
#[must_use]
pub const fn shape(&self) -> &ShapeBuf {
&self.fields.shape
}
#[must_use]
pub const fn strides(&self) -> &StrideBuf {
&self.fields.strides
}
#[must_use]
pub const fn offset_elements(&self) -> usize {
self.fields.offset_elements
}
#[must_use]
pub const fn dtype(&self) -> DTypeDescriptor {
self.fields.dtype
}
#[must_use]
pub const fn device(&self) -> DeviceId {
self.fields.device
}
#[must_use]
pub const fn layout(&self) -> LayoutClass {
self.fields.layout
}
#[must_use]
pub const fn alignment(&self) -> Alignment {
self.fields.alignment
}
}
#[cfg(test)]
mod tests {
use super::*;
fn meta(
shape: &[usize],
strides: &[usize],
offset: usize,
alignment: usize,
capacity: usize,
) -> Result<TensorMeta, MetaError> {
TensorMeta::try_new(
ShapeBuf::from_slice(shape),
StrideBuf::from_slice(strides),
offset,
<f32 as ConstDType>::DESCRIPTOR,
DeviceId::cpu(),
Alignment::new(alignment)?,
capacity,
)
}
#[test]
fn contiguous_layout_is_derived_not_asserted() {
let meta = meta(&[2, 3], &[3, 1], 0, 16, 6).unwrap();
assert_eq!(meta.layout(), LayoutClass::Contiguous);
assert_eq!(meta.shape().dims(), &[2, 3]);
assert_eq!(meta.strides().strides(), &[3, 1]);
}
#[test]
fn transposed_and_broadcast_views_are_strided() {
let transposed = meta(&[3, 2], &[1, 3], 0, 16, 6).unwrap();
let broadcast = meta(&[4, 3], &[0, 1], 0, 16, 3).unwrap();
assert_eq!(transposed.layout(), LayoutClass::Strided);
assert_eq!(broadcast.layout(), LayoutClass::Strided);
}
#[test]
fn a_view_offset_weakens_but_never_strengthens_alignment() {
let four = meta(&[1], &[1], 1, 16, 4).unwrap();
let eight = meta(&[1], &[1], 2, 16, 4).unwrap();
assert_eq!(four.alignment().bytes(), 4);
assert_eq!(eight.alignment().bytes(), 8);
assert!(eight.alignment().supports(4));
assert!(!eight.alignment().supports(16));
}
#[test]
fn zero_offset_preserves_the_allocation_alignment() {
let meta = meta(&[2], &[1], 0, 32, 2).unwrap();
assert_eq!(meta.alignment().bytes(), 32);
}
#[test]
fn empty_views_may_sit_at_but_not_after_the_allocation_end() {
assert!(meta(&[0, usize::MAX], &[usize::MAX, 1], 7, 8, 7).is_ok());
assert!(matches!(
meta(&[0], &[1], 8, 8, 7),
Err(MetaError::OutOfBounds { .. })
));
}
#[test]
fn strided_span_and_offset_are_checked_against_capacity() {
assert!(matches!(
meta(&[2, 2], &[3, 1], 2, 16, 6),
Err(MetaError::OutOfBounds {
offset_elements: 2,
span_elements: 5,
capacity_elements: 6,
})
));
}
#[test]
fn rank_and_arithmetic_failures_remain_structured() {
assert!(matches!(
meta(&[2, 3], &[1], 0, 8, 6),
Err(MetaError::Shape(ShapeError::RankMismatch { .. }))
));
assert!(matches!(
meta(&[usize::MAX, 2], &[2, 1], 0, 8, usize::MAX),
Err(MetaError::Shape(ShapeError::ArithmeticOverflow { .. }))
));
}
#[test]
fn invalid_alignment_is_rejected() {
assert!(matches!(
Alignment::new(0),
Err(MetaError::InvalidAlignment { bytes: 0 })
));
assert!(matches!(
Alignment::new(24),
Err(MetaError::InvalidAlignment { bytes: 24 })
));
}
}