Struct mozjs_sys::jsgc::Heap

#[repr(C)]
pub struct Heap<T: GCMethods + Copy> {
    pub ptr: UnsafeCell<T>,
}

Heap values encapsulate GC concerns of an on-heap reference to a JS object. This means that every reference to a JS object on heap must be realized through this structure.

Safety

For garbage collection to work correctly in SpiderMonkey, modifying the wrapped value triggers a GC barrier, pointing to the underlying object.

This means that after calling the set() function with a non-null or non-undefined value, the Heap wrapper must not be moved, since doing so will invalidate the local reference to wrapped value, still held by SpiderMonkey.

For safe Heap construction with value see Heap::boxed function.

Fields

ptr: UnsafeCell<T>

Implementations

impl<T: GCMethods + Copy> Heap<T>

pub fn boxed(v: T) -> Box<Heap<T>>

where Heap<T>: Default,

This creates a Box-wrapped Heap value. Setting a value inside Heap object triggers a barrier, referring to the Heap object location, hence why it is not safe to construct a temporary Heap value, assign a non-null value and move it (e.g. typical object construction).

Using boxed Heap value guarantees that the underlying Heap value will not be moved when constructed.

pub fn set(&self, v: T)

pub fn get(&self) -> T

pub fn get_unsafe(&self) -> *mut T

pub unsafe fn handle(&self) -> Handle<T>

Retrieves a Handle to the underlying value.

Safety

This is only safe to do on a rooted object (which Heap is not, it needs to be additionally rooted), like RootedGuard, so use this only if you know what you’re doing.

Notes

Since Heap values need to be informed when a change to underlying value is made (e.g. via get()), this does not allow to create MutableHandle objects, which can bypass this and lead to crashes.

Trait Implementations

impl<T: Debug + GCMethods + Copy> Debug for Heap<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for Heap<*mut T>

where *mut T: GCMethods + Copy,

fn default() -> Heap<*mut T>

Returns the “default value” for a type.

impl Default for Heap<Value>

fn default() -> Heap<Value>

Returns the “default value” for a type.

impl<T: GCMethods + Copy> Drop for Heap<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: GCMethods + Copy + PartialEq> PartialEq for Heap<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.