miniextendr_api/externalptr/

sidecar.rs

//! Typed sidecar fields: [`Sidecar<T>`] keeps a Rust-typed value in the
//! external pointer's `prot` list.
//!
//! A Rust struct cannot root an R value: the GC doesn't trace Rust memory, so
//! a `SEXP` stored in a struct field is freed as soon as R drops its own
//! references. A `Sidecar<T>` field holds no data of its own once the struct
//! is wrapped. Its value lives in the external pointer's protection list,
//! after the type ID and the user slot, so the pointer roots it for as long as
//! the pointer is reachable, and `saveRDS()` writes it with the pointer. The
//! struct holds nothing that points back at its pointer: the value is read
//! and written through the `ExternalPtr<T>` handle, which keeps the pointer
//! alive for as long as it exists (#1856).
//!
//! The type is named in one place (this module) and re-exported from
//! [`crate::externalptr`]; its final name is #1857.

use std::any::{Any, TypeId};
use std::cell::{Ref, RefCell, RefMut};
use std::collections::HashMap;
use std::fmt;
use std::marker::PhantomData;
use std::sync::Arc;

use super::{
    NO_HANDLE_CLASS, PROT_TYPE_ID_INDEX, PROT_VEC_LEN, TypedExternal, receiver_class,
    refuse_restored, unwrap_class_handle,
};
use crate::condition::{ConditionCall, RCondition};
use crate::from_r::TryFromSexp;
use crate::into_r::IntoR;
use crate::sys::{R_ExternalPtrAddr, R_ExternalPtrProtected};
use crate::{R_xlen_t, SEXP, SEXPTYPE, SexpExt};

// region: Sidecar<T>

/// A sidecar field whose value R roots: it lives in the external pointer's
/// protection list, typed as `T` on the Rust side.
///
/// Declare it as `#[r_data] pub keys: Sidecar<Vec<i32>>` on a
/// `#[derive(ExternalPtr)]` struct. The derive generates accessors as
/// associated functions of the struct, with the field's visibility. They take
/// an owner handle, which keeps the pointer alive, not the struct:
///
/// | `#[r_data(...)]` | Rust accessors |
/// |---|---|
/// | `ref` | `fn keys(ptr: &impl SidecarOwner<Self>) -> T` |
/// | `mut` | `fn set_keys(ptr: &mut impl SidecarOwnerMut<Self>, value: T)` |
/// | `ref, mut`, or a bare `#[r_data]` | both |
///
/// Rust code sees no `SEXP`s, slot indices or other R plumbing: a plain
/// `fn new() -> Self` constructor fills the field with [`Sidecar::new`], and
/// a method that needs the value takes a view as its receiver
/// (`self: ExternalPtrRef<'_, Self>` / `mut self: ExternalPtrMut<'_, Self>`)
/// and calls `Self::keys(&self)` / `Self::set_keys(&mut self, v)`; other Rust
/// code writes `Engine::keys(&ptr)`. The R side keeps its own accessors whatever the
/// option: for a `pub` field, `Type_get_keys(x)` / `Type_set_keys(x, value)`,
/// an R6 active binding (`r6(r_data_accessors)`), an S7 property
/// (`s7(r_data_accessors)`), or `x$keys` / `x$keys <- value` on an S3, S4 or
/// env class (`s3(r_data_accessors)` & co.). The R setter validates the new
/// value with `TryFromSexp::<T>` and stores the value R gave.
///
/// ```ignore
/// #[derive(ExternalPtr)]
/// #[externalptr(r6)]
/// pub struct Engine {
///     n: i32,
///     #[r_data] _r: RSidecar,
///     #[r_data(ref, mut)] pub keys: Sidecar<Vec<i32>>,
///     #[r_data(ref)] pub labels: Sidecar<Vec<String>>,
///     #[r_data(ref, mut)] cache: Sidecar<Option<List>>,
/// }
///
/// #[miniextendr(r6(r_data_accessors))]
/// impl Engine {
///     pub fn new(n: i32) -> Self {
///         Engine {
///             n,
///             _r: RSidecar,
///             keys: Sidecar::new((1..=n).collect()),
///             labels: Sidecar::new(vec![]),
///             cache: Sidecar::default(),
///         }
///     }
///     pub fn key_count(self: ExternalPtrRef<'_, Self>) -> usize { Self::keys(&self).len() }
///     pub fn remember(mut self: ExternalPtrMut<'_, Self>, value: List) {
///         Self::set_cache(&mut self, Some(value))
///     }
/// }
///
/// // From any other Rust code holding the handle:
/// let mut ptr = ExternalPtr::new(Engine::new(3));
/// Engine::set_keys(&mut ptr, vec![9]);
/// assert_eq!(Engine::keys(&ptr), vec![9]);
/// ```
///
/// The accessors take [`super::ExternalPtrRef`] / [`super::ExternalPtrMut`]
/// views (receivers, arguments, `borrow()` / `borrow_mut()`) or an
/// `ExternalPtr`, which they borrow for the call: shared for the getter,
/// exclusive for the setter. A plain `&self` receiver has no route back to
/// an R owner.
///
/// # Values
///
/// - `T: IntoR + TryFromSexp`, with `T::Error: Display` for the getter's panic
///   message.
/// - A getter converts the slot with `TryFromSexp`, so a converting type
///   (`Vec<i32>`, `String`) copies on every read. A conversion failure is a
///   panic naming the field and the type; the framework turns it into an R
///   error.
/// - `Sidecar<SEXP>`, `Sidecar<List>` and `Sidecar<DataFrame>` keep an
///   arbitrary R object unconverted. The getter returns a view that the slot
///   roots only until the next write to that field; don't hold it across one.
/// - [`Sidecar::new`] and [`Sidecar::replace`] convert their value with
///   `IntoR` at once and root the R object it gives until a slot holds it
///   (#2216). A fresh `SEXP` or list passed to them is safe from that moment;
///   it needs its own protection only before the call.
///
/// # Lifecycle
///
/// - **Pending.** [`Sidecar::new(v)`](Sidecar::new) and [`Default`]
///   (`Sidecar::new(T::default())`) convert `v` to its R object and hold it
///   as a pending value in the struct, rooted in a main-thread pool until a
///   slot holds it or the last copy drops. That is the only state a `Sidecar`
///   has: before the struct is wrapped, after `*ptr = Engine::new(..)`, after
///   `ExternalPtr::into_inner`. They run on R's main thread, or on the
///   managed worker, which hands the conversion to the main thread as
///   `ExternalPtr::new` does; any other thread panics. Like an owning
///   `ExternalPtr`, the last copy of a pending value must be dropped on R's
///   main thread or its managed worker.
/// - **Flushed when wrapped.** `ExternalPtr::new` and the trait ABI's `mx_wrap`
///   move every pending value into the pointer's protection list. From then
///   on the value lives in R only, and the field is empty.
/// - **Flushed on every access to the field.** The handle getter and setter,
///   and the R getter and setter, first move that field's pending value into
///   its slot (the setters drop it: the write supersedes it). So
///   `*ptr.borrow_mut() = Engine::new(..)` or
///   `ptr.borrow_mut().keys = Sidecar::new(v)` takes effect at the next
///   access from either side. A
///   `saveRDS()` before any access writes the old slot value.
/// - **Loaded when the value leaves its pointer.** `ExternalPtr::into_inner`
///   and `into_raw` read each slot of the pointer being consumed back into its
///   field as a pending value (unless one is pending already), rooted as a
///   new one is, so wrapping the value again keeps the values.
/// - **A `self -> Self` method** leaves the values in the pointer across the
///   call; the write-back flushes only what the method set with
///   `Sidecar::new`. `Self { n: .., ..self }` keeps the values,
///   `Self::new(..)` replaces them.
/// - **Clone.** `Sidecar::clone` shares the pending R object and its root,
///   which is none once the struct is wrapped. `ExternalPtr::clone` and
///   `clone_from` copy the slot values as R objects, so the two pointers
///   share them until one side writes the field: every write replaces the
///   slot, and R copies a shared value before modifying it in place. A struct
///   cloned outside its handle carries no sidecar values; clone the handle.
/// - **`*ptr = new` and `mem::swap(&mut *a, &mut *b)`** are plain Rust
///   moves. The sidecar values stay in each pointer's protection list; only
///   pending values travel with the struct.
/// - **After `readRDS()`** there is no Rust value. The standalone R
///   accessors (`Type_get_f()` / `Type_set_f()`), the R6 active bindings and
///   the S7 properties read and write the protection list directly, checked
///   by the type ID stored with it. The `$` / `[[` / `$<-` / `[[<-` field
///   methods of `s3(r_data_accessors)` & co. refuse the restored pointer
///   instead, with the classed restored-object errors: they pass
///   `require_live` to the same accessor (#1891).
///
/// Use the accessors on R's main thread only. Off the main thread an
/// accessor panics with a clear message before it touches R.
///
/// # A save names the values by their R names
///
/// A saved object (`saveRDS()`, `serialize()`) stores one slot per `Sidecar`
/// field, named after the field's R name: the `#[r_data(name = "..")]` value,
/// else the Rust field name (#2187, #2215). After a reload, the standalone R
/// accessors, the R6 bindings, the S7 properties and a rebuild hook
/// (`#[externalptr(rebuild = path)]`, through [`super::Saved`]) find each
/// field's slot by that name. So the R name is the save format:
///
/// - Reordering, adding or removing `Sidecar` fields keeps earlier saves
///   readable. A field the save has no slot for raises the classed
///   [`RESTORED_MISSING_SLOT_CLASS`](super::RESTORED_MISSING_SLOT_CLASS)
///   error (or reads as `None` through a hook's `Self::try_<field>(saved)`).
/// - Renaming the Rust field keeps them readable too, as long as the R name
///   stays: a field without `name = ..` keeps its old ident as
///   `#[r_data(name = "old")]`.
/// - Renaming the R name orphans the field's slot in every earlier save: the
///   field reads as one the save lacks.
/// - Retyping a field keeps its name, so an earlier save's slot is read as the
///   new type; a getter that can't convert it panics naming the field.
///
/// A save from another version of the crate (the `version` in its
/// `Cargo.toml`, which the stored type ID records) is refused with the classed
/// `miniextendr_restored_other_version` error (#1872), unless the type
/// rebuilds it (`rebuild = path, any_version`).
///
/// # Methods that need sidecar values take a view
///
/// A `&self` / `&mut self` method sees the struct, which holds no reference
/// to its pointer, so it can't reach the values. Take a view instead:
/// `self: ExternalPtrRef<'_, Self>` to read, `mut self: ExternalPtrMut<'_, Self>`
/// to write (`Deref` still gives the struct fields). The same holds for a
/// struct moved out of its pointer through `&mut` (`mem::replace`,
/// `mem::take`): it carries nothing to follow, so nothing can read a freed R
/// object (#1856). A trait method takes its owner as
/// `self: ExternalPtrRef<'_, Self>` or `self: ExternalPtrMut<'_, Self>`
/// ([`ExternalPtrRef`](crate::ExternalPtrRef)), over an `ExternalPtr` or a
/// trait-ABI object, and passes it to the same accessors. A `&self` trait
/// method, such as one of a standard trait with a fixed signature, and the
/// high-level ALTREP data traits receive only the struct (#1880).
/// ALTREP derives also accept `#[r_data] Sidecar<T>` fields: with
/// `#[altrep(manual, no_lowlevel)]`, low-level callbacks recover the handle
/// through [`crate::altrep_data1_as_unchecked`] and call the associated
/// accessors. Those derives emit no R class field wrappers.
///
/// A plain `SEXP` field under `#[r_data]` is a compile error: nothing would
/// root it. Use `Sidecar<SEXP>`.
pub struct Sidecar<T> {
    /// The value the field holds while it is not in a pointer's slot.
    pending: RefCell<Option<Pending>>,
    /// The field's type: its accessors convert the slot to it, and the
    /// struct's auto traits follow it as if it held a `T`.
    _value: PhantomData<T>,
}

/// A value on its way into a slot: its R object, rooted from the moment the
/// `Sidecar` holds it until a slot owns the GC edge (#2216).
#[derive(Clone)]
struct Pending {
    sexp: SEXP,
    root: Arc<PendingRoot>,
    /// Made by [`Sidecar::replace`]: in a struct a rebuild hook returns, the
    /// value replaces the slot the save kept (#2187).
    replace: bool,
}

/// Only the pool key crosses threads, as with an owning `ExternalPtr`.
/// Cloning a pending value needs no R call; the last copy releases the root.
struct PendingRoot(crate::protect_pool::ProtectKey);

impl Drop for PendingRoot {
    fn drop(&mut self) {
        let key = self.0;
        crate::worker::with_r_thread(move || super::unroot_owned(key));
    }
}

impl<T: IntoR + 'static> Sidecar<T> {
    /// A sidecar field holding `value`, pending until the struct is wrapped
    /// in an `ExternalPtr`.
    ///
    /// Converts `value` with `IntoR` and roots the R object until a slot
    /// holds it, so a fresh R value is safe from here on.
    ///
    /// # Panics
    ///
    /// Off R's main thread and its managed worker, before converting; or
    /// when the conversion fails.
    pub fn new(value: T) -> Self {
        Self::pending(value, false)
    }

    /// A sidecar field holding `value`, which replaces the slot a save kept
    /// when a rebuild hook (`#[externalptr(rebuild = path)]`) returns it.
    ///
    /// A rebuilt object keeps each slot its save has: the hook's
    /// [`Sidecar::new`] values are placeholders for those fields, and fill only
    /// the fields the save lacks. A hook that recomputes a field's value, and
    /// wants the object to hold the new value rather than the saved one,
    /// returns it as `Sidecar::replace(value)`. Anywhere else it is
    /// `Sidecar::new(value)`. Converts and roots `value` as
    /// [`Sidecar::new`] does, with the same panics.
    pub fn replace(value: T) -> Self {
        Self::pending(value, true)
    }

    /// Converts `value` and roots its R object on R's main thread: inline
    /// there, through the main thread from the managed worker (#2216).
    fn pending(value: T, replace: bool) -> Self {
        assert!(
            crate::worker::is_r_main_thread() || crate::worker::has_worker_context(),
            "`Sidecar::{}` converts its value on R's main thread: call it there or on \
             the managed worker, not from a thread the package spawned",
            if replace { "replace" } else { "new" },
        );
        // `root_owned` roots the fresh object across the pool's growth.
        let (sexp, key) = crate::worker::with_r_thread(move || {
            let sexp = value.into_sexp();
            (sexp, super::root_owned(sexp))
        });
        Self {
            pending: RefCell::new(Some(Pending {
                sexp,
                root: Arc::new(PendingRoot(key)),
                replace,
            })),
            _value: PhantomData,
        }
    }
}

impl<T> Sidecar<T> {
    /// Whether the pending value was made by [`Sidecar::replace`].
    fn replaces_saved(&self) -> bool {
        self.pending
            .borrow()
            .as_ref()
            .is_some_and(|pending| pending.replace)
    }

    /// Drops a pending value, which a write to the slot supersedes.
    fn discard_pending(&self) {
        *self.pending.borrow_mut() = None;
    }

    /// Moves a pending value into slot `index` of `prot`, if there is one.
    /// On R's main thread; `set_vector_elt` allocates nothing.
    fn flush_into(&self, prot: SEXP, index: usize) {
        let Some(Pending { sexp, root, .. }) = self.pending.borrow_mut().take() else {
            return;
        };
        prot.set_vector_elt(prot_index(index), sexp);
        // The slot owns the GC edge now.
        drop(root);
    }

    /// Reads slot `index` of `prot` back into the field as its pending value,
    /// unless one is pending already. On R's main thread.
    fn load_from(&self, prot: SEXP, index: usize) {
        if self.pending.borrow().is_some() {
            return;
        }
        // The old owner still roots the slot while the pool grows. Root the
        // slot itself, not the old protection list, so independent pending
        // fields do not retain one another's values.
        let sexp = prot.vector_elt(prot_index(index));
        *self.pending.borrow_mut() = Some(Pending {
            sexp,
            root: Arc::new(PendingRoot(super::root_owned(sexp))),
            replace: false,
        });
    }
}

impl<T> Clone for Sidecar<T> {
    /// A `Sidecar` sharing this field's pending R object, and its root, if
    /// any. The value in a pointer's slot is not copied: clone the
    /// `ExternalPtr`.
    fn clone(&self) -> Self {
        Self {
            pending: RefCell::new(self.pending.borrow().clone()),
            _value: PhantomData,
        }
    }
}

impl<T: Default + IntoR + 'static> Default for Sidecar<T> {
    /// `Sidecar::new(T::default())`.
    fn default() -> Self {
        Self::new(T::default())
    }
}

impl<T> fmt::Debug for Sidecar<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Sidecar")
            .field("pending", &self.pending.borrow().is_some())
            .finish()
    }
}

/// The element of `prot` at `at`, the slot of `Sidecar` field `name`,
/// converted to `T`.
fn convert_slot<T: TryFromSexp>(prot: SEXP, at: R_xlen_t, name: &str, owner_type: &str) -> T
where
    <T as TryFromSexp>::Error: fmt::Display,
{
    let slot = prot.vector_elt(at);
    match T::try_from_sexp(slot) {
        Ok(value) => value,
        Err(err) => panic!(
            "sidecar field `{name}` of `{owner_type}` holds an R value that does not convert to `{}`: {err}",
            std::any::type_name::<T>(),
        ),
    }
}

/// Panics unless this is R's main thread. No R API: the message names the
/// field and the owning type.
fn assert_main_thread(name: &str, owner_type: &str) {
    if !crate::worker::is_r_main_thread() {
        panic!(
            "sidecar field `{name}` of `{owner_type}`: its accessors run on R's main thread only; \
             this call came from another thread (a `worker` method, or a thread the \
             package spawned)",
        );
    }
}

// endregion

// region: The handle's view of the fields

/// A `Sidecar<T>` field, as the handle sees it through the
/// `TypedExternal::__mx_visit_sidecars` hook the derive emits. Every method
/// runs on R's main thread.
#[doc(hidden)]
pub trait SidecarField {
    /// Moves a pending value into slot `index` of `prot`.
    fn __mx_flush(&self, prot: SEXP, index: usize);
    /// Reads slot `index` of `prot` back into the field as its pending value,
    /// unless one is pending already.
    fn __mx_load(&self, prot: SEXP, index: usize);
    /// Drops a pending value, which a write to the slot supersedes.
    fn __mx_discard_pending(&self);
    /// Whether the pending value was made by [`Sidecar::replace`].
    fn __mx_replaces_saved(&self) -> bool;
}

impl<T> SidecarField for Sidecar<T> {
    fn __mx_flush(&self, prot: SEXP, index: usize) {
        self.flush_into(prot, index);
    }

    fn __mx_load(&self, prot: SEXP, index: usize) {
        self.load_from(prot, index);
    }

    fn __mx_discard_pending(&self) {
        self.discard_pending();
    }

    fn __mx_replaces_saved(&self) -> bool {
        self.replaces_saved()
    }
}

/// Moves every pending value of `value`'s `Sidecar` fields into its slot of
/// `prot`, the protection list of the pointer holding `value`. On R's main
/// thread.
pub(crate) fn flush_sidecars<T: TypedExternal>(value: &T, prot: SEXP) {
    value.__mx_visit_sidecars(&mut |index, _, field| field.__mx_flush(prot, index));
}

/// Reads every slot of `prot`, the protection list of the pointer `value` is
/// leaving, back into its `Sidecar` field as a pending value (unless one is
/// pending already). On R's main thread.
pub(crate) fn load_sidecars<T: TypedExternal>(value: &T, prot: SEXP) {
    value.__mx_visit_sidecars(&mut |index, _, field| field.__mx_load(prot, index));
}

/// Drops every pending value of `value`'s `Sidecar` fields.
pub(crate) fn discard_pending_sidecars<T: TypedExternal>(value: &T) {
    value.__mx_visit_sidecars(&mut |_, _, field| field.__mx_discard_pending());
}

/// Flushes a freshly wrapped value's pending values into its pointer's
/// protection list: the three construction sites and
/// `restore_after_consuming` call this once the `EXTPTRSXP` exists.
///
/// # Safety
///
/// On R's main thread; `any_raw` must own a `RefCell<T>`, and `owner` must be
/// the live `EXTPTRSXP` holding it, with a `prot` list built by `ExternalPtr`.
pub(super) unsafe fn init_sidecars<T: TypedExternal>(any_raw: *mut Box<dyn Any>, owner: SEXP) {
    let value = unsafe { &*any_raw }
        .downcast_ref::<RefCell<T>>()
        .expect("ExternalPtr stores a T at construction")
        .borrow();
    let prot = unsafe { R_ExternalPtrProtected(owner) };
    unsafe { name_slots::<T>(prot) };
    flush_sidecars(&*value, prot);
}

/// Initializes the slots of a trait-ABI owner using the ordinary sidecar
/// layout and visitation hook. The Rust allocation remains erased storage;
/// it must never be wrapped as `ExternalPtr<T>` (which expects `Any` storage).
///
/// # Safety
/// On R's main thread inside an R unwind boundary. `owner` must be the
/// caller-rooted external pointer owning `value`, with its finalizer already
/// registered.
pub(crate) unsafe fn init_erased_sidecars<T: TypedExternal>(value: &T, owner: SEXP) {
    unsafe {
        let type_id = super::type_id_symbol_unchecked::<T>();
        let prot =
            crate::sys::Rf_allocVector_unchecked(SEXPTYPE::VECSXP, super::prot_vec_len::<T>());
        // Attach before the next allocation (the slot names' attribute cell):
        // the owner roots `prot` from here on.
        crate::sys::R_SetExternalPtrProtected_unchecked(owner, prot);
        prot.set_vector_elt_unchecked(PROT_TYPE_ID_INDEX, type_id);
        name_slots::<T>(prot);
        flush_sidecars(value, prot);
    }
}

/// Copies every `Sidecar` slot of the pointer `source` into the pointer
/// `target`: the two share the R values until one side writes a field.
///
/// # Safety
///
/// On R's main thread; both must be live `EXTPTRSXP`s built by `ExternalPtr`
/// for a `T`. `set_vector_elt` allocates nothing.
pub(super) unsafe fn copy_sidecar_slots<T: TypedExternal>(source: SEXP, target: SEXP) {
    let from = unsafe { R_ExternalPtrProtected(source) };
    let to = unsafe { R_ExternalPtrProtected(target) };
    for index in 0..T::R_SLOT_COUNT {
        let at = prot_index(index);
        to.set_vector_elt(at, from.vector_elt(at));
    }
}

/// Reads `T`'s `Sidecar` field `index` of the object `ptr` holds, after
/// moving the field's pending value into the slot.
///
/// Called by the getters `#[derive(ExternalPtr)]` generates
/// (`T::field(&ptr)`); `field` selects the struct's `Sidecar` field.
///
/// # Panics
///
/// Off R's main thread, naming the field, before touching R; or when the
/// slot does not convert to `T`.
#[doc(hidden)]
pub fn sidecar_get<O, T>(
    ptr: &impl super::SidecarOwner<O>,
    index: usize,
    name: &'static str,
    field: fn(&O) -> &Sidecar<T>,
) -> T
where
    O: TypedExternal,
    T: IntoR + TryFromSexp,
    <T as TryFromSexp>::Error: fmt::Display,
{
    assert_main_thread(name, O::TYPE_NAME);
    // SAFETY (both arms): on R's main thread; the handle's EXTPTRSXP is live
    // and was built for an `O`.
    match ptr.__mx_read() {
        super::SidecarRead::Live(value) => {
            let prot = unsafe { R_ExternalPtrProtected(super::ExternalPtrRef::as_sexp(&value)) };
            field(&value).flush_into(prot, index);
            convert_slot::<T>(prot, prot_index(index), name, O::TYPE_NAME)
        }
        // A rebuild hook reads what the save kept, by the field's name;
        // nothing is pending.
        super::SidecarRead::Saved(sexp) => {
            let prot = unsafe { R_ExternalPtrProtected(sexp) };
            match saved_slot(prot, index, name) {
                Some(at) => convert_slot::<T>(prot, at, name, O::TYPE_NAME),
                None => missing_slot::<O>(name),
            }
        }
    }
}

/// `T`'s `Sidecar` field `index`, named `name`, as the save `saved` kept it,
/// or `None` when the save has no slot for it: a field added after the
/// version that saved the object.
///
/// Called by the `try_<field>` getters `#[derive(ExternalPtr)]` generates for
/// a type with a rebuild hook.
///
/// # Panics
///
/// Off R's main thread, naming the field; or when the slot does not convert
/// to `T`.
#[doc(hidden)]
pub fn sidecar_try_saved<O, T>(
    saved: &super::Saved<'_, O>,
    index: usize,
    name: &'static str,
) -> Option<T>
where
    O: TypedExternal,
    T: TryFromSexp,
    <T as TryFromSexp>::Error: fmt::Display,
{
    assert_main_thread(name, O::TYPE_NAME);
    // SAFETY: on R's main thread; `saved` holds a live EXTPTRSXP.
    let prot = unsafe { R_ExternalPtrProtected(saved.as_sexp()) };
    saved_slot(prot, index, name).map(|at| convert_slot::<T>(prot, at, name, O::TYPE_NAME))
}

/// Stores `value` in `T`'s `Sidecar` field `index` of the object `ptr` holds,
/// dropping the field's pending value, which this write supersedes.
///
/// Called by the setters `#[derive(ExternalPtr)]` generates
/// (`T::set_field(&mut ptr, value)`); `field` selects the struct's `Sidecar`
/// field.
///
/// # Panics
///
/// Off R's main thread, naming the field, before touching R.
#[doc(hidden)]
pub fn sidecar_set<O, T>(
    ptr: &mut impl super::SidecarOwnerMut<O>,
    index: usize,
    name: &'static str,
    field: fn(&O) -> &Sidecar<T>,
    value: T,
) where
    O: TypedExternal,
    T: IntoR,
{
    assert_main_thread(name, O::TYPE_NAME);
    let target = ptr.__mx_write();
    // SAFETY: as in `sidecar_get`. Storing allocates nothing.
    let prot = unsafe { R_ExternalPtrProtected(super::ExternalPtrMut::as_sexp(&target)) };
    field(&target).discard_pending();
    prot.set_vector_elt(prot_index(index), value.into_sexp());
}

// endregion

// region: Slot names (#2187)

thread_local! {
    /// Each type's slot names, preserved for the session and shared by every
    /// protection list of the type: `""` for the type ID and the user slot,
    /// then the `Sidecar` fields' R names, in slot order.
    static SLOT_NAMES: RefCell<HashMap<TypeId, SEXP>> = RefCell::new(HashMap::new());
}

/// Names `prot`'s slots after `T`'s `Sidecar` fields. A save then keeps the
/// names, so the version that reads it finds each field by name
/// ([`saved_slot`]), whatever fields it added, removed or reordered since.
/// The names vector is the type's own, built once; this allocates only the
/// attribute's cell.
///
/// # Safety
///
/// On R's main thread, with `prot` a rooted protection list built for a `T`.
pub(crate) unsafe fn name_slots<T: TypedExternal>(prot: SEXP) {
    let cached = SLOT_NAMES.with_borrow(|names| names.get(&TypeId::of::<T>()).copied());
    let names = cached.unwrap_or_else(|| {
        // Preserved before it is filled, so the CHARSXPs it receives are
        // reachable as they are made.
        let names =
            unsafe { crate::sys::Rf_allocVector(SEXPTYPE::STRSXP, super::prot_vec_len::<T>()) };
        unsafe { crate::sys::R_PreserveObject(names) };
        for (index, name) in T::SIDECAR_NAMES.iter().enumerate() {
            names.set_string_elt(prot_index(index), SEXP::charsxp(name));
        }
        SLOT_NAMES.with_borrow_mut(|cache| cache.insert(TypeId::of::<T>(), names));
        names
    });
    prot.set_names(names);
}

/// The position in the saved protection list `prot` of `Sidecar` field
/// `index`, named `name`: found by name when the save carries slot names,
/// else by position (a save by this version made before slots were named).
/// `None` when the save has no slot for the field.
pub(crate) fn saved_slot(prot: SEXP, index: usize, name: &str) -> Option<R_xlen_t> {
    let names = prot.get_attr(SEXP::names_symbol());
    if names.type_of() == SEXPTYPE::STRSXP && names.xlength() == prot.xlength() {
        (PROT_VEC_LEN..names.xlength()).find(|&at| names.string_elt_str(at) == Some(name))
    } else {
        Some(prot_index(index)).filter(|&at| at < prot.xlength())
    }
}

/// Whether the saved protection list `prot` carries slot names.
pub(crate) fn has_slot_names(prot: SEXP) -> bool {
    let names = prot.get_attr(SEXP::names_symbol());
    names.type_of() == SEXPTYPE::STRSXP && names.xlength() == prot.xlength()
}

/// Raises the classed error for a read of `Sidecar` field `name` that a save
/// of an `O` has no slot for.
fn missing_slot<O: TypedExternal>(name: &str) -> ! {
    RCondition::Error {
        message: format!(
            "the saved `{}` has no `{name}` field: the version that saved it did not have it",
            O::TYPE_NAME
        ),
        class: vec![super::RESTORED_MISSING_SLOT_CLASS.to_owned()],
        data: Some(vec![(
            "field".to_owned(),
            crate::RValue::Character(vec![Some(name.to_owned())]),
        )]),
        call: ConditionCall::Inherit,
    }
    .raise()
}

// endregion

// region: The R accessors

/// The protection-list position of `Sidecar` field `index`.
pub(super) fn prot_index(index: usize) -> R_xlen_t {
    let index = R_xlen_t::try_from(index).expect("sidecar index exceeds R_xlen_t::MAX");
    PROT_VEC_LEN + index
}

/// Whether `sym` is the symbol of `T`'s type ID.
///
/// Compares names rather than installing `T`'s symbol, so it allocates nothing.
fn is_type_id_symbol<T: TypedExternal>(sym: SEXP) -> bool {
    if sym.type_of() != SEXPTYPE::SYMSXP {
        return false;
    }
    let id = T::TYPE_ID_CSTR
        .strip_suffix(b"\0")
        .unwrap_or(T::TYPE_ID_CSTR);
    let printname = sym.printname();
    // SAFETY: a CHARSXP's data holds `len` bytes.
    let name =
        unsafe { std::slice::from_raw_parts(printname.r_char().cast::<u8>(), printname.len()) };
    name == id
}

/// The external pointer an R accessor's receiver `x` carries: `x` itself, or
/// the pointer an R6 / S4 / S7 handle, an environment or a list holds in
/// `.ptr`, the shapes an instance method's receiver takes
/// ([`unwrap_class_handle`]). So `Type_get_f(x)` and the `$` / `[[` field
/// methods of `r_data_accessors` read a list that carries the handle (#1848).
/// A bare pointer costs one `TYPEOF` compare; an S4 receiver reads its `ptr`
/// slot through `methods::slot()`, which allocates. The pointer is reachable
/// from `x`, which the caller's `.Call()` frame roots.
///
/// # Panics
///
/// When `x` carries no external pointer, with the classed
/// [`NO_HANDLE_CLASS`] error ([`refuse_no_handle`]).
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`.
unsafe fn sidecar_receiver<T: TypedExternal>(x: SEXP) -> SEXP {
    if x.type_of() == SEXPTYPE::EXTPTRSXP {
        return x;
    }
    match unsafe { unwrap_class_handle(x) } {
        Some(ptr) => ptr,
        None => refuse_no_handle::<T>(x),
    }
}

/// What an R accessor's receiver holds instead of a live `T` (#1920).
#[derive(Clone, Copy)]
enum Refused {
    /// No external pointer at all ([`refuse_no_handle`]).
    NoPointer,
    /// A pointer without an address that `T` did not build.
    NullPointer,
    /// A live pointer to another type.
    OtherType,
}

/// The message of a receiver refusal (#1920): the type's own
/// ([`TypedExternal::FIELD_ERROR_MESSAGE`]), else one naming `receiver`'s R
/// class, which is what the user sees (the field methods dispatched on it),
/// else, for a receiver without a class, one naming the Rust type.
fn refusal_message<T: TypedExternal>(receiver: SEXP, refused: Refused) -> String {
    if let Some(message) = T::FIELD_ERROR_MESSAGE {
        return message.to_owned();
    }
    match (receiver_class(receiver), refused) {
        (Some(class), Refused::NoPointer) => format!("this `{class}` object holds no pointer"),
        (Some(class), Refused::NullPointer) => {
            format!("this `{class}` object holds a null pointer")
        }
        (Some(class), Refused::OtherType) => {
            format!("this `{class}` object holds a pointer of another type")
        }
        (None, Refused::NoPointer) => format!(
            "expected ExternalPtr<{}>, got a non-external-pointer object",
            T::TYPE_NAME
        ),
        (None, Refused::NullPointer) => format!(
            "expected ExternalPtr<{}>, got a null external pointer",
            T::TYPE_NAME
        ),
        (None, Refused::OtherType) => format!("expected ExternalPtr<{}>", T::TYPE_NAME),
    }
}

/// Raises the error for a receiver that carries no external pointer (#1901):
/// [`NO_HANDLE_CLASS`], with the type's field-error classes
/// ([`TypedExternal::FIELD_ERROR_CLASS`], #1899) in front, and for a list or
/// an environment, the shape an earlier release of a package may have
/// written to disk, its restored classes
/// ([`TypedExternal::RESTORED_ERROR_CLASS`]) in front of those: a package
/// refuses such a save as it refuses a restored pointer, with its restored
/// message ([`TypedExternal::RESTORED_ERROR_MESSAGE`]) when it sets one.
/// Another receiver (an atomic vector given the class) was never saved, so
/// it gets neither (#1919).
#[cold]
fn refuse_no_handle<T: TypedExternal>(receiver: SEXP) -> ! {
    let saved_shape = matches!(receiver.type_of(), SEXPTYPE::VECSXP | SEXPTYPE::ENVSXP);
    let restored = if saved_shape {
        T::RESTORED_ERROR_CLASS
    } else {
        &[]
    };
    let message = match T::RESTORED_ERROR_MESSAGE {
        Some(message) if saved_shape => message.to_owned(),
        _ => refusal_message::<T>(receiver, Refused::NoPointer),
    };
    std::panic::panic_any(RCondition::Error {
        message,
        class: no_handle_classes(restored, T::FIELD_ERROR_CLASS),
        data: None,
        call: ConditionCall::Inherit,
    })
}

/// The classes of [`refuse_no_handle`]: `restored`, then `field_error`, then
/// [`NO_HANDLE_CLASS`], each class once at its last place. The two lists
/// usually end in the package's one parent class (`["pkg_saved",
/// "pkg_error"]` and `["pkg_field", "pkg_error"]`), which then follows both
/// specific classes, as a class vector goes from specific to general.
fn no_handle_classes(restored: &[&str], field_error: &[&str]) -> Vec<String> {
    let all: Vec<&str> = restored
        .iter()
        .chain(field_error)
        .chain(&[NO_HANDLE_CLASS])
        .copied()
        .collect();
    all.iter()
        .enumerate()
        .filter(|&(i, c)| !all[i + 1..].contains(c))
        .map(|(_, c)| (*c).to_owned())
        .collect()
}

/// Raises the error for a receiver whose pointer is not a `T` (a pointer of
/// another type, or one without an address that `T` did not build), worded
/// by [`refusal_message`], with the type's field-error classes
/// ([`TypedExternal::FIELD_ERROR_CLASS`], #1899) in front. A type without
/// them gets the plain panic.
#[cold]
fn refuse_other_type<T: TypedExternal>(receiver: SEXP, refused: Refused) -> ! {
    let message = refusal_message::<T>(receiver, refused);
    if T::FIELD_ERROR_CLASS.is_empty() {
        panic!("{message}");
    }
    std::panic::panic_any(RCondition::Error {
        message,
        class: T::FIELD_ERROR_CLASS
            .iter()
            .map(|c| (*c).to_owned())
            .collect(),
        data: None,
        call: ConditionCall::Inherit,
    })
}

/// Reads the `require_live` flag the R accessors' `.Call()`s pass: `TRUE`
/// from the `$` / `[[` / `$<-` / `[[<-` field methods, which refuse a
/// restored pointer, `FALSE` from the standalone accessors, the R6 bindings
/// and the S7 properties, which read a save (#1891). Anything but `TRUE`
/// reads as `false`.
#[doc(hidden)]
pub fn sidecar_require_live(flag: SEXP) -> bool {
    flag.as_logical() == Some(true)
}

/// The `prot` list of the external pointer `x` carries
/// ([`sidecar_receiver`]), after checking that it points to a `T`, and the
/// live `T`'s `RefCell` when it still has an address. Allocates nothing for a
/// pointer, a list or an environment receiver.
///
/// A live pointer is checked by `Any::downcast`. A pointer whose address is
/// NULL (restored from a saved session by `readRDS()` / `unserialize()`)
/// still holds its sidecar values, so without `require_live` it is accepted
/// when its stored type ID is `T`'s; one another version of the crate saved
/// is refused with the classed
/// [`RESTORED_OTHER_VERSION_CLASS`](super::RESTORED_OTHER_VERSION_CLASS)
/// error. With `require_live` (the field methods of `r_data_accessors`)
/// every restored pointer is refused through [`refuse_restored`], so a save
/// by this version gets [`RESTORED_NO_VALUE_CLASS`](super::RESTORED_NO_VALUE_CLASS).
///
/// # Panics
///
/// When `x` carries no external pointer to a `T`, or, with `require_live`,
/// no live one.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`.
unsafe fn checked_prot<'a, T: TypedExternal>(
    receiver: SEXP,
    require_live: bool,
) -> (SEXP, Option<&'a RefCell<T>>) {
    let x = unsafe { sidecar_receiver::<T>(receiver) };
    let mut any_raw = unsafe { R_ExternalPtrAddr(x) }.cast::<Box<dyn Any>>();
    // A reader that needs the value rebuilds a restored pointer first, when
    // the type has a hook; a `Sidecar` read takes the saved slot as it is.
    // Another version's save, under `any_version`, is rebuilt by any reader:
    // the rebuild lays its slots out as this version's (#2187).
    if any_raw.is_null()
        && (require_live
            || T::REBUILDS_ANY_VERSION
                && matches!(
                    unsafe { super::classify_null_address::<T>(x) },
                    super::NullAddress::OtherVersion { .. }
                ))
        && unsafe { super::rebuild_restored::<T>(x, receiver) }
    {
        any_raw = unsafe { R_ExternalPtrAddr(x) }.cast::<Box<dyn Any>>();
    }
    // Read after a rebuild, which gives the pointer a new list (#2187).
    let prot = unsafe { R_ExternalPtrProtected(x) };
    let live = if any_raw.is_null() {
        if require_live
            || !unsafe { super::stored_type_id_symbol(x) }.is_some_and(is_type_id_symbol::<T>)
        {
            // A save by this version (`require_live`) or by another version
            // raises its own error here.
            unsafe { refuse_restored::<T>(x, receiver) };
            refuse_other_type::<T>(receiver, Refused::NullPointer);
        }
        None
    } else {
        if unsafe { super::stored_type_id_symbol(x) }.is_none() {
            refuse_other_type::<T>(receiver, Refused::OtherType);
        }
        match unsafe { &*any_raw }.downcast_ref::<RefCell<T>>() {
            Some(cell) => Some(cell),
            None => refuse_other_type::<T>(receiver, Refused::OtherType),
        }
    };
    // A save read by name may hold fewer slots than the type has fields:
    // its reads look the field up ([`saved_slot`]).
    if (live.is_some() || !has_slot_names(prot))
        && !usize::try_from(prot_index(T::R_SLOT_COUNT)).is_ok_and(|len| len <= prot.len())
    {
        panic!(
            "ExternalPtr<{}> has no sidecar slots: its protection list was not built by `ExternalPtr`",
            T::TYPE_NAME
        );
    }
    (prot, live)
}

/// The live `T` of the external pointer `x` carries ([`sidecar_receiver`]),
/// borrowed shared, for the R getters of a struct field (a field that is not
/// a `Sidecar`). A pointer without an address is refused: with the classed
/// restored-object errors when `T` built it ([`refuse_restored`]), else as a
/// null pointer ([`refusal_message`]).
///
/// # Panics
///
/// When `x` carries no live external pointer to a `T`, or with the
/// `miniextendr_borrow_conflict` R error while a running call holds the value
/// mutably.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`; the borrow must end
/// while `x` keeps its value.
#[doc(hidden)]
pub unsafe fn sidecar_r_struct<'a, T: TypedExternal>(x: SEXP) -> Ref<'a, T> {
    super::borrow_value(unsafe { sidecar_r_cell::<T>(x) })
}

/// The live `T` of the external pointer `x` carries, borrowed mutably, for
/// the R setters of a struct field; see [`sidecar_r_struct`].
///
/// # Panics
///
/// When `x` carries no live external pointer to a `T`, or with the
/// `miniextendr_borrow_conflict` R error while a running call holds the value.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`; the borrow must end
/// while `x` keeps its value.
#[doc(hidden)]
pub unsafe fn sidecar_r_struct_mut<'a, T: TypedExternal>(x: SEXP) -> RefMut<'a, T> {
    super::borrow_value_mut(unsafe { sidecar_r_cell::<T>(x) })
}

/// The body of [`sidecar_r_struct`] and [`sidecar_r_struct_mut`]: the
/// `RefCell` of the struct behind the pointer `x` carries
/// ([`sidecar_receiver`]).
unsafe fn sidecar_r_cell<'a, T: TypedExternal>(receiver: SEXP) -> &'a RefCell<T> {
    let x = unsafe { sidecar_receiver::<T>(receiver) };
    let mut any_raw = unsafe { R_ExternalPtrAddr(x) }.cast::<Box<dyn Any>>();
    if any_raw.is_null() && unsafe { super::rebuild_restored::<T>(x, receiver) } {
        any_raw = unsafe { R_ExternalPtrAddr(x) }.cast::<Box<dyn Any>>();
    }
    if any_raw.is_null() {
        // A save by this or another version raises its own error here.
        unsafe { refuse_restored::<T>(x, receiver) };
        refuse_other_type::<T>(receiver, Refused::NullPointer);
    }
    if unsafe { super::stored_type_id_symbol(x) }.is_none() {
        refuse_other_type::<T>(receiver, Refused::OtherType);
    }
    match unsafe { &*any_raw }.downcast_ref::<RefCell<T>>() {
        Some(cell) => cell,
        None => refuse_other_type::<T>(receiver, Refused::OtherType),
    }
}

/// Checks that `x` carries an external pointer to a `T` ([`sidecar_receiver`]),
/// live or (without `require_live`) read back by `readRDS()`, before a setter
/// validates its value.
///
/// # Panics
///
/// When `x` carries no external pointer to a `T` ([`checked_prot`]), or with
/// the `miniextendr_borrow_conflict` R error while a running call holds the
/// value.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`.
#[doc(hidden)]
pub unsafe fn sidecar_r_check<T: TypedExternal>(x: SEXP, require_live: bool) {
    let (_, live) = unsafe { checked_prot::<T>(x, require_live) };
    if let Some(cell) = live {
        drop(super::borrow_value_mut(cell));
    }
}

/// Whether the receiver `x` (a pointer, or an object carrying one) still has
/// its Rust value, for the field methods of a type with
/// `#[externalptr(restored(refuse = "every_read"))]` (#1901), which ask
/// before a read that never reaches an accessor (`names()`, a name that is
/// not a field).
///
/// With `raise`, a receiver without one is refused as the accessors refuse
/// it ([`checked_prot`] with `require_live`: the type's restored error, the
/// no-pointer error, or the other-type error) and a live pointer of another
/// type is refused too, so the result is always `true`. Without it
/// (`.DollarNames()`, which serves completion and never raises) the answer
/// is whether `x` carries a pointer with an address: a list or an
/// environment without one, or an atomic vector, has none.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`.
#[doc(hidden)]
pub unsafe fn sidecar_r_live<T: TypedExternal>(x: SEXP, raise: bool) -> bool {
    if raise {
        let _ = unsafe { checked_prot::<T>(x, true) };
        return true;
    }
    let ptr = if x.type_of() == SEXPTYPE::EXTPTRSXP {
        Some(x)
    } else {
        unsafe { unwrap_class_handle(x) }
    };
    ptr.is_some_and(|ptr| !unsafe { R_ExternalPtrAddr(ptr) }.is_null())
}

/// Reads `T`'s `Sidecar` field `index` from the external pointer `x` carries
/// ([`sidecar_receiver`]).
///
/// Called by the R getters `#[derive(ExternalPtr)]` generates. A live
/// struct's pending value for the field is flushed into the slot first; a
/// pointer without an address (after `readRDS()`) reads its protection list
/// as is, unless `require_live` refuses it ([`checked_prot`]).
///
/// # Panics
///
/// When `x` carries no external pointer to a `T`, or with the
/// `miniextendr_borrow_conflict` R error while a running call holds the value
/// mutably.
///
/// # Safety
///
/// Must be called from R's main thread with a valid `x`.
#[doc(hidden)]
pub unsafe fn sidecar_r_get<T: TypedExternal>(x: SEXP, index: usize, require_live: bool) -> SEXP {
    let (prot, live) = unsafe { checked_prot::<T>(x, require_live) };
    let Some(cell) = live else {
        // A restored pointer: the slot of the field's name (#2187).
        let name = T::SIDECAR_NAMES[index];
        return match saved_slot(prot, index, name) {
            Some(at) => prot.vector_elt(at),
            None => missing_slot::<T>(name),
        };
    };
    super::borrow_value(cell).__mx_visit_sidecars(&mut |i, _, field| {
        if i == index {
            field.__mx_flush(prot, i);
        }
    });
    prot.vector_elt(prot_index(index))
}

/// Stores `value`, which the caller validated with `TryFromSexp::<T>`, in
/// `T`'s `Sidecar` field `index` of the external pointer `x` carries
/// ([`sidecar_receiver`]).
///
/// Called by the R setters `#[derive(ExternalPtr)]` generates, after
/// [`sidecar_r_check`] with the same `require_live`. A live struct's pending
/// value for the field is dropped, since this write supersedes it. The store
/// allocates nothing; reading an S4 receiver's slot does, and `value`, an
/// argument of the setter's `.Call()`, is rooted by that call.
///
/// # Panics
///
/// When `x` carries no external pointer to a `T`, or with the
/// `miniextendr_borrow_conflict` R error while a running call holds the
/// value.
///
/// # Safety
///
/// Must be called from R's main thread with valid `x` and `value`.
#[doc(hidden)]
pub unsafe fn sidecar_r_set<T: TypedExternal>(
    x: SEXP,
    index: usize,
    value: SEXP,
    require_live: bool,
) {
    let (prot, live) = unsafe { checked_prot::<T>(x, require_live) };
    let Some(cell) = live else {
        // A restored pointer: the slot of the field's name (#2187).
        let name = T::SIDECAR_NAMES[index];
        match saved_slot(prot, index, name) {
            Some(at) => prot.set_vector_elt(at, value),
            None => missing_slot::<T>(name),
        }
        return;
    };
    super::borrow_value_mut(cell).__mx_visit_sidecars(&mut |i, _, field| {
        if i == index {
            field.__mx_discard_pending();
        }
    });
    prot.set_vector_elt(prot_index(index), value);
}

// endregion

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

    /// A parent class both lists share follows both specific classes.
    #[test]
    fn no_handle_classes_keep_each_class_at_its_last_place() {
        assert_eq!(
            no_handle_classes(&["pkg_saved", "pkg_error"], &["pkg_field", "pkg_error"]),
            [
                "pkg_saved",
                "pkg_field",
                "pkg_error",
                "miniextendr_no_handle"
            ]
        );
        assert_eq!(no_handle_classes(&[], &[]), ["miniextendr_no_handle"]);
        assert_eq!(
            no_handle_classes(&["pkg_error"], &[]),
            ["pkg_error", "miniextendr_no_handle"]
        );
    }
}