|
| 1 | +// SPDX-License-Identifier: Apache-2.0 |
| 2 | +// SPDX-FileCopyrightText: Copyright the Vortex contributors |
| 3 | + |
| 4 | +//! Tensor row inputs for scalar functions. |
| 5 | +//! |
| 6 | +//! [`TensorRow`] decodes one flat row from either an ordinary tensor column or either supported |
| 7 | +//! batch-constant representation. Batch execution owns input validity, so decoding handles only |
| 8 | +//! the non-null coordinate storage. |
| 9 | +
|
| 10 | +use std::marker::PhantomData; |
| 11 | + |
| 12 | +use num_traits::Float; |
| 13 | +use vortex_array::ArrayRef; |
| 14 | +use vortex_array::ExecutionCtx; |
| 15 | +use vortex_array::IntoArray; |
| 16 | +use vortex_array::arrays::Constant; |
| 17 | +use vortex_array::arrays::ConstantArray; |
| 18 | +use vortex_array::arrays::Extension; |
| 19 | +use vortex_array::arrays::ExtensionArray; |
| 20 | +use vortex_array::arrays::Masked; |
| 21 | +use vortex_array::arrays::extension::ExtensionArrayExt; |
| 22 | +use vortex_array::arrays::masked::MaskedArraySlotsExt; |
| 23 | +use vortex_array::dtype::DType; |
| 24 | +use vortex_array::dtype::NativePType; |
| 25 | +use vortex_array::dtype::PType; |
| 26 | +use vortex_array::scalar_fn::unstable::row::InputElement; |
| 27 | +use vortex_array::scalar_fn::unstable::row::ViewLen; |
| 28 | +use vortex_buffer::Buffer; |
| 29 | +use vortex_error::VortexResult; |
| 30 | +use vortex_error::vortex_bail; |
| 31 | +use vortex_error::vortex_ensure; |
| 32 | +use vortex_error::vortex_ensure_eq; |
| 33 | +use vortex_error::vortex_err; |
| 34 | + |
| 35 | +use crate::utils::extract_flat_elements; |
| 36 | +use crate::utils::validate_tensor_float_input; |
| 37 | + |
| 38 | +/// Returns the common float element type of tensor row-function arguments. |
| 39 | +pub fn tensor_element_ptype(args: &[DType]) -> VortexResult<PType> { |
| 40 | + let (first, rest) = args |
| 41 | + .split_first() |
| 42 | + .ok_or_else(|| vortex_err!("tensor row function requires at least one input"))?; |
| 43 | + |
| 44 | + for argument in rest { |
| 45 | + vortex_ensure!( |
| 46 | + first.eq_ignore_nullability(argument), |
| 47 | + "tensor row-function inputs must have the same dtype, got {first} and {argument}", |
| 48 | + ); |
| 49 | + } |
| 50 | + |
| 51 | + Ok(validate_tensor_float_input(first)?.element_ptype()) |
| 52 | +} |
| 53 | + |
| 54 | +/// A tensor-valued row-function input whose element is one flat tensor row. |
| 55 | +pub struct TensorRow<T>(PhantomData<T>); |
| 56 | + |
| 57 | +/// A decoded tensor column with constant-width rows. |
| 58 | +pub struct TensorRows<T> { |
| 59 | + elements: Buffer<T>, |
| 60 | + row_count: usize, |
| 61 | + row_width: usize, |
| 62 | + stride: usize, |
| 63 | +} |
| 64 | + |
| 65 | +impl<T> ViewLen for TensorRows<T> { |
| 66 | + fn len(&self) -> usize { |
| 67 | + self.row_count |
| 68 | + } |
| 69 | +} |
| 70 | + |
| 71 | +fn decode_tensor_storage<T: NativePType>( |
| 72 | + storage: &ArrayRef, |
| 73 | + row_count: usize, |
| 74 | + row_width: usize, |
| 75 | + ctx: &mut ExecutionCtx, |
| 76 | +) -> VortexResult<TensorRows<T>> { |
| 77 | + let flat = extract_flat_elements(storage, row_width, ctx)?; |
| 78 | + let row_width = flat.list_size(); |
| 79 | + let stride = flat.row_stride(); |
| 80 | + let elements = flat.into_buffer::<T>(); |
| 81 | + |
| 82 | + let expected_elements = if stride == 0 { |
| 83 | + row_width |
| 84 | + } else { |
| 85 | + vortex_ensure_eq!( |
| 86 | + stride, |
| 87 | + row_width, |
| 88 | + "per-row tensor stride must equal its width, got {stride}", |
| 89 | + ); |
| 90 | + let Some(expected_elements) = row_count.checked_mul(stride) else { |
| 91 | + vortex_bail!( |
| 92 | + "tensor row storage length must fit usize, got {row_count} rows of width {stride}", |
| 93 | + ); |
| 94 | + }; |
| 95 | + expected_elements |
| 96 | + }; |
| 97 | + vortex_ensure_eq!( |
| 98 | + elements.len(), |
| 99 | + expected_elements, |
| 100 | + "tensor row storage must contain {expected_elements} elements, got {}", |
| 101 | + elements.len(), |
| 102 | + ); |
| 103 | + |
| 104 | + Ok(TensorRows { |
| 105 | + elements, |
| 106 | + row_count, |
| 107 | + row_width, |
| 108 | + stride, |
| 109 | + }) |
| 110 | +} |
| 111 | + |
| 112 | +// SAFETY: `TensorRows` records the row count validated during decode, and both checked and |
| 113 | +// unchecked access use the same stride and row width. |
| 114 | +unsafe impl<T: Float + NativePType> InputElement for TensorRow<T> { |
| 115 | + type Column = TensorRows<T>; |
| 116 | + type Constant = Buffer<T>; |
| 117 | + type View<'a> = &'a TensorRows<T>; |
| 118 | + type Elem<'a> = &'a [T]; |
| 119 | + |
| 120 | + const DENSE_SAFE: bool = true; |
| 121 | + const DECODE_INFALLIBLE: bool = true; |
| 122 | + |
| 123 | + fn validate(dtype: &DType) -> VortexResult<()> { |
| 124 | + let tensor_match = validate_tensor_float_input(dtype)?; |
| 125 | + let expected_element_ptype = T::PTYPE; |
| 126 | + vortex_ensure_eq!( |
| 127 | + tensor_match.element_ptype(), |
| 128 | + expected_element_ptype, |
| 129 | + "tensor row input must use {expected_element_ptype} elements, got {dtype}", |
| 130 | + ); |
| 131 | + |
| 132 | + Ok(()) |
| 133 | + } |
| 134 | + |
| 135 | + fn decode(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Self::Column> { |
| 136 | + // Batch execution owns the mask and restores it on the result. |
| 137 | + let array = match array.as_opt::<Masked>() { |
| 138 | + Some(masked) => masked.child().clone(), |
| 139 | + None => array, |
| 140 | + }; |
| 141 | + |
| 142 | + let row_count = array.len(); |
| 143 | + let row_width = validate_tensor_float_input(array.dtype())?.list_size() as usize; |
| 144 | + let extension: ExtensionArray = array.execute(ctx)?; |
| 145 | + decode_tensor_storage(extension.storage_array(), row_count, row_width, ctx) |
| 146 | + } |
| 147 | + |
| 148 | + fn decode_constant(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Self::Constant> { |
| 149 | + let row_width = validate_tensor_float_input(array.dtype())?.list_size() as usize; |
| 150 | + let storage = if let Some(constant) = array.as_opt::<Constant>() { |
| 151 | + let scalar = constant.scalar().as_extension().to_storage_scalar(); |
| 152 | + ConstantArray::new(scalar, 1).into_array() |
| 153 | + } else if let Some(extension) = array.as_opt::<Extension>() { |
| 154 | + extension.storage_array().clone() |
| 155 | + } else { |
| 156 | + vortex_bail!( |
| 157 | + "a tensor batch constant must use the Constant encoding or constant extension \ |
| 158 | + storage, got {}", |
| 159 | + array.encoding_id() |
| 160 | + ); |
| 161 | + }; |
| 162 | + |
| 163 | + let decoded = decode_tensor_storage::<T>(&storage, 1, row_width, ctx)?; |
| 164 | + vortex_ensure_eq!( |
| 165 | + decoded.elements.len(), |
| 166 | + row_width, |
| 167 | + "decoded tensor constant must contain {row_width} elements, got {}", |
| 168 | + decoded.elements.len(), |
| 169 | + ); |
| 170 | + |
| 171 | + Ok(decoded.elements) |
| 172 | + } |
| 173 | + |
| 174 | + fn can_decode_null_tolerant(_array: &ArrayRef) -> VortexResult<bool> { |
| 175 | + Ok(true) |
| 176 | + } |
| 177 | + |
| 178 | + fn get(column: &Self::Column, index: usize) -> &[T] { |
| 179 | + let start = index * column.stride; |
| 180 | + &column.elements.as_slice()[start..start + column.row_width] |
| 181 | + } |
| 182 | + |
| 183 | + fn get_constant(constant: &Self::Constant) -> &[T] { |
| 184 | + constant.as_slice() |
| 185 | + } |
| 186 | + |
| 187 | + fn view(column: &Self::Column) -> Self::View<'_> { |
| 188 | + column |
| 189 | + } |
| 190 | + |
| 191 | + fn get_from_view<'a>(view: &Self::View<'a>, index: usize) -> &'a [T] |
| 192 | + where |
| 193 | + Self: 'a, |
| 194 | + { |
| 195 | + Self::get(view, index) |
| 196 | + } |
| 197 | + |
| 198 | + unsafe fn get_from_view_unchecked<'a>(view: &Self::View<'a>, index: usize) -> &'a [T] |
| 199 | + where |
| 200 | + Self: 'a, |
| 201 | + { |
| 202 | + let start = index * view.stride; |
| 203 | + |
| 204 | + // SAFETY: decode established one complete stored row for stride 0, or `row_count` |
| 205 | + // contiguous `row_width`-element rows otherwise. The caller guarantees |
| 206 | + // `index < row_count`. |
| 207 | + unsafe { |
| 208 | + std::slice::from_raw_parts(view.elements.as_slice().as_ptr().add(start), view.row_width) |
| 209 | + } |
| 210 | + } |
| 211 | +} |
0 commit comments