miniextendr_api/

preserve.rs

//! **Deprecated**: Use [`ProtectPool`](crate::protect_pool::ProtectPool) or
//! [`R_PreserveObject`] instead. This module
//! remains for benchmark comparisons only. See `analysis/gc-protection-benchmarks-results.md`.
//!
//! R object preservation using a circular doubly-linked list.
//!
//! This module provides a protection scheme for R objects (SEXPs) that need to
//! survive R's garbage collection **across multiple `.Call` invocations**.
//!
//! # Protection Strategies in miniextendr
//!
//! miniextendr provides three complementary protection mechanisms for different scenarios:
//!
//! | Strategy | Module | Lifetime | Release Order | Use Case |
//! |----------|--------|----------|---------------|----------|
//! | **PROTECT stack** | [`gc_protect`](crate::gc_protect) | Within `.Call` | LIFO (stack) | Temporary allocations |
//! | **Preserve list** | [`preserve`](crate::preserve) | Across `.Call`s | Any order | Long-lived R objects |
//! | **R ownership** | [`ExternalPtr`](struct@crate::ExternalPtr) | Until R GCs | R decides | Rust data owned by R |
//!
//! ## When to Use This Module
//!
//! **Use `preserve` (this module) when:**
//! - Objects must survive across multiple `.Call` invocations
//! - You need to release protections in arbitrary order (not LIFO)
//! - Example: [`RAllocator`](crate::RAllocator) backing memory
//!
//! **Use [`gc_protect`](crate::gc_protect) instead when:**
//! - Protection is short-lived (within a single `.Call`)
//! - You want RAII-based automatic PROTECT/UNPROTECT balancing
//!
//! **Use [`ExternalPtr`](struct@crate::ExternalPtr) instead when:**
//! - You want R to own a Rust value with automatic cleanup
//!
//! # Architecture
//!
//! This module uses a cpp11-style circular doubly-linked list approach,
//! which has advantages over the R protect stack:
//!
//! - No balance requirement (PROTECT/UNPROTECT pairs must be balanced)
//! - Can release protections in any order
//! - Thread-local storage (each thread has its own preserve list)
//! - More ergonomic with RAII patterns
//!
//! The preservation list is a circular doubly-linked cons list where:
//! - The list itself is preserved with `R_PreserveObject` (never GC'd)
//! - Each protected SEXP is stored as the TAG of a cell
//! - CAR points to previous cell, CDR points to next cell
//! - Head and tail are sentinel nodes
//!
//! # Safety
//!
//! All functions in this module are unsafe and must be called from the R main thread.

use crate::ffi::{PairListExt, R_PreserveObject, Rf_protect, Rf_unprotect, SEXP, SexpExt};
use std::cell::OnceCell;

thread_local! {
    /// The per-thread preservation list.
    ///
    /// Initialized on first use with a circular doubly-linked list
    /// that is preserved from R's GC via `R_PreserveObject`.
    static PRESERVE_LIST: OnceCell<SEXP> = const { OnceCell::new() };
}

/// Initialize the preservation list.
///
/// Creates a circular doubly-linked list: `(head -> sentinel -> head)`
/// and preserves it with `R_PreserveObject` so it's never GC'd.
///
/// # Safety
///
/// Must be called from the R main thread.
#[inline]
unsafe fn init() -> SEXP {
    unsafe {
        let out = SEXP::nil().cons(SEXP::nil().cons(SEXP::nil()));
        R_PreserveObject(out);
        out
    }
}

/// Initialize the preservation list (unchecked version).
///
/// Skips thread safety checks for performance-critical paths.
///
/// # Safety
///
/// Must be called from the R main thread. Only use in contexts where
/// you're certain you're on the main thread.
#[inline]
unsafe fn init_unchecked() -> SEXP {
    use crate::ffi::{PairListExt, R_PreserveObject_unchecked};

    unsafe {
        let out = SEXP::nil().cons_unchecked(SEXP::nil().cons_unchecked(SEXP::nil()));
        R_PreserveObject_unchecked(out);
        out
    }
}

/// Get the current thread's preservation list, initializing if needed.
///
/// # Safety
///
/// Must be called from the R main thread.
#[inline]
pub(crate) unsafe fn get() -> SEXP {
    // One global preserve list per thread.
    PRESERVE_LIST.with(|x| *x.get_or_init(|| unsafe { init() }))
}

/// Get the current thread's preservation list (unchecked version).
///
/// Skips thread safety checks for performance-critical paths.
///
/// # Safety
///
/// Must be called from the R main thread. Only use in contexts where
/// you're certain you're on the main thread (ALTREP callbacks, extern "C-unwind" functions).
#[inline]
pub(crate) unsafe fn get_unchecked() -> SEXP {
    // Use unchecked init for full consistency
    PRESERVE_LIST.with(|x| *x.get_or_init(|| unsafe { init_unchecked() }))
}

/// Count the number of currently protected objects.
///
/// This is useful for debugging and testing, but not typically needed
/// in production code.
///
/// # Safety
///
/// Must be called from the R main thread.
#[cfg(feature = "debug-preserve")]
#[inline]
pub unsafe fn count() -> crate::ffi::R_xlen_t {
    use crate::ffi::{R_xlen_t, Rf_xlength};
    unsafe {
        let head: R_xlen_t = 1;
        let tail: R_xlen_t = 1;
        let list = get();
        Rf_xlength(list) - head - tail
    }
}

/// Count the number of currently protected objects (unchecked version).
///
/// Skips thread safety checks for performance-critical paths.
///
/// # Safety
///
/// Must be called from the R main thread. Only use in contexts where
/// you're certain you're on the main thread.
#[cfg(feature = "debug-preserve")]
#[inline]
pub unsafe fn count_unchecked() -> crate::ffi::R_xlen_t {
    use crate::ffi::{R_xlen_t, Rf_xlength_unchecked};

    unsafe {
        let head: R_xlen_t = 1;
        let tail: R_xlen_t = 1;
        let list = get_unchecked();
        Rf_xlength_unchecked(list) - head - tail
    }
}

/// Insert a SEXP into the preservation list, protecting it from GC.
///
/// Returns a "cell" (a cons cell) that can later be passed to [`release`]
/// to stop protecting the object.
///
/// If `x` is `R_NilValue`, returns `R_NilValue` without protection
/// (since NIL is never collected).
///
/// # Safety
///
/// Must be called from the R main thread. The returned cell must eventually
/// be passed to [`release`] to prevent leaking memory in the preserve list.
#[inline]
pub unsafe fn insert(x: SEXP) -> SEXP {
    unsafe {
        if x.is_nil() {
            return SEXP::nil();
        }

        Rf_protect(x);

        let list = get();

        // head is the list itself; next is the node after head
        let head = list;
        let next = head.cdr();

        // New cell points to current head and next
        let cell = Rf_protect(head.cons(next));
        cell.set_tag(x);

        // Splice cell between head and next
        head.set_cdr(cell);
        next.set_car(cell);

        Rf_unprotect(2);

        cell
    }
}

/// Insert a SEXP into the preservation list (unchecked version).
///
/// Skips thread safety checks for performance-critical paths.
/// Otherwise identical to [`insert`].
///
/// # Safety
///
/// Must be called from the R main thread. Only use in contexts where
/// you're certain you're on the main thread (ALTREP callbacks, extern "C-unwind" functions).
/// The returned cell must eventually be passed to [`release_unchecked`].
#[inline]
pub unsafe fn insert_unchecked(x: SEXP) -> SEXP {
    use crate::ffi::{PairListExt, Rf_protect_unchecked, Rf_unprotect_unchecked};

    unsafe {
        if x.is_nil() {
            return SEXP::nil();
        }

        Rf_protect_unchecked(x);

        let list = get_unchecked();

        // head is the list itself; next is the node after head
        let head = list;
        let next = head.cdr_unchecked();

        // New cell points to current head and next
        let cell = Rf_protect_unchecked(head.cons_unchecked(next));
        cell.set_tag_unchecked(x);

        // Splice cell between head and next
        head.set_cdr_unchecked(cell);
        next.set_car_unchecked(cell);

        Rf_unprotect_unchecked(2);

        cell
    }
}

/// Release a previously protected SEXP from the preservation list.
///
/// The `cell` parameter should be a value returned from [`insert`].
///
/// If `cell` is `R_NilValue`, this is a no-op.
///
/// # Safety
///
/// Must be called from the R main thread. The `cell` must be a valid
/// cell returned from [`insert`] and must not have been released already.
#[inline]
pub unsafe fn release(cell: SEXP) {
    if cell.is_nil() {
        return;
    }

    // Neighbors around the cell
    let lhs = cell.car();
    let rhs = cell.cdr();

    // Bypass cell
    lhs.set_cdr(rhs);
    rhs.set_car(lhs);
}

/// Release a previously protected SEXP (unchecked version).
///
/// Skips thread safety checks for performance-critical paths.
/// Otherwise identical to [`release`].
///
/// # Safety
///
/// Must be called from the R main thread. Only use in contexts where
/// you're certain you're on the main thread. The `cell` must be a valid
/// cell returned from [`insert_unchecked`] and must not have been released already.
#[inline]
pub unsafe fn release_unchecked(cell: SEXP) {
    use crate::ffi::PairListExt;

    unsafe {
        if cell.is_nil() {
            return;
        }

        // Neighbors around the cell
        let lhs = cell.car_unchecked();
        let rhs = cell.cdr_unchecked();

        // Bypass cell
        lhs.set_cdr_unchecked(rhs);
        rhs.set_car_unchecked(lhs);
    }
}