Struct RawValueRootGuard 

pub struct RawValueRootGuard { /* private fields */ }

RAII guard for one or more heap JSVal slots registered with the GC extra-roots table (AddRawValueRoot) — the general form of PersistentGlobal’s rooting, for values that must survive across an async window (pending fetch promises, fs/crypto callbacks, …).

Why the slots live in a Box<[JSVal]>

AddRawValueRoot registers the slot’s address: the GC scans and updates that memory in place for as long as the root is registered, and RemoveRawValueRoot removes by pointer — the registered address must therefore stay both valid and identical until removal. Rooting a stack local whose frame then returns leaves the GC tracing dead stack memory, and removing with a different address is a silent no-op (the root table is keyed by pointer), leaking the dangling root. The Box pins the slots at a stable heap address for the guard’s whole life; moving the guard only moves the Box pointer, never the rooted memory.

Drop semantics (liveness-guarded, leak-on-foreign)

On drop, when the current thread’s Runtime::get() still resolves to the captured context, every slot is unrooted and the values freed. Otherwise (dropped from a foreign thread while the context is alive, or after the runtime went away) the rooted slots are leaked, never freed — freeing memory the root table may still point at would leave the GC a dangling scan address, which is strictly worse than a bounded leak.

Implementations

impl RawValueRootGuard

pub unsafe fn new( cx: *mut JSContext, vals: &[Value], name: &'static CStr, ) -> Option<RawValueRootGuard>

Root vals for an async window that spans ticks/frames.

Returns None if any registration failed (OOM): slots registered before the failure are unrooted before returning, so a None carries no leaked roots and the caller keeps its own rooting (the pre-existing degraded path at the call sites).

Safety

• cx must be a live JSContext on the current thread.
• Each value must be a valid JSVal. After this call the guard’s slots are the live copies — read them via Self::get, not via pre-existing snapshots.

pub fn get(&self, i: usize) -> Value

The live (GC-updated) value at i. After any window in which a GC may have run, this — not a snapshot taken at spawn time — is the value to use (a moving GC updates the guard’s slot in place).

pub fn len(&self) -> usize

Number of rooted slots.

pub fn into_inner(self) -> Option<Box<[Value]>>

Release the roots and take ownership of the values (explicit ownership transfer before the guard’s natural drop site).

Returns None when the roots could not be released (foreign thread or dead runtime): the rooted memory is then leaked by the guard — the caller must NOT receive memory the GC root table still points at.

Trait Implementations

impl Drop for RawValueRootGuard

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.