tvm-ffi 0.1.16

tvm-ffi rust support
Documentation
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

//! Objects made with every field undefined, for reflection to set the fields,
//! such as when a JSON graph is read back or `__ffi_init__` runs.
//!
//! A Rust reference is never null, so an object cannot hold a null reference
//! for its setters to overwrite later; instead [`unsafe_init`]
//! allocates the object zeroed, and a field holding all-zero bytes that are no
//! value of its type ([`AnyCompatible::is_undefined`]) is undefined. The field
//! setter writes an undefined field without dropping it, the field getter reads
//! it as None, and the object's deleter drops only the defined fields, all
//! through raw pointers, so no undefined field is ever viewed as its type.

use std::alloc::Layout;
use std::ffi::c_void;
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::atomic::AtomicU64;

use crate::object::{Object, ObjectArc, ObjectCore, ObjectRef, ObjectRefCore};
use crate::tvm_ffi_sys::TVMFFIObjectDeleterFlagBitMask::{
    kTVMFFIObjectDeleterFlagBitMaskStrong, kTVMFFIObjectDeleterFlagBitMaskWeak,
};
use crate::tvm_ffi_sys::{COMBINED_REF_COUNT_BOTH_ONE, TVMFFIObject, TVMFFIObjectHandle};
use crate::type_traits::AnyCompatible;
use crate::{Error, INTERNAL_ERROR};

/// An object type whose object can start with every field undefined, for
/// reflection to set the fields.
///
/// The creator that `#[rs_object]` registers for its type makes the object with
/// [`unsafe_init`], which a JSON graph read back, `__ffi_init__` and
/// `__ffi_new__` then fill. `#[rs_object]` implements it for its object, so the
/// parent's object must implement it too: [`Object`] does, and so does a
/// binding with `#[object(rs_parent)]` on its [`derive(Object)`](crate::derive::Object).
///
/// `__ffi_init__` leaves an `init_off` field as the creator made it, so such a
/// field's type must take all-zero bytes as a value, as a scalar, `Option<T>`
/// or `Any` does; the type's registration fails otherwise.
///
/// # Safety
///
/// `drop_defined_fields` drops each defined field of the object and no
/// undefined one, the parent's object's included.
pub unsafe trait UnsafeInit: ObjectCore {
    /// Drops the defined fields of the object at `this`, the parent's object's
    /// included, and leaves the undefined ones.
    ///
    /// # Safety
    ///
    /// `this` points to an object that [`unsafe_init`] made, which is not used
    /// afterwards.
    #[doc(hidden)]
    unsafe fn drop_defined_fields(this: *mut Self);
}

// The header holds nothing to drop.
unsafe impl UnsafeInit for Object {
    unsafe fn drop_defined_fields(_this: *mut Self) {}
}

/// Drops the field at `field` unless it is undefined.
///
/// # Safety
///
/// `field` points to a field of an object, defined or undefined, which is not
/// used afterwards.
#[inline]
unsafe fn drop_if_defined<F: AnyCompatible>(field: *mut F) {
    unsafe {
        if !F::is_undefined(field) {
            std::ptr::drop_in_place(field);
        }
    }
}

/// The field drops of a derived `UnsafeInit`, chosen by method resolution:
/// `(&FieldPtr(field)).drop_field()` drops an [`AnyCompatible`] field or an
/// [`Any`](crate::Any) unless it is undefined, and accepts any other field
/// only if it has no drop glue.
#[doc(hidden)]
pub mod field_drop {
    use super::drop_if_defined;
    use crate::any::Any;
    use crate::type_traits::AnyCompatible;

    pub struct FieldPtr<F>(pub *mut F);

    pub trait DropDefined {
        /// # Safety
        ///
        /// The pointer is to a field of an object, defined or undefined,
        /// which is not used afterwards.
        unsafe fn drop_field(&self);
    }

    impl<F: AnyCompatible> DropDefined for FieldPtr<F> {
        #[inline(always)]
        unsafe fn drop_field(&self) {
            unsafe { drop_if_defined(self.0) }
        }
    }

    // All-zero bytes are `None`.
    impl DropDefined for FieldPtr<Any> {
        #[inline(always)]
        unsafe fn drop_field(&self) {
            unsafe { std::ptr::drop_in_place(self.0) }
        }
    }

    pub trait DropNothing {
        fn drop_field(&self);
    }

    impl<F> DropNothing for &FieldPtr<F> {
        #[inline(always)]
        fn drop_field(&self) {
            const {
                assert!(
                    !std::mem::needs_drop::<F>(),
                    "a field of an `UnsafeInit` object must implement `AnyCompatible`, be \
                     `Any`, or have no drop glue"
                )
            };
        }
    }
}

/// An object of `T` with every field undefined, zero-filled, for reflection
/// to set the fields through their setters.
///
/// The [`ObjectRef`] views only the object's header, which is valid all along.
///
/// # Safety
///
/// Each field that all-zero bytes leave undefined
/// ([`AnyCompatible::is_undefined`]) is set before the object is viewed as a
/// `T` (by a cast of the reference) or the field is read as its type. Until
/// then, only the reflection's field setters and getters reach the fields.
pub unsafe fn unsafe_init<T: UnsafeInit>() -> ObjectRef {
    let layout = Layout::new::<T>();
    unsafe {
        let ptr = std::alloc::alloc_zeroed(layout);
        if ptr.is_null() {
            std::alloc::handle_alloc_error(layout);
        }
        std::ptr::write(
            ptr.cast::<TVMFFIObject>(),
            TVMFFIObject {
                combined_ref_count: AtomicU64::new(COMBINED_REF_COUNT_BOTH_ONE),
                type_index: T::type_index(),
                __padding: 0,
                deleter: Some(unsafe_init_deleter::<T>),
            },
        );
        // SAFETY: `ObjectRef` is the view of any object.
        ObjectRef::from_data(ObjectArc::from_raw(ptr.cast::<Object>()))
    }
}

/// The deleter of an object that [`unsafe_init`] made, which may go before
/// reflection sets every field, as when a JSON graph lacks one.
unsafe extern "C" fn unsafe_init_deleter<T: UnsafeInit>(ptr: *mut c_void, flags: i32) {
    // Objects made here drop field by field and never run the struct's `Drop::drop`.
    unsafe {
        if flags & kTVMFFIObjectDeleterFlagBitMaskStrong as i32 != 0 {
            T::drop_defined_fields(ptr.cast::<T>());
        }
        if flags & kTVMFFIObjectDeleterFlagBitMaskWeak as i32 != 0 {
            std::alloc::dealloc(ptr.cast::<u8>(), Layout::new::<T>());
        }
    }
}

/// The creator of `T` (`TVMFFITypeMetadata::creator`) that `#[rs_object]`
/// registers: it writes the owned handle of an object that [`unsafe_init`]
/// made to `result`.
///
/// # Safety
///
/// `result` is valid for writes.
#[doc(hidden)]
pub unsafe extern "C" fn unsafe_init_creator<T: UnsafeInit>(
    result: *mut TVMFFIObjectHandle,
) -> i32 {
    let made = catch_unwind(AssertUnwindSafe(|| unsafe {
        let object = unsafe_init::<T>();
        let handle = ObjectArc::into_raw(ObjectRef::into_data(object));
        std::ptr::write(result, handle as TVMFFIObjectHandle);
    }));
    match made {
        Ok(()) => 0,
        Err(_) => {
            let message = format!("panic while creating an object of `{}`", T::TYPE_KEY);
            Error::set_raised(&Error::new(INTERNAL_ERROR, &message));
            -1
        }
    }
}

#[cfg(test)]
mod tests {
    use std::mem::MaybeUninit;

    use crate::tvm_ffi_sys::dlpack::{DLDevice, DLDeviceType};
    use crate::type_traits::AnyCompatible;
    use crate::{Array, BigInt, String};

    fn zero_is_undefined<F: AnyCompatible>() -> bool {
        let zero = MaybeUninit::<F>::zeroed();
        unsafe { F::is_undefined(zero.as_ptr()) }
    }

    fn is_undefined<F: AnyCompatible>(value: F) -> bool {
        unsafe { F::is_undefined(&value) }
    }

    #[test]
    fn all_zero_bytes_are_undefined_where_they_are_no_value() {
        assert!(zero_is_undefined::<Array<i64>>());
        assert!(zero_is_undefined::<String>());
        assert!(zero_is_undefined::<BigInt>());
        assert!(zero_is_undefined::<DLDevice>());

        assert!(!zero_is_undefined::<i64>());
        assert!(!zero_is_undefined::<bool>());
        // `None`, through the niche of a reference or through a tag.
        assert!(!zero_is_undefined::<Option<Array<i64>>>());
        assert!(!zero_is_undefined::<Option<DLDevice>>());
        assert!(!zero_is_undefined::<Option<String>>());
    }

    #[test]
    fn values_are_defined() {
        let cpu = DLDevice {
            device_type: DLDeviceType::kDLCPU as i32,
            device_id: 0,
        };
        assert!(!is_undefined(Array::<i64>::new()));
        assert!(!is_undefined(String::from("")));
        assert!(!is_undefined(BigInt::from(0_i64)));
        assert!(!is_undefined(cpu));
        assert!(!is_undefined(Some(cpu)));
        assert!(!is_undefined(None::<DLDevice>));
        assert!(!is_undefined(None::<Array<i64>>));
    }
}