Mirrors/servo
1
0
Fork 0
mirror of https://github.com/servo/servo.git synced 2025-08-04 13:10:20 +01:00
Code Issues Projects Releases Packages Wiki Activity

Fix documentation for JS<T> and friends.

Browse source
This commit is contained in:
Eli Friedman 2015-10-14 18:53:18 -07:00
parent 5bdf6bb1d3
commit 5713867778
1 changed files with 18 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

31
components/script/dom/bindings/js.rs
View file

@ -38,8 +38,13 @@ use std::ops::Deref;
use std::ptr; use std::ptr;
use util::mem::HeapSizeOf; use util::mem::HeapSizeOf;
/// A traced reference to a DOM object. Must only be used as a field in other /// A traced reference to a DOM object
/// DOM objects. ///
/// This type is critical to making garbage collection work with the DOM,
/// but it is very dangerous; if garbage collection happens with a `JS<T>`
/// on the stack, the `JS<T>` can point to freed memory.
///
/// This should only be used as a field in other DOM objects.
#[must_root] #[must_root]
pub struct JS<T> { pub struct JS<T> {
ptr: NonZero<*const T> ptr: NonZero<*const T>
@ -61,6 +66,7 @@ impl<T> JS<T> {
} }
} }
} }
impl<T: Reflectable> JS<T> { impl<T: Reflectable> JS<T> {
/// Root this JS-owned value to prevent its collection as garbage. /// Root this JS-owned value to prevent its collection as garbage.
pub fn root(&self) -> Root<T> { pub fn root(&self) -> Root<T> {
@ -204,7 +210,10 @@ impl MutHeapJSVal {
/// A holder that provides interior mutability for GC-managed values such as /// A holder that provides interior mutability for GC-managed values such as
/// `JS<T>`. /// `JS<T>`. Essentially a `Cell<JS<T>>`, but safer.
///
/// This should only be used as a field in other DOM objects; see warning
/// on `JS<T>`.
#[must_root] #[must_root]
#[derive(JSTraceable)] #[derive(JSTraceable)]
pub struct MutHeap<T: HeapGCValue> { pub struct MutHeap<T: HeapGCValue> {
@ -241,10 +250,12 @@ impl<T: HeapGCValue> HeapSizeOf for MutHeap<T> {
} }
} }
/// A mutable holder for GC-managed values such as `JSval` and `JS<T>`, with /// A holder that provides interior mutability for GC-managed values such as
/// nullability represented by an enclosing Option wrapper. Roughly equivalent /// `JS<T>`, with nullability represented by an enclosing Option wrapper.
/// to a DOMRefCell<Option<JS<T>>>, but smaller; the cost is that values which /// Essentially a `Cell<Option<JS<T>>>`, but safer.
/// are read must be immediately rooted. ///
/// This should only be used as a field in other DOM objects; see warning
/// on `JS<T>`.
#[must_root] #[must_root]
#[derive(JSTraceable)] #[derive(JSTraceable)]
pub struct MutNullableHeap<T: HeapGCValue> { pub struct MutNullableHeap<T: HeapGCValue> {
@ -452,12 +463,6 @@ impl<T: Reflectable> Root<T> {
pub fn r(&self) -> &T { pub fn r(&self) -> &T {
&**self &**self
} }
/// Generate a new root from a JS<T> reference
#[allow(unrooted_must_root)]
pub fn from_rooted(js: JS<T>) -> Root<T> {
js.root()
}
} }
impl<T: Reflectable> Deref for Root<T> { impl<T: Reflectable> Deref for Root<T> {