miniextendr_api/

abi.rs

//! # ABI Types for Cross-Package Trait Dispatch
//!
//! This module defines the stable, C-compatible ABI types used for cross-package
//! trait dispatch in miniextendr. These types enable R packages written with
//! miniextendr to share trait-based interfaces across package boundaries.
//!
//! ## Design Principles
//!
//! 1. **Stability**: All types are `#[repr(C)]` and append-only. Fields are never
//!    removed or reordered, only new fields may be added at the end.
//!
//! 2. **C Compatibility**: Types use only C-compatible primitives to ensure
//!    consistent layout across different Rust versions and compilation units.
//!
//! 3. **Type Safety**: Runtime type checking via [`mx_tag`] ensures type-safe
//!    downcasts even across package boundaries.
//!
//! ## Type Hierarchy
//!
//! ```text
//! mx_erased (type-erased object)
//!     │
//!     └── points to → mx_base_vtable (base vtable)
//!                         │
//!                         ├── drop: fn pointer
//!                         ├── concrete_tag: mx_tag
//!                         └── query: fn pointer → interface vtables
//! ```
//!
//! ## Usage Flow
//!
//! 1. Trait is declared with `#[miniextendr]`, impl uses `#[miniextendr] impl Trait for Type`
//! 2. Type derives `ExternalPtr` (generates MxWrapper, base vtable, wrap fn)
//! 3. Trait dispatch entries self-register via `distributed_slice`
//! 4. Constructor returns `*mut mx_erased`
//! 5. `mx_wrap()` wraps pointer in R's EXTPTRSXP
//! 6. Method calls use `universal_query()` to get interface vtable
//! 7. Vtable entry receives `(data, argc, argv)` and returns SEXP
//!
//! ## Example
//!
//! ```ignore
//! // Define trait (generates TAG_Foo, FooVTable, FooView)
//! #[miniextendr]
//! trait Foo {
//!     fn len(&self) -> usize;
//! }
//!
//! // Implement for concrete type (self-registers via distributed_slice)
//! #[miniextendr]
//! impl Foo for MyType { /* ... */ }
//! ```
//!
//! ## Thread Safety
//!
//! All ABI operations are main-thread only. R invokes `.Call` on the main thread,
//! and method shims do not route through `with_r_thread`.

use crate::SEXP;
use std::cell::RefCell;
use std::os::raw::c_void;

/// Type tag for runtime type identification.
///
/// A 128-bit identifier split into two 64-bit halves for C compatibility.
/// Used to identify concrete types and trait interfaces at runtime.
///
/// ## Generation
///
/// Tags should be generated as compile-time constants, typically using
/// a hash of the fully-qualified type/trait path. The `#[miniextendr]`
/// attribute macro handles this automatically.
///
/// ## Comparison
///
/// Tags are compared by value equality of both `lo` and `hi` fields.
///
/// ## Layout Guarantee
///
/// This type is `#[repr(C)]` and its layout is frozen. Fields will never
/// be reordered, and new fields will only be appended.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct mx_tag {
    /// Lower 64 bits of the type tag.
    pub lo: u64,
    /// Upper 64 bits of the type tag.
    pub hi: u64,
}

impl mx_tag {
    /// Create a new type tag from two 64-bit values.
    ///
    /// # Arguments
    ///
    /// * `lo` - Lower 64 bits
    /// * `hi` - Upper 64 bits
    ///
    /// # Example
    ///
    /// ```ignore
    /// const MY_TAG: mx_tag = mx_tag::new(0x1234_5678_9abc_def0, 0xfed_cba9_8765_4321);
    /// ```
    #[inline]
    pub const fn new(lo: u64, hi: u64) -> Self {
        Self { lo, hi }
    }
}

/// Method signature for trait vtable entries.
///
/// All trait methods are erased to this uniform signature:
/// - `data`: Pointer to the concrete object data
/// - `argc`: Number of arguments in `argv`
/// - `argv`: Array of SEXP arguments from R
/// - Returns: SEXP result to R
///
/// ## Argument Handling
///
/// The shim generated by `#[miniextendr]` on a trait is responsible for:
/// 1. Checking `argc` matches expected arity
/// 2. Converting each `argv[i]` via [`TryFromSexp`]
/// 3. Calling the actual method
/// 4. Converting the result via [`IntoR`]
/// 5. Catching panics and converting to R errors
///
/// ## Safety
///
/// This function pointer is `unsafe` because:
/// - `data` must point to valid, properly-aligned data of the expected type
/// - `argv` must point to `argc` valid SEXP values, each rooted by the caller
///   for the whole call (the shim's conversions and the method body allocate);
///   the generated View protects each argument before converting the next
/// - The returned SEXP is unprotected; the caller roots it before allocating
/// - Must be called on R's main thread
///
/// [`TryFromSexp`]: crate::TryFromSexp
/// [`IntoR`]: crate::IntoR
#[allow(non_camel_case_types)]
pub type mx_meth = unsafe extern "C" fn(data: *mut c_void, argc: i32, argv: *const SEXP) -> SEXP;

/// A trait method whose explicit borrowed receiver needs its R owner.
///
/// In addition to [`mx_meth`]'s contract, `owner` must be the caller-rooted
/// external pointer holding `data`, with initialized sidecar slots. Only
/// owner-receiver methods use this signature; ordinary receivers keep `mx_meth`.
#[allow(non_camel_case_types)]
pub type mx_owner_meth =
    unsafe extern "C" fn(data: *mut c_void, owner: SEXP, argc: i32, argv: *const SEXP) -> SEXP;

/// Base vtable present in all erased objects.
///
/// This vtable provides the minimal operations needed for any erased object:
/// - Destructor for cleanup when R garbage collects the wrapper
/// - Concrete type tag for type-safe downcasts
/// - Query function to retrieve interface vtables
///
/// ## Layout Guarantee
///
/// This type is `#[repr(C)]` and its layout is frozen. Fields will never
/// be reordered, and new fields will only be appended at the end.
///
/// ## Generated By
///
/// `#[derive(ExternalPtr)]` emits a static instance of this vtable for each
/// wrapped type.
#[repr(C)]
pub struct mx_base_vtable {
    /// Destructor called when the R external pointer is garbage collected.
    ///
    /// Receives a pointer to the erased object (not the data pointer).
    /// Must deallocate the entire erased wrapper structure.
    ///
    /// # Safety
    ///
    /// - `ptr` must be a valid pointer to `mx_erased` allocated by this type's constructor
    /// - Must only be called once per object
    /// - Must be called on R's main thread (during GC finalization)
    pub drop: unsafe extern "C" fn(ptr: *mut mx_erased),

    /// Tag identifying the concrete type wrapped by this object.
    ///
    /// Used for type-safe downcasts: if `concrete_tag` matches the expected
    /// type's tag, the data pointer can be cast to that type.
    pub concrete_tag: mx_tag,

    /// Query function to retrieve interface vtables.
    ///
    /// Given a trait tag, returns a pointer to the vtable for that interface,
    /// or null if the type does not implement that trait.
    ///
    /// # Arguments
    ///
    /// * `ptr` - Pointer to the erased object
    /// * `trait_tag` - Tag identifying the requested trait interface
    ///
    /// # Returns
    ///
    /// - Non-null pointer to the trait's vtable if implemented
    /// - Null pointer if the trait is not implemented
    ///
    /// # Safety
    ///
    /// - `ptr` must be a valid pointer to `mx_erased`
    /// - The returned pointer (if non-null) must be cast to the correct vtable type
    pub query: unsafe extern "C" fn(ptr: *mut mx_erased, trait_tag: mx_tag) -> *const c_void,

    /// Byte offset from the start of the wrapper struct to the `data` field.
    ///
    /// The generated wrapper struct is
    /// `#[repr(C)] struct { erased: mx_erased, data: RefCell<T> }`. Only the
    /// producer's method shims, compiled with `T` known, look behind this
    /// offset: they borrow the `RefCell` for the call, so a view in another
    /// package passes the pointer on and never sees the borrow flag.
    /// When `T` has stricter alignment than `mx_erased`, padding exists between
    /// `erased` and `data`. This field records the correct offset so that
    /// `TraitView::try_from_sexp` can compute the data pointer without
    /// assuming `offset == size_of::<mx_erased>()`.
    pub data_offset: usize,
}

/// Type-erased object header.
///
/// This is the common prefix of all erased objects, providing access to
/// the base vtable. The actual data follows this header in memory.
///
/// ## Memory Layout
///
/// ```text
/// ┌─────────────────────────────────────┐
/// │ mx_erased                           │
/// │   base: *const mx_base_vtable ──────┼──► static vtable
/// ├─────────────────────────────────────┤
/// │ (type-specific data follows...)     │
/// │   data: RefCell<T>                  │
/// └─────────────────────────────────────┘
/// ```
///
/// ## Layout Guarantee
///
/// This type is `#[repr(C)]` and its layout is frozen. The `base` field
/// will always be at offset 0, and new fields will only be appended.
///
/// ## Generated By
///
/// `#[derive(ExternalPtr)]` uses [`ErasedObject<T>`], which places `mx_erased`
/// as the first field for proper layout.
#[repr(C)]
pub struct mx_erased {
    /// Pointer to the base vtable.
    ///
    /// This must point to a valid, static vtable for the lifetime of the object.
    /// The vtable is typically a `static` generated by `#[derive(ExternalPtr)]`.
    pub base: *const mx_base_vtable,
}

// region: Shared erased storage

/// Optional interface queried by `mx_wrap` after it roots the new owner.
/// Keeping initialization behind `query` leaves the base-vtable layout alone.
/// This tag identifies this exact interface layout and calling convention.
pub(crate) const SIDECAR_INIT_TAG: mx_tag = mx_tag_from_path("miniextendr::sidecar_init/v1");

#[repr(C)]
pub(crate) struct SidecarInitVTable {
    /// `ptr` belongs to the caller-rooted `owner`; attach its sidecar slots.
    pub init: unsafe extern "C-unwind" fn(ptr: *mut mx_erased, owner: SEXP),
}

/// Storage used by generated trait-ABI constructors.
///
/// The C header and concrete value retain their repr(C) layout. Keeping the
/// allocation and destructor here avoids emitting identical helper items for
/// every ExternalPtr derive. This is not ordinary ExternalPtr/Any storage, but
/// it keeps the value in a `RefCell` the same way: the method shims borrow it
/// for each call.
#[doc(hidden)]
#[repr(C)]
pub struct ErasedObject<T> {
    erased: mx_erased,
    data: RefCell<T>,
}

impl<T> ErasedObject<T> {
    /// Offset of the value's `RefCell`, used by trait views, including
    /// over-aligned concrete types.
    pub const DATA_OFFSET: usize = core::mem::offset_of!(Self, data);

    /// Allocate an erased object with the generated type's base vtable.
    ///
    /// # Safety
    /// `base` must describe `T` in this storage: its destructor must be
    /// `Self::drop_raw`, its offset `Self::DATA_OFFSET`, and its query/tag
    /// must identify the trait implementations of this concrete `T`.
    pub unsafe fn into_raw(data: T, base: &'static mx_base_vtable) -> *mut mx_erased {
        Box::into_raw(Box::new(Self {
            erased: mx_erased { base },
            data: RefCell::new(data),
        }))
        .cast()
    }

    /// Destructor installed in generated base vtables.
    ///
    /// # Safety
    /// A non-null `ptr` must be a live allocation returned by
    /// `ErasedObject::<T>::into_raw`, and must be released exactly once.
    pub unsafe extern "C" fn drop_raw(ptr: *mut mx_erased) {
        if ptr.is_null() {
            return;
        }
        crate::externalptr::drop_catching_panic(|| {
            // A panicking user Drop must not cross this C-ABI boundary.
            unsafe { drop(Box::from_raw(ptr.cast::<Self>())) };
        });
    }
}

impl<T: crate::externalptr::TypedExternal> ErasedObject<T> {
    const SIDECAR_INIT: SidecarInitVTable = SidecarInitVTable {
        init: Self::init_sidecars,
    };

    /// Query the concrete type's traits and its optional sidecar initializer.
    ///
    /// # Safety
    /// `ptr` must be a live `ErasedObject<T>` with its matching base vtable.
    /// The returned pointer is valid for the program's lifetime and must be
    /// cast to the interface identified by `tag`.
    pub unsafe extern "C" fn query(ptr: *mut mx_erased, tag: mx_tag) -> *const c_void {
        if tag == SIDECAR_INIT_TAG {
            return if T::R_SLOT_COUNT == 0 {
                core::ptr::null()
            } else {
                core::ptr::from_ref(&Self::SIDECAR_INIT).cast()
            };
        }
        unsafe { crate::registry::universal_query(ptr, tag) }
    }

    unsafe extern "C-unwind" fn init_sidecars(ptr: *mut mx_erased, owner: SEXP) {
        // SAFETY: mx_wrap calls the interface for this concrete allocation
        // after registering its finalizer and while the owner is rooted.
        unsafe {
            let value = (*ptr.cast::<Self>()).data.borrow();
            crate::externalptr::init_erased_sidecars(&*value, owner);
        }
    }
}
// endregion

// region: Tag generation

/// FNV-1a 64-bit offset basis.
pub(crate) const FNV1A_64_OFFSET: u64 = 0xcbf29ce484222325;

/// FNV-1a 64-bit prime.
const FNV1A_64_PRIME: u64 = 0x00000100000001b3;

/// Compute FNV-1a 64-bit hash of a byte slice (const-compatible).
///
/// Also fingerprints the generated wrappers file (`registry.rs`), so the
/// header there and the type tags share one dependency-free digest.
pub(crate) const fn fnv1a_64(bytes: &[u8], seed: u64) -> u64 {
    let mut hash = seed;
    let mut i = 0;
    while i < bytes.len() {
        hash ^= bytes[i] as u64;
        hash = hash.wrapping_mul(FNV1A_64_PRIME);
        i += 1;
    }
    hash
}

/// Create a new type tag from a string path.
///
/// This is a helper for generating deterministic tags from type/trait paths.
/// Uses FNV-1a hash to produce a 128-bit tag (two independent 64-bit hashes).
///
/// # Arguments
///
/// * `path` - Fully-qualified path like `"mypackage::MyType"` or `"mypackage::Foo"`
///
/// # Returns
///
/// A deterministic [`mx_tag`] for the given path.
///
/// # Example
///
/// ```
/// use miniextendr_api::abi::mx_tag_from_path;
///
/// const TAG_FOO: miniextendr_api::abi::mx_tag = mx_tag_from_path("mypackage::Foo");
/// const TAG_BAR: miniextendr_api::abi::mx_tag = mx_tag_from_path("mypackage::Bar");
///
/// // Same path produces same tag
/// assert_eq!(TAG_FOO, mx_tag_from_path("mypackage::Foo"));
///
/// // Different paths produce different tags
/// assert_ne!(TAG_FOO, TAG_BAR);
/// ```
///
/// # Note
///
/// This function is `const` to enable compile-time tag generation.
/// The hash is deterministic across compilations.
#[inline]
pub const fn mx_tag_from_path(path: &str) -> mx_tag {
    let bytes = path.as_bytes();
    // Use different seeds for lo and hi to get independent hash values
    let lo = fnv1a_64(bytes, FNV1A_64_OFFSET);
    // XOR with a different constant for the second hash to avoid correlation
    let hi = fnv1a_64(bytes, FNV1A_64_OFFSET ^ 0x5555555555555555);
    mx_tag::new(lo, hi)
}

#[cfg(test)]
mod tests;
// endregion