Module abi 

ABI types for cross-package trait dispatch.

This module defines the stable, C-compatible types used for runtime trait dispatch across R package boundaries.

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

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

// 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.

Structs

mx_base_vtable

Base vtable present in all erased objects.

mx_erased

Type-erased object header.

mx_tag

Type tag for runtime type identification.

Constants

FNV1A_64_OFFSET 🔒

FNV-1a 64-bit offset basis.

FNV1A_64_PRIME 🔒

FNV-1a 64-bit prime.

Functions

fnv1a_64 🔒

Compute FNV-1a 64-bit hash of a byte slice (const-compatible).

mx_tag_from_path

Create a new type tag from a string path.

Type Aliases

mx_meth

Method signature for trait vtable entries.