//! Type-erased, reference-counted smart pointer with runtime borrow checking.

//!

//! # Safety

//!

//! This module provides `RefAny`, a type-erased container similar to `Arc<RefCell<dyn Any>>`,

//! but designed for FFI compatibility and cross-language interoperability.

//!

//! ## Memory Safety Guarantees

//!

//! 1. **Proper Alignment**: Fixed in commit addressing Miri UB - memory is allocated with correct

//!    alignment for the stored type using `Layout::from_size_align()`.

//!

//! 2. **Atomic Reference Counting**: All reference counts use `AtomicUsize` with `SeqCst` ordering,

//!    ensuring thread-safe access and preventing use-after-free.

//!

//! 3. **Runtime Type Safety**: Type IDs are checked before downcasting, preventing invalid pointer

//!    casts that would cause undefined behavior.

//!

//! 4. **Runtime Borrow Checking**: Shared and mutable borrows are tracked at runtime, enforcing

//!    Rust's borrowing rules dynamically (similar to `RefCell`).

//!

//! ## Thread Safety

//!

//! - `RefAny` is `Send`: Can be transferred between threads (data is heap-allocated)

//! - `RefAny` is `Sync`: Can be shared between threads (atomic operations + `&mut self` for

//!   borrows)

//!

//! The `SeqCst` (Sequentially Consistent) memory ordering provides the strongest guarantees:

//! all atomic operations appear in a single global order visible to all threads, preventing

//! race conditions where one thread doesn't see another's reference count updates.

use alloc::boxed::Box;

use alloc::string::String;

use core::{

    alloc::Layout,

    ffi::c_void,

    fmt,

    sync::atomic::{AtomicUsize, Ordering as AtomicOrdering},

};

use azul_css::AzString;

/// C-compatible destructor function type for RefAny.

/// Called when the last reference to a RefAny is dropped.

pub type RefAnyDestructorType = extern "C" fn(*mut c_void);

// NOTE: JSON serialization/deserialization callback types are defined in azul_layout::json

// The actual types are:

//   RefAnySerializeFnType = extern "C" fn(RefAny) -> Json

//   RefAnyDeserializeFnType = extern "C" fn(Json) -> ResultRefAnyString

// In azul_core, we only store function pointers as usize (0 = not set).

/// Internal reference counting metadata for `RefAny`.

///

/// This struct tracks:

///

/// - How many `RefAny` clones exist (`num_copies`)

/// - How many shared borrows are active (`num_refs`)

/// - How many mutable borrows are active (`num_mutable_refs`)

/// - Memory layout information for correct deallocation

/// - Type information for runtime type checking

///

/// # Thread Safety

///

/// All counters are `AtomicUsize` with `SeqCst` ordering, making them safe to access

/// from multiple threads simultaneously. The strong ordering ensures no thread can

/// observe inconsistent states (e.g., both seeing count=1 during final drop).

#[derive(Debug)]

#[repr(C)]

pub struct RefCountInner {

    /// Type-erased pointer to heap-allocated data.

    ///

    /// SAFETY: Must be properly aligned for the stored type (guaranteed by

    /// `Layout::from_size_align` in `new_c`). Never null for non-ZST types.

    ///

    /// This pointer is shared by all RefAny clones, so replace_contents

    /// updates are visible to all clones.

    pub _internal_ptr: *const c_void,

    /// Number of `RefAny` instances sharing the same data.

    /// When this reaches 0, the data is deallocated.

    pub num_copies: AtomicUsize,

    /// Number of active shared borrows (`Ref<T>`).

    /// While > 0, mutable borrows are forbidden.

    pub num_refs: AtomicUsize,

    /// Number of active mutable borrows (`RefMut<T>`).

    /// While > 0, all other borrows are forbidden.

    pub num_mutable_refs: AtomicUsize,

    /// Size of the stored type in bytes (from `size_of::<T>()`).

    pub _internal_len: usize,

    /// Layout size for deallocation (from `Layout::size()`).

    pub _internal_layout_size: usize,

    /// Required alignment for the stored type (from `align_of::<T>()`).

    /// CRITICAL: Must match the alignment used during allocation to prevent UB.

    pub _internal_layout_align: usize,

    /// Runtime type identifier computed from `TypeId::of::<T>()`.

    /// Used to prevent invalid downcasts.

    pub type_id: u64,

    /// Human-readable type name (e.g., "MyStruct") for debugging.

    pub type_name: AzString,

    /// Function pointer to correctly drop the type-erased data.

    /// SAFETY: Must be called with a pointer to data of the correct type.

    pub custom_destructor: extern "C" fn(*mut c_void),

    /// Function pointer to serialize RefAny to JSON (0 = not set).

    /// Cast to RefAnySerializeFnType (defined in azul_layout::json) when called.

    /// Type: extern "C" fn(RefAny) -> Json

    pub serialize_fn: usize,

    /// Function pointer to deserialize JSON to new RefAny (0 = not set).

    /// Cast to RefAnyDeserializeFnType (defined in azul_layout::json) when called.

    /// Type: extern "C" fn(Json) -> ResultRefAnyString

    pub deserialize_fn: usize,

}

/// Wrapper around a heap-allocated `RefCountInner`.

///

/// This is the shared metadata that all `RefAny` clones point to.

/// The `RefCount` is responsible for all memory management:

///

/// - `RefCount::clone()` increments `num_copies` in RefCountInner

/// - `RefCount::drop()` decrements `num_copies` and, if it reaches 0:

///   1. Frees the RefCountInner

///   2. Calls the custom destructor on the data

///   3. Deallocates the data memory

///

/// # Why `run_destructor: bool`

///

/// This flag tracks whether this `RefCount` instance should decrement

/// `num_copies` when dropped. Set to `true` for all clones (including

/// those created by `RefAny::clone()` and `AZ_REFLECT` macros).

/// Set to `false` after the decrement has been performed to prevent

/// double-decrement.

#[derive(Hash, PartialEq, PartialOrd, Ord, Eq)]

#[repr(C)]

pub struct RefCount {

    pub ptr: *const RefCountInner,

    pub run_destructor: bool,

}

impl fmt::Debug for RefCount {

}

impl Clone for RefCount {

    /// Clones the RefCount and increments the reference count.

    ///

    /// # Safety

    ///

    /// This is safe because:

    /// - The ptr is valid (created from Box::into_raw)

    /// - num_copies is atomically incremented with SeqCst ordering

    /// - This ensures the RefCountInner is not freed while clones exist

        // CRITICAL: Must increment num_copies so the RefCountInner is not freed

        // while this clone exists. The C macros (AZ_REFLECT) use AzRefCount_clone

        // to create Ref/RefMut guards, and those guards must keep the data alive.

}

impl Drop for RefCount {

    /// Decrements the reference count when a RefCount clone is dropped.

    ///

    /// If this was the last reference (num_copies reaches 0), this will also

    /// free the RefCountInner and call the custom destructor.

        // Only decrement if run_destructor is true (meaning this is a clone)

        // and the pointer is valid

        // Atomically decrement and get the PREVIOUS value

        };

        // If previous value wasn't 1, other references still exist

        // We're the last reference! Clean up.

        // SAFETY: ptr came from Box::into_raw, and we're the last reference

        // Get the data pointer

        // Handle zero-sized types specially

            // Reconstruct the layout used during allocation

                )

            };

            // Phase 1: Run the custom destructor

            // Phase 2: Deallocate the memory

        }

}

/// Debug-friendly snapshot of `RefCountInner` with non-atomic values.

#[derive(Debug, Clone)]

pub(crate) struct RefCountInnerDebug {

    pub(crate) num_copies: usize,

    pub(crate) num_refs: usize,

    pub(crate) num_mutable_refs: usize,

    pub(crate) _internal_len: usize,

    pub(crate) _internal_layout_size: usize,

    pub(crate) _internal_layout_align: usize,

    pub(crate) type_id: u64,

    pub(crate) type_name: AzString,

    pub(crate) custom_destructor: usize,

    /// Serialization function pointer (0 = not set)

    pub(crate) serialize_fn: usize,

    /// Deserialization function pointer (0 = not set)

    pub(crate) deserialize_fn: usize,

}

impl RefCount {

    /// Creates a new `RefCount` by boxing the metadata on the heap.

    ///

    /// # Safety

    ///

    /// Safe because we're creating a new allocation with `Box::new`,

    /// then immediately leaking it with `into_raw` to get a stable pointer.

    /// Dereferences the raw pointer to access the metadata.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - The pointer is created from `Box::into_raw`, so it's valid and properly aligned

    /// - The lifetime is tied to `&self`, ensuring the pointer is still alive

    /// - Reference counting ensures the data isn't freed while references exist

    /// Creates a debug snapshot of the current reference counts.

    ///

    /// Loads all atomic values with `SeqCst` ordering to get a consistent view.

    /// Runtime check: can we create a shared borrow?

    ///

    /// Returns `true` if there are no active mutable borrows.

    /// Multiple shared borrows can coexist (like `&T` in Rust).

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure we see the most recent state from all threads.

    /// If another thread just released a mutable borrow, we'll see it.

    /// Runtime check: can we create a mutable borrow?

    ///

    /// Returns `true` only if there are ZERO active borrows of any kind.

    /// This enforces Rust's exclusive mutability rule (like `&mut T`).

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure we see all recent borrows from all threads.

    /// Both counters must be checked atomically to prevent races.

    /// Increments the shared borrow counter.

    ///

    /// Called when a `Ref<T>` is created. The `Ref::drop` will decrement it.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this increment is visible to all threads before they

    /// try to acquire a mutable borrow (which checks this counter).

    /// Decrements the shared borrow counter.

    ///

    /// Called when a `Ref<T>` is dropped, indicating the borrow is released.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this decrement is immediately visible to other threads

    /// waiting to acquire a mutable borrow.

    /// Increments the mutable borrow counter.

    ///

    /// Called when a `RefMut<T>` is created. Should only succeed when this

    /// counter and `num_refs` are both 0.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this increment is visible to all other threads,

    /// blocking them from acquiring any borrow (shared or mutable).

    /// Decrements the mutable borrow counter.

    ///

    /// Called when a `RefMut<T>` is dropped, releasing exclusive access.

    ///

    /// # Memory Ordering

    ///

    /// `SeqCst` ensures this decrement is immediately visible, allowing

    /// other threads to acquire borrows.

}

/// RAII guard for a shared borrow of type `T` from a `RefAny`.

///

/// Similar to `std::cell::Ref`, this automatically decrements the borrow

/// counter when dropped, ensuring borrows are properly released.

///

/// # Deref

///

/// Implements `Deref<Target = T>` so you can use it like `&T`.

#[derive(Debug)]

#[repr(C)]

pub struct Ref<'a, T> {

    ptr: &'a T,

    sharing_info: RefCount,

}

impl<'a, T> Drop for Ref<'a, T> {

    /// Automatically releases the shared borrow when the guard goes out of scope.

    ///

    /// # Safety

    ///

    /// Safe because `decrease_ref` uses atomic operations and is designed to be

    /// called exactly once per `Ref` instance.

}

impl<'a, T> core::ops::Deref for Ref<'a, T> {

    type Target = T;

}

/// RAII guard for a mutable borrow of type `T` from a `RefAny`.

///

/// Similar to `std::cell::RefMut`, this automatically decrements the mutable

/// borrow counter when dropped, releasing exclusive access.

///

/// # Deref / DerefMut

///

/// Implements both `Deref` and `DerefMut` so you can use it like `&mut T`.

#[derive(Debug)]

#[repr(C)]

pub struct RefMut<'a, T> {

    ptr: &'a mut T,

    sharing_info: RefCount,

}

impl<'a, T> Drop for RefMut<'a, T> {

    /// Automatically releases the mutable borrow when the guard goes out of scope.

    ///

    /// # Safety

    ///

    /// Safe because `decrease_refmut` uses atomic operations and is designed to be

    /// called exactly once per `RefMut` instance.

}

impl<'a, T> core::ops::Deref for RefMut<'a, T> {

    type Target = T;

}

impl<'a, T> core::ops::DerefMut for RefMut<'a, T> {

}

/// Type-erased, reference-counted smart pointer with runtime borrow checking.

///

/// `RefAny` is similar to `Arc<RefCell<dyn Any>>`, providing:

/// - Type erasure (stores any `'static` type)

/// - Reference counting (clones share the same data)

/// - Runtime borrow checking (enforces Rust's borrowing rules at runtime)

/// - FFI compatibility (`#[repr(C)]` and C-compatible API)

///

/// # Thread Safety

///

/// - `Send`: Can be moved between threads (heap-allocated data, atomic counters)

/// - `Sync`: Can be shared between threads (`downcast_ref/mut` require `&mut self`)

///

/// # Memory Safety

///

/// Fixed critical UB bugs in alignment, copy count, and pointer provenance.

/// All operations are verified with Miri to ensure absence of undefined behavior.

///

/// # Usage

///

/// ```rust

/// # use azul_core::refany::RefAny;

/// let data = RefAny::new(42i32);

/// let mut data_clone = data.clone(); // shares the same heap allocation

///

/// // Runtime-checked downcasting with type safety

/// if let Some(value_ref) = data_clone.downcast_ref::<i32>() {

///     assert_eq!(*value_ref, 42);

/// };

///

/// // Runtime-checked mutable borrowing

/// if let Some(mut value_mut) = data_clone.downcast_mut::<i32>() {

///     *value_mut = 100;

/// };

/// ```

#[derive(Debug, Hash, PartialEq, PartialOrd, Ord, Eq)]

#[repr(C)]

pub struct RefAny {

    /// Shared metadata: reference counts, type info, destructor, AND data pointer.

    ///

    /// All `RefAny` clones point to the same `RefCountInner` via this field.

    /// The data pointer is stored in RefCountInner so all clones see the same

    /// pointer, even after replace_contents() is called.

    ///

    /// The `run_destructor` flag on `RefCount` controls whether dropping this

    /// RefAny should decrement the reference count and potentially free memory.

    pub sharing_info: RefCount,

    /// Unique ID for this specific clone (root = 0, subsequent clones increment).

    ///

    /// Used to distinguish between the original and clones for debugging.

    pub instance_id: u64,

}

impl_option!(

    RefAny,

    OptionRefAny,

    copy = false,

    [Debug, Hash, Clone, PartialEq, PartialOrd, Ord, Eq]

);

// SAFETY: RefAny is Send because:

// - The data pointer points to heap memory (can be sent between threads)

// - All shared state (RefCountInner) uses atomic operations

// - No thread-local storage is used

unsafe impl Send for RefAny {}

// SAFETY: RefAny is Sync because:

// - Methods on `&RefAny` (like `clone`, `get_type_id`) only use atomic operations or

//   read immutable data, which is inherently thread-safe

// - The runtime borrow checker (via `can_be_shared/shared_mut`) uses SeqCst atomics

//

// KNOWN ISSUE: `downcast_ref/mut` require `&mut self`, but clones of the same RefAny

// are independent values that can each provide `&mut self` concurrently while sharing

// the same `RefCountInner`. The check-then-increment in downcast_ref/mut is not atomic,

// so concurrent borrows via different clones can race. See replace_contents() for the

// correct compare_exchange pattern.

unsafe impl Sync for RefAny {}

impl RefAny {

    /// Creates a new type-erased `RefAny` containing the given value.

    ///

    /// This is the primary way to construct a `RefAny` from Rust code.

    ///

    /// # Type Safety

    ///

    /// Stores the `TypeId` of `T` for runtime type checking during downcasts.

    ///

    /// # Memory Layout

    ///

    /// - Allocates memory on the heap with correct size (`size_of::<T>()`) and alignment

    ///   (`align_of::<T>()`)

    /// - Copies the value into the heap allocation

    /// - Forgets the original value to prevent double-drop

    ///

    /// # Custom Destructor

    ///

    /// Creates a type-specific destructor that:

    /// 1. Copies the data from heap back to stack

    /// 2. Calls `mem::drop` to run `T`'s destructor

    /// 3. The heap memory is freed separately in `RefAny::drop`

    ///

    /// This two-phase destruction ensures proper cleanup even for complex types.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - `mem::forget` prevents double-drop of the original value

    /// - Type `T` and destructor `<U>` are matched at compile time

    /// - `ptr::copy_nonoverlapping` with count=1 copies exactly one `T`

    ///

    /// # Example

    ///

    /// ```rust

    /// # use azul_core::refany::RefAny;

    /// let mut data = RefAny::new(42i32);

    /// let value = data.downcast_ref::<i32>().unwrap();

    /// assert_eq!(*value, 42);

    /// ```

        /// Type-specific destructor that properly drops the inner value.

        ///

        /// # Safety

        ///

        /// Safe to call ONLY with a pointer that was created by `RefAny::new<U>`.

        /// The type `U` must match the original type `T`.

        ///

        /// # Why Copy to Stack?

        ///

        /// Rust's drop glue expects a value, not a pointer. We copy the data

        /// to the stack so `mem::drop` can run the destructor properly.

        ///

        /// # Critical Fix

        ///

        /// The third argument to `copy_nonoverlapping` is the COUNT (1 element),

        /// not the SIZE in bytes. Using `size_of::<U>()` here would copy

        /// `size_of::<U>()` elements, causing buffer overflow.

            use core::{mem, ptr};

            0, // serialize_fn: not set for Rust types by default

            0, // deserialize_fn: not set for Rust types by default

        );

    /// C-ABI compatible function to create a `RefAny` from raw components.

    ///

    /// This is the low-level constructor used by FFI bindings (C, Python, etc.).

    ///

    /// # Parameters

    ///

    /// - `ptr`: Pointer to the value to store (will be copied)

    /// - `len`: Size of the value in bytes (`size_of::<T>()`)

    /// - `align`: Required alignment in bytes (`align_of::<T>()`)

    /// - `type_id`: Unique identifier for the type (for downcast safety)

    /// - `type_name`: Human-readable type name (for debugging)

    /// - `custom_destructor`: Function to call when the last reference is dropped

    /// - `serialize_fn`: Function pointer for JSON serialization (0 = not set)

    /// - `deserialize_fn`: Function pointer for JSON deserialization (0 = not set)

    ///

    /// # Safety

    ///

    /// Caller must ensure:

    /// - `ptr` points to valid data of size `len` with alignment `align`

    /// - `type_id` uniquely identifies the type

    /// - `custom_destructor` correctly drops the type at `ptr`

    /// - `len` and `align` match the actual type's layout

    /// - If `serialize_fn != 0`, it must be a valid function pointer of type

    ///   `extern "C" fn(RefAny) -> Json`

    /// - If `deserialize_fn != 0`, it must be a valid function pointer of type

    ///   `extern "C" fn(Json) -> ResultRefAnyString`

    ///

    /// # Zero-Sized Types

    ///

    /// Special case: ZSTs use a null pointer but still track the type info

    /// and call the destructor (which may have side effects even for ZSTs).

        use core::ptr;

        // CRITICAL: Validate input pointer for non-ZST types

        // A NULL pointer for a non-zero-sized type would cause UB when copying

                len,

            );

        // Special case: Zero-sized types

        //

        // Calling `alloc(Layout { size: 0, .. })` is UB, so we use a null pointer.

        // The destructor is still called (it may have side effects even for ZSTs).

        } else {

            // CRITICAL FIX: Use the caller-provided alignment, not alignment of [u8]

            //

            // Previous bug: `Layout::for_value(&[u8])` created align=1

            // This caused unaligned references when downcasting to types like i32 (align=4)

            //

            // Fixed: `Layout::from_size_align(len, align)` respects the type's alignment

            // Allocate heap memory with correct alignment

            // Handle allocation failure (aborts the program)

            // Copy the data byte-by-byte to the heap

            // SAFETY: Both pointers are valid, non-overlapping, and properly aligned

        };

    /// Returns the raw data pointer for FFI downcasting.

    ///

    /// This is used by the AZ_REFLECT macros in C/C++ to access the

    /// type-erased data pointer for downcasting operations.

    ///

    /// # Safety

    ///

    /// The returned pointer must only be dereferenced after verifying

    /// the type ID matches the expected type. Callers are responsible

    /// for proper type safety checks.

    /// Returns the byte length of the type-erased payload behind

    /// [`Self::get_data_ptr`] (`size_of::<T>()` of the stored type;

    /// `0` for ZSTs).

    /// Checks if this is the only `RefAny` instance with no active borrows.

    ///

    /// Returns `true` only if:

    /// - `num_copies == 1` (no clones exist)

    /// - `num_refs == 0` (no shared borrows active)

    /// - `num_mutable_refs == 0` (no mutable borrows active)

    ///

    /// Useful for checking if you have exclusive ownership.

    ///

    /// # Memory Ordering

    ///

    /// Uses `SeqCst` to ensure a consistent view across all three counters.

    /// Attempts to downcast to a shared reference of type `U`.

    ///

    /// Returns `None` if:

    /// - The stored type doesn't match `U` (type safety)

    /// - A mutable borrow is already active (borrow checking)

    /// - The pointer is null (ZST or uninitialized)

    ///

    /// # Type Safety

    ///

    /// Compares `type_id` at runtime before casting. This prevents casting

    /// `*const c_void` to the wrong type, which would be immediate UB.

    ///

    /// # Borrow Checking

    ///

    /// Checks `can_be_shared()` to enforce Rust's borrowing rules:

    /// - Multiple shared borrows are allowed

    /// - Shared and mutable borrows cannot coexist

    ///

    /// # Safety

    ///

    /// The `unsafe` cast is safe because:

    /// - Type ID check ensures `U` matches the stored type

    /// - Memory was allocated with correct alignment for `U`

    /// - Lifetime `'a` is tied to `&'a mut self`, preventing use-after-free

    /// - Reference count is incremented atomically before returning

    ///

    /// # Why `&mut self`?

    ///

    /// Requires `&mut self` to prevent multiple threads from calling this

    /// simultaneously on the same `RefAny`. The borrow checker enforces this.

    /// Clones of the `RefAny` can call this independently (they share data

    /// but have separate runtime borrow tracking).

    #[inline]

        // Runtime type check: prevent downcasting to wrong type

        // Runtime borrow check: ensure no mutable borrows exist

        // Get data pointer from shared RefCountInner

        // Null check: ZSTs or uninitialized

        // Increment shared borrow count atomically

    /// Attempts to downcast to a mutable reference of type `U`.

    ///

    /// Returns `None` if:

    /// - The stored type doesn't match `U` (type safety)

    /// - Any borrow is already active (borrow checking)

    /// - The pointer is null (ZST or uninitialized)

    ///

    /// # Type Safety

    ///

    /// Compares `type_id` at runtime before casting, preventing UB.

    ///

    /// # Borrow Checking

    ///

    /// Checks `can_be_shared_mut()` to enforce exclusive mutability:

    /// - No other borrows (shared or mutable) can be active

    /// - This is Rust's `&mut T` rule, enforced at runtime

    ///

    /// # Safety

    ///

    /// The `unsafe` cast is safe because:

    ///

    /// - Type ID check ensures `U` matches the stored type

    /// - Memory was allocated with correct alignment for `U`

    /// - Borrow check ensures no other references exist

    /// - Lifetime `'a` is tied to `&'a mut self`, preventing aliasing

    /// - Mutable reference count is incremented atomically

    ///

    /// # Memory Ordering

    ///

    /// The `increase_refmut()` uses `SeqCst`, ensuring other threads see

    /// this mutable borrow before they try to acquire any borrow.

    #[inline]

        // Runtime type check

        // Runtime exclusive borrow check

        // Get data pointer from shared RefCountInner

        // Null check

        // Increment mutable borrow count atomically

    /// Computes a runtime type ID from Rust's `TypeId`.

    ///

    /// Rust's `TypeId` is not `#[repr(C)]` and can't cross FFI boundaries.

    /// This function converts it to a `u64` by treating it as a byte array.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - `TypeId` is a valid type with a stable layout

    /// - We only read from it, never write

    /// - The slice lifetime is bounded by the function scope

    ///

    /// # Implementation

    ///

    /// Treats the `TypeId` as bytes and sums them with bit shifts to create

    /// a unique (but not cryptographically secure) hash.

    #[inline]

        use core::{any::TypeId, mem};

        // SAFETY: TypeId is a valid type, we're only reading it

            )

        };

        // Convert first 8 bytes to u64 using proper bit positions

    /// Checks if the stored type matches the given type ID.

    /// Returns the stored type ID.

    /// Returns the human-readable type name for debugging.

    /// Returns the current reference count (number of `RefAny` clones sharing this data).

    ///

    /// This is useful for debugging and metadata purposes.

    /// Returns the serialize function pointer (0 = not set).

    /// 

    /// This is used for JSON serialization of RefAny contents.

    /// Returns the deserialize function pointer (0 = not set).

    /// 

    /// This is used for JSON deserialization to create a new RefAny.

    /// Sets the serialize function pointer.

    ///

    /// # Safety

    ///

    /// The caller must ensure the function pointer is valid and has the correct

    /// signature: `extern "C" fn(RefAny) -> Json`

    ///

    /// **Known issue:** `&mut self` is exclusive to this clone, not to the shared

    /// `RefCountInner`. Concurrent calls via different clones are a data race

    /// because `serialize_fn` is a plain `usize`, not atomic.

        // FIXME: &mut self is exclusive to this clone only, not to the shared

        // RefCountInner — concurrent calls via different clones are a data race.

    /// Sets the deserialize function pointer.

    ///

    /// # Safety

    ///

    /// The caller must ensure the function pointer is valid and has the correct

    /// signature: `extern "C" fn(Json) -> ResultRefAnyString`

    ///

    /// **Known issue:** `&mut self` is exclusive to this clone, not to the shared

    /// `RefCountInner`. Concurrent calls via different clones are a data race

    /// because `deserialize_fn` is a plain `usize`, not atomic.

        // FIXME: &mut self is exclusive to this clone only, not to the shared

        // RefCountInner — concurrent calls via different clones are a data race.

    /// Returns true if this RefAny supports JSON serialization.

    /// Returns true if this RefAny type supports JSON deserialization.

    /// Replaces the contents of this RefAny with a new value from another RefAny.

    ///

    /// This method:

    /// 1. Atomically acquires a mutable "lock" via compare_exchange

    /// 2. Calls the destructor on the old value

    /// 3. Deallocates the old memory

    /// 4. Copies the new value's memory

    /// 5. Updates metadata (type_id, type_name, destructor, serialize/deserialize fns)

    /// 6. Updates the shared _internal_ptr so ALL clones see the new data

    /// 7. Releases the lock

    ///

    /// Since all clones of a RefAny share the same `RefCountInner`, this change

    /// will be visible to ALL clones of this RefAny.

    ///

    /// # Returns

    ///

    /// - `true` if the replacement was successful

    /// - `false` if there are active borrows (would cause UB)

    ///

    /// # Thread Safety

    ///

    /// Uses compare_exchange to atomically acquire exclusive access, preventing

    /// any race condition between checking for borrows and modifying the data.

    ///

    /// # Safety

    ///

    /// Safe because:

    /// - We atomically acquire exclusive access before modifying

    /// - The old destructor is called before deallocation

    /// - Memory is properly allocated with correct alignment

    /// - All metadata is updated while holding the lock

        use core::ptr;

        // Atomically acquire exclusive access by setting num_mutable_refs to 1.

        // This uses compare_exchange to ensure no race condition:

        // - If num_mutable_refs is 0, set it to 1 (success)

        // - If num_mutable_refs is not 0, someone else has it (fail)

        // We also need to check num_refs == 0 atomically.

        // First, try to acquire the mutable lock

            0,  // expected: no mutable refs

            1,  // desired: we take the mutable ref

        );

            // Someone else has a mutable reference

        // Now check that there are no shared references

        // Note: We hold the mutable lock, so no new shared refs can be acquired

            // Release the lock and fail

        // We now have exclusive access - perform the replacement

        unsafe {

            // Get old layout info before we overwrite it

            // Step 1: Call destructor on old value (if non-ZST)

            // Step 2: Deallocate old memory (if non-ZST)

            // Get new value's metadata

            // Step 3: Allocate new memory and copy data

            } else {

                // Copy data from new_value

                );

            };

            // Step 4: Update the shared internal pointer in RefCountInner

            // All clones will see this new pointer!

            // Step 5: Update metadata in RefCountInner

        }

        // Release the mutable lock

        // Prevent new_value from running its destructor (we copied the data)

}

impl Clone for RefAny {

    /// Creates a new `RefAny` sharing the same heap-allocated data.

    ///

    /// This is cheap (just increments a counter) and is how multiple parts

    /// of the code can hold references to the same data.

    ///

    /// # Reference Counting

    ///

    /// Atomically increments `num_copies` with `SeqCst` ordering before

    /// creating the clone. This ensures all threads see the updated count

    /// before the clone can be used.

    ///

    /// # Instance ID

    ///

    /// Each clone gets a unique `instance_id` based on the current copy count.

    /// The original has `instance_id=0`, the first clone gets `1`, etc.

    ///

    /// # Memory Ordering

    ///

    /// The `fetch_add` followed by `load` both use `SeqCst`:

    /// - `fetch_add`: Ensures the increment is visible to all threads

    /// - `load`: Gets the updated value for the instance_id

    ///

    /// This prevents race conditions where two threads clone simultaneously

    /// and both see the same instance_id.

    ///

    /// # Safety

    ///

    /// Safe because:

    ///

    /// - Atomic operations prevent data races

    /// - The heap allocation remains valid (only freed when count reaches 0)

    /// - `run_destructor` is set to `true` for all clones

        // Atomically increment the reference count

}

impl Drop for RefAny {

    /// Empty drop implementation - all cleanup is handled by `RefCount::drop`.

    ///

    /// When a `RefAny` is dropped, its `sharing_info: RefCount` field is automatically

    /// dropped by Rust. The `RefCount::drop` implementation handles all cleanup:

    ///

    /// 1. Atomically decrements `num_copies` with `fetch_sub`

    /// 2. If the previous value was 1 (we're the last reference):

    ///    - Reclaims the `RefCountInner` via `Box::from_raw`

    ///    - Calls the custom destructor to run `T::drop()`

    ///    - Deallocates the heap memory with the stored layout

    ///

    /// # Why No Code Here?

    ///

    /// Previously, `RefAny::drop` handled cleanup, but this caused issues with the

    /// C API where `Ref<T>` and `RefMut<T>` guards (which clone the `RefCount`) need

    /// to keep the data alive even after the original `RefAny` is dropped.

    ///

    /// By moving all cleanup to `RefCount::drop`, we ensure that:

    /// - `RefAny::clone()` creates a `RefCount` with `run_destructor = true`

    /// - `AZ_REFLECT` macros create `Ref`/`RefMut` guards that clone `RefCount`

    /// - Each `RefCount` drop decrements the counter

    /// - Only the LAST drop (when `num_copies` was 1) cleans up memory

    ///

    /// See `RefCount::drop` for the full algorithm and safety documentation.

        // RefCount::drop handles everything automatically.

        // The sharing_info field is dropped by Rust, triggering RefCount::drop.

}