Trait TypedExternal

Source

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;
    #[doc(hidden)]
    const SIDECAR_NAMES: &'static [&'static str] = _;
    const RESTORED_ERROR_CLASS: &'static [&'static str] = _;
    const RESTORED_ERROR_MESSAGE: Option<&'static str> = None;
    const FIELD_ERROR_CLASS: &'static [&'static str] = _;
    const FIELD_ERROR_MESSAGE: Option<&'static str> = None;
    #[doc(hidden)]
    const REBUILDS: bool = false;
    #[doc(hidden)]
    const REBUILDS_ANY_VERSION: bool = false;

    // Provided methods
    #[doc(hidden)]
    fn __mx_visit_sidecars(
        &self,
        _visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField),
    ) { ... }
    #[doc(hidden)]
    fn __mx_rebuild(saved: &Saved<'_, Self>) -> Result<Self, RCondition>
       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 in prot[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§

Source

const TYPE_NAME: &'static str

The type name as a static string (for debugging and display)

Source

const TYPE_NAME_CSTR: &'static [u8]

The type name as a null-terminated C string (for R tag display)

Source

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§

Source

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<_>.

Source

#[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).

Source

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.

Source

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.

Source

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.

Source

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 = "..."))].

Source

#[doc(hidden)]
const REBUILDS: bool = false

Whether a pointer of this type that this version of its crate saved is rebuilt on first use after readRDS(), by Self::__mx_rebuild, instead of refused.

#[derive(ExternalPtr)] sets it with #[externalptr(rebuild = path)].

Source

#[doc(hidden)]
const REBUILDS_ANY_VERSION: bool = false

Whether Self::__mx_rebuild also rebuilds a pointer another version of the crate saved, when the save carries slot names. #[derive(ExternalPtr)] sets it with any_version next to rebuild = path (#2187).

Provided Methods§

Source

#[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_rebuild(saved: &Saved<'_, Self>) -> Result<Self, RCondition>
where Self: Sized,

Rebuilds the value of a pointer of this type restored from a saved session, from what the save kept. #[derive(ExternalPtr)] emits it for #[externalptr(rebuild = path)]: it calls path and turns its Err into a condition.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Trait TypedExternal Copy item path

§Type ID vs Type Name

Required Associated Constants§

const TYPE_NAME: &'static str

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

Provided Associated Constants§

const R_SLOT_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 FIELD_ERROR_CLASS: &'static [&'static str] = _

const FIELD_ERROR_MESSAGE: Option<&'static str> = None

#[doc(hidden)]const REBUILDS: bool = false

#[doc(hidden)]const REBUILDS_ANY_VERSION: bool = false

Provided Methods§

#[doc(hidden)]fn __mx_visit_sidecars( &self, _visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField), )

#[doc(hidden)]fn __mx_rebuild(saved: &Saved<'_, Self>) -> Result<Self, RCondition>where Self: Sized,

Dyn Compatibility§

Implementations on Foreign Types§

impl TypedExternal for ()

const TYPE_NAME: &'static str = "()"

const TYPE_NAME_CSTR: &'static [u8] = b"()\0"

const TYPE_ID_CSTR: &'static [u8] = b"()\0"

impl TypedExternal for AtomicBool

const TYPE_NAME: &'static str = "AtomicBool"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicI8

const TYPE_NAME: &'static str = "AtomicI8"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicI16

const TYPE_NAME: &'static str = "AtomicI16"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicI32

const TYPE_NAME: &'static str = "AtomicI32"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicI64

const TYPE_NAME: &'static str = "AtomicI64"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicIsize

const TYPE_NAME: &'static str = "AtomicIsize"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicU8

const TYPE_NAME: &'static str = "AtomicU8"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicU16

const TYPE_NAME: &'static str = "AtomicU16"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicU32

const TYPE_NAME: &'static str = "AtomicU32"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicU64

const TYPE_NAME: &'static str = "AtomicU64"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for AtomicUsize

const TYPE_NAME: &'static str = "AtomicUsize"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for Barrier

const TYPE_NAME: &'static str = "Barrier"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for BarrierWaitResult

const TYPE_NAME: &'static str = "BarrierWaitResult"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

impl TypedExternal for CString

const TYPE_NAME: &'static str = "CString"

const TYPE_NAME_CSTR: &'static [u8]

const TYPE_ID_CSTR: &'static [u8]

Trait TypedExternal

#[doc(hidden)]
const SIDECAR_NAMES: &'static [&'static str] = _

#[doc(hidden)]
const REBUILDS: bool = false

#[doc(hidden)]
const REBUILDS_ANY_VERSION: bool = false

#[doc(hidden)]
fn __mx_visit_sidecars( &self, _visit: &mut dyn FnMut(usize, &'static str, &dyn SidecarField), )

#[doc(hidden)]
fn __mx_rebuild(saved: &Saved<'_, Self>) -> Result<Self, RCondition>
where Self: Sized,