Expand description
Cached field values: #[r_data(cache)] (#2271).
The R getter of a struct field converts a clone of the Rust value on every
read, so a large field costs a copy and a conversion per $. The getter of
a field marked #[r_data(cache)] keeps the R object its first read makes,
and later reads return that same object, until the value is borrowed
exclusively.
§Storage
The cached objects live in the pool that roots owning ExternalPtr
handles (root_owned), and their keys in a table keyed by the address of
the value’s RefCell<T>: one entry per object, one slot per cached field,
empty until the field’s first read. Not in the pointer’s prot list, which
saveRDS() writes: a save never carries a cache, and an object
readRDS() brings back starts with none. A clone has a RefCell of its
own, so it starts with none too.
§Invalidation
Every exclusive borrow of the value drops its entry
(borrow_value_mut): a &mut self method, a
&mut T or ExternalPtrMut argument,
ExternalPtr::borrow_mut, an R setter,
a consuming self method, into_inner. The check is a constant
(TypedExternal::CACHED_FIELD_COUNT),
so a type without cached fields pays one constant branch. While the borrow
lasts, a read can’t fill the entry again: the getter’s shared borrow
raises miniextendr_borrow_conflict. The finalizer of such a type drops
the entry before it frees the value (super::finalizer), so a later
value at the same address never finds it.
A change no exclusive borrow covers is not seen, and the field reads its
old value: interior mutability behind &self (a Cell, RefCell,
Mutex or atomic in the field, or anything it reaches), and the ALTREP
data1 paths that read and write without a borrow
(as_mut_unchecked). The value
is stale, not unsound: the cached object is a complete R value, rooted
until its entry drops.
§Sharing
A read returns the cached object itself, so two reads give the same R
object. It is marked not mutable (MARK_NOT_MUTABLE): R code that
modifies it (v[1] <- 0, attr(v, "a") <- 1) copies it first. C code that
writes its argument in place (data.table::set()) changes it for every
later read, as it would any shared R object.
Re-exports§
use std::any::Any;🔒use std::cell::RefCell;🔒use std::collections::HashMap;🔒use super::pooled;🔒use super::root_owned;🔒use super::unroot_owned;🔒use crate::SEXP;🔒use crate::protect_pool::ProtectKey;🔒use crate::sys::MARK_NOT_MUTABLE;🔒
Constants§
- FIELD_
CACHES 🔒 - The cached field values of each object that has any, by the address
of its value’s
RefCell: the pool key of each cached field’s value, in cache-index order,Noneuntil the field’s first read.
Functions§
- cached 🔒
- The cached value of the field at
indexof the value atkey, if a read stored one since the value’s last exclusive borrow. - cell_
key 🔒 - The table key of a stored value: the address of its
RefCell. - forget 🔒
- Drops the cached field values of the value at
key, if it has any. Allocates nothing and calls no R code, so a finalizer can call it. - store 🔒
- Keeps
value, the converted value of the field atindexof the value atkey, whose type hascountcached fields. Marks it not mutable and roots it in the pool, whichvaluemay need no protection for (the pool keeps it reachable while it grows). On R’s main thread. - stored_
key 🔒 - The table key of the value an
ExternalPtr’s address holds: theRefCell<T>itsBox<dyn Any>points to, so the same ascell_keyof that cell.