Expand description
A saved value that comes back after readRDS() (#2186).
R saves an external pointer without its address: saveRDS() writes the
pointer’s protection list and tag, and readRDS() gives back a pointer
whose address is NULL. A type that is Serialize + DeserializeOwned (and
built with miniextendr-api’s serde feature) keeps its value in that list
instead. The last element of its protection list is a carrier: a
zero-length ALTREP raw vector of a class registered for the type at
R_init. R itself calls the class’s methods:
Serialized_state, duringserialize(): the value encoded through the crate’s serde-to-R path in its exact mode (serde/exact.rs, #2256), an R list the value comes back from unchanged. It reads the value throughExternalPtr::borrow, so aserialize()that R code runs while a call holds the object mutably (a callback that savesself) raises theminiextendr_borrow_conflicterror instead of reading a value under a&mut. A pointer without a value, or a value serde can’t encode, gives no state: R writes the empty vector itself, and the reload is refused as before.Unserialize, duringunserialize(), which loads the package (and so registers the class) first: decodes the state at once (the same exact mode) and keeps the value, or the decoding error, in the carrier. It never raises: a failure is kept for the first access.
R reads the protection list before the pointer exists, so the value is
attached at the pointer’s first access (attach): a method receiver, an
ExternalPtr<T> / &T / &mut T argument, or a sidecar accessor. A
decoding failure is refused there as a restored pointer is, with the
decoding error as e$parent (super::refuse_restored).
The type opts in by being serde: #[derive(ExternalPtr)] emits a probe
(SnapshotProbe) that resolves to the serde arm (SnapshotSerde)
when the type implements both traits and to the fallback
(SnapshotNone) otherwise, which keeps the restored refusal. A type
with a hand-written TypedExternal impl (the standard library types’, or
impl_typed_external!’s) has no probe and keeps the refusal (#2243).
Re-exports§
use std::any::Any;🔒use std::cell::RefCell;🔒use std::marker::PhantomData;🔒use std::ptr::NonNull;🔒use std::sync::OnceLock;🔒use super::ExternalPtr;🔒use super::NullAddress;🔒use super::PROT_TYPE_ID_INDEX;🔒use super::PROT_USER_INDEX;🔒use super::PROT_VEC_LEN;🔒use super::TypedExternal;🔒use super::classify_null_address;🔒use super::release_any;🔒use super::saved_identity;🔒use super::sidecar;🔒use super::split_type_id;🔒use super::type_id_str;🔒use super::type_id_symbol;🔒use crate::altrep::RBase;🔒use crate::altrep_traits::AltVec;🔒use crate::altrep_traits::Altrep;🔒use crate::condition::ConditionCall;🔒use crate::condition::RCondition;🔒use crate::condition::RCondition;🔒use crate::gc_protect::ProtectScope;🔒use crate::sys::altrep::R_altrep_class_t;🔒use crate::sys::R_ExternalPtrAddr;🔒use crate::sys::R_ExternalPtrProtected;🔒use crate::sys::R_MakeExternalPtr;🔒use crate::sys::R_RegisterCFinalizerEx;🔒use crate::sys::R_SetExternalPtrAddr;🔒use crate::sys::R_SetExternalPtrProtected;🔒use crate::sys::R_altrep_data1;🔒use crate::sys::R_altrep_data2;🔒use crate::sys::R_set_altrep_data1;🔒use crate::sys::R_set_altrep_data2;🔒use crate::sys::Rf_allocVector;🔒use crate::R_xlen_t;🔒use crate::Rboolean;🔒use crate::SEXP;🔒use crate::SEXPTYPE;🔒use crate::SexpExt;🔒
Structs§
- Carrier 🔒
- The carrier ALTREP class of
T: a zero-length raw vector whoseSerialized_stateencodes the value and whoseUnserializedecodes it. - Snapshot 👻
- How a value of
Tgoes into a save and comes back from one: its carrier class and the serde encoding.T::__mx_snapshot()gives it for a serde type. - Snapshot
Class 👻 - The carrier class of one type, registered at
R_init. The derive emits one per type, in itsTypedExternal::__mx_snapshot. - Snapshot
Probe 👻 - The receiver of the snapshot probe: the type’s class cell. The derive
calls
(&SnapshotProbe::<Self>::new(&CLASS)).__mx_snapshot()withSnapshotSerdeandSnapshotNonein scope, in the type’s ownTypedExternalimpl, where the type is concrete.
Enums§
Constants§
- CLAIMED 🔒
- The carrier class names registered so far, each with the ID of the
type that registered it. Only
R_init, on R’s main thread, claims. - DECODE_
ERROR_ CLASS - The class of the condition a failed decoding gives, the
e$parentof the restored refusal: the message is serde’s.
Traits§
- Snapshot
None 👻 - Snapshot probe, fallback arm: a type that is not serde has no snapshot, and a pointer to it restored from a saved session is refused.
- Snapshot
Serde 👻 - Snapshot probe, serde arm:
T: Serialize + DeserializeOwned. This impl, on the probe taking&self, matches the receiver&SnapshotProbe<T>by value;SnapshotNoneneeds one more auto-ref and is reached only whenTis not serde.
Functions§
- attach 🔒 ⚠
- Gives
sexp, a pointer without an address, the value its save decoded, whenTis serde and the save carries one (#2186): the first access of a pointerreadRDS()gave back. Raises nothing: a failure stays in the carrier, for the caller’s refusal (super::refuse_restored) to name ase$parent. - carrier_
class 🔒 T’s registered carrier class, ifTis serde and its class is registered (it is not while the wrappers are generated).- claim 🔒
- Claims the carrier class
namefor the type with IDid. Two serde types of one crate with the same name would share the class, and each would read the other’s saves, so the second one is an error naming both types’ paths. Claiming a name again for the same type is a no-op. - class_
name_ 🔒of - The carrier class name of the type with ID
id:miniextendr_saved:<crate>::<Type>, without the crate version or the module path (saved_identity), so a save by any version, or of a type since moved to another module, finds the class. A hand-written ID without a version is used whole. - decode 🔒
- Decodes
state, catching a panic: anRConditionas itself, any other as aDECODE_ERROR_CLASScondition with its message. An R error keeps unwinding: its jump belongs to R (#2244). - decode_
failure 🔒 ⚠ - The condition decoding
sexp’s save raised, whenTis serde and the save carries a value it could not decode. - decoded 🔒 ⚠
- The decoded value a holder pointer owns, when
holderis one forT. - has_
carrier_ 🔒slot - Whether
T’s protection list ends in a carrier slot. - init_
carrier 🔒 ⚠ - Puts a carrier for the value
ownerholds in the last slot of its new protection list. A construction site calls it after the address is set. - install 🔒 ⚠
- Puts
valueinsexp, as construction puts a new value in a new pointer (the finalizer first, then the address), with the protection listattachdescribes. - register 👻
- Registers
T’s carrier class whenTis serde, once. The registration function#[derive(ExternalPtr)]emits for the type calls it fromR_init(throughMX_ALTREP_REGISTRATIONS). - saved_
carrier 🔒 ⚠ - The carrier of
sexp’s saved protection list, and what it decoded, whensexpis a save ofTwith one. - saved_
field_ 🔒slot - The position in the saved list
savedofSidecarfieldindex, namedname: by name (sidecar::saved_slot), or, in a list without slot names (a version whose type had noSidecarfield), by position, short of the carrier in the last slot. - serialized_
state 🔒 ⚠ Serialized_state: the state of the carrierx.- unserialize 🔒 ⚠
Unserialize: decodesstateinto a holder and returns a carrier holding it. Never raises (only an R error from the type’s ownDeserializecode carries on).
Type Aliases§
- Decoded 🔒
- What
Unserializedecoded: the value until the first access takes it, or the condition decoding raised. The holder pointer in the carrier’sdata1owns it, freed by the ordinary finalizer.