Skip to main content

Module snapshot

Module snapshot 

Source
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, during serialize(): 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 through ExternalPtr::borrow, so a serialize() that R code runs while a call holds the object mutably (a callback that saves self) raises the miniextendr_borrow_conflict error 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, during unserialize(), 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 whose Serialized_state encodes the value and whose Unserialize decodes it.
Snapshot 👻
How a value of T goes into a save and comes back from one: its carrier class and the serde encoding. T::__mx_snapshot() gives it for a serde type.
SnapshotClass 👻
The carrier class of one type, registered at R_init. The derive emits one per type, in its TypedExternal::__mx_snapshot.
SnapshotProbe 👻
The receiver of the snapshot probe: the type’s class cell. The derive calls (&SnapshotProbe::<Self>::new(&CLASS)).__mx_snapshot() with SnapshotSerde and SnapshotNone in scope, in the type’s own TypedExternal impl, where the type is concrete.

Enums§

Attach 🔒
What attach did with a pointer without an address.

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$parent of the restored refusal: the message is serde’s.

Traits§

SnapshotNone 👻
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.
SnapshotSerde 👻
Snapshot probe, serde arm: T: Serialize + DeserializeOwned. This impl, on the probe taking &self, matches the receiver &SnapshotProbe<T> by value; SnapshotNone needs one more auto-ref and is reached only when T is not serde.

Functions§

attach 🔒 ⚠
Gives sexp, a pointer without an address, the value its save decoded, when T is serde and the save carries one (#2186): the first access of a pointer readRDS() gave back. Raises nothing: a failure stays in the carrier, for the caller’s refusal (super::refuse_restored) to name as e$parent.
carrier_class 🔒
T’s registered carrier class, if T is serde and its class is registered (it is not while the wrappers are generated).
claim 🔒
Claims the carrier class name for the type with ID id. 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: an RCondition as itself, any other as a DECODE_ERROR_CLASS condition with its message. An R error keeps unwinding: its jump belongs to R (#2244).
decode_failure 🔒 ⚠
The condition decoding sexp’s save raised, when T is serde and the save carries a value it could not decode.
decoded 🔒 ⚠
The decoded value a holder pointer owns, when holder is one for T.
has_carrier_slot 🔒
Whether T’s protection list ends in a carrier slot.
init_carrier 🔒 ⚠
Puts a carrier for the value owner holds in the last slot of its new protection list. A construction site calls it after the address is set.
install 🔒 ⚠
Puts value in sexp, as construction puts a new value in a new pointer (the finalizer first, then the address), with the protection list attach describes.
register 👻
Registers T’s carrier class when T is serde, once. The registration function #[derive(ExternalPtr)] emits for the type calls it from R_init (through MX_ALTREP_REGISTRATIONS).
saved_carrier 🔒 ⚠
The carrier of sexp’s saved protection list, and what it decoded, when sexp is a save of T with one.
saved_field_slot 🔒
The position in the saved list saved of Sidecar field index, named name: by name (sidecar::saved_slot), or, in a list without slot names (a version whose type had no Sidecar field), by position, short of the carrier in the last slot.
serialized_state 🔒 ⚠
Serialized_state: the state of the carrier x.
unserialize 🔒 ⚠
Unserialize: decodes state into a holder and returns a carrier holding it. Never raises (only an R error from the type’s own Deserialize code carries on).

Type Aliases§

Decoded 🔒
What Unserialize decoded: the value until the first access takes it, or the condition decoding raised. The holder pointer in the carrier’s data1 owns it, freed by the ordinary finalizer.