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}