Skip to main content

miniextendr_api/
externalptr.rs

1#![allow(rustdoc::private_intra_doc_links)]
2//! `ExternalPtr<T>` — a Box-like owned pointer that wraps R's EXTPTRSXP.
3//!
4//! This provides ownership semantics similar to `Box<T>`, with the key difference
5//! that cleanup is deferred to R's garbage collector via finalizers.
6//!
7//! # Submodules
8//!
9//! | Module | Contents |
10//! |--------|----------|
11//! | [`altrep_helpers`] | ALTREP data1/data2 slot access helpers + the `RSidecar` and `Computed` marker types |
12//! | [`sidecar`] | [`Sidecar<T>`] fields: typed values kept in the `prot` list |
13//!
14//! # Core Types
15//!
16//! - [`ExternalPtr<T>`] — owned pointer wrapping EXTPTRSXP
17//! - [`TypedExternal`] — display and diagnostic metadata for stored types
18//! - [`ExternalSlice<T>`] — helper for slice data in external pointers
19//! - [`ErasedExternalPtr`] — type-erased `ExternalPtr<()>` alias
20//! - [`IntoExternalPtr`] — conversion trait for wrapping values
21//!
22//! `PartialEq`/`PartialOrd` compare the pointee values (like `Box<T>`),
23//! borrowing both. Use `ptr_eq` when you care about pointer identity.
24//!
25//! # Protection Strategies in miniextendr
26//!
27//! miniextendr provides three complementary protection mechanisms for different scenarios:
28//!
29//! | Strategy | Module | Lifetime | Release Order | Use Case |
30//! |----------|--------|----------|---------------|----------|
31//! | **PROTECT stack** | [`gc_protect`](crate::gc_protect) | Within `.Call` | LIFO (stack) | Temporary allocations |
32//! | **VECSXP pool** | [`protect_pool`](crate::protect_pool) | Until released or the pool drops | Any order | Values a struct owns; many values; cross-call roots |
33//! | **R ownership** | [`ExternalPtr`](struct@crate::externalptr::ExternalPtr) | Until R GCs | R decides | Rust data owned by R |
34//!
35//! ## When to Use ExternalPtr
36//!
37//! **Use `ExternalPtr` (this module) when:**
38//! - You want R to own a Rust value
39//! - The Rust value should be dropped when R garbage collects the pointer
40//! - You're exposing Rust structs to R code
41//!
42//! **Use [`gc_protect`](crate::gc_protect) instead when:**
43//! - You're allocating temporary R objects during computation
44//! - Protection is short-lived (within a single `.Call`)
45//!
46//! **Use [`ProtectPool`] instead when:**
47//! - You need R objects (not Rust values) kept alive by a struct, or across `.Call`s
48//! - You need arbitrary-order release of protections
49//!
50//! ## How ExternalPtr Protection Works
51//!
52//! ```text
53//! ┌─────────────────────────────────────────────────────────────────┐
54//! │  ExternalPtr<MyStruct>::new(value)                              │
55//! │  ├── Rf_protect() during construction (temporary)               │
56//! │  ├── R_MakeExternalPtr() creates EXTPTRSXP                      │
57//! │  ├── R_RegisterCFinalizerEx() registers cleanup callback        │
58//! │  ├── pool.insert() roots it for the Rust handle's lifetime       │
59//! │  └── Rf_unprotect() after construction complete                 │
60//! │                                                                 │
61//! │  Held in Rust (even across other R allocations, e.g. in a Vec)  │
62//! │  └── stays alive — the pool's GC-traced VECSXP slot roots it     │
63//! │                                                                 │
64//! │  Return to R → R now also references the EXTPTRSXP              │
65//! │  └── Rust handle drops → pool.release(key) drops the root,      │
66//! │      but R's own reference keeps it live                        │
67//! │                                                                 │
68//! │  R GC runs (no refs left) → finalizer (release_any) frees value │
69//! └─────────────────────────────────────────────────────────────────┘
70//! ```
71//!
72//! Owning handles (`new` / `from_raw` / `Clone`) root their `EXTPTRSXP` in a
73//! process-wide [`ProtectPool`](crate::protect_pool) so they survive R
74//! allocations while held in Rust; *borrowed* views (`wrap_sexp` / `from_sexp`
75//! / `same_object`) take no root — the object is kept alive by whatever R-side
76//! reference handed it to them. The pool (O(1) any-order release) is used
77//! rather than `R_PreserveObject` because a `Vec<ExternalPtr>` releases its
78//! roots front-to-back, the O(n²) worst case for `R_ReleaseObject`'s
79//! precious-list scan — see `analysis/gc-protection-benchmarks-results.md`.
80//!
81//! When the end goal is an R `list()` of external pointers (rather than a
82//! `Vec<ExternalPtr>` you keep working with in Rust), prefer
83//! [`ExternalPtr::collect_into_r_list`](struct@ExternalPtr) — it builds each
84//! `EXTPTRSXP` straight into the protected result list, so the list roots every
85//! element and the pool is never touched at all.
86//!
87//! # Type Identification
88//!
89//! Type safety is enforced via `Any::downcast` (Rust's `TypeId`). R symbols
90//! in the `tag` and `prot` slots are retained for display and error messages
91//! but are **never authoritative** for downcast safety — the `Any` vtable is.
92//!
93//! Internally, data is stored as `Box<Box<dyn Any>>` — a thin pointer (fits
94//! in R's `R_ExternalPtrAddr`) pointing to a fat pointer (carries the `Any`
95//! vtable for runtime downcasting). The `Any` value is a [`RefCell<T>`], whose
96//! borrow flag is what generated method wrappers, field accessors and trait
97//! shims check before they make a `&T` / `&mut T` (see "Reentrant calls"
98//! below). The outer `Box` keeps the heap address stable so
99//! [`ExternalPtr::cached_ptr`](struct@ExternalPtr) can be cached once at
100//! construction.
101//!
102//! The `tag` slot holds a symbol (type name, for display).
103//! The `prot` slot holds a VECSXP (list) of `2 + T::R_SLOT_COUNT` elements:
104//!   - Index 0: SYMSXP (interned type ID symbol, for error messages)
105//!   - Index 1: User-protected SEXP slot (for preventing GC of R objects)
106//!   - Index 2..: one value per [`Sidecar<T>`] field of `T`
107//!
108//! Before reading the address as Rust storage, checked conversions and erased
109//! handle accessors require this metadata shape (including a non-ALTREP list).
110//! Trait-ABI pointers carry a reserved tag and a different allocation layout;
111//! they are rejected here. These checks reject ordinary foreign pointers, not
112//! foreign addresses deliberately forged with miniextendr metadata. Symbol
113//! names never establish the concrete Rust type; `Any::downcast` still does.
114//!
115//! ## `TYPE_NAME_CSTR` vs `TYPE_ID_CSTR`
116//!
117//! [`TypedExternal`] exposes two associated constants with distinct roles —
118//! mixing them up does not break type safety (`Any::downcast` is the real
119//! gate) but produces noisy diagnostics.
120//!
121//! | Constant | Role | Visible to R as | Authoritative? |
122//! |---|---|---|---|
123//! | `TYPE_NAME_CSTR` | Display tag | `class()` / `print()` | No |
124//! | `TYPE_ID_CSTR` | Error-message identifier on downcast failure | Stored in `prot[0]` | No (cosmetic; downcast uses `TypeId`) |
125//!
126//! `#[derive(ExternalPtr)]` fills both with sensible defaults; only override
127//! manually when implementing `TypedExternal` by hand.
128//!
129//! # Pointer provenance for `cached_ptr`
130//!
131//! `ExternalPtr` caches the address of the value's [`RefCell<T>`] at
132//! construction so [`borrow`](ExternalPtr::borrow) /
133//! [`borrow_mut`](ExternalPtr::borrow_mut) avoid an FFI call on every access.
134//! A `RefCell` hands out `&mut T` from a shared reference to the cell, so a
135//! pointer cached from `downcast_ref::<RefCell<T>>()` is as good for writes
136//! as one from `Box::into_raw`.
137//!
138//! # Reentrant calls
139//!
140//! R reaches a Rust value only through a generated wrapper, on R's main
141//! thread, and the wrapper borrows the value's [`RefCell`] for the whole call:
142//! shared for `&self` methods, `&T` arguments, [`ExternalPtrRef`] receivers
143//! and arguments, and field getters; exclusive for `&mut self` and `self`
144//! methods, `&mut T` arguments, [`ExternalPtrMut`] receivers and arguments,
145//! and field setters. The body gets plain references, which Rust's borrow
146//! checker covers from there. A second borrow during the call, from the same
147//! object passed twice with a `&mut T`, or from R code the body calls back
148//! into (an R function argument, `RCall`) reaching the object again, raises
149//! an R error of class `miniextendr_borrow_conflict` instead of making a
150//! second reference. A borrow taken through a trait view lives in the
151//! producer's shim, so views in other packages see it too.
152//!
153//! An `ExternalPtr<T>` handle, as an argument, a `self: ExternalPtr<Self>`
154//! receiver, a `Vec` element or a value Rust keeps, takes no borrow until it
155//! is read: [`borrow`](ExternalPtr::borrow) and
156//! [`borrow_mut`](ExternalPtr::borrow_mut) check the `RefCell` and raise the
157//! same error. A handle has no `Deref`, so every read through it is one of
158//! these. `into_inner` and the other consuming functions refuse a value
159//! something still borrows, with the same error.
160//!
161//! The borrow is released when the wrapper returns, panics, or unwinds an R
162//! error raised through [`RCall::eval_with_handlers`](crate::expression::RCall::eval_with_handlers)
163//! (or any API that turns an R error into a Rust unwind). A bare `Rf_eval`
164//! that raises an R error jumps over the wrapper's frames, so the object
165//! stays borrowed for the rest of the session.
166//!
167//! # See also
168//!
169//! - [`crate::altrep`] — when the alternative (an ALTREP class) makes more
170//!   sense than `ExternalPtr`.
171//!
172//! # ExternalPtr is Not an R Native Type
173//!
174//! Unlike R's native atomic types (`integer`, `double`, `character`, etc.),
175//! external pointers cannot be coerced to vectors or used in R's vectorized
176//! operations. This is an R limitation, not a miniextendr limitation:
177//!
178//! ```r
179//! > matrix(new("externalptr"), 1, 1)
180//! Error in `as.vector()`:
181//! ! cannot coerce type 'externalptr' to vector of type 'any'
182//! ```
183//!
184//! If you need your Rust type to participate in R's vector/matrix operations,
185//! consider implementing [`IntoList`](crate::list::IntoList) (via `#[derive(IntoList)]`)
186//! to convert your struct to a named R list, or use ALTREP to expose Rust
187//! iterators as lazy R vectors.
188
189use std::any::Any;
190use std::any::TypeId;
191use std::cell::{Ref, RefCell, RefMut};
192use std::fmt;
193use std::hash::{Hash, Hasher};
194use std::marker::PhantomData;
195use std::mem::{self, ManuallyDrop, MaybeUninit};
196use std::ptr::{self, NonNull};
197
198use crate::RValue;
199use crate::condition::{ConditionCall, RCondition};
200use crate::gc_protect::ProtectScope;
201use crate::protect_pool::{ProtectKey, ProtectPool};
202use crate::sys::{
203    R_ClearExternalPtr, R_ExternalPtrAddr, R_ExternalPtrProtected, R_ExternalPtrTag,
204    R_MakeExternalPtr, R_MakeExternalPtr_unchecked, R_RegisterCFinalizerEx,
205    R_RegisterCFinalizerEx_unchecked, R_SetExternalPtrAddr, R_SetExternalPtrAddr_unchecked,
206    R_SetExternalPtrProtected, R_SetExternalPtrTag, Rf_allocVector, Rf_allocVector_unchecked,
207    Rf_install, Rf_install_unchecked,
208};
209use crate::{R_xlen_t, Rboolean, SEXP, SEXPTYPE, SexpExt};
210
211/// Index of the type SYMSXP contained in the `prot` (a `VECSXP` list)
212const PROT_TYPE_ID_INDEX: isize = 0;
213/// Index of user-protected objects contained in the `prot` (a `VECSXP` list)
214const PROT_USER_INDEX: isize = 1;
215/// Length of the `prot` list (`VECSXP`) before the [`Sidecar<T>`] entries,
216/// which start at this index
217const PROT_VEC_LEN: isize = 2;
218
219/// Length of `T`'s `prot` list: the type ID, the user slot, one entry per
220/// [`Sidecar<T>`] field, and for a serde type the carrier of its saved value
221/// (#2186).
222#[inline]
223fn prot_vec_len<T: TypedExternal>() -> R_xlen_t {
224    let r_slots = R_xlen_t::try_from(T::R_SLOT_COUNT).expect("sidecar count exceeds R_xlen_t::MAX");
225    PROT_VEC_LEN + r_slots + R_xlen_t::from(snapshot::has_carrier_slot::<T>())
226}
227
228#[inline]
229fn is_type_erased<T: 'static>() -> bool {
230    TypeId::of::<T>() == TypeId::of::<()>()
231}
232
233/// Get the interned R symbol for a type's name.
234///
235/// R interns symbols via `Rf_install`, so the same string always returns the
236/// same pointer. The symbol is stable display metadata; `Any::downcast` is the
237/// authoritative type check.
238///
239/// # Safety
240///
241/// Must be called from R's main thread.
242#[inline]
243unsafe fn type_symbol<T: TypedExternal>() -> SEXP {
244    unsafe { Rf_install(T::TYPE_NAME_CSTR.as_ptr().cast()) }
245}
246
247/// Unchecked version of [`type_symbol`] - no thread safety checks.
248///
249/// # Safety
250///
251/// Must be called from R's main thread. No debug assertions.
252#[inline]
253unsafe fn type_symbol_unchecked<T: TypedExternal>() -> SEXP {
254    unsafe { Rf_install_unchecked(T::TYPE_NAME_CSTR.as_ptr().cast()) }
255}
256
257/// Get the namespaced type ID symbol used in diagnostics.
258///
259/// Uses `TYPE_ID_CSTR`, which includes the module path to make mismatch
260/// messages unambiguous.
261///
262/// # Safety
263///
264/// Must be called from R's main thread.
265#[inline]
266unsafe fn type_id_symbol<T: TypedExternal>() -> SEXP {
267    unsafe { Rf_install(T::TYPE_ID_CSTR.as_ptr().cast()) }
268}
269
270/// Unchecked version of [`type_id_symbol`].
271///
272/// # Safety
273///
274/// Must be called from R's main thread. No debug assertions.
275#[inline]
276unsafe fn type_id_symbol_unchecked<T: TypedExternal>() -> SEXP {
277    unsafe { Rf_install_unchecked(T::TYPE_ID_CSTR.as_ptr().cast()) }
278}
279
280/// Get the type name from a stored symbol SEXP.
281///
282/// # Safety
283///
284/// `sym` must be a valid SYMSXP.
285#[inline]
286fn symbol_name(sym: SEXP) -> &'static str {
287    use crate::SexpExt;
288    let printname = sym.printname();
289    let cstr = printname.r_char();
290    let len = printname.len();
291    unsafe {
292        std::str::from_utf8(std::slice::from_raw_parts(cstr.cast(), len))
293            .expect("R SYMSXP PRINTNAME is not valid UTF-8")
294    }
295}
296
297/// The type-ID symbol an `ExternalPtr`-built pointer keeps in `prot[0]`, or
298/// `None` when its metadata is not the shape ordinary `ExternalPtr` builds.
299/// This also excludes trait-ABI storage, which has a different Rust layout.
300///
301/// Only inspect non-ALTREP metadata: checking ownership must not invoke a
302/// foreign callback. A foreign address forged with this metadata is outside
303/// the trust boundary; after this check `Any` still decides the concrete type.
304///
305/// # Safety
306///
307/// Must be called from R's main thread with a valid `EXTPTRSXP`.
308#[inline]
309unsafe fn stored_type_id_symbol(sexp: SEXP) -> Option<SEXP> {
310    let tag = unsafe { R_ExternalPtrTag(sexp) };
311    // Symbols are interned, so the trait-ABI tag compares by pointer.
312    if tag.type_of() != SEXPTYPE::SYMSXP || tag == unsafe { crate::mx_abi::get_tag() } {
313        return None;
314    }
315    let prot = unsafe { R_ExternalPtrProtected(sexp) };
316    if prot.type_of() != SEXPTYPE::VECSXP || prot.is_altrep() || prot.xlength() < PROT_VEC_LEN {
317        return None;
318    }
319    let sym = prot.vector_elt(PROT_TYPE_ID_INDEX);
320    (sym.type_of() == SEXPTYPE::SYMSXP).then_some(sym)
321}
322
323/// `T`'s type ID as text (`TYPE_ID_CSTR` without its NUL).
324fn type_id_str<T: TypedExternal>() -> &'static str {
325    let id = T::TYPE_ID_CSTR
326        .strip_suffix(b"\0")
327        .unwrap_or(T::TYPE_ID_CSTR);
328    std::str::from_utf8(id).expect("TYPE_ID_CSTR is not valid UTF-8")
329}
330
331/// Splits a type ID of the derive's form, `crate@version::module::Type`,
332/// into `(crate, version, module::Type)`; a hand-written ID without a
333/// version is `(None, None, id)`.
334fn split_type_id(id: &str) -> (Option<&str>, Option<&str>, &str) {
335    let Some((crate_name, rest)) = id.split_once('@') else {
336        return (None, None, id);
337    };
338    match rest.split_once("::") {
339        Some((version, path)) => (Some(crate_name), Some(version), path),
340        None => (None, None, id),
341    }
342}
343
344/// What a save of a type is matched by (#2186): the type ID's crate,
345/// version and type name, without the module path, so a type moved to
346/// another module of its crate still owns its saves. `None` for a
347/// hand-written ID without a version.
348fn saved_identity(id: &str) -> Option<(&str, &str, &str)> {
349    let (Some(crate_name), Some(version), path) = split_type_id(id) else {
350        return None;
351    };
352    let name = path.rsplit_once("::").map_or(path, |(_, name)| name);
353    Some((crate_name, version, name))
354}
355
356// region: A pointer without an address
357
358/// The condition class every error about a pointer restored from a saved
359/// session carries, after its specific class.
360pub const RESTORED_CLASS: &str = "miniextendr_restored";
361
362/// The class of the error for a pointer this version of the crate saved: it
363/// came back from `readRDS()` / `unserialize()` without its Rust value.
364pub const RESTORED_NO_VALUE_CLASS: &str = "miniextendr_restored_no_value";
365
366/// The class of the error for a pointer another version of the crate saved;
367/// the condition carries `saved_version` and `current_version`.
368pub const RESTORED_OTHER_VERSION_CLASS: &str = "miniextendr_restored_other_version";
369
370/// The class of the error for reading a `Sidecar` field of a restored
371/// pointer whose save has no slot for it: a field added after the version
372/// that saved the object (#2187). The condition carries `field`, the field's
373/// name.
374pub const RESTORED_MISSING_SLOT_CLASS: &str = "miniextendr_restored_missing_slot";
375
376/// The class of the error for a receiver of a type's R accessors that carries
377/// no external pointer: neither a pointer nor an object holding one in
378/// `.ptr`, such as an object of the class an earlier release of a package
379/// wrote to disk (#1901). The type's restored and field-error classes go in
380/// front of it.
381pub const NO_HANDLE_CLASS: &str = "miniextendr_no_handle";
382
383/// What a pointer without an address is, as far as `T` is concerned
384/// ([`classify_null_address`]).
385#[derive(#[automatically_derived]impl ::core::fmt::Debug for NullAddress {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        match self {
            Self::Foreign => ::core::fmt::Formatter::write_str(f, "Foreign"),
            Self::Restored =>
                ::core::fmt::Formatter::write_str(f, "Restored"),
            Self::OtherVersion {
                crate_name: __self_0, saved: __self_1, current: __self_2 } =>
                ::core::fmt::Formatter::debug_struct_field3_finish(f,
                    "OtherVersion crate_name saved current", __self_0, __self_1,
                    &__self_2),
            Self::OtherType { found: __self_0 } =>
                ::core::fmt::Formatter::debug_struct_field1_finish(f,
                    "OtherType found", &__self_0),
        }
    }
}Debug, #[automatically_derived]#[doc(hidden)]unsafe impl ::core::clone::TrivialClone
    for NullAddress {
}
#[automatically_derived]impl ::core::clone::Clone for NullAddress {
    #[inline]
    fn clone(&self) -> Self {
        let _: ::core::clone::AssertParamIsClone<&'static str>;
        let _: ::core::clone::AssertParamIsClone<&'static str>;
        let _: ::core::clone::AssertParamIsClone<&'static str>;
        let _: ::core::clone::AssertParamIsClone<&'static str>;
        *self
    }
}Clone, #[automatically_derived]impl ::core::marker::Copy for NullAddress { }Copy, #[automatically_derived]impl ::core::marker::StructuralPartialEq for
    NullAddress {
}
#[automatically_derived]impl ::core::cmp::PartialEq for NullAddress {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        ::core::intrinsics::discriminant_value(self) ==
                ::core::intrinsics::discriminant_value(other) &&
            match (self, other) {
                (Self::OtherVersion {
                    crate_name: __self_0, saved: __self_1, current: __self_2 },
                    Self::OtherVersion {
                    crate_name: __arg1_0, saved: __arg1_1, current: __arg1_2 })
                    =>
                    __self_0 == __arg1_0 && __self_1 == __arg1_1 &&
                        __self_2 == __arg1_2,
                (Self::OtherType { found: __self_0 }, Self::OtherType {
                    found: __arg1_0 }) => __self_0 == __arg1_0,
                _ => true,
            }
    }
}PartialEq, #[automatically_derived]impl ::core::cmp::Eq for NullAddress {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {
        let _: ::core::cmp::AssertParamIsEq<&'static str>;
        let _: ::core::cmp::AssertParamIsEq<&'static str>;
        let _: ::core::cmp::AssertParamIsEq<&'static str>;
        let _: ::core::cmp::AssertParamIsEq<&'static str>;
    }
}Eq)]
386pub(crate) enum NullAddress {
387    /// Not built by `ExternalPtr`: R's `new("externalptr")`, a pointer
388    /// `into_inner` cleared, another library's pointer.
389    Foreign,
390    /// Built for `T` by this version of its crate, in whatever module `T`
391    /// was then: restored from a saved session, so the Rust value is gone.
392    Restored,
393    /// Built for `T` by another version of its crate, in any module.
394    OtherVersion {
395        /// The crate's name.
396        crate_name: &'static str,
397        /// The version that saved the pointer.
398        saved: &'static str,
399        /// This version.
400        current: &'static str,
401    },
402    /// Built for another type.
403    OtherType {
404        /// The stored type ID.
405        found: &'static str,
406    },
407}
408
409/// Reads `prot[0]` of a pointer without an address and says what it is for
410/// `T`. A save is `T`'s when its crate and type name are `T`'s
411/// ([`saved_identity`]): the module path is left out, so moving a type to
412/// another module keeps its saves (#2186). A pointer with a live address is
413/// never classified: `Any::downcast` decides its type. Symbol names live for
414/// the session, so the borrowed parts are `'static`.
415///
416/// # Safety
417///
418/// Must be called from R's main thread with a valid `EXTPTRSXP`.
419pub(crate) unsafe fn classify_null_address<T: TypedExternal>(sexp: SEXP) -> NullAddress {
420    let Some(sym) = (unsafe { stored_type_id_symbol(sexp) }) else {
421        return NullAddress::Foreign;
422    };
423    let found = symbol_name(sym);
424    let own = type_id_str::<T>();
425    if found == own {
426        return NullAddress::Restored;
427    }
428    match (saved_identity(found), saved_identity(own)) {
429        (Some((crate_name, saved, name)), Some((own_crate, current, own_name)))
430            if crate_name == own_crate && name == own_name =>
431        {
432            if saved == current {
433                NullAddress::Restored
434            } else {
435                NullAddress::OtherVersion {
436                    crate_name,
437                    saved,
438                    current,
439                }
440            }
441        }
442        _ => NullAddress::OtherType { found },
443    }
444}
445
446/// The first R class of `receiver`, which is what the user sees and the
447/// field methods dispatched on (#1920); `None` for an object without a class
448/// attribute, such as an R6 object's `.ptr`, whose messages name the Rust
449/// type instead.
450pub(crate) fn receiver_class(receiver: SEXP) -> Option<String> {
451    let class = receiver.get_class();
452    (class.type_of() == SEXPTYPE::STRSXP && class.len() > 0)
453        // SAFETY: an element of a live class attribute. Read lossily: the
454        // name only goes into a message.
455        .then(|| unsafe { crate::from_r::charsxp_to_string_lossy(class.string_elt(0)) })
456        .flatten()
457}
458
459/// The message of the [`RESTORED_NO_VALUE_CLASS`] error.
460pub(crate) fn restored_no_value_message(type_name: &str) -> String {
461    ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("this `{0}` object was restored from a saved session and has no Rust value; re-create it",
                type_name))
    })format!(
462        "this `{type_name}` object was restored from a saved session and has no Rust value; \
463         re-create it"
464    )
465}
466
467/// The message of the [`RESTORED_OTHER_VERSION_CLASS`] error.
468pub(crate) fn restored_other_version_message(
469    type_name: &str,
470    crate_name: &str,
471    saved: &str,
472    current: &str,
473) -> String {
474    ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("this `{0}` object was saved by {1} {2} and can\'t be read by {1} {3}; re-create it",
                type_name, crate_name, saved, current))
    })format!(
475        "this `{type_name}` object was saved by {crate_name} {saved} and can't be read by \
476         {crate_name} {current}; re-create it"
477    )
478}
479
480/// The condition classes of a restored refusal of a `T`: the package's
481/// classes ([`TypedExternal::RESTORED_ERROR_CLASS`], in order), then the
482/// specific class, then [`RESTORED_CLASS`].
483pub(crate) fn restored_classes_of<T: TypedExternal>(specific: &'static str) -> Vec<String> {
484    T::RESTORED_ERROR_CLASS
485        .iter()
486        .copied()
487        .chain([specific, RESTORED_CLASS])
488        .map(str::to_owned)
489        .collect()
490}
491
492/// The message of a restored refusal of a `T`: the package's
493/// ([`TypedExternal::RESTORED_ERROR_MESSAGE`]) when it has one, else
494/// miniextendr's (`default`).
495pub(crate) fn restored_message_of<T: TypedExternal>(default: impl FnOnce() -> String) -> String {
496    T::RESTORED_ERROR_MESSAGE.map_or_else(default, str::to_owned)
497}
498
499/// Raises the error for a pointer without an address when it was built for
500/// `T` (by this version: [`RESTORED_NO_VALUE_CLASS`]; by another:
501/// [`RESTORED_OTHER_VERSION_CLASS`]), with the package's classes in front and
502/// its message when the type declares them (`#[externalptr(restored(...))]`),
503/// and returns the other cases for the caller to word as it did before. The
504/// default message names `receiver`'s R class, the object the user called
505/// on (the pointer itself, or the list, environment or S4 object carrying
506/// it), else the Rust type. The condition is raised through the panic
507/// transport (`panic_any`), like `error!`.
508///
509/// # Safety
510///
511/// Must be called from R's main thread with a valid `EXTPTRSXP` whose
512/// address is NULL.
513#[cold]
514pub(crate) unsafe fn refuse_restored<T: TypedExternal>(sexp: SEXP, receiver: SEXP) -> NullAddress {
515    let kind = unsafe { classify_null_address::<T>(sexp) };
516    let name = || receiver_class(receiver).unwrap_or_else(|| T::TYPE_NAME.to_owned());
517    // A serde type's save that could not be decoded (#2186), by any version:
518    // the no-value refusal, with the decoding error as `e$parent`.
519    if #[allow(non_exhaustive_omitted_patterns)] match kind {
    NullAddress::Restored | NullAddress::OtherVersion { .. } => true,
    _ => false,
}matches!(
520        kind,
521        NullAddress::Restored | NullAddress::OtherVersion { .. }
522    ) && let Some(cause) = unsafe { snapshot::decode_failure::<T>(sexp) }
523    {
524        std::panic::panic_any(
525            RCondition::Error {
526                message: decode_failed_message::<T>(&name(), cause.message()),
527                class: restored_classes_of::<T>(RESTORED_NO_VALUE_CLASS),
528                data: None,
529                call: ConditionCall::Inherit,
530            }
531            .with_parent(cause),
532        )
533    }
534    let (message, class, data) = match kind {
535        NullAddress::Restored => (
536            restored_message_of::<T>(|| restored_no_value_message(&name())),
537            RESTORED_NO_VALUE_CLASS,
538            None,
539        ),
540        NullAddress::OtherVersion {
541            crate_name,
542            saved,
543            current,
544        } => (
545            restored_message_of::<T>(|| {
546                restored_other_version_message(&name(), crate_name, saved, current)
547            }),
548            RESTORED_OTHER_VERSION_CLASS,
549            Some(::alloc::boxed::box_assume_init_into_vec_unsafe(::alloc::intrinsics::write_box_via_move(::alloc::boxed::Box::new_uninit(),
        [(String::from("saved_version"), RValue::from(saved)),
                (String::from("current_version"), RValue::from(current))]))vec![
550                (String::from("saved_version"), RValue::from(saved)),
551                (String::from("current_version"), RValue::from(current)),
552            ]),
553        ),
554        NullAddress::Foreign | NullAddress::OtherType { .. } => return kind,
555    };
556    std::panic::panic_any(RCondition::Error {
557        message,
558        class: restored_classes_of::<T>(class),
559        data,
560        call: ConditionCall::Inherit,
561    })
562}
563
564/// The message of a save that could not be decoded (#2186): the package's
565/// restored message, else miniextendr's, then the cause's.
566fn decode_failed_message<T: TypedExternal>(type_name: &str, cause: &str) -> String {
567    match T::RESTORED_ERROR_MESSAGE {
568        Some(message) => ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("{0} (its saved value could not be read: {1})",
                message, cause))
    })format!("{message} (its saved value could not be read: {cause})"),
569        None => ::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("this `{0}` object was restored from a saved session, but its saved value could not be read: {1}; re-create it",
                type_name, cause))
    })format!(
570            "this `{type_name}` object was restored from a saved session, but its saved value \
571             could not be read: {cause}; re-create it"
572        ),
573    }
574}
575
576/// Empties the pointer a value was moved out of (`into_raw` / `into_inner`):
577/// the address, so the finalizer is a no-op, and the tag and protection list
578/// too, so the pointer reads as empty (the plain `null external pointer`
579/// messages) rather than as one restored from a saved session, which keeps
580/// its `prot` (#1872). `R_ClearExternalPtr` only nulls the address.
581///
582/// # Safety
583///
584/// Must be called from R's main thread with a valid `EXTPTRSXP`.
585unsafe fn clear_moved_out(sexp: SEXP) {
586    unsafe { R_ClearExternalPtr(sexp) };
587    unsafe { R_SetExternalPtrTag(sexp, SEXP::nil()) };
588    unsafe { R_SetExternalPtrProtected(sexp, SEXP::nil()) };
589}
590
591/// Test support: make a restored pointer read as a save by another version of
592/// its crate, so a package can test its handling of
593/// `miniextendr_restored_other_version` (#1872) without building two
594/// versions.
595///
596/// It rewrites the version in the type ID a restored pointer keeps in
597/// `prot[0]` (`crate@version::module::Type`) to `version`. The pointer must
598/// have no address, as one restored by `readRDS()` / `unserialize()` has: a
599/// live pointer is checked by `Any::downcast`, not by the ID. Call it from a
600/// test-only `#[miniextendr]` function:
601///
602/// ```ignore
603/// /// @param x A pointer restored by `unserialize()`.
604/// #[miniextendr(noexport)]
605/// pub fn rewrite_saved_version(x: SEXP, version: String) {
606///     // SAFETY: R's main thread; `x` is an external pointer.
607///     unsafe { miniextendr_api::externalptr::rewrite_stored_version_for_tests(x, &version) };
608/// }
609/// ```
610///
611/// ```r
612/// back <- unserialize(serialize(obj, NULL))
613/// rewrite_saved_version(back, "0.0.1")
614/// tryCatch(method(back), miniextendr_restored_other_version = function(e) e$saved_version)
615/// #> [1] "0.0.1"
616/// ```
617///
618/// # Panics
619///
620/// When `sexp` is not a restored `ExternalPtr`-built pointer with a
621/// versioned type ID.
622///
623/// # Safety
624///
625/// Must be called from R's main thread with a valid `EXTPTRSXP`.
626pub unsafe fn rewrite_stored_version_for_tests(sexp: SEXP, version: &str) {
627    if !unsafe { R_ExternalPtrAddr(sexp) }.is_null() {
    {
        ::core::panicking::panic_fmt(format_args!("the pointer still has its Rust value: save and restore it first"));
    }
};assert!(
628        unsafe { R_ExternalPtrAddr(sexp) }.is_null(),
629        "the pointer still has its Rust value: save and restore it first"
630    );
631    let sym = unsafe { stored_type_id_symbol(sexp) }.expect("an `ExternalPtr`-built pointer");
632    let (crate_name, path) = match split_type_id(symbol_name(sym)) {
633        (Some(crate_name), Some(_), path) => (crate_name, path),
634        _ => {
    ::core::panicking::panic_fmt(format_args!("the stored type ID has no version"));
}panic!("the stored type ID has no version"),
635    };
636    let rewritten = std::ffi::CString::new(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("{0}@{1}::{2}", crate_name, version,
                path))
    })format!("{crate_name}@{version}::{path}"))
637        .expect("a type ID has no NUL");
638    // `Rf_install` interns the symbol for the session; the list keeps it.
639    let prot = unsafe { R_ExternalPtrProtected(sexp) };
640    prot.set_vector_elt(PROT_TYPE_ID_INDEX, unsafe {
641        Rf_install(rewritten.as_ptr())
642    });
643}
644
645/// Test support: make a pointer read as built by `crate_name` for the type
646/// at `path` (`module::Type`), keeping the version in its type ID, so a
647/// package can test what a save of a type moved to another module, renamed,
648/// or of another crate gives after `unserialize()` (#2186).
649///
650/// It rewrites the type ID in `prot[0]` to `crate_name@version::path`. A
651/// live pointer keeps working, since `Any::downcast` checks its type, and its
652/// next save writes the rewritten ID, as the type's earlier location would
653/// have:
654///
655/// ```ignore
656/// /// @param x An external pointer.
657/// #[miniextendr(noexport)]
658/// pub fn rewrite_saved_type(x: SEXP, crate_name: String, path: String) {
659///     // SAFETY: R's main thread; `x` is an external pointer.
660///     unsafe { miniextendr_api::externalptr::rewrite_stored_type_for_tests(x, &crate_name, &path) };
661/// }
662/// ```
663///
664/// ```r
665/// rewrite_saved_type(obj, "mypkg", "mypkg::old_module::Model")
666/// back <- unserialize(serialize(obj, NULL))  # comes back as a `Model`
667/// ```
668///
669/// # Panics
670///
671/// When `sexp` is not an `ExternalPtr`-built pointer with a versioned type
672/// ID.
673///
674/// # Safety
675///
676/// Must be called from R's main thread with a valid `EXTPTRSXP`.
677pub unsafe fn rewrite_stored_type_for_tests(sexp: SEXP, crate_name: &str, path: &str) {
678    let sym = unsafe { stored_type_id_symbol(sexp) }.expect("an `ExternalPtr`-built pointer");
679    let (_, Some(version), _) = split_type_id(symbol_name(sym)) else {
680        {
    ::core::panicking::panic_fmt(format_args!("the stored type ID has no version"));
}panic!("the stored type ID has no version")
681    };
682    let rewritten = std::ffi::CString::new(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("{0}@{1}::{2}", crate_name, version,
                path))
    })format!("{crate_name}@{version}::{path}"))
683        .expect("a type ID has no NUL");
684    // `Rf_install` interns the symbol for the session; the list keeps it.
685    let prot = unsafe { R_ExternalPtrProtected(sexp) };
686    prot.set_vector_elt(PROT_TYPE_ID_INDEX, unsafe {
687        Rf_install(rewritten.as_ptr())
688    });
689}
690
691// endregion
692
693// region: TypedExternalPtr Trait
694
695/// Trait for types that can be stored in an ExternalPtr.
696///
697/// This provides R-visible display and diagnostic identifiers. Runtime type
698/// checking is performed by `Any::downcast` (Rust's `TypeId`), not by comparing
699/// these symbols.
700///
701/// # Type ID vs Type Name
702///
703/// - `TYPE_ID_CSTR`: Namespaced identifier used in mismatch diagnostics (stored in `prot[0]`).
704///   Format: `"<crate_name>@<crate_version>::<module_path>::<type_name>\0"`
705///
706///   The crate name, version, and module path distinguish otherwise similar
707///   names in error messages. They do not determine compatibility.
708///
709/// - `TYPE_NAME_CSTR`: Short display name for the R tag (shown when printing).
710///   Just the type identifier for readability.
711#[diagnostic::on_unimplemented(
712    message = "`{Self}` is not a type an `ExternalPtr` stores",
713    label = "`{Self}` does not implement `TypedExternal`",
714    note = "`#[derive(ExternalPtr)]` (or `impl_typed_external!`) implements it; R reaches a `{Self}` through an external pointer, as the object of a `#[miniextendr]` impl or a `&{Self}` / `&mut {Self}` parameter",
715    note = "a parameter whose `&{Self}` converts through its own `TryFromSexp` impl, or whose type is an alias (`type Text = str`), takes `#[miniextendr(convert)]` (`#[miniextendr(convert(param))]` on an impl method)"
716)]
717pub trait TypedExternal: 'static {
718    /// The type name as a static string (for debugging and display)
719    const TYPE_NAME: &'static str;
720
721    /// The type name as a null-terminated C string (for R tag display)
722    const TYPE_NAME_CSTR: &'static [u8];
723
724    /// Namespaced type ID as a null-terminated C string (for diagnostics).
725    ///
726    /// This should include the module path to prevent ambiguous messages.
727    /// Use `concat!(module_path!(), "::", stringify!(Type), "\0").as_bytes()`
728    /// when implementing manually, or use `#[derive(ExternalPtr)]`.
729    const TYPE_ID_CSTR: &'static [u8];
730
731    /// Number of [`Sidecar<T>`] fields: values the external pointer's
732    /// protection list keeps after the type ID and the user slot.
733    ///
734    /// `#[derive(ExternalPtr)]` counts the type's `#[r_data]` fields of type
735    /// `Sidecar<_>`.
736    const R_SLOT_COUNT: usize = 0;
737
738    /// Number of `#[r_data(cache)]` fields: struct fields whose R getter
739    /// keeps the R value its first read makes until the value is next
740    /// borrowed exclusively (#2271).
741    ///
742    /// `#[derive(ExternalPtr)]` counts them. Every exclusive borrow of a
743    /// value whose type has any drops the value's cached field values, and
744    /// its pointer's finalizer drops them too; a type with none pays one
745    /// constant branch per exclusive borrow.
746    const CACHED_FIELD_COUNT: usize = 0;
747
748    /// The R names of the `Sidecar` fields (`#[r_data(name = "..")]`, else
749    /// the Rust field name), in slot order: the names the protection list
750    /// carries, so a save is read back by field name (#2187, #2215).
751    #[doc(hidden)]
752    const SIDECAR_NAMES: &'static [&'static str] = &[];
753
754    /// The package's condition classes for a pointer of this type restored
755    /// from a saved session, in front of the `miniextendr_restored*` classes
756    /// ([`RESTORED_NO_VALUE_CLASS`] / [`RESTORED_OTHER_VERSION_CLASS`], then
757    /// [`RESTORED_CLASS`]), which every restored refusal keeps.
758    ///
759    /// `#[derive(ExternalPtr)]` fills it from
760    /// `#[externalptr(restored(class = "pkg_saved"))]` or
761    /// `restored(class = ["pkg_saved", "pkg_error"])`; the default adds
762    /// nothing.
763    const RESTORED_ERROR_CLASS: &'static [&'static str] = &[];
764
765    /// The package's message for a pointer of this type restored from a saved
766    /// session, replacing miniextendr's in both the no-value and the
767    /// other-version case (the condition's `saved_version` /
768    /// `current_version` fields stay), and for a list or environment of the
769    /// class that carries no pointer (a save in an older format). A static
770    /// string: one type is one R class, so the package names it literally.
771    ///
772    /// `#[derive(ExternalPtr)]` fills it from
773    /// `#[externalptr(restored(message = "..."))]`; the default keeps
774    /// miniextendr's messages.
775    const RESTORED_ERROR_MESSAGE: Option<&'static str> = None;
776
777    /// The package's message for a list or an environment of the type's
778    /// class that carries no pointer (#2218), the shape an earlier release
779    /// may have saved: it says why the object has none. It replaces
780    /// [`Self::RESTORED_ERROR_MESSAGE`] for that receiver, which otherwise
781    /// serves both. The R accessors raise it with
782    /// [`NO_HANDLE_CLASS`]; a package's own code that refuses such an object
783    /// reads it here to word the refusal the same way.
784    ///
785    /// `#[derive(ExternalPtr)]` fills it from
786    /// `#[externalptr(restored(no_handle = "..."))]`.
787    const NO_HANDLE_MESSAGE: Option<&'static str> = None;
788
789    /// The package's condition classes for the errors the type's R field
790    /// readers raise themselves (#1899), in front of their own class: a
791    /// refused position (`subscriptOutOfBoundsError`), a name that is not a
792    /// field (`miniextendr_no_field`), a computed field assigned to
793    /// (`miniextendr_read_only_field`), a pointer of another type, and a
794    /// receiver that carries no pointer ([`NO_HANDLE_CLASS`]). The R
795    /// accessors of the type read it for the last two; the derive writes the
796    /// same classes into the R helpers for the others.
797    ///
798    /// `#[derive(ExternalPtr)]` fills it from
799    /// `#[externalptr(field_error(class = ["pkg_error_config", "pkg_error"]))]`;
800    /// the default adds nothing.
801    const FIELD_ERROR_CLASS: &'static [&'static str] = &[];
802
803    /// The package's message for the R accessors' refusal of a receiver
804    /// whose pointer is not a `T` or that carries no pointer (#1920),
805    /// replacing miniextendr's, which names the receiver's R class.
806    ///
807    /// `#[derive(ExternalPtr)]` fills it from
808    /// `#[externalptr(field_error(message = "..."))]`.
809    const FIELD_ERROR_MESSAGE: Option<&'static str> = None;
810
811    /// Visits every [`Sidecar<T>`] field of `self` with its slot index and
812    /// name, so the handle can flush the field's pending value into its slot
813    /// or load the slot back into the field.
814    ///
815    /// `#[derive(ExternalPtr)]` emits the body for a type with `Sidecar`
816    /// fields; the default visits nothing, so other types pay nothing.
817    #[doc(hidden)]
818    #[inline]
819    fn __mx_visit_sidecars(&self, _visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField)) {}
820
821    /// How a value of this type goes into a save and comes back after
822    /// `readRDS()` (#2186): `Some` for a type that is `Serialize +
823    /// DeserializeOwned` with miniextendr-api's `serde` feature.
824    /// `#[derive(ExternalPtr)]` emits the probe that decides it, in the
825    /// type's own impl; the default (`impl_typed_external!`, the standard
826    /// library types', a hand-written impl) is `None`, which keeps the
827    /// restored refusal.
828    #[doc(hidden)]
829    #[inline]
830    fn __mx_snapshot() -> Option<Snapshot<Self>>
831    where
832        Self: Sized,
833    {
834        None
835    }
836}
837
838/// Marker trait for types that should be converted to R as ExternalPtr.
839///
840/// When a type implements this trait (via `#[derive(ExternalPtr)]`), it gets a
841/// blanket `IntoR` implementation that wraps the value in `ExternalPtr<T>`.
842///
843/// This allows returning the type directly from `#[miniextendr]` functions:
844///
845/// ```ignore
846/// #[derive(ExternalPtr)]
847/// struct MyData { value: i32 }
848///
849/// #[miniextendr]
850/// fn create_data(v: i32) -> MyData {
851///     MyData { value: v }  // Automatically wrapped in ExternalPtr
852/// }
853/// ```
854pub trait IntoExternalPtr: TypedExternal {}
855
856impl TypedExternal for () {
857    const TYPE_NAME: &'static str = "()";
858    const TYPE_NAME_CSTR: &'static [u8] = b"()\0";
859    // Unit type is special - same ID as name since it's only used for type-erased ptrs
860    const TYPE_ID_CSTR: &'static [u8] = b"()\0";
861}
862// endregion
863
864// region: Class-handle unwrapping (audit A9)
865
866/// Look up a variable bound directly in a single environment frame (no search
867/// of enclosing frames) with [`REnv::get`](crate::expression::REnv::get).
868///
869/// Returns `None` for a non-environment, an absent binding, or `NULL` (none
870/// can hold a class handle). Promises and active bindings are evaluated once;
871/// their errors unwind to the caller's miniextendr boundary.
872///
873/// # Safety
874///
875/// R's main thread, inside a miniextendr boundary.
876unsafe fn env_binding(env: SEXP, name: &str) -> Option<SEXP> {
877    unsafe {
878        if !env.is_environment() {
879            return None;
880        }
881        crate::expression::REnv::from_sexp(env)
882            .get(name)
883            .filter(|val| !val.is_null_or_nil())
884    }
885}
886
887/// Attempt to unwrap a class-wrapped handle down to the bare `EXTPTRSXP` it
888/// carries, so [`ExternalPtr::<T>`](ExternalPtr) argument conversion accepts
889/// the ergonomic class handle (e.g. `Foo$new(...)`) in addition to the raw
890/// pointer returned by a low-level constructor (audit finding A9 —
891/// `audit/2026-07-03-api-sense-conversions-dataframe-errors.md` #5).
892///
893/// Tries, in order:
894/// - **Env / R6**: a direct `.ptr` binding on `sexp` itself — most
895///   `#[miniextendr(env)]` classes are actually a bare classed `EXTPTRSXP`
896///   (the generated constructor does `class(.val) <- "T"` directly on the
897///   pointer returned by Rust, see `env_class.rs`), which already satisfies
898///   the plain `EXTPTRSXP` check and never reaches this function, but a
899///   user-authored environment that binds `.ptr` is covered here too. Then
900///   the R6 handle chain `.__enclos_env__` -> `private` -> `.ptr` (R6
901///   objects are the *public* environment; `private` only hangs off the
902///   enclosing environment stored at `.__enclos_env__` for `portable`
903///   classes, the default — see `r6_class.rs`).
904/// - **S4**: the `ptr` slot via `methods::slot()`
905///   ([`crate::s4_helpers::s4_get_slot`]). Guarded by `isS4()`, which
906///   excludes S7 objects even though both share the `S4SXP`/`OBJSXP`
907///   `SEXPTYPE` — S7's `new_object(S7_object(), ...)` base never sets the S4
908///   bit.
909/// - **List**: a generic vector with a `.ptr` element (`x[[".ptr"]]`), the
910///   shape of a hand-built S3 object that keeps R-side state next to the
911///   handle: `structure(list(.ptr = <ptr>, log = ...), class = "Foo")`
912///   (#1469). The `.ptr` spelling matches the env / R6 / S7 convention.
913/// - **Anything else carrying a `.ptr` attribute**: S7 stores properties as
914///   plain attributes on its base object (see `s7_class.rs`), so
915///   `Rf_getAttrib(x, ".ptr")` recovers the pointer without going through
916///   S7's `@`/`prop()` dispatch machinery. A list without a `.ptr` element
917///   falls through to this check too (an S7 class over `class_list` is a
918///   `VECSXP` with its properties as attributes).
919///
920/// Both the `ExternalPtr<T>` argument conversion and, via
921/// `resolve_receiver`, every generated instance-method prelude go through
922/// this function.
923///
924/// Returns `Some(inner)` only when the unwrapped value is itself an
925/// `EXTPTRSXP` — anything else (e.g. a `.ptr`-named field that isn't a
926/// pointer) is treated as "no handle found" rather than an error. No
927/// recursion beyond one unwrap level. `Any::downcast` remains the type-safety
928/// authority: unwrapping a handle for the *wrong* `T` still fails at the
929/// caller with the existing type-mismatch error — this only loosens the
930/// accepted R-side shape, not type safety.
931///
932/// # Safety
933///
934/// - Must be called from R's main thread, inside a miniextendr boundary: an R
935///   error from a promise or active binding the lookup forces unwinds to it.
936/// - The returned SEXP is reachable from `sexp` (an env binding, S4 slot, or
937///   attribute) for as long as `sexp` itself is protected. Macro-generated
938///   `.Call()` wrappers hold every argument alive in the call's PROTECT stack
939///   for the duration of the call, so no additional protection is needed
940///   here.
941pub(crate) unsafe fn unwrap_class_handle(sexp: SEXP) -> Option<SEXP> {
942    unsafe {
943        if sexp.is_environment() {
944            if let Some(direct) = env_binding(sexp, ".ptr") {
945                if direct.type_of() == SEXPTYPE::EXTPTRSXP {
946                    return Some(direct);
947                }
948            }
949            // An active binding can return a fresh environment that is not
950            // retained by its owner. Keep it rooted across the next lookup.
951            let scope = ProtectScope::new();
952            let enclos = scope.protect_raw(env_binding(sexp, ".__enclos_env__")?);
953            let private = scope.protect_raw(env_binding(enclos, "private")?);
954            let inner = env_binding(private, ".ptr")?;
955            return (inner.type_of() == SEXPTYPE::EXTPTRSXP).then_some(inner);
956        }
957
958        if sexp.is_s4() {
959            let slot = crate::s4_helpers::s4_get_slot(sexp, "ptr").ok()?;
960            return (slot.type_of() == SEXPTYPE::EXTPTRSXP).then_some(slot);
961        }
962
963        if sexp.type_of() == SEXPTYPE::VECSXP {
964            if let Some(elt) = list_element(sexp, ".ptr") {
965                if elt.type_of() == SEXPTYPE::EXTPTRSXP {
966                    return Some(elt);
967                }
968            }
969        }
970
971        let attr = sexp.get_attr(Rf_install(c".ptr".as_ptr()));
972        (attr.type_of() == SEXPTYPE::EXTPTRSXP).then_some(attr)
973    }
974}
975
976/// The element of a generic vector bound to `name`: the first match in
977/// `names(x)`, like `x[[name]]`. `None` when `x` has no character names or
978/// no element by that name.
979///
980/// # Safety
981///
982/// Must be called from R's main thread; `sexp` must be a `VECSXP`.
983unsafe fn list_element(sexp: SEXP, name: &str) -> Option<SEXP> {
984    let names = sexp.get_names();
985    if names.type_of() != SEXPTYPE::STRSXP {
986        return None;
987    }
988    let n = names.len().min(sexp.len());
989    for i in 0..n {
990        let i = isize::try_from(i).ok()?;
991        if crate::list::text_name(names.string_elt(i)) == Some(name) {
992            return Some(sexp.vector_elt(i));
993        }
994    }
995    None
996}
997
998/// Resolve an instance-method receiver to the bare `EXTPTRSXP` it carries.
999///
1000/// Generated method preludes call this on `self_sexp` before
1001/// `ErasedExternalPtr::from_sexp` / `ExternalPtr::<T>::wrap_sexp`. A bare
1002/// pointer, the shape every generated constructor returns (classed or not),
1003/// passes through after one `TYPEOF` compare. Anything else goes through the
1004/// same class-handle unwrap as `ExternalPtr<T>` arguments: an R6 / S4 / S7
1005/// handle, an environment or a list carrying the pointer in `.ptr`, or any
1006/// object with a `.ptr` attribute. An S3 class whose object is a list with
1007/// R-side state next to the handle, `structure(list(.ptr = <ptr>, log = ...),
1008/// class = "Foo")`, therefore dispatches into `#[miniextendr(s3)] impl Foo`
1009/// methods unchanged (#1469).
1010///
1011/// Panics (the framework converts it to an R error) when no pointer can be
1012/// recovered, naming `T` and the receiver's `SEXPTYPE`. Type safety is still
1013/// decided by the `Any::downcast` that follows; this only widens the accepted
1014/// R-side shape.
1015///
1016/// Runs on R's main thread, in the generated preludes.
1017#[inline]
1018pub fn resolve_receiver<T: TypedExternal>(sexp: SEXP) -> SEXP {
1019    let ptr = if sexp.type_of() == SEXPTYPE::EXTPTRSXP {
1020        sexp
1021    } else {
1022        match unsafe { unwrap_class_handle(sexp) } {
1023            Some(inner) => inner,
1024            None => receiver_not_a_handle::<T>(sexp),
1025        }
1026    };
1027    // A serde type's pointer restored from a saved session gets its value
1028    // back here, before the receiver is borrowed (#2186). A save that could
1029    // not be decoded is refused by the receiver's prelude, which names the
1030    // decoding error.
1031    // SAFETY: on R's main thread; `ptr` is a valid EXTPTRSXP reachable from
1032    // `sexp`, which the call's frame roots.
1033    if unsafe { R_ExternalPtrAddr(ptr) }.is_null() {
1034        let _ = unsafe { snapshot::attach::<T>(ptr) };
1035    }
1036    ptr
1037}
1038
1039/// The typed handle of an instance-method receiver, for `self: ExternalPtr<Self>`
1040/// receivers: [`resolve_receiver`]
1041/// then [`ExternalPtr::wrap_sexp`], failing like the erased receivers do
1042/// ([`handle_downcast_failed`]: consumed, restored from a saved session, or a
1043/// type mismatch). Runs on R's main thread (the generated prelude).
1044#[inline]
1045pub fn wrap_receiver<T: TypedExternal>(sexp: SEXP) -> ExternalPtr<T> {
1046    let ptr = resolve_receiver::<T>(sexp);
1047    // SAFETY: `ptr` is a valid EXTPTRSXP the call's frame roots; on R's main
1048    // thread. The handle borrows it for the method's duration, like the
1049    // erased receivers.
1050    match unsafe { ExternalPtr::<T>::wrap_sexp(ptr) } {
1051        Some(handle) => handle,
1052        None => {
1053            let erased = unsafe { ErasedExternalPtr::from_sexp(ptr) };
1054            handle_downcast_failed::<T>(&erased)
1055        }
1056    }
1057}
1058
1059#[cold]
1060fn receiver_not_a_handle<T: TypedExternal>(sexp: SEXP) -> ! {
1061    {
    ::core::panicking::panic_fmt(format_args!("expected a `{0}` object (an external pointer, or an R6/S4/S7 handle, environment, or list carrying one in `.ptr`), got {1:?}",
            ExternalPtr::<T>::type_name(), sexp.type_of()));
}panic!(
1062        "expected a `{}` object (an external pointer, or an R6/S4/S7 handle, \
1063         environment, or list carrying one in `.ptr`), got {:?}",
1064        ExternalPtr::<T>::type_name(),
1065        sexp.type_of()
1066    )
1067}
1068// endregion
1069
1070// region: Receiver borrows
1071
1072/// A generated method's receiver: the `EXTPTRSXP` [`resolve_receiver`] finds
1073/// in the `.Call` argument, rooted for the call when a class handle carried
1074/// it. R code the method calls back into can drop the handle's reference, and
1075/// the finalizer would then free the value under the method's borrow. A bare
1076/// pointer is the `.Call` argument itself, which R keeps alive.
1077#[doc(hidden)]
1078pub struct ReceiverOwner {
1079    sexp: SEXP,
1080    _root: Option<PoolRoot>,
1081}
1082
1083impl ReceiverOwner {
1084    /// Resolve `sexp` like [`resolve_receiver`]. Runs on R's main thread (the
1085    /// generated prelude).
1086    #[inline]
1087    pub fn resolve<T: TypedExternal>(sexp: SEXP) -> Self {
1088        let owner = resolve_receiver::<T>(sexp);
1089        // SAFETY: on R's main thread; `owner` is reachable through `sexp`,
1090        // which the call's frame roots.
1091        let root = (owner != sexp).then(|| unsafe { PoolRoot::new(owner) });
1092        Self {
1093            sexp: owner,
1094            _root: root,
1095        }
1096    }
1097
1098    /// The resolved `EXTPTRSXP`.
1099    #[inline]
1100    pub fn get(&self) -> SEXP {
1101        self.sexp
1102    }
1103
1104    /// The resolved `EXTPTRSXP`, as the owner of an [`ExternalPtrRef`] /
1105    /// [`ExternalPtrMut`] receiver.
1106    #[inline]
1107    pub fn owner(&self) -> &SEXP {
1108        &self.sexp
1109    }
1110}
1111
1112/// Borrow a stored value shared for a generated wrapper: the R error of
1113/// class `miniextendr_borrow_conflict` while a running call holds it mutably.
1114#[doc(hidden)]
1115#[inline]
1116pub fn borrow_value<T>(cell: &RefCell<T>) -> Ref<'_, T> {
1117    cell.try_borrow().unwrap_or_else(|_| borrow_conflict::<T>())
1118}
1119
1120/// Borrow a stored value exclusively for a generated wrapper: the R error of
1121/// class `miniextendr_borrow_conflict` while a running call holds it.
1122///
1123/// The borrow may change the value, so it drops the value's cached field
1124/// values (`#[r_data(cache)]`, #2271) when `T` has any: every exclusive
1125/// borrow of an `ExternalPtr`'s value goes through here.
1126#[doc(hidden)]
1127#[inline]
1128pub fn borrow_value_mut<T: TypedExternal>(cell: &RefCell<T>) -> RefMut<'_, T> {
1129    let guard = borrow_erased_value_mut(cell);
1130    if T::CACHED_FIELD_COUNT > 0 {
1131        field_cache::forget(field_cache::cell_key(cell));
1132    }
1133    guard
1134}
1135
1136/// [`borrow_value_mut`] for a value in trait-ABI storage
1137/// (`abi::ErasedObject<T>`), whose shims are generic over `T`: no R field
1138/// getter reads that storage, so it has no cached field values to drop.
1139#[doc(hidden)]
1140#[inline]
1141pub fn borrow_erased_value_mut<T>(cell: &RefCell<T>) -> RefMut<'_, T> {
1142    cell.try_borrow_mut()
1143        .unwrap_or_else(|_| borrow_conflict::<T>())
1144}
1145
1146// The generated wrapper reaches a borrowed argument's value only through
1147// these functions, each bounded on `TypedExternal` and spanned on the
1148// parameter's type: for a `T` that isn't `TypedExternal` rustc then reports
1149// the one missing bound once, with its `on_unimplemented` message.
1150
1151/// [`ExternalPtr::borrow`] for a generated wrapper's argument.
1152#[doc(hidden)]
1153#[inline]
1154pub fn __mx_borrow<T: TypedExternal>(ptr: &ExternalPtr<T>) -> ExternalPtrRef<'_, T> {
1155    ptr.borrow()
1156}
1157
1158/// [`ExternalPtr::borrow_mut`] for a generated wrapper's argument.
1159#[doc(hidden)]
1160#[inline]
1161pub fn __mx_borrow_mut<T: TypedExternal>(ptr: &mut ExternalPtr<T>) -> ExternalPtrMut<'_, T> {
1162    ptr.borrow_mut()
1163}
1164
1165/// The `&T` a generated wrapper hands a `&T` parameter.
1166#[doc(hidden)]
1167#[inline]
1168pub fn __mx_shared<'a, T: TypedExternal>(view: &'a ExternalPtrRef<'_, T>) -> &'a T {
1169    view
1170}
1171
1172/// The `&mut T` a generated wrapper hands a `&mut T` parameter.
1173#[doc(hidden)]
1174#[inline]
1175pub fn __mx_exclusive<'a, T: TypedExternal>(view: &'a mut ExternalPtrMut<'_, T>) -> &'a mut T {
1176    view
1177}
1178
1179#[cold]
1180fn borrow_conflict<T>() -> ! {
1181    {
    let (__mx_call, __mx_class, __mx_data, __mx_message) =
        {
            let (__mx_class, __mx_data, __mx_message) =
                (crate::condition::ConditionClass::into_condition_class("miniextendr_borrow_conflict"),
                    ::std::option::Option::<crate::condition::ConditionData>::None,
                    ::alloc::__export::must_use({
                            ::alloc::fmt::format(format_args!("this `{0}` object is in use by a call that is still running",
                                    core::any::type_name::<T>()))
                        }));
            (crate::condition::ConditionCall::Inherit, __mx_class, __mx_data,
                __mx_message)
        };
    ::std::panic::panic_any(crate::condition::RCondition::Error {
            message: __mx_message,
            class: __mx_class,
            data: __mx_data,
            call: __mx_call,
        })
}crate::error!(
1182        class = "miniextendr_borrow_conflict",
1183        "this `{}` object is in use by a call that is still running",
1184        core::any::type_name::<T>()
1185    )
1186}
1187// endregion
1188
1189// region: ExternalPtr<T>
1190
1191/// An owned pointer stored in R's external pointer SEXP.
1192///
1193/// This is conceptually similar to `Box<T>`, but with the following differences:
1194/// - Memory is freed by R's GC via a registered finalizer (non-deterministic)
1195/// - The underlying SEXP is Copy, so aliasing must be manually prevented
1196/// - Type checking happens at runtime via `Any::downcast` (Rust `TypeId`)
1197///
1198/// # Thread Safety
1199///
1200/// `ExternalPtr` is `!Send` and `!Sync`: its R object, its root and its
1201/// finalizer belong to R's main thread, where every handle is made and
1202/// dropped. Move the value out ([`into_inner`](Self::into_inner)) to hand it
1203/// to another thread.
1204///
1205/// ```compile_fail
1206/// fn assert_send<T: Send>() {}
1207/// assert_send::<miniextendr_api::ExternalPtr<()>>();
1208/// ```
1209///
1210/// # Reading the value
1211///
1212/// A handle has no `Deref`: [`borrow`](Self::borrow) /
1213/// [`borrow_mut`](Self::borrow_mut) read the value, checking its `RefCell`
1214/// (see "Reentrant calls" in the [module docs](self)). A `#[miniextendr]`
1215/// function that needs only the value takes `&T` / `&mut T` instead, and the
1216/// generated wrapper borrows it for the call.
1217///
1218/// # Safety
1219///
1220/// The ExternalPtr assumes exclusive ownership of the underlying data.
1221/// Cloning the raw SEXP without proper handling will lead to double-free.
1222///
1223/// # Examples
1224///
1225/// ```no_run
1226/// use miniextendr_api::externalptr::{ExternalPtr, TypedExternal};
1227///
1228/// struct MyData { value: f64 }
1229/// impl TypedExternal for MyData {
1230///     const TYPE_NAME: &'static str = "MyData";
1231///     const TYPE_NAME_CSTR: &'static [u8] = b"MyData\0";
1232///     const TYPE_ID_CSTR: &'static [u8] = b"my_crate::MyData\0";
1233/// }
1234///
1235/// let ptr = ExternalPtr::new(MyData { value: 3.14 });
1236/// assert_eq!(ptr.borrow().value, 3.14);
1237/// ```
1238#[repr(C)]
1239pub struct ExternalPtr<T: TypedExternal> {
1240    sexp: SEXP,
1241    /// Cached address of the value's `RefCell`, set once at construction time.
1242    ///
1243    /// This avoids the `R_ExternalPtrAddr` FFI call on every `borrow()`/`borrow_mut()`.
1244    /// The pointer remains valid for the lifetime of the `ExternalPtr` because:
1245    /// - R's finalizer only runs after R garbage-collects the SEXP (which cannot
1246    ///   happen while a Rust `ExternalPtr` value exists).
1247    /// - `R_ClearExternalPtr` is only called in methods that consume or finalize
1248    ///   (`into_raw`, `into_inner`, `release_any`).
1249    cached_ptr: NonNull<RefCell<T>>,
1250    /// The [`ProtectPool`] key rooting this handle's `EXTPTRSXP`, or `None` for
1251    /// borrowed views.
1252    ///
1253    /// `Some(key)` for *owning* handles built from a fresh value (`new` /
1254    /// `new_unchecked` / `from_raw` / `Clone` / `Default`): the constructor
1255    /// roots the `EXTPTRSXP` in the main-thread pool so it stays alive for the
1256    /// whole Rust lifetime of the handle — including while it sits in a `Vec`
1257    /// across other R allocations before being handed to R (#836). `Drop` /
1258    /// `into_raw` / `into_inner` release the root via the key.
1259    ///
1260    /// `None` for *borrowed* views of an SEXP R already owns (`wrap_sexp*` /
1261    /// `from_sexp*` / `same_object`): no root is taken, so none is released. The
1262    /// aliased object is kept alive by whatever R-side reference handed it to us
1263    /// (a `.Call` argument frame, an owning sibling handle, …).
1264    root: Option<ProtectKey>,
1265    _marker: PhantomData<T>,
1266}
1267
1268// region: ExternalPtr GC roots
1269//
1270// Owning `ExternalPtr` handles keep their `EXTPTRSXP` alive for the handle's
1271// whole Rust lifetime by rooting it in a process-wide `ProtectPool` — a single
1272// GC-traced VECSXP with Rust-side slot bookkeeping. This is what makes a naive
1273// `Vec<ExternalPtr<T>>` GC-safe: every element stays rooted while later elements
1274// allocate (#836).
1275//
1276// Why a pool and not `R_PreserveObject`: the pool releases in O(1) any order,
1277// whereas `R_ReleaseObject` scans R's precious list (O(n)). A `Vec<ExternalPtr>`
1278// drops front-to-back — oldest first, i.e. the entries deepest in R's LIFO
1279// precious list — so `R_PreserveObject` rooting degrades to O(n²) on exactly
1280// this workload (60–65× slower at 10k; see
1281// analysis/gc-protection-benchmarks-results.md). The pool is the mechanism the
1282// strategy analysis prescribes for ExternalPtr (analysis/gc-protection-strategies.md).
1283//
1284// `ProtectPool` is `!Send`/`!Sync` and lives in a `thread_local!` on R's main
1285// thread. Every access happens there: roots are taken inside
1286// `create_extptr_sexp[_unchecked]` (main-thread by contract / `with_r_thread`),
1287// and released through `with_r_thread` from `Drop` / `into_raw` / `into_inner`.
1288// The pool is wrapped in `ManuallyDrop` so it is never released at thread exit —
1289// it is a session-lifetime root table, and running `R_ReleaseObject` on its
1290// backing during R's own teardown would touch a half-freed R heap.
1291
1292const EXTPTR_ROOTS:
    ::std::thread::LocalKey<RefCell<Option<ManuallyDrop<ProtectPool>>>> =
    {
        const __RUST_STD_INTERNAL_INIT:
            RefCell<Option<ManuallyDrop<ProtectPool>>> =
            { RefCell::new(None) };
        unsafe {
            ::std::thread::LocalKey::new(const {
                        if ::std::mem::needs_drop::<RefCell<Option<ManuallyDrop<ProtectPool>>>>()
                            {
                            |__rust_std_internal_init|
                                {
                                    #[thread_local]
                                    static __RUST_STD_INTERNAL_VAL:
                                        ::std::thread::local_impl::EagerStorage<RefCell<Option<ManuallyDrop<ProtectPool>>>>
                                        =
                                        ::std::thread::local_impl::EagerStorage::new(__RUST_STD_INTERNAL_INIT);
                                    __RUST_STD_INTERNAL_VAL.get()
                                }
                        } else {
                            |__rust_std_internal_init|
                                {
                                    #[thread_local]
                                    static __RUST_STD_INTERNAL_VAL:
                                        RefCell<Option<ManuallyDrop<ProtectPool>>> =
                                        __RUST_STD_INTERNAL_INIT;
                                    &__RUST_STD_INTERNAL_VAL
                                }
                        }
                    })
        }
    };thread_local! {
1293    static EXTPTR_ROOTS: RefCell<Option<ManuallyDrop<ProtectPool>>> = const { RefCell::new(None) };
1294}
1295
1296/// Root an owning handle's `EXTPTRSXP` in the main-thread pool.
1297///
1298/// Must run on R's main thread, which holds inside
1299/// `create_extptr_sexp[_unchecked]` and `TraitViewData::new`, whose trait views
1300/// root their receiver here too. `sexp` may be fresh: it stays reachable while
1301/// the first call creates the pool and while the pool grows.
1302#[inline]
1303pub(crate) fn root_owned(sexp: SEXP) -> ProtectKey {
1304    EXTPTR_ROOTS.with_borrow_mut(|slot| {
1305        let pool = slot.get_or_insert_with(|| {
1306            // SAFETY: on R's main thread (caller contract). Creating the pool
1307            // allocates before it holds `sexp`.
1308            let _sexp = unsafe { crate::OwnedProtect::new(sexp) };
1309            ManuallyDrop::new(ProtectPool::new(ProtectPool::DEFAULT_CAPACITY))
1310        });
1311        pool.insert(sexp)
1312    })
1313}
1314
1315/// Release an owning handle's pool root. Stale keys are a safe no-op.
1316///
1317/// Must run on R's main thread (callers route through `with_r_thread`, or are
1318/// `!Send` like `TraitViewData`).
1319#[inline]
1320pub(crate) fn unroot_owned(key: ProtectKey) {
1321    EXTPTR_ROOTS.with_borrow_mut(|slot| {
1322        if let Some(pool) = slot.as_mut() {
1323            pool.release(key);
1324        }
1325    });
1326}
1327
1328/// The object a [`root_owned`] key roots, `None` once the key is released.
1329/// On R's main thread.
1330#[inline]
1331pub(crate) fn pooled(key: ProtectKey) -> Option<SEXP> {
1332    EXTPTR_ROOTS.with_borrow(|slot| slot.as_ref().and_then(|pool| pool.get(key)))
1333}
1334
1335/// One R object rooted in the main-thread pool, released when dropped.
1336///
1337/// For roots that R's finalizers drop, such as the caches an ALTREP owner
1338/// keeps in data1. GC finalizes the newest objects first, while
1339/// `R_ReleaseObject` scans the precious list from its head, so precious-list
1340/// roots taken in any other order release in quadratic time. The pool
1341/// releases in O(1) whatever the order.
1342///
1343/// Raw-pointer marker: `!Send` and `!Sync`, so it is dropped on the thread
1344/// that took it.
1345pub(crate) struct PoolRoot {
1346    sexp: SEXP,
1347    key: ProtectKey,
1348    _not_send: PhantomData<*mut ()>,
1349}
1350
1351impl PoolRoot {
1352    /// Root `sexp`, which needs no protection of its own.
1353    ///
1354    /// # Safety
1355    ///
1356    /// Must run on R's main thread.
1357    pub(crate) unsafe fn new(sexp: SEXP) -> Self {
1358        Self {
1359            sexp,
1360            key: root_owned(sexp),
1361            _not_send: PhantomData,
1362        }
1363    }
1364
1365    /// The rooted object.
1366    pub(crate) fn get(&self) -> SEXP {
1367        self.sexp
1368    }
1369}
1370
1371impl Drop for PoolRoot {
1372    fn drop(&mut self) {
1373        // Releasing a slot neither allocates nor runs finalizers, so this is
1374        // sound inside a finalizer too.
1375        unroot_owned(self.key);
1376    }
1377}
1378// endregion
1379
1380impl<T: TypedExternal> ExternalPtr<T> {
1381    /// Build an *owning* handle rooted at `root`.
1382    ///
1383    /// Pairs with the [`ProtectPool`] root that [`create_extptr_sexp`] /
1384    /// [`create_extptr_sexp_unchecked`] take on the SEXP (and return as the
1385    /// key). The root is released by `Drop` / `into_raw` / `into_inner`. Only
1386    /// the four fresh-value constructors (`new` / `new_unchecked` / `from_raw` /
1387    /// `from_raw_unchecked`) build through here.
1388    ///
1389    /// [`create_extptr_sexp`]: Self::create_extptr_sexp
1390    /// [`create_extptr_sexp_unchecked`]: Self::create_extptr_sexp_unchecked
1391    #[inline]
1392    fn from_owned_parts(sexp: SEXP, cached_ptr: NonNull<RefCell<T>>, root: ProtectKey) -> Self {
1393        Self {
1394            sexp,
1395            cached_ptr,
1396            root: Some(root),
1397            _marker: PhantomData,
1398        }
1399    }
1400
1401    /// Build a *borrowed* view (`root = None`) of an SEXP R already owns.
1402    ///
1403    /// No GC root is taken and none is released — the aliased object is kept
1404    /// alive by the R-side reference that handed it to us. Used by every
1405    /// `wrap_sexp*` / `from_sexp*` / `same_object` path.
1406    #[inline]
1407    fn from_borrowed_parts(sexp: SEXP, cached_ptr: NonNull<RefCell<T>>) -> Self {
1408        Self {
1409            sexp,
1410            cached_ptr,
1411            root: None,
1412            _marker: PhantomData,
1413        }
1414    }
1415
1416    /// Root this handle's `EXTPTRSXP` for as long as the handle lives, as the
1417    /// fresh-value constructors do: for a pointer converted from a class
1418    /// handle, whose `.ptr` reference R code can drop while Rust still holds
1419    /// the pointer (a callback the call makes, or a handle Rust keeps).
1420    ///
1421    /// # Safety
1422    ///
1423    /// On R's main thread, with no root taken yet.
1424    #[inline]
1425    pub(crate) unsafe fn rooted(mut self) -> Self {
1426        if true {
    if !self.root.is_none() {
        ::core::panicking::panic("assertion failed: self.root.is_none()")
    };
};debug_assert!(self.root.is_none());
1427        self.root = Some(root_owned(self.sexp));
1428        self
1429    }
1430
1431    /// Release the pool root iff this handle owns one.
1432    ///
1433    /// Through [`with_r_thread`]: the pool lives on R's main thread, so a
1434    /// handle dropped on any other thread panics instead of touching it.
1435    ///
1436    /// [`with_r_thread`]: crate::with_r_thread
1437    #[inline]
1438    fn release_root_if_owned(&self) {
1439        let Some(key) = self.root else {
1440            return;
1441        };
1442        crate::with_r_thread(move || unroot_owned(key));
1443    }
1444
1445    /// Box `x` in its [`RefCell`] and erase that to the `Box<Box<dyn Any>>` R
1446    /// stores, returning the cell's address for `cached_ptr` as well.
1447    #[inline]
1448    fn erase(x: T) -> (NonNull<RefCell<T>>, *mut Box<dyn Any>) {
1449        let cell: *mut RefCell<T> = Box::into_raw(Box::new(RefCell::new(x)));
1450        // SAFETY: `cell` is the allocation `Box::into_raw` just released, so
1451        // `Box::from_raw` takes it back; the value stays at `cell`.
1452        let inner: Box<dyn Any> = unsafe { Box::from_raw(cell) };
1453        // SAFETY: `Box::into_raw` never returns null.
1454        let cell = unsafe { NonNull::new_unchecked(cell) };
1455        (cell, Box::into_raw(Box::new(inner)))
1456    }
1457
1458    /// Allocates memory on the heap and places `x` into it.
1459    ///
1460    /// Internally stores a `Box<Box<dyn Any>>` — a thin pointer (fits in R's
1461    /// `R_ExternalPtrAddr`) pointing to a fat pointer (carries the `Any` vtable
1462    /// for runtime type checking via `downcast`) to a `RefCell<T>`.
1463    ///
1464    /// # Panics
1465    ///
1466    /// Panics if called from a thread other than R's main thread (through
1467    /// [`with_r_thread`]); `x` is dropped.
1468    ///
1469    /// Equivalent to `Box::new`.
1470    ///
1471    /// [`with_r_thread`]: crate::with_r_thread
1472    #[inline]
1473    pub fn new(x: T) -> Self {
1474        let (cached_ptr, any_raw) = Self::erase(x);
1475
1476        // Own the allocation until R holds it: if `with_r_thread` panics, the
1477        // closure drops it. The pool root is taken on the main thread, where
1478        // the pool lives.
1479        // SAFETY: `any_raw` is the live `Box::into_raw` allocation `erase` made.
1480        let any_box = unsafe { Box::from_raw(any_raw) };
1481        let (sexp, root) = crate::with_r_thread(move || unsafe {
1482            Self::create_extptr_sexp_unchecked(Box::into_raw(any_box))
1483        });
1484
1485        Self::from_owned_parts(sexp, cached_ptr, root)
1486    }
1487
1488    /// Allocates memory on the heap and places `x` into it, without thread checks.
1489    ///
1490    /// # Safety
1491    ///
1492    /// Must be called from R's main thread. Calling from another thread
1493    /// is undefined behavior (R APIs are not thread-safe).
1494    #[inline]
1495    pub unsafe fn new_unchecked(x: T) -> Self {
1496        let (cached_ptr, any_raw) = Self::erase(x);
1497        let (sexp, root) = unsafe { Self::create_extptr_sexp_unchecked(any_raw) };
1498        Self::from_owned_parts(sexp, cached_ptr, root)
1499    }
1500
1501    /// Create an EXTPTRSXP from a `*mut Box<dyn Any>`. Must be called from main thread.
1502    ///
1503    /// The `any_raw` is a thin pointer to a heap-allocated fat pointer (`Box<dyn Any>`).
1504    /// R stores the thin pointer in `R_ExternalPtrAddr`. Returns the SEXP and the
1505    /// [`ProtectPool`] key that roots it for the owning handle's lifetime.
1506    #[inline]
1507    unsafe fn create_extptr_sexp(any_raw: *mut Box<dyn Any>) -> (SEXP, ProtectKey) {
1508        if true {
    if !!any_raw.is_null() {
        {
            ::core::panicking::panic_fmt(format_args!("create_extptr_sexp received null pointer"));
        }
    };
};debug_assert!(
1509            !any_raw.is_null(),
1510            "create_extptr_sexp received null pointer"
1511        );
1512
1513        // Own the Rust allocation until its R finalizer is registered. Temporary
1514        // roots remain lexical even when a pool root takes over on success.
1515        let allocation = unsafe { Box::from_raw(any_raw) };
1516        let scope = unsafe { ProtectScope::new() };
1517        let type_sym = unsafe { type_symbol::<T>() };
1518        let type_id_sym = unsafe { type_id_symbol::<T>() };
1519        let prot = unsafe { Rf_allocVector(SEXPTYPE::VECSXP, prot_vec_len::<T>()) };
1520        unsafe { scope.protect(prot) };
1521        prot.set_vector_elt(PROT_TYPE_ID_INDEX, type_id_sym);
1522
1523        let sexp = unsafe { R_MakeExternalPtr(ptr::null_mut(), type_sym, prot) };
1524        unsafe { scope.protect(sexp) };
1525
1526        // Non-generic finalizer — Box<dyn Any> vtable handles the concrete drop
1527        unsafe { R_RegisterCFinalizerEx(sexp, finalizer::<T>(), Rboolean::TRUE) };
1528        // Install the address only after the finalizer is ready. Use the pointer
1529        // returned by the ownership transfer, retaining its mutable provenance.
1530        let any_raw = Box::into_raw(allocation);
1531        unsafe { R_SetExternalPtrAddr(sexp, any_raw.cast()) };
1532
1533        // Move the value's pending `Sidecar` values into `prot`, which is
1534        // protected.
1535        if T::R_SLOT_COUNT > 0 {
1536            unsafe { init_sidecars::<T>(any_raw, sexp) };
1537        }
1538        // A serde type carries its value into a save (#2186).
1539        unsafe { snapshot::init_carrier::<T>(sexp) };
1540
1541        // Root the owning handle for its whole Rust lifetime so it survives R
1542        // allocations while held (e.g. element-by-element in a `Vec`) before
1543        // reaching R (#836). The pool gives O(1) any-order release — see the
1544        // `EXTPTR_ROOTS` docs for why that beats `R_PreserveObject` here.
1545        let root = root_owned(sexp);
1546
1547        (sexp, root)
1548    }
1549
1550    /// Create an EXTPTRSXP from a `*mut Box<dyn Any>` without thread safety checks.
1551    ///
1552    /// # Safety
1553    ///
1554    /// Must be called from R's main thread. No debug assertions for thread safety.
1555    ///
1556    /// Returns the SEXP and the [`ProtectPool`] key that roots it.
1557    #[inline]
1558    unsafe fn create_extptr_sexp_unchecked(any_raw: *mut Box<dyn Any>) -> (SEXP, ProtectKey) {
1559        if true {
    if !!any_raw.is_null() {
        {
            ::core::panicking::panic_fmt(format_args!("create_extptr_sexp_unchecked received null pointer"));
        }
    };
};debug_assert!(
1560            !any_raw.is_null(),
1561            "create_extptr_sexp_unchecked received null pointer"
1562        );
1563
1564        let allocation = unsafe { Box::from_raw(any_raw) };
1565        let scope = unsafe { ProtectScope::new() };
1566        let type_sym = unsafe { type_symbol_unchecked::<T>() };
1567        let type_id_sym = unsafe { type_id_symbol_unchecked::<T>() };
1568
1569        let prot = unsafe { Rf_allocVector_unchecked(SEXPTYPE::VECSXP, prot_vec_len::<T>()) };
1570        unsafe { scope.protect(prot) };
1571        unsafe { prot.set_vector_elt_unchecked(PROT_TYPE_ID_INDEX, type_id_sym) };
1572
1573        let sexp = unsafe { R_MakeExternalPtr_unchecked(ptr::null_mut(), type_sym, prot) };
1574        unsafe { scope.protect(sexp) };
1575
1576        // Non-generic finalizer — Box<dyn Any> vtable handles the concrete drop
1577        unsafe {
1578            R_RegisterCFinalizerEx_unchecked(sexp, finalizer::<T>(), Rboolean::TRUE);
1579        };
1580        let any_raw = Box::into_raw(allocation);
1581        unsafe { R_SetExternalPtrAddr_unchecked(sexp, any_raw.cast()) };
1582
1583        // Flush the value's pending `Sidecar` values and add the carrier of a
1584        // serde type (see `create_extptr_sexp`).
1585        if T::R_SLOT_COUNT > 0 {
1586            unsafe { init_sidecars::<T>(any_raw, sexp) };
1587        }
1588        unsafe { snapshot::init_carrier::<T>(sexp) };
1589
1590        // Root the owning handle (see `create_extptr_sexp` for the rationale).
1591        // `root_owned` uses the pool's checked FFI, which runs inline here
1592        // because the unchecked constructors are main-thread-by-contract.
1593        let root = root_owned(sexp);
1594
1595        (sexp, root)
1596    }
1597
1598    /// Collect an iterator of values into a protected R list (`VECSXP`) holding
1599    /// one fresh external pointer per item, rooting each via the destination
1600    /// list instead of the [`ProtectPool`](crate::protect_pool).
1601    ///
1602    /// This is the GC-safe, allocation-lean way to hand many Rust values to R at
1603    /// once — e.g. converting a `Vec<T>` into an R `list()` of external pointers.
1604    /// Each `EXTPTRSXP` is created and **immediately** stored into the
1605    /// already-protected result list, so the list roots it the instant it
1606    /// exists: there is no unprotected window between element allocations, and
1607    /// **no per-element pool traffic**.
1608    ///
1609    /// Contrast the naive `items.map(ExternalPtr::new).collect::<Vec<_>>()`,
1610    /// which roots every handle in the process-wide pool (keeping the `Vec`
1611    /// GC-safe while held — #836) only to release every root again when the `Vec`
1612    /// drops, then still needs a second pass to copy the handles into a list.
1613    /// Here the list *is* the root, so both the pool round-trip and the copy
1614    /// pass are skipped. The whole batch also takes a single
1615    /// [`with_r_thread`](crate::with_r_thread) main-thread check rather than
1616    /// one per element.
1617    ///
1618    /// The returned `VECSXP` is **not** protected: the caller must protect it or
1619    /// return it to R immediately, exactly like any other freshly built SEXP
1620    /// (e.g. an [`IntoR`](crate::IntoR) result).
1621    pub fn collect_into_r_list<I>(items: I) -> SEXP
1622    where
1623        I: IntoIterator<Item = T>,
1624    {
1625        // Box + type-erase every value first (no R API needed). Keep them owned
1626        // until each pointer's finalizer is registered: iterator or conversion
1627        // panics must drop every value that has not yet been transferred to R.
1628        let allocations: Vec<Box<dyn Any>> = items
1629            .into_iter()
1630            .map(|x| -> Box<dyn Any> { Box::new(RefCell::new(x)) })
1631            .collect();
1632        crate::with_r_thread(move || {
1633            // SAFETY: `with_r_thread` runs this on R's main thread; every entry
1634            // owns a `RefCell<T>` in the ordinary ExternalPtr layout.
1635            unsafe { Self::build_extptr_list(allocations) }
1636        })
1637    }
1638
1639    /// Build a protected `VECSXP` of external pointers from already-erased boxes.
1640    ///
1641    /// Allocates the result list, protects it, then creates one `EXTPTRSXP` per
1642    /// entry directly into its slot — rooted by the protected list, no pool. The
1643    /// type symbols are interned once and reused (they are never GC'd, so they
1644    /// stay valid across the allocating loop). Returns the list **unprotected**.
1645    ///
1646    /// # Safety
1647    ///
1648    /// Must run on R's main thread; each allocation must wrap a `RefCell<T>`.
1649    unsafe fn build_extptr_list(allocations: Vec<Box<dyn Any>>) -> SEXP {
1650        let n = R_xlen_t::try_from(allocations.len()).expect("list length exceeds R_xlen_t::MAX");
1651        let scope = unsafe { ProtectScope::new() };
1652        let list = unsafe { Rf_allocVector_unchecked(SEXPTYPE::VECSXP, n) };
1653        unsafe { scope.protect(list) };
1654
1655        let type_sym = unsafe { type_symbol_unchecked::<T>() };
1656        let type_id_sym = unsafe { type_id_symbol_unchecked::<T>() };
1657
1658        for (i, allocation) in allocations.into_iter().enumerate() {
1659            let idx = R_xlen_t::try_from(i).expect("index exceeds R_xlen_t::MAX");
1660            // Only now allocate the outer box that gives R a thin address.
1661            let any_raw = Box::into_raw(Box::new(allocation));
1662            // SAFETY: main thread; `any_raw` owns a `T`; `list` is protected, so
1663            // it roots each element the instant `set_vector_elt` stores it.
1664            unsafe { Self::make_extptr_into_slot(any_raw, type_sym, type_id_sym, list, idx) };
1665        }
1666
1667        list
1668    }
1669
1670    /// Create an `EXTPTRSXP` for `any_raw` and store it into `dest[idx]`.
1671    ///
1672    /// Mirrors [`create_extptr_sexp_unchecked`](Self::create_extptr_sexp_unchecked)
1673    /// but roots the new pointer via `dest` (which the caller keeps protected)
1674    /// instead of the pool — the element is live the instant it lands in the
1675    /// protected list, so a bulk build pays no pool insert/release per element.
1676    ///
1677    /// # Safety
1678    ///
1679    /// Must run on R's main thread; `any_raw` must own a `T`; `dest` must be a
1680    /// protected `VECSXP` with `idx` in bounds; `type_sym` / `type_id_sym` must
1681    /// be the interned symbols for `T`.
1682    #[inline]
1683    unsafe fn make_extptr_into_slot(
1684        any_raw: *mut Box<dyn Any>,
1685        type_sym: SEXP,
1686        type_id_sym: SEXP,
1687        dest: SEXP,
1688        idx: R_xlen_t,
1689    ) {
1690        let allocation = unsafe { Box::from_raw(any_raw) };
1691        let scope = unsafe { ProtectScope::new() };
1692        let prot = unsafe { Rf_allocVector_unchecked(SEXPTYPE::VECSXP, prot_vec_len::<T>()) };
1693        unsafe { scope.protect(prot) };
1694        unsafe { prot.set_vector_elt_unchecked(PROT_TYPE_ID_INDEX, type_id_sym) };
1695
1696        let sexp = unsafe { R_MakeExternalPtr_unchecked(ptr::null_mut(), type_sym, prot) };
1697        unsafe { scope.protect(sexp) };
1698        unsafe { R_RegisterCFinalizerEx_unchecked(sexp, finalizer::<T>(), Rboolean::TRUE) };
1699        let any_raw = Box::into_raw(allocation);
1700        unsafe { R_SetExternalPtrAddr_unchecked(sexp, any_raw.cast()) };
1701
1702        // Flush the value's pending `Sidecar` values and add the carrier of a
1703        // serde type (see `create_extptr_sexp`).
1704        if T::R_SLOT_COUNT > 0 {
1705            unsafe { init_sidecars::<T>(any_raw, sexp) };
1706        }
1707        unsafe { snapshot::init_carrier::<T>(sexp) };
1708
1709        // Root via the destination list instead of the pool: `dest` is protected
1710        // by the caller, so storing `sexp` keeps it (and its `prot`) alive with
1711        // no pool churn.
1712        unsafe { dest.set_vector_elt_unchecked(idx, sexp) };
1713    }
1714
1715    /// Constructs a new `ExternalPtr` with uninitialized contents.
1716    ///
1717    /// Equivalent to `Box::new_uninit`.
1718    #[inline]
1719    pub fn new_uninit() -> ExternalPtr<MaybeUninit<T>>
1720    where
1721        MaybeUninit<T>: TypedExternal,
1722    {
1723        ExternalPtr::new(MaybeUninit::uninit())
1724    }
1725
1726    /// Constructs a new `ExternalPtr` with zeroed contents.
1727    ///
1728    /// Equivalent to `Box::new_zeroed`.
1729    #[inline]
1730    pub fn new_zeroed() -> ExternalPtr<MaybeUninit<T>>
1731    where
1732        MaybeUninit<T>: TypedExternal,
1733    {
1734        ExternalPtr::new(MaybeUninit::zeroed())
1735    }
1736
1737    /// Constructs an ExternalPtr from a raw pointer.
1738    ///
1739    /// Moves the value out of the `Box<T>` allocation into the pointer's own
1740    /// `RefCell<T>` storage and frees that allocation, so the value's address
1741    /// changes: `from_raw(into_raw(p))` round-trips the value, not the address.
1742    ///
1743    /// # Safety
1744    ///
1745    /// - `raw` must have been allocated via `Box::into_raw` or equivalent
1746    /// - `raw` must not be null
1747    /// - Caller transfers ownership to the ExternalPtr
1748    /// - Must be called from R's main thread
1749    ///
1750    /// Like `Box::from_raw`, except for the address.
1751    #[inline]
1752    pub unsafe fn from_raw(raw: *mut T) -> Self {
1753        let (cached_ptr, any_raw) = Self::erase(*unsafe { Box::from_raw(raw) });
1754        let (sexp, root) = unsafe { Self::create_extptr_sexp(any_raw) };
1755        Self::from_owned_parts(sexp, cached_ptr, root)
1756    }
1757
1758    /// Constructs an ExternalPtr from a raw pointer, without thread checks.
1759    ///
1760    /// # Safety
1761    ///
1762    /// - `raw` must have been allocated via `Box::into_raw` or equivalent
1763    /// - `raw` must not be null
1764    /// - Caller transfers ownership to the ExternalPtr
1765    /// - Must be called from R's main thread (no debug assertions)
1766    #[inline]
1767    pub unsafe fn from_raw_unchecked(raw: *mut T) -> Self {
1768        let (cached_ptr, any_raw) = Self::erase(*unsafe { Box::from_raw(raw) });
1769        let (sexp, root) = unsafe { Self::create_extptr_sexp_unchecked(any_raw) };
1770        Self::from_owned_parts(sexp, cached_ptr, root)
1771    }
1772
1773    /// Consumes the ExternalPtr, returning a raw pointer.
1774    ///
1775    /// The caller is responsible for the memory, and the finalizer is
1776    /// effectively orphaned (will do nothing since we clear the pointer).
1777    /// The R object is emptied: address, tag and protection list (each
1778    /// [`Sidecar<T>`] slot is read back into its field as a pending value
1779    /// first, so the values travel with the struct), so its accessors report
1780    /// a null external pointer, not an object restored from a saved session.
1781    ///
1782    /// The value moves out of the pointer's `RefCell<T>` storage into a new
1783    /// `Box<T>`, so its address changes. Like [`into_inner`](Self::into_inner),
1784    /// this raises the `miniextendr_borrow_conflict` error while a running call
1785    /// holds the value.
1786    ///
1787    /// Like `Box::into_raw`, except for the address.
1788    #[inline]
1789    pub fn into_raw(this: Self) -> *mut T {
1790        Box::into_raw(Box::new(Self::into_inner(this)))
1791    }
1792
1793    /// Consumes the ExternalPtr, returning a `NonNull` pointer.
1794    ///
1795    /// Equivalent to `Box::into_non_null`.
1796    #[inline]
1797    pub fn into_non_null(this: Self) -> NonNull<T> {
1798        unsafe { NonNull::new_unchecked(Self::into_raw(this)) }
1799    }
1800
1801    /// Consumes and leaks the ExternalPtr, returning a mutable reference.
1802    ///
1803    /// The memory will never be freed (from Rust's perspective; R's GC
1804    /// finalizer is neutralized).
1805    ///
1806    /// Equivalent to `Box::leak`.
1807    #[inline]
1808    pub fn leak<'a>(this: Self) -> &'a mut T
1809    where
1810        T: 'a,
1811    {
1812        unsafe { &mut *Self::into_raw(this) }
1813    }
1814
1815    /// Consumes the ExternalPtr, returning the wrapped value.
1816    ///
1817    /// Uses `Box<dyn Any>::downcast` to recover the concrete
1818    /// `Box<RefCell<T>>`, then moves the value out. The R object is emptied
1819    /// like by [`into_raw`](Self::into_raw): its accessors report a null
1820    /// external pointer afterwards, and each [`Sidecar<T>`] slot is read back
1821    /// into its field as a pending value, so wrapping the value again keeps
1822    /// the values.
1823    ///
1824    /// # Panics
1825    ///
1826    /// With the `miniextendr_borrow_conflict` R error while a running call
1827    /// (a generated method of the same object, further up the stack) holds the
1828    /// value: the call's borrow points into the storage this frees.
1829    ///
1830    /// Equivalent to `*boxed` (deref move) or `Box::into_inner`.
1831    #[inline]
1832    pub fn into_inner(this: Self) -> T {
1833        let any_raw = unsafe { R_ExternalPtrAddr(this.sexp) as *mut Box<dyn Any> };
1834        if !!any_raw.is_null() {
    {
        ::core::panicking::panic_fmt(format_args!("ExternalPtr is null or cleared"));
    }
};assert!(!any_raw.is_null(), "ExternalPtr is null or cleared");
1835        if !unsafe { stored_type_id_symbol(this.sexp) }.is_some() {
    {
        ::core::panicking::panic_fmt(format_args!("ExternalPtr has no valid storage metadata"));
    }
};assert!(
1836            unsafe { stored_type_id_symbol(this.sexp) }.is_some(),
1837            "ExternalPtr has no valid storage metadata"
1838        );
1839        if let Some(cell) = unsafe { &*any_raw }.downcast_ref::<RefCell<T>>() {
1840            drop(borrow_value_mut(cell));
1841        }
1842
1843        // The value leaves its pointer: read its slots back into the struct
1844        // as pending values, slot `i` into field `i`, so wrapping it again
1845        // keeps them.
1846        if T::R_SLOT_COUNT > 0 {
1847            // SAFETY: `cached_ptr` is valid for the handle's lifetime and no
1848            // call holds the value; `sexp` is the live pointer this handle
1849            // holds.
1850            let prot = unsafe { R_ExternalPtrProtected(this.sexp) };
1851            load_sidecars(unsafe { &*this.value_ptr() }, prot);
1852        }
1853
1854        // Ownership leaves this handle: drop our GC root before `mem::forget`.
1855        this.release_root_if_owned();
1856
1857        // Clear so finalizer is no-op
1858        unsafe { clear_moved_out(this.sexp) };
1859        mem::forget(this);
1860
1861        let outer: Box<Box<dyn Any>> = unsafe { Box::from_raw(any_raw) };
1862        let inner: Box<dyn Any> = *outer;
1863        inner
1864            .downcast::<RefCell<T>>()
1865            .expect("ExternalPtr type mismatch in into_inner")
1866            .into_inner()
1867    }
1868
1869    // region: Accessors
1870
1871    /// The value's `RefCell`.
1872    #[inline]
1873    fn cell(&self) -> &RefCell<T> {
1874        // SAFETY: cached_ptr is always valid for the lifetime of ExternalPtr,
1875        // and a shared reference to the cell is always sound.
1876        unsafe { self.cached_ptr.as_ref() }
1877    }
1878
1879    /// The value's address, through its `RefCell`.
1880    #[inline]
1881    fn value_ptr(&self) -> *mut T {
1882        // `as_ptr` gives a pointer that may be written through.
1883        self.cell().as_ptr()
1884    }
1885
1886    /// Borrows the value, as the generated wrapper does for a `&T` argument:
1887    /// until the returned view drops, a method of the same object that needs
1888    /// it mutably, a `&mut T` argument holding it, or
1889    /// [`borrow_mut`](Self::borrow_mut) through another handle raises the
1890    /// error below instead. The view also carries the R object, for the
1891    /// sidecar accessors.
1892    ///
1893    /// # Panics
1894    ///
1895    /// With the R error of class `miniextendr_borrow_conflict` while the value
1896    /// is borrowed mutably, and for a type-erased `ExternalPtr<()>`, which has
1897    /// no value of its own to borrow (downcast it first).
1898    #[inline]
1899    pub fn borrow(&self) -> ExternalPtrRef<'_, T> {
1900        ExternalPtrRef::from_guard(&self.sexp, borrow_value(self.value_cell()))
1901    }
1902
1903    /// Borrows the value mutably, as the generated wrapper does for a
1904    /// `&mut T` argument: until the returned view drops, any other borrow of
1905    /// the value raises the error below.
1906    ///
1907    /// # Panics
1908    ///
1909    /// With the R error of class `miniextendr_borrow_conflict` while the value
1910    /// is borrowed (by a running call holding it, or another handle's
1911    /// [`borrow`](Self::borrow)), and for a type-erased `ExternalPtr<()>`.
1912    #[inline]
1913    pub fn borrow_mut(&mut self) -> ExternalPtrMut<'_, T> {
1914        ExternalPtrMut::from_guard(&self.sexp, borrow_value_mut(self.value_cell()))
1915    }
1916
1917    /// The value, with no `RefCell` borrow: only the ALTREP `data1` paths,
1918    /// whose per-element callbacks read without one until #2103 measures the
1919    /// checked read.
1920    ///
1921    /// # Safety
1922    ///
1923    /// Nothing may hold the value mutably while the reference lives.
1924    #[doc(hidden)]
1925    #[inline]
1926    pub unsafe fn as_ref_unchecked(&self) -> &T {
1927        // SAFETY: the value lives as long as the handle; the caller excludes
1928        // a mutable borrow.
1929        unsafe { &*self.value_ptr() }
1930    }
1931
1932    /// The value mutably, with no `RefCell` borrow, like
1933    /// [`as_ref_unchecked`](Self::as_ref_unchecked).
1934    ///
1935    /// # Safety
1936    ///
1937    /// Nothing else may hold the value while the reference lives.
1938    #[doc(hidden)]
1939    #[inline]
1940    pub unsafe fn as_mut_unchecked(&mut self) -> &mut T {
1941        // SAFETY: as in `as_ref_unchecked`.
1942        unsafe { &mut *self.value_ptr() }
1943    }
1944
1945    /// The value's `RefCell`, which a type-erased handle doesn't point at.
1946    #[inline]
1947    fn value_cell(&self) -> &RefCell<T> {
1948        if !!is_type_erased::<T>() {
    {
        ::core::panicking::panic_fmt(format_args!("a type-erased `ExternalPtr<()>` has no value of its own to borrow; downcast it first"));
    }
};assert!(
1949            !is_type_erased::<T>(),
1950            "a type-erased `ExternalPtr<()>` has no value of its own to borrow; downcast it first"
1951        );
1952        self.cell()
1953    }
1954
1955    /// Returns the raw pointer without consuming the ExternalPtr.
1956    #[inline]
1957    pub fn as_ptr(&self) -> *const T {
1958        self.value_ptr().cast_const()
1959    }
1960
1961    /// Returns the raw mutable pointer without consuming the ExternalPtr.
1962    #[inline]
1963    pub fn as_mut_ptr(&mut self) -> *mut T {
1964        self.value_ptr()
1965    }
1966
1967    /// Checks whether two `ExternalPtr`s refer to the same allocation (pointer identity).
1968    ///
1969    /// This ignores the pointee values. Use this when you need alias detection;
1970    /// prefer `PartialEq`/`PartialOrd` for value comparisons.
1971    #[inline]
1972    pub fn ptr_eq(this: &Self, other: &Self) -> bool {
1973        ptr::eq(this.cached_ptr.as_ptr(), other.cached_ptr.as_ptr())
1974    }
1975    // endregion
1976
1977    // region: R-specific accessors
1978
1979    /// Returns the underlying SEXP.
1980    ///
1981    /// # Warning
1982    ///
1983    /// The returned SEXP must not be duplicated or the finalizer will double-free.
1984    #[inline]
1985    pub fn as_sexp(&self) -> SEXP {
1986        self.sexp
1987    }
1988
1989    /// A second handle to the same R object: no value is copied and no R
1990    /// object is allocated, and the handle takes no borrow until it is read.
1991    /// Returning it from a `#[miniextendr]` function returns the same R
1992    /// object, so R sees the identity it passed in.
1993    ///
1994    /// ```ignore
1995    /// #[miniextendr]
1996    /// pub fn first_of(objs: Vec<ExternalPtr<MyType>>) -> ExternalPtr<MyType> {
1997    ///     objs[0].same_object()
1998    /// }
1999    /// ```
2000    ///
2001    /// The new handle takes no GC root of its own: something else (the handle
2002    /// it was made from, or R) must keep the R object reachable while it is
2003    /// used.
2004    #[inline]
2005    pub fn same_object(&self) -> Self {
2006        // SAFETY: self.sexp is a valid live EXTPTRSXP that we already hold.
2007        // wrap_sexp re-extracts the data pointer from the same SEXP.
2008        unsafe { Self::wrap_sexp(self.sexp) }
2009            .expect("same_object of a live ExternalPtr should never fail")
2010    }
2011
2012    /// Returns the tag SEXP (type identifier symbol).
2013    #[inline]
2014    pub fn tag(&self) -> SEXP {
2015        unsafe { R_ExternalPtrTag(self.sexp) }
2016    }
2017
2018    /// Returns the tag SEXP (unchecked version).
2019    ///
2020    /// Skips thread safety checks for performance-critical paths.
2021    ///
2022    /// # Safety
2023    ///
2024    /// Must be called from the R main thread. Only use in ALTREP callbacks
2025    /// or other contexts where you're certain you're on the main thread.
2026    #[inline]
2027    pub unsafe fn tag_unchecked(&self) -> SEXP {
2028        unsafe { crate::sys::R_ExternalPtrTag_unchecked(self.sexp) }
2029    }
2030
2031    /// Returns the protected SEXP slot (user-protected objects).
2032    ///
2033    /// This returns the user-protected object stored in the prot VECSXP,
2034    /// not the VECSXP itself.
2035    #[inline]
2036    pub fn protected(&self) -> SEXP {
2037        unsafe {
2038            let prot = R_ExternalPtrProtected(self.sexp);
2039            if prot.is_null_or_nil() {
2040                return SEXP::nil();
2041            }
2042            if prot.type_of() != SEXPTYPE::VECSXP || prot.len() < PROT_VEC_LEN as usize {
2043                return SEXP::nil();
2044            }
2045            prot.vector_elt(PROT_USER_INDEX)
2046        }
2047    }
2048
2049    /// Returns the protected SEXP slot (unchecked version).
2050    ///
2051    /// Skips thread safety checks for performance-critical paths.
2052    ///
2053    /// # Safety
2054    ///
2055    /// Must be called from the R main thread. Only use in ALTREP callbacks
2056    /// or other contexts where you're certain you're on the main thread.
2057    #[inline]
2058    pub unsafe fn protected_unchecked(&self) -> SEXP {
2059        use crate::sys::R_ExternalPtrProtected_unchecked;
2060
2061        unsafe {
2062            let prot = R_ExternalPtrProtected_unchecked(self.sexp);
2063            if prot.is_null_or_nil() {
2064                return SEXP::nil();
2065            }
2066            if prot.type_of() != SEXPTYPE::VECSXP || prot.len() < PROT_VEC_LEN as usize {
2067                return SEXP::nil();
2068            }
2069            prot.vector_elt_unchecked(PROT_USER_INDEX)
2070        }
2071    }
2072
2073    /// Sets the user-protected SEXP slot.
2074    ///
2075    /// Use this to prevent R objects from being GC'd while this ExternalPtr exists.
2076    /// The type ID stored in prot slot 0 is preserved.
2077    ///
2078    /// Returns `false` if the prot structure is malformed (should not happen
2079    /// for ExternalPtrs created by this library).
2080    ///
2081    /// # Safety
2082    ///
2083    /// - `user_prot` must be a valid SEXP or R_NilValue
2084    /// - Must be called from the R main thread
2085    #[inline]
2086    pub unsafe fn set_protected(&self, user_prot: SEXP) -> bool {
2087        unsafe {
2088            let prot = R_ExternalPtrProtected(self.sexp);
2089            if prot.is_null_or_nil() {
2090                if true {
    if !false {
        {
            ::core::panicking::panic_fmt(format_args!("ExternalPtr prot slot is null or R_NilValue"));
        }
    };
};debug_assert!(false, "ExternalPtr prot slot is null or R_NilValue");
2091                return false;
2092            }
2093            if prot.type_of() != SEXPTYPE::VECSXP || prot.len() < PROT_VEC_LEN as usize {
2094                if true {
    if !false {
        {
            ::core::panicking::panic_fmt(format_args!("ExternalPtr prot slot is not a VECSXP of expected length"));
        }
    };
};debug_assert!(
2095                    false,
2096                    "ExternalPtr prot slot is not a VECSXP of expected length"
2097                );
2098                return false;
2099            }
2100            prot.set_vector_elt(PROT_USER_INDEX, user_prot);
2101            true
2102        }
2103    }
2104
2105    /// Returns the raw prot VECSXP (contains both type ID and user protected).
2106    ///
2107    /// Prefer using `protected()` for user data and `stored_type_id()` for type info.
2108    #[inline]
2109    pub fn prot_raw(&self) -> SEXP {
2110        unsafe { R_ExternalPtrProtected(self.sexp) }
2111    }
2112
2113    /// Checks if the internal pointer is null (already finalized or cleared).
2114    #[inline]
2115    pub fn is_null(&self) -> bool {
2116        unsafe { R_ExternalPtrAddr(self.sexp).is_null() }
2117    }
2118    // endregion
2119
2120    // region: Type checking
2121
2122    /// Attempt to wrap a SEXP as an ExternalPtr with type checking.
2123    ///
2124    /// Uses `Any::downcast_ref` for authoritative type checking (Rust `TypeId`).
2125    /// Type-erased `ExternalPtr<()>` deliberately skips the concrete downcast.
2126    ///
2127    /// A serde type's pointer restored from a saved session gets its value
2128    /// first (#2186): attaching it allocates the pointer's new protection
2129    /// list, so this call may allocate (it never raises).
2130    /// [`wrap_sexp_unchecked`](Self::wrap_sexp_unchecked) does not attach.
2131    ///
2132    /// Returns `None` if:
2133    /// - The internal pointer is null (a restored pointer whose save carries
2134    ///   no value, or one that could not be decoded, included)
2135    /// - The metadata does not identify ordinary miniextendr storage
2136    /// - The stored `Box<dyn Any>` does not contain a `RefCell<T>`
2137    ///
2138    /// # Safety
2139    ///
2140    /// - `sexp` must be a valid EXTPTRSXP; foreign pointers must not carry
2141    ///   forged miniextendr metadata
2142    /// - The caller must ensure no other ExternalPtr owns this SEXP
2143    pub unsafe fn wrap_sexp(sexp: SEXP) -> Option<Self> {
2144        if true {
    {
        match (&sexp.type_of(), &crate::SEXPTYPE::EXTPTRSXP) {
            (left_val, right_val) => {
                if !(*left_val == *right_val) {
                    let kind = ::core::panicking::AssertKind::Eq;
                    ::core::panicking::assert_failed(kind, &*left_val,
                        &*right_val,
                        ::core::option::Option::Some(format_args!("wrap_sexp: expected EXTPTRSXP, got {0:?}",
                                sexp.type_of())));
                }
            }
        }
    };
};debug_assert_eq!(
2145            sexp.type_of(),
2146            crate::SEXPTYPE::EXTPTRSXP,
2147            "wrap_sexp: expected EXTPTRSXP, got {:?}",
2148            sexp.type_of()
2149        );
2150        let any_raw = unsafe { R_ExternalPtrAddr(sexp) as *mut Box<dyn Any> };
2151        if any_raw.is_null() {
2152            // SAFETY: on R's main thread with a valid EXTPTRSXP, which the
2153            // caller roots. Attaching never raises.
2154            return match unsafe { snapshot::attach::<T>(sexp) } {
2155                snapshot::Attach::Attached => unsafe { Self::wrap_sexp(sexp) },
2156                snapshot::Attach::Failed | snapshot::Attach::NoCarrier => None,
2157            };
2158        }
2159        unsafe { stored_type_id_symbol(sexp) }?;
2160
2161        if is_type_erased::<T>() {
2162            // Type-erased path: skip downcast, just use the raw pointer
2163            // (ExternalPtr<()> doesn't care about the concrete type)
2164            return Some(Self::from_borrowed_parts(sexp, unsafe {
2165                NonNull::new_unchecked(any_raw.cast())
2166            }));
2167        }
2168
2169        let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2170        let cell: &RefCell<T> = any_box.downcast_ref::<RefCell<T>>()?;
2171        Some(Self::from_borrowed_parts(sexp, NonNull::from(cell)))
2172    }
2173
2174    /// Attempt to wrap a SEXP as an ExternalPtr (unchecked version).
2175    ///
2176    /// Skips thread safety checks for performance-critical paths like ALTREP callbacks.
2177    /// Unlike [`wrap_sexp`](Self::wrap_sexp) it never attaches a serde type's
2178    /// saved value to a restored pointer (#2186), so it allocates nothing and
2179    /// returns `None` for such a pointer until another access attached it.
2180    ///
2181    /// # Safety
2182    ///
2183    /// - `sexp` must be a valid EXTPTRSXP; foreign pointers must not carry
2184    ///   forged miniextendr metadata
2185    /// - The caller must ensure exclusive ownership
2186    /// - Must be called from the R main thread (guaranteed in ALTREP callbacks)
2187    pub unsafe fn wrap_sexp_unchecked(sexp: SEXP) -> Option<Self> {
2188        use crate::sys::R_ExternalPtrAddr_unchecked;
2189
2190        if true {
    {
        match (&sexp.type_of(), &crate::SEXPTYPE::EXTPTRSXP) {
            (left_val, right_val) => {
                if !(*left_val == *right_val) {
                    let kind = ::core::panicking::AssertKind::Eq;
                    ::core::panicking::assert_failed(kind, &*left_val,
                        &*right_val,
                        ::core::option::Option::Some(format_args!("wrap_sexp_unchecked: expected EXTPTRSXP, got {0:?}",
                                sexp.type_of())));
                }
            }
        }
    };
};debug_assert_eq!(
2191            sexp.type_of(),
2192            crate::SEXPTYPE::EXTPTRSXP,
2193            "wrap_sexp_unchecked: expected EXTPTRSXP, got {:?}",
2194            sexp.type_of()
2195        );
2196        let any_raw = unsafe { R_ExternalPtrAddr_unchecked(sexp) as *mut Box<dyn Any> };
2197        if any_raw.is_null() {
2198            return None;
2199        }
2200        unsafe { stored_type_id_symbol(sexp) }?;
2201
2202        if is_type_erased::<T>() {
2203            return Some(Self::from_borrowed_parts(sexp, unsafe {
2204                NonNull::new_unchecked(any_raw.cast())
2205            }));
2206        }
2207
2208        let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2209        let cell: &RefCell<T> = any_box.downcast_ref::<RefCell<T>>()?;
2210        Some(Self::from_borrowed_parts(sexp, NonNull::from(cell)))
2211    }
2212
2213    /// Attempt to wrap a SEXP as an ExternalPtr, returning an error with type info on mismatch.
2214    ///
2215    /// This is used by the [`TryFromSexp`] trait implementation.
2216    ///
2217    /// A pointer restored from a saved session gets its value first when `T`
2218    /// derives serde and the save carries one (#2186). A save that could not
2219    /// be decoded raises its refusal (the classed restored error, with the
2220    /// decoding error as `e$parent`); every other pointer without a value is
2221    /// returned as `Err`.
2222    ///
2223    /// # Safety
2224    ///
2225    /// Same as [`wrap_sexp`](Self::wrap_sexp).
2226    ///
2227    /// [`TryFromSexp`]: crate::TryFromSexp
2228    pub unsafe fn wrap_sexp_with_error(sexp: SEXP) -> Result<Self, TypeMismatchError> {
2229        if true {
    {
        match (&sexp.type_of(), &crate::SEXPTYPE::EXTPTRSXP) {
            (left_val, right_val) => {
                if !(*left_val == *right_val) {
                    let kind = ::core::panicking::AssertKind::Eq;
                    ::core::panicking::assert_failed(kind, &*left_val,
                        &*right_val,
                        ::core::option::Option::Some(format_args!("wrap_sexp_with_error: expected EXTPTRSXP, got {0:?}",
                                sexp.type_of())));
                }
            }
        }
    };
};debug_assert_eq!(
2230            sexp.type_of(),
2231            crate::SEXPTYPE::EXTPTRSXP,
2232            "wrap_sexp_with_error: expected EXTPTRSXP, got {:?}",
2233            sexp.type_of()
2234        );
2235        let any_raw = unsafe { R_ExternalPtrAddr(sexp) as *mut Box<dyn Any> };
2236        if any_raw.is_null() {
2237            // SAFETY: on R's main thread with a valid EXTPTRSXP, which the
2238            // caller roots. A serde type's saved value comes back (#2186); a
2239            // save that could not be decoded raises its refusal, with the
2240            // decoding error as `e$parent`.
2241            match unsafe { snapshot::attach::<T>(sexp) } {
2242                snapshot::Attach::Attached => return unsafe { Self::wrap_sexp_with_error(sexp) },
2243                snapshot::Attach::Failed => {
2244                    unsafe { refuse_restored::<T>(sexp, sexp) };
2245                }
2246                snapshot::Attach::NoCarrier => {}
2247            }
2248            // SAFETY: on R's main thread with a valid EXTPTRSXP.
2249            return Err(match unsafe { classify_null_address::<T>(sexp) } {
2250                NullAddress::Foreign => TypeMismatchError::NullPointer,
2251                NullAddress::Restored => TypeMismatchError::Restored {
2252                    type_name: T::TYPE_NAME,
2253                    package_classes: T::RESTORED_ERROR_CLASS,
2254                    package_message: T::RESTORED_ERROR_MESSAGE,
2255                },
2256                NullAddress::OtherVersion {
2257                    crate_name,
2258                    saved,
2259                    current,
2260                } => TypeMismatchError::OtherVersion {
2261                    type_name: T::TYPE_NAME,
2262                    crate_name,
2263                    saved,
2264                    current,
2265                    package_classes: T::RESTORED_ERROR_CLASS,
2266                    package_message: T::RESTORED_ERROR_MESSAGE,
2267                },
2268                NullAddress::OtherType { found } => TypeMismatchError::Mismatch {
2269                    expected: T::TYPE_NAME,
2270                    found,
2271                },
2272            });
2273        }
2274
2275        let stored =
2276            unsafe { stored_type_id_symbol(sexp) }.ok_or(TypeMismatchError::InvalidTypeId)?;
2277
2278        if is_type_erased::<T>() {
2279            return Ok(Self::from_borrowed_parts(sexp, unsafe {
2280                NonNull::new_unchecked(any_raw.cast())
2281            }));
2282        }
2283
2284        let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2285        match any_box.downcast_ref::<RefCell<T>>() {
2286            Some(cell) => Ok(Self::from_borrowed_parts(sexp, NonNull::from(cell))),
2287            None => {
2288                // The stored type ID, for the diagnostic.
2289                let found = symbol_name(stored);
2290                Err(TypeMismatchError::Mismatch {
2291                    expected: T::TYPE_NAME,
2292                    found,
2293                })
2294            }
2295        }
2296    }
2297
2298    /// Create an ExternalPtr from an SEXP without type checking.
2299    ///
2300    /// # Safety
2301    ///
2302    /// - `sexp` must be a valid EXTPTRSXP containing a `*mut Box<dyn Any>`
2303    ///   wrapping a `RefCell<T>`
2304    /// - The caller must ensure exclusive ownership
2305    #[inline]
2306    pub unsafe fn from_sexp_unchecked(sexp: SEXP) -> Self {
2307        if true {
    {
        match (&sexp.type_of(), &crate::SEXPTYPE::EXTPTRSXP) {
            (left_val, right_val) => {
                if !(*left_val == *right_val) {
                    let kind = ::core::panicking::AssertKind::Eq;
                    ::core::panicking::assert_failed(kind, &*left_val,
                        &*right_val,
                        ::core::option::Option::Some(format_args!("from_sexp_unchecked: expected EXTPTRSXP, got {0:?}",
                                sexp.type_of())));
                }
            }
        }
    };
};debug_assert_eq!(
2308            sexp.type_of(),
2309            crate::SEXPTYPE::EXTPTRSXP,
2310            "from_sexp_unchecked: expected EXTPTRSXP, got {:?}",
2311            sexp.type_of()
2312        );
2313        let any_raw = unsafe { R_ExternalPtrAddr(sexp) as *mut Box<dyn Any> };
2314
2315        let cached_ptr = if is_type_erased::<T>() {
2316            // A type-erased handle never reads through `cached_ptr` (its
2317            // methods read the address afresh), so a pointer without an
2318            // address (restored from a saved session, or cleared) is accepted
2319            // here: the downcast that follows refuses it with a clear error.
2320            NonNull::new(any_raw.cast()).unwrap_or(NonNull::dangling())
2321        } else {
2322            if true {
    if !!any_raw.is_null() {
        {
            ::core::panicking::panic_fmt(format_args!("from_sexp_unchecked: null pointer"));
        }
    };
};debug_assert!(!any_raw.is_null(), "from_sexp_unchecked: null pointer");
2323            let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2324            NonNull::from(unsafe { any_box.downcast_ref::<RefCell<T>>().unwrap_unchecked() })
2325        };
2326
2327        Self::from_borrowed_parts(sexp, cached_ptr)
2328    }
2329    // endregion
2330
2331    // region: Downcast support
2332
2333    /// Returns the type name for type T.
2334    #[inline]
2335    pub fn type_name() -> &'static str {
2336        T::TYPE_NAME
2337    }
2338
2339    /// Returns the type name stored in this ExternalPtr's prot slot.
2340    ///
2341    /// Returns `None` if the prot slot doesn't contain a valid type symbol.
2342    #[inline]
2343    pub fn stored_type_name(&self) -> Option<&'static str> {
2344        // SAFETY: `self.sexp` is a valid EXTPTRSXP; on R's main thread.
2345        unsafe { stored_type_id_symbol(self.sexp) }.map(symbol_name)
2346    }
2347    // endregion
2348}
2349
2350impl ExternalPtr<()> {
2351    /// Create a type-erased ExternalPtr from an EXTPTRSXP without checking the stored type.
2352    ///
2353    /// # Safety
2354    ///
2355    /// - `sexp` must be a valid EXTPTRSXP
2356    /// - Caller must ensure exclusive ownership semantics are upheld
2357    #[inline]
2358    pub unsafe fn from_sexp(sexp: SEXP) -> Self {
2359        if true {
    if !(sexp.type_of() == SEXPTYPE::EXTPTRSXP) {
        ::core::panicking::panic("assertion failed: sexp.type_of() == SEXPTYPE::EXTPTRSXP")
    };
};debug_assert!(sexp.type_of() == SEXPTYPE::EXTPTRSXP);
2360        unsafe { Self::from_sexp_unchecked(sexp) }
2361    }
2362
2363    /// Check whether the stored `Box<dyn Any>` contains a `T`.
2364    ///
2365    /// Uses `Any::is` for authoritative runtime type checking.
2366    #[inline]
2367    pub fn is<T: TypedExternal>(&self) -> bool {
2368        self.downcast_cell::<T>().is_some()
2369    }
2370
2371    /// The `RefCell` holding the stored value if it is a `T`.
2372    ///
2373    /// Uses `Any::downcast_ref` for authoritative runtime type checking. This
2374    /// is where every generated method receiver (inherent and trait-impl) gets
2375    /// the struct: it borrows the cell for the call.
2376    #[doc(hidden)]
2377    #[inline]
2378    pub fn downcast_cell<T: TypedExternal>(&self) -> Option<&RefCell<T>> {
2379        let any_raw = unsafe { R_ExternalPtrAddr(self.sexp) as *mut Box<dyn Any> };
2380        if any_raw.is_null() {
2381            return None;
2382        }
2383        unsafe { stored_type_id_symbol(self.sexp) }?;
2384        let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2385        any_box.downcast_ref::<RefCell<T>>()
2386    }
2387
2388    /// Borrow the stored value if it is a `T`, like [`ExternalPtr::borrow`].
2389    ///
2390    /// Uses `Any::downcast_ref` for authoritative runtime type checking.
2391    ///
2392    /// # Panics
2393    ///
2394    /// With the R error of class `miniextendr_borrow_conflict` while the value
2395    /// is borrowed mutably.
2396    #[inline]
2397    pub fn downcast_ref<T: TypedExternal>(&self) -> Option<ExternalPtrRef<'_, T>> {
2398        self.downcast_cell::<T>()
2399            .map(|cell| ExternalPtrRef::from_guard(&self.sexp, borrow_value(cell)))
2400    }
2401
2402    /// Borrow the stored value mutably if it is a `T`, like
2403    /// [`ExternalPtr::borrow_mut`].
2404    ///
2405    /// # Panics
2406    ///
2407    /// With the R error of class `miniextendr_borrow_conflict` while the value
2408    /// is borrowed.
2409    #[inline]
2410    pub fn downcast_mut<T: TypedExternal>(&mut self) -> Option<ExternalPtrMut<'_, T>> {
2411        self.downcast_cell::<T>()
2412            .map(|cell| ExternalPtrMut::from_guard(&self.sexp, borrow_value_mut(cell)))
2413    }
2414}
2415
2416// region: Consuming (`self` by value) method support
2417
2418/// Marker left in an `EXTPTRSXP` slot while a consuming (`self` by value)
2419/// method runs, and left behind for good if that method panics.
2420///
2421/// `#[miniextendr]` methods taking bare `self` move the stored value out of
2422/// the R handle with [`ExternalPtr::<()>::take_for_consuming`], call the
2423/// method, and either write the result back
2424/// ([`ExternalPtr::<()>::restore_after_consuming`], for `self -> Self`) or
2425/// leave the slot consumed (terminal `self -> T`). A slot holding this marker
2426/// makes every later method call on the handle fail with a "consumed" error
2427/// instead of a type mismatch; the finaliser drops the marker like any value.
2428#[derive(#[automatically_derived]impl ::core::fmt::Debug for ConsumedSlot {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::write_str(f, "ConsumedSlot")
    }
}Debug)]
2429pub struct ConsumedSlot;
2430
2431/// Bound for the receiver of a **fallible** consuming method
2432/// (`self -> Result<Self, E>` / `self -> Option<Self>`).
2433///
2434/// The generated wrapper calls the method on a clone of the stored value and
2435/// only overwrites the R handle on `Ok` / `Some`, so a failed step leaves the
2436/// R object exactly as it was, which is what an interactive R user expects
2437/// from `obj |> add_step(-1)` erroring. Blanket-implemented for every
2438/// `T: Clone`; the `on_unimplemented` text below is what rustc prints when
2439/// the type is not `Clone`.
2440#[diagnostic::on_unimplemented(
2441    message = "a fallible consuming method (`self -> Result<Self, E>` / `Option<Self>`) needs `{Self}: Clone`",
2442    note = "the wrapper calls the method on a clone so a failed step leaves the R object untouched; derive or implement `Clone`, or take `&mut self` and return `Result<&mut Self, E>` instead"
2443)]
2444pub trait ConsumingFallible: Clone {}
2445impl<T: Clone> ConsumingFallible for T {}
2446
2447/// Clone the stored value for a fallible consuming step (see
2448/// [`ConsumingFallible`]). Free function so codegen can name the bound.
2449#[inline]
2450pub fn clone_for_consuming<T: ConsumingFallible>(value: &T) -> T {
2451    value.clone()
2452}
2453
2454/// Panic with the right message when a handle's stored value is not a `T`:
2455/// "consumed" if a previous `self`-by-value step failed; the classed
2456/// [`RESTORED_NO_VALUE_CLASS`] / [`RESTORED_OTHER_VERSION_CLASS`] error for a
2457/// pointer built for `T` that came back from a saved session without its
2458/// value; type mismatch otherwise. Used by generated method preludes instead
2459/// of a bare `expect`.
2460#[cold]
2461pub fn handle_downcast_failed<T: TypedExternal>(ptr: &ExternalPtr<()>) -> ! {
2462    refuse_consumed_or_restored::<T>(ptr);
2463    {
    ::core::panicking::panic_fmt(format_args!("expected ExternalPtr<{0}>, found `{1}`",
            ExternalPtr::<T>::type_name(),
            ptr.stored_type_name().unwrap_or("<unknown>")));
};panic!(
2464        "expected ExternalPtr<{}>, found `{}`",
2465        ExternalPtr::<T>::type_name(),
2466        ptr.stored_type_name().unwrap_or("<unknown>")
2467    );
2468}
2469
2470/// [`handle_downcast_failed`] for a trait-impl method receiver: the same
2471/// consumed / restored errors, and a mismatch message naming the trait
2472/// method (`Trait::method()`).
2473#[cold]
2474pub fn handle_downcast_failed_in<T: TypedExternal>(ptr: &ExternalPtr<()>, trait_method: &str) -> ! {
2475    refuse_consumed_or_restored::<T>(ptr);
2476    {
    ::core::panicking::panic_fmt(format_args!("type mismatch in {0}: expected ExternalPtr<{1}>, got different type. This can happen if you pass an object of a different type to a trait method.",
            trait_method, ExternalPtr::<T>::type_name()));
};panic!(
2477        "type mismatch in {}: expected ExternalPtr<{}>, got different type. \
2478         This can happen if you pass an object of a different type to a trait method.",
2479        trait_method,
2480        ExternalPtr::<T>::type_name()
2481    );
2482}
2483
2484/// The errors a receiver prelude raises before a type mismatch: "consumed"
2485/// for a slot a failed `self`-by-value step left, the classed restored-object
2486/// errors for a pointer built for `T` without an address.
2487fn refuse_consumed_or_restored<T: TypedExternal>(ptr: &ExternalPtr<()>) {
2488    if ptr.is_consumed() {
2489        {
    ::core::panicking::panic_fmt(format_args!("this `{0}` object was consumed by a `self`-by-value method that did not return a new value (it returned a plain result or panicked) and can no longer be used",
            ExternalPtr::<T>::type_name()));
};panic!(
2490            "this `{}` object was consumed by a `self`-by-value method that did not return \
2491             a new value (it returned a plain result or panicked) and can no longer be used",
2492            ExternalPtr::<T>::type_name()
2493        );
2494    }
2495    if ptr.has_null_address() {
2496        // SAFETY: `ptr.sexp` is a valid EXTPTRSXP without an address; on R's
2497        // main thread (the generated prelude).
2498        unsafe { refuse_restored::<T>(ptr.sexp, ptr.sexp) };
2499    }
2500}
2501
2502impl ExternalPtr<()> {
2503    /// Whether the slot holds the [`ConsumedSlot`] marker.
2504    pub fn is_consumed(&self) -> bool {
2505        let any_raw = unsafe { R_ExternalPtrAddr(self.sexp) as *mut Box<dyn Any> };
2506        if any_raw.is_null() || unsafe { stored_type_id_symbol(self.sexp) }.is_none() {
2507            return false;
2508        }
2509        let any_box: &Box<dyn Any> = unsafe { &*any_raw };
2510        any_box.is::<ConsumedSlot>()
2511    }
2512
2513    /// Whether the pointer has no address: restored from a saved session
2514    /// (`readRDS()` / `unserialize()`), cleared by `into_inner`, or never
2515    /// given one (R's `new("externalptr")`).
2516    pub fn has_null_address(&self) -> bool {
2517        unsafe { R_ExternalPtrAddr(self.sexp) }.is_null()
2518    }
2519
2520    /// Move the stored `T` out of the handle, leaving [`ConsumedSlot`] behind.
2521    ///
2522    /// Returns `None` when the slot does not hold a `T` (wrong type, null, or
2523    /// already consumed); the slot is untouched in that case. The outer
2524    /// `Box<Box<dyn Any>>` cell stays allocated, so the finaliser and every
2525    /// other accessor keep working on the marker. The value's [`Sidecar<T>`]
2526    /// slots stay in the pointer's `prot` list across the method: a
2527    /// `self -> Self` result that keeps the fields (`Self { n, ..self }`)
2528    /// keeps the values, one built afresh (`Self::new(..)`) replaces them at
2529    /// the write-back. Runs on R's main thread (the generated receiver
2530    /// prelude). Raises the `miniextendr_borrow_conflict` error while a
2531    /// running call holds the value.
2532    pub fn take_for_consuming<T: TypedExternal>(&mut self) -> Option<T> {
2533        let any_raw = unsafe { R_ExternalPtrAddr(self.sexp) as *mut Box<dyn Any> };
2534        if any_raw.is_null() {
2535            return None;
2536        }
2537        // A running call's borrow points into the storage this replaces.
2538        drop(borrow_value_mut(self.downcast_cell::<T>()?));
2539        let any_box: &mut Box<dyn Any> = unsafe { &mut *any_raw };
2540        let taken = std::mem::replace(any_box, Box::new(ConsumedSlot));
2541        let cell = taken
2542            .downcast::<RefCell<T>>()
2543            .expect("checked by `downcast_cell` above");
2544        Some(cell.into_inner())
2545    }
2546
2547    /// Put a value back into a slot emptied by [`Self::take_for_consuming`]
2548    /// (the write-back half of `self -> Self`). Replaces whatever the slot
2549    /// holds; the `TypedExternal` tag in the `prot` slot is unchanged because
2550    /// the type is the same. The pending values of the value's
2551    /// [`Sidecar<T>`] fields (what the method set with `Sidecar::new`) are
2552    /// flushed into `prot`, on R's main thread; the other slots keep their
2553    /// values. Raises the `miniextendr_borrow_conflict` error while a
2554    /// running call holds the value the slot holds.
2555    pub fn restore_after_consuming<T: TypedExternal>(&mut self, value: T) {
2556        let any_raw = unsafe { R_ExternalPtrAddr(self.sexp) as *mut Box<dyn Any> };
2557        if !!any_raw.is_null() {
    {
        ::core::panicking::panic_fmt(format_args!("restore_after_consuming on a null external pointer"));
    }
};assert!(
2558            !any_raw.is_null(),
2559            "restore_after_consuming on a null external pointer"
2560        );
2561        if !unsafe { stored_type_id_symbol(self.sexp) }.is_some() {
    {
        ::core::panicking::panic_fmt(format_args!("restore_after_consuming on a foreign external pointer"));
    }
};assert!(
2562            unsafe { stored_type_id_symbol(self.sexp) }.is_some(),
2563            "restore_after_consuming on a foreign external pointer"
2564        );
2565        // A running call's borrow points into the storage this replaces.
2566        if let Some(cell) = self.downcast_cell::<T>() {
2567            drop(borrow_value_mut(cell));
2568        }
2569        let any_box: &mut Box<dyn Any> = unsafe { &mut *any_raw };
2570        *any_box = Box::new(RefCell::new(value));
2571        if T::R_SLOT_COUNT > 0 {
2572            // SAFETY: on R's main thread (checked by `with_r_thread`);
2573            // `any_raw` owns the `T` just stored, inside the live EXTPTRSXP.
2574            crate::with_r_thread(|| unsafe { init_sidecars::<T>(any_raw, self.sexp) });
2575        }
2576    }
2577}
2578
2579// endregion
2580
2581/// Error returned when type checking fails in `try_from_sexp_with_error`.
2582///
2583/// The `found` field in `Mismatch` contains a `&'static str` from R's
2584/// interned symbol table, which persists for the R session lifetime.
2585#[derive(#[automatically_derived]impl ::core::fmt::Debug for TypeMismatchError {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        match self {
            Self::NullPointer =>
                ::core::fmt::Formatter::write_str(f, "NullPointer"),
            Self::InvalidTypeId =>
                ::core::fmt::Formatter::write_str(f, "InvalidTypeId"),
            Self::Mismatch { expected: __self_0, found: __self_1 } =>
                ::core::fmt::Formatter::debug_struct_field2_finish(f,
                    "Mismatch expected found", __self_0, &__self_1),
            Self::Restored {
                type_name: __self_0,
                package_classes: __self_1,
                package_message: __self_2 } =>
                ::core::fmt::Formatter::debug_struct_field3_finish(f,
                    "Restored type_name package_classes package_message",
                    __self_0, __self_1, &__self_2),
            Self::OtherVersion {
                type_name: __self_0,
                crate_name: __self_1,
                saved: __self_2,
                current: __self_3,
                package_classes: __self_4,
                package_message: __self_5 } => {
                let names: &'static _ =
                    "OtherVersion type_name crate_name saved current package_classes package_message";
                let values: &[&dyn ::core::fmt::Debug] =
                    &[__self_0, __self_1, __self_2, __self_3, __self_4,
                                &__self_5];
                ::core::fmt::Formatter::debug_struct_fields_finish(f, names,
                    values)
            }
        }
    }
}Debug, #[automatically_derived]impl ::core::clone::Clone for TypeMismatchError {
    #[inline]
    fn clone(&self) -> Self {
        match self {
            Self::NullPointer => TypeMismatchError::NullPointer,
            Self::InvalidTypeId => TypeMismatchError::InvalidTypeId,
            Self::Mismatch { expected: __self_0, found: __self_1 } =>
                TypeMismatchError::Mismatch {
                    expected: ::core::clone::Clone::clone(__self_0),
                    found: ::core::clone::Clone::clone(__self_1),
                },
            Self::Restored {
                type_name: __self_0,
                package_classes: __self_1,
                package_message: __self_2 } =>
                TypeMismatchError::Restored {
                    type_name: ::core::clone::Clone::clone(__self_0),
                    package_classes: ::core::clone::Clone::clone(__self_1),
                    package_message: ::core::clone::Clone::clone(__self_2),
                },
            Self::OtherVersion {
                type_name: __self_0,
                crate_name: __self_1,
                saved: __self_2,
                current: __self_3,
                package_classes: __self_4,
                package_message: __self_5 } =>
                TypeMismatchError::OtherVersion {
                    type_name: ::core::clone::Clone::clone(__self_0),
                    crate_name: ::core::clone::Clone::clone(__self_1),
                    saved: ::core::clone::Clone::clone(__self_2),
                    current: ::core::clone::Clone::clone(__self_3),
                    package_classes: ::core::clone::Clone::clone(__self_4),
                    package_message: ::core::clone::Clone::clone(__self_5),
                },
        }
    }
}Clone)]
2586pub enum TypeMismatchError {
2587    /// The external pointer's address was null, and it was not built by
2588    /// `ExternalPtr` (R's `new("externalptr")`, a cleared pointer).
2589    NullPointer,
2590    /// The prot slot didn't contain a valid type symbol.
2591    InvalidTypeId,
2592    /// The stored type doesn't match the expected type.
2593    Mismatch {
2594        /// Expected Rust type name from this pointer wrapper.
2595        expected: &'static str,
2596        /// Actual stored Rust type name found in pointer metadata.
2597        found: &'static str,
2598    },
2599    /// A pointer this version of the crate built, restored from a saved
2600    /// session without its Rust value ([`RESTORED_NO_VALUE_CLASS`]).
2601    Restored {
2602        /// The type's name.
2603        type_name: &'static str,
2604        /// The package's classes for the type
2605        /// ([`TypedExternal::RESTORED_ERROR_CLASS`]).
2606        package_classes: &'static [&'static str],
2607        /// The package's message for the type
2608        /// ([`TypedExternal::RESTORED_ERROR_MESSAGE`]).
2609        package_message: Option<&'static str>,
2610    },
2611    /// A pointer another version of the crate saved
2612    /// ([`RESTORED_OTHER_VERSION_CLASS`]).
2613    OtherVersion {
2614        /// The type's name.
2615        type_name: &'static str,
2616        /// The crate's name.
2617        crate_name: &'static str,
2618        /// The version that saved the pointer.
2619        saved: &'static str,
2620        /// This version.
2621        current: &'static str,
2622        /// The package's classes for the type
2623        /// ([`TypedExternal::RESTORED_ERROR_CLASS`]).
2624        package_classes: &'static [&'static str],
2625        /// The package's message for the type
2626        /// ([`TypedExternal::RESTORED_ERROR_MESSAGE`]).
2627        package_message: Option<&'static str>,
2628    },
2629}
2630
2631impl TypeMismatchError {
2632    /// The condition classes of the error about a restored pointer: the
2633    /// package's classes, then the specific class, then [`RESTORED_CLASS`];
2634    /// `None` for the other variants.
2635    pub fn restored_classes(&self) -> Option<Vec<&'static str>> {
2636        let (package_classes, specific) = match self {
2637            Self::Restored {
2638                package_classes, ..
2639            } => (package_classes, RESTORED_NO_VALUE_CLASS),
2640            Self::OtherVersion {
2641                package_classes, ..
2642            } => (package_classes, RESTORED_OTHER_VERSION_CLASS),
2643            Self::NullPointer | Self::InvalidTypeId | Self::Mismatch { .. } => return None,
2644        };
2645        Some(
2646            package_classes
2647                .iter()
2648                .copied()
2649                .chain([specific, RESTORED_CLASS])
2650                .collect(),
2651        )
2652    }
2653}
2654
2655impl fmt::Display for TypeMismatchError {
2656    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2657        match self {
2658            Self::NullPointer => f.write_fmt(format_args!("external pointer is null"))write!(f, "external pointer is null"),
2659            Self::InvalidTypeId => f.write_fmt(format_args!("external pointer has no valid type id"))write!(f, "external pointer has no valid type id"),
2660            Self::Mismatch { expected, found } => {
2661                f.write_fmt(format_args!("type mismatch: expected `{0}`, found `{1}`",
        expected, found))write!(
2662                    f,
2663                    "type mismatch: expected `{}`, found `{}`",
2664                    expected, found
2665                )
2666            }
2667            Self::Restored {
2668                type_name,
2669                package_message,
2670                ..
2671            } => match package_message {
2672                Some(message) => f.write_str(message),
2673                None => f.write_str(&restored_no_value_message(type_name)),
2674            },
2675            Self::OtherVersion {
2676                type_name,
2677                crate_name,
2678                saved,
2679                current,
2680                package_message,
2681                ..
2682            } => match package_message {
2683                Some(message) => f.write_str(message),
2684                None => f.write_str(&restored_other_version_message(
2685                    type_name, crate_name, saved, current,
2686                )),
2687            },
2688        }
2689    }
2690}
2691
2692impl std::error::Error for TypeMismatchError {}
2693// endregion
2694
2695// region: MaybeUninit support
2696
2697// We need a separate TypedExternal impl for MaybeUninit<T>
2698// This is typically done via blanket impl or macro
2699
2700impl<T: TypedExternal> ExternalPtr<MaybeUninit<T>>
2701where
2702    MaybeUninit<T>: TypedExternal,
2703{
2704    /// Converts to `ExternalPtr<T>`.
2705    ///
2706    /// # Safety
2707    ///
2708    /// The value must have been initialized.
2709    ///
2710    /// # Implementation Note
2711    ///
2712    /// This method creates a *new* SEXP with `T`'s type information, leaving
2713    /// the original `MaybeUninit<T>` SEXP as an orphaned empty shell in R's heap.
2714    /// This is necessary because the type ID stored in the prot slot must match
2715    /// the actual type. The orphaned SEXP will be cleaned up by R's GC eventually.
2716    ///
2717    /// If you need to avoid this overhead, consider using `ExternalPtr<T>::new`
2718    /// directly and initializing in place via `as_mut`.
2719    ///
2720    /// Equivalent to `Box::assume_init`.
2721    #[inline]
2722    pub fn assume_init(self) -> ExternalPtr<T> {
2723        // Get the raw pointer (this clears the original SEXP, making its finalizer a no-op)
2724        let ptr = Self::into_raw(self).cast();
2725
2726        // Create a new ExternalPtr with T's type info
2727        unsafe { ExternalPtr::from_raw(ptr) }
2728    }
2729
2730    /// Writes a value and converts to initialized.
2731    ///
2732    /// Creates a new SEXP with `T`'s type information (the original
2733    /// `MaybeUninit<T>` SEXP becomes an orphaned shell, cleaned up by GC).
2734    #[inline]
2735    pub fn write(mut self, value: T) -> ExternalPtr<T> {
2736        unsafe {
2737            (*Self::as_mut_ptr(&mut self)).write(value);
2738            self.assume_init()
2739        }
2740    }
2741}
2742/// Type-erased `ExternalPtr` for cases where the concrete `T` is not needed.
2743pub type ErasedExternalPtr = ExternalPtr<()>;
2744// endregion
2745
2746// region: Trait Implementations
2747
2748impl<T: TypedExternal + Clone> Clone for ExternalPtr<T> {
2749    /// Deep clones the inner value into a new ExternalPtr.
2750    ///
2751    /// This creates a completely independent ExternalPtr with its own
2752    /// heap allocation and finalizer. The [`Sidecar<T>`] slots are copied as
2753    /// R objects (after flushing the source's pending values), so the two
2754    /// pointers share those values until one side writes a field: every
2755    /// write replaces the slot, and R copies a shared value before modifying
2756    /// it in place. For a type with `Sidecar` fields this runs on R's main
2757    /// thread only.
2758    ///
2759    /// # Panics
2760    ///
2761    /// With the R error of class `miniextendr_borrow_conflict` while the value
2762    /// is borrowed mutably, like [`borrow`](Self::borrow).
2763    #[inline]
2764    fn clone(&self) -> Self {
2765        let value = self.borrow();
2766        if T::R_SLOT_COUNT == 0 {
2767            return Self::new(T::clone(&value));
2768        }
2769        assert_sidecar_clone_on_main_thread::<T>();
2770        // SAFETY: on R's main thread; `self.sexp` is the live pointer this
2771        // handle holds, built by `ExternalPtr` for a `T`.
2772        let prot = unsafe { R_ExternalPtrProtected(self.sexp) };
2773        flush_sidecars(&*value, prot);
2774        let new = Self::new(T::clone(&value));
2775        drop(value);
2776        // SAFETY: both pointers are live and built for a `T`.
2777        unsafe { copy_sidecar_slots::<T>(self.sexp, new.sexp) };
2778        new
2779    }
2780
2781    /// Clones `source`'s value into this pointer's value in place. The
2782    /// [`Sidecar<T>`] slots are copied as R objects like in
2783    /// [`clone`](Self::clone), replacing this pointer's slot values and its
2784    /// pending values.
2785    ///
2786    /// # Panics
2787    ///
2788    /// With the R error of class `miniextendr_borrow_conflict` while
2789    /// `source`'s value is borrowed mutably or this one's is borrowed, which
2790    /// includes cloning a pointer into itself.
2791    #[inline]
2792    fn clone_from(&mut self, source: &Self) {
2793        let from = source.borrow();
2794        let mut to = self.borrow_mut();
2795        if T::R_SLOT_COUNT == 0 {
2796            T::clone_from(&mut to, &from);
2797            return;
2798        }
2799        assert_sidecar_clone_on_main_thread::<T>();
2800        // SAFETY: as in `clone`.
2801        let source_prot = unsafe { R_ExternalPtrProtected(source.sexp) };
2802        flush_sidecars(&*from, source_prot);
2803        T::clone_from(&mut to, &from);
2804        discard_pending_sidecars(&*to);
2805        drop((from, to));
2806        // SAFETY: both pointers are live and built for a `T`.
2807        unsafe { copy_sidecar_slots::<T>(source.sexp, self.sexp) };
2808    }
2809}
2810
2811/// Copying `Sidecar` slots is R API.
2812fn assert_sidecar_clone_on_main_thread<T: TypedExternal>() {
2813    if !crate::is_r_main_thread() {
    {
        ::core::panicking::panic_fmt(format_args!("cloning an `ExternalPtr<{0}>` copies its sidecar slots, which runs on R\'s main thread only",
                T::TYPE_NAME));
    }
};assert!(
2814        crate::is_r_main_thread(),
2815        "cloning an `ExternalPtr<{}>` copies its sidecar slots, which runs on R's main thread only",
2816        T::TYPE_NAME
2817    );
2818}
2819
2820impl<T: TypedExternal + Default> Default for ExternalPtr<T> {
2821    /// Creates an ExternalPtr containing the default value of T.
2822    #[inline]
2823    fn default() -> Self {
2824        Self::new(T::default())
2825    }
2826}
2827
2828/// Like `RefCell`'s: a value borrowed mutably prints as `<borrowed>`
2829/// instead of raising, and so does a type-erased `ExternalPtr<()>`, which has
2830/// no value of its own.
2831impl<T: TypedExternal + fmt::Debug> fmt::Debug for ExternalPtr<T> {
2832    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2833        if is_type_erased::<T>() {
2834            return f.write_str("<erased>");
2835        }
2836        match self.cell().try_borrow() {
2837            Ok(value) => fmt::Debug::fmt(&*value, f),
2838            Err(_) => f.write_str("<borrowed>"),
2839        }
2840    }
2841}
2842
2843/// Borrows the value, like [`ExternalPtr::borrow`].
2844impl<T: TypedExternal + fmt::Display> fmt::Display for ExternalPtr<T> {
2845    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2846        fmt::Display::fmt(&*self.borrow(), f)
2847    }
2848}
2849
2850impl<T: TypedExternal> fmt::Pointer for ExternalPtr<T> {
2851    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2852        fmt::Pointer::fmt(&Self::as_ptr(self), f)
2853    }
2854}
2855
2856/// Compares the values, borrowing both, like [`ExternalPtr::borrow`].
2857impl<T: TypedExternal + PartialEq> PartialEq for ExternalPtr<T> {
2858    #[inline]
2859    fn eq(&self, other: &Self) -> bool {
2860        *self.borrow() == *other.borrow()
2861    }
2862}
2863
2864impl<T: TypedExternal + Eq> Eq for ExternalPtr<T> {}
2865
2866impl<T: TypedExternal + PartialOrd> PartialOrd for ExternalPtr<T> {
2867    #[inline]
2868    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
2869        (*self.borrow()).partial_cmp(&*other.borrow())
2870    }
2871}
2872
2873impl<T: TypedExternal + Ord> Ord for ExternalPtr<T> {
2874    #[inline]
2875    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
2876        (*self.borrow()).cmp(&*other.borrow())
2877    }
2878}
2879
2880impl<T: TypedExternal + Hash> Hash for ExternalPtr<T> {
2881    #[inline]
2882    fn hash<H: Hasher>(&self, state: &mut H) {
2883        (*self.borrow()).hash(state);
2884    }
2885}
2886
2887/// Each step borrows the value mutably, like [`ExternalPtr::borrow_mut`].
2888impl<T: TypedExternal + std::iter::Iterator> std::iter::Iterator for ExternalPtr<T> {
2889    type Item = T::Item;
2890
2891    fn next(&mut self) -> Option<Self::Item> {
2892        self.borrow_mut().next()
2893    }
2894
2895    fn size_hint(&self) -> (usize, Option<usize>) {
2896        self.borrow().size_hint()
2897    }
2898
2899    fn nth(&mut self, n: usize) -> Option<Self::Item> {
2900        self.borrow_mut().nth(n)
2901    }
2902}
2903
2904impl<T: TypedExternal + std::iter::DoubleEndedIterator> std::iter::DoubleEndedIterator
2905    for ExternalPtr<T>
2906{
2907    fn next_back(&mut self) -> Option<Self::Item> {
2908        self.borrow_mut().next_back()
2909    }
2910
2911    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
2912        self.borrow_mut().nth_back(n)
2913    }
2914}
2915
2916impl<T: TypedExternal + std::iter::ExactSizeIterator> std::iter::ExactSizeIterator
2917    for ExternalPtr<T>
2918{
2919    fn len(&self) -> usize {
2920        self.borrow().len()
2921    }
2922}
2923
2924impl<T: TypedExternal + std::iter::FusedIterator> std::iter::FusedIterator for ExternalPtr<T> {}
2925
2926impl<T: TypedExternal> From<T> for ExternalPtr<T> {
2927    #[inline]
2928    fn from(t: T) -> Self {
2929        Self::new(t)
2930    }
2931}
2932
2933impl<T: TypedExternal> From<Box<T>> for ExternalPtr<T> {
2934    #[inline]
2935    fn from(boxed: Box<T>) -> Self {
2936        unsafe { Self::from_raw(Box::into_raw(boxed)) }
2937    }
2938}
2939
2940// `Drop` releases the R-side GC root taken at construction (for *owning*
2941// handles only) but never frees the pointee — that stays R's job, run by the
2942// `release_any` finalizer when R garbage-collects the `EXTPTRSXP`. Dropping the
2943// root just makes the object eligible for collection once R itself holds no
2944// other reference; if R still references it (the usual case — it was returned
2945// from a `.Call` or stored), it stays alive and the finalizer runs later.
2946//
2947// For deterministic *value* cleanup, use `ExternalPtr::into_inner` (moves the
2948// value out) or `drop(Box::from_raw(ExternalPtr::into_raw(ptr)))`.
2949impl<T: TypedExternal> Drop for ExternalPtr<T> {
2950    fn drop(&mut self) {
2951        self.release_root_if_owned();
2952    }
2953}
2954// endregion
2955
2956// region: Finalizer
2957
2958/// Guard that aborts the process if a panic starts while it is alive.
2959///
2960/// Used by [`drop_catching_panic`] to implement panic-safe destructor calls
2961/// without `catch_unwind`. When `f()` completes normally, the guard is
2962/// dropped with `std::thread::panicking()` unchanged and becomes a no-op.
2963/// If `f()` panics, the guard's destructor runs during stack unwinding
2964/// (when `std::thread::panicking()` has become `true`) and calls
2965/// `process::abort()`.
2966///
2967/// A destructor can also run *because* of an unrelated panic: a handle that
2968/// goes out of scope in a panicking `#[miniextendr]` fn is dropped by that
2969/// unwind, with `panicking()` already `true`. That is not a panic in the
2970/// destructor, so the guard records the state it started in and aborts only
2971/// on a change. (A panic in `f()` while already unwinding is a double panic,
2972/// which the Rust runtime aborts on by itself.)
2973///
2974/// This approach avoids `catch_unwind`, which registers LLVM unwind landing
2975/// pads. Inside R's GC finalizer walk, any interaction with the unwinding
2976/// machinery — especially on the first call that lazily initialises exception
2977/// handling state — can trigger an allocator call that re-enters R's GC and
2978/// produces a "recursive gc invocation" hard crash.
2979#[must_use]
2980struct AbortIfUnwinding {
2981    /// `std::thread::panicking()` when the guard was created.
2982    already_unwinding: bool,
2983}
2984
2985impl AbortIfUnwinding {
2986    #[inline]
2987    fn new() -> Self {
2988        AbortIfUnwinding {
2989            already_unwinding: std::thread::panicking(),
2990        }
2991    }
2992}
2993
2994impl Drop for AbortIfUnwinding {
2995    #[cold]
2996    fn drop(&mut self) {
2997        if !self.already_unwinding && std::thread::panicking() {
2998            // A panic propagated through a finalizer — abort immediately.
2999            // The value being dropped is in an indeterminate state; continuing
3000            // is not safe.
3001            {
    ::std::io::_eprint(format_args!("miniextendr: destructor panicked during R finalization; aborting\n"));
};eprintln!("miniextendr: destructor panicked during R finalization; aborting");
3002            std::process::abort();
3003        }
3004    }
3005}
3006
3007/// Run a destructor closure, aborting the process if the closure panics.
3008///
3009/// A panic inside a GC finalizer cannot be safely propagated: the finalizer
3010/// runs at an arbitrary point in R's garbage collector, and unwinding across
3011/// the C-ABI boundary into R's runtime is undefined behaviour. Aborting is
3012/// the only safe recovery strategy — the destructor has already left the
3013/// value in an indeterminate state, so continuing is not an option.
3014///
3015/// ## Implementation note
3016///
3017/// This function deliberately avoids `std::panic::catch_unwind`. On the first
3018/// call from within R's GC finalizer, `catch_unwind` may lazily initialise
3019/// LLVM exception-handling state, which can allocate. Any allocation during a
3020/// GC finalizer re-enters the GC and triggers the fatal "recursive gc
3021/// invocation" crash. Instead, this function uses a drop-guard that compares
3022/// `std::thread::panicking()` — a cheap, allocation-free TLS read — on entry
3023/// and on exit.
3024///
3025/// Called from a `Drop` that an unrelated panic's unwind is running, it runs
3026/// `f()` and returns: the unwind continues and reaches its `catch_unwind`
3027/// boundary (for a `#[miniextendr]` fn, the R error it becomes).
3028///
3029/// Deferred conditions queued by this destructor (including nested guards)
3030/// are suppressed on this thread. Finalization has no caller handlers to
3031/// receive them, and retaining them would strand or misattribute diagnostics.
3032///
3033/// This helper is `#[doc(hidden)]` because it is called from macro-generated
3034/// code and is not part of the public API.
3035#[doc(hidden)]
3036#[inline]
3037pub fn drop_catching_panic<F: FnOnce()>(f: F) {
3038    let _guard = AbortIfUnwinding::new();
3039    let _conditions = crate::deferred_condition::Suppress::new();
3040    f();
3041    // guard dropped here with panicking() unchanged → no-op
3042}
3043
3044/// Non-generic C finalizer called by R's garbage collector.
3045///
3046/// Since `ExternalPtr` stores `Box<Box<dyn Any>>`, the `Any` vtable carries
3047/// the concrete type's drop function. No generic parameter needed — one
3048/// finalizer function handles all `ExternalPtr<T>` types.
3049extern "C-unwind" fn release_any(sexp: SEXP) {
3050    if sexp.is_null_or_nil() {
3051        return;
3052    }
3053
3054    let any_raw = unsafe { R_ExternalPtrAddr(sexp) as *mut Box<dyn Any> };
3055
3056    // Guard against double-finalization
3057    if any_raw.is_null() {
3058        return;
3059    }
3060
3061    // Clear the external pointer first (prevents double-free if called again)
3062    unsafe { R_ClearExternalPtr(sexp) };
3063
3064    // Reconstruct the outer Box<Box<dyn Any>> and let it drop.
3065    // This drops the outer Box, then the inner Box<dyn Any>, which
3066    // uses the vtable to drop the concrete T value.
3067    //
3068    // A panicking Drop impl must not unwind across the C-ABI boundary into R.
3069    // `drop_catching_panic` catches any panic and aborts instead.
3070    drop_catching_panic(|| drop(unsafe { Box::from_raw(any_raw) }));
3071}
3072
3073/// The finalizer of a type with cached fields (`#[r_data(cache)]`, #2271):
3074/// drops the value's cached field values, then frees the value as
3075/// [`release_any`] does, so no later value at the same address finds them.
3076/// Releasing pool slots allocates nothing, so this is sound in a finalizer.
3077extern "C-unwind" fn release_cached(sexp: SEXP) {
3078    if !sexp.is_null_or_nil() {
3079        let any_raw = unsafe { R_ExternalPtrAddr(sexp) }.cast::<Box<dyn Any>>();
3080        if !any_raw.is_null() {
3081            // SAFETY: a live address of a pointer `ExternalPtr` built holds
3082            // the `Box<dyn Any>` this finalizer frees.
3083            field_cache::forget(field_cache::stored_key(&**unsafe { &*any_raw }));
3084        }
3085    }
3086    release_any(sexp);
3087}
3088
3089/// The finalizer `T`'s pointers register: [`release_cached`] for a type with
3090/// cached fields, else [`release_any`]. A constant choice per type.
3091#[inline]
3092fn finalizer<T: TypedExternal>() -> crate::R_CFinalizer_t {
3093    if T::CACHED_FIELD_COUNT > 0 {
3094        Some(release_cached)
3095    } else {
3096        Some(release_any)
3097    }
3098}
3099// endregion
3100
3101// region: Utility: ExternalSlice (helper for slice data)
3102
3103/// A slice stored as a standalone struct, suitable for wrapping in ExternalPtr.
3104///
3105/// This is analogous to the data inside a `Box<[T]>`, but stores capacity
3106/// for proper deallocation when created from a `Vec`.
3107///
3108/// # Usage
3109///
3110/// To use with `ExternalPtr`, implement `TypedExternal` for your specific
3111/// `ExternalSlice<YourType>`:
3112///
3113/// ```ignore
3114/// impl_typed_external!(ExternalSlice<MyElement>);
3115/// let ptr = ExternalPtr::new(ExternalSlice::new(vec![1, 2, 3]));
3116/// ```
3117#[repr(C)]
3118pub struct ExternalSlice<T: 'static> {
3119    ptr: NonNull<T>,
3120    len: usize,
3121    capacity: usize,
3122}
3123
3124impl<T: 'static> ExternalSlice<T> {
3125    /// Create an external slice from a `Vec`, preserving its allocation.
3126    pub fn new(slice: Vec<T>) -> Self {
3127        let mut vec = ManuallyDrop::new(slice);
3128        Self {
3129            ptr: unsafe { NonNull::new_unchecked(vec.as_mut_ptr()) },
3130            len: vec.len(),
3131            capacity: vec.capacity(),
3132        }
3133    }
3134
3135    /// Create from a boxed slice (capacity == len).
3136    pub fn from_boxed(boxed: Box<[T]>) -> Self {
3137        let len = boxed.len();
3138        let ptr = Box::into_raw(boxed).cast();
3139        Self {
3140            ptr: unsafe { NonNull::new_unchecked(ptr) },
3141            len,
3142            capacity: len,
3143        }
3144    }
3145
3146    /// Borrow the contents as a shared slice.
3147    pub fn as_slice(&self) -> &[T] {
3148        unsafe { std::slice::from_raw_parts(self.ptr.as_ptr(), self.len) }
3149    }
3150
3151    /// Borrow the contents as a mutable slice.
3152    pub fn as_mut_slice(&mut self) -> &mut [T] {
3153        unsafe { std::slice::from_raw_parts_mut(self.ptr.as_ptr(), self.len) }
3154    }
3155
3156    /// Number of elements in the slice.
3157    pub fn len(&self) -> usize {
3158        self.len
3159    }
3160
3161    /// Returns true if the slice is empty.
3162    pub fn is_empty(&self) -> bool {
3163        self.len == 0
3164    }
3165
3166    /// Capacity of the underlying allocation.
3167    pub fn capacity(&self) -> usize {
3168        self.capacity
3169    }
3170}
3171
3172impl<T: 'static> Drop for ExternalSlice<T> {
3173    fn drop(&mut self) {
3174        unsafe {
3175            let _ = Vec::from_raw_parts(self.ptr.as_ptr(), self.len, self.capacity);
3176        }
3177    }
3178}
3179// endregion
3180
3181mod altrep_helpers;
3182pub use altrep_helpers::*;
3183
3184mod borrowed;
3185pub use borrowed::{ExternalPtrMut, ExternalPtrRef, SidecarOwner, SidecarOwnerMut};
3186
3187mod field_cache;
3188
3189mod sidecar;
3190pub use sidecar::*;
3191
3192mod snapshot;
3193pub use snapshot::DECODE_ERROR_CLASS;
3194#[doc(hidden)]
3195pub use snapshot::{
3196    Snapshot, SnapshotClass, SnapshotNone, SnapshotProbe, SnapshotSerde,
3197    register as __mx_register_snapshot,
3198};
3199
3200#[cfg(test)]
3201mod tests;