Module miniextendr_impl_trait 

#[miniextendr] on trait impls - Trait Implementation Registration

This module handles #[miniextendr] applied to trait implementations, generating the vtable static for cross-package trait dispatch, plus optional R-callable wrappers for direct method access.

Overview

When #[miniextendr] is applied to an impl Trait for Type block, it:

1. Detects the trait from the impl syntax (no attribute args needed)
2. Generates vtable static using the trait’s __<trait>_build_vtable function
3. Generates C wrappers for each trait method (for R .Call access)
4. Generates R wrapper code for the trait methods
5. Passes through the original impl block unchanged

Usage

use miniextendr_api::miniextendr;

// The trait must have been defined with #[miniextendr]
// which generates __counter_build_vtable::<T>()

struct MyCounter { value: i32 }

#[miniextendr]
impl Counter for MyCounter {
    fn value(&self) -> i32 {
        self.value
    }
    fn increment(&mut self) {
        self.value += 1;
    }
    fn add(&mut self, n: i32) {
        self.value += n;
    }
}

Generates (conceptually):

// Original impl block (passed through)
impl Counter for MyCounter {
    fn value(&self) -> i32 { self.value }
    fn increment(&mut self) { self.value += 1; }
    fn add(&mut self, n: i32) { self.value += n; }
}

// Generated vtable static
pub static __VTABLE_COUNTER_FOR_MYCOUNTER: CounterVTable =
    __counter_build_vtable::<MyCounter>();

How It Works

1. Parse impl Trait for Type to extract trait path and concrete type
2. Generate vtable static name: __VTABLE_{TRAIT}_FOR_{TYPE}
3. Generate vtable builder call: __{trait}_build_vtable::<Type>()
4. The vtable builder was generated by #[miniextendr] on the trait

Trait Detection

The macro reads the trait directly from the impl syntax:

#[miniextendr]
impl path::to::Counter for MyType { ... }
//   ^^^^^^^^^^^^^^^^^ detected automatically

No extra arguments are needed; the trait path is explicit in the impl syntax.

Name Generation

• Vtable static: __VTABLE_{TRAIT}_FOR_{TYPE} (uppercase, underscores)
• Vtable builder: __{trait}_build_vtable (lowercase)

For impl foo::Counter for my_mod::MyType:

• Static: __VTABLE_COUNTER_FOR_MYTYPE
• Builder call: foo::__counter_build_vtable::<my_mod::MyType>()

Integration with ExternalPtr / TypedExternal

The generated vtable static is automatically registered via linkme distributed slices.

#[derive(ExternalPtr)]
struct MyCounter { value: i32 }

#[miniextendr]
impl Counter for MyCounter { /* ... */ }

ExternalPtr<T> provides the type identity for the external pointer. Trait dispatch is wired automatically.

Thread Safety

The generated vtable is a static constant, safe to access from any thread. Trait shims now mirror inherent impls: instance methods stay on the main thread, while static trait methods run on the worker thread unless main_thread is explicitly requested.

Modules

r_wrappers 🔒

R wrapper generation for trait methods across all class systems.

vtable 🔒

Vtable static generation, C wrapper generation, and method attribute parsing for trait impls.

Structs

TpieInput 🔒

Input to the __mx_trait_impl_expand! proc macro.

TpieMethod 🔒

A single method entry in TPIE metadata.

TraitConst 🔒

Parsed associated constant from a trait impl block.

TraitMethod 🔒

Parsed method from a trait impl block.

Functions

expand_miniextendr_impl_trait

Expand #[miniextendr] applied to a trait implementation.

expand_tpie

Entry point for the __mx_trait_impl_expand! proc macro.

extract_trait_and_type 🔒

Extract the trait path and concrete type from an impl block.

generate_tpie_invocation 🔒

Generate vtable static + TPIE macro invocation for an empty trait impl.

rewrite_self_in_sig 🔒

Rewrite Self → concrete type in a method signature.

rewrite_self_type 🔒

Recursively replace Self with the concrete type in a type tree.

trait_method_body_lines 🔒

Generate R function body lines with optional error_in_r checking.

trait_method_preamble_lines 🔒

Generate R function body preamble lines (r_entry, on.exit, lifecycle, r_post_checks).

type_to_uppercase_name 🔒

Convert a type to an uppercase identifier-safe name.

unwrap_group_type 🔒

Unwrap invisible Group tokens from macro_rules! $t:ty captures.