miniextendr_api/

registry.rs

//! Automatic registration for miniextendr.
//!
//! Every `#[miniextendr]` item self-registers at link time. `package_init()`
//! (generated by `miniextendr_init!`) calls [`miniextendr_register_routines`](crate::registry::miniextendr_register_routines)
//! during `R_init_*` to finalize registration with R. Users never interact
//! with this module.

use crate::abi::{mx_erased, mx_tag};
use crate::ffi::{DllInfo, R_CallMethodDef};
use linkme::distributed_slice;
use std::os::raw::c_void;

// region: Distributed Slices

/// R `.Call` method registrations (function + method C wrappers).
///
/// Each `#[miniextendr]` function or method emits an entry here.
#[distributed_slice]
pub static MX_CALL_DEFS: [R_CallMethodDef];

/// R wrapper code fragments with priority for ordering.
///
/// Each `#[miniextendr]` function, impl block, or trait impl emits an entry.
/// Priorities ensure correct evaluation order when R sources the wrapper file
/// (sidecar helpers must be defined before class definitions that reference them).
#[distributed_slice]
pub static MX_R_WRAPPERS: [RWrapperEntry];

/// ALTREP class registration functions, called once at package init.
///
/// Each ALTREP struct or trait impl emits an entry.
#[distributed_slice]
pub static MX_ALTREP_REGISTRATIONS: [fn()];

/// Trait dispatch entries for [`universal_query`].
///
/// Each `#[miniextendr] impl Trait for Type` emits an entry mapping
/// `(concrete_tag, trait_tag)` to the trait's vtable pointer.
#[distributed_slice]
pub static MX_TRAIT_DISPATCH: [TraitDispatchEntry];
// endregion

// region: Entry Types

/// Ordering priority for R wrapper code fragments.
///
/// Variant declaration order = output order. The order matters because
/// R evaluates the wrapper file top-to-bottom, so dependencies must come first:
/// sidecar accessors before class definitions, classes before functions, etc.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum RWrapperPriority {
    /// `#[r_data]` getters/setters — must come before class definitions.
    Sidecar,
    /// Class definitions (impl blocks: env/R6/S3/S4/S7).
    Class,
    /// Standalone `#[miniextendr]` functions.
    Function,
    /// Trait impl wrappers (`impl Trait for Type`).
    TraitImpl,
    /// Vctrs S3 method wrappers (`#[derive(Vctrs)]`).
    Vctrs,
}

/// R wrapper code with priority for ordering.
pub struct RWrapperEntry {
    /// Ordering priority (lower = earlier in output file).
    pub priority: RWrapperPriority,
    /// R source code fragment.
    pub content: &'static str,
    /// Source file path (from `file!()`). Used to derive a default `@rdname`
    /// for standalone functions that don't have an explicit one, so that all
    /// functions from the same source file share a single .Rd page.
    pub source_file: &'static str,
}

// SAFETY: All fields are immutable and valid for 'static lifetime.
unsafe impl Sync for RWrapperEntry {}

/// Trait dispatch entry mapping (concrete_tag, trait_tag) → vtable.
#[repr(C)]
pub struct TraitDispatchEntry {
    /// Tag identifying the concrete type.
    pub concrete_tag: mx_tag,
    /// Tag identifying the trait interface.
    pub trait_tag: mx_tag,
    /// Pointer to the trait's vtable (cast from `&'static SomeVTable`).
    pub vtable: *const c_void,
}

// SAFETY: vtable points to a static vtable valid for program lifetime.
// Tags are Copy values. All fields are safe to read from any thread.
unsafe impl Sync for TraitDispatchEntry {}
unsafe impl Send for TraitDispatchEntry {}
// endregion

// region: Universal Query

/// Universal query function for trait dispatch.
///
/// Scans [`MX_TRAIT_DISPATCH`] for a matching `(concrete_tag, trait_tag)` pair.
/// Returns the vtable pointer, or null if the trait is not implemented.
///
/// This replaces per-type query functions — a single function handles all types
/// by reading from the global dispatch table.
///
/// # Safety
///
/// - `ptr` must point to a valid `mx_erased` with a valid base vtable.
/// - Must be called on R's main thread.
pub unsafe extern "C" fn universal_query(ptr: *mut mx_erased, trait_tag: mx_tag) -> *const c_void {
    let concrete_tag = unsafe { (*(*ptr).base).concrete_tag };
    for entry in MX_TRAIT_DISPATCH.iter() {
        if entry.concrete_tag == concrete_tag && entry.trait_tag == trait_tag {
            return entry.vtable;
        }
    }
    std::ptr::null()
}
// endregion

// region: Initialization

/// Register all `#[miniextendr]` routines and ALTREP classes with R.
///
/// Called from `package_init()` during `R_init_*` (via `miniextendr_init!`).
/// Everything else is automatic.
///
/// # Safety
///
/// Must be called from R's main thread during `R_init_*`.
/// `dll` must be a valid pointer provided by R.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_register_routines(dll: *mut DllInfo) {
    // 1. Register ALTREP classes (skip during cdylib wrapper generation)
    //
    // During wrapper-gen, the cdylib is loaded temporarily via dyn.load() then
    // unloaded via dyn.unload(). ALTREP class registration creates R-global entries
    // with method pointers into the cdylib code. After dyn.unload(), those pointers
    // become dangling. When the staticlib later re-registers, R may still have the
    // stale entries, leading to heap corruption (e.g., "malloc(): unsorted double
    // linked list corrupted" on Linux).
    let wrapper_gen = std::env::var_os("MINIEXTENDR_CDYLIB_WRAPPERS").is_some();
    if !wrapper_gen {
        // User-defined ALTREP classes (from #[miniextendr] structs)
        for reg_fn in MX_ALTREP_REGISTRATIONS.iter() {
            reg_fn();
        }
        // Built-in ALTREP classes (Vec, Box, Range, Arrow) — must be
        // registered eagerly so readRDS can find them in fresh sessions.
        crate::altrep_impl::register_builtin_altrep_classes();
        #[cfg(feature = "arrow")]
        crate::altrep_impl::register_arrow_altrep_classes();

        // Verify no two ALTREP types registered the same class name.
        // Duplicates cause silent overwrites in R — the wrong type gets
        // reconstructed on readRDS, leading to memory corruption.
        crate::altrep::assert_altrep_class_uniqueness();
    }

    // 2. Build call method defs with null sentinel
    let mut call_defs: Vec<R_CallMethodDef> = MX_CALL_DEFS.iter().copied().collect();
    // Always register miniextendr_write_wrappers so it's visible via
    // getNativeSymbolInfo even when R_forceSymbols(TRUE) is set.
    // SAFETY: DL_FUNC is Option<extern "C-unwind" fn() -> *mut c_void> — R's
    // standard erased function pointer. The actual signature (SEXP -> SEXP) is
    // ABI-compatible; R dispatches based on numArgs.
    call_defs.push(R_CallMethodDef {
        name: c"miniextendr_write_wrappers".as_ptr(),
        fun: unsafe {
            std::mem::transmute::<*const (), Option<unsafe extern "C-unwind" fn() -> *mut c_void>>(
                miniextendr_write_wrappers as *const (),
            )
        },
        numArgs: 1,
    });
    call_defs.push(R_CallMethodDef {
        name: std::ptr::null(),
        fun: None,
        numArgs: 0,
    });

    // 3. Register routines
    // Leak the Vec — init runs once at package load, so this is fine.
    unsafe {
        crate::ffi::R_registerRoutines_unchecked(
            dll,
            std::ptr::null(),
            call_defs.leak().as_ptr(),
            std::ptr::null(),
            std::ptr::null(),
        );
    }
}

/// Collect all R wrapper entries, sorted by priority and deduplicated.
///
/// Within each priority group, S7 class definitions are topologically sorted
/// so parents are defined before children (S7 `parent = X` requires X to exist).
pub fn collect_r_wrappers() -> Vec<std::borrow::Cow<'static, str>> {
    let mut entries: Vec<&RWrapperEntry> = MX_R_WRAPPERS.iter().collect();
    entries.sort_by_key(|e| e.priority);

    let mut seen = std::collections::HashSet::<&str>::new();
    let mut result: Vec<std::borrow::Cow<'static, str>> = Vec::with_capacity(entries.len());
    for entry in entries {
        let trimmed = entry.content.trim();
        if !trimmed.is_empty() && seen.insert(trimmed) {
            // For standalone functions without explicit @rdname, inject one
            // derived from the source file stem so same-file functions share
            // a single .Rd page.
            if entry.priority == RWrapperPriority::Function
                && !has_rdname_tag(trimmed)
                && !has_no_rd_tag(trimmed)
            {
                if let Some(rdname) = rdname_from_source_file(entry.source_file) {
                    result.push(std::borrow::Cow::Owned(inject_rdname(trimmed, &rdname)));
                    continue;
                }
            }
            result.push(std::borrow::Cow::Borrowed(trimmed));
        }
    }

    // Topological sort for S7 inheritance ordering
    sort_s7_classes(&mut result);

    result
}

/// Check if an R wrapper fragment already has an `@rdname` tag.
fn has_rdname_tag(content: &str) -> bool {
    content.lines().any(|line| {
        let trimmed = line.trim();
        trimmed.starts_with("#' @rdname ")
    })
}

/// Check if an R wrapper fragment has `@noRd`.
fn has_no_rd_tag(content: &str) -> bool {
    content.lines().any(|line| {
        let trimmed = line.trim();
        trimmed == "#' @noRd"
    })
}

/// Derive an `@rdname` value from a source file path.
///
/// `"src/rust/zero_copy_tests.rs"` → `"zero_copy_tests"`
/// `"lib.rs"` → `"lib"`
fn rdname_from_source_file(path: &str) -> Option<String> {
    let file_name = path.rsplit(['/', '\\']).next()?;
    let stem = file_name.strip_suffix(".rs").unwrap_or(file_name);
    if stem.is_empty() || stem == "lib" || stem == "mod" {
        return None;
    }
    Some(stem.to_string())
}

/// Inject `#' @rdname <value>` (and `@title` if missing) into an R wrapper
/// fragment. Inserts before the first `@export`/`@keywords`/`@source` line,
/// or after the last roxygen line.
fn inject_rdname(content: &str, rdname: &str) -> String {
    let rdname_line = format!("#' @rdname {rdname}");
    let has_title = content.lines().any(|l| l.trim().starts_with("#' @title "));
    // Functions with no doc comments need a title so the @rdname page has an anchor
    let title_line = if has_title {
        None
    } else {
        Some(format!("#' @title {}", rdname.replace('_', " ")))
    };

    let lines: Vec<&str> = content.lines().collect();
    let mut result = Vec::with_capacity(lines.len() + 2);
    let mut inserted = false;

    for line in &lines {
        let trimmed = line.trim();
        // Insert before @export, @keywords, or @source lines
        if !inserted
            && (trimmed.starts_with("#' @export")
                || trimmed.starts_with("#' @keywords")
                || trimmed.starts_with("#' @source"))
        {
            if let Some(ref t) = title_line {
                result.push(t.as_str());
            }
            result.push(rdname_line.as_str());
            inserted = true;
        }
        result.push(line);
    }

    // If we never found a good insertion point, insert before the function def
    if !inserted {
        let last_roxy = lines
            .iter()
            .rposition(|l| l.trim().starts_with("#'"))
            .unwrap_or(0);
        let insert_at = last_roxy + 1;
        if let Some(ref t) = title_line {
            result.insert(insert_at, t.as_str());
            result.insert(insert_at + 1, rdname_line.as_str());
        } else {
            result.insert(insert_at, rdname_line.as_str());
        }
    }

    result.join("\n")
}

/// Sort S7 class definitions so parents come before children.
///
/// Detects `S7::new_class()` calls, extracts `parent = ClassName` relationships,
/// and performs topological sort. Non-S7 entries keep their relative order.
fn sort_s7_classes(entries: &mut [std::borrow::Cow<'static, str>]) {
    use std::collections::HashMap;

    // Parse S7 class definitions: find (index, name, parent)
    let mut s7_info: Vec<(usize, String, Option<String>)> = Vec::new();

    for (i, entry) in entries.iter().enumerate() {
        if let Some(nc_pos) = entry.find("S7::new_class(") {
            // Extract class name: "NAME <- S7::new_class("
            let before = entry[..nc_pos].trim_end();
            let name = before
                .strip_suffix("<-")
                .or_else(|| before.rsplit_once("<-").map(|(_, r)| r))
                .map(|s| s.trim())
                .and_then(|s| s.split_whitespace().last());

            let Some(name) = name else { continue };

            // Extract parent: "parent = ParentName,"
            let after = &entry[nc_pos..];
            let parent = after.find("parent = ").and_then(|p| {
                let rest = &after[p + "parent = ".len()..];
                let end = rest.find([',', ')', '\n']).unwrap_or(rest.len());
                let p = rest[..end].trim();
                if p.is_empty() {
                    None
                } else {
                    Some(p.to_string())
                }
            });

            s7_info.push((i, name.to_string(), parent));
        }
    }

    if s7_info.len() <= 1 {
        return;
    }

    // Build name → position-in-s7_info map
    let name_to_pos: HashMap<&str, usize> = s7_info
        .iter()
        .enumerate()
        .map(|(pos, (_, name, _))| (name.as_str(), pos))
        .collect();

    // Topological sort: repeatedly emit classes whose parent is already placed
    let n = s7_info.len();
    let mut order: Vec<usize> = Vec::with_capacity(n);
    let mut placed = vec![false; n];

    for _ in 0..n {
        for (pos, (_, _, parent)) in s7_info.iter().enumerate() {
            if placed[pos] {
                continue;
            }
            let ready = match parent {
                None => true,
                Some(pname) => match name_to_pos.get(pname.as_str()) {
                    None => true, // external parent
                    Some(&pp) => placed[pp],
                },
            };
            if ready {
                order.push(pos);
                placed[pos] = true;
            }
        }
    }

    // Fallback: add any remaining (cycles) in original order
    for (pos, &is_placed) in placed.iter().enumerate().take(n) {
        if !is_placed {
            order.push(pos);
        }
    }

    // Apply: place sorted S7 entries back at their original indices
    let s7_indices: Vec<usize> = s7_info.iter().map(|(i, _, _)| *i).collect();
    let original: Vec<std::borrow::Cow<'static, str>> =
        s7_indices.iter().map(|&i| entries[i].clone()).collect();

    for (slot, &src) in order.iter().enumerate() {
        entries[s7_indices[slot]] = original[src].clone();
    }
}
// endregion

// region: R Wrapper File Generation

/// Write all R wrapper entries to a file.
///
/// Called from [`miniextendr_write_wrappers`] (via cdylib `dyn.load`/`.Call`).
/// All distributed_slice entries from `#[miniextendr]` items are available
/// because the cdylib includes all symbols by design.
pub fn write_r_wrappers_to_file(path: &str) {
    // Build the new content in memory
    let mut content = String::from(
        "# ---- AUTO-GENERATED FILE - DO NOT EDIT ----
# This file is generated by the miniextendr proc-macro during package build.
# Any manual changes will be overwritten.
#
# To regenerate: rebuild the package (R CMD INSTALL or devtools::install).
# nolint start
# nocov start

",
    );

    for fragment in collect_r_wrappers() {
        content.push_str(fragment.as_ref());
        content.push_str("\n\n");
    }

    content.push_str("# nocov end\n# nolint end\n");

    // Only write if content changed (avoids unnecessary NAMESPACE/man regeneration)
    let existing = std::fs::read_to_string(path).unwrap_or_default();
    if existing == content {
        return;
    }

    std::fs::write(path, content.as_bytes())
        .unwrap_or_else(|e| panic!("failed to write {path}: {e}"));

    if !existing.is_empty() {
        let filename = std::path::Path::new(path)
            .file_name()
            .and_then(|f| f.to_str())
            .unwrap_or("wrappers.R");
        eprintln!();
        eprintln!("NOTE: {filename} changed — run devtools::document() to update NAMESPACE.");
        eprintln!();
    }
}
// endregion

// region: C-Callable Entry Points (cdylib)

/// C-callable entry point for R wrapper generation via cdylib.
///
/// Called from Makevars via Rscript: loads the cdylib with `dyn.load()`,
/// then `.Call("miniextendr_write_wrappers", path)` to write
/// `R/miniextendr-wrappers.R`. NAMESPACE generation is left to roxygen2
/// (`devtools::document()`).
///
/// # Safety
///
/// `path_sexp` must be a valid STRSXP of length >= 1.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn miniextendr_write_wrappers(
    path_sexp: crate::ffi::SEXP,
) -> crate::ffi::SEXP {
    unsafe {
        use crate::ffi::{SEXP, SexpExt};

        let char_sexp = path_sexp.string_elt_unchecked(0);
        let c_str = std::ffi::CStr::from_ptr(char_sexp.r_char_unchecked());
        let path = c_str
            .to_str()
            .unwrap_or_else(|e| panic!("invalid UTF-8 in path: {e}"));

        write_r_wrappers_to_file(path);

        SEXP::nil()
    }
}
// endregion