Struct DomRefCell 

pub struct DomRefCell<T> {
    value: RefCell<T>,
}

A mutable field in the DOM.

This extends the API of std::cell::RefCell to allow unsafe access in certain situations, with dynamic checking in debug builds.

Fields

value: RefCell<T>

Implementations

impl<T> DomRefCell<T>

pub unsafe fn borrow_for_layout(&self) -> &T

Return a reference to the contents. For use in layout only.

Safety

Unlike RefCell::borrow, this method is unsafe because it does not return a Ref, thus leaving the borrow flag untouched. Mutably borrowing the RefCell while the reference returned by this method is alive is undefined behaviour.

Panics

Panics if this is called from anywhere other than the layout thread

Panics if the value is currently mutably borrowed.

pub unsafe fn borrow_for_script_deallocation(&self) -> &mut T

Borrow the contents for the purpose of script deallocation.

Safety

Unlike RefCell::borrow, this method is unsafe because it does not return a Ref, thus leaving the borrow flag untouched. Mutably borrowing the RefCell while the reference returned by this method is alive is undefined behaviour.

Panics

Panics if this is called from anywhere other than the script thread.

pub unsafe fn borrow_mut_for_layout(&self) -> &mut T

Mutably borrow a cell for layout. Ideally this would use RefCell::try_borrow_mut_unguarded but that doesn’t exist yet.

Safety

Unlike RefCell::borrow, this method is unsafe because it does not return a Ref, thus leaving the borrow flag untouched. Mutably borrowing the RefCell while the reference returned by this method is alive is undefined behaviour.

Panics

Panics if this is called from anywhere other than the layout thread.

pub fn safe_borrow_mut<'a: 'r, 'no_cx: 'r, 'r>( &'a self, _no_gc: &'no_cx NoGC, ) -> RefMut<'r, T>

Mutably borrows the wrapped value.

The borrow lasts until the returned RefMut exits scope. The value cannot be borrowed while this borrow is active.

By passing a &NoGC we statically prevent GC from being run while the borrow is active, to prevent panic when tracing (which calls borrow).

Example

In simple cases one can use NoGC to statically ensure no GC can happen in the whole DOM method:

use js::context::{JSContext, NoGC};
use script_bindings::cell::DomRefCell;
fn DomMethod(no_gc: &NoGC, cell: &DomRefCell<usize>) {
    let mut mutably_borrowed = cell.safe_borrow_mut(no_gc);
}

But in more complex cases, method might trigger a GC, and thus require a &mut JSContext. In that case &JSContext can be used in place of NoGC, which will make RefMut bounded to the lifetime of the &JSContext and thus prevent any GC from happening while it is alive.

use js::context::{JSContext, NoGC};
use script_bindings::cell::DomRefCell;
fn GC(cx: &mut JSContext) {}

fn DomMethod(cell: &DomRefCell<usize>, cx: &mut JSContext) {
    {
        let mut mutably_borrowed = cell.safe_borrow_mut(cx);
        // do something with mutably_borrowed

        // only &JSContext is available here
    } // mutably_borrowed goes out of scope here
    // so one can now use &mut JSContext
    GC(cx);
}

use js::context::{JSContext, NoGC};
use script_bindings::cell::DomRefCell;
fn GC(cx: &mut JSContext) {}

fn DomMethod(cell: &DomRefCell<usize>, cx: &mut JSContext) {
    {
        let mut mutably_borrowed = cell.safe_borrow_mut(cx);
        // do something with mutably_borrowed

        // here one cannot use anything that might trigger a GC
        // as that would require &mut JSContext
        // but there is already existing &JSContext bounded at RefMut
        GC(cx);
    } // mutably_borrowed goes out of scope here
}

Panics

Panics if the value is currently borrowed.

pub fn safe_try_borrow_mut<'a: 'r, 'no_cx: 'r, 'r>( &'a self, _no_gc: &'no_cx NoGC, ) -> Result<RefMut<'r, T>, BorrowMutError>

Mutably borrows the wrapped value.

The borrow lasts until the returned RefMut exits scope. The value cannot be borrowed while this borrow is active.

By passing a &NoGC we statically prevent GC from being run while the borrow is active, to prevent panic when tracing (which calls borrow).

Returns None if the value is currently borrowed.

impl<T> DomRefCell<T>

pub fn new(value: T) -> DomRefCell<T>

Create a new DomRefCell containing value.

pub fn borrow(&self) -> Ref<'_, T>

Immutably borrows the wrapped value.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

Panics

Panics if the value is currently mutably borrowed. Panics if this is called from anywhere other than the script thread. Use borrow_for_layout if the borrowed data might used during layout.

pub fn borrow_mut(&self) -> RefMut<'_, T>

Mutably borrows the wrapped value.

The borrow lasts until the returned RefMut exits scope. The value cannot be borrowed while this borrow is active.

Panics

Panics if the value is currently borrowed. Panics if this is called from anywhere other than the script thread.

pub fn try_borrow(&self) -> Result<Ref<'_, T>, BorrowError>

Attempts to immutably borrow the wrapped value.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

Returns None if the value is currently mutably borrowed.

Panics

Panics if this is called off the script thread.

pub fn try_borrow_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError>

Mutably borrows the wrapped value.

The borrow lasts until the returned RefMut exits scope. The value cannot be borrowed while this borrow is active.

Returns None if the value is currently borrowed.

Panics

Panics if this is called off the script thread.

impl<T: Default> DomRefCell<T>

pub fn take(&self) -> T

Takes the wrapped value, leaving Default::default() in its place.

Panics

Panics if the value is currently borrowed.

Trait Implementations

impl<T: Clone> Clone for DomRefCell<T>

fn clone(&self) -> DomRefCell<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: CustomTraceable> CustomTraceable for DomRefCell<T>

unsafe fn trace(&self, trc: *mut JSTracer)

Trace self.

impl<T: Debug> Debug for DomRefCell<T>

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

Formats the value using the given formatter.

impl<T: Default> Default for DomRefCell<T>

fn default() -> DomRefCell<T>

Returns the “default value” for a type.

impl<T: MallocConditionalSizeOf> MallocConditionalSizeOf for DomRefCell<T>

fn conditional_size_of(&self, ops: &mut MallocSizeOfOps) -> usize

Measure the heap usage of all heap-allocated descendant structures, but not the space taken up by the value itself, and only if that heap usage hasn’t already been measured.

impl<T> MallocSizeOf for DomRefCell<T>

where T: MallocSizeOf,

fn size_of(&self, ops: &mut MallocSizeOfOps) -> usize

Measure the heap usage of all descendant heap-allocated structures, but not the space taken up by the value itself.

impl<K, V> Maplike for DomRefCell<IndexMap<K, V>>

where K: ToJSValConvertible + Eq + PartialEq + Hash + Clone, V: ToJSValConvertible + Clone,

type Key = K

The type of the key of the map.

type Value = V

The type of the value of the map.

fn get_index( &self, _cx: &mut JSContext, index: u32, ) -> Option<(Self::Key, Self::Value)>

fn get(&self, _cx: &mut JSContext, key: Self::Key) -> Option<Self::Value>

fn size(&self, _cx: &mut JSContext) -> u32

fn set(&self, _cx: &mut JSContext, key: Self::Key, value: Self::Value)

fn has(&self, _cx: &mut JSContext, key: Self::Key) -> bool

fn clear(&self, _cx: &mut JSContext)

fn delete(&self, _cx: &mut JSContext, key: Self::Key) -> bool

impl<T: PartialEq> PartialEq for DomRefCell<T>

fn eq(&self, other: &DomRefCell<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<K> Setlike for DomRefCell<IndexSet<K>>

where K: ToJSValConvertible + Eq + PartialEq + Hash + Clone,

type Key = K

The type of the key of the set.

fn get_index(&self, _cx: &mut JSContext, index: u32) -> Option<Self::Key>

fn size(&self, _cx: &mut JSContext) -> u32

fn add(&self, _cx: &mut JSContext, key: Self::Key)

fn has(&self, _cx: &mut JSContext, key: Self::Key) -> bool

fn clear(&self, _cx: &mut JSContext)

fn delete(&self, _cx: &mut JSContext, key: Self::Key) -> bool

impl<T: Traceable> Traceable for DomRefCell<T>

unsafe fn trace(&self, trc: *mut JSTracer)

Trace self.

impl<T> StructuralPartialEq for DomRefCell<T>