Skip to main content

tvm_ffi/
type_traits.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//! Traits that map Rust types to TVM-FFI values.
20
21use crate::any::{Any, AnyView};
22use std::borrow::Borrow;
23use tvm_ffi_sys::TVMFFITypeIndex as TypeIndex;
24use tvm_ffi_sys::{TVMFFIAny, TVMFFIGetTypeInfo, TVMFFIObject};
25
26/// A type whose values an FFI cell can hold: how a value is stored in a
27/// `TVMFFIAny` and read back.
28///
29/// [`AnyView`] and [`TensorView`](crate::TensorView) borrow their value, so
30/// they are not. Containers and generic code bound on [`ContainerElement`] to
31/// also accept [`Any`].
32///
33/// # Implementing
34///
35/// Object references derive it with `#[derive(ObjectRef)]`. Any other type
36/// implements it by hand, then calls
37/// [`impl_any_compatible_conversions!`](crate::impl_any_compatible_conversions),
38/// which adds its `From`, `TryFrom` and argument conversions. Coherence keeps
39/// those out of this trait, so without the macro the type is stored but not
40/// converted.
41///
42/// # Safety
43/// - A value is written in the cell layout of its type index, and read back from it.
44/// - Every `*_after_check` method is sound on each cell that `check_any_strict` accepts.
45/// - `is_undefined` is false for every value. It is true for all-zero bytes,
46///   unless those bytes are a value whose drop does nothing.
47pub unsafe trait AnyCompatible: Sized {
48    /// Whether the `AnyView -> Self` conversion matches one exact leaf type.
49    ///
50    /// If this is `true`, [`Self::match_any_exact_type_index`] must always
51    /// return the same index for the process lifetime, and conversion from an
52    /// object-backed `AnyView` must succeed if and only if its runtime type
53    /// index equals that index. Matching must not depend on any other part of
54    /// the value. `match_any!` may use this contract to skip conversions for
55    /// all other arms.
56    #[doc(hidden)]
57    const MATCH_ANY_EXACT: bool = false;
58
59    /// Return the sole runtime object type index accepted by this conversion.
60    #[doc(hidden)]
61    fn match_any_exact_type_index() -> i32 {
62        unreachable!("MATCH_ANY_EXACT is false")
63    }
64
65    /// Whether `field`, which holds a value of this type or all-zero bytes,
66    /// holds all-zero bytes that are no value of this type, as a null object
67    /// reference, a string of type index None or a zero device type: a field
68    /// that a creator left undefined for reflection to set. An undefined field
69    /// is no value; a nullable reference is `Option<T>`, whose `None` is a
70    /// defined value.
71    ///
72    /// The field setter writes an undefined field without dropping it, the
73    /// field getter reads it as None, and the object's deleter skips it. The default,
74    /// false, fits a type whose all-zero bytes are a value whose drop does
75    /// nothing, as a scalar's, `Any`'s or `Optional`'s.
76    ///
77    /// # Safety
78    ///
79    /// `field` points to a value of this type or to all-zero bytes. An
80    /// implementation reads only bytes that each value initializes and, when
81    /// `Option<Self>` is niche-optimized, that its `None` initializes too.
82    #[inline]
83    unsafe fn is_undefined(field: *const Self) -> bool {
84        let _ = field;
85        false
86    }
87
88    /// Whether a reflected field of this type is laid out as readers of its
89    /// static type index expect: an `Optional` field as a nullable object
90    /// pointer or a `TVMFFIAny` cell.
91    #[doc(hidden)]
92    fn has_field_layout() -> bool {
93        true
94    }
95
96    /// Write a cell that borrows `src` into `data`.
97    ///
98    /// # Safety
99    /// The written cell borrows `src` without a reference and must not be used
100    /// after `src` is dropped.
101    unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny);
102    /// Write a cell that owns `src` into `data`.
103    ///
104    /// # Safety
105    /// The previous content of `data` is overwritten without release; the
106    /// caller owns the written cell and must release it exactly once.
107    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny);
108    /// Whether `data` holds a `Self` as is, without conversion.
109    ///
110    /// # Safety
111    /// `data` must be a valid `TVMFFIAny` cell.
112    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool;
113
114    /// Additional value-preservation checks used only by `match_any!` and
115    /// dispatch handlers, after `check_any_strict` succeeds. Ordinary conversion
116    /// APIs are unchanged.
117    ///
118    /// # Safety
119    /// `data` must have passed `Self::check_any_strict`.
120    #[doc(hidden)]
121    unsafe fn match_constraints(_data: &TVMFFIAny) -> bool {
122        true
123    }
124
125    /// Copy a `Self` out of a cell that holds one, retaining any object.
126    ///
127    /// # Safety
128    /// `data` must have passed `Self::check_any_strict`.
129    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self;
130    /// Move a `Self` out of an owning cell that holds one.
131    ///
132    /// # Safety
133    /// `data` must have passed `Self::check_any_strict`. Its ownership moves
134    /// into the result, so the caller must not release `data` again.
135    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self;
136    /// Convert `data` into a `Self` by the FFI rules, such as an integer into a
137    /// float; `Err` if it does not convert.
138    ///
139    /// # Safety
140    /// `data` must be a valid `TVMFFIAny` cell.
141    #[allow(clippy::result_unit_err)]
142    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()>;
143    /// The name of the mismatched value `data` in conversion errors; by
144    /// default its runtime type key.
145    fn get_mismatch_type_info(data: &TVMFFIAny) -> String {
146        runtime_type_key(data.type_index)
147    }
148    /// The type name in conversion errors and type schemas, such as `int`,
149    /// `ffi.String` or `Array<int>`.
150    fn type_str() -> String;
151
152    /// The type schema of the type: the JSON object that describes it, which
153    /// the type schemas of functions and fields embed.
154    ///
155    /// The default, `{"type":"<type_str>"}`, fits a type whose type string is
156    /// its type key, as for object references.
157    fn type_schema() -> String {
158        type_schema(&Self::type_str(), &[])
159    }
160
161    /// Borrow `self` into an owned [`Any`], increfing object-backed values.
162    ///
163    /// The by-reference counterpart of `Any::from(value)`, for fields reached
164    /// through a `Deref` into shared object storage. `impl From<&T> for Any`
165    /// cannot be added instead: `&` is fundamental, so a downstream crate may
166    /// implement `AnyCompatible` for its own `&T` and the two impls overlap
167    /// (E0119).
168    #[inline]
169    fn to_any(&self) -> Any {
170        AnyView::from(self).into()
171    }
172}
173
174/// A value an FFI container such as [`Array`](crate::Array) holds: every
175/// [`AnyCompatible`] type, and [`Any`].
176///
177/// Sealed: implement [`AnyCompatible`] to make a type an element.
178pub trait ContainerElement: container_element_ops::Ops {}
179
180impl<T: AnyCompatible> ContainerElement for T {}
181impl ContainerElement for Any {}
182
183/// `Self` subsumes `Source`: every `Source` value, as stored, is a valid
184/// `Self`, a compile-time fact checked by no code, as C++
185/// `type_subsumes_v<Self, Source>`. So a container of `Source` is a container
186/// of `Self` without a copy, as [`Array::upcast`](crate::Array::upcast) and
187/// [`Map::upcast`](crate::Map::upcast) use.
188///
189/// It holds for every type and itself, and for a base object reference and
190/// each derived one, which [`impl_object_ref_upcast!`](crate::impl_object_ref_upcast)
191/// declares.
192///
193/// # Safety
194///
195/// Every cell that `Source` strictly accepts, `Self` strictly accepts, also
196/// after a change made through `Self`.
197pub unsafe trait TypeSubsumes<Source: ?Sized> {}
198
199unsafe impl<T: ?Sized> TypeSubsumes<T> for T {}
200
201/// A `T`, a `&T` or a subtype of `T`, taken where a `T` is expected; a `&str`
202/// or `&[u8]` converts into a `String` or `Bytes`.
203///
204/// [`into_arg`](Self::into_arg) returns a `T` or a `&T` without changing a
205/// reference count, but those two conversions allocate;
206/// [`into_owned`](Self::into_owned) moves an owned value and clones only a
207/// borrowed one, as [`Cow::into_owned`](std::borrow::Cow::into_owned).
208pub trait IntoArg<T> {
209    /// `T` when owned, `&T` when borrowed.
210    type Output: Borrow<T>;
211
212    /// Convert into a `T` or a `&T`.
213    fn into_arg(self) -> Self::Output;
214
215    /// Convert into an owned `T`, cloning only a borrowed value.
216    fn into_owned(self) -> T;
217}
218
219impl IntoArg<crate::String> for &str {
220    type Output = crate::String;
221    #[inline]
222    fn into_arg(self) -> crate::String {
223        crate::String::from(self)
224    }
225    #[inline]
226    fn into_owned(self) -> crate::String {
227        crate::String::from(self)
228    }
229}
230
231impl IntoArg<crate::string::Bytes> for &[u8] {
232    type Output = crate::string::Bytes;
233    #[inline]
234    fn into_arg(self) -> crate::string::Bytes {
235        crate::string::Bytes::from(self)
236    }
237    #[inline]
238    fn into_owned(self) -> crate::string::Bytes {
239        crate::string::Bytes::from(self)
240    }
241}
242
243/// A type whose value an FFI cell stores in place, so `&Self` borrows from the
244/// cell, as [`Array`](crate::Array) indexing does.
245///
246/// A reference type implemented by hand gets it from
247/// [`impl_object_ref_downcast_ref!`](crate::impl_object_ref_downcast_ref).
248///
249/// # Safety
250///
251/// For a cell that `Self` strictly accepts, `ref_from_any_unchecked` must
252/// return a reference into that cell that is a valid `Self` for as long as the
253/// cell is borrowed.
254#[doc(hidden)]
255pub unsafe trait RefFromAnyUnchecked: ContainerElement {
256    /// Borrow the value stored in `cell`.
257    ///
258    /// # Safety
259    ///
260    /// `cell` must hold a `Self`.
261    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self;
262}
263
264// The whole cell is the value.
265unsafe impl RefFromAnyUnchecked for Any {
266    #[inline(always)]
267    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
268        unsafe { &*(cell as *const TVMFFIAny as *const Any) }
269    }
270}
271
272// A `BigInt` is one cell, holding an inline `i64` or a `BigInt` object.
273unsafe impl RefFromAnyUnchecked for crate::big_int::BigInt {
274    #[inline(always)]
275    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
276        const {
277            assert!(
278                std::mem::size_of::<crate::big_int::BigInt>() == std::mem::size_of::<TVMFFIAny>()
279            );
280            assert!(
281                std::mem::align_of::<crate::big_int::BigInt>() == std::mem::align_of::<TVMFFIAny>()
282            );
283        };
284        unsafe { &*(cell as *const TVMFFIAny as *const crate::big_int::BigInt) }
285    }
286}
287
288unsafe impl RefFromAnyUnchecked for crate::String {
289    #[inline(always)]
290    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
291        unsafe { &*(cell as *const TVMFFIAny as *const crate::String) }
292    }
293}
294
295unsafe impl RefFromAnyUnchecked for crate::string::Bytes {
296    #[inline(always)]
297    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
298        unsafe { &*(cell as *const TVMFFIAny as *const crate::string::Bytes) }
299    }
300}
301
302// The payload word holds the value in its own representation.
303unsafe impl RefFromAnyUnchecked for i64 {
304    #[inline(always)]
305    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
306        unsafe { &cell.data_union.v_int64 }
307    }
308}
309
310unsafe impl RefFromAnyUnchecked for f64 {
311    #[inline(always)]
312    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
313        unsafe { &cell.data_union.v_float64 }
314    }
315}
316
317unsafe impl RefFromAnyUnchecked for tvm_ffi_sys::dlpack::DLDataType {
318    #[inline(always)]
319    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
320        unsafe { &cell.data_union.v_dtype }
321    }
322}
323
324unsafe impl RefFromAnyUnchecked for tvm_ffi_sys::dlpack::DLDevice {
325    #[inline(always)]
326    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
327        unsafe { &cell.data_union.v_device }
328    }
329}
330
331// An optional object reference is one nullable object pointer (`None` is null,
332// as `OptionalCompatible` relies on), which is the payload word of a `None` or
333// object cell, so `&Option<T>` borrows that word.
334unsafe impl<T: crate::object::ObjectRefCore> RefFromAnyUnchecked for Option<T> {
335    #[inline(always)]
336    unsafe fn ref_from_any_unchecked(cell: &TVMFFIAny) -> &Self {
337        const {
338            assert!(std::mem::size_of::<Option<T>>() == std::mem::size_of::<*mut TVMFFIObject>());
339            assert!(std::mem::align_of::<Option<T>>() == std::mem::align_of::<*mut TVMFFIObject>());
340        };
341        if cell.type_index == TypeIndex::kTVMFFINone as i32 {
342            // A `None` cell's payload is zero by convention (C++ `Any()`), but
343            // do not rely on a producer for it.
344            return &None;
345        }
346        unsafe { &*(&cell.data_union.v_obj as *const *mut TVMFFIObject as *const Option<T>) }
347    }
348}
349
350/// A type that [`Any::downcast_ref`] and [`AnyView::downcast_ref`] borrow from
351/// an FFI cell in place, without a reference count change: object types
352/// (`ArrayObj`), managed references (`Array<T>`, `String`, any
353/// [`#[derive(ObjectRef)]`](crate::derive::ObjectRef) type), `Option` of a
354/// reference and scalars such as `i64`.
355///
356/// Name it to bound a generic borrow, as in `fn get<T: DowncastRefFromAny>`.
357/// Object types, derived references and containers implement it, not code by
358/// hand: a reference with a hand-written `ObjectRefCore` calls
359/// [`impl_object_ref_downcast_ref!`](crate::impl_object_ref_downcast_ref).
360///
361/// # Safety
362///
363/// `downcast_ref_from_any` must return `Some` only when `cell` holds a `Self`, with
364/// a reference that stays valid while `cell` is borrowed.
365pub unsafe trait DowncastRefFromAny {
366    /// Borrow `cell` as `Self` when it holds one.
367    ///
368    /// # Safety
369    ///
370    /// `cell` must be a valid FFI cell.
371    unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self>;
372}
373
374// An object type borrows the object the cell points to.
375unsafe impl<T: crate::object::ObjectCore> DowncastRefFromAny for T {
376    #[inline(always)]
377    unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self> {
378        if cell.type_index < TypeIndex::kTVMFFIStaticObjectBegin as i32
379            || !crate::object::is_instance_of::<T>(cell.type_index)
380        {
381            return None;
382        }
383        // SAFETY: the type check establishes T's layout, and the cell keeps the
384        // object alive while it is borrowed.
385        Some(unsafe { &*cell.data_union.v_obj.cast::<T>() })
386    }
387}
388
389/// Borrow `cell` as a [`RefFromAnyUnchecked`] type when it strictly holds one:
390/// the [`DowncastRefFromAny`] of such a type.
391///
392/// # Safety
393///
394/// `cell` must be a valid FFI cell.
395#[doc(hidden)]
396#[inline(always)]
397pub unsafe fn downcast_ref_from_any_in_place<T: RefFromAnyUnchecked>(
398    cell: &TVMFFIAny,
399) -> Option<&T> {
400    if unsafe { T::container_check_any_strict(cell) } {
401        Some(unsafe { T::ref_from_any_unchecked(cell) })
402    } else {
403        None
404    }
405}
406
407unsafe impl<T: crate::object::ObjectRefCore> DowncastRefFromAny for Option<T> {
408    #[inline(always)]
409    unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self> {
410        unsafe { downcast_ref_from_any_in_place::<Self>(cell) }
411    }
412}
413
414macro_rules! impl_downcast_ref_from_any {
415    ($($t:ty),* $(,)?) => {
416        $(unsafe impl DowncastRefFromAny for $t {
417            #[inline(always)]
418            unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self> {
419                unsafe { downcast_ref_from_any_in_place::<Self>(cell) }
420            }
421        })*
422    };
423}
424
425// An `&Any` must own what it points at, as an `Any` does: a view's cell may
426// instead borrow a C string, byte array, `DLTensor` or rvalue slot, whose
427// `&Any` would clone into an owner of a borrowed resource. Those are refused;
428// an `Any` or container cell never holds them.
429unsafe impl DowncastRefFromAny for Any {
430    #[inline(always)]
431    unsafe fn downcast_ref_from_any(cell: &TVMFFIAny) -> Option<&Self> {
432        let index = cell.type_index;
433        let borrowed = index == TypeIndex::kTVMFFIRawStr as i32
434            || index == TypeIndex::kTVMFFIByteArrayPtr as i32
435            || index == TypeIndex::kTVMFFIDLTensorPtr as i32
436            || index == TypeIndex::kTVMFFIObjectRValueRef as i32;
437        if borrowed {
438            None
439        } else {
440            Some(unsafe { Any::ref_from_any_unchecked(cell) })
441        }
442    }
443}
444
445impl_downcast_ref_from_any!(
446    crate::String,
447    crate::string::Bytes,
448    i64,
449    f64,
450    crate::big_int::BigInt,
451    tvm_ffi_sys::dlpack::DLDataType,
452    tvm_ffi_sys::dlpack::DLDevice,
453);
454
455/// A type that an object reference's [`ObjectRefCore::downcast_ref`] borrows
456/// from the reference's object pointer: object types (`ArrayObj`), and managed
457/// references that are exactly one object pointer (`Array<T>`, every
458/// `#[derive(ObjectRef)]` type). Object types, derived references and
459/// containers implement it, not code by hand.
460///
461/// [`ObjectRefCore::downcast_ref`]: crate::object::ObjectRefCore::downcast_ref
462///
463/// # Safety
464///
465/// `Self` must be an object type or exactly one pointer to a live object.
466/// `downcast_ref_from_object` must return `Some` only when the object at
467/// `*place` is a `Self`, with a reference that stays valid while `place` is
468/// borrowed.
469#[doc(hidden)]
470pub unsafe trait DowncastRefFromObject {
471    /// Borrow the object at `*place` as `Self` when it is one.
472    ///
473    /// # Safety
474    ///
475    /// `place` must hold a pointer to a live object.
476    unsafe fn downcast_ref_from_object(place: &*mut TVMFFIObject) -> Option<&Self>;
477
478    /// The object that `self` is or refers to.
479    #[inline(always)]
480    fn as_object(&self) -> &crate::object::Object {
481        // SAFETY: a reference type is one pointer to a live object (trait contract).
482        unsafe { &**std::ptr::from_ref(self).cast::<*const crate::object::Object>() }
483    }
484}
485
486// An object type borrows the object itself.
487unsafe impl<T: crate::object::ObjectCore> DowncastRefFromObject for T {
488    #[inline(always)]
489    fn as_object(&self) -> &crate::object::Object {
490        // SAFETY: an object type starts with its object header.
491        unsafe { &*std::ptr::from_ref(self).cast::<crate::object::Object>() }
492    }
493
494    #[inline(always)]
495    unsafe fn downcast_ref_from_object(place: &*mut TVMFFIObject) -> Option<&Self> {
496        let object = *place;
497        if unsafe { !crate::object::is_instance_of::<T>((*object).type_index) } {
498            return None;
499        }
500        // SAFETY: the type check establishes T's layout.
501        Some(unsafe { &*object.cast::<T>() })
502    }
503}
504
505/// Borrow the object pointer at `place` as the one-pointer reference type `T`
506/// when the object strictly is a `T`: the [`DowncastRefFromObject`] of such a
507/// type.
508///
509/// # Safety
510///
511/// `place` must hold a pointer to a live object, and `T` must be exactly one
512/// object pointer.
513#[doc(hidden)]
514#[inline(always)]
515pub unsafe fn downcast_ref_from_object_in_place<T: RefFromAnyUnchecked>(
516    place: &*mut TVMFFIObject,
517) -> Option<&T> {
518    const {
519        assert!(
520            std::mem::size_of::<T>() == std::mem::size_of::<*mut TVMFFIObject>(),
521            "a reference downcast target must be exactly one object pointer"
522        )
523    };
524    let object = *place;
525    // An object header always carries an object-range type index.
526    unsafe {
527        core::hint::assert_unchecked(
528            (*object).type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32,
529        )
530    };
531    let mut cell = TVMFFIAny::new();
532    cell.type_index = unsafe { (*object).type_index };
533    cell.data_union.v_obj = object;
534    if unsafe { T::container_check_any_strict(&cell) } {
535        // SAFETY: `T` is exactly one object pointer, and the check shows the
536        // object satisfies `T`.
537        Some(unsafe { &*(place as *const *mut TVMFFIObject as *const T) })
538    } else {
539        None
540    }
541}
542
543//-----------------------------------------------------
544// AnyCompatible impls
545//-----------------------------------------------------
546unsafe impl AnyCompatible for bool {
547    unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
548        data.type_index = TypeIndex::kTVMFFIBool as i32;
549        data.small_str_len = 0;
550        data.data_union.v_int64 = *src as i64;
551    }
552    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
553        data.type_index == TypeIndex::kTVMFFIBool as i32
554    }
555
556    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
557        unsafe { data.data_union.v_int64 != 0 }
558    }
559
560    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
561        data.type_index = TypeIndex::kTVMFFIBool as i32;
562        data.small_str_len = 0;
563        data.data_union.v_int64 = src as i64;
564    }
565
566    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
567        unsafe { data.data_union.v_int64 != 0 }
568    }
569
570    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
571        if data.type_index == TypeIndex::kTVMFFIBool as i32
572            || data.type_index == TypeIndex::kTVMFFIInt as i32
573        {
574            unsafe { Ok(data.data_union.v_int64 != 0) }
575        } else {
576            Err(())
577        }
578    }
579
580    fn type_str() -> String {
581        "bool".to_string()
582    }
583}
584
585macro_rules! impl_any_compatible_for_int {
586    ($($int_type:ty),* $(,)?) => {
587        $(
588            unsafe impl AnyCompatible for $int_type {
589                fn type_str() -> String {
590                    "int".to_string()
591                }
592
593                unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
594                    data.type_index = TypeIndex::kTVMFFIInt as i32;
595                    data.small_str_len = 0;
596                    data.data_union.v_int64 = *src as i64;
597                }
598
599                unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
600                    data.type_index == TypeIndex::kTVMFFIInt as i32
601                }
602
603                unsafe fn match_constraints(data: &TVMFFIAny) -> bool {
604                    <$int_type>::try_from(unsafe { data.data_union.v_int64 }).is_ok()
605                }
606
607                unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
608                    unsafe { data.data_union.v_int64 as $int_type }
609                }
610
611                unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
612                    data.type_index = TypeIndex::kTVMFFIInt as i32;
613                    data.small_str_len = 0;
614                    data.data_union.v_int64 = src as i64;
615                }
616
617                unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
618                    unsafe { data.data_union.v_int64 as $int_type }
619                }
620
621                unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
622                    if data.type_index == TypeIndex::kTVMFFIInt as i32 ||
623                       data.type_index == TypeIndex::kTVMFFIBool as i32 {
624                        Ok(unsafe { data.data_union.v_int64 } as $int_type)
625                    } else {
626                        Err(())
627                    }
628                }
629            }
630        )*
631    };
632}
633
634// Implement AnyCompatible for all integer types
635impl_any_compatible_for_int!(i8, i16, i32, i64, isize, u8, u16, u32, u64, usize);
636
637macro_rules! impl_any_compatible_for_float {
638    ($($float_type:ty),* $(,)?) => {
639        $(
640            unsafe impl AnyCompatible for $float_type {
641                fn type_str() -> String {
642                    "float".to_string()
643                }
644
645                unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
646                    data.type_index = TypeIndex::kTVMFFIFloat as i32;
647                    data.small_str_len = 0;
648                    data.data_union.v_float64 = *src as f64;
649                }
650
651                unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
652                    data.type_index == TypeIndex::kTVMFFIFloat as i32
653                }
654
655                unsafe fn match_constraints(data: &TVMFFIAny) -> bool {
656                    let value = unsafe { data.data_union.v_float64 };
657                    ((value as $float_type) as f64).to_bits() == value.to_bits()
658                }
659
660                unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
661                    unsafe { data.data_union.v_float64 as $float_type }
662                }
663
664                unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
665                    data.type_index = TypeIndex::kTVMFFIFloat as i32;
666                    data.small_str_len = 0;
667                    data.data_union.v_float64 = src as f64;
668                }
669
670                unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
671                    unsafe { data.data_union.v_float64 as $float_type }
672                }
673
674                unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
675                    if data.type_index == TypeIndex::kTVMFFIFloat as i32 {
676                        Ok(unsafe { data.data_union.v_float64 } as $float_type)
677                    } else if data.type_index == TypeIndex::kTVMFFIInt as i32 ||
678                       data.type_index == TypeIndex::kTVMFFIBool as i32 {
679                        Ok(unsafe { data.data_union.v_int64 } as $float_type)
680                    } else {
681                        Err(())
682                    }
683                }
684            }
685        )*
686    };
687}
688
689// Implement AnyCompatible for all float types
690impl_any_compatible_for_float!(f32, f64);
691
692// Implement AnyCompatible for `Option<T>`
693unsafe impl<T: AnyCompatible> AnyCompatible for Option<T> {
694    fn type_str() -> String {
695        // make it consistent with c++ representation
696        "Optional<".to_string() + T::type_str().as_str() + ">"
697    }
698
699    fn type_schema() -> String {
700        type_schema("Optional", &[<T as AnyCompatible>::type_schema()])
701    }
702
703    fn has_field_layout() -> bool {
704        // Only an `Option` of an object reference is the nullable pointer.
705        crate::reflection::field_static_type_index(&T::type_str())
706            >= TypeIndex::kTVMFFIStaticObjectBegin as i32
707    }
708
709    unsafe fn is_undefined(field: *const Self) -> bool {
710        // With a tag, all-zero bytes are `None`. A niche-optimized `Option<T>`
711        // keeps `T`'s bytes, where all-zero bytes are `None` if `None` looks
712        // undefined to `T` (a reference's null pointer), and undefined if
713        // `None` sits elsewhere in the niche.
714        if std::mem::size_of::<Self>() != std::mem::size_of::<T>() {
715            return false;
716        }
717        let none = std::mem::MaybeUninit::new(None::<T>);
718        unsafe { T::is_undefined(field.cast::<T>()) && !T::is_undefined(none.as_ptr().cast::<T>()) }
719    }
720
721    unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
722        if let Some(value) = src {
723            unsafe { T::copy_to_any_view(value, data) };
724        } else {
725            data.type_index = TypeIndex::kTVMFFINone as i32;
726            data.small_str_len = 0;
727            data.data_union.v_int64 = 0;
728        }
729    }
730
731    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
732        if let Some(value) = src {
733            unsafe { T::move_to_any(value, data) };
734        } else {
735            data.type_index = TypeIndex::kTVMFFINone as i32;
736            data.small_str_len = 0;
737            data.data_union.v_int64 = 0;
738        }
739    }
740
741    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
742        unsafe { T::check_any_strict(data) || data.type_index == TypeIndex::kTVMFFINone as i32 }
743    }
744
745    unsafe fn match_constraints(data: &TVMFFIAny) -> bool {
746        unsafe { data.type_index == TypeIndex::kTVMFFINone as i32 || T::match_constraints(data) }
747    }
748
749    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
750        if data.type_index == TypeIndex::kTVMFFINone as i32 {
751            None
752        } else {
753            Some(unsafe { T::copy_from_any_view_after_check(data) })
754        }
755    }
756
757    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
758        if data.type_index == TypeIndex::kTVMFFINone as i32 {
759            None
760        } else {
761            Some(unsafe { T::move_from_any_after_check(data) })
762        }
763    }
764
765    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
766        if data.type_index == TypeIndex::kTVMFFINone as i32 {
767            Ok(None)
768        } else {
769            unsafe { T::try_cast_from_any_view(data).map(Some) }
770        }
771    }
772}
773
774// Special rule: we convert () to None
775// This allows us to effectively pass () around as null value
776// note that this is indeed a bit relaxation of the type
777// but it is necessary for us to enable void/none interoperability
778unsafe impl AnyCompatible for () {
779    fn type_str() -> String {
780        // make it consistent with c++ representation
781        "None".to_string()
782    }
783
784    unsafe fn copy_to_any_view(_src: &Self, data: &mut TVMFFIAny) {
785        data.type_index = TypeIndex::kTVMFFINone as i32;
786        data.small_str_len = 0;
787        data.data_union.v_int64 = 0;
788    }
789
790    unsafe fn move_to_any(_src: Self, data: &mut TVMFFIAny) {
791        data.type_index = TypeIndex::kTVMFFINone as i32;
792        data.small_str_len = 0;
793        data.data_union.v_int64 = 0;
794    }
795
796    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
797        data.type_index == TypeIndex::kTVMFFINone as i32
798    }
799
800    unsafe fn copy_from_any_view_after_check(_data: &TVMFFIAny) -> Self {}
801
802    unsafe fn move_from_any_after_check(_data: &mut TVMFFIAny) -> Self {}
803
804    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
805        if data.type_index == TypeIndex::kTVMFFINone as i32 {
806            Ok(())
807        } else {
808            Err(())
809        }
810    }
811}
812
813unsafe impl AnyCompatible for *mut core::ffi::c_void {
814    unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
815        data.type_index = TypeIndex::kTVMFFIOpaquePtr as i32;
816        data.small_str_len = 0;
817        data.data_union.v_ptr = *src;
818    }
819    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
820        data.type_index == TypeIndex::kTVMFFIOpaquePtr as i32
821    }
822
823    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
824        unsafe { data.data_union.v_ptr }
825    }
826
827    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
828        data.type_index = TypeIndex::kTVMFFIOpaquePtr as i32;
829        data.small_str_len = 0;
830        data.data_union.v_int64 = src as i64;
831    }
832
833    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
834        unsafe { data.data_union.v_ptr }
835    }
836
837    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
838        if data.type_index == TypeIndex::kTVMFFINone as i32 {
839            Ok(std::ptr::null_mut())
840        } else if data.type_index == TypeIndex::kTVMFFIOpaquePtr as i32 {
841            unsafe { Ok(data.data_union.v_ptr) }
842        } else {
843            Err(())
844        }
845    }
846
847    fn type_str() -> String {
848        "void*".to_string()
849    }
850}
851
852mod container_element_ops {
853    use super::{Any, AnyCompatible, AnyView, TVMFFIAny};
854
855    pub trait Ops: Sized {
856        const CONTAINER_IS_ANY: bool = false;
857
858        unsafe fn container_copy_to_any_view(src: &Self, data: &mut TVMFFIAny);
859        unsafe fn container_move_to_any(src: Self, data: &mut TVMFFIAny);
860        unsafe fn container_check_any_strict(data: &TVMFFIAny) -> bool;
861        unsafe fn container_match_constraints(data: &TVMFFIAny) -> bool;
862        unsafe fn container_copy_from_any_view_after_check(data: &TVMFFIAny) -> Self;
863        unsafe fn container_move_from_any_after_check(data: &mut TVMFFIAny) -> Self;
864        unsafe fn container_try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()>;
865        fn container_get_mismatch_type_info(data: &TVMFFIAny) -> String;
866        fn container_type_str() -> String;
867        fn container_type_schema() -> String;
868    }
869
870    impl<T: AnyCompatible> Ops for T {
871        #[inline(always)]
872        unsafe fn container_copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
873            unsafe { <T as AnyCompatible>::copy_to_any_view(src, data) }
874        }
875
876        #[inline(always)]
877        unsafe fn container_move_to_any(src: Self, data: &mut TVMFFIAny) {
878            unsafe { <T as AnyCompatible>::move_to_any(src, data) }
879        }
880
881        #[inline(always)]
882        unsafe fn container_check_any_strict(data: &TVMFFIAny) -> bool {
883            unsafe { <T as AnyCompatible>::check_any_strict(data) }
884        }
885        #[inline(always)]
886        unsafe fn container_match_constraints(data: &TVMFFIAny) -> bool {
887            unsafe { <T as AnyCompatible>::match_constraints(data) }
888        }
889
890        #[inline(always)]
891        unsafe fn container_copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
892            unsafe { <T as AnyCompatible>::copy_from_any_view_after_check(data) }
893        }
894
895        #[inline(always)]
896        unsafe fn container_move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
897            unsafe { <T as AnyCompatible>::move_from_any_after_check(data) }
898        }
899
900        #[inline(always)]
901        unsafe fn container_try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
902            unsafe { <T as AnyCompatible>::try_cast_from_any_view(data) }
903        }
904
905        #[inline(always)]
906        fn container_get_mismatch_type_info(data: &TVMFFIAny) -> String {
907            <T as AnyCompatible>::get_mismatch_type_info(data)
908        }
909
910        #[inline(always)]
911        fn container_type_str() -> String {
912            <T as AnyCompatible>::type_str()
913        }
914
915        #[inline(always)]
916        fn container_type_schema() -> String {
917            <T as AnyCompatible>::type_schema()
918        }
919    }
920
921    impl Ops for Any {
922        const CONTAINER_IS_ANY: bool = true;
923
924        #[inline(always)]
925        unsafe fn container_copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
926            *data = *src.as_raw_ffi_any();
927        }
928
929        #[inline(always)]
930        unsafe fn container_move_to_any(src: Self, data: &mut TVMFFIAny) {
931            *data = Any::into_raw_ffi_any(src);
932        }
933
934        #[inline(always)]
935        unsafe fn container_check_any_strict(_data: &TVMFFIAny) -> bool {
936            true
937        }
938        #[inline(always)]
939        unsafe fn container_match_constraints(_data: &TVMFFIAny) -> bool {
940            true
941        }
942
943        #[inline(always)]
944        unsafe fn container_copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
945            unsafe { Any::from(AnyView::from_raw_ffi_any(*data)) }
946        }
947
948        #[inline(always)]
949        unsafe fn container_move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
950            unsafe { Any::from_raw_ffi_any(std::mem::replace(data, TVMFFIAny::new())) }
951        }
952
953        #[inline(always)]
954        unsafe fn container_try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
955            Ok(unsafe { Any::from(AnyView::from_raw_ffi_any(*data)) })
956        }
957
958        #[inline(always)]
959        fn container_get_mismatch_type_info(_data: &TVMFFIAny) -> String {
960            "Any".to_string()
961        }
962
963        #[inline(always)]
964        fn container_type_str() -> String {
965            "Any".to_string()
966        }
967
968        #[inline(always)]
969        fn container_type_schema() -> String {
970            <Any as super::TypeSchema>::type_schema()
971        }
972    }
973}
974
975/// The type key of the runtime type index `type_index`.
976pub(crate) fn runtime_type_key(type_index: i32) -> String {
977    unsafe {
978        let info = TVMFFIGetTypeInfo(type_index);
979        assert!(!info.is_null(), "TVMFFIGetTypeInfo returned null");
980        (*info).type_key.as_str().to_string()
981    }
982}
983
984/// Writes a type schema, `{"type":"<origin>"}` or, with type arguments,
985/// `{"type":"<origin>","args":[...]}`.
986pub(crate) fn type_schema(origin: &str, args: &[String]) -> String {
987    if args.is_empty() {
988        format!(r#"{{"type":"{origin}"}}"#)
989    } else {
990        format!(r#"{{"type":"{origin}","args":[{}]}}"#, args.join(","))
991    }
992}
993
994/// The metadata recorded for a function or field of type schema
995/// `type_schema`: `{"type_schema":<type_schema as a JSON string>}`.
996pub(crate) fn type_schema_metadata(type_schema: &str) -> String {
997    format!(r#"{{"type_schema":{}}}"#, escape_string_json(type_schema))
998}
999
1000/// `text` as a JSON string literal, escaped so that the metadata matches the
1001/// C++ runtime's byte for byte.
1002fn escape_string_json(text: &str) -> String {
1003    let mut out = String::with_capacity(text.len() + 2);
1004    out.push('"');
1005    for ch in text.chars() {
1006        match ch {
1007            '"' => out.push_str("\\\""),
1008            '\\' => out.push_str("\\\\"),
1009            '/' => out.push_str("\\/"),
1010            '\u{8}' => out.push_str("\\b"),
1011            '\u{c}' => out.push_str("\\f"),
1012            '\n' => out.push_str("\\n"),
1013            '\r' => out.push_str("\\r"),
1014            '\t' => out.push_str("\\t"),
1015            ch if (ch as u32) < 0x20 || ch == '\u{7f}' => {
1016                out.push_str(&format!("\\u{:04x}", ch as u32))
1017            }
1018            ch => out.push(ch),
1019        }
1020    }
1021    out.push('"');
1022    out
1023}
1024
1025/// The type schema of a function parameter or return type.
1026///
1027/// This is [`AnyCompatible::type_schema`] for a type that converts through
1028/// [`Any`], and `{"type":"Any"}` for `Any` and `AnyView` themselves.
1029pub(crate) trait TypeSchema {
1030    fn type_schema() -> String;
1031}
1032
1033impl<T: AnyCompatible> TypeSchema for T {
1034    fn type_schema() -> String {
1035        <T as AnyCompatible>::type_schema()
1036    }
1037}
1038
1039impl TypeSchema for Any {
1040    fn type_schema() -> String {
1041        type_schema("Any", &[])
1042    }
1043}
1044
1045impl TypeSchema for AnyView<'_> {
1046    fn type_schema() -> String {
1047        type_schema("Any", &[])
1048    }
1049}