pub trait TypedExternal: 'static {
const TYPE_NAME: &'static str;
const TYPE_NAME_CSTR: &'static [u8];
const TYPE_ID_CSTR: &'static [u8];
const R_SLOT_COUNT: usize = 0;
const CACHED_FIELD_COUNT: usize = 0;
#[doc(hidden)] const SIDECAR_NAMES: &'static [&'static str] = _;
const RESTORED_ERROR_CLASS: &'static [&'static str] = _;
const RESTORED_ERROR_MESSAGE: Option<&'static str> = None;
const NO_HANDLE_MESSAGE: Option<&'static str> = None;
const FIELD_ERROR_CLASS: &'static [&'static str] = _;
const FIELD_ERROR_MESSAGE: Option<&'static str> = None;
// Provided methods
#[doc(hidden)] fn __mx_visit_sidecars(
&self,
_visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField),
) { ... }
#[doc(hidden)] fn __mx_snapshot() -> Option<Snapshot<Self>>
where Self: Sized { ... }
}Expand description
Trait for types that can be stored in an ExternalPtr.
This provides R-visible display and diagnostic identifiers. Runtime type
checking is performed by Any::downcast (Rust’s TypeId), not by comparing
these symbols.
§Type ID vs Type Name
-
TYPE_ID_CSTR: Namespaced identifier used in mismatch diagnostics (stored inprot[0]). Format:"<crate_name>@<crate_version>::<module_path>::<type_name>\0"The crate name, version, and module path distinguish otherwise similar names in error messages. They do not determine compatibility.
-
TYPE_NAME_CSTR: Short display name for the R tag (shown when printing). Just the type identifier for readability.
Required Associated Constants§
Sourceconst TYPE_NAME_CSTR: &'static [u8]
const TYPE_NAME_CSTR: &'static [u8]
The type name as a null-terminated C string (for R tag display)
Sourceconst TYPE_ID_CSTR: &'static [u8]
const TYPE_ID_CSTR: &'static [u8]
Namespaced type ID as a null-terminated C string (for diagnostics).
This should include the module path to prevent ambiguous messages.
Use concat!(module_path!(), "::", stringify!(Type), "\0").as_bytes()
when implementing manually, or use #[derive(ExternalPtr)].
Provided Associated Constants§
Sourceconst R_SLOT_COUNT: usize = 0
const R_SLOT_COUNT: usize = 0
Number of Sidecar<T> fields: values the external pointer’s
protection list keeps after the type ID and the user slot.
#[derive(ExternalPtr)] counts the type’s #[r_data] fields of type
Sidecar<_>.
Sourceconst CACHED_FIELD_COUNT: usize = 0
const CACHED_FIELD_COUNT: usize = 0
Number of #[r_data(cache)] fields: struct fields whose R getter
keeps the R value its first read makes until the value is next
borrowed exclusively (#2271).
#[derive(ExternalPtr)] counts them. Every exclusive borrow of a
value whose type has any drops the value’s cached field values, and
its pointer’s finalizer drops them too; a type with none pays one
constant branch per exclusive borrow.
Source#[doc(hidden)]const SIDECAR_NAMES: &'static [&'static str] = _
#[doc(hidden)]const SIDECAR_NAMES: &'static [&'static str] = _
The R names of the Sidecar fields (#[r_data(name = "..")], else
the Rust field name), in slot order: the names the protection list
carries, so a save is read back by field name (#2187, #2215).
Sourceconst RESTORED_ERROR_CLASS: &'static [&'static str] = _
const RESTORED_ERROR_CLASS: &'static [&'static str] = _
The package’s condition classes for a pointer of this type restored
from a saved session, in front of the miniextendr_restored* classes
(RESTORED_NO_VALUE_CLASS / RESTORED_OTHER_VERSION_CLASS, then
RESTORED_CLASS), which every restored refusal keeps.
#[derive(ExternalPtr)] fills it from
#[externalptr(restored(class = "pkg_saved"))] or
restored(class = ["pkg_saved", "pkg_error"]); the default adds
nothing.
Sourceconst RESTORED_ERROR_MESSAGE: Option<&'static str> = None
const RESTORED_ERROR_MESSAGE: Option<&'static str> = None
The package’s message for a pointer of this type restored from a saved
session, replacing miniextendr’s in both the no-value and the
other-version case (the condition’s saved_version /
current_version fields stay), and for a list or environment of the
class that carries no pointer (a save in an older format). A static
string: one type is one R class, so the package names it literally.
#[derive(ExternalPtr)] fills it from
#[externalptr(restored(message = "..."))]; the default keeps
miniextendr’s messages.
Sourceconst NO_HANDLE_MESSAGE: Option<&'static str> = None
const NO_HANDLE_MESSAGE: Option<&'static str> = None
The package’s message for a list or an environment of the type’s
class that carries no pointer (#2218), the shape an earlier release
may have saved: it says why the object has none. It replaces
Self::RESTORED_ERROR_MESSAGE for that receiver, which otherwise
serves both. The R accessors raise it with
NO_HANDLE_CLASS; a package’s own code that refuses such an object
reads it here to word the refusal the same way.
#[derive(ExternalPtr)] fills it from
#[externalptr(restored(no_handle = "..."))].
Sourceconst FIELD_ERROR_CLASS: &'static [&'static str] = _
const FIELD_ERROR_CLASS: &'static [&'static str] = _
The package’s condition classes for the errors the type’s R field
readers raise themselves (#1899), in front of their own class: a
refused position (subscriptOutOfBoundsError), a name that is not a
field (miniextendr_no_field), a computed field assigned to
(miniextendr_read_only_field), a pointer of another type, and a
receiver that carries no pointer (NO_HANDLE_CLASS). The R
accessors of the type read it for the last two; the derive writes the
same classes into the R helpers for the others.
#[derive(ExternalPtr)] fills it from
#[externalptr(field_error(class = ["pkg_error_config", "pkg_error"]))];
the default adds nothing.
Sourceconst FIELD_ERROR_MESSAGE: Option<&'static str> = None
const FIELD_ERROR_MESSAGE: Option<&'static str> = None
The package’s message for the R accessors’ refusal of a receiver
whose pointer is not a T or that carries no pointer (#1920),
replacing miniextendr’s, which names the receiver’s R class.
#[derive(ExternalPtr)] fills it from
#[externalptr(field_error(message = "..."))].
Provided Methods§
Source#[doc(hidden)]fn __mx_visit_sidecars(
&self,
_visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField),
)
#[doc(hidden)]fn __mx_visit_sidecars(
&self,
_visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField),
)
Visits every Sidecar<T> field of self with its slot index and
name, so the handle can flush the field’s pending value into its slot
or load the slot back into the field.
#[derive(ExternalPtr)] emits the body for a type with Sidecar
fields; the default visits nothing, so other types pay nothing.
Source#[doc(hidden)]fn __mx_snapshot() -> Option<Snapshot<Self>>where
Self: Sized,
#[doc(hidden)]fn __mx_snapshot() -> Option<Snapshot<Self>>where
Self: Sized,
How a value of this type goes into a save and comes back after
readRDS() (#2186): Some for a type that is Serialize + DeserializeOwned with miniextendr-api’s serde feature.
#[derive(ExternalPtr)] emits the probe that decides it, in the
type’s own impl; the default (impl_typed_external!, the standard
library types’, a hand-written impl) is None, which keeps the
restored refusal.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".