pub struct GcRef(/* private fields */);Expand description
A non-null, uniformly-typed reference to a garbage-collected object.
Construction is unsafe because the caller must guarantee the pointer
points to a valid, live allocation of the right shape. The safe accessors
are the ordinary way to interact with a GcRef from Rust runtime wrappers.
PartialEq/Eq/Hash are by pointer identity: two GcRefs are equal
iff they point at the same object. (Structural value equality goes through
GcRef::equals and the descriptors, §5.5.)
Implementations§
Source§impl GcRef
impl GcRef
Sourcepub fn as_int(&self) -> i64
pub fn as_int(&self) -> i64
Read an Int payload (§4.3).
Panics if this reference’s descriptor is not Int.
Sourcepub fn as_bool(&self) -> bool
pub fn as_bool(&self) -> bool
Read a Bool payload as a Rust bool (§4.3).
Panics if this reference’s descriptor is not Bool.
Sourcepub fn as_text(&self) -> &str
pub fn as_text(&self) -> &str
Read a Text payload as a &str (§4.3).
The lifetime is tied to the GcRef’s borrow; the text stays valid as long
as the object is reachable. Handles both owned and source-slice payloads
(ADR-013): a slice reads through its owner.
Sourcepub fn format(&self, out: &mut dyn Write)
pub fn format(&self, out: &mut dyn Write)
Format this value through its descriptor into out (§11.4), in the
program’s own rendering — what out(v) writes and what "{v}" splices.
Sourcepub fn format_debug(&self, out: &mut dyn Write)
pub fn format_debug(&self, out: &mut dyn Write)
Format this value into out in the debugger’s rendering
(FormatStyle::Debug): a Text is a quoted
literal, at every depth.
The pair exists because the two callers want opposite things from the
same value. A program printing a string means its characters; a debugger
showing a local means “this is a string, and here is exactly which one” —
and on a locals row the difference between "" and no output at all is
the difference between a value and a bug report.
Sourcepub fn format_styled(&self, out: &mut FormatSink<'_>)
pub fn format_styled(&self, out: &mut FormatSink<'_>)
Format this value into an existing sink, keeping its style.
The shared body of the two above, and the entry point for a caller that already has a sink — a descriptor callback rendering a part of itself.
Source§impl GcRef
impl GcRef
Sourcepub unsafe fn from_non_null(ptr: NonNull<GcHeader>) -> GcRef
pub unsafe fn from_non_null(ptr: NonNull<GcHeader>) -> GcRef
Wrap a non-null pointer. The pointer must point to a valid GcHeader
allocation; the caller (always internal runtime code) upholds this.
§Safety
ptr must be non-null, properly aligned, and dereferenceable for the
full object it heads.
Sourcepub unsafe fn from_raw(ptr: *mut GcHeader) -> GcRef
pub unsafe fn from_raw(ptr: *mut GcHeader) -> GcRef
Wrap a non-null raw header pointer. Internal convenience for callers
(e.g. the shadow frame) that hold a *mut GcHeader already known to be
non-null.
§Safety
ptr must be non-null, properly aligned, and point at a valid live
GcHeader.
Sourcepub fn as_non_null(self) -> NonNull<GcHeader>
pub fn as_non_null(self) -> NonNull<GcHeader>
The underlying non-null pointer, for safe interior access in runtime code.
Sourcepub fn descriptor(&self) -> &'static TypeDescriptor
pub fn descriptor(&self) -> &'static TypeDescriptor
The descriptor describing this object’s payload (§11.4).
Sourcepub fn payload<T>(&self) -> *mut T
pub fn payload<T>(&self) -> *mut T
Pointer to the payload bytes immediately following this object’s header.
This is the low-level escape hatch; prefer the typed accessors on
crate::Runtime / the descriptor callbacks where possible.