miniextendr_api/

gc_protect.rs

//! GC protection tools built on R's PROTECT stack.
//!
//! This module provides RAII wrappers around R's GC protection primitives.
//!
//! # Submodules
//!
//! | Module | Contents |
//! |--------|----------|
//! | [`tls`] | Thread-local convenience API — `tls::protect(x)` without passing `&ProtectScope` |
//!
//! # Core Types
//!
//! - [`ProtectScope`] — RAII scope that calls `UNPROTECT(n)` on drop
//! - [`OwnedProtect`] — single-value RAII protect/unprotect
//! - [`Root`] — lifetime-tied handle to a protected SEXP
//! - [`ReprotectSlot`] — `PROTECT_WITH_INDEX` + `REPROTECT` for mutable slots
//! - [`Protector`] — the trait over `ProtectScope` and
//!   [`ProtectPool`](crate::protect_pool::ProtectPool)
//!
//! # 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 |
//! | **VECSXP pool** | [`protect_pool`](crate::protect_pool) | Until released or the pool drops | Any order | Values a struct owns; many values; cross-call roots |
//! | **R ownership** | [`ExternalPtr`](struct@crate::ExternalPtr) | Until R GCs | R decides | Rust data owned by R |
//!
//! ## When to Use Each
//!
//! **Use `gc_protect` (this module) when:**
//! - You allocate R objects during a `.Call` and need them protected until return
//! - You want RAII-based automatic balancing of PROTECT/UNPROTECT
//! - Protection is short-lived (within a single function)
//!
//! **Use [`ProtectPool`](crate::protect_pool::ProtectPool) when:**
//! - A struct owns the values, or they may be dropped in any order relative to
//!   other roots: the per-call root set, `pool.root(value)`
//! - There are many values: no protect-stack entry per value
//! - Objects must survive across multiple `.Call` invocations, released one at
//!   a time in any order (O(1) insert/release with generational keys)
//!
//! **Use [`ExternalPtr`](struct@crate::ExternalPtr) when:**
//! - You want R to own a Rust value
//! - The Rust value should be dropped when R garbage collects the pointer
//! - You're exposing Rust structs to R code
//!
//! ## Visual Overview
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │  .Call("my_func", x)                                            │
//! │  ┌──────────────────────────────────────────────────────────┐   │
//! │  │  ProtectScope::new()                                     │   │
//! │  │  ├── protect(Rf_allocVector(...))  // temp allocation    │   │
//! │  │  ├── protect(Rf_allocVector(...))  // another temp       │   │
//! │  │  └── UNPROTECT(n) on scope drop                          │   │
//! │  └──────────────────────────────────────────────────────────┘   │
//! │                          ↓ return SEXP                          │
//! └─────────────────────────────────────────────────────────────────┘
//!
//! ┌─────────────────────────────────────────────────────────────────┐
//! │  ProtectPool (a root set; any drop order)                       │
//! │  ├── pool.root(value)         // keep until the pool drops      │
//! │  ├── pool.insert(sexp)        // O(1), generational key         │
//! │  ├── ... allocations, .Calls ... // objects stay rooted         │
//! │  ├── pool.release(key)        // O(1) remove                    │
//! │  └── drop(pool)               // releases everything left       │
//! └─────────────────────────────────────────────────────────────────┘
//!
//! ┌─────────────────────────────────────────────────────────────────┐
//! │  ExternalPtr<MyStruct> (R owns Rust data)                       │
//! │  ├── Construction: temporary Rf_protect                         │
//! │  ├── Return to R → R owns the EXTPTRSXP                         │
//! │  └── R GC → finalizer runs → Rust Drop executes                 │
//! └─────────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Types in This Module
//!
//! This module provides RAII wrappers around R's GC protection primitives:
//!
//! | Type | Purpose |
//! |------|---------|
//! | [`ProtectScope`] | Batch protection with automatic `UNPROTECT(n)` on drop |
//! | [`Root<'scope>`] | Lightweight handle tied to a scope's lifetime |
//! | [`OwnedProtect`] | Single-value RAII guard for simple cases |
//! | [`ReprotectSlot<'scope>`] | Protected slot supporting replace-under-protection |
//!
//! # Design Principles
//!
//! - `ProtectScope` owns the responsibility of calling `UNPROTECT(n)`
//! - `Root<'a>` is a move-friendly, non-dropping handle whose lifetime ties to the scope
//! - `ReprotectSlot<'a>` supports replace-under-protection via `PROTECT_WITH_INDEX`/`REPROTECT`
//!
//! # Safety Model
//!
//! These tools are `unsafe` to create because they require:
//!
//! 1. **Running on the R main thread** - R's API is not thread-safe
//! 2. **No panics across FFI** - Rust panics must not unwind across C boundary
//! 3. **Understanding R errors** - If R raises an error (`longjmp`), Rust destructors
//!    will not run, so scope-based unprotection will leak
//!
//! For cleanup that survives R errors, use `R_UnwindProtect` boundaries in your
//! `.Call` trampoline (see [`unwind_protect`](crate::unwind_protect)).
//!
//! # Example
//!
//! ```ignore
//! use miniextendr_api::gc_protect::ProtectScope;
//! use miniextendr_api::SEXP;
//!
//! unsafe fn process_vectors(x: SEXP, y: SEXP) -> SEXP {
//!     let scope = ProtectScope::new();
//!
//!     // Protect multiple values
//!     let x = scope.protect(x);
//!     let y = scope.protect(y);
//!
//!     // Work with protected values...
//!     let result = scope.protect(some_r_function(x.get(), y.get()));
//!
//!     result.into_raw()
//! } // UNPROTECT(3) called automatically
//! ```
//!
//! # Container Insertion Patterns
//!
//! When building containers (lists, character vectors), children need protection
//! between allocation and insertion:
//!
//! ```ignore
//! // WRONG - child unprotected between allocation and SET_VECTOR_ELT
//! let child = Rf_allocVector(REALSXP, 10);  // unprotected!
//! list.set_vector_elt(0, child);           // GC could occur before this!
//!
//! // CORRECT - use safe insertion methods
//! let list = List::from_raw(scope.alloc_vecsxp(n).into_raw());
//! for i in 0..n {
//!     let child = Rf_allocVector(REALSXP, 10);
//!     list.set_elt(i, child);  // protects child during insertion
//! }
//!
//! // EFFICIENT - use ListBuilder with scope
//! let builder = ListBuilder::new(&scope, n);
//! for i in 0..n {
//!     let child = scope.alloc_real(10).into_raw();
//!     builder.set(i, child);  // child already protected by scope
//! }
//! ```
//!
//! See [`List::set_elt`](crate::list::List::set_elt),
//! [`ListBuilder`](crate::list::ListBuilder), and
//! [`StrVec::set_str`](crate::strvec::StrVec::set_str) for safe container APIs.
//!
//! # Reassignment with `ReprotectSlot`
//!
//! Use [`ReprotectSlot`] when you need to reassign a protected value multiple times
//! without growing the protection stack:
//!
//! ```ignore
//! let slot = scope.protect_with_index(initial_value);
//! for item in items {
//!     let new_value = process(slot.get(), item);
//!     slot.set(new_value);  // R_Reprotect, stack count unchanged
//! }
//! ```
//!
//! This avoids the LIFO drop-order pitfall of reassigning `OwnedProtect` guards.

use crate::sexp_types::cetype_t;
use crate::sys::{
    R_MakeExternalPtr, R_NewEnv, R_ProtectWithIndex, R_Reprotect, Rf_alloc3DArray, Rf_allocArray,
    Rf_allocList, Rf_allocMatrix, Rf_allocS4Object, Rf_allocVector, Rf_allocVector_unchecked,
    Rf_cons, Rf_lcons, Rf_lengthgets, Rf_mkCharLenCE, Rf_protect, Rf_unprotect, Rf_xlengthgets,
};
use crate::{R_xlen_t, RNativeType, SEXP, SEXPTYPE, SexpExt};
use core::cell::{Cell, RefCell};
use core::marker::PhantomData;
use std::rc::Rc;

/// R's PROTECT_INDEX type (just `c_int` under the hood).
pub type ProtectIndex = ::std::os::raw::c_int;

/// Enforces `!Send + !Sync` (R API is not thread-safe).
type NoSendSync = PhantomData<Rc<()>>;

// region: Protector trait

/// A scope-like GC protection backend: everything it protects stays rooted
/// until the protector drops.
///
/// Code that allocates several intermediate SEXPs can take `&mut impl Protector`
/// and leave the choice of backend to its caller. There is no individual
/// release through this trait; for that, use
/// [`ProtectPool::insert`](crate::protect_pool::ProtectPool::insert) and
/// [`ProtectPool::release`](crate::protect_pool::ProtectPool::release).
///
/// # Which backend
///
/// - A temporary within one call: [`ProtectScope`], R's protect stack. The
///   cheapest; its values unprotect together, in LIFO order with the rest of
///   the stack.
/// - Many values, any drop order, or owned by a struct:
///   [`ProtectPool`](crate::protect_pool::ProtectPool), one R list that the
///   pool preserves. No protect-stack entry per value, and dropping it
///   releases everything it holds whatever the order.
/// - One long-lived object: [`Preserved`](crate::Preserved), a handle, not a
///   `Protector`.
///
/// There is no precious-list `Protector`. `R_PreserveObject` per value allocates
/// a cell each time, and `R_ReleaseObject` scans the precious list from its
/// head, so releasing many values (above all in insertion order) is O(n²), the
/// pattern the pool exists to avoid. [`OwnedProtect`] is a single
/// protect-stack entry, not a precious-list root.
///
/// # Safety
///
/// Implementations must keep every SEXP passed to
/// [`protect`](Self::protect) reachable by R's collector for as long as the
/// protector lives: safe code relies on that to hold the returned SEXP across
/// allocations.
pub unsafe trait Protector {
    /// Root `sexp` until the protector drops, and return it.
    ///
    /// `sexp` may be a fresh, unprotected object. Call it on R's main thread,
    /// where the protector was made (both implementations are `!Send`).
    fn protect(&mut self, sexp: SEXP) -> SEXP;
}

// SAFETY: `ProtectScope::new` is `unsafe`: its caller promised to use and drop
// the scope on R's main thread and to keep R's protect stack LIFO around it (no
// protection through the scope while a younger scope or guard is alive). Under
// that promise, protecting through `&mut ProtectScope` pushes one entry that
// the scope's `UNPROTECT(n)` pops at drop, so the value stays rooted for the
// scope's whole life. `Rf_protect` keeps a fresh object reachable before
// anything else allocates.
unsafe impl Protector for ProtectScope {
    #[inline]
    fn protect(&mut self, sexp: SEXP) -> SEXP {
        // SAFETY: see the impl's SAFETY comment.
        unsafe { self.protect_raw(sexp) }
    }
}

// SAFETY: `ProtectPool::insert` stores `sexp` in the pool's preserved list,
// which roots it until its slot is released or replaced, and this impl keeps
// no key to do either: the value stays rooted until the pool drops. An insert
// that grows the pool keeps `sexp` on the protect stack across the allocation.
unsafe impl Protector for crate::protect_pool::ProtectPool {
    #[inline]
    fn protect(&mut self, sexp: SEXP) -> SEXP {
        self.root(sexp)
    }
}

// endregion

// region: ProtectScope

/// A scope that automatically balances `UNPROTECT(n)` on drop.
///
/// This is the primary tool for managing GC protection in batch operations.
/// Each call to [`protect`][Self::protect] or [`protect_with_index`][Self::protect_with_index]
/// increments an internal counter; when the scope is dropped, `UNPROTECT(n)` is called.
///
/// # Example
///
/// ```ignore
/// unsafe fn my_call(x: SEXP, y: SEXP) -> SEXP {
///     let scope = ProtectScope::new();
///     let x = scope.protect(x);
///     let y = scope.protect(y);
///
///     // Both x and y are protected until scope drops
///     let result = scope.protect(some_operation(x.get(), y.get()));
///     result.get()
/// } // UNPROTECT(3)
/// ```
///
/// # Nested Scopes
///
/// Scopes can be nested. Each scope tracks only its own protections:
///
/// ```ignore
/// unsafe fn outer(x: SEXP) -> SEXP {
///     let scope = ProtectScope::new();
///     let x = scope.protect(x);
///
///     let result = helper(&scope, x.get());
///     scope.protect(result).get()
/// } // UNPROTECT(2)
///
/// unsafe fn helper(_parent: &ProtectScope, x: SEXP) -> SEXP {
///     let scope = ProtectScope::new();
///     let temp = scope.protect(allocate_something());
///     combine(x, temp.get())
/// } // UNPROTECT(1) - only this scope's protections
/// ```
pub struct ProtectScope {
    n: Cell<i32>,
    armed: Cell<bool>,
    // Created only by rooted child conversions. A pool avoids one PROTECT
    // stack entry per list/string element, and supports later child additions.
    children: ChildRoots,
    _nosend: NoSendSync,
}

impl ProtectScope {
    /// Create a new protection scope.
    ///
    /// # Safety
    ///
    /// - Use and drop the scope on R's main thread.
    /// - Keep R's protect stack LIFO around it. The scope unprotects with
    ///   `UNPROTECT(n)`, which pops the top `n` entries of the stack whoever
    ///   pushed them. So don't protect through this scope while a scope or
    ///   guard made after it is alive, and drop it after every such scope or
    ///   guard. A scope moved into a struct is easy to drop out of this order;
    ///   a [`ProtectPool`](crate::ProtectPool) owned by a struct has no such
    ///   rule.
    ///
    /// The [`Protector`] impl relies on this promise to make protecting
    /// through a constructed scope safe.
    #[inline]
    pub unsafe fn new() -> Self {
        Self {
            n: Cell::new(0),
            armed: Cell::new(true),
            children: ChildRoots::default(),
            _nosend: PhantomData,
        }
    }

    /// Protect `x` and return a rooted handle tied to this scope.
    ///
    /// This always calls `Rf_protect`. The protection is released when
    /// the scope is dropped (along with all other protections in this scope).
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - `x` must be a valid SEXP
    #[inline]
    pub unsafe fn protect<'a>(&'a self, x: SEXP) -> Root<'a> {
        let y = unsafe { Rf_protect(x) };
        self.n.set(self.n.get() + 1);
        Root {
            sexp: y,
            scope: self,
        }
    }

    /// Protect and return the raw `SEXP` (sometimes more convenient).
    ///
    /// # Safety
    ///
    /// Same as [`protect`][Self::protect].
    #[inline]
    pub unsafe fn protect_raw(&self, x: SEXP) -> SEXP {
        let y = unsafe { Rf_protect(x) };
        self.n.set(self.n.get() + 1);
        y
    }

    /// Protect `x` with an index slot so it can be replaced later via [`R_Reprotect`].
    ///
    /// Use this when you need to update a protected value in-place without
    /// growing the protection stack.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - `x` must be a valid SEXP
    ///
    /// # Example
    ///
    /// ```ignore
    /// unsafe fn accumulate(values: &[SEXP]) -> SEXP {
    ///     let scope = ProtectScope::new();
    ///     let slot = scope.protect_with_index(values[0]);
    ///
    ///     for &v in &values[1..] {
    ///         let combined = combine(slot.get(), v);
    ///         slot.set(combined);  // Reprotect without growing stack
    ///     }
    ///
    ///     slot.get()
    /// }
    /// ```
    #[inline]
    pub unsafe fn protect_with_index<'a>(&'a self, x: SEXP) -> ReprotectSlot<'a> {
        let mut idx: ProtectIndex = 0;
        unsafe { R_ProtectWithIndex(x, std::ptr::from_mut(&mut idx)) };
        self.n.set(self.n.get() + 1);
        ReprotectSlot {
            idx,
            cur: Cell::new(x),
            _scope: PhantomData,
            _nosend: PhantomData,
        }
    }

    /// Protect two values at once (convenience method).
    ///
    /// # Safety
    ///
    /// Same as [`protect`][Self::protect].
    #[inline]
    pub unsafe fn protect2<'a>(&'a self, a: SEXP, b: SEXP) -> (Root<'a>, Root<'a>) {
        // SAFETY: caller guarantees R main thread and valid SEXPs
        unsafe { (self.protect(a), self.protect(b)) }
    }

    /// Protect three values at once (convenience method).
    ///
    /// # Safety
    ///
    /// Same as [`protect`][Self::protect].
    #[inline]
    pub unsafe fn protect3<'a>(
        &'a self,
        a: SEXP,
        b: SEXP,
        c: SEXP,
    ) -> (Root<'a>, Root<'a>, Root<'a>) {
        // SAFETY: caller guarantees R main thread and valid SEXPs
        unsafe { (self.protect(a), self.protect(b), self.protect(c)) }
    }

    /// Return the current protection count.
    #[inline]
    pub fn count(&self) -> i32 {
        self.n.get()
    }

    /// Escape hatch: disable `UNPROTECT` on drop.
    ///
    /// After calling this, the scope will **not** unprotect its values when dropped.
    /// You become responsible for ensuring correct unprotection.
    ///
    /// # Safety
    ///
    /// You must ensure the protects performed in this scope are correctly
    /// unprotected elsewhere, or you will leak protect stack entries.
    #[inline]
    pub unsafe fn disarm(&self) {
        self.armed.set(false);
    }

    /// Re-arm a previously disarmed scope.
    ///
    /// # Safety
    ///
    /// Only call if you know the scope was disarmed and you want to restore
    /// automatic unprotection. Be careful not to double-unprotect.
    #[inline]
    pub unsafe fn rearm(&self) {
        self.armed.set(true);
    }

    // region: Allocation + Protection Helpers

    /// Allocate a vector of the given type and length, and immediately protect it.
    ///
    /// This combines allocation and protection in a single step, eliminating the
    /// GC gap that exists when you separately allocate and then protect.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - Only protects the newly allocated object; does not protect other live
    ///   unprotected objects during allocation
    ///
    /// # Example
    ///
    /// ```ignore
    /// unsafe fn make_ints(n: R_xlen_t) -> SEXP {
    ///     let scope = ProtectScope::new();
    ///     let vec = scope.alloc_vector(SEXPTYPE::INTSXP, n);
    ///     // fill via INTEGER(vec.get()) ...
    ///     vec.get()
    /// }
    /// ```
    #[inline]
    pub unsafe fn alloc_vector<'a>(&'a self, ty: SEXPTYPE, n: R_xlen_t) -> Root<'a> {
        // SAFETY: caller guarantees R main thread
        let sexp = unsafe { Rf_allocVector(ty, n) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a matrix of the given type and dimensions, and immediately protect it.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector`][Self::alloc_vector].
    #[inline]
    pub unsafe fn alloc_matrix<'a>(&'a self, ty: SEXPTYPE, nrow: i32, ncol: i32) -> Root<'a> {
        let sexp = unsafe { Rf_allocMatrix(ty, nrow, ncol) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a list (VECSXP) of the given length and immediately protect it.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector`][Self::alloc_vector].
    #[inline]
    pub unsafe fn alloc_list<'a>(&'a self, n: i32) -> Root<'a> {
        let sexp = unsafe { Rf_allocList(n) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a STRSXP (character vector) of the given length and immediately protect it.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector`][Self::alloc_vector].
    #[inline]
    pub unsafe fn alloc_strsxp<'a>(&'a self, n: usize) -> Root<'a> {
        unsafe { self.alloc_character(n) }
    }

    /// Allocate a VECSXP (generic list) of the given length and immediately protect it.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector`][Self::alloc_vector].
    #[inline]
    pub unsafe fn alloc_vecsxp<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::VECSXP, len) }
    }

    /// Allocate a vector via the **unchecked** FFI path and immediately protect it.
    ///
    /// `_unchecked` twin of [`alloc_vector`](Self::alloc_vector): allocates with
    /// `Rf_allocVector_unchecked` (bypassing the main-thread assertion / worker
    /// round-trip) for use inside ALTREP callbacks, `with_r_unwind_protect`, or
    /// `with_r_thread` bodies. Protection still goes through the (checked)
    /// `Rf_protect` — matching the established `OwnedProtect`-in-unchecked-context
    /// idiom — and is released with the rest of the scope on drop.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread, and only from a context where the
    /// checked-FFI assertion is intentionally bypassed (see CLAUDE.md "FFI thread
    /// checking").
    #[inline]
    pub unsafe fn alloc_vector_unchecked<'a>(&'a self, ty: SEXPTYPE, n: R_xlen_t) -> Root<'a> {
        // SAFETY: caller guarantees R main thread in a checked-bypass context.
        let sexp = unsafe { Rf_allocVector_unchecked(ty, n) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a VECSXP via the **unchecked** FFI path, protected.
    ///
    /// `_unchecked` twin of [`alloc_vecsxp`](Self::alloc_vecsxp). See
    /// [`alloc_vector_unchecked`](Self::alloc_vector_unchecked) for the safety
    /// contract.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector_unchecked`](Self::alloc_vector_unchecked).
    #[inline]
    pub unsafe fn alloc_vecsxp_unchecked<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector_unchecked(SEXPTYPE::VECSXP, len) }
    }

    /// Allocate a STRSXP via the **unchecked** FFI path, protected.
    ///
    /// `_unchecked` twin of [`alloc_character`](Self::alloc_character). See
    /// [`alloc_vector_unchecked`](Self::alloc_vector_unchecked) for the safety
    /// contract.
    ///
    /// # Safety
    ///
    /// Same as [`alloc_vector_unchecked`](Self::alloc_vector_unchecked).
    #[inline]
    pub unsafe fn alloc_character_unchecked<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector_unchecked(SEXPTYPE::STRSXP, len) }
    }

    // region: Typed vector allocation shortcuts

    /// Allocate an integer vector (INTSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_integer<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::INTSXP, len) }
    }

    /// Allocate a real vector (REALSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_real<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::REALSXP, len) }
    }

    /// Allocate a logical vector (LGLSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_logical<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::LGLSXP, len) }
    }

    /// Allocate a raw vector (RAWSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_raw<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::RAWSXP, len) }
    }

    /// Allocate a complex vector (CPLXSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_complex<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::CPLXSXP, len) }
    }

    /// Allocate a character vector (STRSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_character<'a>(&'a self, n: usize) -> Root<'a> {
        let len = R_xlen_t::try_from(n).expect("length exceeds R_xlen_t");
        unsafe { self.alloc_vector(SEXPTYPE::STRSXP, len) }
    }

    // endregion

    // region: Scalar constructors (allocate + set + protect)

    /// Create a scalar integer (length-1 INTSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_integer<'a>(&'a self, x: i32) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_integer(x)) }
    }

    /// Create a scalar real (length-1 REALSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_real<'a>(&'a self, x: f64) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_real(x)) }
    }

    /// Create a scalar logical (length-1 LGLSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_logical<'a>(&'a self, x: bool) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_logical(x)) }
    }

    /// Create a scalar complex (length-1 CPLXSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_complex<'a>(&'a self, x: crate::Rcomplex) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_complex(x)) }
    }

    /// Create a scalar raw (length-1 RAWSXP), protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_raw<'a>(&'a self, x: u8) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_raw(x)) }
    }

    /// Create a scalar string (length-1 STRSXP) from a Rust `&str`, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn scalar_string<'a>(&'a self, s: &str) -> Root<'a> {
        unsafe { self.protect(SEXP::scalar_string(SEXP::charsxp(s))) }
    }

    // endregion

    // region: CHARSXP, duplication, coercion, environment

    /// Create a CHARSXP from a Rust `&str`, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn mkchar<'a>(&'a self, s: &str) -> Root<'a> {
        unsafe { self.protect(SEXP::charsxp(s)) }
    }

    /// Deep-duplicate a SEXP, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `x` must be a valid SEXP.
    #[inline]
    pub unsafe fn duplicate<'a>(&'a self, x: SEXP) -> Root<'a> {
        unsafe { self.protect(x.duplicate()) }
    }

    /// Shallow-duplicate a SEXP, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `x` must be a valid SEXP.
    #[inline]
    pub unsafe fn shallow_duplicate<'a>(&'a self, x: SEXP) -> Root<'a> {
        unsafe { self.protect(x.shallow_duplicate()) }
    }

    /// Coerce a SEXP to a different type, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `x` must be a valid SEXP.
    #[inline]
    pub unsafe fn coerce<'a>(&'a self, x: SEXP, target: SEXPTYPE) -> Root<'a> {
        unsafe { self.protect(x.coerce(target)) }
    }

    /// Create a new environment, protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn new_env<'a>(&'a self, parent: SEXP, hash: bool, size: i32) -> Root<'a> {
        unsafe {
            self.protect(R_NewEnv(
                parent,
                if hash {
                    crate::Rboolean::TRUE
                } else {
                    crate::Rboolean::FALSE
                },
                size,
            ))
        }
    }

    // endregion

    // region: Array, pairlist, S4, and misc allocation helpers

    /// Allocate an n-dimensional array of the given type, and immediately protect it.
    ///
    /// The `dims` slice is first allocated as an integer vector inside this scope
    /// (consuming one protect slot) to satisfy `Rf_allocArray`'s SEXP-dims contract.
    /// The resulting array SEXP consumes a second protect slot.
    ///
    /// # Protect-stack budget
    ///
    /// This helper consumes **two** protect slots — one for the dims vector and
    /// one for the array — yet returns a single [`Root`] (for the array). The
    /// dims INTSXP has no accessible handle: it stays protected until the scope
    /// drops. Consequently [`count()`](Self::count) increases by 2 even though
    /// the caller sees only one `Root`. Callers budgeting protect-stack depth
    /// must account for both slots, not just the returned handle.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `dims` must be non-empty.
    #[inline]
    pub unsafe fn alloc_array<'a>(&'a self, ty: SEXPTYPE, dims: &[i32]) -> Root<'a> {
        // Build the dims INTSXP inside the scope so it is protected across the
        // Rf_allocArray call (which may trigger GC).
        let dims_len = R_xlen_t::try_from(dims.len()).expect("dims length exceeds R_xlen_t");
        let dims_sexp = unsafe { self.alloc_vector(SEXPTYPE::INTSXP, dims_len) };
        for (i, &d) in dims.iter().enumerate() {
            dims_sexp.get().set_integer_elt(i as isize, d);
        }
        let sexp = unsafe { Rf_allocArray(ty, dims_sexp.get()) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a 3-dimensional array of the given type, and immediately protect it.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_3d_array<'a>(
        &'a self,
        ty: SEXPTYPE,
        nrow: i32,
        ncol: i32,
        nface: i32,
    ) -> Root<'a> {
        let sexp = unsafe { Rf_alloc3DArray(ty, nrow, ncol, nface) };
        unsafe { self.protect(sexp) }
    }

    /// Allocate a language object (LANGSXP) of the given length, and immediately protect it.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_lang<'a>(&'a self, n: i32) -> Root<'a> {
        // Rf_allocLang was added in R 4.4.1. Use the equivalent construction
        // from Writing R Extensions, "Some backports", also on R 4.4.0.
        let sexp = unsafe {
            if n > 0 {
                crate::sys::Rf_lcons(crate::sys::R_NilValue, Rf_allocList(n - 1))
            } else {
                crate::sys::R_NilValue
            }
        };
        unsafe { self.protect(sexp) }
    }

    /// Allocate an S4 object (S4SXP), and immediately protect it.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn alloc_s4_object<'a>(&'a self) -> Root<'a> {
        let sexp = unsafe { Rf_allocS4Object() };
        unsafe { self.protect(sexp) }
    }

    /// Create a CHARSXP with a specified encoding and byte length, protected.
    ///
    /// This is the general form; see [`mkchar`][Self::mkchar] for the plain UTF-8 shorthand.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `s` must be valid for `len` bytes.
    #[inline]
    pub unsafe fn mkchar_len_ce<'a>(&'a self, s: &[u8], enc: cetype_t) -> Root<'a> {
        let len = i32::try_from(s.len()).expect("string length exceeds i32");
        let sexp = unsafe { Rf_mkCharLenCE(s.as_ptr().cast::<::std::os::raw::c_char>(), len, enc) };
        unsafe { self.protect(sexp) }
    }

    /// Create a CHARSXP from a Rust `&str` with a specified encoding, protected.
    ///
    /// This is the length-counted variant (wraps `Rf_mkCharLenCE`); it is safe for
    /// strings with embedded NUL bytes and does not require a NUL terminator.
    /// For the raw NUL-terminated `Rf_mkCharCE` form, use
    /// [`mkchar_len_ce`][Self::mkchar_len_ce] with `s.as_bytes()`.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn mkchar_ce<'a>(&'a self, s: &str, enc: cetype_t) -> Root<'a> {
        let len = i32::try_from(s.len()).expect("string length exceeds i32");
        let sexp = unsafe { Rf_mkCharLenCE(s.as_ptr().cast::<::std::os::raw::c_char>(), len, enc) };
        unsafe { self.protect(sexp) }
    }

    /// Construct a pairlist cons cell (`LISTSXP`) and immediately protect it.
    ///
    /// Allocates a single cons cell with `car` as the head and `cdr` as the tail.
    /// Both `car` and `cdr` must already be protected.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `car` and `cdr` must be valid SEXPs.
    #[inline]
    pub unsafe fn cons<'a>(&'a self, car: SEXP, cdr: SEXP) -> Root<'a> {
        let sexp = unsafe { Rf_cons(car, cdr) };
        unsafe { self.protect(sexp) }
    }

    /// Construct a language cons cell (`LANGSXP`) and immediately protect it.
    ///
    /// Like [`cons`][Self::cons] but marks the node as `LANGSXP` (function call list).
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `car` and `cdr` must be valid SEXPs.
    #[inline]
    pub unsafe fn lcons<'a>(&'a self, car: SEXP, cdr: SEXP) -> Root<'a> {
        let sexp = unsafe { Rf_lcons(car, cdr) };
        unsafe { self.protect(sexp) }
    }

    /// Resize a vector to a new length (short-vector variant), returning a protected copy.
    ///
    /// Wraps `Rf_lengthgets`. Both the source vector and the resized copy should be
    /// protected; the copy is protected by this call.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `x` must be a valid vector SEXP.
    #[inline]
    pub unsafe fn lengthgets<'a>(&'a self, x: SEXP, n: R_xlen_t) -> Root<'a> {
        let sexp = unsafe { Rf_lengthgets(x, n) };
        unsafe { self.protect(sexp) }
    }

    /// Resize a vector to a new length (long-vector variant), returning a protected copy.
    ///
    /// Like [`lengthgets`][Self::lengthgets] but uses `Rf_xlengthgets`, which accepts
    /// `R_xlen_t` lengths beyond `INT_MAX`.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `x` must be a valid vector SEXP.
    #[inline]
    pub unsafe fn xlengthgets<'a>(&'a self, x: SEXP, n: R_xlen_t) -> Root<'a> {
        let sexp = unsafe { Rf_xlengthgets(x, n) };
        unsafe { self.protect(sexp) }
    }

    /// Create an external pointer SEXP, and immediately protect it.
    ///
    /// This is an escape-hatch tier wrapper around `R_MakeExternalPtr`. In most
    /// cases you should use [`ExternalPtr<T>`](struct@crate::ExternalPtr) instead — it
    /// provides typed safety, finalizer registration, and correct rooting (#841).
    /// Use this wrapper only when you need raw `EXTPTRSXP` construction that
    /// `ExternalPtr<T>` cannot express.
    ///
    /// Both `tag` and `prot` must be valid SEXPs (pass `R_NilValue` if unused).
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread. `p`, `tag`, and `prot` must all be
    /// valid for the duration of the external pointer's lifetime.
    #[inline]
    pub unsafe fn make_external_ptr<'a>(
        &'a self,
        p: *mut ::std::os::raw::c_void,
        tag: SEXP,
        prot: SEXP,
    ) -> Root<'a> {
        let sexp = unsafe { R_MakeExternalPtr(p, tag, prot) };
        unsafe { self.protect(sexp) }
    }

    // endregion

    /// Create a `Root<'a>` for an already-protected SEXP without adding protection.
    ///
    /// This is useful when you have a SEXP that is already protected by some other
    /// mechanism (e.g., a `ReprotectSlot`, or a `.Call` argument, which R roots
    /// until the call returns) and want to return it as a `Root` tied to this
    /// scope's lifetime. Generated wrappers bind borrowed parameters this way.
    ///
    /// # Safety
    ///
    /// - The caller must ensure `sexp` is already protected and will remain
    ///   protected for at least the lifetime of this scope
    /// - Must be called from the R main thread
    #[inline]
    pub unsafe fn rooted<'a>(&'a self, sexp: SEXP) -> Root<'a> {
        Root { sexp, scope: self }
    }
    // endregion

    // region: Iterator Collection

    /// Collect an iterator into a typed R vector.
    ///
    /// This allocates once, protects, and fills directly - the most efficient pattern
    /// for typed vectors. The element type `T` determines the R vector type via
    /// the [`RNativeType`] trait.
    ///
    /// # Type Mapping
    ///
    /// | Rust Type | R Vector Type |
    /// |-----------|---------------|
    /// | `i32` | `INTSXP` |
    /// | `f64` | `REALSXP` |
    /// | `u8` | `RAWSXP` |
    /// | [`RLogical`](crate::RLogical) | `LGLSXP` |
    /// | [`Rcomplex`](crate::Rcomplex) | `CPLXSXP` |
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    ///
    /// # Example
    ///
    /// ```ignore
    /// unsafe fn squares(n: usize) -> SEXP {
    ///     let scope = ProtectScope::new();
    ///     // Type inferred from iterator
    ///     scope.collect((0..n).map(|i| (i * i) as i32)).get()
    /// }
    /// ```
    ///
    /// # Unknown Length
    ///
    /// For iterators without exact size (e.g., `filter`), collect to `Vec` first:
    ///
    /// ```ignore
    /// let evens: Vec<i32> = data.iter().filter(|x| *x % 2 == 0).copied().collect();
    /// scope.collect(evens)
    /// ```
    #[inline]
    pub unsafe fn collect<'a, T, I>(&'a self, iter: I) -> Root<'a>
    where
        T: RNativeType,
        I: IntoIterator<Item = T>,
        I::IntoIter: ExactSizeIterator,
    {
        let iter = iter.into_iter();
        let len = iter.len();

        let vec = unsafe { self.alloc_vector(T::SEXP_TYPE, len as R_xlen_t) };
        let ptr = unsafe { T::dataptr_mut(vec.get()) };

        for (i, value) in iter.enumerate() {
            unsafe { ptr.add(i).write(value) };
        }

        vec
    }
}

impl Drop for ProtectScope {
    #[inline]
    fn drop(&mut self) {
        if !self.armed.get() {
            return;
        }
        let n = self.n.replace(0);
        if n > 0 {
            unsafe { Rf_unprotect(n) };
        }
    }
}

// endregion

// region: Root

/// Lazy retention of uncached ALTREP elements, shared by call scopes and
/// owned views. Ordinary vectors already trace their elements and need no pool.
#[derive(Default)]
pub(crate) struct ChildRoots(RefCell<Option<Box<crate::protect_pool::ProtectPool>>>);

impl ChildRoots {
    /// Keep `child` alive until this storage drops.
    ///
    /// # Safety
    /// R's main thread; `parent` and `child` must be live on entry. An ordinary
    /// parent must remain rooted while its returned children are in use.
    pub(crate) unsafe fn protect(&self, parent: SEXP, child: SEXP) -> SEXP {
        if !parent.is_altrep() {
            return child;
        }
        let mut children = self.0.borrow_mut();
        let pool = children.get_or_insert_with(|| {
            // Creating the pool allocates before it retains the child. Its
            // inserts keep the child reachable while the pool grows.
            let _child = unsafe { OwnedProtect::new(child) };
            Box::new(crate::protect_pool::ProtectPool::new(
                crate::protect_pool::ProtectPool::DEFAULT_CAPACITY,
            ))
        });
        pool.root(child)
    }
}

/// A rooted SEXP tied to the lifetime of a [`ProtectScope`].
///
/// This type has **no `Drop`**. The scope owns unprotection responsibility.
/// This makes `Root` cheap to move and copy (the SEXP and its scope reference).
///
/// # Lifetime
///
/// The `'a` lifetime ties the root to its creating scope. The compiler ensures
/// you cannot use the root after the scope has been dropped.
#[derive(Clone, Copy)]
pub struct Root<'a> {
    sexp: SEXP,
    scope: &'a ProtectScope,
}

impl<'a> Root<'a> {
    /// Root `child`, an element read from this root, for this root's lifetime.
    ///
    /// An ordinary vector holds its elements, so its root already covers them.
    /// An ALTREP accessor may return a fresh object that its parent does not
    /// keep; the scope then retains it in a lazily allocated pool until the
    /// scope drops, without a PROTECT stack entry per element.
    ///
    /// # Safety
    /// R's main thread; `child` must be live on entry.
    pub(crate) unsafe fn protect_child(self, child: SEXP) -> Self {
        Root {
            sexp: unsafe { self.scope.children.protect(self.sexp, child) },
            scope: self.scope,
        }
    }

    /// Retention storage borrowed by views that read their elements lazily.
    pub(crate) fn child_roots(self) -> &'a ChildRoots {
        &self.scope.children
    }

    /// Get the underlying SEXP.
    #[inline]
    pub fn get(&self) -> SEXP {
        self.sexp
    }

    /// Consume the root and return the underlying SEXP.
    ///
    /// The SEXP remains protected until the scope drops.
    #[inline]
    pub fn into_raw(self) -> SEXP {
        self.sexp
    }
}

impl<'a> std::ops::Deref for Root<'a> {
    type Target = SEXP;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &self.sexp
    }
}
// endregion

// region: OwnedProtect

/// A single-object RAII guard: `PROTECT` on create, `UNPROTECT(1)` on drop.
///
/// Use this for simple cases where you're protecting a single value and
/// don't need the batching benefits of [`ProtectScope`].
///
/// # Example
///
/// ```ignore
/// unsafe fn allocate_and_fill() -> SEXP {
///     let guard = OwnedProtect::new(Rf_allocVector(REALSXP, 10));
///     fill_vector(guard.get());
///     // Return the SEXP - guard drops and unprotects on this line.
///     // This is safe because no GC can occur between unprotect and return.
///     guard.get()
/// }
/// ```
///
/// # Warning: Stack Ordering
///
/// `OwnedProtect` uses `UNPROTECT(1)`, which removes the **top** of the protection
/// stack. If you have nested protections from other sources, the drop order matters!
///
/// For complex scenarios, prefer [`ProtectScope`] which unprotects all its values
/// at once when dropped.
pub struct OwnedProtect {
    sexp: SEXP,
    armed: bool,
    _nosend: NoSendSync,
}

impl OwnedProtect {
    /// Create a new protection guard for `x`.
    ///
    /// Calls `Rf_protect(x)` immediately.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - `x` must be a valid SEXP
    #[inline]
    pub unsafe fn new(x: SEXP) -> Self {
        let y = unsafe { Rf_protect(x) };
        Self {
            sexp: y,
            armed: true,
            _nosend: PhantomData,
        }
    }

    /// Get the protected SEXP.
    #[inline]
    pub fn get(&self) -> SEXP {
        self.sexp
    }

    /// Escape hatch: do not `UNPROTECT(1)` on drop.
    ///
    /// # Safety
    ///
    /// Leaks one protection entry unless unprotected elsewhere.
    #[inline]
    pub unsafe fn forget(mut self) {
        self.armed = false;
        core::mem::forget(self);
    }
}

impl Drop for OwnedProtect {
    #[inline]
    fn drop(&mut self) {
        if self.armed {
            unsafe { Rf_unprotect(1) };
        }
    }
}

impl std::ops::Deref for OwnedProtect {
    type Target = SEXP;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &self.sexp
    }
}
// endregion

// region: Protected

/// A Rust value (`T`) bundled with an [`OwnedProtect`] guard on an SEXP
/// the value borrows from. The protect releases on drop; the lifetime
/// ties any borrows inside `T` to `&self`, so `T`'s SEXP-internal
/// references can't outlive the protection.
///
/// # When to use `Protected<'a, T>` vs the alternatives
///
/// | Pattern | Use | Why |
/// |---------|-----|-----|
/// | [`OwnedProtect`] | raw SEXP, no Rust view | one-shot protect/unprotect on a single SEXP |
/// | [`ProtectScope`] + [`Root`] | several SEXPs in one function body | batched UNPROTECT, no Rust view |
/// | `Protected<'a, T>` | SEXP + Rust view of its data | pairs a root with `T`; does not constrain references inside `T` |
///
/// # Lifetimes and thread affinity
///
/// This generic bundle does not shorten lifetimes inside `T`. Its callers must
/// avoid exposing an inner borrowed view after the root is released; use a
/// concrete owner with accessors tied to `&self` (such as
/// [`ProtectedStrVec`](crate::ProtectedStrVec)) for that guarantee.
/// `Option<OwnedProtect>` is `!Send + !Sync` even when its value is `None`;
/// the trusted constructor does not change those auto-trait properties.
pub struct Protected<'a, T> {
    inner: T,
    _protect: Option<OwnedProtect>,
    _marker: core::marker::PhantomData<&'a ()>,
}

impl<'a, T> Protected<'a, T> {
    /// Create a protected bundle. Calls `Rf_protect` on `sexp`.
    ///
    /// `inner` may borrow from `sexp`, but this bundle does not rewrite those
    /// lifetimes. The caller must ensure any references copied from `inner`
    /// remain valid, including after this root is dropped.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread.
    /// - `sexp` must be a valid SEXP.
    /// - Borrowed data in `inner` must remain valid for its declared lifetime;
    ///   this guard alone cannot guarantee that when `T` exposes a longer
    ///   reference (for example, `T = &'static str`).
    ///
    /// # Example
    ///
    /// ```ignore
    /// use miniextendr_api::{Protected, OwnedProtect};
    /// use miniextendr_api::prelude::SEXP;
    ///
    /// unsafe fn wrap_view(sexp: SEXP, view: MyView<'_>) -> Protected<'_, MyView<'_>> {
    ///     // Protect the SEXP and bundle it with the view.
    ///     // The caller must keep any references exposed by MyView valid.
    ///     Protected::new(sexp, view)
    /// }
    /// ```
    #[inline]
    pub unsafe fn new(sexp: SEXP, inner: T) -> Self {
        let guard = unsafe { OwnedProtect::new(sexp) };
        Self {
            inner,
            _protect: Some(guard),
            _marker: core::marker::PhantomData,
        }
    }

    /// Create a protected bundle without adding to the protect stack.
    ///
    /// Use when `sexp` is already protected by R (a `.Call` argument,
    /// a [`ProtectScope`] slot, an enclosing [`OwnedProtect`]) to avoid
    /// double-protecting. As with `new`, `'a` does not narrow references
    /// contained in `T`.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread.
    /// - `sexp` must be a valid SEXP.
    /// - `sexp` must remain GC-protected for the lifetime of the
    ///   returned `Protected`.
    /// - Lifetime contract same as [`Protected::new`].
    #[inline]
    pub unsafe fn from_trusted(_sexp: SEXP, inner: T) -> Self {
        Self {
            inner,
            _protect: None,
            _marker: core::marker::PhantomData,
        }
    }

    /// Borrow the inner view.
    #[inline]
    pub fn get(&self) -> &T {
        &self.inner
    }

    /// Consume the bundle and return the inner view.
    ///
    /// The [`OwnedProtect`] guard drops here, releasing the SEXP from the protect
    /// stack. Any owned data extracted from `T` must not retain SEXP references
    /// after this point.
    #[inline]
    pub fn into_inner(self) -> T {
        self.inner
    }
}

impl<'a, T> core::ops::Deref for Protected<'a, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &T {
        &self.inner
    }
}

impl<'a, T: std::fmt::Debug> std::fmt::Debug for Protected<'a, T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Protected")
            .field("inner", &self.inner)
            .field("protected", &self._protect.is_some())
            .finish()
    }
}
// endregion

// region: ReprotectSlot

/// A protected slot created with `R_ProtectWithIndex` and updated with `R_Reprotect`.
///
/// This allows updating a protected value in-place without growing the protection
/// stack. Useful for loops that repeatedly allocate and update a value.
///
/// The slot is valid only while the creating [`ProtectScope`] is alive.
///
/// # When to Use `ReprotectSlot`
///
/// Use `ReprotectSlot` when you need to **reassign a protected value** multiple times:
///
/// | Pattern | Use | Why |
/// |---------|-----|-----|
/// | Accumulator loop | `ReprotectSlot` | Repeatedly replace result without stack growth |
/// | Single allocation | `ProtectScope::protect` | Simpler, no reassignment needed |
/// | Child insertion | `List::set_elt` | Container handles child protection |
///
/// # Warning: RAII Assignment Pitfall
///
/// R's PROTECT stack is LIFO. Rust's RAII drop order can cause problems:
///
/// ```ignore
/// // WRONG - can unprotect the new value instead of the old!
/// let mut guard = OwnedProtect::new(old_value);
/// guard = OwnedProtect::new(new_value);  // Old guard drops AFTER new is assigned
/// ```
///
/// `ReprotectSlot` avoids this by using `R_Reprotect` which replaces in-place:
///
/// ```ignore
/// // CORRECT - always keeps exactly one slot protected
/// let slot = scope.protect_with_index(old_value);
/// slot.set(new_value);  // R_Reprotect, no stack change
/// ```
///
/// # Examples
///
/// ## Accumulator Pattern
///
/// ```ignore
/// unsafe fn sum_allocated_vectors(n: i32) -> SEXP {
///     let scope = ProtectScope::new();
///
///     // Initial allocation
///     let slot = scope.protect_with_index(Rf_allocVector(REALSXP, 10));
///
///     for i in 0..n {
///         // Each iteration allocates a new vector
///         let new_vec = compute_step(slot.get(), i);
///         slot.set(new_vec);  // Replace without growing protect stack
///     }
///
///     slot.get()
/// }
/// ```
///
/// ## Starting with Empty Slot
///
/// ```ignore
/// unsafe fn build_result(items: &[Input]) -> SEXP {
///     let scope = ProtectScope::new();
///
///     // Start with R_NilValue, replace with first real result
///     let slot = scope.protect_with_index(R_NilValue);
///
///     for (i, item) in items.iter().enumerate() {
///         let result = process_item(item, slot.get());
///         slot.set(result);
///     }
///
///     slot.get()
/// }
/// ```
///
/// ## Multiple Slots
///
/// ```ignore
/// unsafe fn merge_sorted(a: SEXP, b: SEXP) -> SEXP {
///     let scope = ProtectScope::new();
///
///     let slot_a = scope.protect_with_index(a);
///     let slot_b = scope.protect_with_index(b);
///     let result = scope.protect_with_index(R_NilValue);
///
///     // Process both inputs, updating result
///     while !is_empty(slot_a.get()) && !is_empty(slot_b.get()) {
///         let merged = merge_next(slot_a.get(), slot_b.get());
///         result.set(merged);
///         // ... update slot_a and slot_b as needed
///     }
///
///     result.get()
/// }
/// ```
pub struct ReprotectSlot<'a> {
    idx: ProtectIndex,
    cur: Cell<SEXP>,
    _scope: PhantomData<&'a ProtectScope>,
    _nosend: NoSendSync,
}

impl<'a> ReprotectSlot<'a> {
    /// Get the currently protected SEXP.
    #[inline]
    pub fn get(&self) -> SEXP {
        self.cur.get()
    }

    /// Replace the protected value in-place using `R_Reprotect`.
    ///
    /// The new value `x` becomes protected in this slot, and the old value
    /// is no longer protected (but may still be rooted elsewhere).
    ///
    /// Returns the raw SEXP for convenience. Note that this SEXP is only
    /// protected until the next call to `set()` on this slot - if you need
    /// to hold multiple protected values simultaneously, use separate
    /// protection slots or `OwnedProtect`.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - `x` must be a valid SEXP
    #[inline]
    pub unsafe fn set(&self, x: SEXP) -> SEXP {
        unsafe { R_Reprotect(x, self.idx) };
        self.cur.set(x);
        x
    }

    /// Allocate a new value via the closure and replace this slot's value safely.
    ///
    /// This method encodes the safe pattern for replacing a protected slot with
    /// a newly allocated value. It:
    ///
    /// 1. Calls the closure `f()` to allocate a new SEXP
    /// 2. Temporarily protects the new value (to close the GC gap)
    /// 3. Calls `R_Reprotect` to replace this slot's value
    /// 4. Unprotects the temporary protection
    ///
    /// This prevents the GC gap that would exist if you called `f()` and then
    /// `set()` separately - during that window, the newly allocated value would
    /// be unprotected.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - The closure must return a valid SEXP
    ///
    /// # Example
    ///
    /// ```ignore
    /// unsafe fn grow_list(scope: &ProtectScope, old_list: SEXP) -> SEXP {
    ///     let slot = scope.protect_with_index(old_list);
    ///
    ///     // Safely grow the list without GC gap
    ///     slot.set_with(|| {
    ///         let new_list = Rf_allocVector(VECSXP, new_size);
    ///         // copy elements from old_list to new_list...
    ///         new_list
    ///     });
    ///
    ///     slot.get()
    /// }
    /// ```
    #[inline]
    pub unsafe fn set_with<F>(&self, f: F) -> SEXP
    where
        F: FnOnce() -> SEXP,
    {
        // Allocate the new value
        let new_value = f();

        // Temporarily protect the new value to close the GC gap
        let temp = unsafe { Rf_protect(new_value) };

        // Replace this slot's value with the new value
        unsafe { R_Reprotect(temp, self.idx) };
        self.cur.set(temp);

        // Remove the temporary protection (slot now owns the protection)
        unsafe { Rf_unprotect(1) };

        temp
    }

    /// Take the current value and clear the slot to `R_NilValue`.
    ///
    /// This provides `Option::take`-like semantics. The slot remains allocated
    /// (protect stack depth unchanged), but now holds `R_NilValue` (immortal).
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - The returned SEXP is **unprotected**. If it needs to survive further
    ///   allocations, you must protect it explicitly.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let slot = scope.protect_with_index(some_value);
    /// // ... work with slot.get() ...
    /// let old = slot.take();  // slot now holds R_NilValue
    /// // old is unprotected - protect it if needed
    /// let guard = OwnedProtect::new(old);
    /// ```
    #[inline]
    pub unsafe fn take(&self) -> SEXP {
        let old = self.cur.get();
        let nil = SEXP::nil();
        unsafe { R_Reprotect(nil, self.idx) };
        self.cur.set(nil);
        old
    }

    /// Replace the slot's value with `x` and return the old value.
    ///
    /// This provides `Option::replace`-like semantics. The slot now protects
    /// `x`, and the old value is returned **unprotected**.
    ///
    /// # Safety
    ///
    /// - Must be called from the R main thread
    /// - `x` must be a valid SEXP
    /// - The returned SEXP is **unprotected**. If it needs to survive further
    ///   allocations, you must protect it explicitly.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let slot = scope.protect_with_index(initial);
    /// let old = slot.replace(new_value);
    /// // old is unprotected, slot now protects new_value
    /// ```
    #[inline]
    pub unsafe fn replace(&self, x: SEXP) -> SEXP {
        let old = self.cur.get();
        unsafe { R_Reprotect(x, self.idx) };
        self.cur.set(x);
        old
    }

    /// Clear the slot by setting it to `R_NilValue`.
    ///
    /// The slot remains allocated (protect stack depth unchanged), but releases
    /// its reference to the previous value. The previous value may still be
    /// rooted elsewhere.
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread.
    #[inline]
    pub unsafe fn clear(&self) {
        let nil = SEXP::nil();
        unsafe { R_Reprotect(nil, self.idx) };
        self.cur.set(nil);
    }

    /// Check if the slot is currently cleared (holds `R_NilValue`).
    ///
    /// # Safety
    ///
    /// Must be called from the R main thread (accesses R's `R_NilValue`).
    #[inline]
    pub unsafe fn is_nil(&self) -> bool {
        self.cur.get() == SEXP::nil()
    }
}

// NOTE: Deref was intentionally removed to avoid UB.
// The previous impl fabricated `&SEXP` from `Cell<SEXP>` via pointer cast,
// which violates Cell's aliasing rules if `set()` is called while a
// reference is live. Use `get()` instead, which returns SEXP by value.
// endregion

pub mod tls;

// region: WorkerUnprotectGuard — Send-safe unprotect for worker threads

/// A `Send`-safe guard that calls `Rf_unprotect(n)` on drop via `with_r_thread`.
///
/// Use this when you `Rf_protect` on the R main thread, then need the unprotect
/// to happen when a guard drops on a **worker thread** (e.g., rayon parallel code).
///
/// [`OwnedProtect`] and [`ProtectScope`] are `!Send` — they can only be used on
/// the R main thread. `WorkerUnprotectGuard` fills the gap for cross-thread patterns
/// where allocation + protect happen on the R thread but the guard lives on a worker.
///
/// # Example
///
/// ```ignore
/// use miniextendr_api::gc_protect::WorkerUnprotectGuard;
///
/// let sexp = with_r_thread(|| unsafe {
///     let sexp = Rf_allocVector(REALSXP, n);
///     Rf_protect(sexp);
///     sexp
/// });
/// let _guard = WorkerUnprotectGuard::new(1);
///
/// // ... parallel work on sexp's data ...
/// // _guard drops here, dispatching Rf_unprotect(1) back to R thread
/// ```
pub struct WorkerUnprotectGuard(i32);

impl WorkerUnprotectGuard {
    /// Create a guard that will unprotect `n` entries on drop.
    #[inline]
    pub fn new(n: i32) -> Self {
        Self(n)
    }
}

impl Drop for WorkerUnprotectGuard {
    fn drop(&mut self) {
        let n = self.0;
        crate::worker::with_r_thread(move || unsafe {
            crate::sys::Rf_unprotect_unchecked(n);
        });
    }
}

// Safety: no SEXP field, just an integer count. The actual Rf_unprotect call
// is dispatched to the R main thread via with_r_thread.
unsafe impl Send for WorkerUnprotectGuard {}
// endregion

// region: Typed Vector Collection

// NOTE: Typed vectors (INTSXP, REALSXP, RAWSXP, LGLSXP, CPLXSXP) do NOT need
// complex protection patterns during construction. You allocate once, protect
// once, then fill by writing directly to the data pointer. No GC can occur
// during the fill because you're just doing pointer writes - no R allocations.
//
// Only STRSXP (character vectors) and VECSXP (lists) need the ReprotectSlot
// pattern because each element insertion might allocate (mkChar, etc.).
//
// For typed vectors with unknown length, just collect to Vec<T> first, then
// allocate the exact size. The brief doubling of memory is fine.
// endregion

// region: Tests

#[cfg(test)]
mod tests {
    use super::*;

    // Note: These tests primarily verify compilation and basic invariants.
    // Full integration testing requires R to be initialized.
    // endregion

    // region: Basic invariants

    #[test]
    fn protect_scope_has_nosend_marker() {
        // Verify the NoSendSync marker type is present
        // (ProtectScope contains PhantomData<Rc<()>> which makes it !Send + !Sync)
        let _: NoSendSync = PhantomData;
    }

    #[test]
    fn protect_scope_default_count_is_zero() {
        let scope = unsafe { ProtectScope::new() };
        assert_eq!(scope.count(), 0);
    }

    #[test]
    fn root_is_copy() {
        fn assert_copy<T: Copy>() {}
        assert_copy::<Root<'static>>();
    }

    #[test]
    fn tls_root_is_copy() {
        fn assert_copy<T: Copy>() {}
        assert_copy::<tls::TlsRoot>();
    }
    // endregion

    // region: Threading: compile-time !Send + !Sync checks

    #[test]
    fn protect_scope_is_not_send() {
        fn assert_not_send<T>()
        where
            T: ?Sized,
        {
            // This test passes if ProtectScope is !Send
            // We can't directly assert !Send, but the type containing Rc<()> ensures it
        }
        assert_not_send::<ProtectScope>();
    }

    #[test]
    fn protect_scope_is_not_sync() {
        fn assert_not_sync<T>()
        where
            T: ?Sized,
        {
            // This test passes if ProtectScope is !Sync
        }
        assert_not_sync::<ProtectScope>();
    }

    #[test]
    fn owned_protect_is_not_send() {
        fn assert_not_send<T>()
        where
            T: ?Sized,
        {
        }
        assert_not_send::<OwnedProtect>();
    }

    // Note: We can't easily assert !Send/!Sync at compile time without
    // negative trait bounds. The PhantomData<Rc<()>> marker ensures these types
    // are !Send and !Sync. If you need compile-time verification, use the
    // static_assertions crate with `assert_not_impl_any!`.
    // endregion

    // region: TLS scope tests

    #[test]
    fn tls_no_active_scope_by_default() {
        assert!(!tls::has_active_scope());
        assert_eq!(tls::current_count(), None);
        assert_eq!(tls::scope_depth(), 0);
    }

    #[test]
    fn tls_scope_depth_tracking() {
        // Without R, we can only test the TLS tracking logic
        // The actual protect/unprotect requires R runtime

        // Test that scope depth is tracked correctly
        assert_eq!(tls::scope_depth(), 0);

        // We can't fully test with_protect_scope without R initialized,
        // but we can verify the API compiles and the TLS logic works
    }

    #[test]
    #[should_panic(expected = "tls::protect called outside of with_protect_scope")]
    fn tls_protect_panics_outside_scope() {
        // This should panic because there's no active scope
        // Note: Can't actually call protect without R, but we test the panic message
        unsafe {
            let _ = tls::protect(crate::SEXP(std::ptr::null_mut()));
        }
    }
    // endregion

    // region: Escape hatch tests

    #[test]
    fn disarm_prevents_unprotect() {
        let scope = unsafe { ProtectScope::new() };
        assert!(scope.armed.get());

        unsafe { scope.disarm() };
        assert!(!scope.armed.get());

        // Scope will drop without calling Rf_unprotect (can't test actual R call)
    }

    #[test]
    fn rearm_restores_unprotect() {
        let scope = unsafe { ProtectScope::new() };

        unsafe {
            scope.disarm();
            assert!(!scope.armed.get());

            scope.rearm();
            assert!(scope.armed.get());
        }
    }
    // endregion

    // region: Counter tracking tests

    #[test]
    fn scope_counter_starts_at_zero() {
        let scope = unsafe { ProtectScope::new() };
        assert_eq!(scope.count(), 0);
    }

    // Note: The following tests require R to be initialized and would be
    // integration tests rather than unit tests:
    //
    // - Balance test: protect N, verify unprotect(N) on drop (gctorture)
    // - Nested scopes: verify drop order yields correct net unprotect
    // - Reprotect slot: verify set() many times keeps count at +1
    //
    // These should be tested in miniextendr-api/tests/gc_protect.rs with
    // embedded R.
    // endregion

    // region: Protected<'a, T> tests

    /// Verify `Protected::get()` returns the inner value.
    #[test]
    fn protected_get_returns_inner() {
        // from_trusted with null SEXP (safe for compile-time tests since we
        // never dereference the SEXP itself, only the already-constructed inner)
        let v = vec![1i32, 2, 3];
        let p = unsafe {
            Protected::<'static, Vec<i32>>::from_trusted(crate::SEXP(core::ptr::null_mut()), v)
        };
        assert_eq!(p.get(), &[1, 2, 3]);
    }

    /// Verify `Deref<Target = T>` works (exercises the blanket impl).
    #[test]
    fn protected_deref_reaches_inner() {
        let v = vec![10i32, 20];
        let p = unsafe {
            Protected::<'static, Vec<i32>>::from_trusted(crate::SEXP(core::ptr::null_mut()), v)
        };
        // Deref should let us call Vec methods directly.
        assert_eq!(p.len(), 2);
    }

    /// Verify `into_inner` moves the inner value out cleanly.
    #[test]
    fn protected_into_inner_moves_value() {
        let v = vec![42i32];
        let p = unsafe {
            Protected::<'static, Vec<i32>>::from_trusted(crate::SEXP(core::ptr::null_mut()), v)
        };
        let got = p.into_inner();
        assert_eq!(got, [42]);
    }

    /// Verify `from_trusted` sets `_protect` to `None` (no extra protect push).
    #[test]
    fn protected_from_trusted_does_not_hold_protect() {
        let v: Vec<u8> = vec![];
        let p = unsafe {
            Protected::<'static, Vec<u8>>::from_trusted(crate::SEXP(core::ptr::null_mut()), v)
        };
        // This test uses `from_trusted` to avoid touching the protect stack;
        // `Protected::new` would require an initialized R runtime (see
        // `tests/gc_protect.rs` for that path). Verify the `_protect` field is
        // `None` indirectly via the `Debug` output.
        assert!(format!("{p:?}").contains("protected: false"));
    }

    /// Smoke-test: `Protected::from_trusted` + `Deref` compiles for a scalar `T`.
    #[test]
    fn protected_from_trusted_compile_check() {
        let p = unsafe {
            Protected::<'static, i32>::from_trusted(crate::SEXP(core::ptr::null_mut()), 99)
        };
        assert_eq!(*p, 99);
    }
    // endregion
}
// endregion