Skip to main content

tvm_ffi/collections/
tensor.rs

1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements.  See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership.  The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License.  You may obtain a copy of the License at
9 *
10 *   http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied.  See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19//! [`Tensor`], an owned n-dimensional array, and [`TensorView`], a borrowed one.
20
21use crate::any::AnyView;
22use crate::collections::shape::Shape;
23use crate::derive::{Object, ObjectRef};
24use crate::dtype::AsDLDataType;
25use crate::dtype::DLDataTypeExt;
26use crate::error::Result;
27use crate::object::{Object, ObjectArc, ObjectCore, ObjectCoreWithExtraItems};
28use tvm_ffi_sys::TVMFFIAny;
29use tvm_ffi_sys::TVMFFITypeIndex as TypeIndex;
30use tvm_ffi_sys::dlpack::{DLDataType, DLDevice, DLDeviceType, DLTensor};
31use tvm_ffi_sys::{TVMFFIEnvTensorAlloc, TVMFFIObjectHandle};
32
33//-----------------------------------------------------
34// NDAllocator Trait
35//-----------------------------------------------------
36/// Allocates the data buffer of a tensor made by [`Tensor::from_nd_alloc`].
37///
38/// # Safety
39/// `alloc_data` must return a pointer aligned to `MIN_ALIGN` and valid for the
40/// prototype's data, `numel() * bits * lanes` bits rounded up to whole bytes
41/// (sub-byte types are packed), and `free_data` must release
42/// exactly what `alloc_data` returned. `free_data` may be called for a tensor
43/// whose `data` is null, when `alloc_data` panicked, and must then do nothing.
44///
45/// `Send + Sync`: the tensor frees its data through the allocator when the
46/// last reference drops, which may be on any thread.
47pub unsafe trait NDAllocator: Send + Sync + 'static {
48    /// The minimum alignment of the allocated data, in bytes.
49    const MIN_ALIGN: usize;
50    /// Allocate the data of a tensor.
51    ///
52    /// # Arguments
53    /// * `prototype` - The tensor to allocate for; its data pointer is still null.
54    ///
55    /// # Returns
56    /// The data pointer, which the tensor stores.
57    ///
58    /// # Safety
59    /// `prototype` must have a valid shape and dtype.
60    unsafe fn alloc_data(&mut self, prototype: &DLTensor) -> *mut core::ffi::c_void;
61
62    /// Free the data of a tensor, when the tensor is dropped.
63    ///
64    /// # Arguments
65    /// * `tensor` - The tensor whose `data` to free.
66    ///
67    /// # Safety
68    /// `tensor.data` must be null or come from `alloc_data` on this allocator
69    /// with the same shape and dtype, and must not be used afterwards.
70    unsafe fn free_data(&mut self, tensor: &DLTensor);
71}
72
73/// Size queries on a `DLTensor`.
74pub trait DLTensorExt {
75    /// The number of elements: the product of the shape, 1 for a scalar.
76    ///
77    /// # Safety
78    /// `shape` points to `ndim` extents, or `ndim` is 0.
79    ///
80    /// # Panics
81    /// If an extent is negative or the product overflows `usize`.
82    unsafe fn numel(&self) -> usize;
83}
84
85impl DLTensorExt for DLTensor {
86    unsafe fn numel(&self) -> usize {
87        // A scalar (`ndim == 0`) has one element and may have a null shape.
88        let shape =
89            unsafe { crate::util::slice_from_nullable_raw_parts(self.shape, self.ndim as usize) };
90        checked_numel(shape).expect("tensor shape has a negative extent or overflows usize")
91    }
92}
93
94/// The product of `shape`; `None` if an extent is negative or it overflows.
95fn checked_numel(shape: &[i64]) -> Option<usize> {
96    shape.iter().try_fold(1usize, |numel, &extent| {
97        numel.checked_mul(usize::try_from(extent).ok()?)
98    })
99}
100
101/// The bytes of `tensor`'s data, with sub-byte types packed as C++
102/// `GetDataSize` does; it fits in `isize`, as an allocation must.
103///
104/// # Safety
105/// As [`DLTensorExt::numel`].
106unsafe fn data_size(tensor: &DLTensor) -> usize {
107    let bits = tensor.dtype.bits as usize * tensor.dtype.lanes as usize;
108    unsafe { tensor.numel() }
109        .checked_mul(bits)
110        .map(|total| total.div_ceil(8))
111        .filter(|&size| size <= isize::MAX as usize)
112        .expect("tensor byte size overflows isize")
113}
114
115//-----------------------------------------------------
116// Tensor
117//-----------------------------------------------------
118/// The object behind a [`Tensor`]: an object header followed by a `DLTensor`.
119#[repr(C)]
120#[derive(Object)]
121#[object(type_key = "ffi.Tensor", unsafe type_index = TypeIndex::kTVMFFITensor)]
122pub struct TensorObj {
123    object: Object,
124    dltensor: DLTensor,
125}
126
127/// A reference-counted n-dimensional array, passed across languages as
128/// `ffi.Tensor` and exchanged with other frameworks through DLPack.
129///
130/// # Examples
131///
132/// ```
133/// use tvm_ffi::Tensor;
134///
135/// let tensor = Tensor::from_slice(&[1.0_f32, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3])?;
136/// assert_eq!(tensor.shape(), &[2, 3]);
137/// assert_eq!(tensor.numel(), 6);
138/// assert_eq!(tensor.data_as_slice::<f32>()?[4], 5.0);
139/// # Ok::<(), tvm_ffi::Error>(())
140/// ```
141#[repr(C)]
142#[derive(ObjectRef, Clone)]
143#[object_ref(skip_deref)]
144pub struct Tensor {
145    data: ObjectArc<TensorObj>,
146}
147
148impl Tensor {
149    /// The data pointer, as in the `DLTensor`; `byte_offset` is not applied.
150    ///
151    /// A tensor is a shared handle, so `&mut self` would not make writes
152    /// exclusive; getting the pointer is safe, and writing through it is the
153    /// caller's `unsafe` responsibility, as for
154    /// [`data_as_slice_mut`](Self::data_as_slice_mut).
155    pub fn data_ptr(&self) -> *mut core::ffi::c_void {
156        self.data.dltensor.data
157    }
158
159    /// Whether the elements are laid out in row-major order without gaps; see
160    /// [`TensorView::is_contiguous`].
161    pub fn is_contiguous(&self) -> bool {
162        TensorView::from(self).is_contiguous()
163    }
164
165    /// The elements as a slice, starting `byte_offset` bytes into the data.
166    ///
167    /// # Errors
168    /// A `TypeError` if `T` is not the tensor's dtype, and a `RuntimeError`
169    /// if the tensor is not on the CPU, not contiguous, or its data is not
170    /// aligned for `T`.
171    pub fn data_as_slice<T: AsDLDataType>(&self) -> Result<&[T]> {
172        let (data, len) = self.cpu_elements::<T>()?;
173        unsafe { Ok(crate::util::slice_from_nullable_raw_parts(data, len)) }
174    }
175    /// The elements as a mutable slice, starting `byte_offset` bytes into the
176    /// data.
177    ///
178    /// It takes `&self`: a tensor is a shared handle, and kernels write the
179    /// data of tensors they receive by shared reference, so `&mut self` would
180    /// not make the write exclusive.
181    ///
182    /// # Errors
183    /// As [`data_as_slice`](Self::data_as_slice).
184    ///
185    /// # Safety
186    ///
187    /// While the returned slice is alive, nothing else may access the data:
188    /// no other slice from this method or [`data_as_slice`](Self::data_as_slice)
189    /// on this tensor or a clone of it, and no kernel or foreign caller writing
190    /// the buffer. Rust cannot check this because the method takes `&self`, as
191    /// `std::slice::from_raw_parts_mut` cannot check it for a raw pointer.
192    #[allow(clippy::wrong_self_convention, clippy::mut_from_ref)]
193    pub unsafe fn data_as_slice_mut<T: AsDLDataType>(&self) -> Result<&mut [T]> {
194        let (data, len) = self.cpu_elements::<T>()?;
195        unsafe { Ok(crate::util::slice_from_nullable_raw_parts_mut(data, len)) }
196    }
197
198    /// The first element and element count, checked for a slice of `T`.
199    fn cpu_elements<T: AsDLDataType>(&self) -> Result<(*mut T, usize)> {
200        let dtype = T::DL_DATA_TYPE;
201        if self.dtype() != dtype {
202            crate::bail!(
203                crate::error::TYPE_ERROR,
204                "Data type mismatch: expected {}, got {}",
205                dtype.to_string(),
206                self.dtype().to_string()
207            );
208        }
209        if self.device().device_type != DLDeviceType::kDLCPU as i32 {
210            crate::bail!(crate::error::RUNTIME_ERROR, "Tensor is not on CPU");
211        }
212        crate::ensure!(
213            self.is_contiguous(),
214            crate::error::RUNTIME_ERROR,
215            "Tensor is not contiguous"
216        );
217        let len = self.numel();
218        let t = &self.data.dltensor;
219        let data = t
220            .data
221            .cast::<u8>()
222            .wrapping_add(t.byte_offset as usize)
223            .cast::<T>();
224        // Imported DLPack data may sit at any address.
225        crate::ensure!(
226            len == 0 || data.is_aligned(),
227            crate::error::RUNTIME_ERROR,
228            "Tensor data is not aligned for {}",
229            dtype.to_string()
230        );
231        Ok((data, len))
232    }
233
234    /// The extent of each dimension.
235    pub fn shape(&self) -> &[i64] {
236        let t = &self.data.dltensor;
237        unsafe { crate::util::slice_from_nullable_raw_parts(t.shape, t.ndim as usize) }
238    }
239
240    /// The number of dimensions.
241    pub fn ndim(&self) -> usize {
242        self.data.dltensor.ndim as usize
243    }
244
245    /// The number of elements.
246    ///
247    /// # Panics
248    /// If an extent is negative or the product overflows `usize`.
249    pub fn numel(&self) -> usize {
250        // SAFETY: a tensor's shape holds `ndim` extents.
251        unsafe { self.data.dltensor.numel() }
252    }
253
254    /// The strides, in elements.
255    ///
256    /// # Panics
257    /// If the tensor has null strides and at least one dimension, as
258    /// [`TensorView::strides`] does.
259    pub fn strides(&self) -> &[i64] {
260        let t = &self.data.dltensor;
261        if t.ndim == 0 {
262            return &[];
263        }
264        assert!(
265            !t.strides.is_null(),
266            "Tensor::strides of a DLTensor with null strides"
267        );
268        unsafe { std::slice::from_raw_parts(t.strides, t.ndim as usize) }
269    }
270
271    /// The element type.
272    pub fn dtype(&self) -> DLDataType {
273        self.data.dltensor.dtype
274    }
275
276    /// The device that holds the data.
277    pub fn device(&self) -> DLDevice {
278        self.data.dltensor.device
279    }
280}
281
282#[repr(C)]
283struct TensorObjFromNDAlloc<TNDAlloc>
284where
285    TNDAlloc: NDAllocator,
286{
287    base_: TensorObj,
288    alloc: TNDAlloc,
289}
290
291unsafe impl<TNDAlloc: NDAllocator> ObjectCore for TensorObjFromNDAlloc<TNDAlloc> {
292    type Parent = TensorObj;
293    const TYPE_KEY: &'static str = TensorObj::TYPE_KEY;
294    const TYPE_DEPTH: i32 = TensorObj::TYPE_DEPTH;
295    fn type_index() -> i32 {
296        TensorObj::type_index()
297    }
298    unsafe fn object_header_mut(this: &mut Self) -> &mut tvm_ffi_sys::TVMFFIObject {
299        unsafe { TensorObj::object_header_mut(&mut this.base_) }
300    }
301}
302
303unsafe impl<TNDAlloc: NDAllocator> ObjectCoreWithExtraItems for TensorObjFromNDAlloc<TNDAlloc> {
304    type ExtraItem = i64;
305    fn extra_items_count(this: &Self) -> usize {
306        (this.base_.dltensor.ndim * 2) as usize
307    }
308}
309
310impl<TNDAlloc: NDAllocator> Drop for TensorObjFromNDAlloc<TNDAlloc> {
311    fn drop(&mut self) {
312        unsafe {
313            self.alloc.free_data(&self.base_.dltensor);
314        }
315    }
316}
317
318impl Tensor {
319    /// Create a contiguous tensor whose data `alloc` allocates and frees.
320    ///
321    /// # Arguments
322    /// * `alloc` - The allocator, kept by the tensor until it is dropped.
323    /// * `shape` - The shape of the tensor.
324    /// * `dtype` - The element type.
325    /// * `device` - The device of the data.
326    ///
327    /// # Returns
328    /// The new tensor, with row-major strides.
329    ///
330    /// # Panics
331    /// If an extent of `shape` is negative or the byte size overflows `isize`.
332    pub fn from_nd_alloc<TNDAlloc>(
333        alloc: TNDAlloc,
334        shape: &[i64],
335        dtype: DLDataType,
336        device: DLDevice,
337    ) -> Self
338    where
339        TNDAlloc: NDAllocator,
340    {
341        let ndim = i32::try_from(shape.len()).expect("tensor ndim exceeds i32");
342        let dltensor = DLTensor {
343            data: std::ptr::null_mut(),
344            device,
345            ndim,
346            dtype,
347            shape: shape.as_ptr() as *mut i64,
348            strides: std::ptr::null_mut(),
349            byte_offset: 0,
350        };
351        // Allocators size the data from the shape, so check it before allocating.
352        // SAFETY: `shape` holds `ndim` extents.
353        unsafe { data_size(&dltensor) };
354        let tensor_obj = TensorObjFromNDAlloc {
355            base_: TensorObj {
356                object: Object::new(),
357                dltensor: DLTensor {
358                    shape: std::ptr::null_mut(),
359                    ..dltensor
360                },
361            },
362            alloc,
363        };
364        unsafe {
365            let mut obj_arc = ObjectArc::new_with_extra_items(tensor_obj);
366            // The fresh allocation is unique and has not been exposed.
367            let object = ObjectArc::as_mut_ptr(&mut obj_arc);
368            let items = TensorObjFromNDAlloc::extra_items_ptr(object);
369            std::ptr::copy_nonoverlapping(shape.as_ptr(), items, shape.len());
370            let strides = items.add(shape.len());
371            Shape::fill_strides_from_shape(
372                shape,
373                std::slice::from_raw_parts_mut(strides, shape.len()),
374            );
375            let object = &mut *object;
376            object.base_.dltensor.shape = items;
377            object.base_.dltensor.strides = strides;
378            let dltensor_ptr = &object.base_.dltensor as *const DLTensor;
379            object.base_.dltensor.data = object.alloc.alloc_data(&*dltensor_ptr);
380            Self {
381                data: ObjectArc::from_raw(ObjectArc::into_raw(obj_arc) as *mut TensorObj),
382            }
383        }
384    }
385    /// Create a contiguous tensor with this thread's environment allocator.
386    ///
387    /// Kernel libraries allocate intermediate tensors this way, so that they
388    /// come from the caller's allocator, such as the one a framework sets
389    /// with `TVMFFIEnvSetDLPackManagedTensorAllocator`.
390    ///
391    /// # Arguments
392    /// * `shape` - The shape of the tensor.
393    /// * `dtype` - The element type.
394    /// * `device` - The device of the data.
395    ///
396    /// # Returns
397    /// The new tensor.
398    ///
399    /// # Errors
400    /// The error the allocator raises, or a `RuntimeError` when no allocator
401    /// is set.
402    pub fn from_env_alloc(shape: &[i64], dtype: DLDataType, device: DLDevice) -> Result<Self> {
403        let ndim = i32::try_from(shape.len()).expect("tensor ndim exceeds i32");
404        let mut prototype = DLTensor {
405            data: std::ptr::null_mut(),
406            device,
407            ndim,
408            dtype,
409            shape: shape.as_ptr() as *mut i64,
410            strides: std::ptr::null_mut(),
411            byte_offset: 0,
412        };
413        let mut out: TVMFFIObjectHandle = std::ptr::null_mut();
414        unsafe {
415            if TVMFFIEnvTensorAlloc(&mut prototype, &mut out) != 0 {
416                return Err(crate::error::Error::from_raised());
417            }
418            Ok(Self {
419                data: ObjectArc::from_raw(out as *const TensorObj),
420            })
421        }
422    }
423
424    /// Create a CPU tensor holding a copy of `slice`.
425    ///
426    /// # Arguments
427    /// * `slice` - The elements, in row-major order.
428    /// * `shape` - The shape of the tensor.
429    ///
430    /// # Returns
431    /// The new tensor, allocated with [`CPUNDAlloc`].
432    ///
433    /// # Errors
434    /// A `ValueError` if `slice` does not have as many elements as `shape`,
435    /// or `shape` has a negative extent.
436    pub fn from_slice<T: AsDLDataType>(slice: &[T], shape: &[i64]) -> Result<Self> {
437        if checked_numel(shape) != Some(slice.len()) {
438            crate::bail!(crate::error::VALUE_ERROR, "Slice length mismatch");
439        }
440        let dtype = T::DL_DATA_TYPE;
441        let device = DLDevice::new(DLDeviceType::kDLCPU, 0);
442        let tensor = Tensor::from_nd_alloc(CPUNDAlloc, shape, dtype, device);
443        // SAFETY: the tensor was just allocated, so nothing else can access it.
444        unsafe { tensor.data_as_slice_mut::<T>()? }.copy_from_slice(slice);
445        Ok(tensor)
446    }
447}
448
449/// An [`NDAllocator`] for CPU memory from the Rust global allocator, aligned
450/// to 64 bytes.
451#[derive(Clone, Copy, Debug, Default)]
452pub struct CPUNDAlloc;
453
454unsafe impl NDAllocator for CPUNDAlloc {
455    const MIN_ALIGN: usize = 64;
456
457    unsafe fn alloc_data(&mut self, prototype: &DLTensor) -> *mut core::ffi::c_void {
458        let size = unsafe { data_size(prototype) };
459        // A zero-size allocation is undefined behavior; an empty tensor gets an
460        // aligned dangling pointer, which `free_data` does not release.
461        if size == 0 {
462            return Self::MIN_ALIGN as *mut core::ffi::c_void;
463        }
464        let layout = std::alloc::Layout::from_size_align(size, Self::MIN_ALIGN).unwrap();
465        let ptr = unsafe { std::alloc::alloc(layout) };
466        if ptr.is_null() {
467            std::alloc::handle_alloc_error(layout);
468        }
469        ptr as *mut core::ffi::c_void
470    }
471
472    unsafe fn free_data(&mut self, tensor: &DLTensor) {
473        let size = unsafe { data_size(tensor) };
474        if size == 0 {
475            return;
476        }
477        let layout = std::alloc::Layout::from_size_align(size, Self::MIN_ALIGN).unwrap();
478        unsafe { std::alloc::dealloc(tensor.data as *mut u8, layout) };
479    }
480}
481
482/// A non-owning view of a tensor: a pointer to a `DLTensor`.
483///
484/// A function argument of this type accepts both a borrowed `DLTensor*` (type
485/// index `kTVMFFIDLTensorPtr`, how C callers pass tensors) and a `Tensor`
486/// object (type index `kTVMFFITensor`), and is passed on as a `DLTensor*`.
487/// Prefer it over [`Tensor`] for arguments of exported functions that only
488/// read a tensor's metadata and data.
489///
490/// The view does not keep anything alive: its lifetime `'a` ties it to what
491/// it borrows. For the same reason, a view cannot be moved into an owned
492/// [`Any`](crate::Any), which could outlive it; use [`Tensor`] instead.
493/// Neither misuse compiles:
494///
495/// ```compile_fail,E0597
496/// use tvm_ffi::{Tensor, TensorView};
497/// let view = {
498///     let tensor = Tensor::from_slice(&[1.0_f32], &[1]).unwrap();
499///     TensorView::from(&tensor)
500/// };
501/// view.ndim();
502/// ```
503///
504/// ```compile_fail,E0277
505/// use tvm_ffi::{Any, Tensor, TensorView};
506/// let tensor = Tensor::from_slice(&[1.0_f32], &[1]).unwrap();
507/// let _ = Any::from(TensorView::from(&tensor));
508/// ```
509///
510/// A view received as an argument of an exported function is valid only
511/// during the call. The function may name any lifetime for it,
512/// `TensorView<'static>` included, so the compiler does not stop it from
513/// being kept past the call; doing so is undefined behavior.
514#[derive(Clone, Copy, Debug)]
515pub struct TensorView<'a> {
516    tensor: *const DLTensor,
517    _borrow: std::marker::PhantomData<&'a DLTensor>,
518}
519
520impl<'a> TensorView<'a> {
521    /// Creates a view of a `DLTensor`.
522    ///
523    /// # Safety
524    /// `tensor` must be non-null and valid for every use of the view.
525    pub unsafe fn from_raw(tensor: *const DLTensor) -> Self {
526        assert!(!tensor.is_null(), "TensorView of a null DLTensor");
527        Self {
528            tensor,
529            _borrow: std::marker::PhantomData,
530        }
531    }
532
533    /// The viewed `DLTensor`.
534    pub fn as_raw(&self) -> *const DLTensor {
535        self.tensor
536    }
537
538    fn dltensor(&self) -> &'a DLTensor {
539        // SAFETY: the view borrows a live `DLTensor` for `'a`.
540        unsafe { &*self.tensor }
541    }
542
543    /// The data pointer, as in the `DLTensor`; `byte_offset` is not applied.
544    pub fn data_ptr(&self) -> *mut core::ffi::c_void {
545        self.dltensor().data
546    }
547
548    /// The device that holds the data.
549    pub fn device(&self) -> DLDevice {
550        self.dltensor().device
551    }
552
553    /// The element type.
554    pub fn dtype(&self) -> DLDataType {
555        self.dltensor().dtype
556    }
557
558    /// The number of dimensions.
559    pub fn ndim(&self) -> usize {
560        self.dltensor().ndim as usize
561    }
562
563    /// The extent of each dimension.
564    pub fn shape(&self) -> &'a [i64] {
565        let t = self.dltensor();
566        unsafe { crate::util::slice_from_nullable_raw_parts(t.shape, t.ndim as usize) }
567    }
568
569    /// The number of elements.
570    ///
571    /// # Panics
572    /// If an extent is negative or the product overflows `usize`.
573    pub fn numel(&self) -> usize {
574        // SAFETY: a tensor's shape holds `ndim` extents.
575        unsafe { self.dltensor().numel() }
576    }
577
578    /// The strides, in elements.
579    ///
580    /// # Panics
581    /// If the `DLTensor` has null strides and at least one dimension, which
582    /// DLPack forbids since v1.2.
583    pub fn strides(&self) -> &'a [i64] {
584        let t = self.dltensor();
585        if t.ndim == 0 {
586            return &[];
587        }
588        assert!(
589            !t.strides.is_null(),
590            "TensorView::strides of a DLTensor with null strides"
591        );
592        unsafe { std::slice::from_raw_parts(t.strides, t.ndim as usize) }
593    }
594
595    /// Whether the elements are laid out in row-major order without gaps: a
596    /// `DLTensor` with null strides or no elements is contiguous, and a
597    /// dimension of extent 1 may have any stride.
598    pub fn is_contiguous(&self) -> bool {
599        if self.dltensor().strides.is_null() {
600            return true;
601        }
602        let shape = self.shape();
603        if shape.contains(&0) {
604            return true;
605        }
606        let mut expected_stride = 1;
607        for (size, stride) in shape.iter().zip(self.strides()).rev() {
608            if *size == 1 {
609                continue;
610            }
611            if *stride != expected_stride {
612                return false;
613            }
614            expected_stride *= size;
615        }
616        true
617    }
618}
619
620impl<'a> From<&'a Tensor> for TensorView<'a> {
621    fn from(tensor: &'a Tensor) -> Self {
622        Self {
623            tensor: &tensor.data.dltensor as *const DLTensor,
624            _borrow: std::marker::PhantomData,
625        }
626    }
627}
628
629impl<'a> TensorView<'a> {
630    /// The view of `value`'s cell, when it holds a `DLTensor*` or a tensor object.
631    fn from_cell(value: &TVMFFIAny) -> Option<Self> {
632        let tensor = if value.type_index == TypeIndex::kTVMFFIDLTensorPtr as i32 {
633            unsafe { value.data_union.v_ptr as *const DLTensor }
634        } else if value.type_index == TypeIndex::kTVMFFITensor as i32 {
635            // A tensor object's DLTensor follows its object header.
636            unsafe { &(*(value.data_union.v_obj as *const TensorObj)).dltensor as *const DLTensor }
637        } else {
638            return None;
639        };
640        Some(Self {
641            tensor,
642            _borrow: std::marker::PhantomData,
643        })
644    }
645
646    /// The `TypeError` for a value that is not a tensor.
647    fn mismatch(value: &TVMFFIAny, context: &str) -> crate::error::Error {
648        let message = format!(
649            "{context}Cannot convert from type `{}` to `DLTensor*`",
650            crate::object::type_key_of_index(value.type_index)
651        );
652        crate::error::Error::new(crate::error::TYPE_ERROR, &message)
653    }
654}
655
656// A view is not `AnyCompatible`: that trait builds values from a cell without
657// a lifetime, so a view could outlive what it borrows, and a view cannot be
658// held in an owned `Any` (C++ `TypeTraits<DLTensor*>::MoveToAny` throws). It
659// instead converts from an `AnyView` with that view's lifetime, is a typed
660// function argument, and passes as a `DLTensor*` argument.
661
662// As C++ `AnyView::cast<TensorView>`: from a `DLTensor*` or a tensor object.
663impl<'a> TryFrom<AnyView<'a>> for TensorView<'a> {
664    type Error = crate::error::Error;
665    #[inline]
666    fn try_from(value: AnyView<'a>) -> Result<Self> {
667        let cell = value.as_raw_ffi_any();
668        Self::from_cell(cell).ok_or_else(|| Self::mismatch(cell, ""))
669    }
670}
671
672// A typed function argument, valid only during the call; the lifetime is not
673// checked against it (see the type docs).
674impl crate::type_traits::TypeSchema for TensorView<'_> {
675    fn type_schema() -> String {
676        crate::type_traits::type_schema("DLTensor*", &[])
677    }
678}
679
680impl crate::any::ArgTryFromAnyView for TensorView<'_> {
681    fn try_from_any_view(value: &AnyView, arg_index: usize) -> Result<Self> {
682        let cell = value.as_raw_ffi_any();
683        Self::from_cell(cell)
684            .ok_or_else(|| Self::mismatch(cell, &format!("Argument #{arg_index}: ")))
685    }
686}
687
688// A view of the `DLTensor*`, for `call_packed` and other `AnyView` APIs.
689impl<'a> From<&TensorView<'a>> for AnyView<'a> {
690    fn from(view: &TensorView<'a>) -> Self {
691        let mut cell = TVMFFIAny::new();
692        cell.type_index = TypeIndex::kTVMFFIDLTensorPtr as i32;
693        cell.data_union.v_ptr = view.tensor as *mut core::ffi::c_void;
694        // SAFETY: the view keeps its `DLTensor` alive for `'a`.
695        unsafe { AnyView::from_raw_ffi_any(cell) }
696    }
697}
698
699// Passed to a function as a `DLTensor*`.
700impl<'a> crate::function_internal::PackedCallArg for TensorView<'a> {
701    type Holder = Self;
702    #[inline(always)]
703    fn into_packed_arg(self) -> Self {
704        self
705    }
706    #[inline(always)]
707    fn as_packed_arg(holder: &Self::Holder) -> AnyView<'_> {
708        AnyView::from(holder)
709    }
710}
711
712impl<'a, 'b> crate::function_internal::PackedCallArg for &'b TensorView<'a> {
713    type Holder = Self;
714    #[inline(always)]
715    fn into_packed_arg(self) -> Self {
716        self
717    }
718    #[inline(always)]
719    fn as_packed_arg(holder: &Self::Holder) -> AnyView<'_> {
720        AnyView::from(*holder)
721    }
722}