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(Debug, Clone, Copy, PartialEq, 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 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 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 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(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) => format!("{message} (its saved value could not be read: {cause})"),
569 None => 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 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 _ => panic!("the stored type ID has no version"),
635 };
636 let rewritten = std::ffi::CString::new(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 panic!("the stored type ID has no version")
681 };
682 let rewritten = std::ffi::CString::new(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 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 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
1292thread_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 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 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 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 assert!(!any_raw.is_null(), "ExternalPtr is null or cleared");
1835 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 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 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 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 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 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 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 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 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 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(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 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 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 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 assert!(
2558 !any_raw.is_null(),
2559 "restore_after_consuming on a null external pointer"
2560 );
2561 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(Debug, 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 => write!(f, "external pointer is null"),
2659 Self::InvalidTypeId => write!(f, "external pointer has no valid type id"),
2660 Self::Mismatch { expected, found } => {
2661 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 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 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;