Skip to main content

tvm_ffi/
object.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//! Objects: reference-counted values shared with C++ and Python, and the
20//! traits that define object types ([`ObjectCore`]) and their managed
21//! references ([`ObjectRefCore`]).
22
23use std::ops::Deref;
24use std::ptr::NonNull;
25use std::sync::atomic::AtomicU64;
26
27use crate::any::AnyView;
28use crate::derive::ObjectRef;
29use crate::type_traits::AnyCompatible;
30use tvm_ffi_sys::TVMFFITypeIndex as TypeIndex;
31use tvm_ffi_sys::{COMBINED_REF_COUNT_BOTH_ONE, TVMFFIAny, TVMFFIGetTypeInfo, TVMFFIObject};
32
33// Type registration: writes to the runtime's type table from Rust, and the
34// check that a key registered elsewhere matches its Rust declaration.
35
36/// Held around every write to the type table from Rust, so that registrations
37/// from Rust do not race each other: the runtime does not lock its type table
38/// and leaves that to callers.
39static TYPE_REGISTRATION: std::sync::Mutex<()> = std::sync::Mutex::new(());
40
41/// Holds the lock around every write to the type table from Rust. A panic in
42/// another registration leaves the table consistent, so a poisoned lock is
43/// still taken.
44#[doc(hidden)]
45pub fn lock_type_registration() -> std::sync::MutexGuard<'static, ()> {
46    TYPE_REGISTRATION
47        .lock()
48        .unwrap_or_else(std::sync::PoisonError::into_inner)
49}
50
51/// Panics unless `type_index`, the index `#[derive(Object)]` registered or
52/// bound for `T`'s key, describes `T`: a key registered by another library or
53/// another type must have the same parent and depth and, if it has metadata,
54/// the same size, or for a `binding` no larger, since an opaque binding
55/// declares only its parent.
56///
57/// # Safety
58///
59/// `type_index` is registered and `parent` is the type index of `T::Parent`.
60#[doc(hidden)]
61pub unsafe fn assert_registered_type_matches<T: ObjectCore>(
62    type_index: i32,
63    parent: i32,
64    binding: bool,
65) {
66    let info = unsafe { &*TVMFFIGetTypeInfo(type_index) };
67    let depth = T::TYPE_DEPTH;
68    let same_parent = unsafe {
69        info.type_depth == depth
70            && depth > 0
71            && (**info.type_acenstors.add(depth as usize - 1)).type_index == parent
72    };
73    let size = std::mem::size_of::<T>();
74    let same_size = info.metadata.is_null() || {
75        let registered = unsafe { (*info.metadata).total_size as usize };
76        size == registered || (binding && size < registered)
77    };
78    assert!(
79        same_parent && same_size,
80        "Type key {} is already registered with another parent, depth or size",
81        T::TYPE_KEY
82    );
83}
84
85/// The root object type, `ffi.Object`: just the object header.
86///
87/// An object type defined in Rust starts with its parent's object, which for
88/// a direct subtype is `base_: Object`.
89#[repr(C)]
90pub struct Object {
91    header: TVMFFIObject,
92}
93
94impl Object {
95    /// A new object header, for the `base_` field of a new object.
96    #[allow(clippy::new_without_default)]
97    pub fn new() -> Self {
98        Self {
99            header: TVMFFIObject::new(),
100        }
101    }
102}
103
104unsafe impl ObjectCore for Object {
105    type Parent = ();
106    const TYPE_KEY: &'static str = "ffi.Object";
107    const TYPE_DEPTH: i32 = 0;
108    #[inline]
109    fn type_index() -> i32 {
110        TypeIndex::kTVMFFIStaticObjectBegin as i32
111    }
112    #[inline]
113    unsafe fn object_header_mut(this: &mut Self) -> &mut TVMFFIObject {
114        &mut this.header
115    }
116}
117
118/// A reference-counted pointer to an object `T`, as `Arc<T>`, counting with
119/// the object header so that every language shares the count.
120#[repr(C)]
121pub struct ObjectArc<T: ObjectCore> {
122    ptr: std::ptr::NonNull<T>,
123    _phantom: std::marker::PhantomData<T>,
124}
125
126impl ObjectArc<Object> {
127    /// Allocate a synchronous runtime payload that may contain borrowed Rust state.
128    ///
129    /// # Safety
130    /// `T` begins with a valid Object header and is ABI-compatible with the
131    /// registered `type_index`. The caller must keep this owner scoped to the
132    /// payload's borrows and ensure every temporary strong and weak reference
133    /// is released before those borrows end. Neither native handles nor this
134    /// erased owner may escape that synchronous scope. Destruction uses T's
135    /// exact layout and drop function, not the erased Object layout.
136    /// The erased owner and handles must remain on this thread unless the
137    /// concrete payload permits sharing or transfer; erasure grants neither.
138    pub(crate) unsafe fn new_opaque_unchecked<T>(data: T, type_index: i32) -> Self {
139        unsafe {
140            Self {
141                ptr: allocate_object(data, type_index).cast(),
142                _phantom: std::marker::PhantomData,
143            }
144        }
145    }
146}
147
148impl<T: ObjectCore> ObjectArc<T> {
149    /// Allocate an initialized object at its stable managed address.
150    pub fn new(data: T) -> Self {
151        // Resolve metadata before moving the payload into its allocation.
152        let type_index = T::type_index();
153        unsafe {
154            Self {
155                ptr: allocate_object(data, type_index),
156                _phantom: std::marker::PhantomData,
157            }
158        }
159    }
160
161    /// Allocate a stable object followed by its type's extra item storage.
162    ///
163    /// # Safety
164    /// The extra items start uninitialized: the caller writes each of them,
165    /// through [`ObjectCoreWithExtraItems::extra_items_ptr`] of
166    /// [`as_mut_ptr`](Self::as_mut_ptr), before the object is read or shared.
167    pub unsafe fn new_with_extra_items<U>(data: T) -> Self
168    where
169        T: ObjectCoreWithExtraItems<ExtraItem = U>,
170    {
171        // `data` may describe items it does not hold yet, so a panic before
172        // the write leaks it rather than dropping it.
173        let data = std::mem::ManuallyDrop::new(data);
174        unsafe {
175            // ensure strict alignment requirements
176            // so we can have { T, U*extra_items } layout
177            assert_eq!(std::mem::align_of::<T>() % std::mem::align_of::<U>(), 0);
178            assert_eq!(std::mem::size_of::<T>() % std::mem::align_of::<U>(), 0);
179            let extra_items_count = T::extra_items_count(&data);
180            let layout = unsafe_::extra_items_layout::<T, U>(extra_items_count);
181            let raw_data_ptr = std::alloc::alloc(layout);
182            if raw_data_ptr.is_null() {
183                std::alloc::handle_alloc_error(layout);
184            }
185            let ptr = raw_data_ptr as *mut T;
186            std::ptr::write(ptr, std::mem::ManuallyDrop::into_inner(data));
187            // now override the header directly
188            std::ptr::write(
189                ptr as *mut TVMFFIObject,
190                TVMFFIObject {
191                    combined_ref_count: AtomicU64::new(COMBINED_REF_COUNT_BOTH_ONE),
192                    type_index: T::type_index(),
193                    __padding: 0,
194                    deleter: Some(unsafe_::object_deleter_for_new_with_extra_items::<T, U>),
195                },
196            );
197            // move into the object arc ptr
198            Self {
199                ptr: std::ptr::NonNull::new_unchecked(ptr),
200                _phantom: std::marker::PhantomData,
201            }
202        }
203    }
204
205    /// Whether `this` holds a null pointer, as all-zero bytes do: no
206    /// `ObjectArc`, but the field of an object that a creator left undefined.
207    ///
208    /// See also [`AnyCompatible::is_undefined`].
209    ///
210    /// # Safety
211    ///
212    /// `this` points to an `ObjectArc<T>` or to all-zero bytes.
213    #[inline]
214    pub(crate) unsafe fn is_null(this: *const Self) -> bool {
215        unsafe { (*std::ptr::addr_of!((*this).ptr).cast::<*const T>()).is_null() }
216    }
217
218    /// Take ownership of a raw object pointer, as `Arc::from_raw`.
219    ///
220    /// # Arguments
221    /// * `ptr` - A pointer that owns one strong reference.
222    ///
223    /// # Returns
224    /// The handle that owns that reference.
225    ///
226    /// # Safety
227    /// `ptr` must own one strong reference to a live, stable managed allocation
228    /// whose dynamic type is compatible with `T` and whose payload is valid.
229    /// Ownership of that reference is transferred into the returned handle.
230    #[inline(always)]
231    pub unsafe fn from_raw(ptr: *const T) -> Self {
232        unsafe {
233            Self {
234                ptr: std::ptr::NonNull::new_unchecked(ptr as *mut T),
235                _phantom: std::marker::PhantomData,
236            }
237        }
238    }
239
240    /// Turn the handle into a raw pointer, as `Arc::into_raw`.
241    ///
242    /// # Arguments
243    /// * `this` - The handle.
244    ///
245    /// # Returns
246    /// The pointer, which owns the strong reference; pass it back to
247    /// [`ObjectArc::from_raw`] to release it.
248    #[inline(always)]
249    pub fn into_raw(this: Self) -> *const T {
250        let droped_this = std::mem::ManuallyDrop::new(this);
251        droped_this.ptr.as_ptr() as *const T
252    }
253
254    /// The raw pointer, without giving up ownership, as `Arc::as_ptr`.
255    ///
256    /// # Arguments
257    /// * `this` - The handle.
258    ///
259    /// # Returns
260    /// The non-owning pointer. Dereferencing it must respect existing borrows,
261    /// and it cannot outlive an owning handle.
262    #[inline]
263    pub fn as_ptr(this: &Self) -> *const T {
264        this.ptr.as_ptr() as *const T
265    }
266
267    /// The raw mutable pointer, without giving up ownership.
268    ///
269    /// # Arguments
270    /// * `this` - The handle.
271    ///
272    /// # Returns
273    /// The non-owning pointer. The handle need not be unique: writing through
274    /// it needs exclusive access to the object, and must not move or replace
275    /// the object or its header.
276    #[inline]
277    pub fn as_mut_ptr(this: &mut Self) -> *mut T {
278        this.ptr.as_ptr()
279    }
280
281    /// The number of strong references, as `Arc::strong_count`.
282    ///
283    /// # Arguments
284    /// * `this` - The handle.
285    #[inline]
286    pub fn strong_count(this: &Self) -> usize {
287        unsafe { unsafe_::strong_count(this.ptr.as_ptr().cast::<TVMFFIObject>()) }
288    }
289
290    /// Whether this is the only reference, strong and with no weak one, so the
291    /// object may be mutated in place.
292    ///
293    /// # Arguments
294    /// * `this` - The handle.
295    #[inline]
296    pub fn is_unique(this: &Self) -> bool {
297        unsafe { unsafe_::is_unique(this.ptr.as_ptr().cast::<TVMFFIObject>()) }
298    }
299
300    /// The number of weak references, as `Arc::weak_count`: the weak
301    /// reference that the strong references hold together is not counted.
302    ///
303    /// # Arguments
304    /// * `this` - The handle.
305    #[inline]
306    pub fn weak_count(this: &Self) -> usize {
307        // While a strong reference lives, the raw count includes the one weak
308        // reference that all strong references share.
309        unsafe { unsafe_::weak_count(this.ptr.as_ptr().cast::<TVMFFIObject>()) - 1 }
310    }
311}
312
313// implement Deref for ObjectArc
314impl<T: ObjectCore> Deref for ObjectArc<T> {
315    type Target = T;
316    #[inline]
317    fn deref(&self) -> &Self::Target {
318        unsafe { self.ptr.as_ref() }
319    }
320}
321
322// implement Drop for ObjectArc
323impl<T: ObjectCore> Drop for ObjectArc<T> {
324    #[inline(always)]
325    fn drop(&mut self) {
326        unsafe { unsafe_::dec_ref(self.ptr.as_ptr().cast::<TVMFFIObject>()) }
327    }
328}
329
330// implement Clone for ObjectArc
331impl<T: ObjectCore> Clone for ObjectArc<T> {
332    #[inline]
333    fn clone(&self) -> Self {
334        unsafe { unsafe_::inc_ref(self.ptr.as_ptr().cast::<TVMFFIObject>()) }
335        Self {
336            ptr: self.ptr,
337            _phantom: std::marker::PhantomData,
338        }
339    }
340}
341
342/// An object type whose shared instances are never mutated, so `ObjectArc<T>` is
343/// `Send + Sync` when `T`'s fields are.
344///
345/// Implement it with the `immutable` option of [`rs_object`](crate::rs_object)
346/// or `#[object(immutable)]` on [`derive(Object)`](crate::derive::Object), which
347/// reject `writable` fields.
348///
349/// # Safety
350///
351/// No code may mutate an instance while it is shared: changes go through
352/// copy-on-write, in place only on a uniquely held instance (one strong
353/// reference, no weak ones). This holds for every type not registered as
354/// mutable (`_type_mutable`), in any language. Every subclass must also be
355/// immutable while shared, with thread-safe fields; the derives reject a
356/// subtype that is not `immutable` at compile time. A hand-written impl must
357/// also set `ObjectCore::TYPE_IMMUTABLE` and keep every subtype immutable.
358pub unsafe trait ImmutableObject: ObjectCore {}
359
360// SAFETY: `T` is never mutated while shared, its fields are thread-safe, and the
361// reference count is atomic.
362unsafe impl<T: ImmutableObject + Send + Sync> Send for ObjectArc<T> {}
363// SAFETY: as for `Send`.
364unsafe impl<T: ImmutableObject + Send + Sync> Sync for ObjectArc<T> {}
365
366/// A managed reference to an object of any type, the root of every object
367/// reference; downcast it to a concrete reference with
368/// [`ObjectRefCore::downcast`].
369#[repr(C)]
370#[derive(ObjectRef, Clone)]
371#[object_ref(skip_deref)]
372pub struct ObjectRef {
373    data: ObjectArc<Object>,
374}
375
376/// The native representation of an object-system type.
377///
378/// # Safety
379/// `Self` must have a compatible C layout with a valid `TVMFFIObject` prefix
380/// at offset zero, and embed a `Self::Parent` there unless it is the root.
381/// Its registered type, inheritance and payload must describe that layout
382/// correctly, including for foreign declarations.
383///
384/// A live managed object and its header must remain at their original allocation
385/// address until destruction. Safe APIs must not move, replace or expose mutable
386/// access to that header while managed; payload mutation must preserve its type
387/// invariants. Preallocation builders and values moved out during destruction
388/// are not live managed objects and cannot be borrowed as `AnyView`.
389#[diagnostic::on_unimplemented(message = "`{Self}` is not an object type")]
390pub unsafe trait ObjectCore: Sized + 'static {
391    /// The parent's object type, which `Self` embeds at offset zero; `()` for
392    /// the root [`Object`].
393    type Parent;
394    /// The type key, such as `"ffi.Array"`.
395    const TYPE_KEY: &'static str;
396    /// Depth of this type in the object inheritance tree.
397    ///
398    /// The root [`Object`] has depth zero, and every registered subtype has
399    /// depth one greater than its parent. This value must be non-negative and
400    /// agree with the runtime type table entry for `Self`.
401    const TYPE_DEPTH: i32;
402    /// Whether every instance of this type has exactly `Self::type_index()`.
403    ///
404    /// A final type has no separately registered object-system subtype.
405    #[doc(hidden)]
406    const TYPE_FINAL: bool = false;
407    /// Whether `Self` implements [`ImmutableObject`].
408    #[doc(hidden)]
409    const TYPE_IMMUTABLE: bool = false;
410    /// Whether `Self` or an ancestor declares a `writable` reflected field.
411    #[doc(hidden)]
412    const TYPE_HAS_WRITABLE_FIELD: bool = false;
413    /// The runtime type index of this type.
414    fn type_index() -> i32;
415    /// Whether [`type_index`](Self::type_index) can return now: false while
416    /// the key of a binding, this type or an ancestor, is not registered
417    /// because its library is not loaded yet.
418    #[doc(hidden)]
419    fn type_index_available() -> bool {
420        true
421    }
422    /// The object header, mutably.
423    ///
424    /// # Arguments
425    /// * `this` - The object.
426    ///
427    /// # Safety
428    /// The caller must have exclusive access to the header and preserve the
429    /// managed allocation's address, reference counts, deleter and dynamic type.
430    unsafe fn object_header_mut(this: &mut Self) -> &mut TVMFFIObject;
431}
432
433// Object hierarchy: a compile-time check that one object type derives from
434// another, which `#[object_ref(parent = ...)]` relies on.
435
436/// The object type `Self` is `A` or derives from it through its chain of
437/// [`ObjectCore::Parent`]s, so a `Self` is a valid `A`.
438///
439/// `Depth` is the number of parent steps from `Self` to `A`, a type from
440/// [`marker`] that the compiler infers.
441///
442/// # Safety
443///
444/// The blanket implementations are the only sound ones: do not implement it.
445#[doc(hidden)]
446#[diagnostic::on_unimplemented(message = "`{Self}` does not derive from `{A}`")]
447pub unsafe trait ObjectDerivesFrom<A, Depth> {}
448
449/// Inferred depths for [`ObjectDerivesFrom`].
450#[doc(hidden)]
451pub mod marker {
452    /// `A` is the object type itself.
453    pub enum Itself {}
454    /// `A` is reached through one more [`Parent`](super::ObjectCore::Parent).
455    pub struct Parent<Depth>(std::marker::PhantomData<fn() -> Depth>);
456}
457
458// SAFETY: every type is itself.
459unsafe impl<T: ObjectCore> ObjectDerivesFrom<T, marker::Itself> for T {}
460
461// SAFETY: `T` embeds `T::Parent` at offset zero, so whatever the parent
462// derives from, `T` does.
463unsafe impl<T: ObjectCore, A, Depth> ObjectDerivesFrom<A, marker::Parent<Depth>> for T where
464    T::Parent: ObjectDerivesFrom<A, Depth>
465{
466}
467
468/// An object type whose allocation is followed by a run of extra items, such
469/// as the dimensions of a [`Shape`](crate::Shape).
470///
471/// The items lie past `Self`, so a pointer to them is derived from a pointer
472/// to the whole allocation, such as [`ObjectArc::as_ptr`], never from a
473/// `&Self`, which covers `Self` only.
474///
475/// # Safety
476/// Every allocation of `Self` is followed by `extra_items_count` `ExtraItem`s,
477/// as [`ObjectArc::new_with_extra_items`] lays them out. The count stays the
478/// same for the object's life, and the items are never dropped.
479pub unsafe trait ObjectCoreWithExtraItems: ObjectCore {
480    /// The type of the items that follow the object.
481    type ExtraItem;
482    /// The number of extra items.
483    fn extra_items_count(this: &Self) -> usize;
484    /// A pointer to the first extra item.
485    ///
486    /// # Safety
487    /// `this` points to an allocation that carries its extra items, and its
488    /// provenance covers them.
489    unsafe fn extra_items_ptr(this: *mut Self) -> *mut Self::ExtraItem {
490        unsafe { this.cast::<u8>().add(std::mem::size_of::<Self>()).cast() }
491    }
492    /// The extra items.
493    ///
494    /// # Safety
495    /// As [`extra_items_ptr`](Self::extra_items_ptr), with the items
496    /// initialized and not written for `'a`.
497    unsafe fn extra_items<'a>(this: *const Self) -> &'a [Self::ExtraItem] {
498        unsafe {
499            std::slice::from_raw_parts(
500                Self::extra_items_ptr(this.cast_mut()),
501                Self::extra_items_count(&*this),
502            )
503        }
504    }
505}
506
507/// A managed object reference, such as [`ObjectRef`](struct@ObjectRef), `Array<T>`
508/// or a `#[derive(ObjectRef)]` type, with identity ([`same_as`](Self::same_as))
509/// and strict casts that check the runtime type and never convert; upcasts are
510/// `From`/`Into`.
511///
512/// # Casts
513///
514/// * [`downcast_ref`](Self::downcast_ref) borrows, strictly, as std's
515///   `dyn Any::downcast_ref` does.
516/// * [`downcast`](Self::downcast) takes the value, strictly, and hands it back
517///   on a mismatch, as `Box<dyn Any>::downcast` does.
518/// * `TryFrom` takes the value and returns a `TypeError`, for `?`. Between
519///   references it only checks; from an [`Any`](crate::Any) it converts by
520///   the FFI rules, such as an integer into a float.
521///
522/// # Safety
523///
524/// `data`, `into_data`, and `from_data` must preserve the same object
525/// allocation and form an ownership-preserving round trip. That allocation must
526/// start with a valid `TVMFFIObject` header whose registered object-range
527/// runtime type index correctly describes its layout and inheritance.
528///
529/// When `Self` also implements [`AnyCompatible`], `copy_to_any_view` must
530/// produce a non-owning view, while `move_to_any` must transfer ownership of
531/// the same object pointer and dynamic type index. `move_from_any_after_check`
532/// must be able to reclaim that owned representation exactly once, and a true
533/// `check_any_strict` result must guarantee that both after-check constructors
534/// are valid for it.
535pub unsafe trait ObjectRefCore: Sized + Clone + AnyCompatible {
536    /// The object type the reference points to.
537    type ContainerType: ObjectCore;
538    /// Borrow the object's handle.
539    fn data(this: &Self) -> &ObjectArc<Self::ContainerType>;
540    /// Take the object's handle.
541    fn into_data(this: Self) -> ObjectArc<Self::ContainerType>;
542
543    /// Make a reference from the object's handle.
544    ///
545    /// # Safety
546    ///
547    /// In addition to containing a valid `ContainerType` allocation, `data`
548    /// must satisfy every semantic invariant imposed by `Self`. This matters
549    /// for zero-state views that share a container type but accept only a
550    /// subset of its values, such as a reference whose
551    /// [`ObjectRefAnyCompatible::extra_check`] rejects some objects.
552    unsafe fn from_data(data: ObjectArc<Self::ContainerType>) -> Self;
553
554    /// Whether two references point to the same object.
555    #[inline]
556    fn same_as<Other: ObjectRefCore>(&self, other: &Other) -> bool {
557        ObjectArc::as_ptr(Self::data(self)).cast::<()>()
558            == ObjectArc::as_ptr(Other::data(other)).cast::<()>()
559    }
560
561    /// The registered type key of the object's runtime type, such as
562    /// `"ffi.Array"`, as C++ `ObjectRef::GetTypeKey`.
563    #[inline]
564    fn type_key(&self) -> &'static str {
565        // SAFETY: ObjectRefCore guarantees a live object with a registered
566        // type index.
567        let type_index =
568            unsafe { (*ObjectArc::as_ptr(Self::data(self)).cast::<TVMFFIObject>()).type_index };
569        registered_type_key(type_index)
570    }
571
572    /// Whether the reference is a `T` as is, such as a subtype or a container
573    /// whose elements are checked too, by the strict check of
574    /// [`downcast`](Self::downcast), without a reference count change.
575    /// See also [`crate::Any::is`].
576    #[inline(always)]
577    fn is<T: AnyCompatible>(&self) -> bool {
578        let mut any_data = TVMFFIAny::new();
579        // SAFETY: the view of `self` is a valid cell while `self` is borrowed.
580        unsafe {
581            Self::copy_to_any_view(self, &mut any_data);
582            T::check_any_strict(&any_data)
583        }
584    }
585
586    /// Borrow the underlying object as `T` when it is one.
587    ///
588    /// `T` is an object type such as `MyPairObj`, or a managed reference such
589    /// as `MyPair`: `&ObjectRef` borrows as `&MyPair` when its object is a
590    /// `MyPairObj`. Unrelated types return `None`. Unlike [`downcast`](Self::downcast), this
591    /// method neither consumes the reference nor changes the object's reference
592    /// count. The returned borrow cannot outlive `self`.
593    /// See [`crate::Any::downcast_ref`] for an example.
594    #[inline(always)]
595    fn downcast_ref<T: crate::type_traits::DowncastRefFromObject>(&self) -> Option<&T> {
596        // SAFETY: `ObjectArc` is exactly one non-null object pointer, and
597        // ObjectRefCore guarantees a live object allocation.
598        unsafe {
599            let place = &*(Self::data(self) as *const ObjectArc<Self::ContainerType>
600                as *const *mut TVMFFIObject);
601            T::downcast_ref_from_object(place)
602        }
603    }
604
605    /// Take `self` as `B`, a subtype or a container such as `Array<i64>` whose
606    /// elements are checked too, when its object is one, without copying it.
607    /// On a mismatch the reference is returned unchanged.
608    ///
609    /// ```
610    /// use tvm_ffi::{object::ObjectRef, Array, ObjectRefCore};
611    /// let object: ObjectRef = Array::from_vec(vec![1_i64]).into();
612    /// let object = object.downcast::<Array<f64>>().unwrap_err();
613    /// let array: Array<i64> = object.try_into()?;
614    /// assert_eq!(array.len(), 1);
615    /// # Ok::<(), tvm_ffi::Error>(())
616    /// ```
617    #[inline(always)]
618    fn downcast<B>(self) -> std::result::Result<B, Self>
619    where
620        B: ObjectRefCore,
621    {
622        let mut any_data = TVMFFIAny::new();
623        unsafe {
624            // Keep ownership in `self` while the target check runs, so a
625            // mismatch can hand it back and a panic unwinds normally.
626            Self::copy_to_any_view(&self, &mut any_data);
627            debug_assert!(any_data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32);
628            // SAFETY: ObjectRefCore's contract requires its AnyCompatible
629            // representation to contain a valid object-range type index.
630            std::hint::assert_unchecked(
631                any_data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32,
632            );
633            if B::check_any_strict(&any_data) {
634                // Transfer ownership only after the borrowed representation has
635                // passed the target's complete hierarchy/container check.
636                Self::move_to_any(self, &mut any_data);
637                Ok(B::move_from_any_after_check(&mut any_data))
638            } else {
639                Err(self)
640            }
641        }
642    }
643}
644
645/// The [`AnyCompatible`] implementation of an object reference, with every
646/// hook defaulted: every implementer is `AnyCompatible`.
647///
648/// `#[derive(ObjectRef)]` implements it with the defaults. A typed reference
649/// that accepts only some objects of its type, or converts other values,
650/// implements it by hand and overrides only what differs, such as
651/// [`extra_check`](Self::extra_check) and
652/// [`convert_fallback`](Self::convert_fallback) below. A type with another
653/// representation, such as [`Array`](crate::Array), implements
654/// `AnyCompatible` instead.
655///
656/// # Safety
657///
658/// `Self` is exactly one [`ObjectArc<Self::ContainerType>`](ObjectArc). The
659/// hooks do not modify an `ffi.List` or `ffi.Dict` that holds the value they
660/// examine, whose cell a container read borrows while they run; otherwise
661/// they cannot break the [`AnyCompatible`] contract.
662///
663/// # Examples
664///
665/// ```standalone_crate
666/// use tvm_ffi::derive::ObjectRef;
667/// use tvm_ffi::{rs_object, Any, AnyView, Object, ObjectArc};
668/// use tvm_ffi::object::ObjectRefAnyCompatible;
669///
670/// #[rs_object(type_key = "my_ext.MyPair", final)]
671/// pub struct MyPairObj {
672///     base_: Object,
673///     pub first: i64,
674///     pub second: i64,
675/// }
676///
677/// #[derive(Clone, ObjectRef)]
678/// pub struct MyPair {
679///     data: ObjectArc<MyPairObj>,
680/// }
681///
682/// /// A `MyPair` whose `first` is positive.
683/// #[derive(Clone, ObjectRef)]
684/// #[object_ref(skip_any_compatible)]
685/// pub struct PositivePair {
686///     data: ObjectArc<MyPairObj>,
687/// }
688///
689/// unsafe impl ObjectRefAnyCompatible for PositivePair {
690///     fn extra_check(pair: &MyPairObj) -> bool {
691///         pair.first > 0
692///     }
693///
694///     // A positive integer `n` converts to the pair `(n, n)`.
695///     fn convert_fallback(value: AnyView<'_>) -> Option<Self> {
696///         let n = i64::try_from(value).ok().filter(|n| *n > 0)?;
697///         Some(Self::from_object(MyPairObj::new(Object::new(), n, n)))
698///     }
699/// }
700///
701/// let negative = Any::from(MyPair::from_object(MyPairObj::new(Object::new(), -1, 2)));
702/// assert!(negative.downcast_ref::<PositivePair>().is_none());
703/// assert!(PositivePair::try_from(negative).is_err());
704/// assert_eq!(PositivePair::try_from(Any::from(3_i64))?.second, 3);
705/// # Ok::<(), tvm_ffi::Error>(())
706/// ```
707pub unsafe trait ObjectRefAnyCompatible: ObjectRefCore {
708    /// Whether no hook is overridden, so that `match_any!` may route a final
709    /// object type by its type index alone; only `#[derive(ObjectRef)]` sets
710    /// it. See [`AnyCompatible::MATCH_ANY_EXACT`].
711    #[doc(hidden)]
712    const MATCH_ANY_EXACT: bool = false;
713
714    /// Whether `obj`, an instance of `ContainerType`, is a value of `Self`.
715    /// Every strict and converting cast checks it, after the object type.
716    #[inline]
717    fn extra_check(obj: &Self::ContainerType) -> bool {
718        let _ = obj;
719        true
720    }
721
722    /// Convert a value that is not a `Self` object, such as an integer that
723    /// stands for a constant; `None` rejects it. Only converting casts (`TryFrom<Any>`,
724    /// typed function arguments) call it; `downcast_ref`, `downcast` and
725    /// `match_any!` never do.
726    #[inline]
727    fn convert_fallback(value: AnyView<'_>) -> Option<Self> {
728        let _ = value;
729        None
730    }
731
732    /// The type name in conversion errors and type schemas; by default the
733    /// object's type key. See [`AnyCompatible::type_str`].
734    fn custom_type_str() -> String {
735        Self::ContainerType::TYPE_KEY.into()
736    }
737
738    /// The name of the mismatched `value` in conversion errors; by default its
739    /// runtime type key. See [`AnyCompatible::get_mismatch_type_info`].
740    fn custom_mismatch_type_info(value: AnyView<'_>) -> String {
741        crate::type_traits::runtime_type_key(value.type_index())
742    }
743}
744
745/// An object reference that accepts every object of its type and promises
746/// nothing more, so any object type that derives from it may claim it as
747/// `#[object_ref(parent = ...)]`. `#[derive(ObjectRef)]` implements it for a
748/// non-generic reference with the default checks.
749///
750/// # Safety
751///
752/// Every object of `Self::ContainerType`, or of a type derived from it, is a
753/// valid `Self`.
754#[doc(hidden)]
755#[diagnostic::on_unimplemented(
756    message = "`{Self}` promises more than its object type (generic or custom checks)",
757    note = "write `#[object_ref(unsafe parent = ...)]` and keep that promise for every value"
758)]
759pub unsafe trait PlainObjectRef: ObjectRefCore {}
760
761// The object cell encoding, with the strict check `is_instance_of` then
762// `extra_check`, and `convert_fallback` after it in converting casts.
763unsafe impl<T: ObjectRefAnyCompatible> AnyCompatible for T {
764    // An overridden hook makes the type inexact; a non-final object type always is.
765    const MATCH_ANY_EXACT: bool = <T as ObjectRefAnyCompatible>::MATCH_ANY_EXACT
766        && <T::ContainerType as ObjectCore>::TYPE_FINAL;
767
768    #[inline]
769    fn match_any_exact_type_index() -> i32 {
770        T::ContainerType::type_index()
771    }
772
773    #[inline]
774    unsafe fn is_undefined(field: *const Self) -> bool {
775        // `Self` is one `ObjectArc`, so its null form is the undefined field.
776        unsafe { ObjectArc::is_null(field.cast::<ObjectArc<T::ContainerType>>()) }
777    }
778
779    #[inline(always)]
780    unsafe fn copy_to_any_view(src: &Self, data: &mut TVMFFIAny) {
781        unsafe { write_object_cell(ObjectArc::as_ptr(T::data(src)), data) };
782    }
783
784    #[inline(always)]
785    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
786        unsafe { write_object_cell(ObjectArc::into_raw(T::into_data(src)), data) };
787    }
788
789    #[inline(always)]
790    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
791        // An instance of `ContainerType` points to one, so `extra_check` may read it.
792        unsafe {
793            is_instance_of::<T::ContainerType>(data.type_index)
794                && T::extra_check(&*data.data_union.v_obj.cast::<T::ContainerType>())
795        }
796    }
797
798    #[inline]
799    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
800        // The view does not own the object, so the new reference takes one.
801        unsafe { unsafe_::inc_ref(data.data_union.v_obj) };
802        unsafe { T::from_data(ObjectArc::from_raw(data.data_union.v_obj.cast())) }
803    }
804
805    #[inline(always)]
806    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
807        unsafe { T::from_data(ObjectArc::from_raw(data.data_union.v_obj.cast())) }
808    }
809
810    #[inline]
811    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
812        if unsafe { Self::check_any_strict(data) } {
813            return Ok(unsafe { Self::copy_from_any_view_after_check(data) });
814        }
815        // A moved-from rvalue slot is consumed only by an exact object match.
816        if data.type_index == TypeIndex::kTVMFFIObjectRValueRef as i32 {
817            return Err(());
818        }
819        unsafe { T::convert_fallback(AnyView::from_raw_ffi_any(*data)).ok_or(()) }
820    }
821
822    fn get_mismatch_type_info(data: &TVMFFIAny) -> String {
823        // SAFETY: the caller's cell is valid for the borrow.
824        T::custom_mismatch_type_info(unsafe { AnyView::from_raw_ffi_any(*data) })
825    }
826
827    fn type_str() -> String {
828        T::custom_type_str()
829    }
830}
831
832/// An owning, hashable identity key for an FFI object.
833///
834/// The retained strong reference prevents the allocation address from being
835/// reused while the key is alive. This makes it suitable for identity-based
836/// maps without exposing raw object pointers to downstream code.
837#[derive(Clone)]
838pub struct ObjectIdentity {
839    data: ObjectArc<Object>,
840}
841
842impl ObjectIdentity {
843    /// Retain the allocation referenced by `value` as an identity key.
844    pub fn of<T: ObjectRefCore>(value: &T) -> Self {
845        unsafe {
846            let ptr = ObjectArc::as_ptr(T::data(value)) as *mut TVMFFIObject;
847            unsafe_::inc_ref(ptr);
848            Self {
849                data: ObjectArc::from_raw(ptr.cast::<Object>()),
850            }
851        }
852    }
853
854    #[inline]
855    fn as_ptr(&self) -> *const TVMFFIObject {
856        ObjectArc::as_ptr(&self.data).cast::<TVMFFIObject>()
857    }
858}
859
860impl PartialEq for ObjectIdentity {
861    #[inline]
862    fn eq(&self, other: &Self) -> bool {
863        self.as_ptr() == other.as_ptr()
864    }
865}
866
867impl Eq for ObjectIdentity {}
868
869impl std::hash::Hash for ObjectIdentity {
870    #[inline]
871    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
872        self.as_ptr().hash(state);
873    }
874}
875
876impl std::fmt::Debug for ObjectIdentity {
877    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
878        f.debug_tuple("ObjectIdentity")
879            .field(&self.as_ptr())
880            .finish()
881    }
882}
883
884/// Whether the runtime type index of an object is `Target` or one of its
885/// subtypes, by walking the registered type hierarchy.
886///
887/// Use it in the strict check of a reference type implemented by hand; the
888/// casts of [`ObjectRefCore`] call it already. An index in the object range
889/// must be registered.
890#[inline(always)]
891pub fn is_instance_of<Target: ObjectCore>(object_type_index: i32) -> bool {
892    // Every registered type records its depth in the single inheritance tree
893    // and its ancestors, so the check is O(1): an ancestor `Target` appears in
894    // the candidate's ancestor array exactly at `Target`'s depth.
895    let target_type_index = Target::type_index();
896    if object_type_index == target_type_index {
897        return true;
898    }
899    // A final type cannot have a separately registered subtype. Keep common
900    // borrowed checks, such as `IntImmObj`, to one integer comparison.
901    if Target::TYPE_FINAL {
902        return false;
903    }
904    let object_begin = TypeIndex::kTVMFFIStaticObjectBegin as i32;
905    // Only object types participate in the type hierarchy.
906    if object_type_index < object_begin || target_type_index < object_begin {
907        return false;
908    }
909    // Only the root Object type has depth zero.
910    if const { Target::TYPE_DEPTH == 0 } {
911        return true;
912    }
913    // Parent indices are always smaller than their descendants.
914    if object_type_index < target_type_index {
915        return false;
916    }
917    unsafe {
918        let object_info = TVMFFIGetTypeInfo(object_type_index);
919        if object_info.is_null() {
920            return false;
921        }
922        let target_depth = Target::TYPE_DEPTH;
923        if (*object_info).type_depth <= target_depth {
924            return false;
925        }
926        let ancestor = *(*object_info).type_acenstors.add(target_depth as usize);
927        !ancestor.is_null() && (*ancestor).type_index == target_type_index
928    }
929}
930
931/// Format a managed reference as its runtime type key and object address, as
932/// the `Debug` implementation of `#[derive(ObjectRef)]` does.
933///
934/// Call it from `Debug` for a reference type implemented by hand, such as a
935/// typed view over another reference, so that `downcast(..).unwrap()` and
936/// `assert_eq!` can print it.
937///
938/// ```
939/// use tvm_ffi::object::{fmt_object_ref, ObjectRef};
940/// use tvm_ffi::Array;
941/// struct Shown(ObjectRef);
942/// impl std::fmt::Debug for Shown {
943///     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
944///         fmt_object_ref(&self.0, f)
945///     }
946/// }
947/// let shown = Shown(Array::from_vec(vec![1_i64]).into());
948/// assert!(format!("{shown:?}").starts_with("ffi.Array@"));
949/// ```
950pub fn fmt_object_ref<T: ObjectRefCore>(
951    this: &T,
952    f: &mut std::fmt::Formatter<'_>,
953) -> std::fmt::Result {
954    let object = ObjectArc::as_ptr(T::data(this)).cast::<TVMFFIObject>();
955    // SAFETY: `this` keeps the object, and so its header, alive.
956    let type_index = unsafe { (*object).type_index };
957    write!(f, "{}@{:p}", type_key_of_index(type_index), object)
958}
959
960// -----------------------------------------------------------------------------
961// Helpers
962// -----------------------------------------------------------------------------
963
964/// The strict downcast from the root [`ObjectRef`] to `B`, for the containers'
965/// `TryFrom<ObjectRef>`, which are hand-written as their upcasts are.
966#[inline(always)]
967pub(crate) fn root_try_into<B>(value: ObjectRef) -> crate::error::Result<B>
968where
969    B: ObjectRefCore,
970{
971    value
972        .downcast::<B>()
973        .map_err(crate::error::Error::downcast_failed::<B>)
974}
975
976/// [`root_try_into`] from a borrowed reference, cloning only on success.
977#[inline(always)]
978pub(crate) fn root_try_into_ref<B>(value: &ObjectRef) -> crate::error::Result<B>
979where
980    B: ObjectRefCore + crate::type_traits::DowncastRefFromObject,
981{
982    match value.downcast_ref::<B>() {
983        Some(found) => Ok(found.clone()),
984        None => Err(crate::error::Error::downcast_failed::<B>(value.clone())),
985    }
986}
987
988/// Upcast a managed reference to the root [`ObjectRef`], keeping its allocation.
989#[inline(always)]
990pub(crate) fn into_root_object_ref<S: ObjectRefCore>(value: S) -> ObjectRef {
991    let data = S::into_data(value);
992    // SAFETY: every object starts with the root `Object` header, and an
993    // `ObjectRef` imposes no further invariant.
994    unsafe {
995        ObjectRef::from_data(ObjectArc::from_raw(
996            ObjectArc::into_raw(data).cast::<Object>(),
997        ))
998    }
999}
1000
1001/// The type key of `type_index`, the type index of a value, which the runtime
1002/// always registers.
1003#[inline]
1004pub(crate) fn registered_type_key(type_index: i32) -> &'static str {
1005    // SAFETY: a value's type index is registered, and type information lives
1006    // as long as the process; a type key is UTF-8 text.
1007    unsafe { (*TVMFFIGetTypeInfo(type_index)).type_key.as_str() }
1008}
1009
1010/// The registered type key of `type_index`, or `<type_index N>` when it has none.
1011pub(crate) fn type_key_of_index(type_index: i32) -> String {
1012    match crate::reflection::type_key(type_index) {
1013        Some(key) => key.to_string(),
1014        None => format!("<type_index {type_index}>"),
1015    }
1016}
1017
1018/// Write the object cell of the live object `ptr`.
1019#[inline(always)]
1020unsafe fn write_object_cell<T: ObjectCore>(ptr: *const T, data: &mut TVMFFIAny) {
1021    let object = ptr as *mut TVMFFIObject;
1022    data.type_index = unsafe { (*object).type_index };
1023    // SAFETY: a live object's header holds its registered object-range type index.
1024    unsafe {
1025        std::hint::assert_unchecked(data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32)
1026    };
1027    data.small_str_len = 0;
1028    data.data_union.v_obj = object;
1029}
1030
1031// Allocate and initialize the normal FFI header while preserving the concrete
1032// payload's alignment and drop/layout deleter. The payload starts with an Object.
1033unsafe fn allocate_object<T>(data: T, type_index: i32) -> NonNull<T> {
1034    let layout = std::alloc::Layout::new::<T>();
1035    let allocation = unsafe { std::alloc::alloc(layout) };
1036    if allocation.is_null() {
1037        std::alloc::handle_alloc_error(layout);
1038    }
1039    let ptr = allocation.cast::<T>();
1040    unsafe { std::ptr::write(ptr, data) };
1041    unsafe {
1042        std::ptr::write(
1043            ptr.cast::<TVMFFIObject>(),
1044            TVMFFIObject {
1045                combined_ref_count: AtomicU64::new(COMBINED_REF_COUNT_BOTH_ONE),
1046                type_index,
1047                __padding: 0,
1048                deleter: Some(unsafe_::object_deleter_for_new::<T>),
1049            },
1050        )
1051    };
1052    unsafe { NonNull::new_unchecked(ptr) }
1053}
1054
1055/// Unsafe reference-count operations on raw object headers.
1056#[doc(hidden)]
1057pub mod unsafe_ {
1058    use tvm_ffi_sys::{
1059        COMBINED_REF_COUNT_BOTH_ONE, COMBINED_REF_COUNT_MASK_U32, COMBINED_REF_COUNT_STRONG_ONE,
1060        COMBINED_REF_COUNT_WEAK_ONE,
1061    };
1062
1063    use std::ffi::c_void;
1064    use std::sync::atomic::{Ordering, fence};
1065    use tvm_ffi_sys::TVMFFIObject;
1066    use tvm_ffi_sys::TVMFFIObjectDeleterFlagBitMask::{
1067        kTVMFFIObjectDeleterFlagBitMaskBoth, kTVMFFIObjectDeleterFlagBitMaskStrong,
1068        kTVMFFIObjectDeleterFlagBitMaskWeak,
1069    };
1070
1071    /// Increase the strong reference count of `handle`.
1072    #[inline]
1073    pub(crate) unsafe fn inc_ref(handle: *mut TVMFFIObject) {
1074        let obj = unsafe { &*handle };
1075        obj.combined_ref_count.fetch_add(1, Ordering::Relaxed);
1076    }
1077
1078    /// Decrease the strong reference count of `handle`, deleting the object when it was the last.
1079    #[inline]
1080    pub(crate) unsafe fn dec_ref(handle: *mut TVMFFIObject) {
1081        // Release publishes this owner's writes; the Acquire fence before the deleter pairs with it.
1082        let old_combined_count = unsafe {
1083            (*handle)
1084                .combined_ref_count
1085                .fetch_sub(COMBINED_REF_COUNT_STRONG_ONE, Ordering::Release)
1086        };
1087        if old_combined_count == COMBINED_REF_COUNT_BOTH_ONE {
1088            fence(Ordering::Acquire);
1089            if let Some(deleter) = unsafe { (*handle).deleter } {
1090                unsafe {
1091                    deleter(
1092                        handle.cast::<c_void>(),
1093                        kTVMFFIObjectDeleterFlagBitMaskBoth as i32,
1094                    )
1095                };
1096            }
1097        } else if (old_combined_count & COMBINED_REF_COUNT_MASK_U32)
1098            == COMBINED_REF_COUNT_STRONG_ONE
1099        {
1100            // slow path, there is still a weak reference left
1101            // need to run two phase decrement
1102            fence(Ordering::Acquire);
1103            if let Some(deleter) = unsafe { (*handle).deleter } {
1104                unsafe {
1105                    deleter(
1106                        handle.cast::<c_void>(),
1107                        kTVMFFIObjectDeleterFlagBitMaskStrong as i32,
1108                    )
1109                };
1110            }
1111            let old_weak_count = unsafe {
1112                (*handle)
1113                    .combined_ref_count
1114                    .fetch_sub(COMBINED_REF_COUNT_WEAK_ONE, Ordering::Release)
1115            };
1116            if old_weak_count == COMBINED_REF_COUNT_WEAK_ONE {
1117                fence(Ordering::Acquire);
1118                if let Some(deleter) = unsafe { (*handle).deleter } {
1119                    unsafe {
1120                        deleter(
1121                            handle.cast::<c_void>(),
1122                            kTVMFFIObjectDeleterFlagBitMaskWeak as i32,
1123                        )
1124                    };
1125                }
1126            }
1127        }
1128    }
1129
1130    #[inline]
1131    pub(crate) unsafe fn strong_count(handle: *mut TVMFFIObject) -> usize {
1132        let obj = unsafe { &*handle };
1133        (obj.combined_ref_count.load(Ordering::Relaxed) & COMBINED_REF_COUNT_MASK_U32) as usize
1134    }
1135
1136    /// Whether `handle` is the only strong reference, so it may be mutated in
1137    /// place. Any weak reference rejects it, as a weak handle could upgrade and
1138    /// observe the write.
1139    #[inline]
1140    pub(crate) unsafe fn is_unique(handle: *mut TVMFFIObject) -> bool {
1141        // Acquire pairs with the releasing decrement: other owners' accesses precede an in-place write.
1142        unsafe {
1143            (*handle).combined_ref_count.load(Ordering::Acquire) == COMBINED_REF_COUNT_BOTH_ONE
1144        }
1145    }
1146
1147    #[inline]
1148    pub(crate) unsafe fn weak_count(handle: *mut TVMFFIObject) -> usize {
1149        let obj = unsafe { &*handle };
1150        (obj.combined_ref_count.load(Ordering::Relaxed) >> 32) as usize
1151    }
1152
1153    /// Generic object deleter for objects allocated through Rust's global allocator.
1154    pub(crate) unsafe extern "C" fn object_deleter_for_new<T>(ptr: *mut c_void, flags: i32) {
1155        let obj = ptr as *mut T;
1156        if flags & kTVMFFIObjectDeleterFlagBitMaskStrong as i32 != 0 {
1157            unsafe { std::ptr::drop_in_place(obj) };
1158        }
1159        if flags & kTVMFFIObjectDeleterFlagBitMaskWeak as i32 != 0 {
1160            unsafe { std::alloc::dealloc(ptr as *mut u8, std::alloc::Layout::new::<T>()) };
1161        }
1162    }
1163
1164    /// Layout of a `T` followed by `count` extra items, kept at least one word past the
1165    /// header: once a weak reference outlives the data, the deleter stores `count` there.
1166    /// Panics with "capacity overflow" (like `Vec`) when the size does not fit in `isize`.
1167    pub(crate) fn extra_items_layout<T, U>(count: usize) -> std::alloc::Layout {
1168        use std::alloc::Layout;
1169        let min_size = std::mem::size_of::<TVMFFIObject>() + std::mem::size_of::<u64>();
1170        Layout::array::<U>(count)
1171            .and_then(|items| Layout::new::<T>().extend(items))
1172            .and_then(|(layout, _)| {
1173                Layout::from_size_align(layout.size().max(min_size), layout.align())
1174            })
1175            .expect("capacity overflow")
1176    }
1177
1178    pub(crate) unsafe extern "C" fn object_deleter_for_new_with_extra_items<T, U>(
1179        ptr: *mut c_void,
1180        flags: i32,
1181    ) where
1182        T: super::ObjectCoreWithExtraItems<ExtraItem = U>,
1183    {
1184        let obj = ptr as *mut T;
1185        if flags == kTVMFFIObjectDeleterFlagBitMaskBoth as i32 {
1186            let extra_items_count = unsafe { T::extra_items_count(&(*obj)) };
1187            unsafe { std::ptr::drop_in_place(obj) };
1188            unsafe {
1189                std::alloc::dealloc(
1190                    ptr as *mut u8,
1191                    extra_items_layout::<T, U>(extra_items_count),
1192                )
1193            };
1194        } else {
1195            // Weak references keep using the header, so the weak phase finds the item
1196            // count in the first word after it.
1197            let count_slot =
1198                unsafe { (ptr as *mut u8).add(std::mem::size_of::<TVMFFIObject>()) as *mut u64 };
1199            if flags & kTVMFFIObjectDeleterFlagBitMaskStrong as i32 != 0 {
1200                let extra_items_count = unsafe { T::extra_items_count(&(*obj)) };
1201                unsafe { std::ptr::drop_in_place(obj) };
1202                unsafe { std::ptr::write(count_slot, extra_items_count as u64) };
1203            }
1204            if flags & kTVMFFIObjectDeleterFlagBitMaskWeak as i32 != 0 {
1205                let extra_items_count = unsafe { std::ptr::read(count_slot) as usize };
1206                unsafe {
1207                    std::alloc::dealloc(
1208                        ptr as *mut u8,
1209                        extra_items_layout::<T, U>(extra_items_count),
1210                    )
1211                };
1212            }
1213        }
1214    }
1215}