mirror of
https://github.com/servo/servo.git
synced 2025-08-03 04:30:10 +01:00
Improve the documentation in js.rs.
This commit is contained in:
parent
1d3cd4c34d
commit
84425bf4d7
1 changed files with 31 additions and 31 deletions
|
@ -4,19 +4,19 @@
|
|||
|
||||
//! Smart pointers for the JS-managed DOM objects.
|
||||
//!
|
||||
//! The DOM is made up of Rust types whose lifetime is entirely controlled by
|
||||
//! The DOM is made up of DOM objects whose lifetime is entirely controlled by
|
||||
//! the whims of the SpiderMonkey garbage collector. The types in this module
|
||||
//! are designed to ensure that any interactions with said Rust types only
|
||||
//! occur on values that will remain alive the entire time.
|
||||
//!
|
||||
//! Here is a brief overview of the important types:
|
||||
//!
|
||||
//! - `JSRef<T>`: a freely-copyable reference to a rooted value.
|
||||
//! - `Root<T>`: a stack-based reference to a rooted value.
|
||||
//! - `JS<T>`: a pointer to JS-owned memory that can automatically be traced by
|
||||
//! - `JSRef<T>`: a freely-copyable reference to a rooted DOM object.
|
||||
//! - `Root<T>`: a stack-based reference to a rooted DOM object.
|
||||
//! - `JS<T>`: a reference to a DOM object that can automatically be traced by
|
||||
//! the GC when encountered as a field of a Rust structure.
|
||||
//! - `Temporary<T>`: a value that will remain rooted for the duration of its
|
||||
//! lifetime.
|
||||
//! - `Temporary<T>`: a reference to a DOM object that will remain rooted for
|
||||
//! the duration of its lifetime.
|
||||
//!
|
||||
//! The rule of thumb is as follows:
|
||||
//!
|
||||
|
@ -24,9 +24,9 @@
|
|||
//! until it is stored somewhere that is reachable by the GC.
|
||||
//! - All functions take `JSRef<T>` arguments, to ensure that they will remain
|
||||
//! uncollected for the duration of their usage.
|
||||
//! - All types contain `JS<T>` fields and derive the `Encodable` trait, to
|
||||
//! ensure that they are transitively marked as reachable by the GC if the
|
||||
//! enclosing value is reachable.
|
||||
//! - All DOM structs contain `JS<T>` fields and derive the `JSTraceable`
|
||||
//! trait, to ensure that they are transitively marked as reachable by the GC
|
||||
//! if the enclosing value is reachable.
|
||||
//! - All methods for type `T` are implemented for `JSRef<T>`, to ensure that
|
||||
//! the self value will not be collected for the duration of the method call.
|
||||
//!
|
||||
|
@ -34,12 +34,10 @@
|
|||
//! without explicitly creating a stack-based root via the `root` method. This
|
||||
//! returns a `Root<T>`, which causes the JS-owned value to be uncollectable
|
||||
//! for the duration of the `Root` object's lifetime. A `JSRef<T>` can be
|
||||
//! obtained from a `Root<T>` by calling the `r` method. (Dereferencing the
|
||||
//! object is still supported, but as it is unsafe, this is deprecated.) These
|
||||
//! `JSRef<T>` values are not allowed to outlive their originating `Root<T>`,
|
||||
//! to ensure that all interactions with the enclosed value only occur when
|
||||
//! said value is uncollectable, and will cause static lifetime errors if
|
||||
//! misused.
|
||||
//! obtained from a `Root<T>` by calling the `r` method. These `JSRef<T>`
|
||||
//! values are not allowed to outlive their originating `Root<T>`, to ensure
|
||||
//! that all interactions with the enclosed value only occur when said value is
|
||||
//! uncollectable, and will cause static lifetime errors if misused.
|
||||
//!
|
||||
//! Other miscellaneous helper traits:
|
||||
//!
|
||||
|
@ -69,6 +67,8 @@ use std::mem;
|
|||
use std::ops::Deref;
|
||||
|
||||
/// An unrooted, JS-owned value. Must not be held across a GC.
|
||||
///
|
||||
/// This is used in particular to wrap pointers extracted from a reflector.
|
||||
#[must_root]
|
||||
pub struct Unrooted<T> {
|
||||
ptr: NonZero<*const T>
|
||||
|
@ -180,8 +180,8 @@ impl<T: Reflectable> Temporary<T> {
|
|||
}
|
||||
}
|
||||
|
||||
/// A rooted, JS-owned value. Must only be used as a field in other JS-owned
|
||||
/// types.
|
||||
/// A traced reference to a DOM object. Must only be used as a field in other
|
||||
/// DOM objects.
|
||||
#[must_root]
|
||||
pub struct JS<T> {
|
||||
ptr: NonZero<*const T>
|
||||
|
@ -196,8 +196,8 @@ impl<T> JS<T> {
|
|||
}
|
||||
}
|
||||
|
||||
/// This is specialized `JS<T>` to use in under `layout` crate.
|
||||
/// `Layout*Helpers` traits must be implemented on this.
|
||||
/// An unrooted reference to a DOM object for use in layout. `Layout*Helpers`
|
||||
/// traits must be implemented on this.
|
||||
pub struct LayoutJS<T> {
|
||||
ptr: NonZero<*const T>
|
||||
}
|
||||
|
@ -425,10 +425,9 @@ impl<T: Reflectable> JS<T> {
|
|||
}
|
||||
|
||||
impl<T: Reflectable> LayoutJS<T> {
|
||||
/// Returns an unsafe pointer to the interior of this JS object without
|
||||
/// touching the borrow flags. This is the only method that be safely
|
||||
/// accessed from layout. (The fact that this is unsafe is what
|
||||
/// necessitates the layout wrappers.)
|
||||
/// Returns an unsafe pointer to the interior of this JS object. This is
|
||||
/// the only method that be safely accessed from layout. (The fact that
|
||||
/// this is unsafe is what necessitates the layout wrappers.)
|
||||
pub unsafe fn unsafe_get(&self) -> *const T {
|
||||
*self.ptr
|
||||
}
|
||||
|
@ -642,12 +641,13 @@ impl RootCollection {
|
|||
}
|
||||
}
|
||||
|
||||
/// A rooted JS value. The JS value is pinned for the duration of this object's
|
||||
/// lifetime; roots are additive, so this object's destruction will not
|
||||
/// invalidate other roots for the same JS value. `Root`s cannot outlive the
|
||||
/// associated `RootCollection` object. Attempts to transfer ownership of a
|
||||
/// `Root` via moving will trigger dynamic unrooting failures due to incorrect
|
||||
/// ordering.
|
||||
/// A rooted reference to a DOM object.
|
||||
///
|
||||
/// The JS value is pinned for the duration of this object's lifetime; roots
|
||||
/// are additive, so this object's destruction will not invalidate other roots
|
||||
/// for the same JS value. `Root`s cannot outlive the associated
|
||||
/// `RootCollection` object. Attempts to transfer ownership of a `Root` via
|
||||
/// moving will trigger dynamic unrooting failures due to incorrect ordering.
|
||||
pub struct Root<T> {
|
||||
/// List that ensures correct dynamic root ordering
|
||||
root_list: &'static RootCollection,
|
||||
|
@ -709,8 +709,8 @@ impl<'a, T: Reflectable> Deref for JSRef<'a, T> {
|
|||
}
|
||||
}
|
||||
|
||||
/// Encapsulates a reference to something that is guaranteed to be alive. This
|
||||
/// is freely copyable.
|
||||
/// A reference to a DOM object that is guaranteed to be alive. This is freely
|
||||
/// copyable.
|
||||
pub struct JSRef<'a, T> {
|
||||
ptr: NonZero<*const T>,
|
||||
chain: ContravariantLifetime<'a>,
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue